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

package/src/hooks/use-click-outside/use-click-outside.stories.tsx

@@ -1,39 +1,209 @@
-import { Meta } from "@storybook/react-vite";
-import { useState } from "react";
-import { Button } from "../../components";
-import { useClickOutside } from "../use-click-outside";
+import type { Meta } from "@storybook/react-vite";
+import { useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "../../components/button";
+import { useClickOutside } from "./use-click-outside";
 
+/**
+ * Fires a callback when a `pointerdown` (or any configured event) happens
+ * outside the returned ref. Listener lives on `document`, so the wrapped
+ * element does not need to receive focus or capture events itself.
+ *
+ * ```tsx
+ * const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
+ * ```
+ *
+ * Good to know:
+ * - **Default event is `pointerdown`** (handles mouse + touch + pen in one
+ *   listener). Override via `events` if you need legacy `mousedown` or want
+ *   to combine `mousedown` + `touchstart`.
+ * - **Callback identity does not matter.** The hook reads the callback
+ *   through an internal ref, so an inline arrow function will not re-attach
+ *   the listener every render.
+ * - **`enabled` controls subscription.** When `false` no listener is
+ *   attached at all — cheaper than checking inside the callback, and the
+ *   typical way to "pause" the hook while a popover is closed.
+ * - **Portals:** elements rendered into another part of the tree (modals,
+ *   popovers, tooltips) are NOT inside the ref's subtree. Use
+ *   `additionalRefs` to whitelist them, or `ignore(event)` for finer
+ *   control (e.g. ignore clicks on a specific class).
+ * - **SSR-safe:** the effect early-returns on the server.
+ *
+ * Breaking change from v1: the second argument is now an options object
+ * (`enabled`, `events`, `ignore`, `additionalRefs`) instead of the boolean
+ * `watch`. Default event changed from `mousedown` to `pointerdown`.
+ */
 const meta: Meta = {
   title: "hooks/useClickOutside",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
 };
 
 export default meta;
 
+/**
+ * Open the popover with the button, then click anywhere outside the
+ * yellow card to close it. Clicking inside the card (including the
+ * "Close from inside" button) does not trigger the callback.
+ */
 export const Default = {
   render: () => {
-    const [isOpen, setIsOpen] = useState(true);
+    const [open, setOpen] = useState(true);
+    const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
 
-    const handleClose = () => {
-      setIsOpen(false);
-    };
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <Button onClick={() => setOpen(true)} disabled={open}>
+          Open
+        </Button>
+        {open ? (
+          <div
+            ref={ref}
+            className="rounded-md border border-warning bg-warning/10 p-4 text-sm shadow-md"
+          >
+            <p className="mb-2">Click outside this card to dismiss it.</p>
+            <Button size="sm" onClick={() => setOpen(false)}>
+              Close from inside
+            </Button>
+          </div>
+        ) : (
+          <p className="text-sm text-muted-foreground">
+            Popover closed. Re-open with the button.
+          </p>
+        )}
+      </div>
+    );
+  },
+};
 
-    const ref = useClickOutside<HTMLDivElement>(handleClose);
+/**
+ * `enabled: false` removes the listener entirely. Useful when the consumer
+ * already has a separate "is open" flag — the hook does not need to be
+ * conditionally rendered, just toggled.
+ *
+ * ```tsx
+ * useClickOutside(close, { enabled: isOpen });
+ * ```
+ */
+export const Enabled = {
+  render: () => {
+    const [enabled, setEnabled] = useState(true);
+    const [hits, setHits] = useState(0);
+    const ref = useClickOutside<HTMLDivElement>(() => setHits((n) => n + 1), {
+      enabled,
+    });
 
     return (
-      <div className="flex gap-2">
-        <Button onClick={() => setIsOpen(true)} disabled={isOpen}>
-          Abrir
-        </Button>
-        <Button onClick={() => setIsOpen(false)} disabled={!isOpen}>
-          Cerrar
+      <div className="flex flex-col items-start gap-3">
+        <label className="flex items-center gap-2 text-sm">
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setEnabled(e.target.checked)}
+          />
+          listener enabled
+        </label>
+        <div
+          ref={ref}
+          className="rounded-md border border-input bg-card p-4 text-sm"
+        >
+          Click outside this box.
+        </div>
+        <code className="text-xs">outside clicks counted: {hits}</code>
+      </div>
+    );
+  },
+};
+
+/**
+ * Use `additionalRefs` when the popover has a separate trigger element
+ * that should NOT count as "outside". Without this, clicking the trigger
+ * to toggle the popover would immediately close it again because the
+ * button lives outside the popover's DOM subtree.
+ *
+ * ```tsx
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ * const popoverRef = useClickOutside<HTMLDivElement>(close, {
+ *   additionalRefs: [triggerRef],
+ * });
+ * ```
+ */
+export const AdditionalRefs = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    const popoverRef = useClickOutside<HTMLDivElement>(() => setOpen(false), {
+      additionalRefs: [triggerRef],
+    });
+
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <Button ref={triggerRef} onClick={() => setOpen((v) => !v)}>
+          Toggle
         </Button>
