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

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

@@ -3,70 +3,218 @@ import { describe, expect, it, vi } from "vitest";
 import { useDisclosure } from "../use-disclosure";
 
 describe("useDisclosure", () => {
-  it("starts closed by default", () => {
-    const { result } = renderHook(() => useDisclosure());
-    expect(result.current[0]).toBe(false);
+  // ── 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");
+    });
   });
 
-  it("starts open when initialState=true", () => {
-    const { result } = renderHook(() => useDisclosure(true));
-    expect(result.current[0]).toBe(true);
-  });
+  // ── 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("open() opens disclosure", () => {
-    const { result } = renderHook(() => useDisclosure());
-    act(() => result.current[1].open());
-    expect(result.current[0]).toBe(true);
-  });
+    it("starts open when defaultOpen: true", () => {
+      const { result } = renderHook(() => useDisclosure({ defaultOpen: true }));
+      expect(result.current[0]).toBe(true);
+    });
 
-  it("open() is idempotent when already open", () => {
-    const { result } = renderHook(() => useDisclosure(true));
-    act(() => result.current[1].open());
-    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() closes disclosure", () => {
-    const { result } = renderHook(() => useDisclosure(true));
-    act(() => result.current[1].close());
-    expect(result.current[0]).toBe(false);
-  });
+    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("close() is a no-op when already closed", () => {
-    const { result } = renderHook(() => useDisclosure(false));
-    act(() => 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() opens when closed", () => {
-    const { result } = renderHook(() => useDisclosure());
-    act(() => 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);
+    });
   });
 
-  it("toggle() closes when open", () => {
-    const { result } = renderHook(() => useDisclosure(true));
-    act(() => result.current[1].toggle());
-    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();
+    });
   });
 
-  it("calls onOpen callback when opening", () => {
-    const onOpen = vi.fn();
-    const { result } = renderHook(() => useDisclosure(false, { onOpen }));
-    act(() => result.current[1].open());
-    expect(onOpen).toHaveBeenCalledOnce();
+  // ── 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);
+    });
   });
 
-  it("calls onClose callback when closing", () => {
-    const onClose = vi.fn();
-    const { result } = renderHook(() => useDisclosure(true, { onClose }));
-    act(() => result.current[1].close());
-    expect(onClose).toHaveBeenCalledOnce();
+  // ── 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);
+    });
   });
 
-  it("does not call onOpen when already open", () => {
-    const onOpen = vi.fn();
-    const { result } = renderHook(() => useDisclosure(true, { onOpen }));
-    act(() => result.current[1].open());
-    expect(onOpen).not.toHaveBeenCalled();
+  // ── 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

@@ -1,36 +1,56 @@
-import { useCallback, useState } from "react";
+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(
-  initialState = false,
-  callbacks?: { onOpen?: () => void; onClose?: () => void },
-) {
-  const { onOpen, onClose } = callbacks || {};
-  const [isOpen, setIsOpen] = useState(initialState);
+  props?: UseDisclosureProps,
+): readonly [boolean, UseDisclosureActions] {
+  const [opened, setOpenState] = useState<boolean>(props?.defaultOpen ?? false);
+  const onOpenChangeRef = useLatestRef(props?.onOpenChange);
+  const mountedRef = useRef(true);
 
-  const open = useCallback(() => {
-    setIsOpen((isOpened) => {
-      if (!isOpened) {
-        onOpen?.();
-        return true;
-      }
-      return isOpened;
-    });
-  }, [onOpen]);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
 
-  const close = useCallback(() => {
-    setIsOpen((isOpened) => {
-      if (isOpened) {
-        onClose?.();
-        return false;
-      }
-      return isOpened;
-    });
-  }, [onClose]);
+  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;
+      });
 
-  const toggle = useCallback(() => {
-    isOpen ? close() : open();
-  }, [close, open, isOpen]);
+    return {
+      open: () => transition(() => true),
+      close: () => transition(() => false),
+      toggle: () => transition((prev) => !prev),
+      setOpen: (next) => transition(() => next),
+    };
+  }, []); // setOpenState, onOpenChangeRef, and mountedRef are stable
 
-  return [isOpen, { open, close, toggle }] as const;
+  return [opened, actions] as const;
 }
-

package/src/hooks/use-document-title/use-document-title.stories.tsx

@@ -70,3 +70,57 @@ export const Default: Story = {
     );
   },
 };
