@sproutsocial/seeds-react-pagination 0.1.28 → 0.1.31

package/src/__tests__/Pagination.test.tsx

@@ -0,0 +1,164 @@
+import {
+  render,
+  screen,
+  fireEvent,
+} from "@sproutsocial/seeds-react-testing-library";
+import { Pagination } from "../Pagination";
+import { PAGE_SIZE_OPTIONS } from "../PaginationTypes";
+import type { TypePaginationConfig } from "../PaginationTypes";
+
+const tableCountFunction: TypePaginationConfig["tableCountFunction"] = ({
+  startNum,
+  endNum,
+  totalRowCount,
+}) => `${startNum}-${endNum} of ${totalRowCount}`;
+
+const baseConfig: TypePaginationConfig = {
+  initialPageSize: 10,
+  tableCountFunction,
+};
+
+describe("Pagination", () => {
+  it("is a named component definition (not a bare re-export) so react-docgen can extract its props", () => {
+    // The public entry must contain an actual component definition rather than a
+    // pure `export { ... } from "./PaginationHybrid"` re-export. The Publish
+    // pipeline runs `react-docgen --failOnWarning` over Pagination.tsx, which
+    // errors with "No suitable component definition found" when the file only
+    // re-exports the hybrid. A self-named component with a displayName gives
+    // react-docgen a definition to analyze.
+    expect(typeof Pagination).toBe("function");
+    expect(Pagination.displayName).toBe("Pagination");
+  });
+
+  it("renders nothing when there is a single page and no page size options", () => {
+    const { container } = render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={0}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders the count text and page-number controls for a multi-page config", () => {
+    render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    expect(screen.getByText("1-10 of 100")).toBeInTheDocument();
+    expect(screen.getByLabelText("Page 2")).toBeInTheDocument();
+    expect(screen.getByLabelText("Previous page")).toBeInTheDocument();
+    expect(screen.getByLabelText("Next page")).toBeInTheDocument();
+  });
+
+  it("calls onPageChange with the 0-based index when a page button is clicked", () => {
+    const onPageChange = jest.fn();
+    render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={onPageChange}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    fireEvent.click(screen.getByLabelText("Page 2"));
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
+  it("marks the current page button as disabled with aria-current='page'", () => {
+    render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    const currentPage = screen.getByLabelText("Page 1");
+    expect(currentPage).toBeDisabled();
+    expect(currentPage).toHaveAttribute("aria-current", "page");
+  });
+
+  it("disables Previous on the first page and Next on the last page", () => {
+    const { rerender } = render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    expect(screen.getByLabelText("Previous page")).toBeDisabled();
+    expect(screen.getByLabelText("Next page")).not.toBeDisabled();
+
+    rerender(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={9}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+      />
+    );
+    expect(screen.getByLabelText("Previous page")).not.toBeDisabled();
+    expect(screen.getByLabelText("Next page")).toBeDisabled();
+  });
+
+  it("forwards an optional className onto the root container so consumers can apply utility overrides", () => {
+    const { container } = render(
+      <Pagination
+        paginationConfig={baseConfig}
+        currentPageIndex={0}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={jest.fn()}
+        onPageSizeChange={jest.fn()}
+        className="test-utility"
+      />
+    );
+    expect(container.firstChild).toHaveClass("test-utility");
+    // The base component class must remain so the override composes rather than replaces.
+    expect(container.firstChild).toHaveClass("seeds-pagination-container");
+  });
+
+  it("calls onPageSizeChange and resets to the first page when the page size changes", () => {
+    const onPageChange = jest.fn();
+    const onPageSizeChange = jest.fn();
+    render(
+      <Pagination
+        paginationConfig={{
+          ...baseConfig,
+          displayType: "dropdown",
+          pageSizeOptions: PAGE_SIZE_OPTIONS.STANDARD,
+        }}
+        currentPageIndex={2}
+        pageSize={10}
+        totalRows={100}
+        onPageChange={onPageChange}
+        onPageSizeChange={onPageSizeChange}
+      />
+    );
+    fireEvent.change(screen.getByLabelText("Rows per page"), {
+      target: { value: "25" },
+    });
+    expect(onPageSizeChange).toHaveBeenCalledWith(25);
+    expect(onPageChange).toHaveBeenCalledWith(0);
+  });
+});

package/src/__tests__/usePaginationModel.test.ts

@@ -0,0 +1,91 @@
+import type * as React from "react";
+import { usePaginationModel } from "../usePaginationModel";
+import type { PaginationProps, TypePaginationConfig } from "../PaginationTypes";
+
+const tableCountFunction: TypePaginationConfig["tableCountFunction"] = ({
+  startNum,
+  endNum,
+  totalRowCount,
+}) => `${startNum}-${endNum} of ${totalRowCount}`;
+
+const baseConfig: TypePaginationConfig = {
+  initialPageSize: 10,
+  tableCountFunction,
+};
+
+const buildProps = (
+  overrides: Partial<PaginationProps> = {}
+): PaginationProps => ({
+  paginationConfig: baseConfig,
+  currentPageIndex: 0,
+  pageSize: 10,
+  totalRows: 100,
+  onPageChange: jest.fn(),
+  onPageSizeChange: jest.fn(),
+  ...overrides,
+});
+
+describe("usePaginationModel", () => {
+  it("derives the page math (totalPages / currentPage / row range) for a multi-page config", () => {
+    const model = usePaginationModel(buildProps());
+    expect(model.totalPages).toBe(10);
+    expect(model.currentPage).toBe(1); // 0-based index -> 1-based display
+    expect(model.startRow).toBe(1);
+    expect(model.endRow).toBe(10);
+    expect(model.canGoPrevious).toBe(false);
+    expect(model.canGoNext).toBe(true);
+  });
+
+  it("reports startRow as 0 when there are no rows", () => {
+    const model = usePaginationModel(buildProps({ totalRows: 0 }));
+    expect(model.totalPages).toBe(0);
+    expect(model.startRow).toBe(0);
+    expect(model.endRow).toBe(0);
+  });
+
+  it("collapses the page-number list with ellipses for large page counts", () => {
+    // 20 pages, on the first page: first page, a window, ellipsis, last page.
+    const model = usePaginationModel(
+      buildProps({ totalRows: 200, currentPageIndex: 0 })
+    );
+    expect(model.pageNumbers).toEqual([1, 2, 3, 4, 5, 6, "...", 20]);
+  });
+
+  it("shows leading and trailing ellipses when the current page is in the middle", () => {
+    const model = usePaginationModel(
+      buildProps({ totalRows: 200, currentPageIndex: 9 }) // page 10 of 20
+    );
+    expect(model.pageNumbers).toEqual([1, "...", 9, 10, 11, 12, "...", 20]);
+  });
+
+  it("lists every page without ellipsis when the count is small", () => {
+    const model = usePaginationModel(
+      buildProps({ totalRows: 30, currentPageIndex: 0 }) // 3 pages
+    );
+    expect(model.pageNumbers).toEqual([1, 2, 3]);
+  });
+
+  it("handlePrevious / handleNext respect the boundary guards", () => {
+    const onPageChange = jest.fn();
+    const first = usePaginationModel(
+      buildProps({ currentPageIndex: 0, onPageChange })
+    );
+    first.handlePrevious(); // already on first page -> no-op
+    expect(onPageChange).not.toHaveBeenCalled();
+    first.handleNext();
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
+  it("handlePageSizeChange forwards the new size and resets to the first page", () => {
+    const onPageChange = jest.fn();
+    const onPageSizeChange = jest.fn();
+    const model = usePaginationModel(
+      buildProps({ onPageChange, onPageSizeChange })
+    );
+    model.handlePageSizeChange({
+      currentTarget: { value: "25" },
+    } as React.SyntheticEvent<HTMLSelectElement>);
+    expect(onPageSizeChange).toHaveBeenCalledWith(25);
+    expect(onPageChange).toHaveBeenCalledWith(0);
+  });
+});

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/pagination.css

@@ -0,0 +1,99 @@
+/**
+ * Seeds Pagination component classes
+ * Use these instead of writing out individual Tailwind utility classes.
+ *
+ * Requires @sproutsocial/seeds-react-theme/dist/theme-all.css imported for
+ * CSS variable definitions and dark mode support.
+ *
+ * Rules are wrapped in @layer components so consumer Tailwind utilities (which
+ * live in @layer utilities) win the cascade. Without this layer the unlayered
+ * component CSS would beat utilities like mx-200 / p-300 / inline-flex and they
+ * could not override component styling. Keep every rule inside this single block
+ * in source order — the -selected modifier and the :disabled overrides resolve
+ * by source order within the same layer.
+ */
+
+@layer components {
+  /* StyledPaginationContainer */
+  .seeds-pagination-container {
+    font-size: var(--font-size-200);
+    line-height: var(--line-height-200);
+    display: flex;
+    align-items: center;
+    gap: var(--space-300);
+    margin-top: var(--space-400);
+    flex-wrap: wrap;
+  }
+
+  /* StyledPaginationInfo (styled(Text)) */
+  .seeds-pagination-info {
+    white-space: nowrap;
+  }
+
+  /* StyledPageSizeSelector */
+  .seeds-pagination-page-size-selector {
+    display: flex;
+    align-items: center;
+    gap: var(--space-300);
+  }
+
+  /* StyledPaginationControls */
+  .seeds-pagination-controls {
+    display: flex;
+    align-items: center;
+    margin-left: auto;
+  }
+
+  /* StyledPageButtons */
+  .seeds-pagination-page-buttons {
+    display: inline-flex;
+    flex-flow: row wrap;
+    background-clip: padding-box;
+    border: 1px solid var(--color-button-secondary-border-base);
+    border-radius: var(--radius-outer);
+    padding: var(--space-100);
+    background: transparent;
+  }
+
+  /* StyledPaginationButton — base */
+  .seeds-pagination-button {
+    min-width: calc(var(--space-500) + 4px);
+    min-height: calc(var(--space-500) + 2px);
+    padding: calc(var(--space-350) - 6px);
+    line-height: var(--space-400);
+    font-weight: var(--font-weight-semibold);
+    background-color: transparent;
+    color: var(--color-text-body);
+    border: none;
+    border-radius: var(--radius-inner);
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  /* selected modifier MUST follow base (equal specificity — source order wins) */
+  .seeds-pagination-button-selected {
+    background-color: var(--color-button-secondary-bg-active);
+    color: var(--color-text-inverse);
+  }
+
+  .seeds-pagination-button:hover:not(:disabled) {
+    background-color: var(--color-listItem-bg-hover);
+  }
+
+  .seeds-pagination-button-selected:hover:not(:disabled) {
+    background-color: var(--color-button-secondary-bg-active);
+    color: var(--color-text-inverse);
+  }
+
+  .seeds-pagination-button:disabled {
+    cursor: default;
+    opacity: 0.5;
+  }
+
+  /* current page renders disabled + selected and must stay fully opaque */
+  .seeds-pagination-button-selected:disabled {
+    opacity: 1;
+  }
+}

package/src/usePaginationModel.ts

@@ -0,0 +1,124 @@
+/**
+ * Presentation-agnostic Pagination model: page math, the page-number token
+ * list, and the event handlers consumed identically by PaginationTailwind and
+ * PaginationStyled. Contains NO rendering — the JSX and the `return null` guard
+ * stay in each component — so the two implementations cannot drift apart. Call
+ * it unconditionally at the top of each component, before any early return.
+ */
+
+import * as React from "react";
+import type { PaginationProps } from "./PaginationTypes";
+
+export const usePaginationModel = ({
+  paginationConfig,
+  currentPageIndex,
+  pageSize,
+  totalRows,
+  onPageChange,
+  onPageSizeChange,
+}: PaginationProps) => {
+  const { displayType, pageSizeOptions, tableCountFunction } = paginationConfig;
+
+  // Calculate pagination values
+  const totalPages = Math.ceil(totalRows / pageSize);
+  const currentPage = currentPageIndex + 1; // Convert 0-based to 1-based for display
+  const startRow = totalRows === 0 ? 0 : currentPageIndex * pageSize + 1;
+  const endRow = Math.min((currentPageIndex + 1) * pageSize, totalRows);
+
+  const canGoPrevious = currentPageIndex > 0;
+  const canGoNext = currentPageIndex < totalPages - 1;
+
+  const handlePrevious = () => {
+    if (canGoPrevious) {
+      onPageChange(currentPageIndex - 1);
+    }
+  };
+
+  const handleNext = () => {
+    if (canGoNext) {
+      onPageChange(currentPageIndex + 1);
+    }
+  };
+
+  const handlePageSizeChange = (e: React.SyntheticEvent<HTMLSelectElement>) => {
+    const newPageSize = Number(e.currentTarget.value);
+    onPageSizeChange(newPageSize);
+    // Reset to first page when page size changes
+    onPageChange(0);
+  };
+
+  // Generate page number buttons using web-app-core's algorithm
+  const getPageNumbers = () => {
+    const pages: (number | string)[] = [];
+    const size = paginationConfig.size || "default";
+
+    // Configuration for how many pages to show around current page
+    const NUM_PAGE_LOWER = size === "mini" ? 0 : 1;
+    const NUM_PAGE_UPPER = size === "mini" ? 0 : 2;
+
+    // If number of pages is small enough, show all the page tokens without ellipsis
+    if (totalPages <= 5 + NUM_PAGE_LOWER + NUM_PAGE_UPPER) {
+      for (let i = 1; i <= totalPages; i++) {
+        pages.push(i);
+      }
+    } else {
+      // Add first page
+      pages.push(1);
+
+      // Add ellipsis at the beginning if needed
+      if (currentPage > 3 + NUM_PAGE_LOWER) {
+        pages.push("...");
+      }
+
+      // Add pages in the middle
+      let start: number;
+      let end: number; // inclusive index
+
+      // If near beginning - Show number of pages before ending ellipsis
+      if (currentPage <= 3 + NUM_PAGE_LOWER) {
+        start = 2;
+        end = 3 + NUM_PAGE_LOWER + NUM_PAGE_UPPER;
+      } else if (currentPage > totalPages - (3 + NUM_PAGE_UPPER)) {
+        // If near end - Show number of pages after starting ellipsis
+        start = totalPages - (2 + NUM_PAGE_LOWER + NUM_PAGE_UPPER);
+        end = totalPages - 1;
+      } else {
+        // If in the middle - Show number of pages between two ellipses
+        start = currentPage - NUM_PAGE_LOWER;
+        end = currentPage + NUM_PAGE_UPPER;
+      }
+
+      for (let i = start; i <= end; i++) {
+        pages.push(i);
+      }
+
+      // Add a final ellipsis if necessary
+      if (currentPage < totalPages - (2 + NUM_PAGE_UPPER)) {
+        pages.push("...");
+      }
+
+      // Add the last page number
+      pages.push(totalPages);
+    }
+
+    return pages;
+  };
+
+  const pageNumbers = getPageNumbers();
+
+  return {
+    displayType,
+    pageSizeOptions,
+    tableCountFunction,
+    totalPages,
+    currentPage,
+    startRow,
+    endRow,
+    canGoPrevious,
+    canGoNext,
+    handlePrevious,
+    handleNext,
+    handlePageSizeChange,
+    pageNumbers,
+  };
+};