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

package/src/hooks/use-debounce-value/use-debounced-value.test.ts

@@ -11,12 +11,26 @@ describe("useDebouncedValue", () => {
     vi.useRealTimers();
   });
 
-  it("returns initial value immediately", () => {
+  // --- Return shape (v2: tuple) ---
+
+  it("returns a tuple [debounced, controls]", () => {
+    const { result } = renderHook(() => useDebouncedValue("init", 300));
+    const [debounced, controls] = result.current;
+    expect(debounced).toBe("init");
+    expect(typeof controls.cancel).toBe("function");
+    expect(typeof controls.flush).toBe("function");
+    expect(typeof controls.isPending).toBe("boolean");
+  });
+
+  it("debounced is initial value at mount", () => {
     const { result } = renderHook(() => useDebouncedValue("init", 300));
-    expect(result.current).toBe("init");
+    const [debounced] = result.current;
+    expect(debounced).toBe("init");
   });
 
-  it("does not update before delay elapses", () => {
+  // --- Debounce behavior (using tuple destructure) ---
+
+  it("debounced does not update before delay elapses", () => {
     const { result, rerender } = renderHook(
       ({ value }) => useDebouncedValue(value, 300),
       { initialProps: { value: "a" } },
@@ -27,10 +41,11 @@ describe("useDebouncedValue", () => {
       vi.advanceTimersByTime(299);
     });
 
-    expect(result.current).toBe("a");
+    const [debounced] = result.current;
+    expect(debounced).toBe("a");
   });
 
-  it("updates after delay elapses", () => {
+  it("debounced updates after delay elapses", () => {
     const { result, rerender } = renderHook(
       ({ value }) => useDebouncedValue(value, 300),
       { initialProps: { value: "a" } },
@@ -41,7 +56,8 @@ describe("useDebouncedValue", () => {
       vi.advanceTimersByTime(300);
     });
 
-    expect(result.current).toBe("b");
+    const [debounced] = result.current;
+    expect(debounced).toBe("b");
   });
 
   it("cancels pending update when value changes again before delay", () => {
@@ -60,13 +76,13 @@ describe("useDebouncedValue", () => {
       vi.advanceTimersByTime(200);
     });
 
-    expect(result.current).toBe("a");
+    expect(result.current[0]).toBe("a");
 
     act(() => {
       vi.advanceTimersByTime(100);
     });
 
-    expect(result.current).toBe("c");
+    expect(result.current[0]).toBe("c");
   });
 
   it("works with non-string values", () => {
@@ -80,10 +96,89 @@ describe("useDebouncedValue", () => {
       vi.advanceTimersByTime(100);
     });
 
-    expect(result.current).toBe(42);
+    expect(result.current[0]).toBe(42);
   });
 
-  it("clears timeout on unmount (no state update after unmount)", () => {
+  // --- isPending ---
+
+  it("isPending is true while pending, false after update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    expect(result.current[1].isPending).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  // --- cancel ---
+
+  it("cancel() stops pending value update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    act(() => {
+      result.current[1].cancel();
+    });
+
+    expect(result.current[1].isPending).toBe(false);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // value should still be "a" — update was cancelled
+    expect(result.current[0]).toBe("a");
+  });
+
+  // --- flush ---
+
+  it("flush() forces immediate value update", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+
+    act(() => {
+      result.current[1].flush();
+    });
+
+    expect(result.current[0]).toBe("b");
+    expect(result.current[1].isPending).toBe(false);
+  });
+
+  // --- Stable references ---
+
+  it("cancel and flush forwarded from inner hook — stable references", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    const { cancel: c1, flush: f1 } = result.current[1];
+    rerender({ value: "a" });
+    const { cancel: c2, flush: f2 } = result.current[1];
+
+    expect(c2).toBe(c1);
+    expect(f2).toBe(f1);
+  });
+
+  // --- Unmount cleanup ---
+
+  it("unmount cancels pending timer (no setState after unmount)", () => {
     const { rerender, unmount } = renderHook(
       ({ value }) => useDebouncedValue(value, 300),
       { initialProps: { value: "a" } },

package/src/hooks/use-debounce-value/use-debounced-value.ts

@@ -1,16 +1,25 @@
 import { useEffect, useState } from "react";
+import type { DebouncedControls } from "../use-debounce-callback/use-debounced-callback";
+import { useDebouncedCallback } from "../use-debounce-callback/use-debounced-callback";
 
-export function useDebouncedValue<T>(value: T, delay: number): T {
-  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+/**
+ * Returns the debounced version of `value` together with a controls object.
+ *
+ * Delegates entirely to `useDebouncedCallback` — there is no duplicated timer
+ * logic in this hook.
+ *
+ * @returns `[debouncedValue, { cancel, flush, isPending }]`
+ */
+export function useDebouncedValue<T>(
+  value: T,
+  delay: number,
+): readonly [T, DebouncedControls] {
+  const [debounced, setDebounced] = useState<T>(value);
+  const [schedule, controls] = useDebouncedCallback(setDebounced, delay);
 
   useEffect(() => {
-    const timeout = setTimeout(() => {
-      setDebouncedValue(value);
-    }, delay);
+    schedule(value);
+  }, [value, schedule]);
 
-    return () => clearTimeout(timeout);
-  }, [value, delay]);
-
-  return debouncedValue;
+  return [debounced, controls] as const;
 }
-

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

@@ -1,38 +1,329 @@
-import { Meta } from "@storybook/react-vite";
-import { Button } from "../../components";
-import { cn } from "../../lib";
+import type { Meta } from "@storybook/react-vite";
+import { useRef, useState } from "react";
+import { Button } from "../../components/button";
+import { cn } from "../../lib/cn";
 import { useDisclosure } from "../use-disclosure";
 
 /**
- * Hook que facilita el manejo de un estado booleano. Provee métodos para abrir, cerrar y toggle el estado
+ * Manages a boolean open/closed state for UI patterns like modals, drawers,
+ * dropdowns, and accordions.
+ *
+ * Returns a tuple `[opened, actions]` where `actions` is `{ open, close, toggle, setOpen }`.
+ * All actions are referentially stable after mount — safe to pass as props to memoized
+ * children or use as `useEffect` / `useCallback` dependencies.
+ *
+ * ```ts
+ * const [opened, { open, close, toggle, setOpen }] = useDisclosure()
+ * const [opened, { open, close }] = useDisclosure({ defaultOpen: true })
+ * const [opened, { toggle }] = useDisclosure({ onOpenChange: (next) => track(next) })
+ * ```
  */
 const meta: Meta = {
   title: "hooks/useDisclosure",
+  parameters: { layout: "centered" },
 };
 
 export default meta;
 
+// ── Default (Modal pattern) ───────────────────────────────────────────────────
+
+/**
+ * The most common use case: a trigger opens an overlay, and `close()` dismisses it.
+ * Actions (`open`, `close`, `toggle`, `setOpen`) are referentially stable —
+ * safe to pass as props without breaking child memoization.
+ */
 export const Default = {
+  name: "Default (Modal)",
+  render: () => {
+    const [opened, { open, close }] = useDisclosure();
+
+    return (
+      <div className="flex min-h-64 items-start justify-center pt-8">
+        <Button onClick={open}>Open modal</Button>
+
+        {opened && (
+          <div className="fixed inset-0 z-50 flex items-center justify-center">
+            <div
+              className="absolute inset-0 bg-black/40"
+              onClick={close}
+              aria-hidden="true"
+            />
+            <div className="relative z-10 w-full max-w-md rounded-xl bg-background p-6 shadow-2xl">
+              <h2 className="mb-1 text-lg font-semibold">Confirm action</h2>
+              <p className="mb-6 text-sm text-muted-foreground">
+                This is a modal controlled by <code>useDisclosure</code>. Click
+                outside or use the buttons below to dismiss.
+              </p>
+              <div className="flex justify-end gap-2">
+                <Button variant="outline" onClick={close}>
+                  Cancel
+                </Button>
+                <Button onClick={close}>Confirm</Button>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  },
+};
+
+// ── Drawer ────────────────────────────────────────────────────────────────────
+
+/**
+ * Same hook, different UI — a slide-in side panel.
+ * Demonstrates that `useDisclosure` is agnostic to what it controls.
+ */
+export const Drawer = {
+  render: () => {
+    const [opened, { open, close }] = useDisclosure();
+
+    return (
+      <div className="flex min-h-64 items-start justify-center pt-8">
+        <Button onClick={open}>Open drawer</Button>
+
+        {opened && (
+          <div className="fixed inset-0 z-50 flex justify-end">
+            <div
+              className="absolute inset-0 bg-black/40"
+              onClick={close}
+              aria-hidden="true"
+            />
+            <div className="relative z-10 flex h-full w-72 flex-col bg-background shadow-2xl">
+              <div className="flex items-center justify-between border-b px-4 py-3">
+                <span className="font-semibold">Settings</span>
+                <Button variant="ghost" size="sm" onClick={close}>
+                  ✕
+                </Button>
+              </div>
+              <div className="flex-1 px-4 py-4">
+                <p className="text-sm text-muted-foreground">
+                  Drawer content goes here. The hook doesn't care whether it's
+                  controlling a modal, drawer, tooltip, or any other element.
+                </p>
+              </div>
+              <div className="border-t px-4 py-3">
+                <Button className="w-full" onClick={close}>
+                  Close
+                </Button>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  },
+};
+
+// ── Accordion (multiple independent) ─────────────────────────────────────────
+
+/**
+ * Three independent `useDisclosure()` instances — each item manages its own state.
+ * Opening one does not affect the others.
+ */
+export const Accordion = {
+  render: () => {
+    const [aOpened, { toggle: aToggle }] = useDisclosure();
+    const [bOpened, { toggle: bToggle }] = useDisclosure();
+    const [cOpened, { toggle: cToggle }] = useDisclosure();
+
+    const items = [
+      {
+        id: "a",
+        label: "What does this hook return?",
+        opened: aOpened,
+        toggle: aToggle,
+        body: "A tuple [opened, { open, close, toggle, setOpen }]. The boolean is reactive; all actions are stable.",
+      },
+      {
+        id: "b",
+        label: "Does onOpenChange fire on no-ops?",
+        opened: bOpened,
+        toggle: bToggle,
+        body: "No. Calling open() when already open, or close() when already closed, is a silent no-op — no re-render, no callback.",
+      },
+      {
+        id: "c",
+        label: "Are the actions referentially stable?",
+        opened: cOpened,
+        toggle: cToggle,
+        body: "Yes. All four actions maintain identity for the component's lifetime, making them safe as useEffect dependencies.",
+      },
+    ];
+
+    return (
+      <div className="w-full max-w-lg divide-y rounded-xl border">
+        {items.map(({ id, label, opened, toggle, body }) => (
+          <div key={id}>
+            <button
+              type="button"
+              className="flex w-full items-center justify-between px-4 py-3 text-sm font-medium transition-colors hover:bg-muted/50"
+              onClick={toggle}
+            >
+              {label}
+              <span
+                className={cn(
+                  "text-muted-foreground transition-transform duration-200",
+                  opened && "rotate-180",
+                )}
+              >
+                ▾
+              </span>
+            </button>
+            {opened && (
+              <p className="border-t bg-muted/20 px-4 py-3 text-sm text-muted-foreground">
+                {body}
+              </p>
+            )}
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+// ── onOpenChange ──────────────────────────────────────────────────────────────
+
+/**
+ * `onOpenChange` fires exactly once per real transition — silent on no-ops.
+ * Clicking "Open" twice logs only one entry. Clicking "Close" when already
+ * closed produces no log. The counter proves this visually.
+ */
+export const OnOpenChange = {
+  name: "With onOpenChange",
   render: () => {
-    const [isOpen, { open, close, toggle }] = useDisclosure();
+    const [log, setLog] = useState<Array<{ value: boolean; time: string }>>([]);
+
+    const [opened, { open, close, toggle }] = useDisclosure({
+      onOpenChange: (next) => {
+        setLog((prev) => [
+          { value: next, time: new Date().toLocaleTimeString() },
+          ...prev.slice(0, 5),
+        ]);
+      },
+    });
 
     return (
-      <div>
+      <div className="flex w-80 flex-col gap-4">
         <div
-          onClick={toggle}
           className={cn(
-            "rounded transition-colors w-32 h-32 shadow text-3xl grid place-items-center cursor-pointer",
-            { "bg-accent": isOpen },
+            "flex h-14 items-center justify-center rounded-lg border-2 border-dashed text-sm font-medium transition-all",
+            opened
+              ? "border-primary bg-primary/5 text-primary"
+              : "border-border text-muted-foreground",
           )}
         >
-          🍅
+          {opened ? "Opened" : "Closed"}
+        </div>
+
+        <div className="flex gap-2">
+          <Button size="sm" onClick={open} className="flex-1">
+            Open
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={close}
+            className="flex-1"
+          >
+            Close
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={toggle}
+            className="flex-1"
+          >
+            Toggle
+          </Button>
+        </div>
+
+        <div className="min-h-24 rounded-lg border bg-muted/30 p-3">
+          <p className="mb-2 text-xs font-medium text-muted-foreground">
+            Transition log (no-ops are silent):
+          </p>
+          {log.length === 0 ? (
+            <p className="text-xs italic text-muted-foreground">
+              No transitions yet.
+            </p>
+          ) : (
+            <ul className="space-y-1">
+              {log.map((entry, i) => (
+                <li key={`${entry.time}-${i}`} className="font-mono text-xs">
+                  <span
+                    className={cn(
+                      "font-semibold",
+                      entry.value ? "text-emerald-600" : "text-rose-500",
+                    )}
+                  >
+                    → {entry.value ? "true" : "false"}
+                  </span>
+                  <span className="ml-2 text-muted-foreground">
+                    {entry.time}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
         </div>
+      </div>
+    );
+  },
+};
 
-        <div className="flex gap-2 mt-2">
-          <Button onClick={open}>Abrir</Button>
-          <Button onClick={close}>Cerrar</Button>
-          <Button onClick={toggle}>Toggle</Button>
+// ── StableActions ─────────────────────────────────────────────────────────────
+
+/**
+ * Action references never change after mount, even across many re-renders.
+ * Safe to use as `useEffect` dependencies or as stable props to memoized children.
+ */
+export const StableActions = {
+  render: () => {
+    const [, { open }] = useDisclosure();
+    const [renderCount, setRenderCount] = useState(0);
+    const initialOpenRef = useRef<(() => void) | null>(null);
+
+    if (initialOpenRef.current === null) {
+      initialOpenRef.current = open;
+    }
+
+    const isStable = open === initialOpenRef.current;
+
+    return (
+      <div className="flex w-72 flex-col gap-4">
+        <div className="rounded-xl border bg-muted/20 p-4">
+          <p className="mb-3 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Action identity
+          </p>
+          <div className="flex items-center justify-between rounded-lg border bg-background px-3 py-2">
+            <code className="text-sm">open</code>
+            <span
+              className={cn(
+                "text-sm font-semibold",
+                isStable ? "text-emerald-600" : "text-rose-500",
+              )}
+            >
+              {isStable ? "stable ✓" : "changed ✗"}
+            </span>
+          </div>
         </div>
+
+        <div className="rounded-xl border bg-muted/20 p-4">
+          <p className="mb-3 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Render count
+          </p>
+          <p className="text-2xl font-bold tabular-nums">{renderCount + 1}</p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            renders (this component)
+          </p>
+        </div>
+
+        <Button variant="outline" onClick={() => setRenderCount((c) => c + 1)}>
+          Force re-render
+        </Button>
+        <p className="text-center text-xs text-muted-foreground">
+          Trigger re-renders — <code>open</code> identity stays stable.
+        </p>
       </div>
     );
   },