@nypl/design-system-react-components 0.25.11 → 0.26.0

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

@@ -11,19 +11,19 @@ describe("Pagination Accessibility", () => {
 
   it("passes axe accessibility on the first page", async () => {
     const { container } = render(
-      <Pagination pageCount={20} initialPage={1} getPageHref={getPageHref} />
+      <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} initialPage={10} getPageHref={getPageHref} />
+      <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} initialPage={20} getPageHref={getPageHref} />
+      <Pagination pageCount={20} currentPage={20} getPageHref={getPageHref} />
     );
     expect(await axe(container)).toHaveNoViolations();
   });
@@ -166,7 +166,7 @@ describe("Pagination", () => {
       expect(screen.queryByRole("navigation")).not.toBeInTheDocument();
     });
 
-    it("Renders the UI snapshot correctly", () => {
+    it("renders the UI snapshot correctly", () => {
       const firstPage = renderer
         .create(
           <Pagination
@@ -197,14 +197,64 @@ describe("Pagination", () => {
           />
         )
         .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(
@@ -230,7 +280,7 @@ describe("Pagination", () => {
 
     // 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", () => {
+    it("when page item is selected, runs the onPageChange callback", () => {
       const onPageChange = (page: number) => (currentPage = page);
       let currentPage = 5;
       const { rerender } = render(
@@ -304,5 +354,66 @@ describe("Pagination", () => {
       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

@@ -1,23 +1,25 @@
-import React, { useState } from "react";
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+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 { ListTypes } from "../List/ListTypes";
 import { range } from "../../utils/utils";
-import generateUUID from "../../helpers/generateUUID";
-
 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 current page selected. */
-  initialPage: number;
+  /** 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;
@@ -28,19 +30,32 @@ export interface PaginationProps {
 /**
  * A component that provides a navigational list of page items.
  */
-const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
+export const Pagination = chakra((props: PaginationProps) => {
   const {
     className,
+    currentPage,
     getPageHref,
-    id = generateUUID(),
+    id,
     initialPage = 1,
     onPageChange,
     pageCount,
+    ...rest
   } = props;
-  const [currentPage, setCurrentPage] = useState<number>(initialPage);
+  const refCurrentPage = useRef(currentPage);
+  const [selectedPage, setSelectedPage] = useState<number>(initialPage);
   const styles = useMultiStyleConfig("Pagination", {});
-  const previousPageNumber = currentPage - 1;
-  const nextPageNumber = currentPage + 1;
+  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 !== refCurrentPage.current) {
+      setSelectedPage(currentPage);
+      refCurrentPage.current = currentPage;
+    }
+  }, [currentPage, onPageChange]);
 
   // If there are 0 or 1 page, the pagination should not show.
   if (pageCount <= 1) {
@@ -48,7 +63,16 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
   }
   if (getPageHref && onPageChange) {
     console.warn(
-      "Props for both `getPageHref` and `onPageChange` are passed. Will default to using `getPageHref`."
+      "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."
     );
   }
 
@@ -59,22 +83,22 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
    * This function is only called when clicking on a link should
    * not update the URL or refresh the page.
    */
-  const selectPage = (e: Event, selectedPage: number) => {
+  const handlePageClick = (e: Event, clickedPage: number) => {
     e.preventDefault && e.preventDefault();
-    if (currentPage === selectedPage) return;
-    setCurrentPage(selectedPage);
-    onPageChange && onPageChange(selectedPage);
+    if (selectedPage === clickedPage) return;
+    setSelectedPage(clickedPage);
+    onPageChange && onPageChange(clickedPage);
   };
   // Select the previous page.
   const previousPage = (e: Event) => {
-    if (currentPage > 1) {
-      selectPage(e, previousPageNumber);
+    if (selectedPage > 1) {
+      handlePageClick(e, previousPageNumber);
     }
   };
   // Select the next page.
   const nextPage = (e: Event) => {
-    if (currentPage < pageCount) {
-      selectPage(e, nextPageNumber);
+    if (selectedPage < pageCount) {
+      handlePageClick(e, nextPageNumber);
     }
   };
   /**
@@ -87,9 +111,9 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
    *    "#" and call the `onPageChange` prop through the `onClick` callback.
    */
   const getLinkElement = (type: string, item?: number) => {
-    const isCurrentPage = currentPage === item;
+    const isSelectedPage = selectedPage === item;
     // The current page link has different styles.
-    const currentStyles = isCurrentPage
+    const currentStyles = isSelectedPage
       ? {
           color: "ui.black",
           pointerEvent: "none",
@@ -100,8 +124,8 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
         href: changeUrls ? getPageHref(item) : "#",
         attributes: {
           "aria-label": `Page ${item}`,
-          "aria-current": isCurrentPage ? "page" : null,
-          onClick: changeUrls ? undefined : (e) => selectPage(e, item),
+          "aria-current": isSelectedPage ? "page" : null,
+          onClick: changeUrls ? undefined : (e) => handlePageClick(e, item),
         },
         text: item,
       },
@@ -210,11 +234,11 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
   };
 
   // Don't display the previous link when you're on the first page.
-  const previousLiLink = currentPage !== 1 && (
+  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 = currentPage !== pageCount && (
+  // Don't display the next link when you're on the last page.
+  const nextLiLink = selectedPage !== pageCount && (
     <li key="next">{getLinkElement("next")}</li>
   );
 
@@ -226,14 +250,15 @@ const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
       role="navigation"
       className={className}
       __css={styles}
+      {...rest}
     >
       <List type={ListTypes.Unordered} inline noStyling id={`${id}-list`}>
         {previousLiLink}
-        {getPaginationNumbers(currentPage)}
+        {getPaginationNumbers(selectedPage)}
         {nextLiLink}
       </List>
     </Box>
   );
-};
+});
 
 export default Pagination;