@hyphen/hyphen-components 2.9.0

package/src/components/Pagination/Pagination.stories.tsx

@@ -0,0 +1,55 @@
+import { Pagination } from './Pagination';
+import type { Meta } from '@storybook/react';
+import React from 'react';
+import { useState } from 'react';
+
+const meta: Meta<typeof Pagination> = {
+  title: 'Components/Pagination',
+  component: Pagination,
+};
+
+export default meta;
+
+export const Default = () => {
+  const [activePage, setActivePage] = useState(1);
+
+  return (
+    <>
+      <Pagination
+        activePage={activePage}
+        itemsPerPage={20}
+        onChange={setActivePage}
+        totalItemsCount={87}
+        numberOfPagesDisplayed={0}
+      />
+    </>
+  );
+};
+
+export const Compact = () => {
+  const [activePage, setActivePage] = useState(1);
+  return (
+    <Pagination
+      activePage={activePage}
+      itemsPerPage={20}
+      onChange={setActivePage}
+      totalItemsCount={100}
+      isCompact
+    />
+  );
+};
+
+export const PageNumbers = () => {
+  const [activePage, setActivePage] = useState(1);
+  return (
+    <Pagination
+      activePage={activePage}
+      itemsPerPage={20}
+      onChange={setActivePage}
+      totalItemsCount={100}
+      isCompact
+      arePagesVisible
+      numberOfPagesDisplayed={3}
+    />
+  );
+};

package/src/components/Pagination/Pagination.test.tsx

