@ttt-productions/ui-core 0.11.9 → 0.11.11

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

@@ -0,0 +1,34 @@
+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.
+     */
+    pagination: ListPaginationState;
+    /**
+     * Disables BOTH controls while the next page is in flight, without hiding the
+     * row. Server-paged surfaces pass their query's `isFetching`; a slice-paged
+     * list has nothing to wait for and omits it.
+     */
+    busy?: boolean;
+    /** Optional extra classes. Merged with the component's own classes. */
+    className?: string;
+}
+/**
+ * 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).
+ *
+ * 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 —
+ * which is exactly why there is one component and not two.
+ *
+ * It renders NOTHING when neither direction is available, so no call site
+ * repeats a `totalPages > 1` / `page > 1 || hasMore` guard. Edge state is real
+ * `disabled` on the buttons (announced, and unclickable), and the counter is a
+ * `status` live region so a page change is announced to screen readers.
+ */
+export declare function ListPagination({ pagination, busy, className }: ListPaginationProps): import("react").JSX.Element | null;
+//# sourceMappingURL=list-pagination.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { Button } from "./button.js";
+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).
+ *
+ * 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 —
+ * which is exactly why there is one component and not two.
+ *
+ * It renders NOTHING when neither direction is available, so no call site
+ * repeats a `totalPages > 1` / `page > 1 || hasMore` guard. Edge state is real
+ * `disabled` on the buttons (announced, and unclickable), and the counter is a
+ * `status` live region so a page change is announced to screen readers.
+ */
+export function ListPagination({ pagination, busy = false, className }) {
+    const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } = pagination;
+    // One visibility rule for both flavors. For a known total this is exactly
+    // `totalPages > 1`: page state is clamped into `1..totalPages`, so a
+    // single-page list has no reachable neighbour in either direction, and a
+    // multi-page list always has one. For a cursor feed it is the hand-rolled
+    // `page > 1 || hasMore`. `busy` deliberately does not hide the row — the
+    // controls grey out in place instead of vanishing mid-fetch.
+    if (!canPreviousPage && !canNextPage)
+        return null;
+    return (_jsxs("div", { className: cn("flex w-full items-center justify-between gap-4 mt-4", className), children: [_jsxs(Button, { variant: "outline", size: "sm", onClick: goToPreviousPage, disabled: busy || !canPreviousPage, className: "h-11 min-w-11", children: [_jsx(ChevronLeft, { className: "icon-xs mr-1" }), "Previous"] }), _jsx("span", { className: "text-counter", role: "status", children: totalPages === undefined ? `Page ${currentPage}` : `${currentPage} of ${totalPages}` }), _jsxs(Button, { variant: "outline", size: "sm", onClick: goToNextPage, disabled: busy || !canNextPage, className: "h-11 min-w-11", children: ["Next", _jsx(ChevronRight, { className: "icon-xs ml-1" })] })] }));
+}
+//# sourceMappingURL=list-pagination.js.map

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

@@ -0,0 +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"]}

package/dist/react/components/scroll-to-top-button.d.ts

@@ -6,9 +6,10 @@ import { type ButtonProps } from "./button.js";
  * consumer can never route them through the passthrough channel: `aria-label`
  * is set via {@link ScrollToTopButtonProps.ariaLabel}, extra classes via the
  * merge-aware {@link ScrollToTopButtonProps.className}, content via
- * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top.
- * This mirrors how the sibling `Button` destructures its owned `className` out
- * of the forwarded `...props`.
+ * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top
+ * (its scroll animation configurable via
+ * {@link ScrollToTopButtonProps.scrollBehavior}). This mirrors how the sibling
+ * `Button` destructures its owned `className` out of the forwarded `...props`.
  */
 type ScrollToTopButtonPassthrough = Omit<React.ComponentPropsWithoutRef<"button">, "className" | "onClick" | "aria-label" | "children">;
 export interface ScrollToTopButtonProps extends ScrollToTopButtonPassthrough {
@@ -24,7 +25,16 @@ export interface ScrollToTopButtonProps extends ScrollToTopButtonPassthrough {
     variant?: ButtonProps["variant"];
     /** Button size. Forwarded to the underlying Button. Default "icon". */
     size?: ButtonProps["size"];
+    /**
+     * Scroll behavior passed to `window.scrollTo`. Default "smooth". Pass "auto"
+     * to skip the smooth animation (e.g. for a reduced-motion mode). The package
+     * stays motion-policy agnostic: the consumer decides what to pass here — an
+     * explicit JS `behavior: "smooth"` is not overridden by a CSS
+     * `scroll-behavior` kill-switch, so an app-level reduced-motion mode must
+     * pass "auto" to actually stop the animation.
+     */
+    scrollBehavior?: ScrollBehavior;
 }
-export declare function ScrollToTopButton({ threshold, ariaLabel, className, icon, variant, size, ...rest }: ScrollToTopButtonProps): React.JSX.Element;
+export declare function ScrollToTopButton({ threshold, ariaLabel, className, icon, variant, size, scrollBehavior, ...rest }: ScrollToTopButtonProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=scroll-to-top-button.d.ts.map

package/dist/react/components/scroll-to-top-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-to-top-button.d.ts","sourceRoot":"","sources":["../../../src/react/components/scroll-to-top-button.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAGvD;;;;;;;;;GASG;AACH,KAAK,4BAA4B,GAAG,IAAI,CACtC,KAAK,CAAC,wBAAwB,CAAC,QAAQ,CAAC,EACxC,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,CACpD,CAAC;AAEF,MAAM,WAAW,sBAAuB,SAAQ,4BAA4B;IAC1E,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,uEAAuE;IACvE,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAAC,EAChC,SAAe,EACf,SAA2B,EAC3B,SAAS,EACT,IAAI,EACJ,OAAO,EACP,IAAa,EACb,GAAG,IAAI,EACR,EAAE,sBAAsB,qBA4BxB"}
+{"version":3,"file":"scroll-to-top-button.d.ts","sourceRoot":"","sources":["../../../src/react/components/scroll-to-top-button.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAGvD;;;;;;;;;;GAUG;AACH,KAAK,4BAA4B,GAAG,IAAI,CACtC,KAAK,CAAC,wBAAwB,CAAC,QAAQ,CAAC,EACxC,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,CACpD,CAAC;AAEF,MAAM,WAAW,sBAAuB,SAAQ,4BAA4B;IAC1E,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,uEAAuE;IACvE,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAAC,EAChC,SAAe,EACf,SAA2B,EAC3B,SAAS,EACT,IAAI,EACJ,OAAO,EACP,IAAa,EACb,cAAyB,EACzB,GAAG,IAAI,EACR,EAAE,sBAAsB,qBA4BxB"}

package/dist/react/components/scroll-to-top-button.js

@@ -4,7 +4,7 @@ import * as React from "react";
 import { ChevronUp } from "lucide-react";
 import { Button } from "./button.js";
 import { cn } from "../../lib/utils.js";
-export function ScrollToTopButton({ threshold = 400, ariaLabel = "Scroll to top", className, icon, variant, size = "icon", ...rest }) {
+export function ScrollToTopButton({ threshold = 400, ariaLabel = "Scroll to top", className, icon, variant, size = "icon", scrollBehavior = "smooth", ...rest }) {
     const [isVisible, setIsVisible] = React.useState(false);
     React.useEffect(() => {
         const toggle = () => setIsVisible(window.scrollY > threshold);
@@ -12,7 +12,7 @@ export function ScrollToTopButton({ threshold = 400, ariaLabel = "Scroll to top"
         window.addEventListener("scroll", toggle, { passive: true });
         return () => window.removeEventListener("scroll", toggle);
     }, [threshold]);
-    const onClick = () => window.scrollTo({ top: 0, behavior: "smooth" });
+    const onClick = () => window.scrollTo({ top: 0, behavior: scrollBehavior });
     return (_jsx(Button, { ...rest, variant: variant, size: size, onClick: onClick, "aria-label": ariaLabel, className: cn("fixed bottom-24 left-1/2 -translate-x-1/2 z-50 rounded-full shadow-lg transition-opacity duration-300", isVisible ? "opacity-100" : "opacity-0 pointer-events-none", className), children: icon ?? _jsx(ChevronUp, { className: "h-5 w-5" }) }));
 }
 //# sourceMappingURL=scroll-to-top-button.js.map

package/dist/react/components/scroll-to-top-button.js.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-to-top-button.js","sourceRoot":"","sources":["../../../src/react/components/scroll-to-top-button.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAgCxC,MAAM,UAAU,iBAAiB,CAAC,EAChC,SAAS,GAAG,GAAG,EACf,SAAS,GAAG,eAAe,EAC3B,SAAS,EACT,IAAI,EACJ,OAAO,EACP,IAAI,GAAG,MAAM,EACb,GAAG,IAAI,EACgB;IACvB,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAExD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;QAC9D,MAAM,EAAE,CAAC;QACT,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEtE,OAAO,CACL,KAAC,MAAM,OACD,IAAI,EACR,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,gBACJ,SAAS,EACrB,SAAS,EAAE,EAAE,CACX,uGAAuG,EACvG,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,+BAA+B,EAC3D,SAAS,CACV,YAEA,IAAI,IAAI,KAAC,SAAS,IAAC,SAAS,EAAC,SAAS,GAAG,GACnC,CACV,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport { ChevronUp } from \"lucide-react\";\nimport { Button, type ButtonProps } from \"./button.js\";\nimport { cn } from \"../../lib/utils.js\";\n\n/**\n * Standard button DOM props forwarded to the rendered element, minus the props\n * this component owns. Owned props are excluded (not just overridden) so a\n * consumer can never route them through the passthrough channel: `aria-label`\n * is set via {@link ScrollToTopButtonProps.ariaLabel}, extra classes via the\n * merge-aware {@link ScrollToTopButtonProps.className}, content via\n * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top.\n * This mirrors how the sibling `Button` destructures its owned `className` out\n * of the forwarded `...props`.\n */\ntype ScrollToTopButtonPassthrough = Omit<\n  React.ComponentPropsWithoutRef<\"button\">,\n  \"className\" | \"onClick\" | \"aria-label\" | \"children\"\n>;\n\nexport interface ScrollToTopButtonProps extends ScrollToTopButtonPassthrough {\n  /** Scroll threshold (px) before the button appears. Default 400. */\n  threshold?: number;\n  /** Aria label. Default \"Scroll to top\". */\n  ariaLabel?: string;\n  /** Optional extra classes for the button. Merged with the component's own classes. */\n  className?: string;\n  /** Optional override for the icon. */\n  icon?: React.ReactNode;\n  /** Button variant. Forwarded to the underlying Button. Defaults to Button's own default. */\n  variant?: ButtonProps[\"variant\"];\n  /** Button size. Forwarded to the underlying Button. Default \"icon\". */\n  size?: ButtonProps[\"size\"];\n}\n\nexport function ScrollToTopButton({\n  threshold = 400,\n  ariaLabel = \"Scroll to top\",\n  className,\n  icon,\n  variant,\n  size = \"icon\",\n  ...rest\n}: ScrollToTopButtonProps) {\n  const [isVisible, setIsVisible] = React.useState(false);\n\n  React.useEffect(() => {\n    const toggle = () => setIsVisible(window.scrollY > threshold);\n    toggle();\n    window.addEventListener(\"scroll\", toggle, { passive: true });\n    return () => window.removeEventListener(\"scroll\", toggle);\n  }, [threshold]);\n\n  const onClick = () => window.scrollTo({ top: 0, behavior: \"smooth\" });\n\n  return (\n    <Button\n      {...rest}\n      variant={variant}\n      size={size}\n      onClick={onClick}\n      aria-label={ariaLabel}\n      className={cn(\n        \"fixed bottom-24 left-1/2 -translate-x-1/2 z-50 rounded-full shadow-lg transition-opacity duration-300\",\n        isVisible ? \"opacity-100\" : \"opacity-0 pointer-events-none\",\n        className,\n      )}\n    >\n      {icon ?? <ChevronUp className=\"h-5 w-5\" />}\n    </Button>\n  );\n}\n"]}
+{"version":3,"file":"scroll-to-top-button.js","sourceRoot":"","sources":["../../../src/react/components/scroll-to-top-button.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AA0CxC,MAAM,UAAU,iBAAiB,CAAC,EAChC,SAAS,GAAG,GAAG,EACf,SAAS,GAAG,eAAe,EAC3B,SAAS,EACT,IAAI,EACJ,OAAO,EACP,IAAI,GAAG,MAAM,EACb,cAAc,GAAG,QAAQ,EACzB,GAAG,IAAI,EACgB;IACvB,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAExD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;QAC9D,MAAM,EAAE,CAAC;QACT,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IAE5E,OAAO,CACL,KAAC,MAAM,OACD,IAAI,EACR,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,gBACJ,SAAS,EACrB,SAAS,EAAE,EAAE,CACX,uGAAuG,EACvG,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,+BAA+B,EAC3D,SAAS,CACV,YAEA,IAAI,IAAI,KAAC,SAAS,IAAC,SAAS,EAAC,SAAS,GAAG,GACnC,CACV,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport { ChevronUp } from \"lucide-react\";\nimport { Button, type ButtonProps } from \"./button.js\";\nimport { cn } from \"../../lib/utils.js\";\n\n/**\n * Standard button DOM props forwarded to the rendered element, minus the props\n * this component owns. Owned props are excluded (not just overridden) so a\n * consumer can never route them through the passthrough channel: `aria-label`\n * is set via {@link ScrollToTopButtonProps.ariaLabel}, extra classes via the\n * merge-aware {@link ScrollToTopButtonProps.className}, content via\n * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top\n * (its scroll animation configurable via\n * {@link ScrollToTopButtonProps.scrollBehavior}). This mirrors how the sibling\n * `Button` destructures its owned `className` out of the forwarded `...props`.\n */\ntype ScrollToTopButtonPassthrough = Omit<\n  React.ComponentPropsWithoutRef<\"button\">,\n  \"className\" | \"onClick\" | \"aria-label\" | \"children\"\n>;\n\nexport interface ScrollToTopButtonProps extends ScrollToTopButtonPassthrough {\n  /** Scroll threshold (px) before the button appears. Default 400. */\n  threshold?: number;\n  /** Aria label. Default \"Scroll to top\". */\n  ariaLabel?: string;\n  /** Optional extra classes for the button. Merged with the component's own classes. */\n  className?: string;\n  /** Optional override for the icon. */\n  icon?: React.ReactNode;\n  /** Button variant. Forwarded to the underlying Button. Defaults to Button's own default. */\n  variant?: ButtonProps[\"variant\"];\n  /** Button size. Forwarded to the underlying Button. Default \"icon\". */\n  size?: ButtonProps[\"size\"];\n  /**\n   * Scroll behavior passed to `window.scrollTo`. Default \"smooth\". Pass \"auto\"\n   * to skip the smooth animation (e.g. for a reduced-motion mode). The package\n   * stays motion-policy agnostic: the consumer decides what to pass here — an\n   * explicit JS `behavior: \"smooth\"` is not overridden by a CSS\n   * `scroll-behavior` kill-switch, so an app-level reduced-motion mode must\n   * pass \"auto\" to actually stop the animation.\n   */\n  scrollBehavior?: ScrollBehavior;\n}\n\nexport function ScrollToTopButton({\n  threshold = 400,\n  ariaLabel = \"Scroll to top\",\n  className,\n  icon,\n  variant,\n  size = \"icon\",\n  scrollBehavior = \"smooth\",\n  ...rest\n}: ScrollToTopButtonProps) {\n  const [isVisible, setIsVisible] = React.useState(false);\n\n  React.useEffect(() => {\n    const toggle = () => setIsVisible(window.scrollY > threshold);\n    toggle();\n    window.addEventListener(\"scroll\", toggle, { passive: true });\n    return () => window.removeEventListener(\"scroll\", toggle);\n  }, [threshold]);\n\n  const onClick = () => window.scrollTo({ top: 0, behavior: scrollBehavior });\n\n  return (\n    <Button\n      {...rest}\n      variant={variant}\n      size={size}\n      onClick={onClick}\n      aria-label={ariaLabel}\n      className={cn(\n        \"fixed bottom-24 left-1/2 -translate-x-1/2 z-50 rounded-full shadow-lg transition-opacity duration-300\",\n        isVisible ? \"opacity-100\" : \"opacity-0 pointer-events-none\",\n        className,\n      )}\n    >\n      {icon ?? <ChevronUp className=\"h-5 w-5\" />}\n    </Button>\n  );\n}\n"]}

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

@@ -0,0 +1,32 @@
+import type { ListPaginationState } from "./use-paged-list.js";
+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;
+}
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+export declare function useCursorPage(hasMore: boolean, options?: UseCursorPageOptions): CursorPage;
+//# sourceMappingURL=use-cursor-page.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,50 @@
+"use client";
+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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+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.
+    const goToPreviousPage = useCallback(() => {
+        if (currentPage <= 1)
+            return;
+        setCurrentPage(currentPage - 1);
+        onPageChange?.();
+    }, [currentPage, onPageChange]);
+    const goToNextPage = useCallback(() => {
+        if (!hasMore)
+            return;
+        setCurrentPage(currentPage + 1);
+        onPageChange?.();
+    }, [currentPage, hasMore, onPageChange]);
+    const reset = useCallback(() => {
+        if (currentPage === 1)
+            return;
+        setCurrentPage(1);
+        onPageChange?.();
+    }, [currentPage, onPageChange]);
+    return {
+        currentPage,
+        canPreviousPage: currentPage > 1,
+        canNextPage: hasMore,
+        goToPreviousPage,
+        goToNextPage,
+        reset,
+    };
+}
+//# sourceMappingURL=use-cursor-page.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,60 @@
+/**
+ * The control state a paginated list exposes to its paginator UI, rendered by
+ * the ONE `ListPagination` component. Nothing else builds
+ * Previous / counter / Next controls.
+ *
+ * `totalPages` is the flavor discriminant, and the ONLY difference between the
+ * two flavors:
+ *
+ * - **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
+ *   `"Page 2"`.
+ *
+ * Both flavors share one visibility rule, one disabled-edge rule, one live
+ * region, and one set of classes because they share one component (ENG-002,
+ * FRONTEND-001).
+ */
+export interface ListPaginationState {
+    /** 1-based page currently on screen. */
+    currentPage: number;
+    /**
+     * Total page count when it is knowable — at least 1, even for an empty list
+     * (an empty list is one empty page). Omitted for cursor/`hasMore` pagination,
+     * where the total is unknown until the last page is reached.
+     */
+    totalPages?: number;
+    canPreviousPage: boolean;
+    canNextPage: boolean;
+    goToPreviousPage: () => void;
+    goToNextPage: () => void;
+}
+export interface PagedList<T> extends ListPaginationState {
+    /** Always known for a slice-paginated list. */
+    totalPages: number;
+    /** The slice of `items` belonging to `currentPage`. */
+    pageItems: T[];
+}
+export interface UsePagedListOptions {
+    /**
+     * Called after the page actually changed. Surfaces that keep a per-page
+     * selection (an open detail row) clear it here — the old selection is not on
+     * the new page.
+     */
+    onPageChange?: () => void;
+}
+/**
+ * The single owner of client-side slice pagination: local page state, the page
+ * math, and the current slice over an ALREADY-FETCHED list.
+ *
+ * Page size is the caller's — every surface passes its own page-size constant
+ * (ENG-005), never a literal. Ordering and filtering stay with the caller: pass
+ * the list already sorted and filtered.
+ *
+ * Not for server-paged lists — a cursor/`hasMore` feed pages through the
+ * caller's data layer, not through a slice; use `useCursorPage` (or the query
+ * hook's own page state) with the same `ListPagination` control.
+ */
+export declare function usePagedList<T>(items: readonly T[], pageSize: number, options?: UsePagedListOptions): PagedList<T>;
+//# sourceMappingURL=use-paged-list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-paged-list.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-paged-list.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,CAAE,SAAQ,mBAAmB;IACvD,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,CAAC,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,mBAAwB,GAChC,SAAS,CAAC,CAAC,CAAC,CAoCd"}

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

@@ -0,0 +1,49 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+/**
+ * The single owner of client-side slice pagination: local page state, the page
+ * math, and the current slice over an ALREADY-FETCHED list.
+ *
+ * Page size is the caller's — every surface passes its own page-size constant
+ * (ENG-005), never a literal. Ordering and filtering stay with the caller: pass
+ * the list already sorted and filtered.
+ *
+ * Not for server-paged lists — a cursor/`hasMore` feed pages through the
+ * caller's data layer, not through a slice; use `useCursorPage` (or the query
+ * hook's own page state) with the same `ListPagination` control.
+ */
+export function usePagedList(items, pageSize, options = {}) {
+    const { onPageChange } = options;
+    const [requestedPage, setRequestedPage] = useState(1);
+    const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
+    // The list can shrink under a page that is already open (an item is deleted,
+    // a filter narrows). Clamping keeps the paginator on a real page instead of
+    // rendering an empty slice under an out-of-range "4 of 2".
+    const currentPage = Math.min(Math.max(1, requestedPage), totalPages);
+    const pageItems = useMemo(() => {
+        const startIndex = (currentPage - 1) * pageSize;
+        return items.slice(startIndex, startIndex + pageSize);
+    }, [items, currentPage, pageSize]);
+    const goToPreviousPage = useCallback(() => {
+        if (currentPage <= 1)
+            return;
+        setRequestedPage(currentPage - 1);
+        onPageChange?.();
+    }, [currentPage, onPageChange]);
+    const goToNextPage = useCallback(() => {
+        if (currentPage >= totalPages)
+            return;
+        setRequestedPage(currentPage + 1);
+        onPageChange?.();
+    }, [currentPage, totalPages, onPageChange]);
+    return {
+        currentPage,
+        totalPages,
+        pageItems,
+        canPreviousPage: currentPage > 1,
+        canNextPage: currentPage < totalPages,
+        goToPreviousPage,
+        goToNextPage,
+    };
+}
+//# sourceMappingURL=use-paged-list.js.map

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

@@ -0,0 +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"]}

package/dist/react/index.d.ts

@@ -51,4 +51,10 @@ export { ScrollToTopButton } from "./components/scroll-to-top-button.js";
 export type { ScrollToTopButtonProps } from "./components/scroll-to-top-button.js";
 export { ChunkErrorRecovery } from "./components/chunk-error-recovery.js";
 export type { ChunkErrorRecoveryProps } from "./components/chunk-error-recovery.js";
+export { ListPagination } from "./components/list-pagination.js";
+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";
 //# 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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -41,4 +41,9 @@ export { RelativeTime } from "./components/relative-time.js";
 export { EndOfListIndicator } from "./components/end-of-list-indicator.js";
 export { ScrollToTopButton } from "./components/scroll-to-top-button.js";
 export { ChunkErrorRecovery } from "./components/chunk-error-recovery.js";
+// List pagination — the one Previous / counter / Next control plus the page-state
+// hooks for its two flavors (known total, and cursor/`hasMore`).
+export { ListPagination } from "./components/list-pagination.js";
+export { usePagedList } from "./hooks/use-paged-list.js";
+export { useCursorPage } from "./hooks/use-cursor-page.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"]}
+{"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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/ui-core",
-  "version": "0.11.9",
+  "version": "0.11.11",
   "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.2"
+    "@ttt-productions/firebase-helpers": "^0.12.4"
   },
   "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.2"
