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

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

@@ -0,0 +1,330 @@
+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";
+
+/**
+ * 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 [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 className="flex w-80 flex-col gap-4">
+        <div
+          className={cn(
+            "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>
+    );
+  },
+};
+
+// ── 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>
+    );
+  },
+};

package/src/hooks/use-disclosure/use-disclosure.test.ts

@@ -0,0 +1,220 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useDisclosure } from "../use-disclosure";
+
+describe("useDisclosure", () => {
+  // ── Return shape ──────────────────────────────────────────────────────────
+  describe("return shape", () => {
+    it("returns a two-element tuple [boolean, actions]", () => {
+      const { result } = renderHook(() => useDisclosure());
+      expect(Array.isArray(result.current)).toBe(true);
+      expect(result.current).toHaveLength(2);
+      expect(typeof result.current[0]).toBe("boolean");
+      const actions = result.current[1];
+      expect(typeof actions.open).toBe("function");
+      expect(typeof actions.close).toBe("function");
+      expect(typeof actions.toggle).toBe("function");
+      expect(typeof actions.setOpen).toBe("function");
+    });
+  });
+
+  // ── Uncontrolled mode ─────────────────────────────────────────────────────
+  describe("uncontrolled mode", () => {
+    it("defaults to closed (opened === false) when no args passed", () => {
+      const { result } = renderHook(() => useDisclosure());
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("starts open when defaultOpen: true", () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("open() sets opened to true", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      await act(async () => {
+        result.current[1].open();
+      });
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("close() sets opened to false", async () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      await act(async () => {
+        result.current[1].close();
+      });
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("toggle() flips false → true", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      await act(async () => {
+        result.current[1].toggle();
+      });
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("toggle() flips true → false", async () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      await act(async () => {
+        result.current[1].toggle();
+      });
+      expect(result.current[0]).toBe(false);
+    });
+
+    it("setOpen(true) sets opened to true", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      await act(async () => {
+        result.current[1].setOpen(true);
+      });
+      expect(result.current[0]).toBe(true);
+    });
+
+    it("setOpen(false) sets opened to false", async () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      await act(async () => {
+        result.current[1].setOpen(false);
+      });
+      expect(result.current[0]).toBe(false);
+    });
+  });
+
+  // ── Idempotency ───────────────────────────────────────────────────────────
+  describe("idempotency", () => {
+    it("open() when already open does NOT call onOpenChange", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() =>
+        useDisclosure({ defaultOpen: true, onOpenChange }),
+      );
+      await act(async () => {});
+      onOpenChange.mockClear();
+
+      await act(async () => {
+        result.current[1].open();
+      });
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
+    it("close() when already closed does NOT call onOpenChange", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => useDisclosure({ onOpenChange }));
+      await act(async () => {});
+      onOpenChange.mockClear();
+
+      await act(async () => {
+        result.current[1].close();
+      });
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
+    it("setOpen(same value) does NOT call onOpenChange", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() =>
+        useDisclosure({ defaultOpen: true, onOpenChange }),
+      );
+      await act(async () => {});
+      onOpenChange.mockClear();
+
+      await act(async () => {
+        result.current[1].setOpen(true);
+      });
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── onOpenChange ──────────────────────────────────────────────────────────
+  describe("onOpenChange", () => {
+    it("fires once with true on real transition via open()", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => useDisclosure({ onOpenChange }));
+      await act(async () => {
+        result.current[1].open();
+      });
+      expect(onOpenChange).toHaveBeenCalledOnce();
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    it("fires once with false on real transition via close()", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() =>
+        useDisclosure({ defaultOpen: true, onOpenChange }),
+      );
+      await act(async () => {});
+      onOpenChange.mockClear();
+
+      await act(async () => {
+        result.current[1].close();
+      });
+      expect(onOpenChange).toHaveBeenCalledOnce();
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it("fires once with new value on real transition via setOpen()", async () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => useDisclosure({ onOpenChange }));
+      await act(async () => {
+        result.current[1].setOpen(true);
+      });
+      expect(onOpenChange).toHaveBeenCalledOnce();
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+  });
+
+  // ── Action reference stability ────────────────────────────────────────────
+  describe("action reference stability", () => {
+    it("open ref is stable after state change (uncontrolled)", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      const before = result.current[1].open;
+      await act(async () => {
+        result.current[1].open();
+      });
+      expect(result.current[1].open).toBe(before);
+    });
+
+    it("close ref is stable after state change (uncontrolled)", async () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      const before = result.current[1].close;
+      await act(async () => {
+        result.current[1].close();
+      });
+      expect(result.current[1].close).toBe(before);
+    });
+
+    it("toggle ref is stable after state change (uncontrolled)", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      const before = result.current[1].toggle;
+      await act(async () => {
+        result.current[1].toggle();
+      });
+      expect(result.current[1].toggle).toBe(before);
+    });
+
+    it("setOpen ref is stable after state change (uncontrolled)", async () => {
+      const { result } = renderHook(() => useDisclosure());
+      const before = result.current[1].setOpen;
+      await act(async () => {
+        result.current[1].setOpen(true);
+      });
+      expect(result.current[1].setOpen).toBe(before);
+    });
+  });
+
+  // ── Cleanup on unmount ────────────────────────────────────────────────────
+  describe("cleanup on unmount", () => {
+    it("does not call onOpenChange after unmount", async () => {
+      const onOpenChange = vi.fn();
+      const { result, unmount } = renderHook(() =>
+        useDisclosure({ onOpenChange }),
+      );
+      unmount();
+      await act(async () => {
+        try {
+          result.current[1].open();
+        } catch {
+          // suppress any unmount-related errors
+        }
+      });
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,56 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal";
+
+export type UseDisclosureProps = {
+  /** Initial open value (default: false). */
+  defaultOpen?: boolean;
+  /** Called once per real state transition. Not called on no-op calls. */
+  onOpenChange?: (open: boolean) => void;
+};
+
+export type UseDisclosureActions = {
+  /** Transitions state to true. No-op (and onOpenChange not called) if already open. */
+  open: () => void;
+  /** Transitions state to false. No-op (and onOpenChange not called) if already closed. */
+  close: () => void;
+  /** Flips the current boolean state. */
+  toggle: () => void;
+  /** Sets state to the given value. No-op (and onOpenChange not called) if value is unchanged. */
+  setOpen: (open: boolean) => void;
+};
+
+export function useDisclosure(
+  props?: UseDisclosureProps,
+): readonly [boolean, UseDisclosureActions] {
+  const [opened, setOpenState] = useState<boolean>(props?.defaultOpen ?? false);
+  const onOpenChangeRef = useLatestRef(props?.onOpenChange);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const actions = useMemo<UseDisclosureActions>(() => {
+    const transition = (compute: (prev: boolean) => boolean) =>
+      setOpenState((prev) => {
+        const next = compute(prev);
+        if (next === prev) return prev; // no-op: silent, no re-render
+        if (mountedRef.current) {
+          onOpenChangeRef.current?.(next);
+        }
+        return next;
+      });
+
+    return {
+      open: () => transition(() => true),
+      close: () => transition(() => false),
+      toggle: () => transition((prev) => !prev),
+      setOpen: (next) => transition(() => next),
+    };
+  }, []); // setOpenState, onOpenChangeRef, and mountedRef are stable
+
+  return [opened, actions] as const;
+}

package/src/hooks/use-document-title/index.ts

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