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

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

@@ -0,0 +1,350 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components";
+import { useObject } from "./use-object";
+
+// ─── 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/useObject",
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useObject\` manages plain-object state with a stable set of typed actions.
+
+**Key behaviors**
+- All 4 action references (\`set\`, \`replace\`, \`reset\`, \`setKey\`) are **stable across renders** — built once in \`useMemo([setState])\`. Safe to pass as props or include in dependency arrays.
+- \`set\` **shallow-merges** a partial (or functional updater) into current state — unmentioned keys are preserved.
+- \`replace\` **swaps the entire object** — unmentioned keys are discarded. Use it when you need a clean slate.
+- \`reset()\` restores the **mount-time value** regardless of prop changes after mount (frozen ref pattern).
+- \`onChange\` fires after every state change but **not on initial mount**. Passing a new inline callback reference between renders does not cause double-fires (\`useLatestRef\` pattern).
+- \`setKey(key, value)\` is fully type-safe: \`key\` is constrained to \`keyof T\` and \`value\` must be \`T[K]\`.
+
+\`\`\`ts
+const [state, { set, replace, reset, setKey }] = useObject(initialValue, { onChange? });
+\`\`\`
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    initialValue: {
+      description:
+        "The initial object value. Captured once on mount — `reset()` always restores this value regardless of later prop changes.",
+      table: {
+        category: "Hook options",
+        type: { summary: "T extends object" },
+      },
+    },
+    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: "(state: T) => void" },
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ─── Story 1 — Default (User Profile Form) ────────────────────────────────────
+
+export const Default: Story = {
+  render: () => {
+    const INITIAL = { name: "", email: "", role: "viewer" };
+    const [state, actions] = useObject(INITIAL);
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="flex flex-col gap-1">
+          <label className="text-sm font-medium">Name</label>
+          <input
+            className="rounded-md border px-3 py-2 text-sm"
+            value={state.name}
+            onChange={(e) => actions.setKey("name", e.target.value)}
+            placeholder="Full name"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <label className="text-sm font-medium">Email</label>
+          <input
+            className="rounded-md border px-3 py-2 text-sm"
+            value={state.email}
+            onChange={(e) => actions.setKey("email", e.target.value)}
+            placeholder="you@example.com"
+          />
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <label className="text-sm font-medium">Role</label>
+          <input
+            className="rounded-md border px-3 py-2 text-sm"
+            value={state.role}
+            onChange={(e) => actions.setKey("role", e.target.value)}
+            placeholder="viewer / editor / admin"
+          />
+        </div>
+
+        <Button variant="outline" onClick={() => actions.reset()}>
+          Reset
+        </Button>
+
+        <JsonPanel value={state} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "User profile form wired via `setKey(key, value)` for type-safe single-key updates. The Reset button restores the mount-time value — change any field then click Reset to see it.",
+      },
+    },
+  },
+};
+
+// ─── Story 2 — FunctionalUpdaters ─────────────────────────────────────────────
+
+export const FunctionalUpdaters: Story = {
+  render: () => {
+    const INITIAL = { score: 0, multiplier: 2, label: "light" };
+    const [state, actions] = useObject(INITIAL);
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="flex items-center gap-2">
+          <label className="text-sm shrink-0">Multiplier</label>
+          <input
+            type="number"
+            min={1}
+            max={10}
+            className="w-20 rounded-md border px-2 py-1.5 text-sm"
+            value={state.multiplier}
+            onChange={(e) =>
+              actions.setKey("multiplier", Number(e.target.value))
+            }
+          />
+        </div>
+
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            variant="outline"
+            onClick={() =>
+              actions.set((s) => ({ score: s.score + s.multiplier }))
+            }
+          >
+            Boost score (set)
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() =>
+              actions.replace((s) => ({
+                score: 0,
+                multiplier: 1,
+                label: s.label === "light" ? "dark" : "light",
+              }))
+            }
+          >
+            Toggle theme (replace)
+          </Button>
+          <Button variant="outline" onClick={() => actions.reset()}>
+            Reset
+          </Button>
+        </div>
+
+        <p className="text-xs text-muted-foreground">
+          <strong>Boost score</strong> uses <code>set(fn)</code> — merges only{" "}
+          <code>score</code>, preserving <code>multiplier</code> and{" "}
+          <code>label</code>.<br />
+          <strong>Toggle theme</strong> uses <code>replace(fn)</code> — must
+          rebuild every key; anything omitted would be lost.
+        </p>
+
+        <JsonPanel value={state} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Contrasts `set(fn)` (shallow merge — untouched keys survive) vs `replace(fn)` (full swap — you must supply all keys). Boost score increments by the current multiplier while keeping other fields intact. Toggle theme rebuilds the whole object.",
+      },
+    },
+  },
+};
+
+// ─── Story 3 — ReplaceVsSet ───────────────────────────────────────────────────
+
+export const ReplaceVsSet: Story = {
+  render: () => {
+    const INITIAL = { a: "alpha", b: "beta", c: "gamma" };
+    const [setState, setActions] = useObject({ ...INITIAL });
+    const [replaceState, replaceActions] = useObject({ ...INITIAL });
+
+    return (
+      <div className="flex gap-6 flex-wrap">
+        <div className="flex flex-col gap-3 flex-1 min-w-48">
+          <p className="text-sm font-semibold">
+            <code>set({'{ a: "new" }'})</code>
+          </p>
+          <p className="text-xs text-muted-foreground">
+            Merges — <code>b</code> and <code>c</code> are preserved.
+          </p>
+          <Button
+            variant="outline"
+            onClick={() => setActions.set({ a: "new" })}
+          >
+            set({' { a: "new" }'})
+          </Button>
+          <Button variant="outline" onClick={() => setActions.reset()}>
+            Reset
+          </Button>
+          <JsonPanel value={setState} />
+        </div>
+
+        <div className="flex flex-col gap-3 flex-1 min-w-48">
+          <p className="text-sm font-semibold">
+            <code>replace({'{ a: "new" }'})</code>
+          </p>
+          <p className="text-xs text-muted-foreground">
+            Swaps — <code>b</code> and <code>c</code> vanish.
+          </p>
+          <Button
+            variant="outline"
+            onClick={() =>
+              replaceActions.replace({ a: "new" } as {
+                a: string;
+                b: string;
+                c: string;
+              })
+            }
+          >
+            replace({' { a: "new" }'})
+          </Button>
+          <Button variant="outline" onClick={() => replaceActions.reset()}>
+            Reset
+          </Button>
+          <JsonPanel value={replaceState} />
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Side-by-side comparison: `set({ a: "new" })` keeps `b` and `c` intact (shallow merge). `replace({ a: "new" })` discards `b` and `c` (full swap). The JsonPanel makes the difference visible immediately.',
+      },
+    },
+  },
+};
+
+// ─── Story 4 — WithOnChange ────────────────────────────────────────────────────
+
+export const WithOnChange: Story = {
+  render: () => {
+    const INITIAL = { name: "", email: "" };
+    const [log, setLog] = useState<string[]>([]);
+
+    const addLog = (action: string, s: typeof INITIAL) =>
+      setLog((prev) => [
+        `[${timestamp()}] ${action} → ${JSON.stringify(s)}`,
+        ...prev,
+      ]);
+
+    const [state, actions] = useObject(INITIAL, {
+      onChange: (s) => addLog("onChange", s),
+    });
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <p className="text-xs text-muted-foreground">
+          The log panel below starts empty — proving <code>onChange</code> does
+          not fire on initial mount. Every button triggers a real mutation.
+        </p>
+
+        <div className="flex flex-col gap-1">
+          <label className="text-sm font-medium">Name</label>
+          <input
+            className="rounded-md border px-3 py-2 text-sm"
+            value={state.name}
+            onChange={(e) => actions.setKey("name", e.target.value)}
+            placeholder="Type to trigger setKey..."
+          />
+        </div>
+
+        <div className="flex flex-col gap-1">
+          <label className="text-sm font-medium">Email</label>
+          <input
+            className="rounded-md border px-3 py-2 text-sm"
+            value={state.email}
+            onChange={(e) => actions.setKey("email", e.target.value)}
+            placeholder="Type to trigger setKey..."
+          />
+        </div>
+
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            variant="outline"
+            onClick={() => actions.set({ name: "Bob" })}
+          >
+            set name
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => actions.replace({ name: "Charlie", email: "" })}
+          >
+            replace
+          </Button>
+          <Button variant="outline" onClick={() => actions.reset()}>
+            reset
+          </Button>
+          <Button variant="outline" onClick={() => setLog([])}>
+            Clear log
+          </Button>
+        </div>
+
+        <JsonPanel value={state} />
+        <LogPanel entries={log} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Wires `onChange` to a visible log panel. The log is empty on mount (no initial fire). Each mutation appends a timestamped entry. Passing a new inline `onChange` reference between renders does not cause double-fires because the callback is read through `useLatestRef`.",
+      },
+    },
+  },
+};

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

@@ -0,0 +1,281 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useObject } from "../use-object";
+
+describe("useObject", () => {
+  // ─── initialization ───────────────────────────────────────────────────────
+
+  describe("initialization", () => {
+    it("returns [state, actions] tuple where state deep-equals initialValue", () => {
+      const init = { name: "Alice", age: 30 };
+      const { result } = renderHook(() => useObject(init));
+
+      expect(result.current[0]).toEqual(init);
+    });
+
+    it("actions object exposes set, replace, reset, setKey", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const actions = result.current[1];
+
+      expect(typeof actions.set).toBe("function");
+      expect(typeof actions.replace).toBe("function");
+      expect(typeof actions.reset).toBe("function");
+      expect(typeof actions.setKey).toBe("function");
+    });
+  });
+
+  // ─── set (merge) ──────────────────────────────────────────────────────────
+
+  describe("set", () => {
+    it("set(partial) shallow-merges and preserves untouched keys", () => {
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", email: "a@a.com" }),
+      );
+
+      act(() => result.current[1].set({ name: "Bob" }));
+
+      expect(result.current[0]).toEqual({ name: "Bob", email: "a@a.com" });
+    });
+
+    it("set(fn) functional updater receives prev and merges returned partial", () => {
+      const { result } = renderHook(() => useObject({ count: 3 }));
+
+      act(() => result.current[1].set((s) => ({ count: s.count + 1 })));
+
+      expect(result.current[0]).toEqual({ count: 4 });
+    });
+
+    it("set({}) empty partial produces a new state reference", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].set({}));
+
+      expect(result.current[0]).not.toBe(before);
+    });
+  });
+
+  // ─── replace ──────────────────────────────────────────────────────────────
+
+  describe("replace", () => {
+    it("replace(value) swaps the whole object and discards unmentioned keys", () => {
+      const { result } = renderHook(() => useObject({ a: 1, b: 2 }));
+
+      act(() =>
+        result.current[1].replace({ a: 99 } as { a: number; b: number }),
+      );
+
+      expect(result.current[0]).toEqual({ a: 99 });
+      expect((result.current[0] as { b?: number }).b).toBeUndefined();
+    });
+
+    it("replace(fn) functional variant receives prev and fully replaces", () => {
+      const { result } = renderHook(() => useObject({ count: 5 }));
+
+      act(() => result.current[1].replace((s) => ({ count: s.count * 2 })));
+
+      expect(result.current[0]).toEqual({ count: 10 });
+    });
+
+    it("replace with identical values still produces a new state reference", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].replace({ x: 1 }));
+
+      expect(result.current[0]).not.toBe(before);
+    });
+  });
+
+  // ─── reset ────────────────────────────────────────────────────────────────
+
+  describe("reset", () => {
+    it("reset() restores mount-time value after mutation", () => {
+      const { result } = renderHook(() => useObject({ count: 0 }));
+
+      act(() => result.current[1].set({ count: 5 }));
+      expect(result.current[0]).toEqual({ count: 5 });
+
+      act(() => result.current[1].reset());
+
+      expect(result.current[0]).toEqual({ count: 0 });
+    });
+
+    it("reset() ignores prop changes after mount (frozen ref)", () => {
+      const { result, rerender } = renderHook(
+        ({ iv }: { iv: { count: number } }) => useObject(iv),
+        { initialProps: { iv: { count: 0 } } },
+      );
+
+      // Change the prop after mount
+      rerender({ iv: { count: 99 } });
+      act(() => result.current[1].set({ count: 5 }));
+      act(() => result.current[1].reset());
+
+      // Must restore the mount-time value, NOT the re-rendered prop
+      expect(result.current[0]).toEqual({ count: 0 });
+    });
+  });
+
+  // ─── setKey ───────────────────────────────────────────────────────────────
+
+  describe("setKey", () => {
+    it("setKey(key, value) updates one key and preserves the others", () => {
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", age: 30 }),
+      );
+
+      act(() => result.current[1].setKey("age", 31));
+
+      expect(result.current[0]).toEqual({ name: "Alice", age: 31 });
+    });
+
+    it("setKey only touches the specified key", () => {
+      const { result } = renderHook(() =>
+        useObject({ a: "x", b: "y", c: "z" }),
+      );
+
+      act(() => result.current[1].setKey("b", "updated"));
+
+      expect(result.current[0].a).toBe("x");
+      expect(result.current[0].b).toBe("updated");
+      expect(result.current[0].c).toBe("z");
+    });
+  });
+
+  // ─── action stability ─────────────────────────────────────────────────────
+
+  describe("action stability", () => {
+    it("actions object reference is stable across re-renders", () => {
+      const { result, rerender } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[1];
+
+      rerender();
+
+      expect(result.current[1]).toBe(before);
+    });
+
+    it("each individual action fn is stable across re-renders", () => {
+      const { result, rerender } = renderHook(() => useObject({ x: 1 }));
+      const { set, replace, reset, setKey } = result.current[1];
+
+      rerender();
+
+      expect(result.current[1].set).toBe(set);
+      expect(result.current[1].replace).toBe(replace);
+      expect(result.current[1].reset).toBe(reset);
+      expect(result.current[1].setKey).toBe(setKey);
+    });
+
+    it("changing onChange reference does not invalidate action refs", () => {
+      const { result, rerender } = renderHook(
+        ({ onChange }: { onChange: (s: { x: number }) => void }) =>
+          useObject({ x: 1 }, { onChange }),
+        { initialProps: { onChange: vi.fn() } },
+      );
+      const before = result.current[1];
+
+      rerender({ onChange: vi.fn() }); // new function reference
+
+      expect(result.current[1]).toBe(before);
+    });
+  });
+
+  // ─── onChange ─────────────────────────────────────────────────────────────
+
+  describe("onChange", () => {
+    it("does NOT fire on initial mount", () => {
+      const onChange = vi.fn();
+      renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("fires after set with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      act(() => result.current[1].set({ x: 2 }));
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 2 });
+    });
+
+    it("fires after replace with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() =>
+        useObject({ x: 1, y: 2 }, { onChange }),
+      );
+
+      act(() =>
+        result.current[1].replace({ x: 99 } as { x: number; y: number }),
+      );
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 99 });
+    });
+
+    it("fires after reset with the mount-time state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      act(() => result.current[1].set({ x: 5 }));
+      onChange.mockClear();
+
+      act(() => result.current[1].reset());
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 1 });
+    });
+
+    it("fires after setKey with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", age: 30 }, { onChange }),
+      );
+
+      act(() => result.current[1].setKey("age", 31));
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ name: "Alice", age: 31 });
+    });
+
+    it("new inline onChange reference between renders does not double-fire", () => {
+      const spy = vi.fn();
+      const { rerender } = renderHook(
+        ({ onChange }: { onChange: (s: { x: number }) => void }) =>
+          useObject({ x: 1 }, { onChange }),
+        { initialProps: { onChange: () => spy() } },
+      );
+
+      // Re-render with a fresh inline function — no state change
+      rerender({ onChange: () => spy() });
+
+      expect(spy).not.toHaveBeenCalled();
+    });
+  });
+
+  // ─── edge cases ───────────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("set({}) with empty partial is valid and produces a new reference", () => {
+      const { result } = renderHook(() => useObject({ a: 1 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].set({}));
+
+      expect(result.current[0]).not.toBe(before);
+      expect(result.current[0]).toEqual({ a: 1 });
+    });
+
+    it("replace with identical values still produces a new reference", () => {
+      const { result } = renderHook(() => useObject({ x: 42 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].replace({ x: 42 }));
+
+      expect(result.current[0]).not.toBe(before);
+      expect(result.current[0]).toEqual({ x: 42 });
+    });
+  });
+});

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

@@ -0,0 +1,59 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface UseObjectOptions<T> {
+  /** Called after every state change. NOT called on initial mount. */
+  onChange?: (state: T) => void;
+}
+
+export interface UseObjectActions<T> {
+  /** Shallow-merge a partial (or functional updater returning a partial). */
+  set(partial: Partial<T> | ((state: T) => Partial<T>)): void;
+  /** Replace the entire object (no merge). Functional variant receives prev. */
+  replace(value: T | ((state: T) => T)): void;
+  /** Restore the mount-time value (frozen ref). */
+  reset(): void;
+  /** Update a single typed key. */
+  setKey<K extends keyof T>(key: K, value: T[K]): void;
+}
+
+export function useObject<T extends object>(
+  initialValue: T,
+  options?: UseObjectOptions<T>,
+): readonly [T, UseObjectActions<T>] {
+  const [state, setState] = useState<T>(initialValue);
+
+  // Frozen on mount — reset always restores the original value.
+  const initialRef = useRef(initialValue);
+  // Always the latest handler — never a memo/effect dep.
+  const onChangeRef = useLatestRef(options?.onChange);
+
+  // Fire onChange on every change EXCEPT the initial mount.
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    onChangeRef.current?.(state);
+  }, [state]);
+
+  const actions = useMemo<UseObjectActions<T>>(
+    () => ({
+      set: (partial) =>
+        setState((prev) => ({
+          ...prev,
+          ...(typeof partial === "function" ? partial(prev) : partial),
+        })),
+      replace: (value) =>
+        setState((prev) =>
+          typeof value === "function" ? (value as (s: T) => T)(prev) : value,
+        ),
+      reset: () => setState(initialRef.current),
+      setKey: (key, value) => setState((prev) => ({ ...prev, [key]: value })),
+    }),
+    [setState],
+  );
+
+  return [state, actions] as const;
+}

package/src/hooks/use-on-mount/index.ts

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