@boxcustodia/library 2.0.0-alpha.22 → 2.0.0-alpha.23

package/src/hooks/use-session-storage/use-session-storage.ts

@@ -0,0 +1,115 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { isBrowser, type Serializer } from "../internal";
+
+export type { Serializer };
+
+export interface UseSessionStorageOptions<T> {
+  serializer?: Serializer<T>;
+}
+
+const defaultSerializer: Serializer<unknown> = {
+  read: (raw) => JSON.parse(raw) as unknown,
+  write: (value) => JSON.stringify(value),
+};
+
+type Listener = () => void;
+const listeners = new Map<string, Set<Listener>>();
+
+function notifyKey(key: string): void {
+  listeners.get(key)?.forEach((listener) => listener());
+}
+
+function subscribeKey(key: string, listener: Listener): () => void {
+  if (!isBrowser) return () => {};
+
+  let bucket = listeners.get(key);
+  if (!bucket) {
+    bucket = new Set();
+    listeners.set(key, bucket);
+  }
+  bucket.add(listener);
+
+  return () => {
+    bucket.delete(listener);
+    if (bucket.size === 0) listeners.delete(key);
+  };
+}
+
+export function useSessionStorage<T>(
+  key: string,
+): [
+  T | undefined,
+  (value: T | ((prev: T | undefined) => T)) => void,
+  () => void,
+];
+export function useSessionStorage<T>(
+  key: string,
+  initialValue: T,
+  options?: UseSessionStorageOptions<T>,
+): [T, (value: T | ((prev: T) => T)) => void, () => void];
+export function useSessionStorage<T>(
+  key: string,
+  initialValue?: T,
+  options: UseSessionStorageOptions<T> = {},
+): [
+  T | undefined,
+  (value: T | ((prev: T | undefined) => T)) => void,
+  () => void,
+] {
+  const serializer = (options.serializer ?? defaultSerializer) as Serializer<T>;
+
+  const subscribe = useCallback(
+    (listener: Listener) => subscribeKey(key, listener),
+    [key],
+  );
+
+  const getSnapshot = useCallback((): string | null => {
+    if (!isBrowser) return null;
+    try {
+      return sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }, [key]);
+
+  const getServerSnapshot = useCallback((): string | null => null, []);
+
+  const raw = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const value = useMemo<T | undefined>(() => {
+    if (raw === null) return initialValue;
+    try {
+      return serializer.read(raw);
+    } catch (error) {
+      console.error(`Error parsing sessionStorage key "${key}":`, error);
+      return initialValue;
+    }
+  }, [raw, initialValue, key, serializer]);
+
+  const setValue = useCallback(
+    (next: T | ((prev: T | undefined) => T)) => {
+      try {
+        const resolved =
+          typeof next === "function"
+            ? (next as (prev: T | undefined) => T)(value)
+            : next;
+        sessionStorage.setItem(key, serializer.write(resolved));
+        notifyKey(key);
+      } catch (error) {
+        console.error(`Error setting sessionStorage key "${key}":`, error);
+      }
+    },
+    [key, value, serializer],
+  );
+
+  const remove = useCallback(() => {
+    try {
+      sessionStorage.removeItem(key);
+      notifyKey(key);
+    } catch (error) {
+      console.error(`Error removing sessionStorage key "${key}":`, error);
+    }
+  }, [key]);
+
+  return [value, setValue, remove];
+}

package/dist/hooks/use-async/use-async.cjs.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),o=require("../internal/use-latest-ref.cjs.js");function m({fn:L,deps:h=[],enabled:l=!0,keepPreviousData:k=!1,onSuccess:p,onError:q,onSettled:w}){const[n,u]=t.useState(l?"pending":"idle"),[A,f]=t.useState(null),[C,i]=t.useState(null),d=o.useLatestRef(L),R=o.useLatestRef(p),S=o.useLatestRef(q),b=o.useLatestRef(w),c=t.useRef(0),[T,I]=t.useState(0),y=t.useCallback(async(e,s)=>{let E=null,g=null;try{const r=await d.current(e);if(s!==c.current||e.aborted)return;E=r,f(r),u("success"),R.current?.(r)}catch(r){if(e.aborted||s!==c.current)return;const a=r instanceof Error?r:new Error(String(r));g=a,i(a),u("error"),S.current?.(a)}finally{s===c.current&&!e.aborted&&b.current?.(E,g)}},[d,R,S,b]),j=t.useCallback(()=>{I(e=>e+1)},[]);return t.useEffect(()=>{if(!l){u("idle");return}c.current+=1;const e=c.current,s=new AbortController;return u("pending"),i(null),k||f(null),y(s.signal,e),()=>{s.abort()}},[...h,l,y,T]),{data:A,error:C,status:n,loading:n==="pending",isIdle:n==="idle",isSuccess:n==="success",isError:n==="error",refetch:j}}exports.useAsync=m;

