@ttt-productions/ui-core 0.11.12 → 0.11.15

package/src/react/components/button.tsx

@@ -1,10 +1,11 @@
 "use client"
 
 import * as React from "react"
-import { Slot } from "@radix-ui/react-slot"
+import { Slot, Slottable } from "@radix-ui/react-slot"
 import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const buttonVariants = cva(
   "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-bold ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
@@ -44,19 +45,54 @@ export interface ButtonProps
   extends React.ButtonHTMLAttributes<HTMLButtonElement>,
     VariantProps<typeof buttonVariants> {
   asChild?: boolean
+  /**
+   * Async work this button started is in flight. The button disables itself — so
+   * neither a repeat click nor an implicit form resubmit can fire — sets
+   * `aria-busy`, and shows the canonical spinner: an icon button (`size="icon"`)
+   * swaps its icon for it; any other button shows it in place of its `icon`.
+   */
+  pending?: boolean
+  /** Leading icon, rendered before the label. While `pending`, the spinner takes its place. */
+  icon?: React.ReactNode
 }
 
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, size, asChild = false, children, ...props }, ref) => {
-    const Comp = asChild ? Slot : "button"
+  ({ className, variant, size, asChild = false, pending = false, icon, disabled, children, ...props }, ref) => {
+    const shared = {
+      ...props,
+      ...(pending ? { "aria-busy": true, "data-pending": "" } : {}),
+      disabled: disabled || pending || undefined,
+      className: cn(buttonVariants({ variant, size, className })),
+    }
+    const spinner = <Spinner size={size === "lg" ? "sm" : "xs"} />
+    const leading = pending ? spinner : icon
+
+    if (asChild) {
+      // Slot finds the Slottable among its DIRECT children, so the leading slot and the
+      // Slottable must be siblings here — never wrapped in a fragment.
+      return leading ? (
+        <Slot ref={ref} {...shared}>
+          {leading}
+          <Slottable>{children}</Slottable>
+        </Slot>
+      ) : (
+        <Slot ref={ref} {...shared}>
+          {children}
+        </Slot>
+      )
+    }
+
     return (
-      <Comp
-        className={cn(buttonVariants({ variant, size, className }))}
-        ref={ref}
-        {...props}
-      >
-        {children}
-      </Comp>
+      <button ref={ref} {...shared}>
+        {size === "icon" ? (
+          pending ? spinner : children
+        ) : (
+          <>
+            {leading}
+            {children}
+          </>
+        )}
+      </button>
     )
   }
 )

