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

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

@@ -0,0 +1,88 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useDebouncedCallback } from "./use-debounced-callback";
+
+describe("useDebouncedCallback", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns a stable function reference", () => {
+    const cb = vi.fn();
+    const { result, rerender } = renderHook(() =>
+      useDebouncedCallback(cb, 200),
+    );
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+
+  it("does not call callback before delay elapses", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      result.current("a");
+    });
+
+    vi.advanceTimersByTime(299);
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("calls callback after delay with correct args", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      result.current("hello", 42);
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(cb).toHaveBeenCalledOnce();
+    expect(cb).toHaveBeenCalledWith("hello", 42);
+  });
+
+  it("resets the timer on consecutive calls (debounce behavior)", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 300));
+
+    act(() => {
+      result.current("first");
+      vi.advanceTimersByTime(200);
+      result.current("second");
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(cb).toHaveBeenCalledOnce();
+    expect(cb).toHaveBeenCalledWith("second");
+  });
+
+  it("invokes callback multiple times when enough time passes between calls", () => {
+    const cb = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(cb, 100));
+
+    act(() => {
+      result.current("a");
+      vi.advanceTimersByTime(200);
+      result.current("b");
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(cb).toHaveBeenCalledTimes(2);
+    expect(cb).toHaveBeenNthCalledWith(1, "a");
+    expect(cb).toHaveBeenNthCalledWith(2, "b");
+  });
+});

package/src/hooks/{useDebounceCallback/useDebouncedCallback.ts → use-debounce-callback/use-debounced-callback.ts}

@@ -1,6 +1,6 @@
 import { useCallback, useRef } from "react";
 
-function useDebouncedCallback<T extends (...args: any[]) => any>(
+export function useDebouncedCallback<T extends (...args: any[]) => any>(
   callback: T,
   delay: number,
 ): (...args: Parameters<T>) => void {
@@ -20,4 +20,3 @@ function useDebouncedCallback<T extends (...args: any[]) => any>(
   );
 }
 
-export default useDebouncedCallback;

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

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

package/src/hooks/{useDebounceValue/__doc__/useDebouncedValue.stories.tsx → use-debounce-value/use-debounced-value.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
-import { Input } from "../../../components";
-import { useDebouncedValue } from "../../useDebounceValue";
+import { Input } from "../../components";
+import { useDebouncedValue } from "./use-debounced-value";
 
 const meta: Meta = {
   title: "hooks/useDebouncedValue",

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

@@ -0,0 +1,101 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useDebouncedValue } from "./use-debounced-value";
+
+describe("useDebouncedValue", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns initial value immediately", () => {
+    const { result } = renderHook(() => useDebouncedValue("init", 300));
+    expect(result.current).toBe("init");
+  });
+
+  it("does not update before delay elapses", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(299);
+    });
+
+    expect(result.current).toBe("a");
+  });
+
+  it("updates after delay elapses", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current).toBe("b");
+  });
+
+  it("cancels pending update when value changes again before delay", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    rerender({ value: "c" });
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(result.current).toBe("a");
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(result.current).toBe("c");
+  });
+
+  it("works with non-string values", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebouncedValue(value, 100),
+      { initialProps: { value: 0 } },
+    );
+
+    rerender({ value: 42 });
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(result.current).toBe(42);
+  });
+
+  it("clears timeout on unmount (no state update after unmount)", () => {
+    const { rerender, unmount } = renderHook(
+      ({ value }) => useDebouncedValue(value, 300),
+      { initialProps: { value: "a" } },
+    );
+
+    rerender({ value: "b" });
+    unmount();
+
+    expect(() => {
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+    }).not.toThrow();
+  });
+});

