@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

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

@@ -0,0 +1,135 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+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 function useAsync<T>({
+  fn,
+  deps = [],
+  enabled = true,
+  keepPreviousData = false,
+  onSuccess,
+  onError,
+  onSettled,
+}: UseAsyncOptions<T>): UseAsyncReturn<T> {
+  const [status, setStatus] = useState<AsyncStatus>(
+    enabled ? "pending" : "idle",
+  );
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Stable callback refs — never cause effect re-subscriptions
+  const fnRef = useLatestRef(fn);
+  const onSuccessRef = useLatestRef(onSuccess);
+  const onErrorRef = useLatestRef(onError);
+  const onSettledRef = useLatestRef(onSettled);
+
+  // Monotonically incrementing request ID — guards stale setState
+  const requestIdRef = useRef(0);
+
+  // Tick cell — bumping this from refetch() forces the effect to re-run
+  // without creating a new execute function identity
+  const [refetchTick, setRefetchTick] = useState(0);
+
+  // Stable execute — never changes identity; receives AbortSignal + request id
+  const execute = useCallback(
+    async (signal: AbortSignal, id: number): Promise<void> => {
+      let settled: T | null = null;
+      let settledError: Error | null = null;
+
+      try {
+        const result = await fnRef.current(signal);
+
+        // Stale-skip: abort or superseded by a newer request
+        if (id !== requestIdRef.current || signal.aborted) return;
+
+        settled = result;
+        setData(result);
+        setStatus("success");
+        onSuccessRef.current?.(result);
+      } catch (err) {
+        // Abort errors are swallowed — not surfaced to error state or onError
+        if (signal.aborted) return;
+
+        // Stale-skip for non-abort errors too
+        if (id !== requestIdRef.current) return;
+
+        const coerced = err instanceof Error ? err : new Error(String(err));
+        settledError = coerced;
+        setError(coerced);
+        setStatus("error");
+        onErrorRef.current?.(coerced);
+      } finally {
+        // Only call onSettled if this is still the current request and not aborted
+        if (id === requestIdRef.current && !signal.aborted) {
+          onSettledRef.current?.(settled, settledError);
+        }
+      }
+    },
+    // All deps are refs — this callback is effectively stable
+    [fnRef, onSuccessRef, onErrorRef, onSettledRef],
+  );
+
+  // Stable refetch — bumps tick to trigger the effect
+  const refetch = useCallback(() => {
+    setRefetchTick((n) => n + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      setStatus("idle");
+      return;
+    }
+
+    // Bump request ID and capture local copy for stale-skip checks
+    requestIdRef.current += 1;
+    const id = requestIdRef.current;
+
+    const controller = new AbortController();
+
+    setStatus("pending");
+    setError(null);
+    if (!keepPreviousData) {
+      setData(null);
+    }
+
+    execute(controller.signal, id);
+
+    return () => {
+      controller.abort();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...deps, enabled, execute, refetchTick]);
+
+  return {
+    data,
+    error,
+    status,
+    loading: status === "pending",
+    isIdle: status === "idle",
+    isSuccess: status === "success",
+    isError: status === "error",
+    refetch,
+  };
+}

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

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

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

@@ -0,0 +1,377 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { useBoolean } from "./use-boolean";
+
+// ─── Shared UI helpers ─────────────────────────────────────────────────────────
+
+const JsonPanel = ({ value }: { value: unknown }) => (
+  <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed overflow-auto max-h-48">
+    {JSON.stringify(value, null, 2)}
+  </pre>
+);
+
+const LogPanel = ({ entries }: { entries: string[] }) =>
+  entries.length > 0 ? (
+    <div className="rounded-md border bg-muted p-3 text-xs font-mono space-y-0.5">
+      {entries.map((entry, i) => (
+        <div key={i}>{entry}</div>
+      ))}
+    </div>
+  ) : (
+    <div className="rounded-md border bg-muted p-3 text-xs font-mono text-muted-foreground">
+      No events yet — log is empty until the first mutation (proves onChange
+      does not fire on mount).
+    </div>
+  );
+
+const timestamp = () => new Date().toISOString().slice(11, 23);
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta = {
+  title: "hooks/useBoolean",
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useBoolean\` manages a boolean value with a stable set of typed actions.
+
+**Key behaviors**
+- All 4 action references (\`toggle\`, \`setTrue\`, \`setFalse\`, \`set\`) are **stable across renders** — built once in \`useMemo([setState])\`. Safe to pass as props or include in dependency arrays.
+- \`toggle()\` flips the current value using a functional state updater — safe under React batching.
+- \`setTrue()\` / \`setFalse()\` set an explicit value; if the value is already at the target, React **bails out** with no re-render and no \`onChange\` fire.
+- \`set(value)\` sets the value explicitly — same bail-out semantics as \`setTrue\`/\`setFalse\`.
+- \`onChange\` fires after every real state transition but **not on initial mount**. Callback is read through \`useLatestRef\` — safe to pass inline.
+
+\`\`\`ts
+const [value, { toggle, setTrue, setFalse, set }] = useBoolean(initialValue?, { onChange? });
+\`\`\`
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    initialValue: {
+      description:
+        "The initial boolean value. Defaults to `false` when omitted.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    onChange: {
+      description:
+        "Called after every state change. NOT called on initial mount. Callback is read through `useLatestRef` — safe to pass as an inline function.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(value: boolean) => void" },
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ─── Story 1 — Default ────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  render: () => {
+    const [value, { toggle, setTrue, setFalse, set }] = useBoolean(false);
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div
+          className={`flex items-center justify-center rounded-lg border px-6 py-4 text-sm font-semibold transition-colors ${
+            value
+              ? "border-green-500 bg-green-50 text-green-700"
+              : "border-slate-300 bg-slate-50 text-slate-500"
+          }`}
+        >
+          <span
+            className={`mr-2 h-2.5 w-2.5 rounded-full ${value ? "bg-green-500" : "bg-slate-300"}`}
+          />
+          {value ? "ON" : "OFF"}
+        </div>
+
+        <div className="flex gap-2 flex-wrap">
+          <button
+            type="button"
+            onClick={toggle}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            Toggle
+          </button>
+          <button
+            type="button"
+            onClick={setTrue}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            Set True
+          </button>
+          <button
+            type="button"
+            onClick={setFalse}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            Set False
+          </button>
+          <button
+            type="button"
+            onClick={() => set(true)}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            set(true)
+          </button>
+        </div>
+
+        <JsonPanel value={value} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Basic toggle with a visual ON/OFF indicator. The colored badge reflects the current state. All 4 actions are wired to buttons — try toggling and observe the state update in the JSON panel.",
+      },
+    },
+  },
+};
+
+// ─── Story 2 — AllActions ─────────────────────────────────────────────────────
+
+export const AllActions: Story = {
+  render: () => {
+    const [value, { toggle, setTrue, setFalse, set }] = useBoolean(false);
+
+    const actions = [
+      {
+        label: "toggle()",
+        desc: "Flips the current value (false → true → false)",
+        fn: toggle,
+        color: "border-blue-300 hover:bg-blue-50",
+      },
+      {
+        label: "setTrue()",
+        desc: "Forces value to true — no-op if already true",
+        fn: setTrue,
+        color: "border-green-300 hover:bg-green-50",
+      },
+      {
+        label: "setFalse()",
+        desc: "Forces value to false — no-op if already false",
+        fn: setFalse,
+        color: "border-red-300 hover:bg-red-50",
+      },
+      {
+        label: "set(true)",
+        desc: "Explicit set — same bail-out semantics as setTrue",
+        fn: () => set(true),
+        color: "border-amber-300 hover:bg-amber-50",
+      },
+    ];
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="grid grid-cols-2 gap-2">
+          {actions.map(({ label, desc, fn, color }) => (
+            <button
+              key={label}
+              type="button"
+              onClick={fn}
+              className={`rounded-md border p-3 text-left transition-colors ${color}`}
+            >
+              <p className="text-sm font-mono font-medium">{label}</p>
+              <p className="text-xs text-muted-foreground mt-0.5">{desc}</p>
+            </button>
+          ))}
+        </div>
+
+        <div
+          className={`rounded-lg border px-4 py-3 text-center text-lg font-bold transition-colors ${
+            value
+              ? "border-green-400 bg-green-50 text-green-700"
+              : "border-slate-300 bg-slate-50 text-slate-500"
+          }`}
+        >
+          {String(value)}
+        </div>
+
+        <JsonPanel value={value} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Each action is presented as a labeled card with its description. `toggle()` always flips. `setTrue()` and `setFalse()` are idempotent — clicking them repeatedly when the value is already at the target causes no re-render. `set(value)` gives explicit control.",
+      },
+    },
+  },
+};
+
+// ─── Story 3 — WithOnChange ────────────────────────────────────────────────────
+
+export const WithOnChange: Story = {
+  render: () => {
+    const [log, setLog] = useState<string[]>([]);
+
+    const addLog = (value: boolean) =>
+      setLog((prev) => [
+        `[${timestamp()}] onChange → ${String(value)}`,
+        ...prev,
+      ]);
+
+    const [value, { toggle, setTrue, setFalse, set }] = useBoolean(false, {
+      onChange: addLog,
+    });
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <p className="text-xs text-muted-foreground">
+          The log below starts empty — proving <code>onChange</code> does not
+          fire on initial mount. No-op calls (e.g. <code>setTrue()</code> when
+          already <code>true</code>) also produce no log entry.
+        </p>
+
+        <div className="flex gap-2 flex-wrap">
+          <button
+            type="button"
+            onClick={toggle}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            Toggle
+          </button>
+          <button
+            type="button"
+            onClick={setTrue}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            setTrue
+          </button>
+          <button
+            type="button"
+            onClick={setFalse}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            setFalse
+          </button>
+          <button
+            type="button"
+            onClick={() => set(!value)}
+            className="rounded-md border px-3 py-1.5 text-sm hover:bg-accent transition-colors"
+          >
+            set(!value)
+          </button>
+          <button
+            type="button"
+            onClick={() => setLog([])}
+            className="rounded-md border px-3 py-1.5 text-sm text-muted-foreground hover:bg-accent transition-colors"
+          >
+            Clear log
+          </button>
+        </div>
+
+        <JsonPanel value={value} />
+        <LogPanel entries={log} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Wires `onChange` to a visible log panel. The log is empty on mount (no initial fire). No-op actions — like `setTrue()` when already `true` — produce no log entry because React bails out of the commit and the `useEffect([state])` does not re-run.",
+      },
+    },
+  },
+};
+
+// ─── Story 4 — RealWorld ──────────────────────────────────────────────────────
+
+export const RealWorld: Story = {
+  render: () => {
+    const [showPassword, { toggle }] = useBoolean(false);
+    const [inputValue, setInputValue] = useState("");
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <p className="text-sm text-muted-foreground">
+          Password field with visibility toggle — mirrors the{" "}
+          <code>Password</code> component usage of <code>useBoolean</code>.
+        </p>
+
+        <div className="relative inline-flex h-9 w-full items-center rounded-md border border-input bg-background text-sm transition-shadow focus-within:border-ring">
+          <input
+            type={showPassword ? "text" : "password"}
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            placeholder="Enter password…"
+            className="min-w-0 flex-1 bg-transparent pl-3 outline-none placeholder:text-muted-foreground"
+          />
+          <button
+            type="button"
+            onClick={toggle}
+            className="flex shrink-0 items-center px-2.5 text-muted-foreground hover:text-foreground transition-colors"
+            aria-label={showPassword ? "Hide password" : "Show password"}
+          >
+            {showPassword ? (
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M9.88 9.88a3 3 0 1 0 4.24 4.24" />
+                <path d="M10.73 5.08A10.43 10.43 0 0 1 12 5c7 0 10 7 10 7a13.16 13.16 0 0 1-1.67 2.68" />
+                <path d="M6.61 6.61A13.526 13.526 0 0 0 2 12s3 7 10 7a9.74 9.74 0 0 0 5.39-1.61" />
+                <line x1="2" x2="22" y1="2" y2="22" />
+              </svg>
+            ) : (
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z" />
+                <circle cx="12" cy="12" r="3" />
+              </svg>
+            )}
+          </button>
+        </div>
+
+        <div
+          className={`rounded-md border px-3 py-2 text-xs font-mono transition-colors ${
+            showPassword
+              ? "border-amber-300 bg-amber-50 text-amber-700"
+              : "border-slate-200 bg-slate-50 text-slate-500"
+          }`}
+        >
+          Input type: <strong>{showPassword ? "text" : "password"}</strong>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Realistic password visibility toggle — the exact pattern used inside the `Password` component. `useBoolean(false)` drives the input type between `password` and `text`. The eye icon and state indicator update on each toggle.",
+      },
+    },
+  },
+};

package/src/hooks/use-boolean/use-boolean.test.tsx

@@ -0,0 +1,177 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useBoolean } from "./use-boolean";
+
+describe("useBoolean", () => {
+  // ─── initialization ─────────────────────────────────────────────────────────
+
+  describe("initialization", () => {
+    it("default value is false when no initialValue is provided", () => {
+      const { result } = renderHook(() => useBoolean());
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("initialValue true is honored", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      expect(result.current[0]).toBe(true);
+    });
+  });
+
+  // ─── toggle ──────────────────────────────────────────────────────────────────
+
+  describe("toggle", () => {
+    it("flips false → true", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      act(() => result.current[1].toggle());
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("double toggle returns to original value", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      act(() => {
+        result.current[1].toggle();
+        result.current[1].toggle();
+      });
+      expect(result.current[0]).toBe(false);
+    });
+  });
+
+  // ─── setTrue ─────────────────────────────────────────────────────────────────
+
+  describe("setTrue", () => {
+    it("sets to true from false", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      act(() => result.current[1].setTrue());
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("repeated setTrue does not throw and value stays true", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      expect(() => {
+        act(() => result.current[1].setTrue());
+      }).not.toThrow();
+      expect(result.current[0]).toBe(true);
+    });
+  });
+
+  // ─── setFalse ────────────────────────────────────────────────────────────────
+
+  describe("setFalse", () => {
+    it("sets to false from true", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      act(() => result.current[1].setFalse());
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("repeated setFalse does not throw and value stays false", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      expect(() => {
+        act(() => result.current[1].setFalse());
+      }).not.toThrow();
+      expect(result.current[0]).toBe(false);
+    });
+  });
+
+  // ─── set ─────────────────────────────────────────────────────────────────────
+
+  describe("set", () => {
+    it("set(true) from false", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      act(() => result.current[1].set(true));
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("set(false) from true", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      act(() => result.current[1].set(false));
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("set to same value does not throw", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      expect(() => {
+        act(() => result.current[1].set(true));
+      }).not.toThrow();
+      expect(result.current[0]).toBe(true);
+    });
+  });
+
+  // ─── action stability ─────────────────────────────────────────────────────────
+
+  describe("action stability", () => {
+    it("actions object reference is stable after toggle (re-render)", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      const actionsBefore = result.current[1];
+      act(() => result.current[1].toggle());
+      expect(result.current[1]).toBe(actionsBefore);
+    });
+
+    it("all 4 fn refs are stable across re-renders", () => {
+      const { result } = renderHook(() => useBoolean(false));
+      const { toggle, setTrue, setFalse, set } = result.current[1];
+      act(() => result.current[1].toggle());
+      expect(result.current[1].toggle).toBe(toggle);
+      expect(result.current[1].setTrue).toBe(setTrue);
+      expect(result.current[1].setFalse).toBe(setFalse);
+      expect(result.current[1].set).toBe(set);
+    });
+  });
+
+  // ─── onChange ─────────────────────────────────────────────────────────────────
+
+  describe("onChange", () => {
+    it("not fired on initial mount", () => {
+      const onChange = vi.fn();
+      renderHook(() => useBoolean(false, { onChange }));
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("fired after toggle with the new value", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useBoolean(false, { onChange }));
+      act(() => result.current[1].toggle());
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(true);
+    });
+
+    it("fired after setTrue", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useBoolean(false, { onChange }));
+      act(() => result.current[1].setTrue());
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(true);
+    });
+
+    it("not fired when setTrue is a no-op (already true)", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useBoolean(true, { onChange }));
+      act(() => result.current[1].setTrue());
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("fired after set(false) from true", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useBoolean(true, { onChange }));
+      act(() => result.current[1].set(false));
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(false);
+    });
+  });
+
+  // ─── edge cases ───────────────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("initialValue=true, toggle → false", () => {
+      const { result } = renderHook(() => useBoolean(true));
+      act(() => result.current[1].toggle());
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("set(true) when already true → onChange NOT called", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useBoolean(true, { onChange }));
+      act(() => result.current[1].set(true));
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+});