@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,419 @@
+import * as React from "react";
+import { render, screen, within } from "@testing-library/react";
+import { axe } from "jest-axe";
+import userEvent from "@testing-library/user-event";
+import renderer from "react-test-renderer";
+
+import Pagination from "./Pagination";
+
+describe("Pagination Accessibility", () => {
+  const getPageHref = (page: number) => `page=${page}`;
+
+  it("passes axe accessibility on the first page", async () => {
+    const { container } = render(
+      <Pagination pageCount={20} currentPage={1} getPageHref={getPageHref} />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility on a middle page", async () => {
+    const { container } = render(
+      <Pagination pageCount={20} currentPage={10} getPageHref={getPageHref} />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility on the last page", async () => {
+    const { container } = render(
+      <Pagination pageCount={20} currentPage={20} getPageHref={getPageHref} />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Pagination", () => {
+  const getPageHref = (page: number) => `page=${page}`;
+
+  describe("Rendering", () => {
+    it("renders a nav element with an unordered list and links", () => {
+      render(
+        <Pagination pageCount={5} initialPage={3} getPageHref={getPageHref} />
+      );
+      const nav = screen.getByRole("navigation");
+
+      expect(nav).toBeInTheDocument();
+      expect(nav).toHaveAttribute("aria-label", "Pagination");
+      // Chakra renders other lists so we only want the list we
+      // created within the nav element.
+      const { getByRole } = within(nav);
+      expect(getByRole("list")).toBeInTheDocument();
+      // Previous/Next links + truncated item list = 7 total items
+      expect(screen.getAllByRole("listitem")).toHaveLength(7);
+      // Pagination should show:
+      // Previous 1 2 3 4 5 Next
+      expect(screen.getAllByRole("link")).toHaveLength(7);
+    });
+
+    it("does not render the Previous link on the first page", () => {
+      render(
+        <Pagination pageCount={5} initialPage={1} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // 1 2 3 4 5 Next
+      const links = screen.getAllByRole("link");
+
+      expect(links).toHaveLength(6);
+      expect(screen.queryByText("Previous")).not.toBeInTheDocument();
+      expect(screen.getByText("Next")).toBeInTheDocument();
+    });
+
+    it("does not render the Next link on the last page", () => {
+      render(
+        <Pagination pageCount={5} initialPage={5} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // Previous 1 2 3 4 5
+      const links = screen.getAllByRole("link");
+
+      expect(links).toHaveLength(6);
+      expect(screen.getByText("Previous")).toBeInTheDocument();
+      expect(screen.queryByText("Next")).not.toBeInTheDocument();
+    });
+
+    it("renders an ellipsis at the end of the list", () => {
+      render(
+        <Pagination pageCount={10} initialPage={1} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // 1 2 3 4 5 ... 10 Next
+      const listitem = screen.getAllByRole("listitem");
+
+      expect(listitem).toHaveLength(8);
+      // The ellipsis is not a link
+      expect(screen.getAllByRole("link")).toHaveLength(7);
+      expect(listitem[4].textContent).toEqual("5");
+      expect(listitem[5].textContent).toEqual("...");
+      expect(listitem[6].textContent).toEqual("10");
+      expect(screen.getByText("...")).toBeInTheDocument();
+    });
+
+    it("renders an ellipsis at the start of the list", () => {
+      render(
+        <Pagination pageCount={10} initialPage={10} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // Previous 1 ... 6 7 8 9 10
+      const listitem = screen.getAllByRole("listitem");
+
+      expect(listitem).toHaveLength(8);
+      // The ellipsis is not a link
+      expect(screen.getAllByRole("link")).toHaveLength(7);
+      expect(listitem[1].textContent).toEqual("1");
+      expect(listitem[2].textContent).toEqual("...");
+      expect(listitem[3].textContent).toEqual("6");
+      expect(screen.getByText("...")).toBeInTheDocument();
+    });
+
+    it("renders two ellipsis when the current page is in the middle", () => {
+      render(
+        <Pagination pageCount={10} initialPage={5} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // Previous 1 ... 4 5 6 ... 10 Next
+      const listitem = screen.getAllByRole("listitem");
+
+      expect(listitem).toHaveLength(9);
+      // The ellipses are not links
+      expect(screen.getAllByRole("link")).toHaveLength(7);
+      expect(listitem[0].textContent).toEqual("Previous");
+      expect(listitem[1].textContent).toEqual("1");
+      expect(listitem[2].textContent).toEqual("...");
+      expect(listitem[3].textContent).toEqual("4");
+      expect(listitem[4].textContent).toEqual("5");
+      expect(listitem[5].textContent).toEqual("6");
+      expect(listitem[6].textContent).toEqual("...");
+      expect(listitem[7].textContent).toEqual("10");
+      expect(listitem[8].textContent).toEqual("Next");
+      expect(screen.getAllByText("...")).toHaveLength(2);
+    });
+
+    it("adds aria-current to the active page", () => {
+      render(
+        <Pagination pageCount={5} initialPage={3} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // Previous 1 2 3 4 5 Next
+      const links = screen.getAllByRole("link");
+      const page2 = links[2].getAttribute("aria-current");
+      const page3 = links[3].getAttribute("aria-current");
+      const page4 = links[4].getAttribute("aria-current");
+
+      expect(page2).toEqual(null);
+      // Only the current page has `aria-current="page"` for accessibility.
+      expect(page3).toEqual("page");
+      expect(page4).toEqual(null);
+    });
+
+    it("When pagination has 1 element, pagination is not shown", () => {
+      render(
+        <Pagination pageCount={1} initialPage={1} getPageHref={getPageHref} />
+      );
+      expect(screen.queryByRole("navigation")).not.toBeInTheDocument();
+    });
+
+    it("When pagination has 0 elements, pagination is not shown", () => {
+      render(
+        <Pagination pageCount={0} initialPage={1} getPageHref={getPageHref} />
+      );
+      expect(screen.queryByRole("navigation")).not.toBeInTheDocument();
+    });
+
+    it("renders the UI snapshot correctly", () => {
+      const firstPage = renderer
+        .create(
+          <Pagination
+            id="firstPage"
+            pageCount={10}
+            initialPage={1}
+            getPageHref={getPageHref}
+          />
+        )
+        .toJSON();
+      const lastPage = renderer
+        .create(
+          <Pagination
+            id="lastPage"
+            pageCount={10}
+            initialPage={10}
+            getPageHref={getPageHref}
+          />
+        )
+        .toJSON();
+      const middlePage = renderer
+        .create(
+          <Pagination
+            id="middlePage"
+            pageCount={10}
+            initialPage={5}
+            getPageHref={getPageHref}
+          />
+        )
+        .toJSON();
+      const withChakraProps = renderer
+        .create(
+          <Pagination
+            id="chakra"
+            pageCount={10}
+            initialPage={1}
+            getPageHref={getPageHref}
+            p="20px"
+            color="ui.error.primary"
+          />
+        )
+        .toJSON();
+      const withOtherProps = renderer
+        .create(
+          <Pagination
+            id="props"
+            pageCount={10}
+            initialPage={1}
+            getPageHref={getPageHref}
+            data-testid="props"
+          />
+        )
+        .toJSON();
+
+      expect(firstPage).toMatchSnapshot();
+      expect(lastPage).toMatchSnapshot();
+      expect(middlePage).toMatchSnapshot();
+      expect(withChakraProps).toMatchSnapshot();
+      expect(withOtherProps).toMatchSnapshot();
+    });
+  });
+
+  describe("Behavior", () => {
+    it("navigates to the appropriate page when the Next or Previous links are clicked", () => {
+      const onPageChange = (page: number) => (currentPage = page);
+      let currentPage = 3;
+
+      render(
+        <Pagination
+          pageCount={5}
+          initialPage={currentPage}
+          onPageChange={onPageChange}
+        />
+      );
+
+      let links = screen.getAllByRole("link");
+
+      // Previous link
+      userEvent.click(links[0]);
+      expect(currentPage).toEqual(2);
+
+      links = screen.getAllByRole("link");
+
+      // Next link
+      userEvent.click(links[links.length - 1]);
+      expect(currentPage).toEqual(3);
+    });
+
+    it("updates the links href value when getPageHref is used", () => {
+      const getPageHref = (page: number) => `?page=${page}`;
+      render(
+        <Pagination pageCount={10} initialPage={5} getPageHref={getPageHref} />
+      );
+      // Pagination should show:
+      // Previous 1 ... 4 5 6 ... 10 Next
+      const links = screen.getAllByRole("link");
+
+      expect(screen.getByText("Previous")).toBeInTheDocument();
+      expect(screen.getByText("Next")).toBeInTheDocument();
+
+      // Previous link
+      expect(links[0].getAttribute("href")).toEqual("?page=4");
+      expect(links[1].getAttribute("href")).toEqual("?page=1");
+      expect(links[2].getAttribute("href")).toEqual("?page=4");
+      expect(links[3].getAttribute("href")).toEqual("?page=5");
+      expect(links[4].getAttribute("href")).toEqual("?page=6");
+      expect(links[5].getAttribute("href")).toEqual("?page=10");
+      // Next link
+      expect(links[6].getAttribute("href")).toEqual("?page=6");
+    });
+
+    // In this scenario, we need to update the current page ourselves
+    // since we stay on the same page.
+    it("when page item is selected, runs the onPageChange callback", () => {
+      const onPageChange = (page: number) => (currentPage = page);
+      let currentPage = 5;
+      const { rerender } = render(
+        <Pagination
+          pageCount={10}
+          initialPage={currentPage}
+          onPageChange={onPageChange}
+        />
+      );
+      // Pagination should show:
+      // Previous 1 ... 4 5 6 ... 10 Next
+      let links = screen.getAllByRole("link");
+
+      // Links all have "#" for their href value.
+      // Previous link
+      expect(links[0].getAttribute("href")).toEqual("#");
+      expect(links[1].getAttribute("href")).toEqual("#");
+      expect(links[2].getAttribute("href")).toEqual("#");
+      expect(links[3].getAttribute("href")).toEqual("#");
+      expect(links[4].getAttribute("href")).toEqual("#");
+      expect(links[5].getAttribute("href")).toEqual("#");
+      // Next link
+      expect(links[6].getAttribute("href")).toEqual("#");
+
+      // Page 4
+      userEvent.click(links[2]);
+      expect(currentPage).toEqual(4);
+
+      rerender(
+        <Pagination
+          pageCount={10}
+          initialPage={currentPage}
+          onPageChange={onPageChange}
+        />
+      );
+      // Pagination should show:
+      // Previous 1 2 3 4 5 ... 10 Next
+      links = screen.getAllByRole("link");
+
+      // Previous link
+      userEvent.click(links[0]);
+      expect(currentPage).toEqual(3);
+
+      rerender(
+        <Pagination
+          pageCount={10}
+          initialPage={currentPage}
+          onPageChange={onPageChange}
+        />
+      );
+      // Pagination should show:
+      // Previous 1 2 3 4 5 ... 10 Next
+      links = screen.getAllByRole("link");
+
+      // Page 10
+      userEvent.click(links[6]);
+      expect(currentPage).toEqual(10);
+
+      rerender(
+        <Pagination
+          pageCount={10}
+          initialPage={currentPage}
+          onPageChange={onPageChange}
+        />
+      );
+      // Pagination should show:
+      // Previous 1 ... 6 7 8 9 10
+      links = screen.getAllByRole("link");
+
+      // Page 6
+      userEvent.click(links[2]);
+      expect(currentPage).toEqual(6);
+    });
+
+    it("uses the currentPage prop to update the selected page", () => {
+      const onPageChange = (page: number) => console.log(page);
+      const { rerender } = render(
+        <Pagination currentPage={1} onPageChange={onPageChange} pageCount={5} />
+      );
+
+      let links = screen.getAllByRole("link");
+      let page1 = links[0].getAttribute("aria-current");
+      let page2 = links[1].getAttribute("aria-current");
+      let page3 = links[2].getAttribute("aria-current");
+
+      // Only the current page has `aria-current="page"` for accessibility.
+      expect(page1).toEqual("page");
+      expect(page2).toEqual(null);
+      expect(page3).toEqual(null);
+
+      rerender(
+        <Pagination currentPage={3} onPageChange={onPageChange} pageCount={5} />
+      );
+
+      links = screen.getAllByRole("link");
+      // links[0] is now "Previous"
+      page1 = links[1].getAttribute("aria-current");
+      page2 = links[2].getAttribute("aria-current");
+      page3 = links[3].getAttribute("aria-current");
+
+      expect(page1).toEqual(null);
+      expect(page2).toEqual(null);
+      expect(page3).toEqual("page");
+    });
+
+    it("logs a warning if both `getPageHref` and `onPageChange` props are both passed", () => {
+      const getPageHref = (page: number) => `page=${page}`;
+      const onPageChange = (page: number) => console.log(page);
+      const warn = jest.spyOn(console, "warn");
+      render(
+        <Pagination
+          pageCount={10}
+          onPageChange={onPageChange}
+          getPageHref={getPageHref}
+        />
+      );
+      expect(warn).toHaveBeenCalledWith(
+        "NYPL Reservoir Pagination: Props for both `getPageHref` and " +
+          "`onPageChange` are passed. The component will default to using " +
+          "`getPageHref`."
+      );
+    });
+
+    it("logs a warning if both `getPageHref` and `currentPage` props are both passed", () => {
+      const getPageHref = (page: number) => `page=${page}`;
+      const warn = jest.spyOn(console, "warn");
+      render(
+        <Pagination pageCount={10} currentPage={2} getPageHref={getPageHref} />
+      );
+      expect(warn).toHaveBeenCalledWith(
+        "NYPL Reservoir Pagination: The `currentPage` prop does not work with " +
+          "the `getPageHref` prop. Use `currentPage` with `onPageChange` instead."
+      );
+    });
+  });
+});

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,269 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
+import React, { useState, useRef } from "react";
+
+import Link from "../Link/Link";
+import List from "../List/List";
+import { range } from "../../utils/utils";
+
+export interface PaginationProps {
+  /** Additional className. */
+  className?: string;
+  /** The currentPage can be used to programatically force the selected page to change
+   * without the user explicitly requesting it – for example, if the user should be
+   * brought back to the first page of a set of results after a new search. */
+  currentPage?: number;
+  /** The callback function that takes a page number and returns a string
+   * to use for a link's `href` attribute. This is used when the current
+   * page should refresh when navigating. */
+  getPageHref?: undefined | ((pageNumber: number) => string);
+  /** ID that other components can cross reference for accessibility purposes. */
+  id?: string;
+  /** The initially selected page (default value is 1). */
+  initialPage?: number;
+  /** The callback function called when an item is selected and the current
+   * page should not refresh. */
+  onPageChange?: (selected: number) => void;
+  /** The total number of pages. */
+  pageCount: number;
+}
+
+/**
+ * A component that provides a navigational list of page items.
+ */
+export const Pagination = chakra((props: PaginationProps) => {
+  const {
+    className,
+    currentPage,
+    getPageHref,
+    id,
+    initialPage = 1,
+    onPageChange,
+    pageCount,
+    ...rest
+  } = props;
+  const refCurrentPage = useRef(currentPage);
+  const [selectedPage, setSelectedPage] = useState<number>(initialPage);
+  const styles = useMultiStyleConfig("Pagination", {});
+  const previousPageNumber = selectedPage - 1;
+  const nextPageNumber = selectedPage + 1;
+
+  // If the parent passes down a new currentPage, and an onPageChange
+  // function exists, then set the internal state – selectedPage –
+  // to the new currentPage and update the refCurrentPage with that value.
+  React.useEffect(() => {
+    if (onPageChange && currentPage && currentPage !== refCurrentPage.current) {
+      setSelectedPage(currentPage);
+      refCurrentPage.current = currentPage;
+    }
+  }, [currentPage, onPageChange]);
+
+  // If there are 0 or 1 page, the pagination should not show.
+  if (pageCount <= 1) {
+    return null;
+  }
+  if (getPageHref && onPageChange) {
+    console.warn(
+      "NYPL Reservoir Pagination: Props for both `getPageHref` and " +
+        "`onPageChange` are passed. The component will default to using " +
+        "`getPageHref`."
+    );
+  }
+
+  if (getPageHref && currentPage) {
+    console.warn(
+      "NYPL Reservoir Pagination: The `currentPage` prop does not work with " +
+        "the `getPageHref` prop. Use `currentPage` with `onPageChange` instead."
+    );
+  }
+
+  // If `getPageHref` was passed, then links should go to a new page.
+  const changeUrls =
+    typeof getPageHref !== "undefined" && typeof getPageHref === "function";
+  /**
+   * This function is only called when clicking on a link should
+   * not update the URL or refresh the page.
+   */
+  const handlePageClick = (e: Event, clickedPage: number) => {
+    e.preventDefault && e.preventDefault();
+    if (selectedPage === clickedPage) return;
+    setSelectedPage(clickedPage);
+    onPageChange && onPageChange(clickedPage);
+  };
+  // Select the previous page.
+  const previousPage = (e: Event) => {
+    if (selectedPage > 1) {
+      handlePageClick(e, previousPageNumber);
+    }
+  };
+  // Select the next page.
+  const nextPage = (e: Event) => {
+    if (selectedPage < pageCount) {
+      handlePageClick(e, nextPageNumber);
+    }
+  };
+  /**
+   * All `Link` components have similar attributes but we need to differentiate
+   * between the "previous", "next", and regular number links.
+   * 1. If `getPageHref` is passed, this means that the page refreshes and the
+   *    URL changes. In this case, the parent component returns the `href` URL
+   *    and the `onClick` callback is undefined.
+   * 2. Otherwise, we stay on the same page by setting the `href` attribute to
+   *    "#" and call the `onPageChange` prop through the `onClick` callback.
+   */
+  const getLinkElement = (
+    type: "items" | "previous" | "next",
+    item?: number
+  ) => {
+    const isSelectedPage = selectedPage === item;
+    // The current page link has different styles.
+    const currentStyles = isSelectedPage
+      ? {
+          color: "ui.black",
+          pointerEvent: "none",
+        }
+      : {};
+    const allAttrs = {
+      items: {
+        href: changeUrls ? getPageHref(item as number) : "#",
+        attributes: {
+          "aria-label": `Page ${item}`,
+          "aria-current": isSelectedPage ? "page" : null,
+          onClick: changeUrls
+            ? undefined
+            : (e: Event) => handlePageClick(e, item as number),
+        },
+        text: item,
+      },
+      previous: {
+        href: changeUrls ? getPageHref(previousPageNumber) : "#",
+        attributes: {
+          "aria-label": "Previous page",
+          onClick: changeUrls ? undefined : previousPage,
+        },
+        text: "Previous",
+      },
+      next: {
+        href: changeUrls ? getPageHref(nextPageNumber) : "#",
+        attributes: {
+          "aria-label": "Next page",
+          onClick: changeUrls ? undefined : nextPage,
+        },
+        text: "Next",
+      },
+    };
+    const linkAttrs = allAttrs[type];
+    return (
+      <Link
+        href={linkAttrs.href}
+        id={`${id}-${linkAttrs.text}`}
+        {...linkAttrs.attributes}
+        __css={{
+          ...styles.link,
+          ...currentStyles,
+        }}
+      >
+        {linkAttrs.text}
+      </Link>
+    );
+  };
+
+  /**
+   * This function returns an array of `li` elements with numbers based on the
+   * total pages that `Pagination` should display. When there are many pages to
+   * display, ellipsis are shown to signify that the intermediate page numbers
+   * are hidden.
+   * For a small number of pages, the array will be simple.
+   * For a large number of pages, the resulting array will be in the shape of:
+   * [
+   *    1, this always displays
+   *    2 or an ellipsis,
+   *    a range of numbers in the middle of the total count,
+   *    pageCount - 1 or an ellipsis,
+   *    pageCount, the total number of pages
+   * ]
+   */
+  const getPaginationNumbers = (selected: number) => {
+    // Where should the middle range of numbers start at?
+    const middleRangeStart = Math.max(
+      // Start at three if the current page is near the beginning.
+      3,
+      Math.min(
+        // If the current page is in the middle, start the range
+        // one number before the current page.
+        selected - 1,
+        // If the current page is near the end, show the last five items.
+        pageCount - 4
+      )
+    );
+    // Where should the middle range of numbers end at?
+    const middleRangeEnd = Math.min(
+      // If the current page is near the end, end the range
+      // two place before the last page number.
+      pageCount - 2,
+      Math.max(
+        // If the current page is in the middle, end the range
+        // one number after the current page.
+        selected + 1,
+        // If the current page is near the end, show the first five items.
+        5
+      )
+    );
+    const itemList =
+      pageCount < 4
+        ? // Get a short array with 2 or 3 items: [1, 2] or [1, 2, 3]
+          Array.from({ length: pageCount }, (_, i) => i + 1)
+        : // Otherwise, create the longer array of items.
+          [
+            // Always display the first page.
+            1,
+            // The second item will be 2 or an ellipse.
+            middleRangeStart > 3 ? "ellipse-start" : 2,
+            // The middle range of page numbers to display.
+            // Add +1 to the end since range() doesn't include the last number.
+            ...range(middleRangeStart, middleRangeEnd + 1),
+            // The next to last item will be the next to last
+            // number or an ellipse.
+            middleRangeEnd < pageCount - 2 ? "ellipse-end" : pageCount - 1,
+            // Always display the last page.
+            pageCount,
+          ];
+    // If it's a number, render an `li` element with a link page item,
+    // otherwise return the `li` with the ellipse for a break.
+    const pageLiItems = itemList.map((item) => {
+      const itemElement =
+        typeof item === "number" ? getLinkElement("items", item) : "...";
+      return <li key={item}>{itemElement}</li>;
+    });
+
+    return pageLiItems;
+  };
+
+  // Don't display the previous link when you're on the first page.
+  const previousLiLink = selectedPage !== 1 && (
+    <li key="previous">{getLinkElement("previous")}</li>
+  );
+  // Don't display the next link when you're on the last page.
+  const nextLiLink = selectedPage !== pageCount && (
+    <li key="next">{getLinkElement("next")}</li>
+  );
+
+  return (
+    <Box
+      as="nav"
+      id={id}
+      aria-label="Pagination"
+      role="navigation"
+      className={className}
+      __css={styles}
+      {...rest}
+    >
+      <List type="ul" inline noStyling id={`${id}-list`}>
+        {previousLiLink}
+        {getPaginationNumbers(selectedPage)}
+        {nextLiLink}
+      </List>
+    </Box>
+  );
+});
+
+export default Pagination;