package/src/hooks/{useDebounceValue/useDebouncedValue.ts → use-debounce-value/use-debounced-value.ts}

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 
-function useDebouncedValue<T>(value: T, delay: number): T {
+export function useDebouncedValue<T>(value: T, delay: number): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);
 
   useEffect(() => {
@@ -14,4 +14,3 @@ function useDebouncedValue<T>(value: T, delay: number): T {
   return debouncedValue;
 }
 
-export default useDebouncedValue;

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

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

package/src/hooks/{useDisclosure/__doc__/useDisclosure.stories.tsx → use-disclosure/use-disclosure.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta } from "@storybook/react-vite";
-import { Button } from "../../../components";
-import { cn } from "../../../lib";
-import useDisclosure from "../useDisclosure";
+import { Button } from "../../components";
+import { cn } from "../../lib";
+import { useDisclosure } from "../use-disclosure";
 
 /**
  * Hook que facilita el manejo de un estado booleano. Provee métodos para abrir, cerrar y toggle el estado

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

@@ -0,0 +1,72 @@
+import { act, renderHook } from "@testing-library/react";
+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);
+  });
+
+  it("starts open when initialState=true", () => {
+    const { result } = renderHook(() => useDisclosure(true));
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("open() opens disclosure", () => {
+    const { result } = renderHook(() => useDisclosure());
+    act(() => result.current[1].open());
+    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("close() closes disclosure", () => {
+    const { result } = renderHook(() => useDisclosure(true));
+    act(() => 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() opens when closed", () => {
+    const { result } = renderHook(() => useDisclosure());
+    act(() => result.current[1].toggle());
+    expect(result.current[0]).toBe(true);
+  });
+
+  it("toggle() closes when open", () => {
+    const { result } = renderHook(() => useDisclosure(true));
+    act(() => result.current[1].toggle());
+    expect(result.current[0]).toBe(false);
+  });
+
+  it("calls onOpen callback when opening", () => {
+    const onOpen = vi.fn();
+    const { result } = renderHook(() => useDisclosure(false, { onOpen }));
+    act(() => result.current[1].open());
+    expect(onOpen).toHaveBeenCalledOnce();
+  });
+
+  it("calls onClose callback when closing", () => {
+    const onClose = vi.fn();
+    const { result } = renderHook(() => useDisclosure(true, { onClose }));
+    act(() => result.current[1].close());
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  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();
+  });
+});

package/src/hooks/{useDisclosure/useDisclosure.ts → use-disclosure/use-disclosure.ts}

@@ -1,6 +1,6 @@
 import { useCallback, useState } from "react";
 
-function useDisclosure(
+export function useDisclosure(
   initialState = false,
   callbacks?: { onOpen?: () => void; onClose?: () => void },
 ) {
@@ -34,4 +34,3 @@ function useDisclosure(
   return [isOpen, { open, close, toggle }] as const;
 }
 
-export default useDisclosure;

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

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

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

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Input } from "../../components/input";
+import { Stack } from "../../components/stack";
+import { useDocumentTitle } from "./use-document-title";
+
+/**
+ * Sync `document.title` with a piece of React state — the classic
+ * "mirror the page name in the browser tab" pattern.
+ *
+ * ```tsx
+ * useDocumentTitle("Dashboard");
+ * useDocumentTitle(`Inbox (${unreadCount})`);
+ * ```
+ *
+ * Good to know:
+ * - **Empty and whitespace-only values are ignored.** The current title
+ *   stays put. Avoids the foot-gun of a parent component passing a
+ *   not-yet-loaded value and blanking the tab.
+ * - **Leading and trailing whitespace is trimmed** before being written.
+ * - **Opt-in cleanup:** pass `{ restoreOnUnmount: true }` to restore the
+ *   title that existed at mount time when the component unmounts. Useful
+ *   for modal/route components that only own the title while they are
+ *   visible.
+ *
+ * ```tsx
+ * useDocumentTitle(`Editing: ${doc.name}`, { restoreOnUnmount: true });
+ * ```
+ *
+ * Heads up: inside Storybook the change happens on the **iframe's**
+ * `document.title`, not the parent browser tab. Open the story in
+ * isolated canvas view to see the tab update, or just read the value
+ * rendered inline below.
+ */
+const meta: Meta<typeof useDocumentTitle> = {
+  title: "hooks/useDocumentTitle",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useDocumentTitle>;
+
+/**
+ * Type into the input — the hook writes `document.title` in real time.
+ * The code block below mirrors what gets written, including the
+ * whitespace-trim behavior. Clear the input to see the "ignored" path:
+ * the title stays at its last non-empty value.
+ */
+export const Default: Story = {
+  render: () => {
+    const [title, setTitle] = useState("Dashboard");
+    useDocumentTitle(title);
+
+    const written = title.trim();
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 360 }}>
+        <Input
+          value={title}
+          onValueChange={setTitle}
+          placeholder="Type a title…"
+        />
+        <code className="rounded-md bg-muted px-3 py-2 text-xs">
+          {written.length > 0
+            ? `document.title = "${written}"`
+            : "(empty — current title preserved)"}
+        </code>
+      </Stack>
+    );
+  },
+};

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

