@primitiv-ui/react 0.1.28 → 0.1.30

package/src/usePagination/__tests__/usePagination.page-count.test.tsx

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { usePagination } from "../usePagination.ts";
+import type { UsePaginationOptions } from "../usePagination.ts";
+
+function PageCountProbe(options: UsePaginationOptions) {
+  const { page, pageCount } = usePagination(options);
+  return (
+    <span data-testid="result">
+      {page}/{pageCount}
+    </span>
+  );
+}
+
+describe("usePagination page count", () => {
+  it("should derive pageCount by dividing totalItems by pageSize", () => {
+    render(<PageCountProbe totalItems={200} pageSize={10} />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/20");
+  });
+
+  it("should round a partial last page up so its items stay reachable", () => {
+    render(<PageCountProbe totalItems={237} pageSize={10} />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/24");
+  });
+
+  it("should take pageCount directly when the consumer supplies it", () => {
+    render(<PageCountProbe pageCount={7} />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/7");
+  });
+
+  it("should fall back to one page when given no sizing information at all", () => {
+    // Neither an explicit pageCount nor a totalItems/pageSize pair — there is
+    // nothing to derive a count from, so the range collapses to a single page
+    // rather than reporting 0 (which `page` could never sit inside).
+    render(<PageCountProbe />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/1");
+  });
+
+  it("should fall back to one page when only half the sizing pair is given", () => {
+    render(<PageCountProbe totalItems={200} />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/1");
+  });
+
+  it("should report a single empty page when there are no items at all", () => {
+    // A range has to have somewhere to stand: reporting 0 pages would make
+    // `page` (1-based) immediately out of range for every consumer.
+    render(<PageCountProbe totalItems={0} pageSize={10} />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("1/1");
+  });
+});

package/src/usePagination/__tests__/usePagination.page-state.test.tsx

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { usePagination } from "../usePagination.ts";
+import type { UsePaginationOptions } from "../usePagination.ts";
+
+function PageStateProbe(options: UsePaginationOptions & { goTo?: number }) {
+  const { goTo, ...rest } = options;
+  const { page, setPage } = usePagination(rest);
+  return (
+    <>
+      <span data-testid="page">{page}</span>
+      <button type="button" onClick={() => setPage(goTo ?? 1)}>
+        go
+      </button>
+    </>
+  );
+}
+
+describe("usePagination page state", () => {
+  it("should start on page 1 when no default is given", () => {
+    render(<PageStateProbe pageCount={10} />);
+
+    expect(screen.getByTestId("page")).toHaveTextContent("1");
+  });
+
+  it("should start on defaultPage when uncontrolled", () => {
+    render(<PageStateProbe pageCount={10} defaultPage={4} />);
+
+    expect(screen.getByTestId("page")).toHaveTextContent("4");
+  });
+
+  it("should move to the requested page", async () => {
+    const user = userEvent.setup();
+    render(<PageStateProbe pageCount={10} goTo={6} />);
+
+    await user.click(screen.getByRole("button", { name: "go" }));
+
+    expect(screen.getByTestId("page")).toHaveTextContent("6");
+  });
+
+  it("should clamp a request above the last page down to the last page", async () => {
+    const user = userEvent.setup();
+    render(<PageStateProbe pageCount={10} goTo={99} />);
+
+    await user.click(screen.getByRole("button", { name: "go" }));
+
+    expect(screen.getByTestId("page")).toHaveTextContent("10");
+  });
+
+  it("should clamp a request below the first page up to page 1", async () => {
+    const user = userEvent.setup();
+    render(<PageStateProbe pageCount={10} defaultPage={5} goTo={0} />);
+
+    await user.click(screen.getByRole("button", { name: "go" }));
+
+    expect(screen.getByTestId("page")).toHaveTextContent("1");
+  });
+
+  it("should clamp an out-of-range defaultPage", () => {
+    // A page index restored from a URL or localStorage can easily outlive the
+    // data it pointed at.
+    render(<PageStateProbe pageCount={10} defaultPage={999} />);
+
+    expect(screen.getByTestId("page")).toHaveTextContent("10");
+  });
+
+  it("should notify onPageChange with the clamped page, not the raw request", async () => {
+    const onPageChange = vi.fn();
+    const user = userEvent.setup();
+    render(<PageStateProbe pageCount={10} goTo={99} onPageChange={onPageChange} />);
+
+    await user.click(screen.getByRole("button", { name: "go" }));
+
+    expect(onPageChange).toHaveBeenCalledWith(10);
+  });
+
+  it("should not notify onPageChange when the page has not actually changed", async () => {
+    const onPageChange = vi.fn();
+    const user = userEvent.setup();
+    render(<PageStateProbe pageCount={10} defaultPage={3} goTo={3} onPageChange={onPageChange} />);
+
+    await user.click(screen.getByRole("button", { name: "go" }));
+
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+});

package/src/usePagination/__tests__/usePagination.range.test.tsx

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { paginationRange } from "../usePagination.ts";
+
+/** Render a range compactly: pages as numbers, gaps as the pages they hide. */
+function shape(items: ReturnType<typeof paginationRange>): string {
+  return items
+    .map((item) => (item.type === "page" ? String(item.page) : `[${item.pages.join(",")}]`))
+    .join(" ");
+}
+
+describe("paginationRange", () => {
+  it("should list every page when the window is wide enough to cover the range", () => {
+    // Note the defaults do NOT show all 5: siblingCount 1 + boundaryCount 1
+    // leaves {1,2,5} visible, collapsing [3,4]. Covering a 5-page range takes a
+    // wider window — asserted below so the default's tighter shape is a
+    // deliberate, visible choice rather than an accident.
+    expect(shape(paginationRange(3, 5, { window: "sliding", siblingCount: 2 }))).toBe("1 2 3 4 5");
+  });
+
+  it("should collapse even a short range at the default window", () => {
+    expect(shape(paginationRange(1, 5, { window: "sliding" }))).toBe("1 2 [3,4] 5");
+  });
+
+  it("should collapse the tail when the current page is near the start", () => {
+    expect(shape(paginationRange(2, 10, { window: "sliding" }))).toBe("1 2 3 [4,5,6,7,8,9] 10");
+  });
+
+  it("should collapse the head when the current page is near the end", () => {
+    expect(shape(paginationRange(9, 10, { window: "sliding" }))).toBe("1 [2,3,4,5,6,7] 8 9 10");
+  });
+
+  it("should collapse both ends when the current page is mid-range", () => {
+    const items = paginationRange(50, 100, { window: "sliding" });
+
+    expect(items.map((i) => i.type)).toEqual([
+      "page", // 1
+      "gap", // 2-48
+      "page", // 49
+      "page", // 50 (current)
+      "page", // 51
+      "gap", // 52-99
+      "page", // 100
+    ]);
+  });
+
+  it("should hide exactly the pages between the two shown either side of a gap", () => {
+    const items = paginationRange(50, 100, { window: "sliding" });
+    const [leading] = items.filter((i) => i.type === "gap");
+
+    // The gap must be contiguous and abut its neighbours — an off-by-one here
+    // would silently drop a page from the menu, unreachable anywhere.
+    expect(leading).toEqual({
+      type: "gap",
+      pages: Array.from({ length: 47 }, (_, i) => i + 2),
+    });
+  });
+
+  it("should show a lone hidden page instead of collapsing it", () => {
+    // Hiding one number behind a menu costs a click and saves no width — the
+    // ellipsis cell is the same square as the number it would replace.
+    expect(shape(paginationRange(1, 5, { window: "sliding", siblingCount: 1, boundaryCount: 2 }))).toBe("1 2 3 4 5");
+  });
+
+  it("should widen the window around the current page with siblingCount", () => {
+    expect(shape(paginationRange(50, 100, { window: "sliding", siblingCount: 2 }))).toContain("48 49 50 51 52");
+  });
+
+  it("should pin more pages at each end with boundaryCount", () => {
+    const items = shape(paginationRange(50, 100, { window: "sliding", siblingCount: 1, boundaryCount: 2 }));
+
+    expect(items.startsWith("1 2 ")).toBe(true);
+    expect(items.endsWith(" 99 100")).toBe(true);
+  });
+
+  it("should handle a single page without emitting a gap", () => {
+    expect(shape(paginationRange(1, 1, { window: "sliding" }))).toBe("1");
+  });
+
+  it("should not emit pages beyond the range when the count is tiny", () => {
+    expect(shape(paginationRange(1, 2, { window: "sliding", siblingCount: 3, boundaryCount: 3 }))).toBe("1 2");
+  });
+});

package/src/usePagination/__tests__/usePagination.slice.test.tsx

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { usePagination } from "../usePagination.ts";
+import type { UsePaginationOptions } from "../usePagination.ts";
+
+function SliceProbe(options: UsePaginationOptions) {
+  const { startIndex, endIndex } = usePagination(options);
+  return (
+    <span data-testid="slice">
+      {startIndex}..{endIndex}
+    </span>
+  );
+}
+
+describe("usePagination slice bounds", () => {
+  it("should give a zero-based half-open range for the first page", () => {
+    // Half-open so it drops straight into Array.slice and into a
+    // LIMIT/OFFSET query without an off-by-one at the call site.
+    render(<SliceProbe totalItems={200} pageSize={10} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("0..10");
+  });
+
+  it("should offset the range by the current page", () => {
+    render(<SliceProbe totalItems={200} pageSize={10} defaultPage={3} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("20..30");
+  });
+
+  it("should stop the last page's range at the item count, not the page size", () => {
+    // 237 items at 10/page: the last page holds 7, so endIndex must not run
+    // past the data.
+    render(<SliceProbe totalItems={237} pageSize={10} defaultPage={24} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("230..237");
+  });
+
+  it("should collapse to an empty range when there are no items", () => {
+    render(<SliceProbe totalItems={0} pageSize={10} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("0..0");
+  });
+
+  it("should not clamp the range when the total is unknown", () => {
+    // A server that reports pageCount but not an exact total is common. With
+    // no total to clamp against, the range is just a full page wide.
+    render(<SliceProbe pageCount={10} pageSize={10} defaultPage={3} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("20..30");
+  });
+
+  it("should report an empty range when the page size is unknown", () => {
+    // pageCount given directly — the hook has no idea how big a page is, so it
+    // cannot invent slice bounds.
+    render(<SliceProbe pageCount={10} defaultPage={3} />);
+
+    expect(screen.getByTestId("slice")).toHaveTextContent("0..0");
+  });
+});

package/src/usePagination/__tests__/usePagination.windowing.test.tsx

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { paginationRange } from "../usePagination.ts";
+
+function shape(items: ReturnType<typeof paginationRange>): string {
+  return items
+    .map((item) => (item.type === "page" ? String(item.page) : `[${item.pages.join(",")}]`))
+    .join(" ");
+}
+
+describe("paginationRange paged windowing", () => {
+  it("should hold the same block of pages steady while the current page moves within it", () => {
+    // The whole point: stepping 6 -> 7 -> 8 must not re-label a single cell,
+    // only move which one is active. A sliding window re-renders the numbers
+    // under the reader's cursor on every step, which reads as a flash.
+    const at6 = shape(paginationRange(6, 20, { window: "paged", blockSize: 5 }));
+    const at7 = shape(paginationRange(7, 20, { window: "paged", blockSize: 5 }));
+    const at8 = shape(paginationRange(8, 20, { window: "paged", blockSize: 5 }));
+
+    expect(at7).toBe(at6);
+    expect(at8).toBe(at6);
+  });
+
+  it("should show the block containing the current page, plus the boundaries", () => {
+    expect(shape(paginationRange(7, 20, { window: "paged", blockSize: 5 }))).toBe(
+      "1 [2,3,4,5] 6 7 8 9 10 [11,...,19] 20".replace(
+        "11,...,19",
+        "11,12,13,14,15,16,17,18,19",
+      ),
+    );
+  });
+
+  it("should advance to the next block when stepping past the block's last page", () => {
+    const atLast = shape(paginationRange(10, 20, { window: "paged", blockSize: 5 }));
+    const atNext = shape(paginationRange(11, 20, { window: "paged", blockSize: 5 }));
+
+    expect(atLast).toContain("6 7 8 9 10");
+    expect(atNext).toContain("11 12 13 14 15");
+    expect(atNext).not.toBe(atLast);
+  });
+
+  it("should fall back to the previous block when stepping before the block's first page", () => {
+    const atFirst = shape(paginationRange(6, 20, { window: "paged", blockSize: 5 }));
+    const atPrevious = shape(paginationRange(5, 20, { window: "paged", blockSize: 5 }));
+
+    expect(atFirst).toContain("6 7 8 9 10");
+    expect(atPrevious).toContain("1 2 3 4 5");
+  });
+
+  it("should not run the final block past the last page", () => {
+    // 20 pages at blockSize 5 divides evenly; 22 does not, so the last block
+    // holds only 21 and 22.
+    expect(shape(paginationRange(21, 22, { window: "paged", blockSize: 5 }))).toContain("21 22");
+    expect(shape(paginationRange(21, 22, { window: "paged", blockSize: 5 }))).not.toContain("23");
+  });
+
+  it("should still collapse a lone hidden page into a plain page", () => {
+    // Block 2-6 with boundary 1: nothing hidden at the head, so no gap.
+    expect(shape(paginationRange(3, 12, { window: "paged", blockSize: 5 }))).toBe(
+      "1 2 3 4 5 [6,7,8,9,10,11] 12",
+    );
+  });
+
+  it("should keep sliding behaviour available for consumers who prefer it", () => {
+    expect(shape(paginationRange(7, 20, { window: "sliding" }))).toBe(
+      "1 [2,3,4,5] 6 7 8 [9,...,19] 20".replace("9,...,19", "9,10,11,12,13,14,15,16,17,18,19"),
+    );
+  });
+});

package/src/usePagination/index.ts

@@ -0,0 +1 @@
+export * from "./usePagination.ts";

package/src/usePagination/usePagination.ts

@@ -0,0 +1,292 @@
+import { useCallback, useMemo } from "react";
+import { useControllableState } from "../hooks/useControllableState.ts";
+
+/** One entry in a rendered page range: either a page, or a collapsed run. */
+export type PaginationRangeItem =
+  | { type: "page"; page: number }
+  | { type: "gap"; pages: number[] };
+
+/**
+ * How the visible page window behaves as the current page moves.
+ *
+ * - **paged** — the window holds a fixed block of pages and only advances when
+ *   the current page steps outside it. Within a block nothing re-labels; only
+ *   which cell is active changes. Stepping past the block's last page loads the
+ *   next block in one deliberate jump.
+ * - **sliding** — the window follows the current page continuously, keeping
+ *   `siblingCount` pages either side of it. The conventional behaviour, but the
+ *   numbers under the reader's cursor re-label on EVERY step, which reads as a
+ *   flash.
+ */
+export type PaginationWindow = "paged" | "sliding";
+
+/** Shape of the range — see {@link paginationRange}. */
+export type PaginationRangeOptions = {
+  /**
+   * Which windowing strategy to use.
+   * @default "paged"
+   */
+  window?: PaginationWindow;
+  /**
+   * `paged` only — how many pages a block holds.
+   * @default 5
+   */
+  blockSize?: number;
+  /**
+   * `sliding` only — pages shown either side of the current one.
+   * @default 1
+   */
+  siblingCount?: number;
+  /**
+   * Pages pinned at each end of the range, in both strategies.
+   * @default 1
+   */
+  boundaryCount?: number;
+};
+
+/**
+ * Work out which pages to show, and which to collapse behind an overflow menu.
+ *
+ * Pins `boundaryCount` pages at each end, adds the window around the current
+ * page (see {@link PaginationWindow}), then walks the sorted result and
+ * collapses each remaining run into a `gap` carrying the pages it hides, so a
+ * menu can offer them.
+ *
+ * A run of exactly ONE page is returned as that page instead: hiding a single
+ * number behind a menu costs the reader a click and saves no width, since the
+ * ellipsis cell is the same square as the number it would replace. Same
+ * reasoning as `breadcrumb-overflow`, which only truncates once there is more
+ * than one crumb to hide.
+ *
+ * Pure — exported separately from the hook so a consumer holding its own page
+ * state can still reuse the arithmetic.
+ *
+ * @example
+ * ```ts
+ * paginationRange(7, 20);
+ * // 1 [2,3,4,5] 6 7 8 9 10 [11...19] 20   — the 6-10 block, steady while you
+ * //                                       move within it
+ * ```
+ */
+export function paginationRange(
+  page: number,
+  pageCount: number,
+  options: PaginationRangeOptions = {},
+): PaginationRangeItem[] {
+  const { window = "paged", blockSize = 5, siblingCount = 1, boundaryCount = 1 } = options;
+
+  const visible = new Set<number>();
+  for (let i = 1; i <= Math.min(boundaryCount, pageCount); i++) visible.add(i);
+  for (let i = Math.max(1, pageCount - boundaryCount + 1); i <= pageCount; i++) visible.add(i);
+
+  if (window === "paged") {
+    // Which block the current page falls in. Because this is derived from the
+    // page rather than centred on it, every page in the block yields the same
+    // window — that is what stops the cells re-labelling as you step.
+    const blockStart = Math.floor((page - 1) / blockSize) * blockSize + 1;
+    const blockEnd = Math.min(blockStart + blockSize - 1, pageCount);
+    for (let i = blockStart; i <= blockEnd; i++) visible.add(i);
+  } else {
+    for (let i = Math.max(1, page - siblingCount); i <= Math.min(pageCount, page + siblingCount); i++) {
+      visible.add(i);
+    }
+  }
+
+  const sorted = [...visible].sort((a, b) => a - b);
+  const items: PaginationRangeItem[] = [];
+
+  sorted.forEach((current, i) => {
+    if (i > 0) {
+      const missing: number[] = [];
+      for (let p = sorted[i - 1] + 1; p < current; p++) missing.push(p);
+      if (missing.length === 1) items.push({ type: "page", page: missing[0] });
+      else if (missing.length > 1) items.push({ type: "gap", pages: missing });
+    }
+    items.push({ type: "page", page: current });
+  });
+
+  return items;
+}
+
+export type UsePaginationOptions = {
+  /**
+   * How many pages there are. Supply this directly when the page count comes
+   * from elsewhere (a server response, say); otherwise give `totalItems` and
+   * `pageSize` and let the hook derive it.
+   */
+  pageCount?: number;
+  /** Total number of items across every page. Pairs with `pageSize`. */
+  totalItems?: number;
+  /** How many items each page holds. Pairs with `totalItems`. */
+  pageSize?: number;
+  /**
+   * The current page, 1-based — supply this to drive the hook yourself
+   * (controlled). Leave it out to let the hook hold its own state.
+   */
+  page?: number;
+  /**
+   * Starting page when uncontrolled. Read once on mount.
+   * @default 1
+   */
+  defaultPage?: number;
+  /**
+   * Notified whenever the page changes, with the **clamped** page — never a
+   * raw out-of-range request. Not called when the page hasn't actually moved.
+   */
+  onPageChange?: (page: number) => void;
+  /**
+   * How the visible window behaves as the page moves. See
+   * {@link PaginationWindow} — `paged` holds a block steady, `sliding` follows
+   * the current page.
+   * @default "paged"
+   */
+  window?: PaginationWindow;
+  /**
+   * `paged` only — how many pages a block holds.
+   * @default 5
+   */
+  blockSize?: number;
+  /**
+   * `sliding` only — pages shown either side of the current one.
+   * @default 1
+   */
+  siblingCount?: number;
+  /**
+   * How many pages `items` pins at each end of the range.
+   * @default 1
+   */
+  boundaryCount?: number;
+};
+
+/**
+ * What {@link usePagination} hands back.
+ */
+export type UsePaginationResult = {
+  /** The current page, 1-based. Always within `1...pageCount`. */
+  page: number;
+  /** How many pages there are. Never less than 1. */
+  pageCount: number;
+  /** Go to a page. Out-of-range requests are clamped, not rejected. */
+  setPage: (page: number) => void;
+  /** Step forward one page. A no-op on the last page. */
+  next: () => void;
+  /** Step back one page. A no-op on the first page. */
+  previous: () => void;
+  /** Jump to page 1. */
+  first: () => void;
+  /** Jump to the last page. */
+  last: () => void;
+  /** Whether there is a page before this one — wire to a prev control's `disabled`. */
+  canPrevious: boolean;
+  /** Whether there is a page after this one — wire to a next control's `disabled`. */
+  canNext: boolean;
+  /**
+   * Zero-based index of this page's first item. Together with `endIndex` this
+   * is a **half-open** range, so it drops straight into `Array.slice(start,
+   * end)` or a LIMIT/OFFSET query with no off-by-one at the call site.
+   *
+   * Both are `0` when the hook has no `pageSize` to reason from.
+   */
+  startIndex: number;
+  /** Zero-based index one past this page's last item. Never exceeds `totalItems`. */
+  endIndex: number;
+  /**
+   * The range to render: each entry is either a page or a collapsed `gap`
+   * carrying the pages it hides. See {@link paginationRange}.
+   */
+  items: PaginationRangeItem[];
+};
+
+function clamp(page: number, pageCount: number): number {
+  return Math.min(Math.max(page, 1), pageCount);
+}
+
+/**
+ * Headless pagination state: the page arithmetic every paged surface needs,
+ * with no opinion about where the data comes from or how the row is rendered.
+ *
+ * @see https://primitiv-ui.dev/docs/hooks/use-pagination
+ */
+export function usePagination(options: UsePaginationOptions): UsePaginationResult {
+  const {
+    pageCount: explicitPageCount,
+    totalItems,
+    pageSize,
+    page: controlledPage,
+    defaultPage = 1,
+    onPageChange,
+    window = "paged",
+    blockSize = 5,
+    siblingCount = 1,
+    boundaryCount = 1,
+  } = options;
+
+  const derived =
+    explicitPageCount !== undefined
+      ? explicitPageCount
+      : totalItems !== undefined && pageSize !== undefined
+        ? Math.ceil(totalItems / pageSize)
+        : 1;
+
+  // A range needs somewhere to stand: with 0 pages, a 1-based `page` would be
+  // out of range the moment it is read.
+  const pageCount = Math.max(derived, 1);
+
+  const [rawPage, setRawPage] = useControllableState(controlledPage, defaultPage, onPageChange);
+
+  // Clamped on the way OUT as well as on the way in: `defaultPage` is read once
+  // on mount, and a controlled `page` comes straight from the consumer, so
+  // neither has passed through `setPage`. Both can outlive the data they
+  // pointed at (a page index restored from a URL, a list that shrank).
+  const page = clamp(rawPage, pageCount);
+
+  const setPage = useCallback(
+    (next: number) => {
+      const target = clamp(next, pageCount);
+      // useControllableState deliberately does not dedupe, so the guard lives
+      // here — a consumer re-selecting the page they are already on should not
+      // see a change notification.
+      if (target === page) return;
+      setRawPage(target);
+    },
+    [page, pageCount, setRawPage],
+  );
+
+  // Every mover goes through setPage, so clamping and the change guard are
+  // stated once — stepping past either end is a no-op rather than an error.
+  const next = useCallback(() => setPage(page + 1), [page, setPage]);
+  const previous = useCallback(() => setPage(page - 1), [page, setPage]);
+  const first = useCallback(() => setPage(1), [setPage]);
+  const last = useCallback(() => setPage(pageCount), [pageCount, setPage]);
+
+  // Only meaningful when the hook knows a page size. Given `pageCount` alone it
+  // cannot invent slice bounds, so it reports an empty range rather than a
+  // plausible-looking guess a consumer might slice with.
+  const canSlice = pageSize !== undefined;
+  const startIndex = canSlice ? (page - 1) * pageSize : 0;
+  const endIndex = canSlice
+    ? // Clamped to the real item count so the final, partial page's range stops
+      // at the data instead of a page-size multiple past it.
+      Math.min(startIndex + pageSize, totalItems ?? startIndex + pageSize)
+    : 0;
+
+  const items = useMemo(
+    () => paginationRange(page, pageCount, { window, blockSize, siblingCount, boundaryCount }),
+    [page, pageCount, window, blockSize, siblingCount, boundaryCount],
+  );
+
+  return {
+    page,
+    pageCount,
+    setPage,
+    items,
+    startIndex,
+    endIndex,
+    next,
+    previous,
+    first,
+    last,
+    canPrevious: page > 1,
+    canNext: page < pageCount,
+  };
+}

package/src/utils/focusable.ts

@@ -0,0 +1,15 @@
+/**
+ * Elements that can receive keyboard focus and take part in the natural tab
+ * order. Two consumers rely on it: moving initial focus into a surface when it
+ * opens (e.g. `Popover`), and locating the boundary elements of a focus trap
+ * (e.g. `Modal`). `[tabindex="-1"]` is excluded because such elements are only
+ * programmatically focusable, not tabbable.
+ */
+export const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");

package/src/utils/getKeyToActionMap.ts

@@ -44,7 +44,7 @@ type GetKeyToActionMapOptions = {
  * "activate") into its own movement / activation logic.
  *
  * Returns a plain `Record<string, RovingKeyAction>` so call sites can do
- * `const action = map[event.key]; if (action === "next") …`.
+ * `const action = map[event.key]; if (action === "next") ...`.
  *
  * @example Tabs trigger (horizontal, RTL, all features)
  * ```ts

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export { createStrictContext } from "./createStrictContext";
 export { deriveId } from "./deriveId";
+export { FOCUSABLE_SELECTOR } from "./focusable";
 export { getKeyToActionMap, type RovingKeyAction } from "./getKeyToActionMap";