@purpurds/pagination 5.19.1

package/src/pagination-truncation-separator.test.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+import * as matchers from "@testing-library/jest-dom/matchers";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { PaginationTruncationSeparator } from "./pagination-truncation-separator";
+
+expect.extend(matchers);
+
+afterEach(() => {
+  vi.clearAllMocks();
+  cleanup();
+});
+
+describe("PaginationTruncationSeparator", () => {
+  it("renders without crashing", () => {
+    render(<PaginationTruncationSeparator />);
+    expect(screen.getByTestId(Selectors.PAGINATION_TRUNCATION_SEPARATOR)).toBeInTheDocument();
+    expect(screen.getByTestId(Selectors.PAGINATION_TRUNCATION_SEPARATOR)).toHaveTextContent("...");
+  });
+});
+
+const Selectors = {
+  PAGINATION_TRUNCATION_SEPARATOR: "purpur-pagination-truncation-separator",
+};

package/src/pagination-truncation-separator.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import { Paragraph } from "@purpurds/paragraph";
+import c from "classnames/bind";
+
+import styles from "./pagination-truncation-separator.module.scss";
+const cx = c.bind(styles);
+
+export type PaginationTruncationSeparatorProps = {
+  ["data-testid"]?: string;
+  className?: string;
+};
+
+const rootClassName = "purpur-pagination-truncation-separator";
+
+export const PaginationTruncationSeparator = ({
+  ["data-testid"]: dataTestId = "purpur-pagination-truncation-separator",
+  className,
+  ...props
+}: PaginationTruncationSeparatorProps) => {
+  const classes = cx([className, rootClassName]);
+
+  return (
+    <li className={classes} data-testid={dataTestId} {...props}>
+      <Paragraph>...</Paragraph>
+    </li>
+  );
+};
+
+PaginationTruncationSeparator.displayName = "PaginationTruncationSeparator";

package/src/pagination.module.scss

@@ -0,0 +1,105 @@
+@import "@purpurds/tokens/breakpoint/variables";
+
+.purpur-pagination {
+  $root: &;
+  align-items: center;
+  display: flex;
+  flex-direction: column-reverse;
+  gap: var(--purpur-spacing-300);
+
+  @media screen and (min-width: $purpur-breakpoint-lg) {
+    align-items: center;
+    display: grid;
+    gap: var(--purpur-spacing-100);
+    grid-template-areas: "pagesize pagination empty";
+    grid-template-columns: 1fr 3fr 1fr;
+  }
+
+  &__page-size-select-container {
+    flex: 0 0 auto;
+    width: 100%;
+
+    @media screen and (min-width: $purpur-breakpoint-lg) {
+      grid-area: pagesize;
+      width: auto;
+    }
+  }
+
+  &__pagination-container {
+    align-items: center;
+    display: inline-flex;
+    gap: var(--purpur-spacing-200);
+    margin: 0 auto;
+    max-width: calc(3 * var(--purpur-spacing-1200));
+    width: 100%;
+
+    @media screen and (min-width: $purpur-breakpoint-md) {
+      gap: var(--purpur-spacing-400);
+      max-width: none;
+      width: auto;
+    }
+
+    @media screen and (min-width: $purpur-breakpoint-lg) {
+      grid-area: pagination;
+      justify-self: center;
+    }
+  }
+
+  &__step-trigger-label {
+    border: 0;
+    clip: rect(0, 0, 0, 0);
+    display: block;
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    padding: 0;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+
+    @media screen and (min-width: $purpur-breakpoint-lg) {
+      clip: auto;
+      display: inline;
+      height: auto;
+      margin: 0;
+      overflow: visible;
+      position: static;
+      white-space: normal;
+      width: auto;
+    }
+  }
+
+  &__step-trigger {
+    flex: 0 0 auto;
+  }
+
+  &__page-trigger-container {
+    display: flex;
+    flex: 1 1 auto;
+    justify-content: center;
+  }
+
+  #{$root}__pages {
+    display: none;
+
+    &--visible {
+      display: flex;
+    }
+
+    @media screen and (min-width: $purpur-breakpoint-md) {
+      display: flex;
+    }
+  }
+
+  #{$root}__page-selector {
+    display: none;
+
+    &--visible {
+      display: flex;
+    }
+
+    @media screen and (min-width: $purpur-breakpoint-md) {
+      display: none;
+    }
+  }
+}