@@ -0,0 +1,225 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Pagination } from './Pagination';
+
+describe('Pagination', () => {
+  describe('Default', () => {
+    test('It renders a component with a nav tag based on props', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+        />
+      );
+
+      const pagination = screen.getByRole('navigation');
+      expect(pagination).toBeInTheDocument();
+    });
+  });
+
+  describe('Custom Class', () => {
+    test('It renders with a custom class if provided', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          className="custom-class"
+        />
+      );
+
+      const pagination = screen.getByRole('navigation');
+      expect(pagination).toHaveClass('custom-class');
+    });
+  });
+
+  describe('Custom button labels', () => {
+    test('It renders with a custom class if provided', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          className="custom-class"
+          prevPageText="hello"
+          nextPageText="goodbye"
+        />
+      );
+
+      const prevButton = screen.getByText('hello');
+      const nextButton = screen.getByText('goodbye');
+      expect(prevButton).toBeInTheDocument();
+      expect(nextButton).toBeInTheDocument();
+    });
+  });
+
+  describe('With Page numbers', () => {
+    test('It renders width default page numbers for 5 pages or records', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          className="custom-class"
+          arePagesVisible
+        />
+      );
+      const expectedPages = ['1', '2', '3', '4', '5'];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const pages: any[] = [];
+
+      expectedPages.forEach((_page, i) => {
+        pages.push(screen.getByText(expectedPages[i]));
+      });
+
+      expectedPages.forEach((_page, i) => {
+        expect(pages[i]).toBeInTheDocument();
+      });
+    });
+
+    test('It does not show excess page numbers if prop passed overshoots the number of records', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={5}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          numberOfPagesDisplayed={4}
+        />
+      );
+      const expectedPageNumbers = ['1'];
+      const excludedPageNumbers = ['2', '3', '4'];
+
+      expectedPageNumbers.forEach((_page, i) => {
+        expect(screen.getByText(expectedPageNumbers[i])).toBeInTheDocument();
+      });
+
+      excludedPageNumbers.forEach((_page, i) => {
+        expect(screen.queryByText(excludedPageNumbers[i])).toBe(null);
+      });
+    });
+
+    test('It shows the correct range of active entries when not on last page', () => {
+      render(
+        <Pagination
+          activePage={2}
+          totalItemsCount={1200}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          numberOfPagesDisplayed={4}
+        />
+      );
+
+      const range = screen.getByText('Showing 21-40 of 1200');
+      expect(range).toBeInTheDocument();
+    });
+
+    test('It shows the correct range of active entries when last page is active', () => {
+      render(
+        <Pagination
+          activePage={12}
+          totalItemsCount={1151}
+          itemsPerPage={100}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          numberOfPagesDisplayed={4}
+        />
+      );
+
+      const range = screen.getByText('Showing 1101-1151 of 1151');
+      expect(range).toBeInTheDocument();
+    });
+
+    test('It shows ellipsis buttons where appropriate', () => {
+      const { rerender } = render(
+        <Pagination
+          activePage={12}
+          totalItemsCount={1151}
+          itemsPerPage={100}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          numberOfPagesDisplayed={4}
+        />
+      );
+
+      let ellipsisFound: HTMLElement[] = [];
+
+      ellipsisFound = screen.queryAllByText('...');
+      expect(ellipsisFound.length).toBe(1);
+
+      rerender(
+        <Pagination
+          activePage={6}
+          totalItemsCount={1151}
+          itemsPerPage={100}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          numberOfPagesDisplayed={4}
+        />
+      );
+
+      ellipsisFound = screen.queryAllByText('...');
+      expect(ellipsisFound.length).toBe(2);
+
+      const buttonsFound = screen.queryAllByRole('button');
+      expect(buttonsFound[2]).toHaveTextContent('...');
+      expect(buttonsFound[buttonsFound.length - 3]).toHaveTextContent('...');
+    });
+  });
+
+  describe('Compact', () => {
+    test('Renders compact pagination if prop is passed', () => {
+      render(
+        <Pagination
+          activePage={1}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={() => 'blerg'}
+          arePagesVisible
+          isCompact
+        />
+      );
+
+      const buttons = screen.queryAllByRole('button');
+
+      buttons.forEach((button) => {
+        expect(button).toHaveClass('size-sm');
+      });
+    });
+  });
+
+  describe('Callback Handling', () => {
+    test('It fires onChange callback when previous/next buttons are clicked', () => {
+      const mockedHandleChange = jest.fn();
+
+      render(
+        <Pagination
+          activePage={2}
+          totalItemsCount={100}
+          itemsPerPage={20}
+          onChange={mockedHandleChange}
+          arePagesVisible
+        />
+      );
+
+      const prevButton = screen.getByText('Previous').closest('button');
+      const nextButton = screen.getByText('Next').closest('button');
+      const pageFour = screen.getByText('4').closest('button');
+      if (prevButton) fireEvent.click(prevButton);
+      if (nextButton) fireEvent.click(nextButton);
+      if (pageFour) fireEvent.click(pageFour);
+
+      expect(mockedHandleChange).toBeCalledTimes(3);
+      expect(mockedHandleChange.mock.calls[0][0]).toBe(1);
+      expect(mockedHandleChange.mock.calls[1][0]).toBe(3);
+      expect(mockedHandleChange.mock.calls[2][0]).toBe(4);
+    });
+  });
+});

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,162 @@
+import React, { FC, ReactNode, useMemo } from 'react';
+import classNames from 'classnames';
+import { Box } from '../Box/Box';
+import { Button } from '../Button/Button';
+import {
+  generatePages,
+  generatePageRange,
+  generatePageTotal,
+  generateActiveListRange,
+} from './Pagination.utilities';
+
+export interface PaginationProps {
+  /**
+   * The current page number being displayed.
+   */
+  activePage: number;
+  /**
+   * The number of list items contained in a page.
+   */
+  itemsPerPage: number;
+  /**
+   * Callback fired when the user clicks a page or prev/next button.
+   */
+  onChange: (pageNumber: number) => void;
+  /**
+   * The total number of items in the list
+   */
+  totalItemsCount: number;
+  /**
+   * Boolean to determine if individual page buttons (or dropdown are visible). Takes a `ResponsiveProp`
+   * if you want to render it differently at different breakpoints
+   */
+  arePagesVisible?: boolean;
+  /**
+   * Custom class to pass down to the pagination container.
+   */
+  className?: string;
+  /**
+   * Pass true to render a version of Pagination with smaller buttons.
+   */
+  isCompact?: boolean;
+  /**
+   * Boolean to determine if the list totals (and current range) are visible.
+   * NOTE: these are hidden on mobile regardless of this prop value.
+   */
+  isTotalVisible?: boolean;
+  /**
+   * The text (or react node) to pass to the NEXT page button.
+   */
+  nextPageText?: string | ReactNode;
+  /**
+   * Number of pages shown in paginator, not including navigation blocks (prev, next), as well as first, last pages.
+   * In other words the number of pages displayed 'in the middle', that the user can navigate to.
+   */
+  numberOfPagesDisplayed?: number;
+  /**
+   * The text (or react node) to pass to the PREVIOUS page button.
+   */
+  prevPageText?: string | ReactNode;
+}
+
+export const Pagination: FC<PaginationProps> = ({
+  activePage,
+  itemsPerPage,
+  onChange,
+  totalItemsCount,
+  arePagesVisible = false,
+  className = undefined,
+  isCompact = false,
+  isTotalVisible = true,
+  nextPageText = 'Next',
+  numberOfPagesDisplayed = 5,
+  prevPageText = 'Previous',
+}) => {
+  const pageTotal = useMemo(
+    () => generatePageTotal(totalItemsCount, itemsPerPage),
+    [totalItemsCount, itemsPerPage]
+  );
+
+  const pageRange = useMemo(
+    () => generatePageRange(numberOfPagesDisplayed, pageTotal),
+    [numberOfPagesDisplayed, pageTotal]
+  );
+
+  const activeListRange = useMemo(
+    () => generateActiveListRange(activePage, totalItemsCount, itemsPerPage),
+    [activePage, totalItemsCount, itemsPerPage]
+  );
+
+  const pages = useMemo(
+    () =>
+      generatePages(pageRange, pageTotal, activePage, numberOfPagesDisplayed),
+    [pageRange, pageTotal, activePage, numberOfPagesDisplayed]
+  );
+
+  return (
+    <Box
+      as="nav"
+      direction="row"
+      alignItems="center"
+      justifyContent="space-between"
+      padding="lg"
+      className={classNames(className)}
+    >
+      <Box
+        direction="row"
+        justifyContent={{ base: 'space-between' }}
+        flex={{ base: 'auto', tablet: 'none' }}
+        gap={isCompact ? 'xs' : 'sm'}
+      >
+        <Button
+          variant="primary"
+          size={isCompact ? 'sm' : 'md'}
+          isDisabled={activePage === 1}
+          onClick={() => onChange(activePage - 1)}
+        >
+          {prevPageText}
+        </Button>
+        {arePagesVisible && (
+          <Box direction="row" gap="2xs">
+            {pages.map(({ pageNumber, isPage }) => {
+              console.log(activePage, pageNumber, isPage);
+              return (
+                <Button
+                  key={pageNumber}
+                  onClick={() => onChange(pageNumber)}
+                  variant={pageNumber === activePage ? 'secondary' : 'tertiary'}
+                  size={isCompact ? 'sm' : 'md'}
+                  style={{
+                    minWidth: isCompact ? '33px' : '42px',
+                  }}
+                  className={className}
+                >
+                  {isPage ? pageNumber : '...'}
+                </Button>
+              );
+            })}
+          </Box>
+        )}
+        <Button
+          variant="primary"
+          size={isCompact ? 'sm' : 'md'}
+          isDisabled={activePage === pageTotal}
+          onClick={() => onChange(activePage + 1)}
+        >
+          {nextPageText}
+        </Button>
+      </Box>
+      <Box
+        as="p"
+        display={{
+          base: 'none',
+          tablet: 'block',
+        }}
+        fontSize={isCompact ? 'sm' : 'md'}
+      >
+        {isTotalVisible &&
+          `Showing ${activeListRange.first}-${activeListRange.last} of ${totalItemsCount}`}
+      </Box>
+    </Box>
+  );
+};

