@boxcustodia/library 2.0.0-alpha.3 → 2.0.0-alpha.30

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

@@ -0,0 +1,97 @@
+import { useCallback, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+type ActionStatus = "idle" | "pending" | "success" | "error";
+
+export interface UseActionOptions<TVariables = void, TData = unknown> {
+  fn: (variables: TVariables) => Promise<TData>;
+  onExecute?: (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 UseActionReturn<TVariables = void, TData = unknown> {
+  execute: (variables: TVariables) => void;
+  executeAsync: (variables: TVariables) => Promise<TData>;
+  reset: () => void;
+  data: TData | null;
+  error: Error | null;
+  status: ActionStatus;
+  isIdle: boolean;
+  isPending: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+}
+
+export const useAction = <TVariables = void, TData = unknown>(
+  options: UseActionOptions<TVariables, TData>,
+): UseActionReturn<TVariables, TData> => {
+  const [status, setStatus] = useState<ActionStatus>("idle");
+  const [data, setData] = useState<TData | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fnRef = useLatestRef(options.fn);
+  const onExecuteRef = useLatestRef(options.onExecute);
+  const onSuccessRef = useLatestRef(options.onSuccess);
+  const onErrorRef = useLatestRef(options.onError);
+  const onSettledRef = useLatestRef(options.onSettled);
+
+  const executeAsync = useCallback(
+    async (variables: TVariables): Promise<TData> => {
+      onExecuteRef.current?.(variables);
+      setStatus("pending");
+      setData(null);
+      setError(null);
+
+      let result: TData | null = null;
+      let caught: Error | null = null;
+      try {
+        result = await fnRef.current(variables);
+        setData(result);
+        setStatus("success");
+        onSuccessRef.current?.(result, variables);
+        return result;
+      } catch (err) {
+        caught = err as Error;
+        setError(caught);
+        setStatus("error");
+        onErrorRef.current?.(caught, variables);
+        throw caught;
+      } finally {
+        onSettledRef.current?.(result, caught, variables);
+      }
+    },
+    [fnRef, onExecuteRef, onSuccessRef, onErrorRef, onSettledRef],
+  );
+
+  const execute = useCallback(
+    (variables: TVariables): void => {
+      executeAsync(variables).catch(() => {});
+    },
+    [executeAsync],
+  );
+
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setData(null);
+    setError(null);
+  }, []);
+
+  return {
+    execute,
+    executeAsync,
+    reset,
+    data,
+    error,
+    status,
+    isIdle: status === "idle",
+    isPending: status === "pending",
+    isSuccess: status === "success",
+    isError: status === "error",
+  };
+};

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

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

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

@@ -0,0 +1,471 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components";
+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;
+
+// ─── Story 1 — Default (Core CRUD) ────────────────────────────────────────────
+
+export const Default: Story = {
+  render: () => {
+    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="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
+            variant="outline"
+            onClick={() => actions.insertAt(0, "Prepended")}
+          >
+            Prepend
+          </Button>
+          <Button
+            variant="outline"
+            disabled={list.length === 0}
+            onClick={() => actions.pop()}
+          >
+            Pop
+          </Button>
+          <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
+            variant="outline"
+            onClick={() => actions.removeWhere((item) => !item.active)}
+          >
+            Remove inactive
+          </Button>
+          <Button variant="outline" onClick={() => actions.set(INITIAL_ITEMS)}>
+            Reset to initial
+          </Button>
+        </div>
+
+        {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.",
+      },
+    },
+  },
+};
+
+// ─── Story 3 — Reordering ─────────────────────────────────────────────────────
+
+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="flex flex-col gap-4 max-w-sm">
+        <div className="flex items-center gap-2">
+          <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>
+
+        <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`.",
+      },
+    },
+  },
+};