package/dist/hooks/use-async/use-async.es.js

@@ -1,57 +0,0 @@
-import { useState as o, useRef as L, useCallback as m, useEffect as j } from "react";
-import { useLatestRef as u } from "../internal/use-latest-ref.es.js";
-function B({
-  fn: y,
-  deps: g = [],
-  enabled: l = !0,
-  keepPreviousData: k = !1,
-  onSuccess: w,
-  onError: x,
-  onSettled: A
-}) {
-  const [n, s] = o(
-    l ? "pending" : "idle"
-  ), [C, i] = o(null), [I, a] = o(null), d = u(y), R = u(w), E = u(x), p = u(A), c = L(0), [T, q] = o(0), S = m(
-    async (r, t) => {
-      let b = null, h = null;
-      try {
-        const e = await d.current(r);
-        if (t !== c.current || r.aborted) return;
-        b = e, i(e), s("success"), R.current?.(e);
-      } catch (e) {
-        if (r.aborted || t !== c.current) return;
-        const f = e instanceof Error ? e : new Error(String(e));
-        h = f, a(f), s("error"), E.current?.(f);
-      } finally {
-        t === c.current && !r.aborted && p.current?.(b, h);
-      }
-    },
-    // All deps are refs — this callback is effectively stable
-    [d, R, E, p]
-  ), D = m(() => {
-    q((r) => r + 1);
-  }, []);
-  return j(() => {
-    if (!l) {
-      s("idle");
-      return;
-    }
-    c.current += 1;
-    const r = c.current, t = new AbortController();
-    return s("pending"), a(null), k || i(null), S(t.signal, r), () => {
-      t.abort();
-    };
-  }, [...g, l, S, T]), {
-    data: C,
-    error: I,
-    status: n,
-    loading: n === "pending",
-    isIdle: n === "idle",
-    isSuccess: n === "success",
-    isError: n === "error",
-    refetch: D
-  };
-}
-export {
-  B as useAsync
-};

package/dist/hooks/use-focus-trap/scope-tab.cjs.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./tabbable.cjs.js");function s(a,e){const t=r.findTabbableDescendants(a);if(!t.length){e.preventDefault();return}const o=t[e.shiftKey?0:t.length-1],i=a.getRootNode();let c=o===i.activeElement||a===i.activeElement;const n=i.activeElement;if(n.tagName==="INPUT"&&n.getAttribute("type")==="radio"&&(c=t.filter(b=>b.getAttribute("type")==="radio"&&b.getAttribute("name")===n.getAttribute("name")).includes(o)),!c)return;e.preventDefault();const l=t[e.shiftKey?t.length-1:0];l&&l.focus()}exports.scopeTab=s;

package/dist/hooks/use-focus-trap/scope-tab.es.js