package/src/components/Pagination/Pagination.utilities.test.ts

@@ -0,0 +1,133 @@
+import {
+  generatePages,
+  generatePageRange,
+  generatePageTotal,
+  generateActiveListRange,
+} from './Pagination.utilities';
+
+describe('generatePageRange', () => {
+  it('returns the number of pages displayed if there are enough total pages', () => {
+    const pageRange = generatePageRange(3, 50);
+    expect(pageRange).toBe(3);
+  });
+
+  it('returns the page total if it is smaller than the number of pages displayed', () => {
+    const pageRange = generatePageRange(3, 2);
+    expect(pageRange).toBe(2);
+  });
+
+  it('returns the number of pages displayed if it is the same as total pages', () => {
+    const pageRange = generatePageRange(3, 3);
+    expect(pageRange).toBe(3);
+  });
+});
+
+describe('generatePageTotal', () => {
+  it('returns correct number of pages for a variety of inputs', () => {
+    const pageTotal1 = generatePageTotal(948, 20);
+    expect(pageTotal1).toBe(48);
+
+    const pageTotal2 = generatePageTotal(20, 20);
+    expect(pageTotal2).toBe(1);
+
+    const pageTotal3 = generatePageTotal(15, 20);
+    expect(pageTotal3).toBe(1);
+  });
+});
+
+describe('generateActiveListRange', () => {
+  it('returns correct active range for a variety of inputs', () => {
+    const activeRange = generateActiveListRange(3, 100, 20);
+
+    expect(activeRange.first).toBe(41);
+    expect(activeRange.last).toBe(60);
+
+    const activeRange2 = generateActiveListRange(1, 10000, 300);
+
+    expect(activeRange2.first).toBe(1);
+    expect(activeRange2.last).toBe(300);
+  });
+});
+
+describe('generatePages', () => {
+  it('returns correct pages -- scenario 1', () => {
+    const pages = generatePages(3, 10, 3, 3);
+    expect(pages.length).toBe(5);
+
+    expect(pages[0].isPage).toBe(true);
+    expect(pages[0].pageNumber).toBe(1);
+
+    expect(pages[1].isPage).toBe(true);
+    expect(pages[1].pageNumber).toBe(2);
+
+    expect(pages[2].isPage).toBe(true);
+    expect(pages[2].pageNumber).toBe(3);
+
+    expect(pages[3].isPage).toBe(false);
+    expect(pages[3].pageNumber).toBe(6);
+
+    expect(pages[4].isPage).toBe(true);
+    expect(pages[4].pageNumber).toBe(10);
+  });
+
+  it('returns correct pages -- scenario 2', () => {
+    const pages = generatePages(3, 10, 6, 3);
+    expect(pages.length).toBe(7);
+
+    expect(pages[0].isPage).toBe(true);
+    expect(pages[0].pageNumber).toBe(1);
+
+    expect(pages[1].isPage).toBe(false);
+    expect(pages[1].pageNumber).toBe(3);
+
+    expect(pages[2].isPage).toBe(true);
+    expect(pages[2].pageNumber).toBe(5);
+
+    expect(pages[3].isPage).toBe(true);
+    expect(pages[3].pageNumber).toBe(6);
+
+    expect(pages[4].isPage).toBe(true);
+    expect(pages[4].pageNumber).toBe(7);
+
+    expect(pages[5].isPage).toBe(false);
+    expect(pages[5].pageNumber).toBe(9);
+
+    expect(pages[6].isPage).toBe(true);
+    expect(pages[6].pageNumber).toBe(10);
+  });
+
+  it('returns correct pages -- scenario 3', () => {
+    const pages = generatePages(3, 10, 9, 3);
+    expect(pages.length).toBe(5);
+
+    expect(pages[0].isPage).toBe(true);
+    expect(pages[0].pageNumber).toBe(1);
+
+    expect(pages[1].isPage).toBe(false);
+    expect(pages[1].pageNumber).toBe(6);
+
+    expect(pages[2].isPage).toBe(true);
+    expect(pages[2].pageNumber).toBe(8);
+
+    expect(pages[3].isPage).toBe(true);
+    expect(pages[3].pageNumber).toBe(9);
+
+    expect(pages[4].isPage).toBe(true);
+    expect(pages[4].pageNumber).toBe(10);
+  });
+
+  it('returns the correct pages -- one less page range than total', () => {
+    const pages = generatePages(2, 3, 1, 2);
+
+    expect(pages[0].isPage).toBe(true);
+    expect(pages[0].pageNumber).toBe(1);
+
+    expect(pages[1].isPage).toBe(true);
+    expect(pages[1].pageNumber).toBe(2);
+
+    expect(pages[2].isPage).toBe(true);
+    expect(pages[2].pageNumber).toBe(3);
+
+    expect(pages.length).toBe(3);
+  });
+});

