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

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

@@ -1,100 +1,471 @@
-import { Meta, StoryObj } from "@storybook/react-vite";
-import { Trash } from "lucide-react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
 import { Button } from "../../components";
-import { useArray } from "../use-array";
-
-/**
- * Hook que facilita el manejo de estado de una lista
- * Se exponen los siguientes métodos:
- *
- * | Método | Descripción |
- * | --- | --- |
- * | `insertAt(index: number, item: T)` | Inserta un elemento en un índice específico en la lista. |
- * | `removeAt(index: number)` | Elimina un elemento en un índice específico de la lista. |
- * | `updateAt(index: number, newItem: T)` | Actualiza un elemento en un índice específico de la lista. |
- * | `clear()` | Elimina todos los elementos de la lista. |
- * | `reset()` | Restablece la lista a su valor por defecto o inicial. |
- * | `push(item: T)` | Agrega un nuevo elemento al final de la lista. |
- * | `pop()` | Elimina el último elemento de la lista. |
- * | `set(newList: T[])` | Actualiza la lista con una nueva lista. |
- * | `update(predicate: ListIterateeCustom<T, boolean>, newItem: T | (item: T) => T)` | Actualiza un elemento de la lista.
- */
+import { useArray } from "./use-array";
+
+// ─── Types ─────────────────────────────────────────────────────────────────────
+
+interface ActiveItem {
+  id: number;
+  name: string;
+  active: 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);
+
+// ─── Shared data ───────────────────────────────────────────────────────────────
+
+const INITIAL_ITEMS: ActiveItem[] = [
+  { id: 1, name: "Alice", active: true },
+  { id: 2, name: "Bob", active: false },
+  { id: 3, name: "Charlie", active: true },
+  { id: 4, name: "Diana", active: false },
+];
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
 const meta: Meta = {
   title: "hooks/useArray",
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useArray\` manages array state with a stable set of immutable actions.
+
+**Key behaviors**
+- All 17 action references are **stable across renders** — built once in \`useMemo([setList])\`. Safe to pass as props or include in dependency arrays without causing extra renders.
+- Every mutating action returns a **new array reference** — React change detection always works correctly.
+- \`sort\` and \`reverse\` spread the previous state before calling the native method, preventing in-place mutation.
+- \`replace\` returns the previous ref unchanged when the predicate matches nothing — no phantom re-render, no spurious \`onChange\`.
+- \`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**.
+
+\`\`\`ts
+const [list, actions] = useArray(initialValue, { onChange? });
+\`\`\`
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    initialValue: {
+      description:
+        "The initial array value. Captured once on mount — `reset()` always restores this value regardless of later prop changes.",
+      table: {
+        category: "Hook options",
+        type: { summary: "T[]" },
+      },
+    },
+  },
 };
 
 export default meta;
+type Story = StoryObj;
 
-type Story = StoryObj<typeof meta>;
+// ─── Story 1 — Default (Core CRUD) ────────────────────────────────────────────
 
 export const Default: Story = {
   render: () => {
-    const [list, { insertAt, removeAt, clear, reset, pop, update }] =
-      useArray<string>(["First", "Second", "Third"]);
+    const INITIAL = ["First", "Second", "Third"];
+    const [inputValue, setInputValue] = useState("");
+    const [list, actions] = useArray<string>(INITIAL);
+
+    const handlePush = () => {
+      const val = inputValue.trim();
+      if (!val) return;
+      actions.push(val);
+      setInputValue("");
+    };
 
     return (
-      <div className="space-y-2">
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="flex gap-2">
+          <input
+            className="flex-1 rounded-md border px-3 py-2 text-sm"
+            placeholder="Type an item..."
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            onKeyDown={(e) => e.key === "Enter" && handlePush()}
+          />
+          <Button variant="outline" onClick={handlePush}>
+            Push
+          </Button>
+        </div>
+
         <div className="flex gap-2 flex-wrap">
-          <Button disabled={list.length < 1} onClick={() => insertAt(1, "woo")}>
-            Insertar despúes del primero
+          <Button
+            variant="outline"
+            onClick={() => actions.insertAt(0, "Prepended")}
+          >
+            Prepend
           </Button>
-          <Button disabled={list.length < 2} onClick={() => removeAt(1)}>
-            Eliminar segundo item
+          <Button
+            variant="outline"
+            disabled={list.length === 0}
+            onClick={() => actions.pop()}
+          >
+            Pop
           </Button>
-          <Button disabled={list.length < 2} onClick={() => pop()}>
-            Eliminar el último item
+          <Button variant="outline" onClick={() => actions.reset()}>
+            Reset
+          </Button>
+          <Button variant="outline" onClick={() => actions.clear()}>
+            Clear
+          </Button>
+        </div>
+
+        {list.length > 0 && (
+          <ul className="space-y-1">
+            {list.map((item, index) => (
+              <li
+                key={index}
+                className="flex items-center justify-between rounded-md border px-3 py-1.5 text-sm"
+              >
+                <span>{item}</span>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => actions.removeAt(index)}
+                >
+                  Remove
+                </Button>
+              </li>
+            ))}
+          </ul>
+        )}
+
+        <JsonPanel value={list} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Core CRUD: push, pop, prepend via `insertAt(0)`, removeAt per row, reset (restores mount-time value), and clear. Type in the input and press Enter or click **Push** to add items.",
+      },
+    },
+  },
+};
+
+// ─── Story 2 — SearchAndTransform ─────────────────────────────────────────────
+
+export const SearchAndTransform: Story = {
+  render: () => {
+    const [list, actions] = useArray<ActiveItem>(INITIAL_ITEMS);
+    const [findResult, setFindResult] = useState<ActiveItem | undefined>(
+      undefined,
+    );
+    const [searched, setSearched] = useState(false);
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            variant="outline"
+            onClick={() => actions.filter((item) => item.active)}
+          >
+            Filter active only
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => {
+              const found = actions.find((item) => !item.active);
+              setFindResult(found);
+              setSearched(true);
+            }}
+          >
+            Find first inactive
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() =>
+              actions.replace(
+                (item) => item.name.toLowerCase().includes("a"),
+                (item) => ({ ...item, active: true }),
+              )
+            }
+          >
+            Activate first with "a"
           </Button>
           <Button
-            onClick={() => update((item: string) => item === "First", "🐙")}
+            variant="outline"
+            onClick={() => actions.removeWhere((item) => !item.active)}
           >
-            Actualizar primer elemento por 🐙
+            Remove inactive
+          </Button>
+          <Button variant="outline" onClick={() => actions.set(INITIAL_ITEMS)}>
+            Reset to initial
           </Button>
-          <Button onClick={reset}>Resetear</Button>
-          <Button onClick={clear}>Limpiar</Button>
         </div>
 
-        <pre className="rounded-md bg-slate-950 p-4 text-white">
-          <code className="block">
-            List:{" "}
-            <span className="text-blue-300">
-              {JSON.stringify(list, null, 2)}
-            </span>
-          </code>
-        </pre>
+        {searched && (
+          <div className="rounded-md border bg-muted p-3 text-xs font-mono">
+            <span className="text-muted-foreground">find result: </span>
+            {findResult ? JSON.stringify(findResult) : "undefined"}
+          </div>
+        )}
+
+        <JsonPanel value={list} />
       </div>
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Predicate-based operations: `filter` retains matching items, `find` returns the first match without mutating state, `replace` transforms the first match (updater fn variant), and `removeWhere` removes all matching items.",
+      },
+    },
+  },
 };
 
-export const DynamicList: Story = {
-  render: () => {
-    const [list, updateList] = useArray<string>([]);
+// ─── Story 3 — Reordering ─────────────────────────────────────────────────────
 
-    const addItem = () => updateList.push(`Item ${list.length + 1}`);
+export const Reordering: Story = {
+  render: () => {
+    const [list, actions] = useArray(["Apple", "Banana", "Cherry", "Date"]);
+    const [fromIdx, setFromIdx] = useState(0);
+    const [toIdx, setToIdx] = useState(2);
+    const [swapA, setSwapA] = useState(0);
+    const [swapB, setSwapB] = useState(3);
 
     return (
-      <div className="space-y-2">
+      <div className="flex flex-col gap-4 max-w-sm">
         <div className="flex items-center gap-2">
-          <Button onClick={addItem}>Add Item</Button>
-          <Button onClick={updateList.clear}>
-            <Trash /> Clear
+          <label className="text-sm shrink-0">Move from</label>
+          <input
+            type="number"
+            min={0}
+            max={list.length - 1}
+            value={fromIdx}
+            onChange={(e) => setFromIdx(Number(e.target.value))}
+            className="w-16 rounded-md border px-2 py-1.5 text-sm"
+          />
+          <label className="text-sm shrink-0">to</label>
+          <input
+            type="number"
+            min={0}
+            max={list.length - 1}
+            value={toIdx}
+            onChange={(e) => setToIdx(Number(e.target.value))}
+            className="w-16 rounded-md border px-2 py-1.5 text-sm"
+          />
+          <Button
+            variant="outline"
+            onClick={() => actions.move(fromIdx, toIdx)}
+          >
+            Move
           </Button>
         </div>
-        <ul>
-          {list.map((item, index) => (
-            <li key={index}>
-              {item}{" "}
-              <Button
-                size="icon"
-                variant="ghost"
-                onClick={() => updateList.removeAt(index)}
-              >
-                <Trash />
-              </Button>
-            </li>
-          ))}
-        </ul>
+
+        <div className="flex items-center gap-2">
+          <label className="text-sm shrink-0">Swap</label>
+          <input
+            type="number"
+            min={0}
+            max={list.length - 1}
+            value={swapA}
+            onChange={(e) => setSwapA(Number(e.target.value))}
+            className="w-16 rounded-md border px-2 py-1.5 text-sm"
+          />
+          <label className="text-sm shrink-0">and</label>
+          <input
+            type="number"
+            min={0}
+            max={list.length - 1}
+            value={swapB}
+            onChange={(e) => setSwapB(Number(e.target.value))}
+            className="w-16 rounded-md border px-2 py-1.5 text-sm"
+          />
+          <Button variant="outline" onClick={() => actions.swap(swapA, swapB)}>
+            Swap
+          </Button>
+        </div>
+
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            variant="outline"
+            onClick={() => actions.sort((a, b) => a.localeCompare(b))}
+          >
+            Sort A→Z
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => actions.sort((a, b) => b.localeCompare(a))}
+          >
+            Sort Z→A
+          </Button>
+          <Button variant="outline" onClick={() => actions.reverse()}>
+            Reverse
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => actions.set(["Apple", "Banana", "Cherry", "Date"])}
+          >
+            Reset
+          </Button>
+        </div>
+
+        <JsonPanel value={list} />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Reorder actions: `move(from, to)` repositions an element, `swap(a, b)` exchanges two, `sort` with a compareFn sorts without mutating prior state, and `reverse` reverses into a new array. Same-index `move` or `swap` returns the previous ref unchanged.",
+      },
+    },
+  },
+};
+
+// ─── Story 4 — BulkOperations ─────────────────────────────────────────────────
+
+export const BulkOperations: Story = {
+  render: () => {
+    const [list, actions] = useArray<string>([]);
+    const [csvInput, setCsvInput] = useState("foo, bar, baz");
+
+    const handlePushMany = () => {
+      const items = csvInput
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      actions.pushMany(items);
+    };
+
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <div className="flex gap-2">
+          <input
+            className="flex-1 rounded-md border px-3 py-2 text-sm"
+            placeholder="comma-separated values"
+            value={csvInput}
+            onChange={(e) => setCsvInput(e.target.value)}
+          />
+          <Button variant="outline" onClick={handlePushMany}>
+            Push Many
+          </Button>
+        </div>
+
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            variant="outline"
+            onClick={() => actions.set(["🍎", "🍌", "🍒", "🍇"])}
+          >
+            Set fruits
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => actions.set(["red", "green", "blue"])}
+          >
+            Set colors
+          </Button>
+          <Button
+            variant="outline"
+            onClick={() => actions.set([1, 2, 3, 4, 5] as unknown as string[])}
+          >
+            Set numbers
+          </Button>
+          <Button variant="outline" onClick={() => actions.clear()}>
+            Clear
+          </Button>
+        </div>
+
+        <JsonPanel value={list} />
       </div>
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`pushMany` appends all items in one state update — more efficient than multiple `push` calls. `set` replaces the entire array at once. Calling `pushMany([])` is a no-op (no state change, no `onChange` fire).",
+      },
+    },
+  },
+};
+
+// ─── Story 5 — WithOnChange ────────────────────────────────────────────────────
+
+export const WithOnChange: Story = {
+  render: () => {
+    const [log, setLog] = useState<string[]>([]);
+
+    const addLog = (action: string, list: string[]) =>
+      setLog((prev) => [
+        `[${timestamp()}] ${action} → ${JSON.stringify(list)}`,
+        ...prev,
+      ]);
+
+    const [list, actions] = useArray<string>(["a", "b", "c"], {
+      onChange: (updated) => addLog("onChange", updated),
+    });
+
+    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 gap-2 flex-wrap">
+          <Button variant="outline" onClick={() => actions.push("x")}>
+            Push "x"
+          </Button>
+          <Button
+            variant="outline"
+            disabled={list.length === 0}
+            onClick={() => actions.pop()}
+          >
+            Pop
+          </Button>
+          <Button variant="outline" onClick={() => actions.clear()}>
+            Clear
+          </Button>
+          <Button variant="outline" onClick={() => actions.reset()}>
+            Reset
+          </Button>
+          <Button variant="outline" onClick={() => setLog([])}>
+            Clear log
+          </Button>
+        </div>
+
+        <JsonPanel value={list} />
+        <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 with the updated list. Passing a new inline `onChange` reference between renders does not cause double-fires because the callback is read through `useLatestRef`.",
+      },
+    },
+  },
 };