@ttt-productions/ui-core 0.11.11 → 0.11.14

package/dist/react/components/list-pagination.d.ts

@@ -1,8 +1,9 @@
 import type { ListPaginationState } from "../hooks/use-paged-list.js";
 export interface ListPaginationProps {
     /**
-     * Page state from `usePagedList` (known total), `useCursorPage` (unknown
-     * total), or any caller-owned state of the same shape.
+     * Page state from `usePagedList` (known total),
+     * `useCursorPage().paginationFor(hasMore)` (unknown total), or any
+     * caller-owned state of the same shape.
      */
     pagination: ListPaginationState;
     /**
@@ -18,8 +19,9 @@ export interface ListPaginationProps {
  * The ONE Previous / counter / Next control for paginated lists, in both
  * flavors. Pair it with the hook that owns the page state (`usePagedList` for a
  * client-side slice, `useCursorPage` — or the caller's own query state — for a
- * cursor feed); this component owns only the controls, so every paginated list
- * reads and behaves the same (ENG-002, FRONTEND-001).
+ * cursor feed; a cursor feed passes `pager.paginationFor(hasMore)`, which binds
+ * the query's answer to these controls); this component owns only the controls,
+ * so every paginated list reads and behaves the same (ENG-002, FRONTEND-001).
  *
  * The counter follows the flavor: a known `totalPages` reads "2 of 5", an
  * omitted one reads "Page 2". Everything else is identical in both flavors —

package/dist/react/components/list-pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-pagination.d.ts","sourceRoot":"","sources":["../../../src/react/components/list-pagination.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,EAAE,UAAU,EAAE,IAAY,EAAE,SAAS,EAAE,EAAE,mBAAmB,sCAuC1F"}
+{"version":3,"file":"list-pagination.d.ts","sourceRoot":"","sources":["../../../src/react/components/list-pagination.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAAE,UAAU,EAAE,IAAY,EAAE,SAAS,EAAE,EAAE,mBAAmB,sCAuC1F"}

package/dist/react/components/list-pagination.js

@@ -7,8 +7,9 @@ import { cn } from "../../lib/utils.js";
  * The ONE Previous / counter / Next control for paginated lists, in both
  * flavors. Pair it with the hook that owns the page state (`usePagedList` for a
  * client-side slice, `useCursorPage` — or the caller's own query state — for a
- * cursor feed); this component owns only the controls, so every paginated list
- * reads and behaves the same (ENG-002, FRONTEND-001).
+ * cursor feed; a cursor feed passes `pager.paginationFor(hasMore)`, which binds
+ * the query's answer to these controls); this component owns only the controls,
+ * so every paginated list reads and behaves the same (ENG-002, FRONTEND-001).
  *
  * The counter follows the flavor: a known `totalPages` reads "2 of 5", an
  * omitted one reads "Page 2". Everything else is identical in both flavors —

package/dist/react/components/list-pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-pagination.js","sourceRoot":"","sources":["../../../src/react/components/list-pagination.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAmBxC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,UAAU,EAAE,IAAI,GAAG,KAAK,EAAE,SAAS,EAAuB;IACzF,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,GAC7F,UAAU,CAAC;IAEb,0EAA0E;IAC1E,qEAAqE;IACrE,yEAAyE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,6DAA6D;IAC7D,IAAI,CAAC,eAAe,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAElD,OAAO,CACL,eAAK,SAAS,EAAE,EAAE,CAAC,qDAAqD,EAAE,SAAS,CAAC,aAClF,MAAC,MAAM,IACL,OAAO,EAAC,SAAS,EACjB,IAAI,EAAC,IAAI,EACT,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,IAAI,IAAI,CAAC,eAAe,EAClC,SAAS,EAAC,eAAe,aAEzB,KAAC,WAAW,IAAC,SAAS,EAAC,cAAc,GAAG,gBAEjC,EACT,eAAM,SAAS,EAAC,cAAc,EAAC,IAAI,EAAC,QAAQ,YACzC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,OAAO,UAAU,EAAE,GAChF,EACP,MAAC,MAAM,IACL,OAAO,EAAC,SAAS,EACjB,IAAI,EAAC,IAAI,EACT,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,IAAI,IAAI,CAAC,WAAW,EAC9B,SAAS,EAAC,eAAe,qBAGzB,KAAC,YAAY,IAAC,SAAS,EAAC,cAAc,GAAG,IAClC,IACL,CACP,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { ChevronLeft, ChevronRight } from \"lucide-react\";\nimport { Button } from \"./button.js\";\nimport { cn } from \"../../lib/utils.js\";\nimport type { ListPaginationState } from \"../hooks/use-paged-list.js\";\n\nexport interface ListPaginationProps {\n  /**\n   * Page state from `usePagedList` (known total), `useCursorPage` (unknown\n   * total), or any caller-owned state of the same shape.\n   */\n  pagination: ListPaginationState;\n  /**\n   * Disables BOTH controls while the next page is in flight, without hiding the\n   * row. Server-paged surfaces pass their query's `isFetching`; a slice-paged\n   * list has nothing to wait for and omits it.\n   */\n  busy?: boolean;\n  /** Optional extra classes. Merged with the component's own classes. */\n  className?: string;\n}\n\n/**\n * The ONE Previous / counter / Next control for paginated lists, in both\n * flavors. Pair it with the hook that owns the page state (`usePagedList` for a\n * client-side slice, `useCursorPage` — or the caller's own query state — for a\n * cursor feed); this component owns only the controls, so every paginated list\n * reads and behaves the same (ENG-002, FRONTEND-001).\n *\n * The counter follows the flavor: a known `totalPages` reads \"2 of 5\", an\n * omitted one reads \"Page 2\". Everything else is identical in both flavors —\n * which is exactly why there is one component and not two.\n *\n * It renders NOTHING when neither direction is available, so no call site\n * repeats a `totalPages > 1` / `page > 1 || hasMore` guard. Edge state is real\n * `disabled` on the buttons (announced, and unclickable), and the counter is a\n * `status` live region so a page change is announced to screen readers.\n */\nexport function ListPagination({ pagination, busy = false, className }: ListPaginationProps) {\n  const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } =\n    pagination;\n\n  // One visibility rule for both flavors. For a known total this is exactly\n  // `totalPages > 1`: page state is clamped into `1..totalPages`, so a\n  // single-page list has no reachable neighbour in either direction, and a\n  // multi-page list always has one. For a cursor feed it is the hand-rolled\n  // `page > 1 || hasMore`. `busy` deliberately does not hide the row — the\n  // controls grey out in place instead of vanishing mid-fetch.\n  if (!canPreviousPage && !canNextPage) return null;\n\n  return (\n    <div className={cn(\"flex w-full items-center justify-between gap-4 mt-4\", className)}>\n      <Button\n        variant=\"outline\"\n        size=\"sm\"\n        onClick={goToPreviousPage}\n        disabled={busy || !canPreviousPage}\n        className=\"h-11 min-w-11\"\n      >\n        <ChevronLeft className=\"icon-xs mr-1\" />\n        Previous\n      </Button>\n      <span className=\"text-counter\" role=\"status\">\n        {totalPages === undefined ? `Page ${currentPage}` : `${currentPage} of ${totalPages}`}\n      </span>\n      <Button\n        variant=\"outline\"\n        size=\"sm\"\n        onClick={goToNextPage}\n        disabled={busy || !canNextPage}\n        className=\"h-11 min-w-11\"\n      >\n        Next\n        <ChevronRight className=\"icon-xs ml-1\" />\n      </Button>\n    </div>\n  );\n}\n"]}
+{"version":3,"file":"list-pagination.js","sourceRoot":"","sources":["../../../src/react/components/list-pagination.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAoBxC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,UAAU,EAAE,IAAI,GAAG,KAAK,EAAE,SAAS,EAAuB;IACzF,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,GAC7F,UAAU,CAAC;IAEb,0EAA0E;IAC1E,qEAAqE;IACrE,yEAAyE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,6DAA6D;IAC7D,IAAI,CAAC,eAAe,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAElD,OAAO,CACL,eAAK,SAAS,EAAE,EAAE,CAAC,qDAAqD,EAAE,SAAS,CAAC,aAClF,MAAC,MAAM,IACL,OAAO,EAAC,SAAS,EACjB,IAAI,EAAC,IAAI,EACT,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,IAAI,IAAI,CAAC,eAAe,EAClC,SAAS,EAAC,eAAe,aAEzB,KAAC,WAAW,IAAC,SAAS,EAAC,cAAc,GAAG,gBAEjC,EACT,eAAM,SAAS,EAAC,cAAc,EAAC,IAAI,EAAC,QAAQ,YACzC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,OAAO,UAAU,EAAE,GAChF,EACP,MAAC,MAAM,IACL,OAAO,EAAC,SAAS,EACjB,IAAI,EAAC,IAAI,EACT,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,IAAI,IAAI,CAAC,WAAW,EAC9B,SAAS,EAAC,eAAe,qBAGzB,KAAC,YAAY,IAAC,SAAS,EAAC,cAAc,GAAG,IAClC,IACL,CACP,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { ChevronLeft, ChevronRight } from \"lucide-react\";\nimport { Button } from \"./button.js\";\nimport { cn } from \"../../lib/utils.js\";\nimport type { ListPaginationState } from \"../hooks/use-paged-list.js\";\n\nexport interface ListPaginationProps {\n  /**\n   * Page state from `usePagedList` (known total),\n   * `useCursorPage().paginationFor(hasMore)` (unknown total), or any\n   * caller-owned state of the same shape.\n   */\n  pagination: ListPaginationState;\n  /**\n   * Disables BOTH controls while the next page is in flight, without hiding the\n   * row. Server-paged surfaces pass their query's `isFetching`; a slice-paged\n   * list has nothing to wait for and omits it.\n   */\n  busy?: boolean;\n  /** Optional extra classes. Merged with the component's own classes. */\n  className?: string;\n}\n\n/**\n * The ONE Previous / counter / Next control for paginated lists, in both\n * flavors. Pair it with the hook that owns the page state (`usePagedList` for a\n * client-side slice, `useCursorPage` — or the caller's own query state — for a\n * cursor feed; a cursor feed passes `pager.paginationFor(hasMore)`, which binds\n * the query's answer to these controls); this component owns only the controls,\n * so every paginated list reads and behaves the same (ENG-002, FRONTEND-001).\n *\n * The counter follows the flavor: a known `totalPages` reads \"2 of 5\", an\n * omitted one reads \"Page 2\". Everything else is identical in both flavors —\n * which is exactly why there is one component and not two.\n *\n * It renders NOTHING when neither direction is available, so no call site\n * repeats a `totalPages > 1` / `page > 1 || hasMore` guard. Edge state is real\n * `disabled` on the buttons (announced, and unclickable), and the counter is a\n * `status` live region so a page change is announced to screen readers.\n */\nexport function ListPagination({ pagination, busy = false, className }: ListPaginationProps) {\n  const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } =\n    pagination;\n\n  // One visibility rule for both flavors. For a known total this is exactly\n  // `totalPages > 1`: page state is clamped into `1..totalPages`, so a\n  // single-page list has no reachable neighbour in either direction, and a\n  // multi-page list always has one. For a cursor feed it is the hand-rolled\n  // `page > 1 || hasMore`. `busy` deliberately does not hide the row — the\n  // controls grey out in place instead of vanishing mid-fetch.\n  if (!canPreviousPage && !canNextPage) return null;\n\n  return (\n    <div className={cn(\"flex w-full items-center justify-between gap-4 mt-4\", className)}>\n      <Button\n        variant=\"outline\"\n        size=\"sm\"\n        onClick={goToPreviousPage}\n        disabled={busy || !canPreviousPage}\n        className=\"h-11 min-w-11\"\n      >\n        <ChevronLeft className=\"icon-xs mr-1\" />\n        Previous\n      </Button>\n      <span className=\"text-counter\" role=\"status\">\n        {totalPages === undefined ? `Page ${currentPage}` : `${currentPage} of ${totalPages}`}\n      </span>\n      <Button\n        variant=\"outline\"\n        size=\"sm\"\n        onClick={goToNextPage}\n        disabled={busy || !canNextPage}\n        className=\"h-11 min-w-11\"\n      >\n        Next\n        <ChevronRight className=\"icon-xs ml-1\" />\n      </Button>\n    </div>\n  );\n}\n"]}