@@ -0,0 +1,75 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { useDocumentTitle } from "./use-document-title";
+
+describe("useDocumentTitle", () => {
+  beforeEach(() => {
+    document.title = "Original";
+  });
+
+  afterEach(() => {
+    document.title = "";
+  });
+
+  it("sets document.title to the provided value", () => {
+    renderHook(() => useDocumentTitle("Dashboard"));
+    expect(document.title).toBe("Dashboard");
+  });
+
+  it("updates the title when the value changes", () => {
+    const { rerender } = renderHook(({ title }) => useDocumentTitle(title), {
+      initialProps: { title: "First" },
+    });
+    expect(document.title).toBe("First");
+
+    rerender({ title: "Second" });
+    expect(document.title).toBe("Second");
+  });
+
+  it("ignores empty strings — the existing title stays put", () => {
+    renderHook(() => useDocumentTitle(""));
+    expect(document.title).toBe("Original");
+  });
+
+  it("ignores whitespace-only strings", () => {
+    renderHook(() => useDocumentTitle("   \t\n  "));
+    expect(document.title).toBe("Original");
+  });
+
+  it("trims surrounding whitespace before writing", () => {
+    renderHook(() => useDocumentTitle("  Hello  "));
+    expect(document.title).toBe("Hello");
+  });
+
+  it("does not restore the previous title on unmount by default", () => {
+    const { unmount } = renderHook(() => useDocumentTitle("New"));
+    expect(document.title).toBe("New");
+
+    unmount();
+    expect(document.title).toBe("New");
+  });
+
+  it("restores the previous title on unmount when restoreOnUnmount=true", () => {
+    const { unmount } = renderHook(() =>
+      useDocumentTitle("New", { restoreOnUnmount: true }),
+    );
+    expect(document.title).toBe("New");
+
+    unmount();
+    expect(document.title).toBe("Original");
+  });
+
+  it("captures the original title at mount, not the latest one", () => {
+    document.title = "First";
+    const { unmount, rerender } = renderHook(
+      ({ title }) => useDocumentTitle(title, { restoreOnUnmount: true }),
+      { initialProps: { title: "Step 1" } },
+    );
+
+    rerender({ title: "Step 2" });
+    expect(document.title).toBe("Step 2");
+
+    unmount();
+    expect(document.title).toBe("First");
+  });
+});

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

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from "react";
+
+export interface UseDocumentTitleInput {
+  /** Restore the previous `document.title` when the component unmounts. Defaults to `false`. */
+  restoreOnUnmount?: boolean;
+}
+
+export function useDocumentTitle(
+  title: string,
+  options: UseDocumentTitleInput = {},
+): void {
+  const { restoreOnUnmount = false } = options;
+  const restoreRef = useRef(restoreOnUnmount);
+  restoreRef.current = restoreOnUnmount;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: mount/unmount only
+  useEffect(() => {
+    const previous = document.title;
+    return () => {
+      if (restoreRef.current) {
+        document.title = previous;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (typeof title !== "string") return;
+    const trimmed = title.trim();
+    if (trimmed.length === 0) return;
+    document.title = trimmed;
+  }, [title]);
+}

package/src/hooks/use-event-listener/index.ts

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

package/src/hooks/{useEventListener/__doc__/useEventListener.stories.tsx → use-event-listener/use-event-listener.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta } from "@storybook/react-vite";
 import { action } from "storybook/actions";
-import { Button } from "../../../components";
-import useEventListener from "../useEventListener";
+import { Button } from "../../components";
+import { useEventListener } from "../use-event-listener";
 
 /**
  * Hook que facilita el manejor de eventos

package/src/hooks/{useEventListener/__test__/useEventListener.test.tsx → use-event-listener/use-event-listener.test.tsx}

@@ -1,8 +1,8 @@
 import { screen } from "@testing-library/dom";
 import { render, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import { click } from "../../../utils/tests";
-import useEventListener from "../useEventListener";
+import { click } from "../../utils/tests";
+import { useEventListener } from "../use-event-listener";
 
 describe("useEventListener hook", () => {
   it("should be defined", () => {
@@ -12,7 +12,10 @@ describe("useEventListener hook", () => {
   it("should handle event", () => {
     const handleEvent = vi.fn();
     const Component = () => {
-      const ref = useEventListener("click", handleEvent);
+      const ref = useEventListener<"click", HTMLDivElement>(
+        "click",
+        handleEvent,
+      );
       return <div ref={ref} data-testid="target" />;
     };
     render(<Component />);

package/src/hooks/{useEventListener/useEventListener.ts → use-event-listener/use-event-listener.ts}

@@ -1,11 +1,11 @@
 import { useEffect, useRef } from "react";
 
-function useEventListener<
+export function useEventListener<
   K extends keyof HTMLElementEventMap,
-  T extends HTMLElement = any,
+  T extends HTMLElement = HTMLElement,
 >(
   type: K,
-  listener: (this: HTMLDivElement, ev: HTMLElementEventMap[K]) => any,
+  listener: (this: T, ev: HTMLElementEventMap[K]) => void,
   options?: boolean | AddEventListenerOptions,
 ) {
   const ref = useRef<T | null>(null);
@@ -22,4 +22,3 @@ function useEventListener<
   return ref;
 }
 
-export default useEventListener;

package/src/hooks/use-focus-trap/index.ts

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

package/src/hooks/{useFocusTrap/__doc__/useFocusTrap.stories.tsx → use-focus-trap/use-focus-trap.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta } from "@storybook/react-vite";
 import { useState } from "react";
-import { Button, Checkbox } from "../../../components";
-import useFocusTrap from "../useFocusTrap";
+import { Button, Checkbox } from "../../components";
+import { useFocusTrap } from "../use-focus-trap";
 
 /**
  * Hook que atrapa el focus en un scope