@@ -1,21 +0,0 @@
-import { findTabbableDescendants as b } from "./tabbable.es.js";
-function g(a, e) {
-  const t = b(a);
-  if (!t.length) {
-    e.preventDefault();
-    return;
-  }
-  const o = t[e.shiftKey ? 0 : t.length - 1], i = a.getRootNode();
-  let c = o === i.activeElement || a === i.activeElement;
-  const n = i.activeElement;
-  if (n.tagName === "INPUT" && n.getAttribute("type") === "radio" && (c = t.filter(
-    (r) => r.getAttribute("type") === "radio" && r.getAttribute("name") === n.getAttribute("name")
-  ).includes(o)), !c)
-    return;
-  e.preventDefault();
-  const l = t[e.shiftKey ? t.length - 1 : 0];
-  l && l.focus();
-}
-export {
-  g as scopeTab
-};

package/dist/hooks/use-focus-trap/tabbable.cjs.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=/input|select|textarea|button|object/,a="a, input, select, textarea, button, object, [tabindex]";function b(t){return process.env.NODE_ENV==="test"?!1:t.style.display==="none"}function d(t){if(t.getAttribute("aria-hidden")||t.getAttribute("hidden")||t.getAttribute("type")==="hidden")return!1;let e=t;for(;e&&!(e===document.body||e.nodeType===11);){if(b(e))return!1;e=e.parentNode}return!0}function r(t){let n=t.getAttribute("tabindex");return n===null&&(n=void 0),parseInt(n,10)}function i(t){const n=t.nodeName.toLowerCase(),e=!Number.isNaN(r(t));return(o.test(n)&&!t.disabled||t instanceof HTMLAnchorElement&&t.href||e)&&d(t)}function s(t){const n=r(t);return(Number.isNaN(n)||n>=0)&&i(t)}function u(t){return Array.from(t.querySelectorAll(a)).filter(s)}exports.FOCUS_SELECTOR=a;exports.findTabbableDescendants=u;exports.focusable=i;exports.tabbable=s;

package/dist/hooks/use-focus-trap/tabbable.es.js

@@ -1,38 +0,0 @@
-const i = /input|select|textarea|button|object/, a = "a, input, select, textarea, button, object, [tabindex]";
-function o(t) {
-  return process.env.NODE_ENV === "test" ? !1 : t.style.display === "none";
-}
-function s(t) {
-  if (t.getAttribute("aria-hidden") || t.getAttribute("hidden") || t.getAttribute("type") === "hidden")
-    return !1;
-  let e = t;
-  for (; e && !(e === document.body || e.nodeType === 11); ) {
-    if (o(e))
-      return !1;
-    e = e.parentNode;
-  }
-  return !0;
-}
-function r(t) {
-  let n = t.getAttribute("tabindex");
-  return n === null && (n = void 0), parseInt(n, 10);
-}
-function d(t) {
-  const n = t.nodeName.toLowerCase(), e = !Number.isNaN(r(t));
-  return /* @ts-expect-error function accepts any html element but if it is a button, it should not be disabled to trigger the condition */ (i.test(n) && !t.disabled || t instanceof HTMLAnchorElement && t.href || e) && s(t);
-}
-function u(t) {
-  const n = r(t);
-  return (Number.isNaN(n) || n >= 0) && d(t);
-}
-function c(t) {
-  return Array.from(
-    t.querySelectorAll(a)
-  ).filter(u);
-}
-export {
-  a as FOCUS_SELECTOR,
-  c as findTabbableDescendants,
-  d as focusable,
-  u as tabbable
-};

package/dist/hooks/use-focus-trap/use-focus-trap.cjs.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("react"),f=require("./scope-tab.cjs.js"),n=require("./tabbable.cjs.js");function i(u=!0){const t=c.useRef(null),o=e=>{let r=e.querySelector("[data-autofocus]");if(!r){const s=Array.from(e.querySelectorAll(n.FOCUS_SELECTOR));r=s.find(n.tabbable)||s.find(n.focusable)||null,!r&&n.focusable(e)&&(r=e)}r&&r.focus({preventScroll:!0})},l=c.useCallback(e=>{u&&e!==null&&t.current!==e&&(e?(setTimeout(()=>{e.getRootNode()&&o(e)}),t.current=e):t.current=null)},[u]);return c.useEffect(()=>{if(!u)return;t.current&&setTimeout(()=>o(t.current));const e=r=>{r.key==="Tab"&&t.current&&f.scopeTab(t.current,r)};return document.addEventListener("keydown",e),()=>document.removeEventListener("keydown",e)},[u]),l}exports.useFocusTrap=i;

