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

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

@@ -1,119 +1,350 @@
-import { Meta } from "@storybook/react-vite";
-import { ChevronLeft, ChevronRight } from "lucide-react";
-import { Button, Input } from "../../components";
-import { useObject } from "../use-object";
-
-/**
- * Hook para manejar un estado en forma de objeto
- *
- * `@param initialValue` - Valor inicial del estado, se recomienda pasar para evitar el caso donde el estado `T` pueda ser `T | undefined`
- *
- * `@returns` [state, setState, reset]
- */
+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;
 
-interface Form {
-  name: string;
-  email: string;
-}
-
-function Results({ state }: { state?: Record<string, any> }) {
-  if (!state) return;
-  return (
-    <pre className="rounded-md bg-slate-950 p-4 text-white">
-      {Object.keys(state).map((key, i) => (
-        <code className="block flex gap-2" key={i}>
-          <span>{key}:</span>
-          <span className="text-blue-300">
-            {JSON.stringify(state[key as string], null, 2)}
-          </span>
-        </code>
-      ))}
-    </pre>
-  );
-}
+// ─── Story 1 — Default (User Profile Form) ────────────────────────────────────
 
-export const Default = {
+export const Default: Story = {
   render: () => {
-    const [state, setState, reset] = useObject<Form>({ name: "", email: "" });
+    const INITIAL = { name: "", email: "", role: "viewer" };
+    const [state, actions] = useObject(INITIAL);
 
     return (
-      <div className="grid gap-2">
-        <Input
-          name="name"
-          autoComplete="0"
-          value={state?.name}
-          onChange={(name) =>
-            setState({
-              name,
-            })
-          }
-        />
-        <Input
-          name="email"
-          autoComplete="0"
-          value={state?.email}
-          onChange={(email) =>
-            setState({
-              email,
-            })
-          }
-        />
-
-        <Button type="button" onClick={reset}>
+      <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>
 
-        <Results state={state} />
+        <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.",
+      },
+    },
+  },
 };
 
-interface Counter {
-  count: number;
-}
+// ─── Story 2 — FunctionalUpdaters ─────────────────────────────────────────────
 
-export const Counter = {
+export const FunctionalUpdaters: Story = {
   render: () => {
-    const [state, setState, reset] = useObject<Counter>({ count: 0 });
+    const INITIAL = { score: 0, multiplier: 2, label: "light" };
+    const [state, actions] = useObject(INITIAL);
 
     return (
-      <div className="space-y-2">
-        <div className="flex items-center gap-x-2">
+      <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
-            size="icon"
-            variant="ghost"
+            variant="outline"
             onClick={() =>
-              setState((state) => ({
-                count: state.count - 1,
-              }))
+              actions.set((s) => ({ score: s.score + s.multiplier }))
             }
           >
-            <ChevronLeft />
+            Boost score (set)
           </Button>
-          {state?.count}
           <Button
-            size="icon"
-            variant="ghost"
+            variant="outline"
             onClick={() =>
-              setState((state) => ({
-                count: state.count + 1,
+              actions.replace((s) => ({
+                score: 0,
+                multiplier: 1,
+                label: s.label === "light" ? "dark" : "light",
               }))
             }
           >
-            <ChevronRight />
+            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 type="button" onClick={reset}>
+          <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>
-        <Results state={state} />
+
+        <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`.",
+      },
+    },
+  },
 };