@usefy/use-pagination 0.20.0

package/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-pagination</h1>
+
+<p align="center">
+  <strong>A headless pagination state machine — current page, page count, a slice-ready range, and an ellipsis-aware pager model</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-pagination"><img src="https://img.shields.io/npm/v/@usefy/use-pagination.svg?style=flat-square&color=007acc" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@usefy/use-pagination"><img src="https://img.shields.io/npm/dm/@usefy/use-pagination.svg?style=flat-square&color=007acc" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/@usefy/use-pagination"><img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-pagination?style=flat-square&color=007acc" alt="bundle size" /></a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@usefy/use-pagination.svg?style=flat-square&color=007acc" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-usepagination--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`usePagination` is part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It owns **pagination state** — nothing else — so you can render the pager however you like: a table footer, a numbered button row, a "load more" counter, an API cursor.
+
+From `total` and `pageSize` it derives the page count, keeps the current page clamped in range, hands you a **slice-ready index window** (`range`) for your data array, and builds the **ellipsis-aware page-number model** (`items`) you need for a `1 … 24 25 26 … 50` pager — the same model as MUI/Mantine's `usePagination`. The current page works in both **controlled** and **uncontrolled** modes, composing [`@usefy/use-controllable-state`](https://www.npmjs.com/package/@usefy/use-controllable-state).
+
+## Features
+
+- **Controlled & uncontrolled** — pass `page` + `onChange`, or let the hook own the page from `defaultPage`
+- **Slice-ready `range`** — a 0-based `{ start, end }` window (end **exclusive**, clamped to `total`) so `data.slice(start, end)` just works
+- **Ellipsis-aware `items`** — page numbers + `"ellipsis"` tokens driven by `siblingCount` / `boundaryCount`, each flagged `selected` for the current page
+- **Always in range** — the page is clamped into `[1, pageCount]`; when the dataset shrinks the current page follows it, no dangling out-of-range page
+- **No wasted renders** — `next`/`prev` at a bound and `setPage` to the current page are no-ops (no re-render, no `onChange`)
+- **Stable controls** — `setPage`/`next`/`prev`/`first`/`last` keep their identity across renders, safe as effect deps
+- **Robust guards** — non-positive `pageSize` is coerced to `1`, negative/`NaN` `total` to `0`, fractional pages floored
+- **TypeScript-first** — full type inference and exported types
+- **Tiny & tree-shakeable** — one tiny dependency, published as its own package
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-pagination
+
+# yarn
+yarn add @usefy/use-pagination
+
+# pnpm
+pnpm add @usefy/use-pagination
+```
+
+Requires React 18 or 19 (`peerDependencies: "react": "^18.0.0 || ^19.0.0"`).
+
+## Quick Start
+
+```tsx
+import { usePagination } from "@usefy/use-pagination";
+
+function UsersTable({ users }: { users: User[] }) {
+  const { page, pageCount, range, items, setPage, next, prev, canNext, canPrev } =
+    usePagination({ total: users.length, pageSize: 10 });
+
+  const visible = users.slice(range.start, range.end);
+
+  return (
+    <>
+      <ul>
+        {visible.map((u) => (
+          <li key={u.id}>{u.name}</li>
+        ))}
+      </ul>
+
+      <nav>
+        <button onClick={prev} disabled={!canPrev}>‹ Prev</button>
+        {items.map((item, i) =>
+          item.type === "ellipsis" ? (
+            <span key={`gap-${i}`}>…</span>
+          ) : (
+            <button
+              key={item.page}
+              aria-current={item.selected ? "page" : undefined}
+              onClick={() => setPage(item.page!)}
+            >
+              {item.page}
+            </button>
+          )
+        )}
+        <button onClick={next} disabled={!canNext}>Next ›</button>
+      </nav>
+
+      <p>Page {page} of {pageCount}</p>
+    </>
+  );
+}
+```
+
+## API
+
+```ts
+const pagination = usePagination(options);
+```
+
+### Options — `UsePaginationOptions`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `total` | `number` | — (required) | Total number of items across all pages. Values below `0` and non-finite values are treated as `0`; fractions are floored. |
+| `pageSize` | `number` | `10` | Items per page. Clamped to a minimum of `1`. |
+| `page` | `number` | `undefined` | **Controlled** current page (1-based). When provided, the returned `page` mirrors this prop (clamped) and the controls only call `onChange`. |
+| `defaultPage` | `number` | `1` | Initial page in **uncontrolled** mode. Ignored while controlled. |
+| `siblingCount` | `number` | `1` | Pages shown on each side of the current page in `items`. |
+| `boundaryCount` | `number` | `1` | Pages shown at the start and end in `items`. |
+| `onChange` | `(page: number) => void` | `undefined` | Called with the next page whenever the page changes. Its identity may change between renders freely. |
+
+### Returns — `UsePaginationReturn`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `page` | `number` | Current page, 1-based, always within `[1, pageCount]`. |
+| `pageCount` | `number` | Number of pages, always `>= 1` (an empty dataset still has one empty page). |
+| `pageSize` | `number` | The effective page size (clamped to `>= 1`). |
+| `setPage` | `(page: number) => void` | Go to a specific page. Argument is clamped and floored; going to the current page is a no-op. Stable identity. |
+| `next` | `() => void` | Go to the next page (no-op on the last). Stable identity. |
+| `prev` | `() => void` | Go to the previous page (no-op on the first). Stable identity. |
+| `first` | `() => void` | Go to the first page. Stable identity. |
+| `last` | `() => void` | Go to the last page. Stable identity. |
+| `canNext` | `boolean` | `true` when `page < pageCount`. |
+| `canPrev` | `boolean` | `true` when `page > 1`. |
+| `range` | `PaginationRange` | 0-based `{ start, end }` window of the current page — see below. |
+| `items` | `PaginationItem[]` | Ellipsis-aware pager model — see below. |
+
+### `range` — `PaginationRange`
+
+The 0-based index window for slicing your data array:
+
+- `start` — index of the first item on the current page (**inclusive**).
+- `end` — index **one past** the last item (**exclusive**), clamped to `total`.
+
+So `array.slice(range.start, range.end)` yields exactly the current page's items. For an empty dataset, `start === end === 0`.
+
+```ts
+// total: 25, pageSize: 10, page: 3  →  { start: 20, end: 25 }
+data.slice(20, 25); // the last 5 items
+```
+
+### `items` — `PaginationItem[]`
+
+The ordered model for rendering a pager, MUI/Mantine-style. Each entry is either a page button or an `"ellipsis"` gap:
+
+```ts
+interface PaginationItem {
+  type: "page" | "ellipsis";
+  page: number | null; // 1-based page for "page", null for "ellipsis"
+  selected: boolean; // true only for the current page
+}
+```
+
+`siblingCount` (pages around the current page) and `boundaryCount` (pages pinned at each end) control how the middle collapses. When a gap would hide exactly one page, that page is shown instead of an ellipsis:
+
+```ts
+// pageCount 50, page 25, siblingCount 1, boundaryCount 1:
+// [1, "ellipsis", 24, 25, 26, "ellipsis", 50]
+```
+
+The pure builder is also exported for non-React use:
+
+```ts
+import { buildPaginationRange, getPageCount } from "@usefy/use-pagination";
+
+getPageCount(95, 10); // 10
+buildPaginationRange({ page: 1, pageCount: 10 }); // [1, 2, 3, 4, 5, "ellipsis", 10]
+```
+
+### Behavior notes
+
+- **Clamping is derived.** The current page is clamped **presentationally** into `[1, pageCount]` — it is never written back into state, so shrinking `total` never fires a surprise `onChange`. In **controlled** mode this means a `page` prop that is out of range is displayed clamped but not corrected via `onChange`; pass a valid `page`. Any navigation interaction (`next`/`prev`/`setPage`) commits a fresh in-range value.
+- **No-op skipping.** Moving to the page you're already on — including `next`/`prev` at a bound — does not re-render or call `onChange`.
+- **SSR-safe.** Pure state and math; there is no `window`/`document` access, so it renders identically on the server and client.
+
+## Testing
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-pagination/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages) — **48 tests**, 100% statement coverage.
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.

package/dist/index.d.mts

@@ -0,0 +1,253 @@
+/**
+ * Options for the {@link usePagination} hook.
+ */
+interface UsePaginationOptions {
+    /**
+     * Total number of items across all pages. Values below `0` (and non-finite
+     * values) are treated as `0`. Fractional values are floored.
+     */
+    total: number;
+    /**
+     * Number of items per page.
+     *
+     * @defaultValue 10
+     * @remarks Clamped to a minimum of `1` — a page size of `0` or a negative
+     * value would make `pageCount` meaningless, so it is coerced to `1`.
+     */
+    pageSize?: number;
+    /**
+     * The **controlled** current page (1-based). When provided (not `undefined`),
+     * the hook runs in controlled mode: the returned `page` mirrors this prop
+     * (clamped into `[1, pageCount]`) and `setPage`/`next`/`prev`/… only call
+     * `onChange` — the parent owns the value.
+     *
+     * Pass `undefined` to run uncontrolled, seeded from {@link defaultPage}.
+     */
+    page?: number;
+    /**
+     * The initial current page (1-based) in **uncontrolled** mode. Ignored while
+     * controlled.
+     *
+     * @defaultValue 1
+     */
+    defaultPage?: number;
+    /**
+     * Number of always-visible page buttons on each side of the current page in
+     * the {@link UsePaginationReturn.items} model.
+     *
+     * @defaultValue 1
+     */
+    siblingCount?: number;
+    /**
+     * Number of always-visible page buttons at the start and end (the boundaries)
+     * in the {@link UsePaginationReturn.items} model.
+     *
+     * @defaultValue 1
+     */
+    boundaryCount?: number;
+    /**
+     * Called with the next page whenever the current page changes — via any of the
+     * navigation controls in uncontrolled mode, or when a control requests a
+     * *different* page in controlled mode. Its identity may change between renders
+     * without any effect on the hook (the latest callback is always used).
+     */
+    onChange?: (page: number) => void;
+}
+/**
+ * The kind of a {@link PaginationItem}: a real page button, or an `"ellipsis"`
+ * gap token used to collapse a long run of pages.
+ */
+type PaginationItemType = "page" | "ellipsis";
+/**
+ * A single entry in the ellipsis-aware page-number model
+ * ({@link UsePaginationReturn.items}) used to render a pager UI.
+ */
+interface PaginationItem {
+    /** Whether this entry is a clickable page or an `"ellipsis"` gap. */
+    type: PaginationItemType;
+    /**
+     * The 1-based page number for a `"page"` entry, or `null` for an `"ellipsis"`.
+     */
+    page: number | null;
+    /** `true` when this is the current page (always `false` for `"ellipsis"`). */
+    selected: boolean;
+}
+/**
+ * The 0-based index window of the current page, ready to slice an array with
+ * `array.slice(range.start, range.end)`.
+ */
+interface PaginationRange {
+    /** 0-based index of the first item on the current page (**inclusive**). */
+    readonly start: number;
+    /**
+     * 0-based index **one past** the last item on the current page
+     * (**exclusive**), clamped to `total`. `array.slice(start, end)` yields the
+     * current page's items. For an empty dataset, `start === end === 0`.
+     */
+    readonly end: number;
+}
+/**
+ * Return value of {@link usePagination}.
+ */
+interface UsePaginationReturn {
+    /** The current page, 1-based, always within `[1, pageCount]`. */
+    page: number;
+    /**
+     * Total number of pages, always `>= 1` (an empty dataset still has one empty
+     * page). Equals `Math.max(1, Math.ceil(total / pageSize))`.
+     */
+    pageCount: number;
+    /** The effective page size (clamped to a minimum of `1`). */
+    pageSize: number;
+    /**
+     * Go to a specific page. The argument is clamped into `[1, pageCount]` and
+     * floored; going to the page you are already on is a no-op (no re-render, no
+     * `onChange`). Stable identity.
+     */
+    setPage: (page: number) => void;
+    /** Go to the next page (no-op on the last page). Stable identity. */
+    next: () => void;
+    /** Go to the previous page (no-op on the first page). Stable identity. */
+    prev: () => void;
+    /** Go to the first page. Stable identity. */
+    first: () => void;
+    /** Go to the last page. Stable identity. */
+    last: () => void;
+    /** `true` when there is a next page (`page < pageCount`). */
+    canNext: boolean;
+    /** `true` when there is a previous page (`page > 1`). */
+    canPrev: boolean;
+    /**
+     * The 0-based index window of the current page for slicing your data array.
+     * See {@link PaginationRange}.
+     */
+    range: PaginationRange;
+    /**
+     * The ellipsis-aware ordered list of page buttons and gap tokens to render a
+     * pager UI, driven by `siblingCount`/`boundaryCount`. Read-only — it is a
+     * memoized derived model, so treat it as immutable. See {@link PaginationItem}.
+     */
+    items: readonly PaginationItem[];
+}
+
+/**
+ * A headless pagination state machine — the current page (controlled or
+ * uncontrolled), the derived page count, a slice-ready index range, and an
+ * ellipsis-aware page-number model for rendering a pager UI. It owns *state*
+ * only; you render however you like.
+ *
+ * The current page is always kept within `[1, pageCount]`: it is clamped
+ * **derived** from `total`/`pageSize`, so when the dataset shrinks the returned
+ * `page` never points past the last page and the navigation controls stay
+ * correct (a plain re-clamp, no surprise `onChange`). All controls
+ * (`setPage`/`next`/`prev`/`first`/`last`) have stable identities and skip
+ * no-op moves (staying on the current page does not re-render or fire
+ * `onChange`).
+ *
+ * Works in both modes, mirroring `useControllableState`:
+ * - **Uncontrolled** (`page` omitted): the hook owns the page, seeded from
+ *   `defaultPage`; `onChange` fires after each committed change.
+ * - **Controlled** (`page` provided): the returned `page` mirrors the prop
+ *   (clamped) and the controls only call `onChange` — the parent owns the value.
+ *
+ * @param options - See {@link UsePaginationOptions}.
+ * @returns The pagination state and controls — see {@link UsePaginationReturn}.
+ *
+ * @example
+ * ```tsx
+ * function UsersTable({ users }: { users: User[] }) {
+ *   const { page, pageCount, range, items, setPage, next, prev, canNext, canPrev } =
+ *     usePagination({ total: users.length, pageSize: 10 });
+ *
+ *   const visible = users.slice(range.start, range.end);
+ *
+ *   return (
+ *     <>
+ *       <ul>{visible.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
+ *       <nav>
+ *         <button onClick={prev} disabled={!canPrev}>Prev</button>
+ *         {items.map((item, i) =>
+ *           item.type === "ellipsis" ? (
+ *             <span key={`gap-${i}`}>…</span>
+ *           ) : (
+ *             <button
+ *               key={item.page}
+ *               aria-current={item.selected}
+ *               onClick={() => setPage(item.page!)}
+ *             >
+ *               {item.page}
+ *             </button>
+ *           )
+ *         )}
+ *         <button onClick={next} disabled={!canNext}>Next</button>
+ *       </nav>
+ *       <p>Page {page} of {pageCount}</p>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
+
+/**
+ * Compute the number of pages for a dataset. Always returns at least `1` — an
+ * empty dataset still has a single (empty) page — so it is safe to use directly
+ * as the upper clamp bound. `total` is treated as `>= 0` and `pageSize` as
+ * `>= 1` (both floored; non-finite inputs are normalized).
+ *
+ * @param total - Total number of items.
+ * @param pageSize - Items per page.
+ * @returns The page count, `>= 1`.
+ *
+ * @example
+ * ```ts
+ * getPageCount(0, 10);  // 1
+ * getPageCount(25, 10); // 3
+ * getPageCount(30, 10); // 3
+ * ```
+ */
+declare function getPageCount(total: number, pageSize: number): number;
+/**
+ * Clamp a requested page into `[1, pageCount]`, flooring fractions. Non-finite
+ * requests fall back to page `1`. `pageCount` is assumed to be `>= 1` (as
+ * returned by {@link getPageCount}).
+ *
+ * @param page - The requested 1-based page.
+ * @param pageCount - The number of pages (upper bound).
+ * @returns The clamped page, within `[1, pageCount]`.
+ */
+declare function clampPage(page: number, pageCount: number): number;
+/**
+ * Parameters for {@link buildPaginationRange}.
+ */
+interface BuildPaginationRangeParams {
+    /** The current (clamped) 1-based page. */
+    page: number;
+    /** Total number of pages (`>= 1`). */
+    pageCount: number;
+    /** Pages shown on each side of the current page. @defaultValue 1 */
+    siblingCount?: number;
+    /** Pages shown at the start and end. @defaultValue 1 */
+    boundaryCount?: number;
+}
+/**
+ * Build the ordered list of page numbers with `"ellipsis"` gap tokens for a
+ * pager UI — the well-known MUI/Mantine `usePagination` model. Always shows the
+ * `boundaryCount` first/last pages and the `siblingCount` pages around the
+ * current page, collapsing anything in between into a single `"ellipsis"`. When
+ * a gap would hide exactly one page, that page is shown instead of an ellipsis.
+ *
+ * @param params - See {@link BuildPaginationRangeParams}.
+ * @returns An ordered array of 1-based page numbers and `"ellipsis"` tokens.
+ *
+ * @example
+ * ```ts
+ * buildPaginationRange({ page: 1, pageCount: 10 });
+ * // [1, 2, 3, 4, 5, "ellipsis", 10]
+ * buildPaginationRange({ page: 6, pageCount: 10 });
+ * // [1, "ellipsis", 5, 6, 7, "ellipsis", 10]
+ * ```
+ */
+declare function buildPaginationRange(params: BuildPaginationRangeParams): (number | "ellipsis")[];
+
+export { type BuildPaginationRangeParams, type PaginationItem, type PaginationItemType, type PaginationRange, type UsePaginationOptions, type UsePaginationReturn, buildPaginationRange, clampPage, getPageCount, usePagination };

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Options for the {@link usePagination} hook.
+ */
+interface UsePaginationOptions {
+    /**
+     * Total number of items across all pages. Values below `0` (and non-finite
+     * values) are treated as `0`. Fractional values are floored.
+     */
+    total: number;
+    /**
+     * Number of items per page.
+     *
+     * @defaultValue 10
+     * @remarks Clamped to a minimum of `1` — a page size of `0` or a negative
+     * value would make `pageCount` meaningless, so it is coerced to `1`.
+     */
+    pageSize?: number;
+    /**
+     * The **controlled** current page (1-based). When provided (not `undefined`),
+     * the hook runs in controlled mode: the returned `page` mirrors this prop
+     * (clamped into `[1, pageCount]`) and `setPage`/`next`/`prev`/… only call
+     * `onChange` — the parent owns the value.
+     *
+     * Pass `undefined` to run uncontrolled, seeded from {@link defaultPage}.
+     */
+    page?: number;
+    /**
+     * The initial current page (1-based) in **uncontrolled** mode. Ignored while
+     * controlled.
+     *
+     * @defaultValue 1
+     */
+    defaultPage?: number;
+    /**
+     * Number of always-visible page buttons on each side of the current page in
+     * the {@link UsePaginationReturn.items} model.
+     *
+     * @defaultValue 1
+     */
+    siblingCount?: number;
+    /**
+     * Number of always-visible page buttons at the start and end (the boundaries)
+     * in the {@link UsePaginationReturn.items} model.
+     *
+     * @defaultValue 1
+     */
+    boundaryCount?: number;
+    /**
+     * Called with the next page whenever the current page changes — via any of the
+     * navigation controls in uncontrolled mode, or when a control requests a
+     * *different* page in controlled mode. Its identity may change between renders
+     * without any effect on the hook (the latest callback is always used).
+     */
+    onChange?: (page: number) => void;
+}
+/**
+ * The kind of a {@link PaginationItem}: a real page button, or an `"ellipsis"`
+ * gap token used to collapse a long run of pages.
+ */
+type PaginationItemType = "page" | "ellipsis";
+/**
+ * A single entry in the ellipsis-aware page-number model
+ * ({@link UsePaginationReturn.items}) used to render a pager UI.
+ */
+interface PaginationItem {
+    /** Whether this entry is a clickable page or an `"ellipsis"` gap. */
+    type: PaginationItemType;
+    /**
+     * The 1-based page number for a `"page"` entry, or `null` for an `"ellipsis"`.
+     */
+    page: number | null;
+    /** `true` when this is the current page (always `false` for `"ellipsis"`). */
+    selected: boolean;
+}
+/**
+ * The 0-based index window of the current page, ready to slice an array with
+ * `array.slice(range.start, range.end)`.
+ */
+interface PaginationRange {
+    /** 0-based index of the first item on the current page (**inclusive**). */
+    readonly start: number;
+    /**
+     * 0-based index **one past** the last item on the current page
+     * (**exclusive**), clamped to `total`. `array.slice(start, end)` yields the
+     * current page's items. For an empty dataset, `start === end === 0`.
+     */
+    readonly end: number;
+}
+/**
+ * Return value of {@link usePagination}.
+ */
+interface UsePaginationReturn {
+    /** The current page, 1-based, always within `[1, pageCount]`. */
+    page: number;
+    /**
+     * Total number of pages, always `>= 1` (an empty dataset still has one empty
+     * page). Equals `Math.max(1, Math.ceil(total / pageSize))`.
+     */
+    pageCount: number;
+    /** The effective page size (clamped to a minimum of `1`). */
+    pageSize: number;
+    /**
+     * Go to a specific page. The argument is clamped into `[1, pageCount]` and
+     * floored; going to the page you are already on is a no-op (no re-render, no
+     * `onChange`). Stable identity.
+     */
+    setPage: (page: number) => void;
+    /** Go to the next page (no-op on the last page). Stable identity. */
+    next: () => void;
+    /** Go to the previous page (no-op on the first page). Stable identity. */
+    prev: () => void;
+    /** Go to the first page. Stable identity. */
+    first: () => void;
+    /** Go to the last page. Stable identity. */
+    last: () => void;
+    /** `true` when there is a next page (`page < pageCount`). */
+    canNext: boolean;
+    /** `true` when there is a previous page (`page > 1`). */
+    canPrev: boolean;
+    /**
+     * The 0-based index window of the current page for slicing your data array.
+     * See {@link PaginationRange}.
+     */
+    range: PaginationRange;
+    /**
+     * The ellipsis-aware ordered list of page buttons and gap tokens to render a
+     * pager UI, driven by `siblingCount`/`boundaryCount`. Read-only — it is a
+     * memoized derived model, so treat it as immutable. See {@link PaginationItem}.
+     */
+    items: readonly PaginationItem[];
+}
+
+/**
+ * A headless pagination state machine — the current page (controlled or
+ * uncontrolled), the derived page count, a slice-ready index range, and an
+ * ellipsis-aware page-number model for rendering a pager UI. It owns *state*
+ * only; you render however you like.
+ *
+ * The current page is always kept within `[1, pageCount]`: it is clamped
+ * **derived** from `total`/`pageSize`, so when the dataset shrinks the returned
+ * `page` never points past the last page and the navigation controls stay
+ * correct (a plain re-clamp, no surprise `onChange`). All controls
+ * (`setPage`/`next`/`prev`/`first`/`last`) have stable identities and skip
+ * no-op moves (staying on the current page does not re-render or fire
+ * `onChange`).
+ *
+ * Works in both modes, mirroring `useControllableState`:
+ * - **Uncontrolled** (`page` omitted): the hook owns the page, seeded from
+ *   `defaultPage`; `onChange` fires after each committed change.
+ * - **Controlled** (`page` provided): the returned `page` mirrors the prop
+ *   (clamped) and the controls only call `onChange` — the parent owns the value.
+ *
+ * @param options - See {@link UsePaginationOptions}.
+ * @returns The pagination state and controls — see {@link UsePaginationReturn}.
+ *
+ * @example
+ * ```tsx
+ * function UsersTable({ users }: { users: User[] }) {
+ *   const { page, pageCount, range, items, setPage, next, prev, canNext, canPrev } =
+ *     usePagination({ total: users.length, pageSize: 10 });
+ *
+ *   const visible = users.slice(range.start, range.end);
+ *
+ *   return (
+ *     <>
+ *       <ul>{visible.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
+ *       <nav>
+ *         <button onClick={prev} disabled={!canPrev}>Prev</button>
+ *         {items.map((item, i) =>
+ *           item.type === "ellipsis" ? (
+ *             <span key={`gap-${i}`}>…</span>
+ *           ) : (
+ *             <button
+ *               key={item.page}
+ *               aria-current={item.selected}
+ *               onClick={() => setPage(item.page!)}
+ *             >
+ *               {item.page}
+ *             </button>
+ *           )
+ *         )}
+ *         <button onClick={next} disabled={!canNext}>Next</button>
+ *       </nav>
+ *       <p>Page {page} of {pageCount}</p>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
+
+/**
+ * Compute the number of pages for a dataset. Always returns at least `1` — an
+ * empty dataset still has a single (empty) page — so it is safe to use directly
+ * as the upper clamp bound. `total` is treated as `>= 0` and `pageSize` as
+ * `>= 1` (both floored; non-finite inputs are normalized).
+ *
+ * @param total - Total number of items.
+ * @param pageSize - Items per page.
+ * @returns The page count, `>= 1`.
+ *
+ * @example
+ * ```ts
+ * getPageCount(0, 10);  // 1
+ * getPageCount(25, 10); // 3
+ * getPageCount(30, 10); // 3
+ * ```
+ */
+declare function getPageCount(total: number, pageSize: number): number;
+/**
+ * Clamp a requested page into `[1, pageCount]`, flooring fractions. Non-finite
+ * requests fall back to page `1`. `pageCount` is assumed to be `>= 1` (as
+ * returned by {@link getPageCount}).
+ *
+ * @param page - The requested 1-based page.
+ * @param pageCount - The number of pages (upper bound).
+ * @returns The clamped page, within `[1, pageCount]`.
+ */
+declare function clampPage(page: number, pageCount: number): number;
+/**
+ * Parameters for {@link buildPaginationRange}.
+ */
+interface BuildPaginationRangeParams {
+    /** The current (clamped) 1-based page. */
+    page: number;
+    /** Total number of pages (`>= 1`). */
+    pageCount: number;
+    /** Pages shown on each side of the current page. @defaultValue 1 */
+    siblingCount?: number;
+    /** Pages shown at the start and end. @defaultValue 1 */
+    boundaryCount?: number;
+}
+/**
+ * Build the ordered list of page numbers with `"ellipsis"` gap tokens for a
+ * pager UI — the well-known MUI/Mantine `usePagination` model. Always shows the
+ * `boundaryCount` first/last pages and the `siblingCount` pages around the
+ * current page, collapsing anything in between into a single `"ellipsis"`. When
+ * a gap would hide exactly one page, that page is shown instead of an ellipsis.
+ *
+ * @param params - See {@link BuildPaginationRangeParams}.
+ * @returns An ordered array of 1-based page numbers and `"ellipsis"` tokens.
+ *
+ * @example
+ * ```ts
+ * buildPaginationRange({ page: 1, pageCount: 10 });
+ * // [1, 2, 3, 4, 5, "ellipsis", 10]
+ * buildPaginationRange({ page: 6, pageCount: 10 });
+ * // [1, "ellipsis", 5, 6, 7, "ellipsis", 10]
+ * ```
+ */
+declare function buildPaginationRange(params: BuildPaginationRangeParams): (number | "ellipsis")[];
+
+export { type BuildPaginationRangeParams, type PaginationItem, type PaginationItemType, type PaginationRange, type UsePaginationOptions, type UsePaginationReturn, buildPaginationRange, clampPage, getPageCount, usePagination };

package/dist/index.js

@@ -0,0 +1,190 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildPaginationRange: () => buildPaginationRange,
+  clampPage: () => clampPage,
+  getPageCount: () => getPageCount,
+  usePagination: () => usePagination
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/usePagination.ts
+var import_react = require("react");
+var import_use_controllable_state = require("@usefy/use-controllable-state");
+
+// src/utils.ts
+function toSafeInt(value, min, fallback) {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  const floored = Math.floor(value);
+  return floored < min ? min : floored;
+}
+function getPageCount(total, pageSize) {
+  const safeTotal = toSafeInt(total, 0, 0);
+  const safeSize = toSafeInt(pageSize, 1, 1);
+  return Math.max(1, Math.ceil(safeTotal / safeSize));
+}
+function clampPage(page, pageCount) {
+  if (!Number.isFinite(page)) {
+    return 1;
+  }
+  const floored = Math.floor(page);
+  if (floored < 1) {
+    return 1;
+  }
+  return floored > pageCount ? pageCount : floored;
+}
+var inclusiveRange = (start, end) => start > end ? [] : Array.from({ length: end - start + 1 }, (_, index) => start + index);
+function buildPaginationRange(params) {
+  const count = Math.max(1, Math.floor(params.pageCount));
+  const page = clampPage(params.page, count);
+  const siblingCount = Math.max(0, Math.floor(params.siblingCount ?? 1));
+  const boundaryCount = Math.max(0, Math.floor(params.boundaryCount ?? 1));
+  const startPages = inclusiveRange(1, Math.min(boundaryCount, count));
+  const endPages = inclusiveRange(
+    Math.max(count - boundaryCount + 1, boundaryCount + 1),
+    count
+  );
+  const siblingsStart = Math.max(
+    Math.min(page - siblingCount, count - boundaryCount - siblingCount * 2 - 1),
+    boundaryCount + 2
+  );
+  const siblingsEnd = Math.min(
+    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),
+    endPages.length > 0 ? endPages[0] - 2 : count - 1
+  );
+  return [
+    ...startPages,
+    // Start gap: an ellipsis, or the single page it would have hidden.
+    ...siblingsStart > boundaryCount + 2 ? ["ellipsis"] : boundaryCount + 1 < count - boundaryCount ? [boundaryCount + 1] : [],
+    ...inclusiveRange(siblingsStart, siblingsEnd),
+    // End gap: an ellipsis, or the single page it would have hidden.
+    ...siblingsEnd < count - boundaryCount - 1 ? ["ellipsis"] : count - boundaryCount > boundaryCount ? [count - boundaryCount] : [],
+    ...endPages
+  ];
+}
+
+// src/usePagination.ts
+var DEFAULT_PAGE_SIZE = 10;
+var DEFAULT_SIBLING_COUNT = 1;
+var DEFAULT_BOUNDARY_COUNT = 1;
+function usePagination(options) {
+  const {
+    total: rawTotal,
+    pageSize: rawPageSize = DEFAULT_PAGE_SIZE,
+    page: controlledPage,
+    defaultPage = 1,
+    siblingCount = DEFAULT_SIBLING_COUNT,
+    boundaryCount = DEFAULT_BOUNDARY_COUNT,
+    onChange
+  } = options;
+  const total = toSafeInt(rawTotal, 0, 0);
+  const pageSize = toSafeInt(rawPageSize, 1, 1);
+  const pageCount = getPageCount(rawTotal, rawPageSize);
+  const [rawPage, setRawPage] = (0, import_use_controllable_state.useControllableState)({
+    value: controlledPage,
+    defaultValue: defaultPage,
+    onChange
+  });
+  const page = clampPage(rawPage, pageCount);
+  const stateRef = (0, import_react.useRef)({ page, pageCount });
+  stateRef.current = { page, pageCount };
+  const setRawPageRef = (0, import_react.useRef)(setRawPage);
+  setRawPageRef.current = setRawPage;
+  const setPage = (0, import_react.useCallback)((next2) => {
+    const { page: current, pageCount: count } = stateRef.current;
+    const target = clampPage(next2, count);
+    if (target === current) {
+      return;
+    }
+    setRawPageRef.current(target);
+  }, []);
+  const next = (0, import_react.useCallback)(() => {
+    setPage(stateRef.current.page + 1);
+  }, [setPage]);
+  const prev = (0, import_react.useCallback)(() => {
+    setPage(stateRef.current.page - 1);
+  }, [setPage]);
+  const first = (0, import_react.useCallback)(() => {
+    setPage(1);
+  }, [setPage]);
+  const last = (0, import_react.useCallback)(() => {
+    setPage(stateRef.current.pageCount);
+  }, [setPage]);
+  const canNext = page < pageCount;
+  const canPrev = page > 1;
+  const range = (0, import_react.useMemo)(() => {
+    const start = (page - 1) * pageSize;
+    const end = Math.min(start + pageSize, total);
+    return { start, end };
+  }, [page, pageSize, total]);
+  const items = (0, import_react.useMemo)(
+    () => buildPaginationRange({
+      page,
+      pageCount,
+      siblingCount,
+      boundaryCount
+    }).map(
+      (entry) => entry === "ellipsis" ? { type: "ellipsis", page: null, selected: false } : { type: "page", page: entry, selected: entry === page }
+    ),
+    [page, pageCount, siblingCount, boundaryCount]
+  );
+  return (0, import_react.useMemo)(
+    () => ({
+      page,
+      pageCount,
+      pageSize,
+      setPage,
+      next,
+      prev,
+      first,
+      last,
+      canNext,
+      canPrev,
+      range,
+      items
+    }),
+    [
+      page,
+      pageCount,
+      pageSize,
+      setPage,
+      next,
+      prev,
+      first,
+      last,
+      canNext,
+      canPrev,
+      range,
+      items
+    ]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildPaginationRange,
+  clampPage,
+  getPageCount,
+  usePagination
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/usePagination.ts","../src/utils.ts"],"sourcesContent":["export { usePagination } from \"./usePagination\";\nexport type {\n  UsePaginationOptions,\n  UsePaginationReturn,\n  PaginationItem,\n  PaginationItemType,\n  PaginationRange,\n} from \"./types\";\nexport {\n  getPageCount,\n  clampPage,\n  buildPaginationRange,\n  type BuildPaginationRangeParams,\n} from \"./utils\";\n","import { useCallback, useMemo, useRef } from \"react\";\nimport { useControllableState } from \"@usefy/use-controllable-state\";\nimport type {\n  PaginationItem,\n  PaginationRange,\n  UsePaginationOptions,\n  UsePaginationReturn,\n} from \"./types\";\nimport { buildPaginationRange, clampPage, getPageCount, toSafeInt } from \"./utils\";\n\nconst DEFAULT_PAGE_SIZE = 10;\nconst DEFAULT_SIBLING_COUNT = 1;\nconst DEFAULT_BOUNDARY_COUNT = 1;\n\n/**\n * A headless pagination state machine — the current page (controlled or\n * uncontrolled), the derived page count, a slice-ready index range, and an\n * ellipsis-aware page-number model for rendering a pager UI. It owns *state*\n * only; you render however you like.\n *\n * The current page is always kept within `[1, pageCount]`: it is clamped\n * **derived** from `total`/`pageSize`, so when the dataset shrinks the returned\n * `page` never points past the last page and the navigation controls stay\n * correct (a plain re-clamp, no surprise `onChange`). All controls\n * (`setPage`/`next`/`prev`/`first`/`last`) have stable identities and skip\n * no-op moves (staying on the current page does not re-render or fire\n * `onChange`).\n *\n * Works in both modes, mirroring `useControllableState`:\n * - **Uncontrolled** (`page` omitted): the hook owns the page, seeded from\n *   `defaultPage`; `onChange` fires after each committed change.\n * - **Controlled** (`page` provided): the returned `page` mirrors the prop\n *   (clamped) and the controls only call `onChange` — the parent owns the value.\n *\n * @param options - See {@link UsePaginationOptions}.\n * @returns The pagination state and controls — see {@link UsePaginationReturn}.\n *\n * @example\n * ```tsx\n * function UsersTable({ users }: { users: User[] }) {\n *   const { page, pageCount, range, items, setPage, next, prev, canNext, canPrev } =\n *     usePagination({ total: users.length, pageSize: 10 });\n *\n *   const visible = users.slice(range.start, range.end);\n *\n *   return (\n *     <>\n *       <ul>{visible.map((u) => <li key={u.id}>{u.name}</li>)}</ul>\n *       <nav>\n *         <button onClick={prev} disabled={!canPrev}>Prev</button>\n *         {items.map((item, i) =>\n *           item.type === \"ellipsis\" ? (\n *             <span key={`gap-${i}`}>…</span>\n *           ) : (\n *             <button\n *               key={item.page}\n *               aria-current={item.selected}\n *               onClick={() => setPage(item.page!)}\n *             >\n *               {item.page}\n *             </button>\n *           )\n *         )}\n *         <button onClick={next} disabled={!canNext}>Next</button>\n *       </nav>\n *       <p>Page {page} of {pageCount}</p>\n *     </>\n *   );\n * }\n * ```\n */\nexport function usePagination(\n  options: UsePaginationOptions\n): UsePaginationReturn {\n  const {\n    total: rawTotal,\n    pageSize: rawPageSize = DEFAULT_PAGE_SIZE,\n    page: controlledPage,\n    defaultPage = 1,\n    siblingCount = DEFAULT_SIBLING_COUNT,\n    boundaryCount = DEFAULT_BOUNDARY_COUNT,\n    onChange,\n  } = options;\n\n  const total = toSafeInt(rawTotal, 0, 0);\n  const pageSize = toSafeInt(rawPageSize, 1, 1);\n  const pageCount = getPageCount(rawTotal, rawPageSize);\n\n  // Raw (unclamped) page state, controllable. We always write *concrete*\n  // clamped values through this setter (never updater functions), so the fact\n  // that its internal value may drift out of range while the dataset shrinks\n  // never leaks — the `page` below is always the clamped, derived value.\n  const [rawPage, setRawPage] = useControllableState<number>({\n    value: controlledPage,\n    defaultValue: defaultPage,\n    onChange,\n  });\n\n  const page = clampPage(rawPage, pageCount);\n\n  // Mirror the latest derived values + setter into refs so the controls can be\n  // fully identity-stable (empty dep arrays) while still reading fresh state.\n  const stateRef = useRef({ page, pageCount });\n  stateRef.current = { page, pageCount };\n\n  const setRawPageRef = useRef(setRawPage);\n  setRawPageRef.current = setRawPage;\n\n  const setPage = useCallback((next: number) => {\n    const { page: current, pageCount: count } = stateRef.current;\n    const target = clampPage(next, count);\n    if (target === current) {\n      return; // no-op: staying put must not re-render or fire onChange\n    }\n    setRawPageRef.current(target);\n  }, []);\n\n  const next = useCallback(() => {\n    setPage(stateRef.current.page + 1);\n  }, [setPage]);\n\n  const prev = useCallback(() => {\n    setPage(stateRef.current.page - 1);\n  }, [setPage]);\n\n  const first = useCallback(() => {\n    setPage(1);\n  }, [setPage]);\n\n  const last = useCallback(() => {\n    setPage(stateRef.current.pageCount);\n  }, [setPage]);\n\n  const canNext = page < pageCount;\n  const canPrev = page > 1;\n\n  const range = useMemo<PaginationRange>(() => {\n    const start = (page - 1) * pageSize;\n    const end = Math.min(start + pageSize, total);\n    return { start, end };\n  }, [page, pageSize, total]);\n\n  const items = useMemo<readonly PaginationItem[]>(\n    () =>\n      buildPaginationRange({\n        page,\n        pageCount,\n        siblingCount,\n        boundaryCount,\n      }).map((entry) =>\n        entry === \"ellipsis\"\n          ? { type: \"ellipsis\", page: null, selected: false }\n          : { type: \"page\", page: entry, selected: entry === page }\n      ),\n    [page, pageCount, siblingCount, boundaryCount]\n  );\n\n  return useMemo<UsePaginationReturn>(\n    () => ({\n      page,\n      pageCount,\n      pageSize,\n      setPage,\n      next,\n      prev,\n      first,\n      last,\n      canNext,\n      canPrev,\n      range,\n      items,\n    }),\n    [\n      page,\n      pageCount,\n      pageSize,\n      setPage,\n      next,\n      prev,\n      first,\n      last,\n      canNext,\n      canPrev,\n      range,\n      items,\n    ]\n  );\n}\n","/**\n * Coerce a value to a safe integer, flooring fractions and enforcing a minimum.\n * Non-finite values (`NaN`, `Infinity`) fall back to `fallback`.\n *\n * @internal\n */\nexport function toSafeInt(value: number, min: number, fallback: number): number {\n  if (!Number.isFinite(value)) {\n    return fallback;\n  }\n  const floored = Math.floor(value);\n  return floored < min ? min : floored;\n}\n\n/**\n * Compute the number of pages for a dataset. Always returns at least `1` — an\n * empty dataset still has a single (empty) page — so it is safe to use directly\n * as the upper clamp bound. `total` is treated as `>= 0` and `pageSize` as\n * `>= 1` (both floored; non-finite inputs are normalized).\n *\n * @param total - Total number of items.\n * @param pageSize - Items per page.\n * @returns The page count, `>= 1`.\n *\n * @example\n * ```ts\n * getPageCount(0, 10);  // 1\n * getPageCount(25, 10); // 3\n * getPageCount(30, 10); // 3\n * ```\n */\nexport function getPageCount(total: number, pageSize: number): number {\n  const safeTotal = toSafeInt(total, 0, 0);\n  const safeSize = toSafeInt(pageSize, 1, 1);\n  return Math.max(1, Math.ceil(safeTotal / safeSize));\n}\n\n/**\n * Clamp a requested page into `[1, pageCount]`, flooring fractions. Non-finite\n * requests fall back to page `1`. `pageCount` is assumed to be `>= 1` (as\n * returned by {@link getPageCount}).\n *\n * @param page - The requested 1-based page.\n * @param pageCount - The number of pages (upper bound).\n * @returns The clamped page, within `[1, pageCount]`.\n */\nexport function clampPage(page: number, pageCount: number): number {\n  if (!Number.isFinite(page)) {\n    return 1;\n  }\n  const floored = Math.floor(page);\n  if (floored < 1) {\n    return 1;\n  }\n  return floored > pageCount ? pageCount : floored;\n}\n\n/**\n * Parameters for {@link buildPaginationRange}.\n */\nexport interface BuildPaginationRangeParams {\n  /** The current (clamped) 1-based page. */\n  page: number;\n  /** Total number of pages (`>= 1`). */\n  pageCount: number;\n  /** Pages shown on each side of the current page. @defaultValue 1 */\n  siblingCount?: number;\n  /** Pages shown at the start and end. @defaultValue 1 */\n  boundaryCount?: number;\n}\n\nconst inclusiveRange = (start: number, end: number): number[] =>\n  start > end\n    ? []\n    : Array.from({ length: end - start + 1 }, (_, index) => start + index);\n\n/**\n * Build the ordered list of page numbers with `\"ellipsis\"` gap tokens for a\n * pager UI — the well-known MUI/Mantine `usePagination` model. Always shows the\n * `boundaryCount` first/last pages and the `siblingCount` pages around the\n * current page, collapsing anything in between into a single `\"ellipsis\"`. When\n * a gap would hide exactly one page, that page is shown instead of an ellipsis.\n *\n * @param params - See {@link BuildPaginationRangeParams}.\n * @returns An ordered array of 1-based page numbers and `\"ellipsis\"` tokens.\n *\n * @example\n * ```ts\n * buildPaginationRange({ page: 1, pageCount: 10 });\n * // [1, 2, 3, 4, 5, \"ellipsis\", 10]\n * buildPaginationRange({ page: 6, pageCount: 10 });\n * // [1, \"ellipsis\", 5, 6, 7, \"ellipsis\", 10]\n * ```\n */\nexport function buildPaginationRange(\n  params: BuildPaginationRangeParams\n): (number | \"ellipsis\")[] {\n  const count = Math.max(1, Math.floor(params.pageCount));\n  const page = clampPage(params.page, count);\n  const siblingCount = Math.max(0, Math.floor(params.siblingCount ?? 1));\n  const boundaryCount = Math.max(0, Math.floor(params.boundaryCount ?? 1));\n\n  const startPages = inclusiveRange(1, Math.min(boundaryCount, count));\n  const endPages = inclusiveRange(\n    Math.max(count - boundaryCount + 1, boundaryCount + 1),\n    count\n  );\n\n  const siblingsStart = Math.max(\n    Math.min(page - siblingCount, count - boundaryCount - siblingCount * 2 - 1),\n    boundaryCount + 2\n  );\n  const siblingsEnd = Math.min(\n    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),\n    endPages.length > 0 ? endPages[0] - 2 : count - 1\n  );\n\n  return [\n    ...startPages,\n    // Start gap: an ellipsis, or the single page it would have hidden.\n    ...(siblingsStart > boundaryCount + 2\n      ? ([\"ellipsis\"] as const)\n      : boundaryCount + 1 < count - boundaryCount\n        ? [boundaryCount + 1]\n        : []),\n    ...inclusiveRange(siblingsStart, siblingsEnd),\n    // End gap: an ellipsis, or the single page it would have hidden.\n    ...(siblingsEnd < count - boundaryCount - 1\n      ? ([\"ellipsis\"] as const)\n      : count - boundaryCount > boundaryCount\n        ? [count - boundaryCount]\n        : []),\n    ...endPages,\n  ];\n}\n"],"mappings":"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","names":["next"]}

package/dist/index.mjs

@@ -0,0 +1,160 @@
+// src/usePagination.ts
+import { useCallback, useMemo, useRef } from "react";
+import { useControllableState } from "@usefy/use-controllable-state";
+
+// src/utils.ts
+function toSafeInt(value, min, fallback) {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  const floored = Math.floor(value);
+  return floored < min ? min : floored;
+}
+function getPageCount(total, pageSize) {
+  const safeTotal = toSafeInt(total, 0, 0);
+  const safeSize = toSafeInt(pageSize, 1, 1);
+  return Math.max(1, Math.ceil(safeTotal / safeSize));
+}
+function clampPage(page, pageCount) {
+  if (!Number.isFinite(page)) {
+    return 1;
+  }
+  const floored = Math.floor(page);
+  if (floored < 1) {
+    return 1;
+  }
+  return floored > pageCount ? pageCount : floored;
+}
+var inclusiveRange = (start, end) => start > end ? [] : Array.from({ length: end - start + 1 }, (_, index) => start + index);
+function buildPaginationRange(params) {
+  const count = Math.max(1, Math.floor(params.pageCount));
+  const page = clampPage(params.page, count);
+  const siblingCount = Math.max(0, Math.floor(params.siblingCount ?? 1));
+  const boundaryCount = Math.max(0, Math.floor(params.boundaryCount ?? 1));
+  const startPages = inclusiveRange(1, Math.min(boundaryCount, count));
+  const endPages = inclusiveRange(
+    Math.max(count - boundaryCount + 1, boundaryCount + 1),
+    count
+  );
+  const siblingsStart = Math.max(
+    Math.min(page - siblingCount, count - boundaryCount - siblingCount * 2 - 1),
+    boundaryCount + 2
+  );
+  const siblingsEnd = Math.min(
+    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),
+    endPages.length > 0 ? endPages[0] - 2 : count - 1
+  );
+  return [
+    ...startPages,
+    // Start gap: an ellipsis, or the single page it would have hidden.
+    ...siblingsStart > boundaryCount + 2 ? ["ellipsis"] : boundaryCount + 1 < count - boundaryCount ? [boundaryCount + 1] : [],
+    ...inclusiveRange(siblingsStart, siblingsEnd),
+    // End gap: an ellipsis, or the single page it would have hidden.
+    ...siblingsEnd < count - boundaryCount - 1 ? ["ellipsis"] : count - boundaryCount > boundaryCount ? [count - boundaryCount] : [],
+    ...endPages
+  ];
+}
+
+// src/usePagination.ts
+var DEFAULT_PAGE_SIZE = 10;
+var DEFAULT_SIBLING_COUNT = 1;
+var DEFAULT_BOUNDARY_COUNT = 1;
+function usePagination(options) {
+  const {
+    total: rawTotal,
+    pageSize: rawPageSize = DEFAULT_PAGE_SIZE,
+    page: controlledPage,
+    defaultPage = 1,
+    siblingCount = DEFAULT_SIBLING_COUNT,
+    boundaryCount = DEFAULT_BOUNDARY_COUNT,
+    onChange
+  } = options;
+  const total = toSafeInt(rawTotal, 0, 0);
+  const pageSize = toSafeInt(rawPageSize, 1, 1);
+  const pageCount = getPageCount(rawTotal, rawPageSize);
+  const [rawPage, setRawPage] = useControllableState({
+    value: controlledPage,
+    defaultValue: defaultPage,
+    onChange
+  });
+  const page = clampPage(rawPage, pageCount);
+  const stateRef = useRef({ page, pageCount });
+  stateRef.current = { page, pageCount };
+  const setRawPageRef = useRef(setRawPage);
+  setRawPageRef.current = setRawPage;
+  const setPage = useCallback((next2) => {
+    const { page: current, pageCount: count } = stateRef.current;
+    const target = clampPage(next2, count);
+    if (target === current) {
+      return;
+    }
+    setRawPageRef.current(target);
+  }, []);
+  const next = useCallback(() => {
+    setPage(stateRef.current.page + 1);
+  }, [setPage]);
+  const prev = useCallback(() => {
+    setPage(stateRef.current.page - 1);
+  }, [setPage]);
+  const first = useCallback(() => {
+    setPage(1);
+  }, [setPage]);
+  const last = useCallback(() => {
+    setPage(stateRef.current.pageCount);
+  }, [setPage]);
+  const canNext = page < pageCount;
+  const canPrev = page > 1;
+  const range = useMemo(() => {
+    const start = (page - 1) * pageSize;
+    const end = Math.min(start + pageSize, total);
+    return { start, end };
+  }, [page, pageSize, total]);
+  const items = useMemo(
+    () => buildPaginationRange({
+      page,
+      pageCount,
+      siblingCount,
+      boundaryCount
+    }).map(
+      (entry) => entry === "ellipsis" ? { type: "ellipsis", page: null, selected: false } : { type: "page", page: entry, selected: entry === page }
+    ),
+    [page, pageCount, siblingCount, boundaryCount]
+  );
+  return useMemo(
+    () => ({
+      page,
+      pageCount,
+      pageSize,
+      setPage,
+      next,
+      prev,
+      first,
+      last,
+      canNext,
+      canPrev,
+      range,
+      items
+    }),
+    [
+      page,
+      pageCount,
+      pageSize,
+      setPage,
+      next,
+      prev,
+      first,
+      last,
+      canNext,
+      canPrev,
+      range,
+      items
+    ]
+  );
+}
+export {
+  buildPaginationRange,
+  clampPage,
+  getPageCount,
+  usePagination
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/usePagination.ts","../src/utils.ts"],"sourcesContent":["import { useCallback, useMemo, useRef } from \"react\";\nimport { useControllableState } from \"@usefy/use-controllable-state\";\nimport type {\n  PaginationItem,\n  PaginationRange,\n  UsePaginationOptions,\n  UsePaginationReturn,\n} from \"./types\";\nimport { buildPaginationRange, clampPage, getPageCount, toSafeInt } from \"./utils\";\n\nconst DEFAULT_PAGE_SIZE = 10;\nconst DEFAULT_SIBLING_COUNT = 1;\nconst DEFAULT_BOUNDARY_COUNT = 1;\n\n/**\n * A headless pagination state machine — the current page (controlled or\n * uncontrolled), the derived page count, a slice-ready index range, and an\n * ellipsis-aware page-number model for rendering a pager UI. It owns *state*\n * only; you render however you like.\n *\n * The current page is always kept within `[1, pageCount]`: it is clamped\n * **derived** from `total`/`pageSize`, so when the dataset shrinks the returned\n * `page` never points past the last page and the navigation controls stay\n * correct (a plain re-clamp, no surprise `onChange`). All controls\n * (`setPage`/`next`/`prev`/`first`/`last`) have stable identities and skip\n * no-op moves (staying on the current page does not re-render or fire\n * `onChange`).\n *\n * Works in both modes, mirroring `useControllableState`:\n * - **Uncontrolled** (`page` omitted): the hook owns the page, seeded from\n *   `defaultPage`; `onChange` fires after each committed change.\n * - **Controlled** (`page` provided): the returned `page` mirrors the prop\n *   (clamped) and the controls only call `onChange` — the parent owns the value.\n *\n * @param options - See {@link UsePaginationOptions}.\n * @returns The pagination state and controls — see {@link UsePaginationReturn}.\n *\n * @example\n * ```tsx\n * function UsersTable({ users }: { users: User[] }) {\n *   const { page, pageCount, range, items, setPage, next, prev, canNext, canPrev } =\n *     usePagination({ total: users.length, pageSize: 10 });\n *\n *   const visible = users.slice(range.start, range.end);\n *\n *   return (\n *     <>\n *       <ul>{visible.map((u) => <li key={u.id}>{u.name}</li>)}</ul>\n *       <nav>\n *         <button onClick={prev} disabled={!canPrev}>Prev</button>\n *         {items.map((item, i) =>\n *           item.type === \"ellipsis\" ? (\n *             <span key={`gap-${i}`}>…</span>\n *           ) : (\n *             <button\n *               key={item.page}\n *               aria-current={item.selected}\n *               onClick={() => setPage(item.page!)}\n *             >\n *               {item.page}\n *             </button>\n *           )\n *         )}\n *         <button onClick={next} disabled={!canNext}>Next</button>\n *       </nav>\n *       <p>Page {page} of {pageCount}</p>\n *     </>\n *   );\n * }\n * ```\n */\nexport function usePagination(\n  options: UsePaginationOptions\n): UsePaginationReturn {\n  const {\n    total: rawTotal,\n    pageSize: rawPageSize = DEFAULT_PAGE_SIZE,\n    page: controlledPage,\n    defaultPage = 1,\n    siblingCount = DEFAULT_SIBLING_COUNT,\n    boundaryCount = DEFAULT_BOUNDARY_COUNT,\n    onChange,\n  } = options;\n\n  const total = toSafeInt(rawTotal, 0, 0);\n  const pageSize = toSafeInt(rawPageSize, 1, 1);\n  const pageCount = getPageCount(rawTotal, rawPageSize);\n\n  // Raw (unclamped) page state, controllable. We always write *concrete*\n  // clamped values through this setter (never updater functions), so the fact\n  // that its internal value may drift out of range while the dataset shrinks\n  // never leaks — the `page` below is always the clamped, derived value.\n  const [rawPage, setRawPage] = useControllableState<number>({\n    value: controlledPage,\n    defaultValue: defaultPage,\n    onChange,\n  });\n\n  const page = clampPage(rawPage, pageCount);\n\n  // Mirror the latest derived values + setter into refs so the controls can be\n  // fully identity-stable (empty dep arrays) while still reading fresh state.\n  const stateRef = useRef({ page, pageCount });\n  stateRef.current = { page, pageCount };\n\n  const setRawPageRef = useRef(setRawPage);\n  setRawPageRef.current = setRawPage;\n\n  const setPage = useCallback((next: number) => {\n    const { page: current, pageCount: count } = stateRef.current;\n    const target = clampPage(next, count);\n    if (target === current) {\n      return; // no-op: staying put must not re-render or fire onChange\n    }\n    setRawPageRef.current(target);\n  }, []);\n\n  const next = useCallback(() => {\n    setPage(stateRef.current.page + 1);\n  }, [setPage]);\n\n  const prev = useCallback(() => {\n    setPage(stateRef.current.page - 1);\n  }, [setPage]);\n\n  const first = useCallback(() => {\n    setPage(1);\n  }, [setPage]);\n\n  const last = useCallback(() => {\n    setPage(stateRef.current.pageCount);\n  }, [setPage]);\n\n  const canNext = page < pageCount;\n  const canPrev = page > 1;\n\n  const range = useMemo<PaginationRange>(() => {\n    const start = (page - 1) * pageSize;\n    const end = Math.min(start + pageSize, total);\n    return { start, end };\n  }, [page, pageSize, total]);\n\n  const items = useMemo<readonly PaginationItem[]>(\n    () =>\n      buildPaginationRange({\n        page,\n        pageCount,\n        siblingCount,\n        boundaryCount,\n      }).map((entry) =>\n        entry === \"ellipsis\"\n          ? { type: \"ellipsis\", page: null, selected: false }\n          : { type: \"page\", page: entry, selected: entry === page }\n      ),\n    [page, pageCount, siblingCount, boundaryCount]\n  );\n\n  return useMemo<UsePaginationReturn>(\n    () => ({\n      page,\n      pageCount,\n      pageSize,\n      setPage,\n      next,\n      prev,\n      first,\n      last,\n      canNext,\n      canPrev,\n      range,\n      items,\n    }),\n    [\n      page,\n      pageCount,\n      pageSize,\n      setPage,\n      next,\n      prev,\n      first,\n      last,\n      canNext,\n      canPrev,\n      range,\n      items,\n    ]\n  );\n}\n","/**\n * Coerce a value to a safe integer, flooring fractions and enforcing a minimum.\n * Non-finite values (`NaN`, `Infinity`) fall back to `fallback`.\n *\n * @internal\n */\nexport function toSafeInt(value: number, min: number, fallback: number): number {\n  if (!Number.isFinite(value)) {\n    return fallback;\n  }\n  const floored = Math.floor(value);\n  return floored < min ? min : floored;\n}\n\n/**\n * Compute the number of pages for a dataset. Always returns at least `1` — an\n * empty dataset still has a single (empty) page — so it is safe to use directly\n * as the upper clamp bound. `total` is treated as `>= 0` and `pageSize` as\n * `>= 1` (both floored; non-finite inputs are normalized).\n *\n * @param total - Total number of items.\n * @param pageSize - Items per page.\n * @returns The page count, `>= 1`.\n *\n * @example\n * ```ts\n * getPageCount(0, 10);  // 1\n * getPageCount(25, 10); // 3\n * getPageCount(30, 10); // 3\n * ```\n */\nexport function getPageCount(total: number, pageSize: number): number {\n  const safeTotal = toSafeInt(total, 0, 0);\n  const safeSize = toSafeInt(pageSize, 1, 1);\n  return Math.max(1, Math.ceil(safeTotal / safeSize));\n}\n\n/**\n * Clamp a requested page into `[1, pageCount]`, flooring fractions. Non-finite\n * requests fall back to page `1`. `pageCount` is assumed to be `>= 1` (as\n * returned by {@link getPageCount}).\n *\n * @param page - The requested 1-based page.\n * @param pageCount - The number of pages (upper bound).\n * @returns The clamped page, within `[1, pageCount]`.\n */\nexport function clampPage(page: number, pageCount: number): number {\n  if (!Number.isFinite(page)) {\n    return 1;\n  }\n  const floored = Math.floor(page);\n  if (floored < 1) {\n    return 1;\n  }\n  return floored > pageCount ? pageCount : floored;\n}\n\n/**\n * Parameters for {@link buildPaginationRange}.\n */\nexport interface BuildPaginationRangeParams {\n  /** The current (clamped) 1-based page. */\n  page: number;\n  /** Total number of pages (`>= 1`). */\n  pageCount: number;\n  /** Pages shown on each side of the current page. @defaultValue 1 */\n  siblingCount?: number;\n  /** Pages shown at the start and end. @defaultValue 1 */\n  boundaryCount?: number;\n}\n\nconst inclusiveRange = (start: number, end: number): number[] =>\n  start > end\n    ? []\n    : Array.from({ length: end - start + 1 }, (_, index) => start + index);\n\n/**\n * Build the ordered list of page numbers with `\"ellipsis\"` gap tokens for a\n * pager UI — the well-known MUI/Mantine `usePagination` model. Always shows the\n * `boundaryCount` first/last pages and the `siblingCount` pages around the\n * current page, collapsing anything in between into a single `\"ellipsis\"`. When\n * a gap would hide exactly one page, that page is shown instead of an ellipsis.\n *\n * @param params - See {@link BuildPaginationRangeParams}.\n * @returns An ordered array of 1-based page numbers and `\"ellipsis\"` tokens.\n *\n * @example\n * ```ts\n * buildPaginationRange({ page: 1, pageCount: 10 });\n * // [1, 2, 3, 4, 5, \"ellipsis\", 10]\n * buildPaginationRange({ page: 6, pageCount: 10 });\n * // [1, \"ellipsis\", 5, 6, 7, \"ellipsis\", 10]\n * ```\n */\nexport function buildPaginationRange(\n  params: BuildPaginationRangeParams\n): (number | \"ellipsis\")[] {\n  const count = Math.max(1, Math.floor(params.pageCount));\n  const page = clampPage(params.page, count);\n  const siblingCount = Math.max(0, Math.floor(params.siblingCount ?? 1));\n  const boundaryCount = Math.max(0, Math.floor(params.boundaryCount ?? 1));\n\n  const startPages = inclusiveRange(1, Math.min(boundaryCount, count));\n  const endPages = inclusiveRange(\n    Math.max(count - boundaryCount + 1, boundaryCount + 1),\n    count\n  );\n\n  const siblingsStart = Math.max(\n    Math.min(page - siblingCount, count - boundaryCount - siblingCount * 2 - 1),\n    boundaryCount + 2\n  );\n  const siblingsEnd = Math.min(\n    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),\n    endPages.length > 0 ? endPages[0] - 2 : count - 1\n  );\n\n  return [\n    ...startPages,\n    // Start gap: an ellipsis, or the single page it would have hidden.\n    ...(siblingsStart > boundaryCount + 2\n      ? ([\"ellipsis\"] as const)\n      : boundaryCount + 1 < count - boundaryCount\n        ? [boundaryCount + 1]\n        : []),\n    ...inclusiveRange(siblingsStart, siblingsEnd),\n    // End gap: an ellipsis, or the single page it would have hidden.\n    ...(siblingsEnd < count - boundaryCount - 1\n      ? ([\"ellipsis\"] as const)\n      : count - boundaryCount > boundaryCount\n        ? [count - boundaryCount]\n        : []),\n    ...endPages,\n  ];\n}\n"],"mappings":"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","names":["next"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@usefy/use-pagination",
+  "version": "0.20.0",
+  "description": "A React hook for pagination state — controlled/uncontrolled current page, page count, range, and an ellipsis-aware page-number model",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@usefy/use-controllable-state": "0.20.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-pagination"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "pagination",
+    "paginate",
+    "pager",
+    "page",
+    "controllable",
+    "ellipsis",
+    "usePagination"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}