+    "@ttt-productions/firebase-helpers": "^0.12.4"
   },
   "author": "DJ (TTT Productions)",
   "license": "MIT"

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

@@ -0,0 +1,79 @@
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { Button } from "./button.js";
+import { cn } from "../../lib/utils.js";
+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.
+   */
+  pagination: ListPaginationState;
+  /**
+   * Disables BOTH controls while the next page is in flight, without hiding the
+   * row. Server-paged surfaces pass their query's `isFetching`; a slice-paged
+   * list has nothing to wait for and omits it.
+   */
+  busy?: boolean;
+  /** Optional extra classes. Merged with the component's own classes. */
+  className?: string;
+}
+
+/**
+ * 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).
+ *
+ * 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 —
+ * which is exactly why there is one component and not two.
+ *
+ * It renders NOTHING when neither direction is available, so no call site
+ * repeats a `totalPages > 1` / `page > 1 || hasMore` guard. Edge state is real
+ * `disabled` on the buttons (announced, and unclickable), and the counter is a
+ * `status` live region so a page change is announced to screen readers.
+ */
+export function ListPagination({ pagination, busy = false, className }: ListPaginationProps) {
+  const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } =
+    pagination;
+
+  // One visibility rule for both flavors. For a known total this is exactly
+  // `totalPages > 1`: page state is clamped into `1..totalPages`, so a
+  // single-page list has no reachable neighbour in either direction, and a
+  // multi-page list always has one. For a cursor feed it is the hand-rolled
+  // `page > 1 || hasMore`. `busy` deliberately does not hide the row — the
+  // controls grey out in place instead of vanishing mid-fetch.
+  if (!canPreviousPage && !canNextPage) return null;
+
+  return (
+    <div className={cn("flex w-full items-center justify-between gap-4 mt-4", className)}>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={goToPreviousPage}
+        disabled={busy || !canPreviousPage}
+        className="h-11 min-w-11"
+      >
+        <ChevronLeft className="icon-xs mr-1" />
+        Previous
+      </Button>
+      <span className="text-counter" role="status">
+        {totalPages === undefined ? `Page ${currentPage}` : `${currentPage} of ${totalPages}`}
+      </span>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={goToNextPage}
+        disabled={busy || !canNextPage}
+        className="h-11 min-w-11"
+      >
+        Next
+        <ChevronRight className="icon-xs ml-1" />
+      </Button>
+    </div>
+  );
+}