package/dist/react/hooks/use-cursor-page.d.ts

@@ -1,32 +1,77 @@
 import type { ListPaginationState } from "./use-paged-list.js";
+/**
+ * Render-time page state for a cursor feed, shaped as {@link ListPaginationState}
+ * so it drops straight into the ONE `ListPagination` control. Produced by
+ * {@link CursorPager.paginationFor} once the query for `currentPage` has
+ * answered with its `hasMore`.
+ */
 export interface CursorPage extends ListPaginationState {
     /** Never known for cursor pagination — the counter reads "Page N". */
     totalPages?: undefined;
-    /**
-     * Return to page 1 without walking back. Call it whenever the underlying
-     * query's inputs change (a new filter, a new tag, a new sort) — page 4 of the
-     * old result set is not page 4 of the new one.
-     */
-    reset: () => void;
 }
 export interface UseCursorPageOptions {
     /** Called after the page actually changed. Same contract as `usePagedList`. */
     onPageChange?: () => void;
+    /**
+     * A snapshot of the query inputs the page number belongs to — a tag, a filter,
+     * a sort. When it changes, the page is 1 again **in the same render**, so the
+     * query never fires for "page 4" of inputs whose page 4 may not exist.
+     *
+     * Use this when the input change arrives as a prop (there is no event handler
+     * of yours to hang the reset on); use {@link CursorPager.reset} when your own
+     * handler already owns the change. Compose several inputs into one string
+     * (`` `${type}|${projectId ?? ""}` ``) — the type is deliberately narrowed to
+     * primitives so a fresh object literal cannot pin the list to page 1 forever.
+     */
+    resetKey?: string | number | boolean | null;
+}
+/**
+ * What {@link useCursorPage} owns: the page number, the guarded step controls,
+ * and the return-to-page-1 control.
+ */
+export interface CursorPager {
+    /** 1-based page to feed into the paged query. */
+    currentPage: number;
+    /**
+     * Return to page 1 without walking back. Call it from the handler that changes
+     * the query's inputs (a new filter, a new tag, a new sort) — page 4 of the old
+     * result set is not page 4 of the new one. A no-op on page 1, so it never
+     * fires `onPageChange` for nothing.
+     */
+    reset: () => void;
+    /**
+     * Bind the query's answer to the controls: pass the `hasMore` that came back
+     * for {@link currentPage} and render the result as
+     * `<ListPagination pagination={…} />`. `hasMore` binds HERE, after the query,
+     * because that is the only moment it exists — a cursor query needs
+     * `currentPage` as its input, so `hasMore` cannot be an argument to the hook
+     * that produces `currentPage`.
+     */
+    paginationFor: (hasMore: boolean) => CursorPage;
 }
 /**
  * Page state for a server-paged (cursor / `hasMore`) list: the 1-based page
- * number plus guarded step controls, shaped as {@link ListPaginationState} so it
- * drops straight into the ONE `ListPagination` control.
+ * number, the guarded step controls, and the reset — the pieces each
+ * server-paged surface was otherwise re-declaring as a local `useState(1)` plus
+ * its own clamped increment/decrement and its own "reset when the filter
+ * changed" adjustment (ENG-002, ENG-003).
+ *
+ * The data stays the caller's, and the two halves bind at different moments:
+ *
+ * ```tsx
+ * const pager = useCursorPage({ resetKey: tag });
+ * const { data, isFetching } = useThingsByTag(tag, pager.currentPage);
+ * …
+ * <ListPagination pagination={pager.paginationFor(data?.hasMore ?? false)} busy={isFetching} />
+ * ```
  *
- * The caller owns the data: it feeds `hasMore` from its query and passes
- * `currentPage` back into that query. This hook owns only the page number — the
- * piece each server-paged surface was otherwise re-declaring as a local
- * `useState(1)` plus its own clamped increment/decrement (ENG-002, ENG-003).
+ * The guards live in here, not at the call site: a step that cannot move the
+ * page changes nothing and does not fire `onPageChange`.
  *
  * A surface whose data hook ALREADY owns its page state (it returns
  * `page`/`hasNextPage`/`nextPage`/`prevPage` itself) does not need this hook —
- * it maps those fields onto `ListPaginationState` directly. The hook exists for
- * the surfaces that would otherwise hand-roll the state.
+ * it maps those fields onto {@link ListPaginationState} directly. The hook
+ * exists for the surfaces that would otherwise hand-roll the state.
  */
-export declare function useCursorPage(hasMore: boolean, options?: UseCursorPageOptions): CursorPage;
+export declare function useCursorPage(options?: UseCursorPageOptions): CursorPager;
 //# sourceMappingURL=use-cursor-page.d.ts.map

package/dist/react/hooks/use-cursor-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cursor-page.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cursor-page.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD,sEAAsE;IACtE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,oBAAyB,GACjC,UAAU,CAgCZ"}
+{"version":3,"file":"use-cursor-page.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cursor-page.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD,sEAAsE;IACtE,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,UAAU,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,WAAW,CAwD7E"}

package/dist/react/hooks/use-cursor-page.js

@@ -2,49 +2,73 @@
 import { useCallback, useState } from "react";
 /**
  * Page state for a server-paged (cursor / `hasMore`) list: the 1-based page
- * number plus guarded step controls, shaped as {@link ListPaginationState} so it
- * drops straight into the ONE `ListPagination` control.
+ * number, the guarded step controls, and the reset — the pieces each
+ * server-paged surface was otherwise re-declaring as a local `useState(1)` plus
+ * its own clamped increment/decrement and its own "reset when the filter
+ * changed" adjustment (ENG-002, ENG-003).
  *
- * The caller owns the data: it feeds `hasMore` from its query and passes
- * `currentPage` back into that query. This hook owns only the page number — the
- * piece each server-paged surface was otherwise re-declaring as a local
- * `useState(1)` plus its own clamped increment/decrement (ENG-002, ENG-003).
+ * The data stays the caller's, and the two halves bind at different moments:
+ *
+ * ```tsx
+ * const pager = useCursorPage({ resetKey: tag });
+ * const { data, isFetching } = useThingsByTag(tag, pager.currentPage);
+ * …
+ * <ListPagination pagination={pager.paginationFor(data?.hasMore ?? false)} busy={isFetching} />
+ * ```
+ *
+ * The guards live in here, not at the call site: a step that cannot move the
+ * page changes nothing and does not fire `onPageChange`.
  *
  * A surface whose data hook ALREADY owns its page state (it returns
  * `page`/`hasNextPage`/`nextPage`/`prevPage` itself) does not need this hook —
- * it maps those fields onto `ListPaginationState` directly. The hook exists for
- * the surfaces that would otherwise hand-roll the state.
+ * it maps those fields onto {@link ListPaginationState} directly. The hook
+ * exists for the surfaces that would otherwise hand-roll the state.
  */
-export function useCursorPage(hasMore, options = {}) {
-    const { onPageChange } = options;
-    const [currentPage, setCurrentPage] = useState(1);
-    // Guards live here, not at the call site: a click that cannot move the page
-    // must not fire `onPageChange` and must not push the page past the data.
+export function useCursorPage(options = {}) {
+    const { onPageChange, resetKey } = options;
+    // The stored page is only meaningful for the inputs it was reached under, so
+    // the key it belongs to is stored WITH it.
+    const [pageState, setPageState] = useState({ page: 1, key: resetKey });
+    // `Object.is`, the same comparison React uses for state and deps: a `NaN` key
+    // must compare equal to itself, or the adjustment below would re-fire forever.
+    const keyMatches = Object.is(pageState.key, resetKey);
+    // React's "adjusting state when a prop changes": a new key retires the stored
+    // page, because page 4 of the old result set is not page 4 of the new one.
+    // Retiring it (rather than only ignoring it) is what makes going BACK to
+    // earlier inputs start at page 1 too, instead of reviving a dead page.
+    if (!keyMatches) {
+        setPageState({ page: 1, key: resetKey });
+    }
+    // Derived as well as adjusted, so even the render that triggers the adjustment
+    // already reports page 1 — the caller's query is never asked for a page of the
+    // new inputs that the user never navigated to.
+    const currentPage = keyMatches ? pageState.page : 1;
     const goToPreviousPage = useCallback(() => {
         if (currentPage <= 1)
             return;
-        setCurrentPage(currentPage - 1);
-        onPageChange?.();
-    }, [currentPage, onPageChange]);
-    const goToNextPage = useCallback(() => {
-        if (!hasMore)
-            return;
-        setCurrentPage(currentPage + 1);
+        setPageState({ page: currentPage - 1, key: resetKey });
         onPageChange?.();
-    }, [currentPage, hasMore, onPageChange]);
+    }, [currentPage, resetKey, onPageChange]);
     const reset = useCallback(() => {
         if (currentPage === 1)
             return;
-        setCurrentPage(1);
+        setPageState({ page: 1, key: resetKey });
         onPageChange?.();
-    }, [currentPage, onPageChange]);
-    return {
+    }, [currentPage, resetKey, onPageChange]);
+    // Memoized on the page state itself, so a consumer may hold it in a dep array
+    // and it changes only when the page (or the callback/inputs) actually change.
+    const paginationFor = useCallback((hasMore) => ({
         currentPage,
         canPreviousPage: currentPage > 1,
         canNextPage: hasMore,
         goToPreviousPage,
-        goToNextPage,
-        reset,
-    };
+        goToNextPage: () => {
+            if (!hasMore)
+                return;
+            setPageState({ page: currentPage + 1, key: resetKey });
+            onPageChange?.();
+        },
+    }), [currentPage, resetKey, onPageChange, goToPreviousPage]);
+    return { currentPage, reset, paginationFor };
 }
 //# sourceMappingURL=use-cursor-page.js.map