package/src/pagination.stories.tsx

@@ -0,0 +1,197 @@
+import React, { forwardRef } from "react";
+import { Skeleton } from "@purpurds/skeleton";
+import { useArgs } from "@storybook/preview-api";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import "@purpurds/autocomplete/styles";
+import "@purpurds/icon/styles";
+import "@purpurds/label/styles";
+import "@purpurds/listbox/styles";
+import "@purpurds/paragraph/styles";
+import "@purpurds/select/styles";
+import "@purpurds/skeleton/styles";
+import "@purpurds/text-field/styles";
+import { Pagination, PaginationProps } from "./pagination";
+import { PaginationInformation } from "./types";
+
+type CustomTestLinkProps = {
+  children?: React.ReactNode;
+  href?: string;
+  target?: string;
+};
+
+const CustomTestLink = forwardRef(({ children, href, target, ...props }: CustomTestLinkProps) => {
+  return (
+    <a href={href} target={target} {...props}>
+      {children}
+    </a>
+  );
+});
+
+const meta = {
+  title: "Components/Pagination",
+  component: Pagination,
+  argTypes: {
+    asLink: {
+      table: {
+        type: { summary: "Whether or not the pages should be rendered as links or buttons" },
+      },
+    },
+    hrefGetter: {
+      table: {
+        type: {
+          summary: `hrefGetter: (hrefInformation: HrefInformation) => string;
+                   - Function that returns a url for a step when asLink is true.
+          `,
+        },
+      },
+    },
+    navigationFunction: {
+      table: {
+        type: {
+          summary: `(navigationInformation: NavigationInformation) => void 
+            - Optional function to be used when navigating from javascript. 
+            Defaults to a function that changes window.location.href. 
+            Will only be called in link mode from the page select dropdown or the page size select.`,
+        },
+      },
+    },
+    anchorTagElement: {
+      table: {
+        type: {
+          summary:
+            "A React.ForwardRefExoticComponent<React.AnchorHTMLAttributes<HTMLAnchorElement>> that will be used as the link if asLink is true.",
+        },
+      },
+    },
+    onPageChange: {
+      table: {
+        type: {
+          summary: `onPageChange: (paginationChangeInformation: PaginationInformation) => void
+                  - Function that will be called when the page changes. Mandatory for keeping up with the currentPage in button mode.
+                    Optional when asLink is true, can be used to run some code on page change.`,
+        },
+      },
+    },
+  },
+  parameters: {
+    design: [
+      {
+        name: "Pagination",
+        type: "figma",
+        url: "https://www.figma.com/design/XEaIIFskrrxIBHMZDkIuIg/Purpur-DS---Component-library-%26-guidelines?node-id=33818-15953",
+      },
+    ],
+  },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+type Story = StoryObj<typeof Pagination>;
+
+export const Showcase: Story = {
+  args: {
+    className: "myClassName",
+    currentPage: 1,
+    pageSize: 10,
+    pageSizeLabel: "Items per page",
+    nextButtonText: "Next",
+    outOfLabel: "of",
+    previousButtonText: "Previous",
+    pageSelectorAutocompleteId: "pageSelectorAutocompleteId",
+    pageSelectorListBoxLabel: "Select a page",
+    pageSelectorNoOptionsText: "Page does not exist",
+    totalItems: 145,
+  },
+  render: ({ ...args }) => {
+    const [{ currentPage }, updateArgs]: [
+      PaginationProps,
+      (newArgs: Partial<PaginationProps>) => void,
+      (argNames?: (keyof PaginationProps)[] | undefined) => void
+    ] = useArgs(); // eslint-disable-line react-hooks/rules-of-hooks
+    const onPageChange = ({ currentPage }: PaginationInformation) => {
+      updateArgs({ currentPage });
+    };
+
+    return (
+      <div>
+        <Skeleton style={{ height: "25rem", width: "100%", marginBottom: "2rem" }} />
+        <Pagination {...args} currentPage={currentPage} onPageChange={onPageChange} />
+      </div>
+    );
+  },
+};
+
+export const AsLinks: Story = {
+  args: {
+    asLink: true,
+    className: "myClassName",
+    currentPage: 1,
+    pageSize: 10,
+    pageSizeLabel: "Items per page",
+    hrefGetter: ({ page, pageSize }) =>
+      `?path=/story/components-pagination--as-links&args=currentPage:${page};pageSize:${pageSize}`,
+    nextButtonText: "Next",
+    outOfLabel: "of",
+    previousButtonText: "Previous",
+    pageSelectorListBoxLabel: "Select a page",
+    pageSelectorNoOptionsText: "Page does not exist",
+    totalItems: 145,
+  },
+  render: ({ ...args }) => {
+    const [{ currentPage }, updateArgs]: [
+      PaginationProps,
+      (newArgs: Partial<PaginationProps>) => void,
+      (argNames?: (keyof PaginationProps)[] | undefined) => void
+    ] = useArgs(); // eslint-disable-line react-hooks/rules-of-hooks
+    const onPageChange = ({ currentPage }: PaginationInformation) => {
+      updateArgs({ currentPage });
+    };
+
+    return (
+      <div>
+        <Skeleton style={{ height: "25rem", width: "100%", marginBottom: "2rem" }} />
+        <Pagination {...args} currentPage={currentPage} onPageChange={onPageChange} />
+      </div>
+    );
+  },
+};
+
+export const AsCustomLinks: Story = {
+  args: {
+    anchorTagElement: CustomTestLink,
+    asLink: true,
+    className: "myClassName",
+    currentPage: 5,
+    hrefGetter: ({ page, pageSize }) =>
+      `?path=/story/components-pagination--as-custom-links&args=currentPage:${page};pageSize:${pageSize}`,
+    navigationFunction: function ({ currentPage, pageSize, url }) {
+      // eslint-disable-next-line no-console
+      console.log(currentPage, pageSize, url);
+    },
+    nextButtonText: "Next",
+    outOfLabel: "of",
+    previousButtonText: "Previous",
+    pageSize: 10,
+    pageSizeLabel: "Items per page",
+    pageSelectorListBoxLabel: "Select a page",
+    pageSelectorNoOptionsText: "Page does not exist",
+    totalItems: 145,
+  },
+  render: ({ ...args }) => {
+    const [{ currentPage }, updateArgs]: [
+      PaginationProps,
+      (newArgs: Partial<PaginationProps>) => void,
+      (argNames?: (keyof PaginationProps)[] | undefined) => void
+    ] = useArgs(); // eslint-disable-line react-hooks/rules-of-hooks
+    const onPageChange = ({ currentPage }: PaginationInformation) => {
+      updateArgs({ currentPage });
+    };
+
+    return (
+      <div>
+        <Skeleton style={{ height: "25rem", width: "100%", marginBottom: "2rem" }} />
+        <Pagination {...args} currentPage={currentPage} onPageChange={onPageChange} />
+      </div>
+    );
+  },
+};

package/src/pagination.test.tsx

@@ -0,0 +1,76 @@
+import React from "react";
+import * as matchers from "@testing-library/jest-dom/matchers";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Pagination } from "./pagination";
+
+expect.extend(matchers);
+
+const defaultArgs = {
+  currentPage: 1,
+  pageSize: 10,
+  pageSizeLabel: "Items per page",
+  nextButtonText: "Next",
+  outOfLabel: "of",
+  previousButtonText: "Previous",
+  pageSelectorListBoxLabel: "Select a page",
+  pageSelectorNoOptionsText: "Page does not exist",
+  totalItems: 145,
+  onPageChange: vi.fn(),
+};
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("Pagination", () => {
+  it("should render", () => {
+    render(<Pagination {...defaultArgs} />);
+    const pagination = screen.getByTestId(Selectors.PAGINATION);
+    expect(pagination).toBeInTheDocument();
+  });
+
+  it("should have a previous page button", () => {
+    render(<Pagination {...defaultArgs} />);
+    const previousButton = screen.getByTestId(Selectors.PREVIOUS_BUTTON);
+    expect(previousButton).toBeInTheDocument();
+  });
+
+  it("should have a next page button", () => {
+    render(<Pagination {...defaultArgs} />);
+    const nextButton = screen.getByTestId(Selectors.NEXT_BUTTON);
+    expect(nextButton).toBeInTheDocument();
+  });
+
+  it("should have a page size selector", () => {
+    render(<Pagination {...defaultArgs} />);
+    const pageSizeSelector = screen.getByTestId(Selectors.PAGE_SIZE_SELECTOR);
+    expect(pageSizeSelector).toBeInTheDocument();
+  });
+
+  it("should always show regular page buttons if total number of pages is less than or equal to 3", () => {
+    render(<Pagination {...defaultArgs} pageSize={75} />);
+    const paginationPages = screen.getByTestId(Selectors.PAGINATION_PAGES);
+    const paginationPageSelector = screen.getByTestId(Selectors.PAGINATION_PAGE_SELECTOR);
+    expect(paginationPages).toHaveClass("purpur-pagination__pages--visible");
+    expect(paginationPageSelector).not.toHaveClass("purpur-pagination__page-selector--visible");
+  });
+
+  it("should show pagination page selector if total number of pages is greater than 3 (shown on small screen sizes)", () => {
+    render(<Pagination {...defaultArgs} pageSize={10} />);
+    const paginationPages = screen.getByTestId(Selectors.PAGINATION_PAGES);
+    const paginationPageSelector = screen.getByTestId(Selectors.PAGINATION_PAGE_SELECTOR);
+    expect(paginationPages).not.toHaveClass("purpur-pagination__pages--visible");
+    expect(paginationPageSelector).toHaveClass("purpur-pagination__page-selector--visible");
+  });
+});
+
+const Selectors = {
+  PAGINATION: "purpur-pagination",
+  PREVIOUS_BUTTON: "purpur-pagination-previous-step-trigger",
+  NEXT_BUTTON: "purpur-pagination-next-step-trigger",
+  PAGE_SIZE_SELECTOR: "purpur-pagination-page-size-selector",
+  PAGINATION_PAGES: "purpur-pagination-pages",
+  PAGINATION_PAGE_SELECTOR: "purpur-pagination-page-selector",
+};