package/dist/hooks/use-focus-trap/use-focus-trap.es.js

@@ -1,34 +0,0 @@
-import { useRef as l, useCallback as s, useEffect as i } from "react";
-import { scopeTab as m } from "./scope-tab.es.js";
-import { FOCUS_SELECTOR as a, tabbable as b, focusable as f } from "./tabbable.es.js";
-function E(u = !0) {
-  const t = l(null), n = (e) => {
-    let r = e.querySelector("[data-autofocus]");
-    if (!r) {
-      const o = Array.from(
-        e.querySelectorAll(a)
-      );
-      r = o.find(b) || o.find(f) || null, !r && f(e) && (r = e);
-    }
-    r && r.focus({ preventScroll: !0 });
-  }, c = s(
-    (e) => {
-      u && e !== null && t.current !== e && (e ? (setTimeout(() => {
-        e.getRootNode() && n(e);
-      }), t.current = e) : t.current = null);
-    },
-    [u]
-  );
-  return i(() => {
-    if (!u)
-      return;
-    t.current && setTimeout(() => n(t.current));
-    const e = (r) => {
-      r.key === "Tab" && t.current && m(t.current, r);
-    };
-    return document.addEventListener("keydown", e), () => document.removeEventListener("keydown", e);
-  }, [u]), c;
-}
-export {
-  E as useFocusTrap
-};

package/dist/hooks/use-mutation/use-mutation.cjs.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),c=require("../internal/use-latest-ref.cjs.js"),k=s=>{const[u,l]=t.useState("idle"),[y,a]=t.useState(null),[L,o]=t.useState(null),d=c.useLatestRef(s.fn),R=c.useLatestRef(s.onMutate),i=c.useLatestRef(s.onSuccess),S=c.useLatestRef(s.onError),g=c.useLatestRef(s.onSettled),f=t.useCallback(async e=>{R.current?.(e),l("pending"),a(null),o(null);let n=null,r=null;try{return n=await d.current(e),a(n),l("success"),i.current?.(n,e),n}catch(E){throw r=E,o(r),l("error"),S.current?.(r,e),r}finally{g.current?.(n,r,e)}},[d,R,i,S,g]),M=t.useCallback(e=>{f(e).catch(()=>{})},[f]),h=t.useCallback(()=>{l("idle"),a(null),o(null)},[]);return{mutate:M,mutateAsync:f,reset:h,data:y,error:L,status:u,isIdle:u==="idle",isPending:u==="pending",isSuccess:u==="success",isError:u==="error"}};exports.useMutation=k;

package/dist/hooks/use-mutation/use-mutation.es.js

@@ -1,41 +0,0 @@
-import { useState as f, useCallback as d } from "react";
-import { useLatestRef as s } from "../internal/use-latest-ref.es.js";
-const x = (e) => {
-  const [n, u] = f("idle"), [h, o] = f(null), [y, l] = f(null), i = s(e.fn), S = s(e.onMutate), m = s(e.onSuccess), R = s(e.onError), g = s(e.onSettled), a = d(
-    async (t) => {
-      S.current?.(t), u("pending"), o(null), l(null);
-      let r = null, c = null;
-      try {
-        return r = await i.current(t), o(r), u("success"), m.current?.(r, t), r;
-      } catch (w) {
-        throw c = w, l(c), u("error"), R.current?.(c, t), c;
-      } finally {
-        g.current?.(r, c, t);
-      }
-    },
-    [i, S, m, R, g]
-  ), E = d(
-    (t) => {
-      a(t).catch(() => {
-      });
-    },
-    [a]
-  ), M = d(() => {
-    u("idle"), o(null), l(null);
-  }, []);
-  return {
-    mutate: E,
-    mutateAsync: a,
-    reset: M,
-    data: h,
-    error: y,
-    status: n,
-    isIdle: n === "idle",
-    isPending: n === "pending",
-    isSuccess: n === "success",
-    isError: n === "error"
-  };
-};
-export {
-  x as useMutation
-};