package/dist/react/hooks/use-cursor-page.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-cursor-page.js","sourceRoot":"","sources":["../../../src/react/hooks/use-cursor-page.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAmB9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,UAAgC,EAAE;IAElC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACjC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAElD,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE;QACxC,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,cAAc,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAChC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAEhC,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,cAAc,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAChC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAEzC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,WAAW,KAAK,CAAC;YAAE,OAAO;QAC9B,cAAc,CAAC,CAAC,CAAC,CAAC;QAClB,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAEhC,OAAO;QACL,WAAW;QACX,eAAe,EAAE,WAAW,GAAG,CAAC;QAChC,WAAW,EAAE,OAAO;QACpB,gBAAgB;QAChB,YAAY;QACZ,KAAK;KACN,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { useCallback, useState } from \"react\";\nimport type { ListPaginationState } from \"./use-paged-list.js\";\n\nexport interface CursorPage extends ListPaginationState {\n  /** Never known for cursor pagination — the counter reads \"Page N\". */\n  totalPages?: undefined;\n  /**\n   * Return to page 1 without walking back. Call it whenever the underlying\n   * query's inputs change (a new filter, a new tag, a new sort) — page 4 of the\n   * old result set is not page 4 of the new one.\n   */\n  reset: () => void;\n}\n\nexport interface UseCursorPageOptions {\n  /** Called after the page actually changed. Same contract as `usePagedList`. */\n  onPageChange?: () => void;\n}\n\n/**\n * Page state for a server-paged (cursor / `hasMore`) list: the 1-based page\n * number plus guarded step controls, shaped as {@link ListPaginationState} so it\n * drops straight into the ONE `ListPagination` control.\n *\n * The caller owns the data: it feeds `hasMore` from its query and passes\n * `currentPage` back into that query. This hook owns only the page number — the\n * piece each server-paged surface was otherwise re-declaring as a local\n * `useState(1)` plus its own clamped increment/decrement (ENG-002, ENG-003).\n *\n * A surface whose data hook ALREADY owns its page state (it returns\n * `page`/`hasNextPage`/`nextPage`/`prevPage` itself) does not need this hook —\n * it maps those fields onto `ListPaginationState` directly. The hook exists for\n * the surfaces that would otherwise hand-roll the state.\n */\nexport function useCursorPage(\n  hasMore: boolean,\n  options: UseCursorPageOptions = {},\n): CursorPage {\n  const { onPageChange } = options;\n  const [currentPage, setCurrentPage] = useState(1);\n\n  // Guards live here, not at the call site: a click that cannot move the page\n  // must not fire `onPageChange` and must not push the page past the data.\n  const goToPreviousPage = useCallback(() => {\n    if (currentPage <= 1) return;\n    setCurrentPage(currentPage - 1);\n    onPageChange?.();\n  }, [currentPage, onPageChange]);\n\n  const goToNextPage = useCallback(() => {\n    if (!hasMore) return;\n    setCurrentPage(currentPage + 1);\n    onPageChange?.();\n  }, [currentPage, hasMore, onPageChange]);\n\n  const reset = useCallback(() => {\n    if (currentPage === 1) return;\n    setCurrentPage(1);\n    onPageChange?.();\n  }, [currentPage, onPageChange]);\n\n  return {\n    currentPage,\n    canPreviousPage: currentPage > 1,\n    canNextPage: hasMore,\n    goToPreviousPage,\n    goToNextPage,\n    reset,\n  };\n}\n"]}
+{"version":3,"file":"use-cursor-page.js","sourceRoot":"","sources":["../../../src/react/hooks/use-cursor-page.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAwD9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE3C,6EAA6E;IAC7E,2CAA2C;IAC3C,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAGvC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE/B,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAEtD,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,+EAA+E;IAC/E,+EAA+E;IAC/E,+CAA+C;IAC/C,MAAM,WAAW,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpD,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE;QACxC,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QACvD,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;IAE1C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,WAAW,KAAK,CAAC;YAAE,OAAO;QAC9B,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;IAE1C,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,aAAa,GAAG,WAAW,CAC/B,CAAC,OAAgB,EAAc,EAAE,CAAC,CAAC;QACjC,WAAW;QACX,eAAe,EAAE,WAAW,GAAG,CAAC;QAChC,WAAW,EAAE,OAAO;QACpB,gBAAgB;QAChB,YAAY,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;YACvD,YAAY,EAAE,EAAE,CAAC;QACnB,CAAC;KACF,CAAC,EACF,CAAC,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,CAAC,CACxD,CAAC;IAEF,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;AAC/C,CAAC","sourcesContent":["\"use client\";\n\nimport { useCallback, useState } from \"react\";\nimport type { ListPaginationState } from \"./use-paged-list.js\";\n\n/**\n * Render-time page state for a cursor feed, shaped as {@link ListPaginationState}\n * so it drops straight into the ONE `ListPagination` control. Produced by\n * {@link CursorPager.paginationFor} once the query for `currentPage` has\n * answered with its `hasMore`.\n */\nexport interface CursorPage extends ListPaginationState {\n  /** Never known for cursor pagination — the counter reads \"Page N\". */\n  totalPages?: undefined;\n}\n\nexport interface UseCursorPageOptions {\n  /** Called after the page actually changed. Same contract as `usePagedList`. */\n  onPageChange?: () => void;\n  /**\n   * A snapshot of the query inputs the page number belongs to — a tag, a filter,\n   * a sort. When it changes, the page is 1 again **in the same render**, so the\n   * query never fires for \"page 4\" of inputs whose page 4 may not exist.\n   *\n   * Use this when the input change arrives as a prop (there is no event handler\n   * of yours to hang the reset on); use {@link CursorPager.reset} when your own\n   * handler already owns the change. Compose several inputs into one string\n   * (`` `${type}|${projectId ?? \"\"}` ``) — the type is deliberately narrowed to\n   * primitives so a fresh object literal cannot pin the list to page 1 forever.\n   */\n  resetKey?: string | number | boolean | null;\n}\n\n/**\n * What {@link useCursorPage} owns: the page number, the guarded step controls,\n * and the return-to-page-1 control.\n */\nexport interface CursorPager {\n  /** 1-based page to feed into the paged query. */\n  currentPage: number;\n  /**\n   * Return to page 1 without walking back. Call it from the handler that changes\n   * the query's inputs (a new filter, a new tag, a new sort) — page 4 of the old\n   * result set is not page 4 of the new one. A no-op on page 1, so it never\n   * fires `onPageChange` for nothing.\n   */\n  reset: () => void;\n  /**\n   * Bind the query's answer to the controls: pass the `hasMore` that came back\n   * for {@link currentPage} and render the result as\n   * `<ListPagination pagination={…} />`. `hasMore` binds HERE, after the query,\n   * because that is the only moment it exists — a cursor query needs\n   * `currentPage` as its input, so `hasMore` cannot be an argument to the hook\n   * that produces `currentPage`.\n   */\n  paginationFor: (hasMore: boolean) => CursorPage;\n}\n\n/**\n * Page state for a server-paged (cursor / `hasMore`) list: the 1-based page\n * number, the guarded step controls, and the reset — the pieces each\n * server-paged surface was otherwise re-declaring as a local `useState(1)` plus\n * its own clamped increment/decrement and its own \"reset when the filter\n * changed\" adjustment (ENG-002, ENG-003).\n *\n * The data stays the caller's, and the two halves bind at different moments:\n *\n * ```tsx\n * const pager = useCursorPage({ resetKey: tag });\n * const { data, isFetching } = useThingsByTag(tag, pager.currentPage);\n * …\n * <ListPagination pagination={pager.paginationFor(data?.hasMore ?? false)} busy={isFetching} />\n * ```\n *\n * The guards live in here, not at the call site: a step that cannot move the\n * page changes nothing and does not fire `onPageChange`.\n *\n * A surface whose data hook ALREADY owns its page state (it returns\n * `page`/`hasNextPage`/`nextPage`/`prevPage` itself) does not need this hook —\n * it maps those fields onto {@link ListPaginationState} directly. The hook\n * exists for the surfaces that would otherwise hand-roll the state.\n */\nexport function useCursorPage(options: UseCursorPageOptions = {}): CursorPager {\n  const { onPageChange, resetKey } = options;\n\n  // The stored page is only meaningful for the inputs it was reached under, so\n  // the key it belongs to is stored WITH it.\n  const [pageState, setPageState] = useState<{\n    page: number;\n    key: UseCursorPageOptions[\"resetKey\"];\n  }>({ page: 1, key: resetKey });\n\n  // `Object.is`, the same comparison React uses for state and deps: a `NaN` key\n  // must compare equal to itself, or the adjustment below would re-fire forever.\n  const keyMatches = Object.is(pageState.key, resetKey);\n\n  // React's \"adjusting state when a prop changes\": a new key retires the stored\n  // page, because page 4 of the old result set is not page 4 of the new one.\n  // Retiring it (rather than only ignoring it) is what makes going BACK to\n  // earlier inputs start at page 1 too, instead of reviving a dead page.\n  if (!keyMatches) {\n    setPageState({ page: 1, key: resetKey });\n  }\n  // Derived as well as adjusted, so even the render that triggers the adjustment\n  // already reports page 1 — the caller's query is never asked for a page of the\n  // new inputs that the user never navigated to.\n  const currentPage = keyMatches ? pageState.page : 1;\n\n  const goToPreviousPage = useCallback(() => {\n    if (currentPage <= 1) return;\n    setPageState({ page: currentPage - 1, key: resetKey });\n    onPageChange?.();\n  }, [currentPage, resetKey, onPageChange]);\n\n  const reset = useCallback(() => {\n    if (currentPage === 1) return;\n    setPageState({ page: 1, key: resetKey });\n    onPageChange?.();\n  }, [currentPage, resetKey, onPageChange]);\n\n  // Memoized on the page state itself, so a consumer may hold it in a dep array\n  // and it changes only when the page (or the callback/inputs) actually change.\n  const paginationFor = useCallback(\n    (hasMore: boolean): CursorPage => ({\n      currentPage,\n      canPreviousPage: currentPage > 1,\n      canNextPage: hasMore,\n      goToPreviousPage,\n      goToNextPage: () => {\n        if (!hasMore) return;\n        setPageState({ page: currentPage + 1, key: resetKey });\n        onPageChange?.();\n      },\n    }),\n    [currentPage, resetKey, onPageChange, goToPreviousPage],\n  );\n\n  return { currentPage, reset, paginationFor };\n}\n"]}

package/dist/react/hooks/use-paged-list.d.ts

@@ -8,8 +8,8 @@
  *
  * - **Known total** (client-side slice pagination — {@link usePagedList}):
  *   `totalPages` is a number and the counter reads `"2 of 5"`.
- * - **Unknown total** (server/cursor pagination — `useCursorPage`, or a
- *   caller's own query hook): `totalPages` is omitted and the counter reads
+ * - **Unknown total** (server/cursor pagination — `useCursorPage().paginationFor(hasMore)`,
+ *   or a caller's own query hook): `totalPages` is omitted and the counter reads
  *   `"Page 2"`.
  *
  * Both flavors share one visibility rule, one disabled-edge rule, one live

package/dist/react/hooks/use-paged-list.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-paged-list.js","sourceRoot":"","sources":["../../../src/react/hooks/use-paged-list.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAmDvD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAmB,EACnB,QAAgB,EAChB,UAA+B,EAAE;IAEjC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACjC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEtD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC;IACnE,6EAA6E;IAC7E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,CAAC;IAErE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE;QAC7B,MAAM,UAAU,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC;QAChD,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;IACxD,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEnC,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE;QACxC,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,gBAAgB,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAClC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAEhC,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,IAAI,WAAW,IAAI,UAAU;YAAE,OAAO;QACtC,gBAAgB,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAClC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW;QACX,UAAU;QACV,SAAS;QACT,eAAe,EAAE,WAAW,GAAG,CAAC;QAChC,WAAW,EAAE,WAAW,GAAG,UAAU;QACrC,gBAAgB;QAChB,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { useCallback, useMemo, useState } from \"react\";\n\n/**\n * The control state a paginated list exposes to its paginator UI, rendered by\n * the ONE `ListPagination` component. Nothing else builds\n * Previous / counter / Next controls.\n *\n * `totalPages` is the flavor discriminant, and the ONLY difference between the\n * two flavors:\n *\n * - **Known total** (client-side slice pagination — {@link usePagedList}):\n *   `totalPages` is a number and the counter reads `\"2 of 5\"`.\n * - **Unknown total** (server/cursor pagination — `useCursorPage`, or a\n *   caller's own query hook): `totalPages` is omitted and the counter reads\n *   `\"Page 2\"`.\n *\n * Both flavors share one visibility rule, one disabled-edge rule, one live\n * region, and one set of classes because they share one component (ENG-002,\n * FRONTEND-001).\n */\nexport interface ListPaginationState {\n  /** 1-based page currently on screen. */\n  currentPage: number;\n  /**\n   * Total page count when it is knowable — at least 1, even for an empty list\n   * (an empty list is one empty page). Omitted for cursor/`hasMore` pagination,\n   * where the total is unknown until the last page is reached.\n   */\n  totalPages?: number;\n  canPreviousPage: boolean;\n  canNextPage: boolean;\n  goToPreviousPage: () => void;\n  goToNextPage: () => void;\n}\n\nexport interface PagedList<T> extends ListPaginationState {\n  /** Always known for a slice-paginated list. */\n  totalPages: number;\n  /** The slice of `items` belonging to `currentPage`. */\n  pageItems: T[];\n}\n\nexport interface UsePagedListOptions {\n  /**\n   * Called after the page actually changed. Surfaces that keep a per-page\n   * selection (an open detail row) clear it here — the old selection is not on\n   * the new page.\n   */\n  onPageChange?: () => void;\n}\n\n/**\n * The single owner of client-side slice pagination: local page state, the page\n * math, and the current slice over an ALREADY-FETCHED list.\n *\n * Page size is the caller's — every surface passes its own page-size constant\n * (ENG-005), never a literal. Ordering and filtering stay with the caller: pass\n * the list already sorted and filtered.\n *\n * Not for server-paged lists — a cursor/`hasMore` feed pages through the\n * caller's data layer, not through a slice; use `useCursorPage` (or the query\n * hook's own page state) with the same `ListPagination` control.\n */\nexport function usePagedList<T>(\n  items: readonly T[],\n  pageSize: number,\n  options: UsePagedListOptions = {},\n): PagedList<T> {\n  const { onPageChange } = options;\n  const [requestedPage, setRequestedPage] = useState(1);\n\n  const totalPages = Math.max(1, Math.ceil(items.length / pageSize));\n  // The list can shrink under a page that is already open (an item is deleted,\n  // a filter narrows). Clamping keeps the paginator on a real page instead of\n  // rendering an empty slice under an out-of-range \"4 of 2\".\n  const currentPage = Math.min(Math.max(1, requestedPage), totalPages);\n\n  const pageItems = useMemo(() => {\n    const startIndex = (currentPage - 1) * pageSize;\n    return items.slice(startIndex, startIndex + pageSize);\n  }, [items, currentPage, pageSize]);\n\n  const goToPreviousPage = useCallback(() => {\n    if (currentPage <= 1) return;\n    setRequestedPage(currentPage - 1);\n    onPageChange?.();\n  }, [currentPage, onPageChange]);\n\n  const goToNextPage = useCallback(() => {\n    if (currentPage >= totalPages) return;\n    setRequestedPage(currentPage + 1);\n    onPageChange?.();\n  }, [currentPage, totalPages, onPageChange]);\n\n  return {\n    currentPage,\n    totalPages,\n    pageItems,\n    canPreviousPage: currentPage > 1,\n    canNextPage: currentPage < totalPages,\n    goToPreviousPage,\n    goToNextPage,\n  };\n}\n"]}
+{"version":3,"file":"use-paged-list.js","sourceRoot":"","sources":["../../../src/react/hooks/use-paged-list.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAmDvD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAmB,EACnB,QAAgB,EAChB,UAA+B,EAAE;IAEjC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACjC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEtD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC;IACnE,6EAA6E;IAC7E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,CAAC;IAErE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE;QAC7B,MAAM,UAAU,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC;QAChD,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;IACxD,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEnC,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE;QACxC,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,gBAAgB,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAClC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAEhC,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,IAAI,WAAW,IAAI,UAAU;YAAE,OAAO;QACtC,gBAAgB,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;QAClC,YAAY,EAAE,EAAE,CAAC;IACnB,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW;QACX,UAAU;QACV,SAAS;QACT,eAAe,EAAE,WAAW,GAAG,CAAC;QAChC,WAAW,EAAE,WAAW,GAAG,UAAU;QACrC,gBAAgB;QAChB,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport { useCallback, useMemo, useState } from \"react\";\n\n/**\n * The control state a paginated list exposes to its paginator UI, rendered by\n * the ONE `ListPagination` component. Nothing else builds\n * Previous / counter / Next controls.\n *\n * `totalPages` is the flavor discriminant, and the ONLY difference between the\n * two flavors:\n *\n * - **Known total** (client-side slice pagination — {@link usePagedList}):\n *   `totalPages` is a number and the counter reads `\"2 of 5\"`.\n * - **Unknown total** (server/cursor pagination — `useCursorPage().paginationFor(hasMore)`,\n *   or a caller's own query hook): `totalPages` is omitted and the counter reads\n *   `\"Page 2\"`.\n *\n * Both flavors share one visibility rule, one disabled-edge rule, one live\n * region, and one set of classes because they share one component (ENG-002,\n * FRONTEND-001).\n */\nexport interface ListPaginationState {\n  /** 1-based page currently on screen. */\n  currentPage: number;\n  /**\n   * Total page count when it is knowable — at least 1, even for an empty list\n   * (an empty list is one empty page). Omitted for cursor/`hasMore` pagination,\n   * where the total is unknown until the last page is reached.\n   */\n  totalPages?: number;\n  canPreviousPage: boolean;\n  canNextPage: boolean;\n  goToPreviousPage: () => void;\n  goToNextPage: () => void;\n}\n\nexport interface PagedList<T> extends ListPaginationState {\n  /** Always known for a slice-paginated list. */\n  totalPages: number;\n  /** The slice of `items` belonging to `currentPage`. */\n  pageItems: T[];\n}\n\nexport interface UsePagedListOptions {\n  /**\n   * Called after the page actually changed. Surfaces that keep a per-page\n   * selection (an open detail row) clear it here — the old selection is not on\n   * the new page.\n   */\n  onPageChange?: () => void;\n}\n\n/**\n * The single owner of client-side slice pagination: local page state, the page\n * math, and the current slice over an ALREADY-FETCHED list.\n *\n * Page size is the caller's — every surface passes its own page-size constant\n * (ENG-005), never a literal. Ordering and filtering stay with the caller: pass\n * the list already sorted and filtered.\n *\n * Not for server-paged lists — a cursor/`hasMore` feed pages through the\n * caller's data layer, not through a slice; use `useCursorPage` (or the query\n * hook's own page state) with the same `ListPagination` control.\n */\nexport function usePagedList<T>(\n  items: readonly T[],\n  pageSize: number,\n  options: UsePagedListOptions = {},\n): PagedList<T> {\n  const { onPageChange } = options;\n  const [requestedPage, setRequestedPage] = useState(1);\n\n  const totalPages = Math.max(1, Math.ceil(items.length / pageSize));\n  // The list can shrink under a page that is already open (an item is deleted,\n  // a filter narrows). Clamping keeps the paginator on a real page instead of\n  // rendering an empty slice under an out-of-range \"4 of 2\".\n  const currentPage = Math.min(Math.max(1, requestedPage), totalPages);\n\n  const pageItems = useMemo(() => {\n    const startIndex = (currentPage - 1) * pageSize;\n    return items.slice(startIndex, startIndex + pageSize);\n  }, [items, currentPage, pageSize]);\n\n  const goToPreviousPage = useCallback(() => {\n    if (currentPage <= 1) return;\n    setRequestedPage(currentPage - 1);\n    onPageChange?.();\n  }, [currentPage, onPageChange]);\n\n  const goToNextPage = useCallback(() => {\n    if (currentPage >= totalPages) return;\n    setRequestedPage(currentPage + 1);\n    onPageChange?.();\n  }, [currentPage, totalPages, onPageChange]);\n\n  return {\n    currentPage,\n    totalPages,\n    pageItems,\n    canPreviousPage: currentPage > 1,\n    canNextPage: currentPage < totalPages,\n    goToPreviousPage,\n    goToNextPage,\n  };\n}\n"]}

package/dist/react/hooks/use-return-scroll.d.ts

@@ -0,0 +1,26 @@
+export interface ReturnScrollEntry {
+    /** The saved `window.scrollY`. */
+    y: number;
+    /** Epoch ms at save time (diagnostic; the caller decides eligibility, not the hook). */
+    savedAt: number;
+}
+export interface UseReturnScrollOptions {
+    /** The caller's CANONICAL list URL — equivalent list states must give the same key. */
+    key: string;
+    /** Decided by the caller ONCE at mount (e.g. "the list's data was already cached on first render"). */
+    eligible: boolean;
+    /** The list is displayed at its real height: data present, no error surface in its place. */
+    ready: boolean;
+}
+export interface UseReturnScrollResult {
+    /** Record the current window offset for `key`. Call right before navigating away. */
+    save: () => void;
+}
+/** The stored entry for `key`, or null when absent, unreadable, or malformed. */
+export declare function readReturnScroll(key: string): ReturnScrollEntry | null;
+/** Record `y` (default: the current `window.scrollY`) for `key`. No-op without storage. */
+export declare function saveReturnScroll(key: string, y?: number): void;
+/** Drop the entry for `key` (e.g. the list changed underneath the saved offset). */
+export declare function clearReturnScroll(key: string): void;
+export declare function useReturnScroll({ key, eligible, ready }: UseReturnScrollOptions): UseReturnScrollResult;
+//# sourceMappingURL=use-return-scroll.d.ts.map

package/dist/react/hooks/use-return-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-return-scroll.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-return-scroll.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,CAAC,EAAE,MAAM,CAAC;IACV,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,uGAAuG;IACvG,QAAQ,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAeD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CActE;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAU9D;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAQnD;AASD,wBAAgB,eAAe,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,sBAAsB,GAAG,qBAAqB,CAuCvG"}

package/dist/react/hooks/use-return-scroll.js

@@ -0,0 +1,123 @@
+"use client";
+// Return-scroll: bring a list back to where the user left it after a REAL route change.
+//
+// A same-page view swap keeps its component mounted and can restore from a ref; a list
+// whose detail pages have their own URLs unmounts, so the offset has to survive in
+// per-tab storage and the restore has to wait until the list is displayed at its real
+// height again. This hook is the ONE owner of that mechanism. It knows nothing about
+// what the list is — the caller supplies a canonical key, decides eligibility once at
+// mount, and reports readiness.
+//
+// Contract (every rule below is tested):
+//   - `save()` writes { y, savedAt } for `key` — call it immediately before navigating
+//     away (inside any guarded-navigation callback, so a cancelled leave writes nothing).
+//   - `eligible` is latched per key the first time the hook sees that key. Not eligible
+//     ⇒ the entry is deleted immediately and permanently for that key; a later flip
+//     of `eligible` or `ready` never re-arms the restore.
+//   - `ready` ⇒ the restore fires ONCE, in a requestAnimationFrame, `behavior: "instant"`,
+//     then consumes the entry. The scheduled frame is cancelled on unmount or key change.
+//     React Strict Mode's mount/unmount/mount cancels and reschedules, so exactly one
+//     scroll happens and the entry is consumed exactly once.
+//   - Blocked, unavailable, or malformed storage is a silent no-op.
+import * as React from "react";
+const STORAGE_PREFIX = "return-scroll:";
+function storageKey(key) {
+    return `${STORAGE_PREFIX}${key}`;
+}
+function sessionStorageOrNull() {
+    try {
+        if (typeof window === "undefined")
+            return null;
+        return window.sessionStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The stored entry for `key`, or null when absent, unreadable, or malformed. */
+export function readReturnScroll(key) {
+    const storage = sessionStorageOrNull();
+    if (!storage)
+        return null;
+    try {
+        const raw = storage.getItem(storageKey(key));
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { y, savedAt } = parsed;
+        if (typeof y !== "number" || !Number.isFinite(y) || y < 0)
+            return null;
+        return { y, savedAt: typeof savedAt === "number" ? savedAt : 0 };
+    }
+    catch {
+        return null;
+    }
+}
+/** Record `y` (default: the current `window.scrollY`) for `key`. No-op without storage. */
+export function saveReturnScroll(key, y) {
+    const storage = sessionStorageOrNull();
+    if (!storage)
+        return;
+    try {
+        const offset = typeof y === "number" ? y : window.scrollY;
+        const entry = { y: offset, savedAt: Date.now() };
+        storage.setItem(storageKey(key), JSON.stringify(entry));
+    }
+    catch {
+        /* storage blocked or full — nothing to restore later, which is the honest outcome */
+    }
+}
+/** Drop the entry for `key` (e.g. the list changed underneath the saved offset). */
+export function clearReturnScroll(key) {
+    const storage = sessionStorageOrNull();
+    if (!storage)
+        return;
+    try {
+        storage.removeItem(storageKey(key));
+    }
+    catch {
+        /* nothing to clear */
+    }
+}
+export function useReturnScroll({ key, eligible, ready }) {
+    const decisionRef = React.useRef(null);
+    // Decide ONCE per key, the first time the hook sees it. Effects may read and write refs;
+    // the decision is latched, so a later `eligible` flip finds it already made and returns.
+    React.useEffect(() => {
+        if (decisionRef.current?.key === key)
+            return;
+        const entry = readReturnScroll(key);
+        if (!entry) {
+            decisionRef.current = { key, y: null, done: true };
+            return;
+        }
+        if (!eligible) {
+            // A cold return: nothing cached to restore against. Discard permanently for this visit.
+            clearReturnScroll(key);
+            decisionRef.current = { key, y: null, done: true };
+            return;
+        }
+        decisionRef.current = { key, y: entry.y, done: false };
+    }, [key, eligible]);
+    // Restore once the list is displayed at its real height. The frame is cancelled on unmount
+    // or key change; Strict Mode's re-run reschedules it, so exactly one scroll happens.
+    React.useEffect(() => {
+        const decision = decisionRef.current;
+        if (!decision || decision.key !== key || decision.y === null || decision.done || !ready)
+            return;
+        if (typeof window === "undefined")
+            return;
+        const y = decision.y;
+        const frame = window.requestAnimationFrame(() => {
+            window.scrollTo({ top: y, left: 0, behavior: "instant" });
+            clearReturnScroll(key);
+            decision.done = true;
+        });
+        return () => window.cancelAnimationFrame(frame);
+    }, [key, ready]);
+    const save = React.useCallback(() => saveReturnScroll(key), [key]);
+    return { save };
+}
+//# sourceMappingURL=use-return-scroll.js.map

package/dist/react/hooks/use-return-scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-return-scroll.js","sourceRoot":"","sources":["../../../src/react/hooks/use-return-scroll.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n// Return-scroll: bring a list back to where the user left it after a REAL route change.\n//\n// A same-page view swap keeps its component mounted and can restore from a ref; a list\n// whose detail pages have their own URLs unmounts, so the offset has to survive in\n// per-tab storage and the restore has to wait until the list is displayed at its real\n// height again. This hook is the ONE owner of that mechanism. It knows nothing about\n// what the list is — the caller supplies a canonical key, decides eligibility once at\n// mount, and reports readiness.\n//\n// Contract (every rule below is tested):\n//   - `save()` writes { y, savedAt } for `key` — call it immediately before navigating\n//     away (inside any guarded-navigation callback, so a cancelled leave writes nothing).\n//   - `eligible` is latched per key the first time the hook sees that key. Not eligible\n//     ⇒ the entry is deleted immediately and permanently for that key; a later flip\n//     of `eligible` or `ready` never re-arms the restore.\n//   - `ready` ⇒ the restore fires ONCE, in a requestAnimationFrame, `behavior: \"instant\"`,\n//     then consumes the entry. The scheduled frame is cancelled on unmount or key change.\n//     React Strict Mode's mount/unmount/mount cancels and reschedules, so exactly one\n//     scroll happens and the entry is consumed exactly once.\n//   - Blocked, unavailable, or malformed storage is a silent no-op.\n\nimport * as React from \"react\";\n\nconst STORAGE_PREFIX = \"return-scroll:\";\n\nexport interface ReturnScrollEntry {\n  /** The saved `window.scrollY`. */\n  y: number;\n  /** Epoch ms at save time (diagnostic; the caller decides eligibility, not the hook). */\n  savedAt: number;\n}\n\nexport interface UseReturnScrollOptions {\n  /** The caller's CANONICAL list URL — equivalent list states must give the same key. */\n  key: string;\n  /** Decided by the caller ONCE at mount (e.g. \"the list's data was already cached on first render\"). */\n  eligible: boolean;\n  /** The list is displayed at its real height: data present, no error surface in its place. */\n  ready: boolean;\n}\n\nexport interface UseReturnScrollResult {\n  /** Record the current window offset for `key`. Call right before navigating away. */\n  save: () => void;\n}\n\nfunction storageKey(key: string): string {\n  return `${STORAGE_PREFIX}${key}`;\n}\n\nfunction sessionStorageOrNull(): Storage | null {\n  try {\n    if (typeof window === \"undefined\") return null;\n    return window.sessionStorage ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/** The stored entry for `key`, or null when absent, unreadable, or malformed. */\nexport function readReturnScroll(key: string): ReturnScrollEntry | null {\n  const storage = sessionStorageOrNull();\n  if (!storage) return null;\n  try {\n    const raw = storage.getItem(storageKey(key));\n    if (!raw) return null;\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed !== \"object\" || parsed === null) return null;\n    const { y, savedAt } = parsed as { y?: unknown; savedAt?: unknown };\n    if (typeof y !== \"number\" || !Number.isFinite(y) || y < 0) return null;\n    return { y, savedAt: typeof savedAt === \"number\" ? savedAt : 0 };\n  } catch {\n    return null;\n  }\n}\n\n/** Record `y` (default: the current `window.scrollY`) for `key`. No-op without storage. */\nexport function saveReturnScroll(key: string, y?: number): void {\n  const storage = sessionStorageOrNull();\n  if (!storage) return;\n  try {\n    const offset = typeof y === \"number\" ? y : window.scrollY;\n    const entry: ReturnScrollEntry = { y: offset, savedAt: Date.now() };\n    storage.setItem(storageKey(key), JSON.stringify(entry));\n  } catch {\n    /* storage blocked or full — nothing to restore later, which is the honest outcome */\n  }\n}\n\n/** Drop the entry for `key` (e.g. the list changed underneath the saved offset). */\nexport function clearReturnScroll(key: string): void {\n  const storage = sessionStorageOrNull();\n  if (!storage) return;\n  try {\n    storage.removeItem(storageKey(key));\n  } catch {\n    /* nothing to clear */\n  }\n}\n\ninterface Decision {\n  key: string;\n  /** The offset to restore, or null when this key's return is not restorable. */\n  y: number | null;\n  done: boolean;\n}\n\nexport function useReturnScroll({ key, eligible, ready }: UseReturnScrollOptions): UseReturnScrollResult {\n  const decisionRef = React.useRef<Decision | null>(null);\n\n  // Decide ONCE per key, the first time the hook sees it. Effects may read and write refs;\n  // the decision is latched, so a later `eligible` flip finds it already made and returns.\n  React.useEffect(() => {\n    if (decisionRef.current?.key === key) return;\n    const entry = readReturnScroll(key);\n    if (!entry) {\n      decisionRef.current = { key, y: null, done: true };\n      return;\n    }\n    if (!eligible) {\n      // A cold return: nothing cached to restore against. Discard permanently for this visit.\n      clearReturnScroll(key);\n      decisionRef.current = { key, y: null, done: true };\n      return;\n    }\n    decisionRef.current = { key, y: entry.y, done: false };\n  }, [key, eligible]);\n\n  // Restore once the list is displayed at its real height. The frame is cancelled on unmount\n  // or key change; Strict Mode's re-run reschedules it, so exactly one scroll happens.\n  React.useEffect(() => {\n    const decision = decisionRef.current;\n    if (!decision || decision.key !== key || decision.y === null || decision.done || !ready) return;\n    if (typeof window === \"undefined\") return;\n    const y = decision.y;\n    const frame = window.requestAnimationFrame(() => {\n      window.scrollTo({ top: y, left: 0, behavior: \"instant\" as ScrollBehavior });\n      clearReturnScroll(key);\n      decision.done = true;\n    });\n    return () => window.cancelAnimationFrame(frame);\n  }, [key, ready]);\n\n  const save = React.useCallback(() => saveReturnScroll(key), [key]);\n\n  return { save };\n}\n"]}

package/dist/react/index.d.ts

@@ -56,5 +56,7 @@ export type { ListPaginationProps } from "./components/list-pagination.js";
 export { usePagedList } from "./hooks/use-paged-list.js";
 export type { ListPaginationState, PagedList, UsePagedListOptions } from "./hooks/use-paged-list.js";
 export { useCursorPage } from "./hooks/use-cursor-page.js";
-export type { CursorPage, UseCursorPageOptions } from "./hooks/use-cursor-page.js";
+export type { CursorPage, CursorPager, UseCursorPageOptions } from "./hooks/use-cursor-page.js";
+export { useReturnScroll, saveReturnScroll, clearReturnScroll, readReturnScroll } from "./hooks/use-return-scroll.js";
+export type { ReturnScrollEntry, UseReturnScrollOptions, UseReturnScrollResult } from "./hooks/use-return-scroll.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7G,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACpL,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC1W,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACtS,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAChQ,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC5E,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACnI,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChM,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACrI,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACjI,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzK,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAClG,YAAY,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,kCAAkC,EAAE,MAAM,oCAAoC,CAAC;AAC9I,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAEvE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAErF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACzE,YAAY,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAIpF,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErG,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -46,4 +46,8 @@ export { ChunkErrorRecovery } from "./components/chunk-error-recovery.js";
 export { ListPagination } from "./components/list-pagination.js";
 export { usePagedList } from "./hooks/use-paged-list.js";
 export { useCursorPage } from "./hooks/use-cursor-page.js";
+// Return-scroll: restore a list's window offset when the user comes back to it after a
+// route change (save on leave, restore once on an eligible + ready return, keyed by the
+// caller's canonical list URL).
+export { useReturnScroll, saveReturnScroll, clearReturnScroll, readReturnScroll } from "./hooks/use-return-scroll.js";
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nexport type { ButtonProps } from \"./components/button.js\";\nexport { Button, buttonVariants } from \"./components/button.js\";\nexport { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from \"./components/card.js\";\nexport { Label } from \"./components/label.js\";\nexport { Textarea } from \"./components/textarea.js\";\nexport { Skeleton } from \"./components/skeleton.js\";\nexport { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription } from \"./components/dialog.js\";\nexport { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from \"./components/popover.js\";\nexport { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from \"./components/dropdown-menu.js\";\nexport { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarPortal, MenubarSubContent, MenubarSubTrigger, MenubarGroup, MenubarSub, MenubarShortcut } from \"./components/menubar.js\";\nexport { AlertDialog, AlertDialogPortal, AlertDialogOverlay, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel } from \"./components/alert-dialog.js\";\nexport { Alert, AlertTitle, AlertDescription } from \"./components/alert.js\";\nexport type { ToastProps, ToastActionElement } from \"./components/toast.js\";\nexport { ToastProvider, ToastViewport, Toast, ToastTitle, ToastDescription, ToastClose, ToastAction } from \"./components/toast.js\";\nexport { Toaster } from \"./components/toaster.js\";\nexport type { ToastVariant, ToasterToast } from \"./hooks/use-toast.js\";\nexport { toast, useToast } from \"./hooks/use-toast.js\";\nexport { Input } from \"./components/input.js\";\nexport { Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton } from \"./components/select.js\";\nexport { Tabs, TabsList, TabsTrigger, TabsContent } from \"./components/tabs.js\";\nexport { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from \"./components/tooltip.js\";\nexport { useFormField, Form, FormItem, FormLabel, FormControl, FormDescription, FormMessage, FormField } from \"./components/form.js\";\nexport { Checkbox } from \"./components/checkbox.js\";\nexport { Switch } from \"./components/switch.js\";\nexport type { BadgeProps } from \"./components/badge.js\";\nexport { Badge, badgeVariants } from \"./components/badge.js\";\nexport { Avatar, AvatarImage, AvatarFallback } from \"./components/avatar.js\";\nexport { Separator } from \"./components/separator.js\";\nexport { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from \"./components/accordion.js\";\nexport { RadioGroup, RadioGroupItem } from \"./components/radio-group.js\";\nexport { Progress } from \"./components/progress.js\";\nexport { Slider } from \"./components/slider.js\";\nexport type { DatePickerProps } from \"./components/date-picker.js\";\nexport { DatePicker } from \"./components/date-picker.js\";\nexport { ScrollArea, ScrollBar } from \"./components/scroll-area.js\";\nexport { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption } from \"./components/table.js\";\nexport { Sheet, SheetPortal, SheetOverlay, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription } from \"./components/sheet.js\";\nexport { Collapsible, CollapsibleTrigger, CollapsibleContent } from \"./components/collapsible.js\";\nexport type { SearchDropdownProps } from \"./components/search-dropdown.js\";\nexport { SearchDropdown } from \"./components/search-dropdown.js\";\n\nexport type { ConsequenceDialogProps, ConsequenceDialogReason, ConsequenceDialogTypedConfirmation } from \"./components/consequence-dialog.js\";\nexport { ConsequenceDialog } from \"./components/consequence-dialog.js\";\n\nexport type { MaxWidthOption, ScreenAdaptiveViewProps } from \"./components/layout/screen-adaptive-view.js\";\nexport { ScreenAdaptiveView } from \"./components/layout/screen-adaptive-view.js\";\n\nexport { useMediaQuery } from \"./hooks/use-media-query.js\";\n\n// Shared building blocks\nexport { RelativeTime } from \"./components/relative-time.js\";\nexport type { RelativeTimeProps } from \"./components/relative-time.js\";\n\nexport { EndOfListIndicator } from \"./components/end-of-list-indicator.js\";\nexport type { EndOfListIndicatorProps } from \"./components/end-of-list-indicator.js\";\n\nexport { ScrollToTopButton } from \"./components/scroll-to-top-button.js\";\nexport type { ScrollToTopButtonProps } from \"./components/scroll-to-top-button.js\";\n\nexport { ChunkErrorRecovery } from \"./components/chunk-error-recovery.js\";\nexport type { ChunkErrorRecoveryProps } from \"./components/chunk-error-recovery.js\";\n\n// List pagination — the one Previous / counter / Next control plus the page-state\n// hooks for its two flavors (known total, and cursor/`hasMore`).\nexport { ListPagination } from \"./components/list-pagination.js\";\nexport type { ListPaginationProps } from \"./components/list-pagination.js\";\n\nexport { usePagedList } from \"./hooks/use-paged-list.js\";\nexport type { ListPaginationState, PagedList, UsePagedListOptions } from \"./hooks/use-paged-list.js\";\n\nexport { useCursorPage } from \"./hooks/use-cursor-page.js\";\nexport type { CursorPage, UseCursorPageOptions } from \"./hooks/use-cursor-page.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nexport type { ButtonProps } from \"./components/button.js\";\nexport { Button, buttonVariants } from \"./components/button.js\";\nexport { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from \"./components/card.js\";\nexport { Label } from \"./components/label.js\";\nexport { Textarea } from \"./components/textarea.js\";\nexport { Skeleton } from \"./components/skeleton.js\";\nexport { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription } from \"./components/dialog.js\";\nexport { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from \"./components/popover.js\";\nexport { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from \"./components/dropdown-menu.js\";\nexport { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarPortal, MenubarSubContent, MenubarSubTrigger, MenubarGroup, MenubarSub, MenubarShortcut } from \"./components/menubar.js\";\nexport { AlertDialog, AlertDialogPortal, AlertDialogOverlay, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel } from \"./components/alert-dialog.js\";\nexport { Alert, AlertTitle, AlertDescription } from \"./components/alert.js\";\nexport type { ToastProps, ToastActionElement } from \"./components/toast.js\";\nexport { ToastProvider, ToastViewport, Toast, ToastTitle, ToastDescription, ToastClose, ToastAction } from \"./components/toast.js\";\nexport { Toaster } from \"./components/toaster.js\";\nexport type { ToastVariant, ToasterToast } from \"./hooks/use-toast.js\";\nexport { toast, useToast } from \"./hooks/use-toast.js\";\nexport { Input } from \"./components/input.js\";\nexport { Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton } from \"./components/select.js\";\nexport { Tabs, TabsList, TabsTrigger, TabsContent } from \"./components/tabs.js\";\nexport { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from \"./components/tooltip.js\";\nexport { useFormField, Form, FormItem, FormLabel, FormControl, FormDescription, FormMessage, FormField } from \"./components/form.js\";\nexport { Checkbox } from \"./components/checkbox.js\";\nexport { Switch } from \"./components/switch.js\";\nexport type { BadgeProps } from \"./components/badge.js\";\nexport { Badge, badgeVariants } from \"./components/badge.js\";\nexport { Avatar, AvatarImage, AvatarFallback } from \"./components/avatar.js\";\nexport { Separator } from \"./components/separator.js\";\nexport { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from \"./components/accordion.js\";\nexport { RadioGroup, RadioGroupItem } from \"./components/radio-group.js\";\nexport { Progress } from \"./components/progress.js\";\nexport { Slider } from \"./components/slider.js\";\nexport type { DatePickerProps } from \"./components/date-picker.js\";\nexport { DatePicker } from \"./components/date-picker.js\";\nexport { ScrollArea, ScrollBar } from \"./components/scroll-area.js\";\nexport { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption } from \"./components/table.js\";\nexport { Sheet, SheetPortal, SheetOverlay, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription } from \"./components/sheet.js\";\nexport { Collapsible, CollapsibleTrigger, CollapsibleContent } from \"./components/collapsible.js\";\nexport type { SearchDropdownProps } from \"./components/search-dropdown.js\";\nexport { SearchDropdown } from \"./components/search-dropdown.js\";\n\nexport type { ConsequenceDialogProps, ConsequenceDialogReason, ConsequenceDialogTypedConfirmation } from \"./components/consequence-dialog.js\";\nexport { ConsequenceDialog } from \"./components/consequence-dialog.js\";\n\nexport type { MaxWidthOption, ScreenAdaptiveViewProps } from \"./components/layout/screen-adaptive-view.js\";\nexport { ScreenAdaptiveView } from \"./components/layout/screen-adaptive-view.js\";\n\nexport { useMediaQuery } from \"./hooks/use-media-query.js\";\n\n// Shared building blocks\nexport { RelativeTime } from \"./components/relative-time.js\";\nexport type { RelativeTimeProps } from \"./components/relative-time.js\";\n\nexport { EndOfListIndicator } from \"./components/end-of-list-indicator.js\";\nexport type { EndOfListIndicatorProps } from \"./components/end-of-list-indicator.js\";\n\nexport { ScrollToTopButton } from \"./components/scroll-to-top-button.js\";\nexport type { ScrollToTopButtonProps } from \"./components/scroll-to-top-button.js\";\n\nexport { ChunkErrorRecovery } from \"./components/chunk-error-recovery.js\";\nexport type { ChunkErrorRecoveryProps } from \"./components/chunk-error-recovery.js\";\n\n// List pagination — the one Previous / counter / Next control plus the page-state\n// hooks for its two flavors (known total, and cursor/`hasMore`).\nexport { ListPagination } from \"./components/list-pagination.js\";\nexport type { ListPaginationProps } from \"./components/list-pagination.js\";\n\nexport { usePagedList } from \"./hooks/use-paged-list.js\";\nexport type { ListPaginationState, PagedList, UsePagedListOptions } from \"./hooks/use-paged-list.js\";\n\nexport { useCursorPage } from \"./hooks/use-cursor-page.js\";\nexport type { CursorPage, CursorPager, UseCursorPageOptions } from \"./hooks/use-cursor-page.js\";\n\n// Return-scroll: restore a list's window offset when the user comes back to it after a\n// route change (save on leave, restore once on an eligible + ready return, keyed by the\n// caller's canonical list URL).\nexport { useReturnScroll, saveReturnScroll, clearReturnScroll, readReturnScroll } from \"./hooks/use-return-scroll.js\";\nexport type { ReturnScrollEntry, UseReturnScrollOptions, UseReturnScrollResult } from \"./hooks/use-return-scroll.js\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/ui-core",
-  "version": "0.11.11",
+  "version": "0.11.14",
   "description": "Shared UI components for TTT Productions projects",
   "repository": {
     "type": "git",
@@ -49,7 +49,7 @@
     "react-dom": ">=19.0.0",
     "react-hook-form": ">=7.0.0",
     "@hookform/resolvers": ">=3.0.0",
-    "@ttt-productions/firebase-helpers": "^0.12.4"
+    "@ttt-productions/firebase-helpers": "^0.12.7"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -99,7 +99,7 @@
     "typescript": "^5.8.3",
     "react-hook-form": "^7.69.0",
     "@hookform/resolvers": "^5.2.2",
-    "@ttt-productions/firebase-helpers": "^0.12.4"
+    "@ttt-productions/firebase-helpers": "^0.12.7"
   },
   "author": "DJ (TTT Productions)",
   "license": "MIT"

package/src/react/components/list-pagination.tsx

@@ -7,8 +7,9 @@ import type { ListPaginationState } from "../hooks/use-paged-list.js";
 
 export interface ListPaginationProps {
   /**
-   * Page state from `usePagedList` (known total), `useCursorPage` (unknown
-   * total), or any caller-owned state of the same shape.
+   * Page state from `usePagedList` (known total),
+   * `useCursorPage().paginationFor(hasMore)` (unknown total), or any
+   * caller-owned state of the same shape.
    */
   pagination: ListPaginationState;
   /**
@@ -25,8 +26,9 @@ export interface ListPaginationProps {
  * The ONE Previous / counter / Next control for paginated lists, in both
  * flavors. Pair it with the hook that owns the page state (`usePagedList` for a
  * client-side slice, `useCursorPage` — or the caller's own query state — for a
- * cursor feed); this component owns only the controls, so every paginated list
- * reads and behaves the same (ENG-002, FRONTEND-001).
+ * cursor feed; a cursor feed passes `pager.paginationFor(hasMore)`, which binds
+ * the query's answer to these controls); this component owns only the controls,
+ * so every paginated list reads and behaves the same (ENG-002, FRONTEND-001).
  *
  * The counter follows the flavor: a known `totalPages` reads "2 of 5", an
  * omitted one reads "Page 2". Everything else is identical in both flavors —

package/src/react/hooks/use-cursor-page.ts

@@ -3,70 +3,137 @@
 import { useCallback, useState } from "react";
 import type { ListPaginationState } from "./use-paged-list.js";
 
+/**
+ * Render-time page state for a cursor feed, shaped as {@link ListPaginationState}
+ * so it drops straight into the ONE `ListPagination` control. Produced by
+ * {@link CursorPager.paginationFor} once the query for `currentPage` has
+ * answered with its `hasMore`.
+ */
 export interface CursorPage extends ListPaginationState {
   /** Never known for cursor pagination — the counter reads "Page N". */
   totalPages?: undefined;
-  /**
-   * Return to page 1 without walking back. Call it whenever the underlying
-   * query's inputs change (a new filter, a new tag, a new sort) — page 4 of the
-   * old result set is not page 4 of the new one.
-   */
-  reset: () => void;
 }
 
 export interface UseCursorPageOptions {
   /** Called after the page actually changed. Same contract as `usePagedList`. */
   onPageChange?: () => void;
+  /**
+   * A snapshot of the query inputs the page number belongs to — a tag, a filter,
+   * a sort. When it changes, the page is 1 again **in the same render**, so the
+   * query never fires for "page 4" of inputs whose page 4 may not exist.
+   *
+   * Use this when the input change arrives as a prop (there is no event handler
+   * of yours to hang the reset on); use {@link CursorPager.reset} when your own
+   * handler already owns the change. Compose several inputs into one string
+   * (`` `${type}|${projectId ?? ""}` ``) — the type is deliberately narrowed to
+   * primitives so a fresh object literal cannot pin the list to page 1 forever.
+   */
+  resetKey?: string | number | boolean | null;
+}
+
+/**
+ * What {@link useCursorPage} owns: the page number, the guarded step controls,
+ * and the return-to-page-1 control.
+ */
+export interface CursorPager {
+  /** 1-based page to feed into the paged query. */
+  currentPage: number;
+  /**
+   * Return to page 1 without walking back. Call it from the handler that changes
+   * the query's inputs (a new filter, a new tag, a new sort) — page 4 of the old
+   * result set is not page 4 of the new one. A no-op on page 1, so it never
+   * fires `onPageChange` for nothing.
+   */
+  reset: () => void;
+  /**
+   * Bind the query's answer to the controls: pass the `hasMore` that came back
+   * for {@link currentPage} and render the result as
+   * `<ListPagination pagination={…} />`. `hasMore` binds HERE, after the query,
+   * because that is the only moment it exists — a cursor query needs
+   * `currentPage` as its input, so `hasMore` cannot be an argument to the hook
+   * that produces `currentPage`.
+   */
+  paginationFor: (hasMore: boolean) => CursorPage;
 }
 
 /**
  * Page state for a server-paged (cursor / `hasMore`) list: the 1-based page
- * number plus guarded step controls, shaped as {@link ListPaginationState} so it
- * drops straight into the ONE `ListPagination` control.
+ * number, the guarded step controls, and the reset — the pieces each
+ * server-paged surface was otherwise re-declaring as a local `useState(1)` plus
+ * its own clamped increment/decrement and its own "reset when the filter
+ * changed" adjustment (ENG-002, ENG-003).
+ *
+ * The data stays the caller's, and the two halves bind at different moments:
+ *
+ * ```tsx
+ * const pager = useCursorPage({ resetKey: tag });
+ * const { data, isFetching } = useThingsByTag(tag, pager.currentPage);
+ * …
+ * <ListPagination pagination={pager.paginationFor(data?.hasMore ?? false)} busy={isFetching} />
+ * ```
  *
- * The caller owns the data: it feeds `hasMore` from its query and passes
- * `currentPage` back into that query. This hook owns only the page number — the
- * piece each server-paged surface was otherwise re-declaring as a local
- * `useState(1)` plus its own clamped increment/decrement (ENG-002, ENG-003).
+ * The guards live in here, not at the call site: a step that cannot move the
+ * page changes nothing and does not fire `onPageChange`.
  *
  * A surface whose data hook ALREADY owns its page state (it returns
  * `page`/`hasNextPage`/`nextPage`/`prevPage` itself) does not need this hook —
- * it maps those fields onto `ListPaginationState` directly. The hook exists for
- * the surfaces that would otherwise hand-roll the state.
+ * it maps those fields onto {@link ListPaginationState} directly. The hook
+ * exists for the surfaces that would otherwise hand-roll the state.
  */
-export function useCursorPage(
-  hasMore: boolean,
-  options: UseCursorPageOptions = {},
-): CursorPage {
-  const { onPageChange } = options;
-  const [currentPage, setCurrentPage] = useState(1);
+export function useCursorPage(options: UseCursorPageOptions = {}): CursorPager {
+  const { onPageChange, resetKey } = options;
+
+  // The stored page is only meaningful for the inputs it was reached under, so
+  // the key it belongs to is stored WITH it.
+  const [pageState, setPageState] = useState<{
+    page: number;
+    key: UseCursorPageOptions["resetKey"];
+  }>({ page: 1, key: resetKey });
+
+  // `Object.is`, the same comparison React uses for state and deps: a `NaN` key
+  // must compare equal to itself, or the adjustment below would re-fire forever.
+  const keyMatches = Object.is(pageState.key, resetKey);
+
+  // React's "adjusting state when a prop changes": a new key retires the stored
+  // page, because page 4 of the old result set is not page 4 of the new one.
+  // Retiring it (rather than only ignoring it) is what makes going BACK to
+  // earlier inputs start at page 1 too, instead of reviving a dead page.
+  if (!keyMatches) {
+    setPageState({ page: 1, key: resetKey });
+  }
+  // Derived as well as adjusted, so even the render that triggers the adjustment
+  // already reports page 1 — the caller's query is never asked for a page of the
+  // new inputs that the user never navigated to.
+  const currentPage = keyMatches ? pageState.page : 1;
 
-  // Guards live here, not at the call site: a click that cannot move the page
-  // must not fire `onPageChange` and must not push the page past the data.
   const goToPreviousPage = useCallback(() => {
     if (currentPage <= 1) return;
-    setCurrentPage(currentPage - 1);
+    setPageState({ page: currentPage - 1, key: resetKey });
     onPageChange?.();
-  }, [currentPage, onPageChange]);
-
-  const goToNextPage = useCallback(() => {
-    if (!hasMore) return;
-    setCurrentPage(currentPage + 1);
-    onPageChange?.();
-  }, [currentPage, hasMore, onPageChange]);
+  }, [currentPage, resetKey, onPageChange]);
 
   const reset = useCallback(() => {
     if (currentPage === 1) return;
-    setCurrentPage(1);
+    setPageState({ page: 1, key: resetKey });
     onPageChange?.();
-  }, [currentPage, onPageChange]);
+  }, [currentPage, resetKey, onPageChange]);
+
+  // Memoized on the page state itself, so a consumer may hold it in a dep array
+  // and it changes only when the page (or the callback/inputs) actually change.
+  const paginationFor = useCallback(
+    (hasMore: boolean): CursorPage => ({
+      currentPage,
+      canPreviousPage: currentPage > 1,
+      canNextPage: hasMore,
+      goToPreviousPage,
+      goToNextPage: () => {
+        if (!hasMore) return;
+        setPageState({ page: currentPage + 1, key: resetKey });
+        onPageChange?.();
+      },
+    }),
+    [currentPage, resetKey, onPageChange, goToPreviousPage],
+  );
 
-  return {
-    currentPage,
-    canPreviousPage: currentPage > 1,
-    canNextPage: hasMore,
-    goToPreviousPage,
-    goToNextPage,
-    reset,
-  };
+  return { currentPage, reset, paginationFor };
 }

package/src/react/hooks/use-paged-list.ts

@@ -12,8 +12,8 @@ import { useCallback, useMemo, useState } from "react";
  *
  * - **Known total** (client-side slice pagination — {@link usePagedList}):
  *   `totalPages` is a number and the counter reads `"2 of 5"`.
- * - **Unknown total** (server/cursor pagination — `useCursorPage`, or a
- *   caller's own query hook): `totalPages` is omitted and the counter reads
+ * - **Unknown total** (server/cursor pagination — `useCursorPage().paginationFor(hasMore)`,
+ *   or a caller's own query hook): `totalPages` is omitted and the counter reads
  *   `"Page 2"`.
  *
  * Both flavors share one visibility rule, one disabled-edge rule, one live

package/src/react/hooks/use-return-scroll.ts

@@ -0,0 +1,149 @@
+"use client";
+
+// Return-scroll: bring a list back to where the user left it after a REAL route change.
+//
+// A same-page view swap keeps its component mounted and can restore from a ref; a list
+// whose detail pages have their own URLs unmounts, so the offset has to survive in
+// per-tab storage and the restore has to wait until the list is displayed at its real
+// height again. This hook is the ONE owner of that mechanism. It knows nothing about
+// what the list is — the caller supplies a canonical key, decides eligibility once at
+// mount, and reports readiness.
+//
+// Contract (every rule below is tested):
+//   - `save()` writes { y, savedAt } for `key` — call it immediately before navigating
+//     away (inside any guarded-navigation callback, so a cancelled leave writes nothing).
+//   - `eligible` is latched per key the first time the hook sees that key. Not eligible
+//     ⇒ the entry is deleted immediately and permanently for that key; a later flip
+//     of `eligible` or `ready` never re-arms the restore.
+//   - `ready` ⇒ the restore fires ONCE, in a requestAnimationFrame, `behavior: "instant"`,
+//     then consumes the entry. The scheduled frame is cancelled on unmount or key change.
+//     React Strict Mode's mount/unmount/mount cancels and reschedules, so exactly one
+//     scroll happens and the entry is consumed exactly once.
+//   - Blocked, unavailable, or malformed storage is a silent no-op.
+
+import * as React from "react";
+
+const STORAGE_PREFIX = "return-scroll:";
+
+export interface ReturnScrollEntry {
+  /** The saved `window.scrollY`. */
+  y: number;
+  /** Epoch ms at save time (diagnostic; the caller decides eligibility, not the hook). */
+  savedAt: number;
+}
+
+export interface UseReturnScrollOptions {
+  /** The caller's CANONICAL list URL — equivalent list states must give the same key. */
+  key: string;
+  /** Decided by the caller ONCE at mount (e.g. "the list's data was already cached on first render"). */
+  eligible: boolean;
+  /** The list is displayed at its real height: data present, no error surface in its place. */
+  ready: boolean;
+}
+
+export interface UseReturnScrollResult {
+  /** Record the current window offset for `key`. Call right before navigating away. */
+  save: () => void;
+}
+
+function storageKey(key: string): string {
+  return `${STORAGE_PREFIX}${key}`;
+}
+
+function sessionStorageOrNull(): Storage | null {
+  try {
+    if (typeof window === "undefined") return null;
+    return window.sessionStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The stored entry for `key`, or null when absent, unreadable, or malformed. */
+export function readReturnScroll(key: string): ReturnScrollEntry | null {
+  const storage = sessionStorageOrNull();
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(storageKey(key));
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const { y, savedAt } = parsed as { y?: unknown; savedAt?: unknown };
+    if (typeof y !== "number" || !Number.isFinite(y) || y < 0) return null;
+    return { y, savedAt: typeof savedAt === "number" ? savedAt : 0 };
+  } catch {
+    return null;
+  }
+}
+
+/** Record `y` (default: the current `window.scrollY`) for `key`. No-op without storage. */
+export function saveReturnScroll(key: string, y?: number): void {
+  const storage = sessionStorageOrNull();
+  if (!storage) return;
+  try {
+    const offset = typeof y === "number" ? y : window.scrollY;
+    const entry: ReturnScrollEntry = { y: offset, savedAt: Date.now() };
+    storage.setItem(storageKey(key), JSON.stringify(entry));
+  } catch {
+    /* storage blocked or full — nothing to restore later, which is the honest outcome */
+  }
+}
+
+/** Drop the entry for `key` (e.g. the list changed underneath the saved offset). */
+export function clearReturnScroll(key: string): void {
+  const storage = sessionStorageOrNull();
+  if (!storage) return;
+  try {
+    storage.removeItem(storageKey(key));
+  } catch {
+    /* nothing to clear */
+  }
+}
+
+interface Decision {
+  key: string;
+  /** The offset to restore, or null when this key's return is not restorable. */
+  y: number | null;
+  done: boolean;
+}
+
+export function useReturnScroll({ key, eligible, ready }: UseReturnScrollOptions): UseReturnScrollResult {
+  const decisionRef = React.useRef<Decision | null>(null);
+
+  // Decide ONCE per key, the first time the hook sees it. Effects may read and write refs;
+  // the decision is latched, so a later `eligible` flip finds it already made and returns.
+  React.useEffect(() => {
+    if (decisionRef.current?.key === key) return;
+    const entry = readReturnScroll(key);
+    if (!entry) {
+      decisionRef.current = { key, y: null, done: true };
+      return;
+    }
+    if (!eligible) {
+      // A cold return: nothing cached to restore against. Discard permanently for this visit.
+      clearReturnScroll(key);
+      decisionRef.current = { key, y: null, done: true };
+      return;
+    }
+    decisionRef.current = { key, y: entry.y, done: false };
+  }, [key, eligible]);
+
+  // Restore once the list is displayed at its real height. The frame is cancelled on unmount
+  // or key change; Strict Mode's re-run reschedules it, so exactly one scroll happens.
+  React.useEffect(() => {
+    const decision = decisionRef.current;
+    if (!decision || decision.key !== key || decision.y === null || decision.done || !ready) return;
+    if (typeof window === "undefined") return;
+    const y = decision.y;
+    const frame = window.requestAnimationFrame(() => {
+      window.scrollTo({ top: y, left: 0, behavior: "instant" as ScrollBehavior });
+      clearReturnScroll(key);
+      decision.done = true;
+    });
+    return () => window.cancelAnimationFrame(frame);
+  }, [key, ready]);
+
+  const save = React.useCallback(() => saveReturnScroll(key), [key]);
+
+  return { save };
+}

package/src/react/index.ts

@@ -71,4 +71,10 @@ export { usePagedList } from "./hooks/use-paged-list.js";
 export type { ListPaginationState, PagedList, UsePagedListOptions } from "./hooks/use-paged-list.js";
 
 export { useCursorPage } from "./hooks/use-cursor-page.js";
-export type { CursorPage, UseCursorPageOptions } from "./hooks/use-cursor-page.js";
+export type { CursorPage, CursorPager, UseCursorPageOptions } from "./hooks/use-cursor-page.js";
+
+// Return-scroll: restore a list's window offset when the user comes back to it after a
+// route change (save on leave, restore once on an eligible + ready return, keyed by the
+// caller's canonical list URL).
+export { useReturnScroll, saveReturnScroll, clearReturnScroll, readReturnScroll } from "./hooks/use-return-scroll.js";
+export type { ReturnScrollEntry, UseReturnScrollOptions, UseReturnScrollResult } from "./hooks/use-return-scroll.js";