package/src/pagination.tsx

@@ -0,0 +1,177 @@
+import React, { ForwardedRef, forwardRef } from "react";
+import { IconArrowLeft, IconArrowRight } from "@purpurds/icon";
+import c from "classnames/bind";
+
+import { navigateToPage } from "./navigation";
+import styles from "./pagination.module.scss";
+import { PaginationPageSelector } from "./pagination-page-selector";
+import { PaginationPageSizeSelector } from "./pagination-page-size-selector";
+import { PaginationPages } from "./pagination-pages";
+import { PaginationStepTrigger } from "./pagination-step-trigger";
+import { LinkProps, NoLinkProps, PaginationInformation } from "./types";
+import { usePaginationPages } from "./use-pagination-pages.hook";
+
+const cx = c.bind(styles);
+
+export type PaginationTexts = {
+  nextButtonText: string;
+  outOfLabel: string;
+  pageSelectorListBoxLabel: string;
+  pageSelectorNoOptionsText: string;
+  previousButtonText: string;
+};
+
+export type PageSizeProps = {
+  availablePageSizes?: number[];
+  pageSize?: number;
+  pageSizeLabel: string;
+};
+
+export type PaginationProps = {
+  ["data-testid"]?: string;
+  className?: string;
+  currentPage: number;
+  pageSelectorAutocompleteId?: string;
+  totalItems: number;
+} & PaginationTexts &
+  PageSizeProps &
+  (LinkProps | NoLinkProps);
+
+const rootClassName = "purpur-pagination";
+
+export const Pagination = forwardRef(
+  (
+    {
+      ["data-testid"]: dataTestId = "purpur-pagination",
+      anchorTagElement = "a",
+      asLink,
+      availablePageSizes = [10, 25, 50, 75],
+      className,
+      currentPage = 1,
+      hrefGetter,
+      navigationFunction,
+      nextButtonText,
+      onPageChange,
+      outOfLabel,
+      pageSelectorAutocompleteId,
+      pageSelectorListBoxLabel,
+      pageSelectorNoOptionsText,
+      pageSize = 10,
+      pageSizeLabel,
+      previousButtonText,
+      totalItems,
+      ...props
+    }: PaginationProps,
+    ref: ForwardedRef<HTMLDivElement>
+  ) => {
+    const classes = cx([className, rootClassName]);
+    const [_pageSize, _setPageSize] = React.useState(pageSize);
+    const { pages, numberOfPages } = usePaginationPages(totalItems, _pageSize, currentPage);
+
+    const _onPageChange = (page: number): void => {
+      onPageChange?.({ currentPage: page, pageSize });
+    };
+
+    const _hrefGetter = (page: number): string => {
+      return hrefGetter?.({ page, pageSize }) ?? "";
+    };
+
+    const _onPageSizeChange = (newPageSize: number): void => {
+      _setPageSize(newPageSize);
+      onPageChange?.({ currentPage: 1, pageSize: newPageSize });
+    };
+
+    const _navigationFunction = (page: number, url: string): void => {
+      if (navigationFunction) {
+        navigationFunction({ currentPage: page, pageSize: _pageSize, url });
+      } else {
+        navigateToPage(url);
+      }
+    };
+
+    const linkProps = asLink
+      ? { asLink: true as const, hrefGetter: _hrefGetter }
+      : {
+          asLink: undefined as never,
+          hrefGetter: undefined as never,
+        };
+
+    const ContainerTag = asLink ? "nav" : "div";
+
+    return (
+      <ContainerTag className={classes} data-testid={dataTestId} ref={ref} {...props}>
+        <div className={cx(`${rootClassName}__page-size-select-container`)}>
+          <PaginationPageSizeSelector
+            {...(asLink
+              ? { asLink: true, hrefGetter, navigationFunction }
+              : { asLink: undefined as never, hrefGetter: undefined as never })}
+            availablePageSizes={availablePageSizes}
+            className={cx(`${rootClassName}__page-size-selector`)}
+            data-testid={`${dataTestId}-page-size-selector`}
+            onPageSizeChange={_onPageSizeChange}
+            pageSize={_pageSize}
+            pageSizeLabel={pageSizeLabel}
+          />
+        </div>
+        <div className={cx(`${rootClassName}__pagination-container`)}>
+          <PaginationStepTrigger
+            {...linkProps}
+            anchorTagElement={anchorTagElement}
+            className={cx(`${rootClassName}__step-trigger`)}
+            data-testid={`${dataTestId}-previous-step-trigger`}
+            disabled={currentPage === 1}
+            onPageChange={_onPageChange}
+            pageToNavigateTo={currentPage - 1}
+          >
+            <IconArrowLeft size="sm" />
+            <span className={cx(`${rootClassName}__step-trigger-label`)}>{previousButtonText}</span>
+          </PaginationStepTrigger>
+          <div className={cx(`${rootClassName}__page-trigger-container`)}>
+            <PaginationPageSelector
+              {...linkProps}
+              className={cx([
+                `${rootClassName}__page-selector`,
+                { [`${rootClassName}__page-selector--visible`]: pages.length > 3 },
+              ])}
+              currentPage={currentPage}
+              data-testid={`${dataTestId}-page-selector`}
+              navigationFunction={_navigationFunction}
+              numberOfPages={numberOfPages}
+              onPageChange={_onPageChange}
+              outOfLabel={outOfLabel}
+              pageSelectorAutocompleteId={pageSelectorAutocompleteId}
+              pageSelectorListBoxLabel={pageSelectorListBoxLabel}
+              pageSelectorNoOptionsText={pageSelectorNoOptionsText}
+            />
+            <PaginationPages
+              {...linkProps}
+              anchorTagElement={anchorTagElement}
+              className={cx([
+                `${rootClassName}__pages`,
+                { [`${rootClassName}__pages--visible`]: pages.length <= 3 },
+              ])}
+              currentPage={currentPage}
+              data-testid={`${dataTestId}-pages`}
+              onPageChange={_onPageChange}
+              pages={pages}
+            />
+          </div>
+          <PaginationStepTrigger
+            {...linkProps}
+            anchorTagElement={anchorTagElement}
+            className={cx(`${rootClassName}__step-trigger`)}
+            data-testid={`${dataTestId}-next-step-trigger`}
+            disabled={currentPage === numberOfPages}
+            onPageChange={_onPageChange}
+            pageToNavigateTo={currentPage + 1}
+          >
+            <span className={cx(`${rootClassName}__step-trigger-label`)}>{nextButtonText}</span>
+            <IconArrowRight size="sm" />
+          </PaginationStepTrigger>
+        </div>
+      </ContainerTag>
+    );
+  }
+);
+
+Pagination.displayName = "Pagination";