package/dist/src/hooks/use-async/index.d.ts

@@ -1 +0,0 @@
-export * from './use-async';

package/dist/src/hooks/use-async/use-async.d.ts

@@ -1,21 +0,0 @@
-export type AsyncStatus = "idle" | "pending" | "success" | "error";
-export interface UseAsyncOptions<T> {
-    fn: (signal: AbortSignal) => Promise<T>;
-    deps?: readonly unknown[];
-    enabled?: boolean;
-    keepPreviousData?: boolean;
-    onSuccess?: (data: T) => void;
-    onError?: (error: Error) => void;
-    onSettled?: (data: T | null, error: Error | null) => void;
-}
-export interface UseAsyncReturn<T> {
-    data: T | null;
-    error: Error | null;
-    status: AsyncStatus;
-    loading: boolean;
-    isIdle: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    refetch: () => void;
-}
-export declare function useAsync<T>({ fn, deps, enabled, keepPreviousData, onSuccess, onError, onSettled, }: UseAsyncOptions<T>): UseAsyncReturn<T>;

package/dist/src/hooks/use-focus-trap/index.d.ts

@@ -1 +0,0 @@
-export * from './use-focus-trap';

package/dist/src/hooks/use-focus-trap/scope-tab.d.ts

@@ -1 +0,0 @@
-export declare function scopeTab(node: HTMLElement, event: KeyboardEvent): void;

package/dist/src/hooks/use-focus-trap/tabbable.d.ts

@@ -1,4 +0,0 @@
-export declare const FOCUS_SELECTOR = "a, input, select, textarea, button, object, [tabindex]";
-export declare function focusable(element: HTMLElement): boolean | "";
-export declare function tabbable(element: HTMLElement): boolean | "";
-export declare function findTabbableDescendants(element: HTMLElement): HTMLElement[];

package/dist/src/hooks/use-focus-trap/use-focus-trap.d.ts

@@ -1 +0,0 @@
-export declare function useFocusTrap(active?: boolean): (instance: HTMLElement | null) => void;

package/dist/src/hooks/use-mutation/index.d.ts

@@ -1 +0,0 @@
-export * from './use-mutation';

package/dist/src/hooks/use-mutation/use-mutation.d.ts

@@ -1,22 +0,0 @@
-type MutationStatus = "idle" | "pending" | "success" | "error";
-export interface UseMutationOptions<TVariables = void, TData = unknown> {
-    fn: (variables: TVariables) => Promise<TData>;
-    onMutate?: (variables: TVariables) => void;
-    onSuccess?: (data: TData, variables: TVariables) => void;
-    onError?: (error: Error, variables: TVariables) => void;
-    onSettled?: (data: TData | null, error: Error | null, variables: TVariables) => void;
-}
-export interface UseMutationReturn<TVariables = void, TData = unknown> {
-    mutate: (variables: TVariables) => void;
-    mutateAsync: (variables: TVariables) => Promise<TData>;
-    reset: () => void;
-    data: TData | null;
-    error: Error | null;
-    status: MutationStatus;
-    isIdle: boolean;
-    isPending: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-}
-export declare const useMutation: <TVariables = void, TData = unknown>(options: UseMutationOptions<TVariables, TData>) => UseMutationReturn<TVariables, TData>;
-export {};

package/dist/src/hooks/use-mutation/use-mutation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/src/hooks/use-async/index.ts

@@ -1 +0,0 @@
-export * from "./use-async";

package/src/hooks/use-async/use-async.stories.tsx