+
+/**
+ * Pass a `template` with a `%s` placeholder to wrap every title in a
+ * suffix or prefix — e.g. append the app name to the page name.
+ *
+ * ```tsx
+ * useDocumentTitle(pageName, { template: "%s | Acme" });
+ * ```
+ */
+export const Template: Story = {
+  render: () => {
+    const [page, setPage] = useState("Inbox");
+    useDocumentTitle(page, { template: "%s | Acme" });
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <Input value={page} onValueChange={setPage} placeholder="Page name…" />
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {`document.title = "${page.trim() || "…"} | Acme"`}
+        </code>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Set `enabled: false` to make the hook a no-op. The title is only
+ * written while `enabled` is `true`, so a component can own the tab
+ * title conditionally without unmounting.
+ */
+export const Enabled: Story = {
+  render: () => {
+    const [enabled, setEnabled] = useState(true);
+    useDocumentTitle("Live title", { enabled });
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <label className="flex items-center gap-2 text-sm">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setEnabled(e.target.checked)}
+          />
+          enabled
+        </label>
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {enabled
+            ? 'document.title = "Live title"'
+            : "(disabled — current title preserved)"}
+        </code>
+      </Stack>
+    );
+  },
+};

package/src/hooks/use-document-title/use-document-title.test.tsx

@@ -59,6 +59,32 @@ describe("useDocumentTitle", () => {
     expect(document.title).toBe("Original");
   });
 