+        {open ? (
+          <div
+            ref={popoverRef}
+            className="rounded-md border border-input bg-card p-4 text-sm shadow-md"
+          >
+            Toggling the trigger does NOT close me, but clicking elsewhere does.
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+};
+
+/**
+ * `ignore(event)` is the escape hatch for content rendered into a React
+ * portal — by definition that DOM is not under the ref's subtree, so a
+ * raw click on a tooltip / overlay / dropdown would close the parent.
+ * Returning `true` from `ignore` skips the callback for that event.
+ *
+ * Here, the green portal is anchored to `document.body` but tagged with
+ * `data-inside-portal`. The `ignore` predicate checks that attribute and
+ * treats clicks on the portal as "inside".
+ *
+ * ```tsx
+ * useClickOutside(close, {
+ *   ignore: (event) =>
+ *     (event.target as HTMLElement | null)?.closest("[data-tooltip]") != null,
+ * });
+ * ```
+ */
+export const IgnorePortals = {
+  render: () => {
+    const [closed, setClosed] = useState(false);
+    const ref = useClickOutside<HTMLDivElement>(() => setClosed(true), {
+      ignore: (event) =>
+        (event.target as HTMLElement | null)?.closest("[data-inside-portal]") !=
+        null,
+    });
+
+    return (
+      <div className="flex flex-col items-start gap-3">
         <div
           ref={ref}
-          className={`relative p-4 bg-white shadow-md  ${isOpen ? "" : "hidden"}`}
+          className="rounded-md border border-input bg-card p-4 text-sm"
         >
-          <p>Haz clic fuera de este cuadro para cerrarlo.</p>
-          <Button onClick={() => setIsOpen(false)}>Cerrar desde dentro</Button>
+          {closed
+            ? "Closed — click Reset."
+            : "Click the green portal: NOT counted as outside. Click anywhere else: counted."}
         </div>
+        {closed ? (
+          <Button size="sm" onClick={() => setClosed(false)}>
+            Reset
+          </Button>
+        ) : null}
+        {createPortal(
+          <div
+            data-inside-portal
+            className="fixed right-4 bottom-4 rounded-md border border-success bg-success/15 p-3 text-xs shadow-md"
+          >
+            Portal content (anchored to body, but ignored).
+          </div>,
+          document.body,
+        )}
       </div>
     );
   },

package/src/hooks/use-click-outside/use-click-outside.test.tsx

@@ -1,39 +1,118 @@
 import { act, render, screen } from "@testing-library/react";
+import { useRef } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { useClickOutside } from "../use-click-outside";
 
-function Component({ onOutside, watch }: { onOutside: () => void; watch?: boolean }) {
-  const ref = useClickOutside<HTMLDivElement>(onOutside, watch);
+type ComponentProps = {
+  onOutside: (event: Event) => void;
+  enabled?: boolean;
+  events?: Array<"mousedown" | "pointerdown" | "touchstart">;
+  ignore?: (event: Event) => boolean;
+  withExtra?: boolean;
+};
+
+function Component({
+  onOutside,
+  enabled,
+  events,
+  ignore,
+  withExtra,
+}: ComponentProps) {
+  const extraRef = useRef<HTMLDivElement>(null);
+  const ref = useClickOutside<HTMLDivElement>(onOutside, {
+    enabled,
+    events,
+    ignore,
+    additionalRefs: withExtra ? [extraRef] : undefined,
+  });
   return (
     <div data-testid="wrapper">
       <div ref={ref} data-testid="target" />
+      {withExtra ? <div ref={extraRef} data-testid="extra" /> : null}
     </div>
   );
 }
 
-function fireMousedown(el: Element) {
-  el.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+function fireEvent(
+  el: Element,
+  type: "mousedown" | "pointerdown" | "touchstart",
+) {
+  el.dispatchEvent(new Event(type, { bubbles: true }));
 }
 
 describe("useClickOutside", () => {
-  it("calls callback when clicking outside the ref element", () => {
+  it("calls callback on pointerdown outside the ref element (default event)", () => {
     const fn = vi.fn();
     render(<Component onOutside={fn} />);
-    act(() => fireMousedown(screen.getByTestId("wrapper")));
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
     expect(fn).toHaveBeenCalledOnce();
   });
 
+  it("passes the event to the callback", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn.mock.calls[0][0]).toBeInstanceOf(Event);
+  });
+
   it("does not call callback when clicking inside the ref element", () => {
     const fn = vi.fn();
     render(<Component onOutside={fn} />);
-    act(() => fireMousedown(screen.getByTestId("target")));
+    act(() => fireEvent(screen.getByTestId("target"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("does not attach listener when enabled=false", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} enabled={false} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
     expect(fn).not.toHaveBeenCalled();
   });
 
-  it("does not attach listener when watch=false", () => {
+  it("attaches listeners for each event in the events option", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} events={["mousedown", "touchstart"]} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "mousedown"));
+    act(() => fireEvent(screen.getByTestId("wrapper"), "touchstart"));
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not call callback for events not in the events option", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} events={["mousedown"]} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("skips the callback when ignore returns true", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} ignore={() => true} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("treats additional refs as inside", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} withExtra />);
+    act(() => fireEvent(screen.getByTestId("extra"), "pointerdown"));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("uses the latest callback without re-attaching listeners", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<Component onOutside={first} />);
+    rerender(<Component onOutside={second} />);
+    act(() => fireEvent(screen.getByTestId("wrapper"), "pointerdown"));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it("removes listeners on unmount", () => {
     const fn = vi.fn();
-    render(<Component onOutside={fn} watch={false} />);
-    act(() => fireMousedown(screen.getByTestId("wrapper")));
+    const { unmount } = render(<Component onOutside={fn} />);
+    unmount();
+    act(() => fireEvent(document.body, "pointerdown"));
     expect(fn).not.toHaveBeenCalled();
   });
 });

package/src/hooks/use-click-outside/use-click-outside.ts

@@ -1,25 +1,71 @@
-import { useEffect, useRef } from "react";
+import { type RefObject, useEffect, useRef } from "react";
+import { isBrowser, useLatestRef } from "../internal";
+
+type UseClickOutsideOptions = {
+  /** Disable the listener without unmounting the hook. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Which DOM events trigger the outside check. Any DOM event names work;
+   * pass `null` to fall back to the default. Defaults to `["pointerdown"]`.
+   */
+  events?: string[] | null;
+  /**
+   * Return `true` to skip the callback for a given event. Useful for portals
+   * or popovers whose DOM lives outside the wrapped ref but should still count
+   * as "inside".
+   */
+  ignore?: (event: Event) => boolean;
+  /**
+   * Extra refs that also count as "inside". An event whose target lives in
+   * any of these elements will not fire the callback.
+   */
+  additionalRefs?: RefObject<HTMLElement | null>[];
+};
+
+const DEFAULT_EVENTS = ["pointerdown"];
 
 export const useClickOutside = <T extends HTMLElement = HTMLElement>(
-  callback: () => void,
-  watch: boolean = true,
-) => {
-  const ref = useRef<T>(null);
-
-  const handleClickOutside = (event: MouseEvent) => {
-    if (ref.current && !ref.current.contains(event.target as Node)) {
-      callback();
-    }
-  };
+  callback: (event: Event) => void,
+  options: UseClickOutsideOptions = {},
+): RefObject<T | null> => {
+  const { enabled = true, events, ignore, additionalRefs } = options;
+  const resolvedEvents = events ?? DEFAULT_EVENTS;
+
+  const ref = useRef<T | null>(null);
+  const callbackRef = useLatestRef(callback);
+  const ignoreRef = useLatestRef(ignore);
+  const additionalRefsRef = useLatestRef(additionalRefs);
 
   useEffect(() => {
-    if (!watch) return;
-    document.addEventListener("mousedown", handleClickOutside);
+    if (!enabled || !isBrowser) return;
+
+    const handler = (event: Event) => {
+      if (ignoreRef.current?.(event)) return;
+
+      const target = event.target as Node | null;
+      if (!target) return;
+
+      if (ref.current?.contains(target)) return;
+
+      const extras = additionalRefsRef.current;
+      if (extras) {
+        for (const extra of extras) {
+          if (extra.current?.contains(target)) return;
+        }
+      }
+
+      callbackRef.current(event);
+    };
+
+    for (const event of resolvedEvents) {
+      document.addEventListener(event, handler);
+    }
     return () => {
-      document.removeEventListener("mousedown", handleClickOutside);
+      for (const event of resolvedEvents) {
+        document.removeEventListener(event, handler);
+      }
     };
-  }, [watch]);
+  }, [enabled, resolvedEvents.join("|")]);
 
   return ref;
 };
-

package/src/hooks/use-debounce-callback/use-debounced-callback.stories.tsx

@@ -1,15 +1,46 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
 import { Input } from "../../components";
-import { createToastManager, ToastProvider } from "../../components/toast";
+import {
+  createToastManager,
+  ToastProvider,
+  toast,
+} from "../../components/toast";
 import { useDebouncedCallback } from "./use-debounced-callback";
 
 const toastManager = createToastManager();
 
-const meta: Meta = {
+type Args = { delay: number };
+
+const meta: Meta<Args> = {
   title: "hooks/useDebouncedCallback",
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 100, max: 3000, step: 100 },
+      description: "Debounce delay in milliseconds.",
+    },
+  },
+  args: { delay: 600 },
+  parameters: {
+    docs: {
+      description: {
+        component: [
+          "Returns a stable debounced wrapper around `callback` with controls.",
+          "",
+          "**Signature**: `[debounced, { cancel, flush, isPending }] = useDebouncedCallback(callback, delay)`",
+          "",
+          "- `cancel()` — discard the pending call without invoking.",
+          "- `flush()` — invoke the pending call immediately.",
+          "- `isPending` — reactive boolean, `true` while a call is scheduled.",
+          "",
+          "The wrapper has a **stable identity** — it is only recreated when `delay` changes,",
+          "never when `callback` changes. Inline arrow functions are safe to pass.",
+        ].join("\n"),
+      },
+    },
+  },
   decorators: [
     (Story) => (
-      <ToastProvider toastManager={toastManager}>
+      <ToastProvider>
         <Story />
       </ToastProvider>
     ),
@@ -18,66 +49,135 @@ const meta: Meta = {
 
 export default meta;
 
-export const Basic = {
-  render: () => {
-    const handleSearch = useDebouncedCallback((value: string) => {
-      console.log("Búsqueda con:", value);
-      toastManager.add({
-        variant: "success",
-        description: `Búsqueda realizada con: ${value}`,
-      });
-    }, 600);
+export const Basic: StoryObj<Args> = {
+  render: ({ delay }) => {
+    const [handleSearch, { isPending, cancel, flush }] = useDebouncedCallback(
+      (value: string) => {
+        toast({
+          description: `Fired with: "${value}"`,
+        });
+      },
+      delay,
+    );
 
     return (
-      <div className="space-y-2">
-        <pre className="rounded-md bg-slate-950 p-4 text-white">
-          <code className="block">
-            Escribe en el input para ver el callback debounced en acción.
-          </code>
-          <code className="block">Revisa la consola para ver los logs.</code>
-        </pre>
+      <div className="flex max-w-sm flex-col gap-4">
         <Input
           onValueChange={(value) => handleSearch(value)}
-          placeholder="Escribe para buscar..."
+          placeholder="Type to trigger the debounced callback..."
         />
+        <div className="overflow-hidden rounded-lg border border-slate-800 bg-slate-900 font-mono text-sm">
+          <div className="border-b border-slate-800 bg-slate-800/60 px-4 py-2 font-sans text-xs font-semibold uppercase tracking-widest text-slate-400">
+            State
+          </div>
+          <div className="px-4 py-2.5">
+            <span className="text-slate-500">status</span>
+            <span className="ml-4">
+              <span
+                className={isPending ? "text-yellow-300" : "text-slate-500"}
+              >
+                {isPending ? "pending" : "idle"}
+              </span>
+            </span>
+          </div>
+        </div>
+        <div className="flex gap-2">
+          <button
+            type="button"
+            onClick={cancel}
+            disabled={!isPending}
+            className="rounded border border-slate-300 px-3 py-1.5 text-sm text-slate-600 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={flush}
+            disabled={!isPending}
+            className="rounded border border-slate-300 px-3 py-1.5 text-sm text-slate-600 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            Flush
+          </button>
+        </div>
       </div>
     );
   },
 };
 
-export const DifferentDelays: StoryObj = {
+export const DifferentDelays: StoryObj<Args> = {
+  parameters: {
+    controls: { exclude: ["delay"] },
+  },
   render: () => {
-    const handleFastDebounce = useDebouncedCallback((value: string) => {
+    const [
+      handleFast,
+      { isPending: fastPending, cancel: cancelFast, flush: flushFast },
+    ] = useDebouncedCallback((value: string) => {
       toastManager.add({
         variant: "success",
-        description: `Debounce rápido (200ms): ${value}`,
+        description: `Fast (200ms): "${value}"`,
       });
     }, 200);
 
-    const handleSlowDebounce = useDebouncedCallback((value: string) => {
+    const [
+      handleSlow,
+      { isPending: slowPending, cancel: cancelSlow, flush: flushSlow },
+    ] = useDebouncedCallback((value: string) => {
       toastManager.add({
         variant: "success",
-        description: `Debounce lento (1000ms): ${value}`,
+        description: `Slow (1000ms): "${value}"`,
       });
     }, 1000);
 
     return (
-      <div className="space-y-4">
-        <div>
-          <h3 className="text-sm font-semibold">Debounce Rápido (200ms)</h3>
-          <Input
-            onValueChange={(value) => handleFastDebounce(value)}
-            placeholder="Debounce rápido..."
-          />
-        </div>
-
-        <div>
-          <h3 className="text-sm font-semibold">Debounce Lento (1000ms)</h3>
-          <Input
-            onValueChange={(value) => handleSlowDebounce(value)}
-            placeholder="Debounce lento..."
-          />
-        </div>
+      <div className="flex max-w-sm flex-col gap-6">
+        {[
+          {
+            label: "Fast — 200ms",
+            handler: handleFast,
+            pending: fastPending,
+            cancel: cancelFast,
+            flush: flushFast,
+          },
+          {
+            label: "Slow — 1000ms",
+            handler: handleSlow,
+            pending: slowPending,
+            cancel: cancelSlow,
+            flush: flushSlow,
+          },
+        ].map(({ label, handler, pending, cancel, flush }) => (
+          <div key={label} className="flex flex-col gap-2">
+            <p className="text-sm font-medium text-slate-700">{label}</p>
+            <Input
+              onValueChange={(value) => handler(value)}
+              placeholder="Type..."
+            />
+            <div className="flex items-center gap-3">
+              <span
+                className={`text-xs font-mono ${pending ? "text-yellow-500" : "text-slate-400"}`}
+              >
+                {pending ? "pending" : "idle"}
+              </span>
+              <button
+                type="button"
+                onClick={cancel}
+                disabled={!pending}
+                className="rounded border border-slate-300 px-2.5 py-1 text-xs text-slate-600 hover:bg-slate-50 disabled:opacity-40"
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                onClick={flush}
+                disabled={!pending}
+                className="rounded border border-slate-300 px-2.5 py-1 text-xs text-slate-600 hover:bg-slate-50 disabled:opacity-40"
+              >
+                Flush
+              </button>
+            </div>
+          </div>
+        ))}
       </div>
     );
   },