package/src/types.ts

@@ -0,0 +1,43 @@
+export type PaginationInformation = {
+  pageSize: number;
+  currentPage: number;
+};
+
+export type NavigationInformation = PaginationInformation & {
+  url: string;
+};
+
+export type HrefInformation = {
+  pageSize: number;
+  page: number;
+};
+
+export type LinkProps = {
+  anchorTagElement?: Link;
+  asLink: true;
+  hrefGetter: (hrefInformation: HrefInformation) => string;
+  navigationFunction?: (navigationInformation: NavigationInformation) => void;
+  onPageChange?: (paginationChangeInformation: PaginationInformation) => void;
+};
+
+export type NoLinkProps = {
+  anchorTagElement?: never;
+  asLink?: never;
+  hrefGetter?: never;
+  navigationFunction?: never;
+  onPageChange: (paginationChangeInformation: PaginationInformation) => void;
+};
+
+export type InternalLinkProps = {
+  asLink: true;
+  hrefGetter: (page: number) => string;
+};
+
+export type InternalNoLinkProps = {
+  asLink?: never;
+  hrefGetter?: never;
+};
+
+export type Link =
+  | React.ForwardRefExoticComponent<React.AnchorHTMLAttributes<HTMLAnchorElement>>
+  | "a";

package/src/use-page-options.hook.ts

@@ -0,0 +1,21 @@
+import { useMemo } from "react";
+import { Option } from "@purpurds/autocomplete";
+
+type UsePageOptionsHook = {
+  options: Option[];
+};
+
+export const usePageOptions = (numberOfPages: number): UsePageOptionsHook => {
+  const options = useMemo(
+    () =>
+      Array.from({ length: numberOfPages }, (_, i) => ({
+        id: `${i + 1}`,
+        label: `${i + 1}`,
+      })),
+    [numberOfPages]
+  );
+
+  return {
+    options,
+  };
+};

package/src/use-page-size-options.hook.ts

@@ -0,0 +1,21 @@
+import { useMemo } from "react";
+import { SelectOption } from "@purpurds/select";
+
+type UsePageSizeOptionsHook = {
+  options: SelectOption[];
+};
+
+export const usePageSizeOptions = (availablePageSizes: number[]): UsePageSizeOptionsHook => {
+  const options = useMemo(
+    () =>
+      availablePageSizes.map((pageSize: number) => ({
+        label: `${pageSize}`,
+        value: `${pageSize}`,
+      })),
+    [availablePageSizes]
+  );
+
+  return {
+    options,
+  };
+};