package/src/components/Pagination/Pagination.utilities.ts

@@ -0,0 +1,101 @@
+export interface Page {
+  isPage: boolean;
+  pageNumber: number;
+}
+
+export const generatePages = (
+  pageRange: number,
+  pageTotal: number,
+  activePage: number,
+  numberOfPagesDisplayed: number
+): Page[] => {
+  const pages: Page[] = [];
+  let startingPage = 1;
+  let endingPage = pageRange;
+
+  if (pageTotal <= pageRange) {
+    startingPage = 1;
+    endingPage = pageRange;
+  } else if (activePage + numberOfPagesDisplayed > pageTotal) {
+    startingPage = pageTotal - (numberOfPagesDisplayed - 1);
+    endingPage = startingPage + (numberOfPagesDisplayed - 1);
+  } else if (
+    activePage > numberOfPagesDisplayed &&
+    activePage + numberOfPagesDisplayed <= pageTotal
+  ) {
+    startingPage = activePage - Math.floor(numberOfPagesDisplayed / 2);
+    endingPage = startingPage + (numberOfPagesDisplayed - 1);
+  }
+
+  for (let i = startingPage; i <= endingPage; i += 1) {
+    pages.push({ pageNumber: i, isPage: true });
+  }
+
+  if (pageTotal > pages[pages.length - 1]?.pageNumber) {
+    const secondToLastPage =
+      pageTotal !== activePage + numberOfPagesDisplayed
+        ? activePage + numberOfPagesDisplayed
+        : pageTotal - 1;
+
+    // only add ellipsis if there are more than 0 pages between the final page and the rest of the pages
+    if (pageTotal > numberOfPagesDisplayed + 1) {
+      pages.push({ pageNumber: secondToLastPage, isPage: false });
+    }
+
+    pages.push({ pageNumber: pageTotal, isPage: true });
+  }
+
+  if (activePage > numberOfPagesDisplayed) {
+    const threeDotsPage =
+      activePage - numberOfPagesDisplayed > 1
+        ? activePage - numberOfPagesDisplayed
+        : activePage - numberOfPagesDisplayed + 1;
+
+    pages.unshift(
+      { pageNumber: 1, isPage: true },
+      { pageNumber: threeDotsPage, isPage: false }
+    );
+  }
+
+  return [...pages];
+};
+
+// Return the true page range in cases
+// where number of pages wanted for display is larger than the actual page total.
+export const generatePageRange = (
+  numberOfPagesDisplayed: number,
+  pageTotal: number
+): number =>
+  numberOfPagesDisplayed > pageTotal ? pageTotal : numberOfPagesDisplayed;
+
+export const generatePageTotal = (
+  totalItemsCount: number,
+  itemsPerPage: number
+): number => Math.ceil(totalItemsCount / itemsPerPage);
+
+// Returns the range of current items displayed based on the specific page.
+// E.G: if the items per page is 20 and we are on page 1, it will return:
+// { first: 1, last: 20 }
+export const generateActiveListRange = (
+  activePage: number,
+  totalItemsCount: number,
+  itemsPerPage: number
+): { first?: number; last?: number } => {
+  const activePageRange: { first?: number; last?: number } = {};
+
+  const pageTotal = generatePageTotal(totalItemsCount, itemsPerPage);
+
+  if (activePage === 1) {
+    activePageRange.first = 1;
+    activePageRange.last =
+      totalItemsCount > itemsPerPage ? itemsPerPage : totalItemsCount;
+  } else if (activePage < pageTotal) {
+    activePageRange.first = activePage * itemsPerPage - (itemsPerPage - 1);
+    activePageRange.last = activePage * itemsPerPage;
+  } else {
+    activePageRange.first = activePage * itemsPerPage - (itemsPerPage - 1);
+    activePageRange.last = totalItemsCount;
+  }
+
+  return activePageRange;
+};