+  it("applies a template with the %s placeholder", () => {
+    renderHook(() => useDocumentTitle("Inbox", { template: "%s | Acme" }));
+    expect(document.title).toBe("Inbox | Acme");
+  });
+
+  it("trims before applying the template", () => {
+    renderHook(() => useDocumentTitle("  Inbox  ", { template: "%s | Acme" }));
+    expect(document.title).toBe("Inbox | Acme");
+  });
+
+  it("does not touch the title when enabled is false", () => {
+    renderHook(() => useDocumentTitle("New", { enabled: false }));
+    expect(document.title).toBe("Original");
+  });
+
+  it("starts writing once enabled flips to true", () => {
+    const { rerender } = renderHook(
+      ({ enabled }) => useDocumentTitle("New", { enabled }),
+      { initialProps: { enabled: false } },
+    );
+    expect(document.title).toBe("Original");
+
+    rerender({ enabled: true });
+    expect(document.title).toBe("New");
+  });
+
   it("captures the original title at mount, not the latest one", () => {
     document.title = "First";
     const { unmount, rerender } = renderHook(

package/src/hooks/use-document-title/{use-document-title.tsx → use-document-title.ts}

@@ -1,20 +1,33 @@
 import { useEffect, useRef } from "react";
+import { isBrowser } from "../internal";
 
 export interface UseDocumentTitleInput {
   /** Restore the previous `document.title` when the component unmounts. Defaults to `false`. */
   restoreOnUnmount?: boolean;
+  /**
+   * Template applied to the title. The `%s` placeholder is replaced with
+   * the (trimmed) title value. Example: `"%s | Acme"` turns `"Inbox"`
+   * into `"Inbox | Acme"`. When omitted, the title is written as-is.
+   */
+  template?: string;
+  /**
+   * When `false`, the hook does not touch `document.title`. Defaults to
+   * `true`. Useful to conditionally own the title.
+   */
+  enabled?: boolean;
 }
 
 export function useDocumentTitle(
   title: string,
   options: UseDocumentTitleInput = {},
 ): void {
-  const { restoreOnUnmount = false } = options;
+  const { restoreOnUnmount = false, template, enabled = true } = options;
   const restoreRef = useRef(restoreOnUnmount);
   restoreRef.current = restoreOnUnmount;
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount only
   useEffect(() => {
+    if (!isBrowser) return;
     const previous = document.title;
     return () => {
       if (restoreRef.current) {
@@ -24,9 +37,10 @@ export function useDocumentTitle(
   }, []);
 
   useEffect(() => {
+    if (!isBrowser || !enabled) return;
     if (typeof title !== "string") return;
     const trimmed = title.trim();
     if (trimmed.length === 0) return;
-    document.title = trimmed;
-  }, [title]);
+    document.title = template ? template.replace("%s", trimmed) : trimmed;
+  }, [title, template, enabled]);
 }

package/src/hooks/use-event-listener/use-event-listener.stories.tsx

@@ -1,28 +1,124 @@
-import { Meta } from "@storybook/react-vite";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useRef, useState } from "react";
 import { action } from "storybook/actions";
 import { Button } from "../../components";
 import { useEventListener } from "../use-event-listener";
 
 /**
- * Hook que facilita el manejor de eventos
+ * Subscribe to a DOM event with automatic add/remove, without writing a
+ * manual `useEffect` + cleanup.
  *
- * Evita tener que hacer el `useEffect` con el cleanup
+ * The `listener` is held in an internal ref (handler-stable pattern): passing
+ * an inline function does **not** re-attach the underlying listener on every
+ * render, and the listener always sees fresh props/state when it fires.
+ *
+ * The target is **explicit** and chosen by overload — there is no returned
+ * ref to wire up:
+ *
+ * ```tsx
+ * // window — omit the target
+ * useEventListener("resize", onResize);
+ *
+ * // an element — create your own ref and pass it
+ * const ref = useRef<HTMLButtonElement>(null);
+ * useEventListener("click", onClick, ref);
+ *
+ * // document — pass it directly (global key handlers, etc.)
+ * useEventListener("keydown", onKeyDown, document);
+ *
+ * // a MediaQueryList — react to media query changes
+ * const mql = window.matchMedia("(min-width: 768px)");
+ * useEventListener("change", onChange, mql);
+ * ```
+ *
+ * The fourth argument forwards the native `addEventListener` options
+ * (`{ capture, once, passive, signal }` or a boolean). The listener is
+ * re-attached when the `capture` / `once` / `passive` flags change.
+ *
+ * SSR-safe: the effect no-ops when there is no DOM.
+ *
+ * Migrating from v1: the hook no longer returns a ref. Replace
+ * `const ref = useEventListener("click", cb)` with an explicit ref —
+ * `const ref = useRef(null); useEventListener("click", cb, ref)`.
  */
 const meta: Meta = {
   title: "hooks/useEventListener",
 };
 
 export default meta;
+type Story = StoryObj<typeof meta>;
 
 /**
- * ```tsx
- * const ref = useEventListener<HTMLELEMENT>("EVENT_KEY", callback);
- * return <HTMLELEMENT ref={ref} />;
- * ```
+ * Listen on an element by creating a ref yourself and passing it as the
+ * third argument. The hook attaches the listener once the element is mounted.
  */
-export const Default = {
+export const ElementByRef: Story = {
   render: () => {
-    const ref = useEventListener("click", action("click"));
+    const ref = useRef<HTMLButtonElement>(null);
+    useEventListener("click", action("click"), ref);
     return <Button ref={ref}>click me</Button>;
   },
 };
+
+/**
+ * Omitting the target listens on `window`. Resize the preview pane to watch
+ * the value update — no manual subscription or cleanup required.
+ */
+export const WindowResize: Story = {
+  render: () => {
+    const [width, setWidth] = useState(window.innerWidth);
+    useEventListener("resize", () => setWidth(window.innerWidth));
+    return (
+      <p>
+        window width: <strong>{width}px</strong>
+      </p>
+    );
+  },
+};
+
+/**
+ * Pass `document` directly for document-level events such as global keyboard
+ * shortcuts that should fire regardless of focus. The listener receives the
+ * native `KeyboardEvent`.
+ */
+export const DocumentKeydown: Story = {
+  render: () => {
+    const [key, setKey] = useState("—");
+    useEventListener("keydown", (event) => setKey(event.key), document);
+    return (
+      <p>
+        last key pressed: <kbd>{key}</kbd>
+      </p>
+    );
+  },
+};
+
+/**
+ * Pass a `MediaQueryList` (from `window.matchMedia`) to react to viewport
+ * changes. Create the `MediaQueryList` once so its identity stays stable and
+ * the listener is not re-attached on every render.
+ */
+export const MediaQueryChange: Story = {
+  render: () => {
+    const [mql] = useState(() => window.matchMedia("(min-width: 768px)"));
+    const [matches, setMatches] = useState(mql.matches);
+    useEventListener("change", (event) => setMatches(event.matches), mql);
+    return <p>{matches ? "≥ 768px (desktop)" : "< 768px (mobile)"}</p>;
+  },
+};
+
+/**
+ * The fourth argument is forwarded to `addEventListener`. Here `{ once: true }`
+ * makes the listener fire a single time and then detach itself — the counter
+ * never goes past one regardless of how many times you click.
+ */
+export const OnceOption: Story = {
+  render: () => {
+    const ref = useRef<HTMLButtonElement>(null);
+    const [count, setCount] = useState(0);
+    useEventListener("click", () => setCount((c) => c + 1), ref, {
+      once: true,
+    });
+    return <Button ref={ref}>clicked {count} time(s)</Button>;
+  },
+};