refactor(content-explorer): refactor pagination footer (#4007)

* refactor(content-explorer): refactor pagination footer

* refactor(content-explorer): update prop and style

* refactor(content-explorer): add withPagination section

* refactor(content-explorer): update test description

Author: tjiang-box

i18n/en-US.properties

@@ -592,10 +592,16 @@ be.noActivityCommentPrompt = Comment and @mention people to notify them.
 be.open = Open
 # Next page button tooltip
 be.pagination.nextPage = Next Page
+# Next page button
+be.pagination.nextPageButton = Next
+# Pagination menu status with the range of entries shown
+be.pagination.pageEntryStatus = Showing {startEntryIndex} to {endEntryIndex} of {totalCount} entries
 # Pagination menu button with current page number out of total number of pages
 be.pagination.pageStatus = {pageNumber} of {pageCount}
 # Previous page button tooltip
 be.pagination.previousPage = Previous Page
+# Previous page button
+be.pagination.previousPageButton = Previous
 # Icon title for a Box item of type folder that is private and has no collaborators
 be.personalFolder = Personal Folder
 # Message to the user to enter into point annotation mode

src/elements/common/messages.js

@@ -916,11 +916,21 @@ const messages = defineMessages({
         description: 'Next page button tooltip',
         id: 'be.pagination.nextPage',
     },
+    nextPageButton: {
+        defaultMessage: 'Next',
+        description: 'Next page button',
+        id: 'be.pagination.nextPageButton',
+    },
     pageStatus: {
         defaultMessage: '{pageNumber} of {pageCount}',
         description: 'Pagination menu button with current page number out of total number of pages',
         id: 'be.pagination.pageStatus',
     },
+    pageEntryStatus: {
+        defaultMessage: 'Showing {startEntryIndex} to {endEntryIndex} of {totalCount} entries',
+        description: 'Pagination menu status with the range of entries shown',
+        id: 'be.pagination.pageEntryStatus',
+    },
     previousFile: {
         defaultMessage: 'Previous File',
         description: 'Previous file button title',
@@ -931,6 +941,11 @@ const messages = defineMessages({
         description: 'Previous page button tooltip',
         id: 'be.pagination.previousPage',
     },
+    previousPageButton: {
+        defaultMessage: 'Previous',
+        description: 'Previous page button',
+        id: 'be.pagination.previousPageButton',
+    },
     previousSegment: {
         id: 'be.previousSegment',
         description: 'Title for previous segment on skill timeline',

src/elements/common/pagination/MarkerBasedPagination.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import noop from 'lodash/noop';
+import PaginationControls from './PaginationControls';
+
+export interface MarkerBasedPaginationProps {
+    hasNextMarker?: boolean;
+    hasPrevMarker?: boolean;
+    isSmall: boolean;
+    onMarkerBasedPageChange?: (offset: number) => void;
+}
+
+const MarkerBasedPagination = ({
+    hasNextMarker = false,
+    hasPrevMarker = false,
+    isSmall,
+    onMarkerBasedPageChange = noop,
+}: MarkerBasedPaginationProps) => {
+    if (!hasNextMarker && !hasPrevMarker) {
+        return null;
+    }
+    const handleNextClick = () => {
+        onMarkerBasedPageChange(1);
+    };
+
+    const handlePreviousClick = () => {
+        onMarkerBasedPageChange(-1);
+    };
+
+    return (
+        <PaginationControls
+            handleNextClick={handleNextClick}
+            handlePreviousClick={handlePreviousClick}
+            hasNextPage={hasNextMarker}
+            hasPageEntryStatus={false}
+            hasPreviousPage={hasPrevMarker}
+            isSmall={isSmall}
+        />
+    );
+};
+
+export default MarkerBasedPagination;

src/elements/common/pagination/OffsetBasedPagination.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import noop from 'lodash/noop';
+import PaginationControls from './PaginationControls';
+import { DEFAULT_PAGE_SIZE } from '../../../constants';
+
+export interface OffsetBasedPaginationProps {
+    isSmall: boolean;
+    offset?: number;
+    onOffsetChange?: (offset: number) => void;
+    pageSize?: number;
+    totalCount?: number;
+}
+
+const OffsetBasedPagination = ({
+    isSmall,
+    offset = 0,
+    onOffsetChange = noop,
+    pageSize = DEFAULT_PAGE_SIZE,
+    totalCount = 0,
+}: OffsetBasedPaginationProps) => {
+    const pageCount = Math.ceil(totalCount / pageSize);
+    if (pageCount <= 1) return null;
+
+    const pageByOffset = Math.floor(offset / pageSize) + 1;
+    const pageNumber = pageByOffset > 0 ? Math.min(pageCount, pageByOffset) : 1;
+    const hasNextPage = pageNumber < pageCount;
+    const hasPreviousPage = pageNumber > 1;
+
+    const updateOffset = (newPageNumber: number) => {
+        let newOffset = (newPageNumber - 1) * pageSize;
+
+        if (newOffset <= 0) {
+            newOffset = 0;
+        }
+
+        if (newOffset >= totalCount) {
+            newOffset = totalCount - pageSize;
+        }
+
+        onOffsetChange(newOffset);
+    };
+
+    const handleNextClick = () => {
+        updateOffset(pageNumber + 1);
+    };
+
+    const handlePreviousClick = () => {
+        updateOffset(pageNumber - 1);
+    };
+
+    return (
+        <PaginationControls
+            handleNextClick={handleNextClick}
+            handlePreviousClick={handlePreviousClick}
+            hasNextPage={hasNextPage}
+            hasPageEntryStatus={true}
+            hasPreviousPage={hasPreviousPage}
+            isSmall={isSmall}
+            offset={offset}
+            pageSize={pageSize}
+            totalCount={totalCount}
+        />
+    );
+};
+
+export default OffsetBasedPagination;

src/elements/common/pagination/Pagination.scss

@@ -0,0 +1,16 @@
+@import '../../../styles/variables';
+
+.bdl-Pagination {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+
+    .bdl-Pagination-buttons {
+        display: flex;
+        gap: var(--space-2);
+
+        .bdl-Pagination-iconButton {
+            border: 1px solid var(--border-cta-border-secondary);
+        }
+    }
+}

src/elements/common/pagination/Pagination.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import MarkerBasedPagination from './MarkerBasedPagination';
+import OffsetBasedPagination from './OffsetBasedPagination';
+import './Pagination.scss';
+
+export interface PaginationProps {
+    hasNextMarker?: boolean;
+    hasPrevMarker?: boolean;
+    isSmall: boolean;
+    offset?: number;
+    onMarkerBasedPageChange?: (offset: number) => void;
+    onOffsetChange?: (offset: number) => void;
+    pageSize?: number;
+    totalCount?: number;
+}
+
+const Pagination = ({ hasNextMarker, hasPrevMarker, isSmall, onMarkerBasedPageChange, ...rest }: PaginationProps) => {
+    if (hasNextMarker || hasPrevMarker) {
+        return (
+            <MarkerBasedPagination
+                hasNextMarker={hasNextMarker}
+                hasPrevMarker={hasPrevMarker}
+                isSmall={isSmall}
+                onMarkerBasedPageChange={onMarkerBasedPageChange}
+            />
+        );
+    }
+
+    return <OffsetBasedPagination isSmall={isSmall} {...rest} />;
+};
+
+export default Pagination;

src/elements/common/pagination/PaginationControls.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react';
+import { FormattedMessage, useIntl } from 'react-intl';
+import { Button, IconButton, Tooltip } from '@box/blueprint-web';
+import { PointerChevronLeft, PointerChevronRight } from '@box/blueprint-web-assets/icons/Fill';
+
+import messages from '../messages';
+
+import './Pagination.scss';
+
+export interface PaginationControlsProps {
+    handleNextClick: () => void;
+    handlePreviousClick: () => void;
+    hasNextPage: boolean;
+    hasPageEntryStatus?: boolean;
+    hasPreviousPage: boolean;
+    isSmall: boolean;
+    offset?: number;
+    pageSize?: number;
+    totalCount?: number;
+}
+
+const PaginationControls = ({
+    handleNextClick,
+    handlePreviousClick,
+    hasNextPage,
+    hasPageEntryStatus = true,
+    hasPreviousPage,
+    isSmall,
+    offset = 0,
+    pageSize = 0,
+    totalCount = 0,
+}: PaginationControlsProps) => {
+    const { formatMessage } = useIntl();
+    const startEntryIndex = offset + 1;
+    const endEntryIndex = Math.min(offset + pageSize, totalCount);
+
+    return (
+        <div className="bdl-Pagination">
+            {hasPageEntryStatus && (
+                <FormattedMessage
+                    {...messages.pageEntryStatus}
+                    values={{ startEntryIndex, endEntryIndex, totalCount }}
+                />
+            )}
+            <div className="bdl-Pagination-buttons">
+                <Tooltip content={formatMessage(messages.previousPage)}>
+                    {isSmall ? (
+                        <IconButton
+                            aria-label={formatMessage(messages.previousPageButton)}
+                            className="bdl-Pagination-iconButton"
+                            disabled={!hasPreviousPage}
+                            icon={PointerChevronLeft}
+                            onClick={handlePreviousClick}
+                            size="large"
+                        />
+                    ) : (
+                        <Button disabled={!hasPreviousPage} onClick={handlePreviousClick} variant="secondary">
+                            {formatMessage(messages.previousPageButton)}
+                        </Button>
+                    )}
+                </Tooltip>
+                <Tooltip content={formatMessage(messages.nextPage)}>
+                    {isSmall ? (
+                        <IconButton
+                            aria-label={formatMessage(messages.nextPageButton)}
+                            className="bdl-Pagination-iconButton"
+                            disabled={!hasNextPage}
+                            icon={PointerChevronRight}
+                            onClick={handleNextClick}
+                            size="large"
+                        />
+                    ) : (
+                        <Button disabled={!hasNextPage} onClick={handleNextClick} variant="secondary">
+                            {formatMessage(messages.nextPageButton)}
+                        </Button>
+                    )}
+                </Tooltip>
+            </div>
+        </div>
+    );
+};
+
+export default PaginationControls;

src/elements/common/pagination/__tests__/MarkerBasedPagination.test.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '../../../../test-utils/testing-library';
+import MarkerBasedPagination, { MarkerBasedPaginationProps } from '../MarkerBasedPagination';
+
+describe('elements/common/pagination/MarkerBasedPagination', () => {
+    const renderComponent = (props: Partial<MarkerBasedPaginationProps> = {}) =>
+        render(<MarkerBasedPagination isSmall={false} {...props} />);
+
+    test('should not render pagination controls when both markers are set to false by default', () => {
+        renderComponent();
+
+        expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    });
+
+    test('should call onMarkerBasedPageChange with correct offset when clicking next', async () => {
+        const onMarkerBasedPageChange = jest.fn();
+        renderComponent({
+            hasNextMarker: true,
+            onMarkerBasedPageChange,
+        });
+
+        await userEvent.click(screen.getByRole('button', { name: 'Next' }));
+        expect(onMarkerBasedPageChange).toHaveBeenCalledWith(1);
+    });
+
+    test('should call onMarkerBasedPageChange with correct offset when clicking previous', async () => {
+        const onMarkerBasedPageChange = jest.fn();
+        renderComponent({
+            hasPrevMarker: true,
+            onMarkerBasedPageChange,
+        });
+
+        await userEvent.click(screen.getByRole('button', { name: 'Previous' }));
+        expect(onMarkerBasedPageChange).toHaveBeenCalledWith(-1);
+    });
+});