@nypl/design-system-react-components 0.25.0 → 0.25.4

package/src/components/Pagination/Pagination.tsx

@@ -1,218 +1,238 @@
-import * as React from "react";
+import React, { useState } from "react";
+import { Box, useMultiStyleConfig } from "@chakra-ui/react";
 
 import Link from "../Link/Link";
-import bem from "../../utils/bem";
+import List from "../List/List";
+import { ListTypes } from "../List/ListTypes";
 import { range } from "../../utils/utils";
+import generateUUID from "../../helpers/generateUUID";
 
 export interface PaginationProps {
-  /** BlockName for use with BEM. See how to work with blockNames and BEM here: http://getbem.com/introduction/ */
-  blockName?: string;
-  /** Additional className for use with BEM. See how to work with blockNames and BEM here: http://getbem.com/introduction/ */
+  /** Additional className. */
   className?: string;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** The total number of pages. */
-  pageCount: 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. */
-  currentPage: number;
-  /** A method that returns a Link component given the target page */
-  getPageHref?: (pageNumber: number) => string;
-  /** The method to callback when an item is selected. Passes the selected page to the consuming app as an argument. */
+  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. */
+/**
+ * A component that provides a navigational list of page items.
+ */
 const Pagination: React.FC<PaginationProps> = (props: PaginationProps) => {
   const {
-    blockName,
     className,
-    modifiers = [],
-    pageCount,
-    currentPage = 1,
+    initialPage = 1,
     getPageHref,
-    onPageChange,
+    id = generateUUID(),
+    onPageChange = () => {},
+    pageCount,
   } = props;
+  const [currentPage, setCurrentPage] = useState<number>(initialPage);
+  const styles = useMultiStyleConfig("Pagination", {});
+  const previousPageNumber = currentPage - 1;
+  const nextPageNumber = currentPage + 1;
 
-  // If there are 0 or 1 pages, the pagination should not show.
+  // If there are 0 or 1 page, the pagination should not show.
   if (pageCount <= 1) {
     return null;
   }
-
   if (getPageHref && onPageChange) {
     console.warn(
-      "Both onPageHref and onPageChange are passed. Will default to using `onPageHref`."
+      "Props for both `getPageHref` and `onPageChange` are passed. Will default to using `getPageHref`."
     );
   }
 
+  // If `getPageHref` was passed, then links should go to a new page.
   const changeUrls =
     typeof getPageHref !== "undefined" && typeof getPageHref === "function";
-
-  const selectPage = (evt: Event, item: number) => {
-    const runCallback = (selectedItem: number) => {
-      evt.preventDefault ? evt.preventDefault() : (evt.returnValue = false);
-
-      if (
-        typeof onPageChange !== "undefined" &&
-        typeof onPageChange === "function"
-      ) {
-        onPageChange(selectedItem);
-      }
-    };
-
-    evt.preventDefault ? evt.preventDefault() : (evt.returnValue = false);
-    if (currentPage === item) return;
-
-    // Invoke the callback with the new selected item.
-    runCallback(item);
+  /**
+   * 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) => {
+    e.preventDefault && e.preventDefault();
+    if (currentPage === selectedPage) return;
+    setCurrentPage(selectedPage);
+    onPageChange(selectedPage);
   };
-
-  const previousPage = (evt: Event) => {
-    evt.preventDefault ? evt.preventDefault() : (evt.returnValue = false);
+  // Select the previous page.
+  const previousPage = (e: Event) => {
     if (currentPage > 1) {
-      selectPage(evt, currentPage - 1);
+      selectPage(e, previousPageNumber);
     }
   };
-
-  const nextPage = (evt: Event) => {
-    evt.preventDefault ? evt.preventDefault() : (evt.returnValue = false);
+  // Select the next page.
+  const nextPage = (e: Event) => {
     if (currentPage < pageCount) {
-      selectPage(evt, currentPage + 1);
+      selectPage(e, nextPageNumber);
     }
   };
-
-  const getPageElement = (item: number) => {
-    const pageAttributes = {
-      "aria-label": null,
-      onClick: !changeUrls ? (evt) => selectPage(evt, item) : undefined,
-      role: "button",
-      tabIndex: 0,
+  /**
+   * 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: string, item?: number) => {
+    const isCurrentPage = currentPage === item;
+    // The current page link has different styles.
+    const currentStyles = isCurrentPage
+      ? {
+          color: "ui.black",
+          pointerEvent: "none",
+        }
+      : {};
+    const allAttrs = {
+      items: {
+        href: changeUrls ? getPageHref(item) : "#",
+        attributes: {
+          "aria-label": `Page ${item}`,
+          "aria-current": isCurrentPage ? "page" : null,
+          onClick: changeUrls ? undefined : (e) => selectPage(e, item),
+        },
+        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",
+      },
     };
-
-    pageAttributes["aria-label"] = item ? item : null;
-
-    const pageClass = currentPage === item ? "selected" : null;
-
+    const linkAttrs = allAttrs[type];
     return (
       <Link
-        attributes={{ ...pageAttributes }}
-        className={bem("link", modifiers, "pagination", [pageClass])}
-        href={changeUrls ? getPageHref(item) : "#"}
+        additionalStyles={{
+          ...styles.link,
+          ...currentStyles,
+        }}
+        attributes={linkAttrs.attributes}
+        href={linkAttrs.href}
+        id={`${id}-${linkAttrs.text}`}
       >
-        {item}
+        {linkAttrs.text}
       </Link>
     );
   };
 
-  const pagination = (selected: number) => {
-    // 1, (2 or ...), pageStart - pageEnd, (next to last item or ...), pageCount
-    const pageStart = Math.max(
-      3, // if near the beginning, inner pages start at 3
+  /**
+   * 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 in the middle, inner pages begin two items before the selected page
-        selected - 2,
-        // If near the end, count back and show 7 items
-        pageCount - 6
+        // 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
       )
     );
-
-    const pageEnd = Math.min(
-      // if near the end, inner pages end just before next to last item (or ellipse)
+    // 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 in the middle, inner pages end two items after the selected page
-        selected + 2,
-        // If near the beginning, show the first 7 items
-        7
+        // 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 truncatedList =
+    const itemList =
       pageCount < 4
-        ? Array.from({ length: pageCount }, (_, i) => i + 1)
-        : [
-            // list always starts at and displays the first page item
+        ? // 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,
-            // second item will either be item 2 or an ellipse
-            pageStart > 3 ? "ellipse-start" : 2,
-            // Adding + 1 here since range() doesn't include the last item passed to it
-            ...range(pageStart, pageEnd + 1),
-            // next to last item will either be an ellipse or the next to last page number
-            pageEnd < pageCount - 2 ? "ellipse-end" : pageCount - 1,
-            // list always ends at and displays the last page number in the pageCount
+            // 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,
           ];
-    const pageItems = truncatedList.map((item) => {
-      // if it's a number, render that page item, otherwise return the ellipse
+    // 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" ? getPageElement(item) : "...";
-      return (
-        <li key={item} className={bem("item", modifiers, "pagination")}>
-          {itemElement}
-        </li>
-      );
+        typeof item === "number" ? getLinkElement("items", item) : "...";
+      return <li key={item}>{itemElement}</li>;
     });
 
-    return pageItems;
-  };
-
-  // When at the beginning, disable Previous. When at the end, disable Next.
-  const prevDisabled = currentPage === 1;
-  const nextDisabled = currentPage === pageCount;
-
-  // Attributes for Previous and Next Buttons
-  const prevAttributes = {
-    "aria-disabled": prevDisabled ? "true" : null,
-    "aria-label": "Previous page",
-    role: "button",
-    onClick: changeUrls ? undefined : previousPage,
-    tabIndex: prevDisabled ? -1 : 0,
-  };
-
-  const nextAttributes = {
-    "aria-disabled": nextDisabled ? "true" : null,
-    "aria-label": "Next page",
-    role: "button",
-    onClick: changeUrls ? undefined : nextPage,
-    tabIndex: nextDisabled ? -1 : null,
+    return pageLiItems;
   };
 
-  const prevClass = prevDisabled ? "disabled" : null;
-  const nextClass = nextDisabled ? "disabled" : null;
+  // Don't display the previous link when you're on the first page.
+  const previousLiLink = currentPage !== 1 && (
+    <li key="previous">{getLinkElement("previous")}</li>
+  );
+  /// Don't display the next link when you're on the last page.
+  const nextLiLink = currentPage !== pageCount && (
+    <li key="next">{getLinkElement("next")}</li>
+  );
 
   return (
-    <nav
+    <Box
+      as="nav"
+      id={id}
       aria-label="Pagination"
-      className={bem("pagination", modifiers, blockName, [className])}
+      role="navigation"
+      className={className}
+      __css={styles}
     >
-      <ul className={bem("list", modifiers, "pagination")}>
-        <li key="previous" className={bem("item", modifiers, "pagination")}>
-          <Link
-            attributes={{ ...prevAttributes }}
-            className={bem("link", modifiers, "pagination", [prevClass])}
-            href={
-              !prevDisabled && changeUrls ? getPageHref(currentPage - 1) : "#"
-            }
-          >
-            Previous
-          </Link>
-        </li>
-
-        {pagination(currentPage)}
-
-        <li key="next" className={bem("item", modifiers, "pagination")}>
-          <Link
-            attributes={{
-              ...nextAttributes,
-            }}
-            className={bem("link", modifiers, "pagination", [nextClass])}
-            href={
-              !nextDisabled && changeUrls ? getPageHref(currentPage + 1) : "#"
-            }
-          >
-            Next
-          </Link>
-        </li>
-      </ul>
-    </nav>
+      <List type={ListTypes.Unordered} inline noStyling id={`${id}-list`}>
+        {previousLiLink}
+        {getPaginationNumbers(currentPage)}
+        {nextLiLink}
+      </List>
+    </Box>
   );
 };
 

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

@@ -0,0 +1,285 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Pagination Rendering Renders the UI snapshot correctly 1`] = `
+<nav
+  aria-label="Pagination"
+  className="css-0"
+  id="firstPage"
+  role="navigation"
+>
+  <ul
+    className="css-0"
+    id="firstPage-list"
+  >
+    <li>
+      <a
+        aria-current="page"
+        aria-label="Page 1"
+        className="css-1858g8z"
+        href="page=1"
+        id="firstPage-1"
+      >
+        1
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 2"
+        className="css-0"
+        href="page=2"
+        id="firstPage-2"
+      >
+        2
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 3"
+        className="css-0"
+        href="page=3"
+        id="firstPage-3"
+      >
+        3
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 4"
+        className="css-0"
+        href="page=4"
+        id="firstPage-4"
+      >
+        4
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 5"
+        className="css-0"
+        href="page=5"
+        id="firstPage-5"
+      >
+        5
+      </a>
+    </li>
+    <li>
+      ...
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 10"
+        className="css-0"
+        href="page=10"
+        id="firstPage-10"
+      >
+        10
+      </a>
+    </li>
+    <li>
+      <a
+        aria-label="Next page"
+        className="css-0"
+        href="page=2"
+        id="firstPage-Next"
+      >
+        Next
+      </a>
+    </li>
+  </ul>
+</nav>
+`;
+
+exports[`Pagination Rendering Renders the UI snapshot correctly 2`] = `
+<nav
+  aria-label="Pagination"
+  className="css-0"
+  id="lastPage"
+  role="navigation"
+>
+  <ul
+    className="css-0"
+    id="lastPage-list"
+  >
+    <li>
+      <a
+        aria-label="Previous page"
+        className="css-0"
+        href="page=9"
+        id="lastPage-Previous"
+      >
+        Previous
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 1"
+        className="css-0"
+        href="page=1"
+        id="lastPage-1"
+      >
+        1
+      </a>
+    </li>
+    <li>
+      ...
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 6"
+        className="css-0"
+        href="page=6"
+        id="lastPage-6"
+      >
+        6
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 7"
+        className="css-0"
+        href="page=7"
+        id="lastPage-7"
+      >
+        7
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 8"
+        className="css-0"
+        href="page=8"
+        id="lastPage-8"
+      >
+        8
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 9"
+        className="css-0"
+        href="page=9"
+        id="lastPage-9"
+      >
+        9
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current="page"
+        aria-label="Page 10"
+        className="css-1858g8z"
+        href="page=10"
+        id="lastPage-10"
+      >
+        10
+      </a>
+    </li>
+  </ul>
+</nav>
+`;
+
+exports[`Pagination Rendering Renders the UI snapshot correctly 3`] = `
+<nav
+  aria-label="Pagination"
+  className="css-0"
+  id="middlePage"
+  role="navigation"
+>
+  <ul
+    className="css-0"
+    id="middlePage-list"
+  >
+    <li>
+      <a
+        aria-label="Previous page"
+        className="css-0"
+        href="page=4"
+        id="middlePage-Previous"
+      >
+        Previous
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 1"
+        className="css-0"
+        href="page=1"
+        id="middlePage-1"
+      >
+        1
+      </a>
+    </li>
+    <li>
+      ...
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 4"
+        className="css-0"
+        href="page=4"
+        id="middlePage-4"
+      >
+        4
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current="page"
+        aria-label="Page 5"
+        className="css-1858g8z"
+        href="page=5"
+        id="middlePage-5"
+      >
+        5
+      </a>
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 6"
+        className="css-0"
+        href="page=6"
+        id="middlePage-6"
+      >
+        6
+      </a>
+    </li>
+    <li>
+      ...
+    </li>
+    <li>
+      <a
+        aria-current={null}
+        aria-label="Page 10"
+        className="css-0"
+        href="page=10"
+        id="middlePage-10"
+      >
+        10
+      </a>
+    </li>
+    <li>
+      <a
+        aria-label="Next page"
+        className="css-0"
+        href="page=6"
+        id="middlePage-Next"
+      >
+        Next
+      </a>
+    </li>
+  </ul>
+</nav>
+`;