package/src/react/components/chunk-error-recovery.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import * as React from "react";
-import { Loader2 } from "lucide-react";
+import { Spinner } from "./spinner.js";
 
 export interface ChunkErrorRecoveryProps {
   children: React.ReactNode;
@@ -48,7 +48,7 @@ export function ChunkErrorRecovery({
   if (hasError) {
     return (
       <div className="flex flex-col h-screen w-screen items-center justify-center gap-4 bg-background">
-        <Loader2 className="h-10 w-10 animate-spin" />
+        <Spinner size="xl" />
         <p className="text-muted-foreground">{loadingMessage}</p>
       </div>
     );

package/src/react/components/consequence-dialog.tsx

@@ -14,7 +14,7 @@ import { Button } from './button.js';
 import { Textarea } from './textarea.js';
 import { Input } from './input.js';
 import { Label } from './label.js';
-import { Loader2, Zap, Clock, RotateCcw } from 'lucide-react';
+import { Zap, Clock, RotateCcw } from 'lucide-react';
 
 /**
  * The inline required-reason config. The caller OWNS the reason value/onChange (draft state lives at
@@ -71,7 +71,7 @@ export interface ConsequenceDialogProps {
 
   /**
    * Runs on confirm. May be async — while it is pending the dialog STAYS OPEN, both buttons disable,
-   * and a `Loader2` spins in the confirm button. Closes on resolve. If it rejects the dialog
+   * and the confirm button shows its pending spinner. Closes on resolve. If it rejects the dialog
    * stays open so the caller's own surface (error toast, TOTP step-up) can show and the operator can
    * retry or cancel. This component takes no Sentry/monitoring dependency — every error path
    * belongs to the caller's `onConfirm`.
@@ -184,7 +184,6 @@ export function ConsequenceDialog({
           (reason.maxLength === undefined || reason.value.length <= reason.maxLength);
 
   const typedOk = !typedConfirmation ? true : typedValue === typedConfirmation.phrase;
-  const confirmDisabled = pending || !reasonOk || !typedOk;
 
   return (
     <AlertDialog open={actualOpen} onOpenChange={handleOpenChange}>
@@ -263,10 +262,9 @@ export function ConsequenceDialog({
           <Button
             variant={destructive ? 'destructive' : 'default'}
             onClick={handleConfirm}
-            disabled={confirmDisabled}
-            aria-busy={pending}
+            disabled={!reasonOk || !typedOk}
+            pending={pending}
           >
-            {pending ? <Loader2 className="mr-2 spinner-xs" aria-hidden="true" /> : null}
             {confirmLabel}
           </Button>
         </AlertDialogFooter>

package/src/react/components/dropdown-menu.tsx

@@ -5,6 +5,7 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu"
 import { Check, ChevronRight, Circle } from "lucide-react"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const DropdownMenu = DropdownMenuPrimitive.Root
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
@@ -71,8 +72,16 @@ const DropdownMenuItem = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Item>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
     inset?: boolean
+    /**
+     * The action this item started is in flight: the item disables itself, sets
+     * `aria-busy`, and shows the spinner in place of its `icon`. Keeping the menu open
+     * meanwhile is the caller's `onSelect` (`event.preventDefault()`, close on settle).
+     */
+    pending?: boolean
+    /** Leading icon. While `pending`, the spinner takes its place. */
+    icon?: React.ReactNode
   }
->(({ className, inset, ...props }, ref) => (
+>(({ className, inset, pending = false, icon, disabled, children, ...props }, ref) => (
   <DropdownMenuPrimitive.Item
     ref={ref}
     className={cn(
@@ -81,7 +90,12 @@ const DropdownMenuItem = React.forwardRef<
       className
     )}
     {...props}
-  />
+    {...(pending ? { "aria-busy": true, "data-pending": "" } : {})}
+    disabled={disabled || pending || undefined}
+  >
+    {pending ? <Spinner size="xs" /> : icon}
+    {children}
+  </DropdownMenuPrimitive.Item>
 ))
 DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName
 

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

@@ -1,5 +1,6 @@
 "use client";
 
+import { useState } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { Button } from "./button.js";
 import { cn } from "../../lib/utils.js";
@@ -43,6 +44,17 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
   const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } =
     pagination;
 
+  // The control that started the in-flight page shows the spinner. Cleared when `busy`
+  // ends — a render-phase adjustment, so there is no effect and no stale frame.
+  const [clicked, setClicked] = useState<"previous" | "next" | null>(null);
+  const [wasBusy, setWasBusy] = useState(busy);
+  if (busy !== wasBusy) {
+    setWasBusy(busy);
+    if (!busy) setClicked(null);
+  }
+  const previousPending = busy && clicked === "previous";
+  const nextPending = busy && clicked === "next";
+
   // 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
@@ -56,11 +68,15 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
       <Button
         variant="outline"
         size="sm"
-        onClick={goToPreviousPage}
+        onClick={() => {
+          setClicked("previous");
+          goToPreviousPage();
+        }}
         disabled={busy || !canPreviousPage}
+        pending={previousPending}
+        icon={<ChevronLeft className="icon-xs" />}
         className="h-11 min-w-11"
       >
-        <ChevronLeft className="icon-xs mr-1" />
         Previous
       </Button>
       <span className="text-counter" role="status">
@@ -69,12 +85,16 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
       <Button
         variant="outline"
         size="sm"
-        onClick={goToNextPage}
+        onClick={() => {
+          setClicked("next");
+          goToNextPage();
+        }}
         disabled={busy || !canNextPage}
+        pending={nextPending}
         className="h-11 min-w-11"
       >
         Next
-        <ChevronRight className="icon-xs ml-1" />
+        {nextPending ? null : <ChevronRight className="icon-xs" />}
       </Button>
     </div>
   );

package/src/react/components/search-dropdown.tsx

@@ -3,7 +3,8 @@
 import { useState, useRef, useEffect } from 'react';
 import { Input } from './input.js';
 import { Label } from './label.js';
-import { Loader2, X, Search } from 'lucide-react';
+import { X, Search } from 'lucide-react';
+import { Spinner } from './spinner.js';
 import { cn } from "../../lib/utils.js";
 
 export interface SearchDropdownProps<T> {
@@ -173,7 +174,7 @@ export function SearchDropdown<T>({
 
         <div className="absolute right-3 top-1/2 -translate-y-1/2">
           {isLoading ? (
-            <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+            <Spinner size="xs" className="text-muted-foreground" />
           ) : value ? (
             <button
               type="button"
@@ -195,7 +196,7 @@ export function SearchDropdown<T>({
             </div>
           ) : isLoading ? (
             <div className="px-3 py-2 text-sm text-muted-foreground flex items-center gap-2">
-              <Loader2 className="h-4 w-4 animate-spin" />
+              <Spinner size="xs" />
               Searching...
             </div>
           ) : results.length === 0 ? (

package/src/react/components/select.tsx

@@ -5,6 +5,7 @@ import * as SelectPrimitive from "@radix-ui/react-select"
 import { Check, ChevronDown, ChevronUp } from "lucide-react"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const Select = SelectPrimitive.Root
 const SelectGroup = SelectPrimitive.Group
@@ -12,8 +13,15 @@ const SelectValue = SelectPrimitive.Value
 
 const SelectTrigger = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & {
+    /**
+     * The change this select started is in flight: the trigger disables itself, sets
+     * `aria-busy`, and shows the spinner in place of its chevron. It keeps showing the
+     * COMMITTED value — the caller changes `value` only once the write lands.
+     */
+    pending?: boolean
+  }
+>(({ className, children, pending = false, disabled, ...props }, ref) => (
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
@@ -21,11 +29,17 @@ const SelectTrigger = React.forwardRef<
       className
     )}
     {...props}
+    {...(pending ? { "aria-busy": true, "data-pending": "" } : {})}
+    disabled={disabled || pending || undefined}
   >
     {children}
-    <SelectPrimitive.Icon asChild>
-      <ChevronDown className="h-4 w-4 opacity-50" />
-    </SelectPrimitive.Icon>
+    {pending ? (
+      <Spinner size="xs" />
+    ) : (
+      <SelectPrimitive.Icon asChild>
+        <ChevronDown className="h-4 w-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    )}
   </SelectPrimitive.Trigger>
 ))
 SelectTrigger.displayName = SelectPrimitive.Trigger.displayName

package/src/react/components/spinner.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import { Loader2 } from "lucide-react"
+
+import { cn } from "../../lib/utils.js"
+
+export type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl"
+
+export interface SpinnerProps {
+  /** Maps onto the theme-core `spinner-*` classes. Defaults to `xs` (the in-control size). */
+  size?: SpinnerSize
+  /**
+   * Screen-reader text. When set, the spinner becomes a `status` live region that
+   * announces it. Omit it for a spinner inside a control that already carries its
+   * own busy state (`aria-busy`) — the control speaks for it.
+   */
+  label?: string
+  className?: string
+}
+
+const SIZE_CLASS: Record<SpinnerSize, string> = {
+  xs: "spinner-xs",
+  sm: "spinner-sm",
+  md: "spinner-md",
+  lg: "spinner-lg",
+  xl: "spinner-xl",
+}
+
+/**
+ * The ONE loading spinner. Every in-progress indicator renders through this
+ * component (or through a control's `pending` prop, which renders it), so the
+ * spinner's look, size scale, and color rule have one change point. The
+ * theme-core `spinner-*` classes own size, animation, and color — including the
+ * `button .spinner-*` rule that makes an in-button spinner inherit the button's
+ * text color so it is never primary-on-primary.
+ */
+function Spinner({ size = "xs", label, className }: SpinnerProps) {
+  if (!label) {
+    return <Loader2 className={cn(SIZE_CLASS[size], className)} aria-hidden="true" />
+  }
+  return (
+    <span role="status" className={cn("inline-flex items-center justify-center", className)}>
+      <Loader2 className={SIZE_CLASS[size]} aria-hidden="true" />
+      <span className="sr-only">{label}</span>
+    </span>
+  )
+}
+
+export { Spinner }

package/src/react/components/switch.tsx

@@ -4,24 +4,36 @@ import * as React from "react"
 import * as SwitchPrimitives from "@radix-ui/react-switch"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const Switch = React.forwardRef<
   React.ElementRef<typeof SwitchPrimitives.Root>,
-  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
->(({ className, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root> & {
+    /**
+     * The change this switch started is in flight: the switch disables itself, sets
+     * `aria-busy`, and spins inside its thumb. It keeps showing the COMMITTED state —
+     * the caller flips `checked` only once the write lands.
+     */
+    pending?: boolean
+  }
+>(({ className, pending = false, disabled, ...props }, ref) => (
   <SwitchPrimitives.Root
     className={cn(
       "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
       className
     )}
     {...props}
+    {...(pending ? { "aria-busy": true, "data-pending": "" } : {})}
+    disabled={disabled || pending || undefined}
     ref={ref}
   >
     <SwitchPrimitives.Thumb
       className={cn(
-        "pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0"
+        "pointer-events-none flex h-5 w-5 items-center justify-center rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0"
       )}
-    />
+    >
+      {pending ? <Spinner size="xs" /> : null}
+    </SwitchPrimitives.Thumb>
   </SwitchPrimitives.Root>
 ))
 Switch.displayName = SwitchPrimitives.Root.displayName

package/src/react/hooks/use-async-action.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+export interface UseAsyncActionOptions {
+  /**
+   * Receives anything the action throws. REQUIRED, so every call site decides what a
+   * failure means (surface it, capture it, or accept that another layer already did):
+   * `run` itself never rejects, so a fire-and-forget `onClick={() => void run()}` can
+   * never become an unhandled rejection.
+   */
+  onError: (error: unknown) => void;
+}
+
+export interface AsyncAction<TArgs extends unknown[]> {
+  /**
+   * Starts the action unless one is already in flight — a repeat call while pending is
+   * ignored. Resolves once the action settles: `true` when it completed, `false` when it
+   * was ignored or threw. Never rejects.
+   */
+  run: (...args: TArgs) => Promise<boolean>;
+  /** True from the moment `run` starts the action until it settles. */
+  pending: boolean;
+}
+
+/**
+ * Pending state + repeat guard for async work that is NOT a React Query mutation
+ * (a local media step, a sign-out, an awaited navigation). Feed `pending` to the
+ * control's own `pending` prop. Server writes stay mutations — this hook does not
+ * replace the data layer's one mutation path.
+ *
+ * The guard is a ref, not the state, so two clicks inside one frame cannot both start
+ * the action.
+ */
+export function useAsyncAction<TArgs extends unknown[]>(
+  action: (...args: TArgs) => Promise<unknown>,
+  options: UseAsyncActionOptions,
+): AsyncAction<TArgs> {
+  const [pending, setPending] = useState(false);
+  const inFlightRef = useRef(false);
+  const actionRef = useRef(action);
+  const onErrorRef = useRef(options.onError);
+  actionRef.current = action;
+  onErrorRef.current = options.onError;
+
+  const run = useCallback(async (...args: TArgs): Promise<boolean> => {
+    if (inFlightRef.current) return false;
+    inFlightRef.current = true;
+    setPending(true);
+    try {
+      await actionRef.current(...args);
+      return true;
+    } catch (error) {
+      onErrorRef.current(error);
+      return false;
+    } finally {
+      inFlightRef.current = false;
+      setPending(false);
+    }
+  }, []);
+
+  return { run, pending };
+}

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

@@ -2,6 +2,8 @@
 
 export type { ButtonProps } from "./components/button.js";
 export { Button, buttonVariants } from "./components/button.js";
+export type { SpinnerProps, SpinnerSize } from "./components/spinner.js";
+export { Spinner } from "./components/spinner.js";
 export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from "./components/card.js";
 export { Label } from "./components/label.js";
 export { Textarea } from "./components/textarea.js";
@@ -49,6 +51,9 @@ export { ScreenAdaptiveView } from "./components/layout/screen-adaptive-view.js"
 
 export { useMediaQuery } from "./hooks/use-media-query.js";
 
+export { useAsyncAction } from "./hooks/use-async-action.js";
+export type { AsyncAction, UseAsyncActionOptions } from "./hooks/use-async-action.js";
+
 // Shared building blocks
 export { RelativeTime } from "./components/relative-time.js";
 export type { RelativeTimeProps } from "./components/relative-time.js";
@@ -72,3 +77,9 @@ export type { ListPaginationState, PagedList, UsePagedListOptions } from "./hook
 
 export { useCursorPage } 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";