package/src/react/components/scroll-to-top-button.tsx

@@ -11,9 +11,10 @@ import { cn } from "../../lib/utils.js";
  * consumer can never route them through the passthrough channel: `aria-label`
  * is set via {@link ScrollToTopButtonProps.ariaLabel}, extra classes via the
  * merge-aware {@link ScrollToTopButtonProps.className}, content via
- * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top.
- * This mirrors how the sibling `Button` destructures its owned `className` out
- * of the forwarded `...props`.
+ * {@link ScrollToTopButtonProps.icon}, and `onClick` is fixed to scroll-to-top
+ * (its scroll animation configurable via
+ * {@link ScrollToTopButtonProps.scrollBehavior}). This mirrors how the sibling
+ * `Button` destructures its owned `className` out of the forwarded `...props`.
  */
 type ScrollToTopButtonPassthrough = Omit<
   React.ComponentPropsWithoutRef<"button">,
@@ -33,6 +34,15 @@ export interface ScrollToTopButtonProps extends ScrollToTopButtonPassthrough {
   variant?: ButtonProps["variant"];
   /** Button size. Forwarded to the underlying Button. Default "icon". */
   size?: ButtonProps["size"];
+  /**
+   * Scroll behavior passed to `window.scrollTo`. Default "smooth". Pass "auto"
+   * to skip the smooth animation (e.g. for a reduced-motion mode). The package
+   * stays motion-policy agnostic: the consumer decides what to pass here — an
+   * explicit JS `behavior: "smooth"` is not overridden by a CSS
+   * `scroll-behavior` kill-switch, so an app-level reduced-motion mode must
+   * pass "auto" to actually stop the animation.
+   */
+  scrollBehavior?: ScrollBehavior;
 }
 
 export function ScrollToTopButton({
@@ -42,6 +52,7 @@ export function ScrollToTopButton({
   icon,
   variant,
   size = "icon",
+  scrollBehavior = "smooth",
   ...rest
 }: ScrollToTopButtonProps) {
   const [isVisible, setIsVisible] = React.useState(false);
@@ -53,7 +64,7 @@ export function ScrollToTopButton({
     return () => window.removeEventListener("scroll", toggle);
   }, [threshold]);
 
-  const onClick = () => window.scrollTo({ top: 0, behavior: "smooth" });
+  const onClick = () => window.scrollTo({ top: 0, behavior: scrollBehavior });
 
   return (
     <Button

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

@@ -0,0 +1,72 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ListPaginationState } from "./use-paged-list.js";
+
+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;
+}
+
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+export function useCursorPage(
+  hasMore: boolean,
+  options: UseCursorPageOptions = {},
+): CursorPage {
+  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.
+  const goToPreviousPage = useCallback(() => {
+    if (currentPage <= 1) return;
+    setCurrentPage(currentPage - 1);
+    onPageChange?.();
+  }, [currentPage, onPageChange]);
+
+  const goToNextPage = useCallback(() => {
+    if (!hasMore) return;
+    setCurrentPage(currentPage + 1);
+    onPageChange?.();
+  }, [currentPage, hasMore, onPageChange]);
+
+  const reset = useCallback(() => {
+    if (currentPage === 1) return;
+    setCurrentPage(1);
+    onPageChange?.();
+  }, [currentPage, onPageChange]);
+
+  return {
+    currentPage,
+    canPreviousPage: currentPage > 1,
+    canNextPage: hasMore,
+    goToPreviousPage,
+    goToNextPage,
+    reset,
+  };
+}

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

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+/**
+ * The control state a paginated list exposes to its paginator UI, rendered by
+ * the ONE `ListPagination` component. Nothing else builds
+ * Previous / counter / Next controls.
+ *
+ * `totalPages` is the flavor discriminant, and the ONLY difference between the
+ * two flavors:
+ *
+ * - **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
+ *   `"Page 2"`.
+ *
+ * Both flavors share one visibility rule, one disabled-edge rule, one live
+ * region, and one set of classes because they share one component (ENG-002,
+ * FRONTEND-001).
+ */
+export interface ListPaginationState {
+  /** 1-based page currently on screen. */
+  currentPage: number;
+  /**
+   * Total page count when it is knowable — at least 1, even for an empty list
+   * (an empty list is one empty page). Omitted for cursor/`hasMore` pagination,
+   * where the total is unknown until the last page is reached.
+   */
+  totalPages?: number;
+  canPreviousPage: boolean;
+  canNextPage: boolean;
+  goToPreviousPage: () => void;
+  goToNextPage: () => void;
+}
+
+export interface PagedList<T> extends ListPaginationState {
+  /** Always known for a slice-paginated list. */
+  totalPages: number;
+  /** The slice of `items` belonging to `currentPage`. */
+  pageItems: T[];
+}
+
+export interface UsePagedListOptions {
+  /**
+   * Called after the page actually changed. Surfaces that keep a per-page
+   * selection (an open detail row) clear it here — the old selection is not on
+   * the new page.
+   */
+  onPageChange?: () => void;
+}
+
+/**
+ * The single owner of client-side slice pagination: local page state, the page
+ * math, and the current slice over an ALREADY-FETCHED list.
+ *
+ * Page size is the caller's — every surface passes its own page-size constant
+ * (ENG-005), never a literal. Ordering and filtering stay with the caller: pass
+ * the list already sorted and filtered.
+ *
+ * Not for server-paged lists — a cursor/`hasMore` feed pages through the
+ * caller's data layer, not through a slice; use `useCursorPage` (or the query
+ * hook's own page state) with the same `ListPagination` control.
+ */
+export function usePagedList<T>(
+  items: readonly T[],
+  pageSize: number,
+  options: UsePagedListOptions = {},
+): PagedList<T> {
+  const { onPageChange } = options;
+  const [requestedPage, setRequestedPage] = useState(1);
+
+  const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
+  // The list can shrink under a page that is already open (an item is deleted,
+  // a filter narrows). Clamping keeps the paginator on a real page instead of
+  // rendering an empty slice under an out-of-range "4 of 2".
+  const currentPage = Math.min(Math.max(1, requestedPage), totalPages);
+
+  const pageItems = useMemo(() => {
+    const startIndex = (currentPage - 1) * pageSize;
+    return items.slice(startIndex, startIndex + pageSize);
+  }, [items, currentPage, pageSize]);
+
+  const goToPreviousPage = useCallback(() => {
+    if (currentPage <= 1) return;
+    setRequestedPage(currentPage - 1);
+    onPageChange?.();
+  }, [currentPage, onPageChange]);
+
+  const goToNextPage = useCallback(() => {
+    if (currentPage >= totalPages) return;
+    setRequestedPage(currentPage + 1);
+    onPageChange?.();
+  }, [currentPage, totalPages, onPageChange]);
+
+  return {
+    currentPage,
+    totalPages,
+    pageItems,
+    canPreviousPage: currentPage > 1,
+    canNextPage: currentPage < totalPages,
+    goToPreviousPage,
+    goToNextPage,
+  };
+}

package/src/react/index.ts

@@ -61,3 +61,14 @@ export type { ScrollToTopButtonProps } from "./components/scroll-to-top-button.j
 
 export { ChunkErrorRecovery } from "./components/chunk-error-recovery.js";
 export type { ChunkErrorRecoveryProps } from "./components/chunk-error-recovery.js";
+
+// List pagination — the one Previous / counter / Next control plus the page-state
+// hooks for its two flavors (known total, and cursor/`hasMore`).
+export { ListPagination } from "./components/list-pagination.js";
+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";