@@ -1,272 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { useState } from "react";
-import { Button } from "../../components";
-import { useAsync } from "./use-async";
-
-// ─── Types ─────────────────────────────────────────────────────────────────────
-
-interface DemoData {
-  message: string;
-  timestamp: string;
-}
-
-// ─── Demo component ────────────────────────────────────────────────────────────
-
-type AsyncDemoProps = {
-  /** Simulated async delay in ms */
-  delay?: number;
-  /** When true the demo's fn rejects with a simulated error */
-  shouldFail?: boolean;
-  enabled?: boolean;
-  keepPreviousData?: boolean;
-  onSuccess?: (data: DemoData) => void;
-  onError?: (error: Error) => void;
-  onSettled?: (data: DemoData | null, error: Error | null) => void;
-};
-
-const AsyncDemo = ({
-  delay = 800,
-  shouldFail = false,
-  enabled = true,
-  keepPreviousData = false,
-  onSuccess,
-  onError,
-  onSettled,
-}: AsyncDemoProps) => {
-  const [log, setLog] = useState<string[]>([]);
-
-  const addLog = (msg: string) =>
-    setLog((prev) => [
-      `[${new Date().toISOString().slice(11, 23)}] ${msg}`,
-      ...prev,
-    ]);
-
-  const { status, data, error, loading, refetch } = useAsync<DemoData>({
-    fn: async (signal) => {
-      await new Promise<void>((res, rej) => {
-        const timer = setTimeout(() => {
-          if (shouldFail) rej(new Error("Simulated failure"));
-          else res();
-        }, delay);
-        signal.addEventListener("abort", () => clearTimeout(timer));
-      });
-      return {
-        message: "Data loaded successfully",
-        timestamp: new Date().toLocaleTimeString(),
-      };
-    },
-    enabled,
-    keepPreviousData,
-    onSuccess: (d) => {
-      addLog(`onSuccess — ${d.message} at ${d.timestamp}`);
-      onSuccess?.(d);
-    },
-    onError: (e) => {
-      addLog(`onError — ${e.message}`);
-      onError?.(e);
-    },
-    onSettled: (d, e) => {
-      addLog(
-        `onSettled — data: ${d ? d.timestamp : "null"}, error: ${e?.message ?? "null"}`,
-      );
-      onSettled?.(d, e);
-    },
-  });
-
-  return (
-    <div className="flex flex-col gap-4 max-w-sm">
-      <Button variant="outline" onClick={refetch} disabled={loading}>
-        {loading ? "Loading…" : "Refetch"}
-      </Button>
-
-      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
-        {JSON.stringify(
-          {
-            status,
-            loading,
-            data,
-            error: error?.message ?? null,
-          },
-          null,
-          2,
-        )}
-      </pre>
-
-      {log.length > 0 && (
-        <div className="rounded-md border bg-muted p-3 text-xs font-mono space-y-0.5">
-          {log.map((entry, i) => (
-            // biome-ignore lint/suspicious/noArrayIndexKey: log is append-only
-            <div key={i}>{entry}</div>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-};
-
-// ─── Meta ─────────────────────────────────────────────────────────────────────
-
-const meta: Meta<typeof AsyncDemo> = {
-  title: "hooks/useAsync",
-  component: AsyncDemo,
-  parameters: {
-    docs: {
-      description: {
-        component: `
-\`useAsync\` runs an async function automatically when its \`deps\` change.
-
-**API summary**
-
-\`\`\`ts
-const { data, error, status, loading, isIdle, isSuccess, isError, refetch } =
-  useAsync({ fn, deps?, enabled?, keepPreviousData?, onSuccess?, onError?, onSettled? });
-\`\`\`
-
-**Key behaviors**
-- \`fn(signal)\` receives an \`AbortSignal\` — pass it to \`fetch\` to cancel in-flight requests on cleanup.
-- Runs on mount (when \`enabled: true\`) and re-runs whenever \`deps\` change.
-- Race-safe: if \`deps\` change before \`fn\` resolves, the stale response is silently discarded.
-- \`enabled: false\` keeps the hook in \`'idle'\` state — no request fires until \`enabled\` becomes \`true\`.
-- \`keepPreviousData: true\` retains the last resolved \`data\` while a new request is in-flight.
-- \`refetch()\` manually re-triggers without changing deps. Stable reference across renders.
-- All callbacks read through \`useLatestRef\` — inline functions never cause re-subscriptions.
-        `.trim(),
-      },
-    },
-  },
-  argTypes: {
-    delay: {
-      control: { type: "range", min: 0, max: 3000, step: 100 },
-      description:
-        "Simulated async delay in ms. Demo control only — not a hook option.",
-      table: { category: "Demo controls" },
-    },
-    shouldFail: {
-      control: "boolean",
-      description:
-        "When true the demo's fn rejects. Toggle then click Refetch to see the error state.",
-      table: { category: "Demo controls" },
-    },
-    enabled: {
-      control: "boolean",
-      description:
-        "When false the hook stays idle and no request fires. Set to true to trigger the first run.",
-      table: {
-        category: "Hook options",
-        type: { summary: "boolean" },
-        defaultValue: { summary: "true" },
-      },
-    },
-    keepPreviousData: {
-      control: "boolean",
-      description:
-        "When true, `data` is preserved while a new request is in-flight instead of being reset to null.",
-      table: {
-        category: "Hook options",
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
-    },
-    onSuccess: {
-      action: "onSuccess",
-      description: "Called with `data` after `fn` resolves successfully.",
-      table: {
-        category: "Hook options",
-        type: { summary: "(data: T) => void" },
-      },
-    },
-    onError: {
-      action: "onError",
-      description:
-        "Called with the thrown `Error` when `fn` rejects. Abort errors are swallowed and never reach this callback.",
-      table: {
-        category: "Hook options",
-        type: { summary: "(error: Error) => void" },
-      },
-    },
-    onSettled: {
-      action: "onSettled",
-      description:
-        "Always called after `fn` settles — regardless of success or failure.",
-      table: {
-        category: "Hook options",
-        type: { summary: "(data: T | null, error: Error | null) => void" },
-      },
-    },
-  },
-  render: (args) => <AsyncDemo {...args} />,
-};
-
-export default meta;
-type Story = StoryObj<typeof AsyncDemo>;
-
-// ─── Stories ──────────────────────────────────────────────────────────────────
-
-export const Default: Story = {
-  args: {
-    delay: 800,
-    shouldFail: false,
-    enabled: true,
-    keepPreviousData: false,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Runs on mount, transitions through `pending` → `success`, then populates `data`. Click **Refetch** to re-trigger manually. Toggle **shouldFail** in controls then refetch to see the error path.",
-      },
-    },
-  },
-};
-
-export const ErrorState: Story = {
-  name: "Error",
-  args: {
-    delay: 600,
-    shouldFail: true,
-    enabled: true,
-    keepPreviousData: false,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "`fn` rejects immediately — `status` becomes `'error'`, `error` is populated, and `data` stays null. `onError` and `onSettled` both fire. Toggle **shouldFail** off then click Refetch to recover.",
-      },
-    },
-  },
-};
-
-export const WithEnabled: Story = {
-  args: {
-    delay: 800,
-    shouldFail: false,
-    enabled: false,
-    keepPreviousData: false,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Starts with `enabled: false` — the hook is in `'idle'` state and no request fires. Flip **enabled** to true in controls to trigger the first run.",
-      },
-    },
-  },
-};
-
-export const WithKeepPreviousData: Story = {
-  args: {
-    delay: 1500,
-    shouldFail: false,
-    enabled: true,
-    keepPreviousData: true,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "With `keepPreviousData: true`, the previous `data` stays visible while the next request is in-flight (`status: 'pending'`). Click **Refetch** to see stale data persist during the 1.5 s delay.",
-      },
-    },
-  },
-};