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

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-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

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

@@ -0,0 +1,330 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { FOCUS_SELECTOR, findTabbableDescendants, focusable, tabbable } from "./tabbable";
+import { scopeTab } from "./scope-tab";
+import { useFocusTrap } from "./use-focus-trap";
+
+// ─── tabbable.ts ─────────────────────────────────────────────────────────────
+
+describe("focusable", () => {
+  it("returns true for a non-disabled button", () => {
+    const btn = document.createElement("button");
+    document.body.appendChild(btn);
+    expect(focusable(btn)).toBe(true);
+    btn.remove();
+  });
+
+  it("returns false for a disabled button", () => {
+    const btn = document.createElement("button");
+    btn.disabled = true;
+    document.body.appendChild(btn);
+    expect(focusable(btn)).toBe(false);
+    btn.remove();
+  });
+
+  it("returns true for an anchor with href", () => {
+    const a = document.createElement("a");
+    a.href = "https://example.com";
+    document.body.appendChild(a);
+    expect(focusable(a)).toBe(true);
+    a.remove();
+  });
+
+  it("returns false for an anchor without href and no tabindex", () => {
+    const a = document.createElement("a");
+    document.body.appendChild(a);
+    expect(focusable(a)).toBe(false);
+    a.remove();
+  });
+
+  it("returns true for div with tabindex='0'", () => {
+    const div = document.createElement("div");
+    div.setAttribute("tabindex", "0");
+    document.body.appendChild(div);
+    expect(focusable(div)).toBe(true);
+    div.remove();
+  });
+
+  it("returns false for div without tabindex", () => {
+    const div = document.createElement("div");
+    document.body.appendChild(div);
+    expect(focusable(div)).toBe(false);
+    div.remove();
+  });
+
+  it("returns false for element with aria-hidden='true'", () => {
+    const btn = document.createElement("button");
+    btn.setAttribute("aria-hidden", "true");
+    document.body.appendChild(btn);
+    expect(focusable(btn)).toBe(false);
+    btn.remove();
+  });
+
+  it("returns false for element with hidden='true'", () => {
+    const btn = document.createElement("button");
+    btn.setAttribute("hidden", "true");
+    document.body.appendChild(btn);
+    expect(focusable(btn)).toBe(false);
+    btn.remove();
+  });
+
+  it("returns false for input with type='hidden'", () => {
+    const input = document.createElement("input");
+    input.setAttribute("type", "hidden");
+    document.body.appendChild(input);
+    expect(focusable(input)).toBe(false);
+    input.remove();
+  });
+});
+
+describe("tabbable", () => {
+  it("returns true for a button (no tabindex)", () => {
+    const btn = document.createElement("button");
+    document.body.appendChild(btn);
+    expect(tabbable(btn)).toBe(true);
+    btn.remove();
+  });
+
+  it("returns false for element with tabindex='-1'", () => {
+    const btn = document.createElement("button");
+    btn.setAttribute("tabindex", "-1");
+    document.body.appendChild(btn);
+    expect(tabbable(btn)).toBe(false);
+    btn.remove();
+  });
+
+  it("returns true for element with tabindex='0'", () => {
+    const btn = document.createElement("button");
+    btn.setAttribute("tabindex", "0");
+    document.body.appendChild(btn);
+    expect(tabbable(btn)).toBe(true);
+    btn.remove();
+  });
+});
+
+describe("findTabbableDescendants", () => {
+  it("returns tabbable children of a container", () => {
+    const container = document.createElement("div");
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    btn2.disabled = true;
+    const input = document.createElement("input");
+    container.append(btn1, btn2, input);
+    document.body.appendChild(container);
+
+    const result = findTabbableDescendants(container);
+    expect(result).toContain(btn1);
+    expect(result).toContain(input);
+    expect(result).not.toContain(btn2);
+
+    container.remove();
+  });
+
+  it("returns empty array when no tabbable descendants", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    expect(findTabbableDescendants(container)).toHaveLength(0);
+    container.remove();
+  });
+});
+
+describe("FOCUS_SELECTOR", () => {
+  it("is a non-empty string covering focusable elements", () => {
+    expect(typeof FOCUS_SELECTOR).toBe("string");
+    expect(FOCUS_SELECTOR).toContain("button");
+    expect(FOCUS_SELECTOR).toContain("input");
+  });
+});
+
+// ─── scope-tab.ts ─────────────────────────────────────────────────────────────
+
+describe("scopeTab", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("calls preventDefault when no tabbable descendants", () => {
+    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    scopeTab(container, event);
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+  });
+
+  it("wraps focus to first element on Tab when last is focused", () => {
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    container.append(btn1, btn2);
+    btn2.focus();
+
+    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    scopeTab(container, event);
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(document.activeElement).toBe(btn1);
+  });
+
+  it("wraps focus to last element on Shift+Tab when first is focused", () => {
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    container.append(btn1, btn2);
+    btn1.focus();
+
+    const event = { key: "Tab", shiftKey: true, preventDefault: vi.fn() } as any;
+    scopeTab(container, event);
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(document.activeElement).toBe(btn2);
+  });
+
+  it("does not call preventDefault when mid-element is focused (Tab forward)", () => {
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    const btn3 = document.createElement("button");
+    container.append(btn1, btn2, btn3);
+    btn1.focus();
+
+    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    scopeTab(container, event);
+
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("radio group: Tab from any radio in group triggers wrap when last element is same group", () => {
+    const btn = document.createElement("button");
+    const radio1 = document.createElement("input");
+    radio1.setAttribute("type", "radio");
+    radio1.setAttribute("name", "choice");
+    const radio2 = document.createElement("input");
+    radio2.setAttribute("type", "radio");
+    radio2.setAttribute("name", "choice");
+    container.append(btn, radio1, radio2);
+    radio1.focus();
+
+    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    scopeTab(container, event);
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(document.activeElement).toBe(btn);
+  });
+});
+
+// ─── use-focus-trap.ts ────────────────────────────────────────────────────────
+
+describe("useFocusTrap", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns a ref callback function", () => {
+    const { result } = renderHook(() => useFocusTrap());
+    expect(typeof result.current).toBe("function");
+  });
+
+  it("does nothing when active=false", () => {
+    const { result } = renderHook(() => useFocusTrap(false));
+    const container = document.createElement("div");
+    const btn = document.createElement("button");
+    container.appendChild(btn);
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+
+    expect(document.activeElement).not.toBe(btn);
+    container.remove();
+  });
+
+  it("focuses first tabbable element when active=true", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    const container = document.createElement("div");
+    const btn = document.createElement("button");
+    container.appendChild(btn);
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+
+    expect(document.activeElement).toBe(btn);
+    container.remove();
+  });
+
+  it("focuses [data-autofocus] element when present", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    const container = document.createElement("div");
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    btn2.setAttribute("data-autofocus", "");
+    container.append(btn1, btn2);
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+
+    expect(document.activeElement).toBe(btn2);
+    container.remove();
+  });
+
+  it("does nothing when setRef called with null", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    expect(() => result.current(null)).not.toThrow();
+  });
+
+  it("focuses the container itself when no tabbable children but container is focusable", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    const container = document.createElement("div");
+    container.setAttribute("tabindex", "0");
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+
+    expect(document.activeElement).toBe(container);
+    container.remove();
+  });
+
+  it("does not re-focus when same node is assigned a second time", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    const container = document.createElement("div");
+    const btn = document.createElement("button");
+    container.appendChild(btn);
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+    expect(document.activeElement).toBe(btn);
+
+    result.current(container);
+    vi.runAllTimers();
+    expect(document.activeElement).toBe(btn);
+    container.remove();
+  });
+
+  it("adds keydown listener that calls scopeTab on Tab key", () => {
+    const { result } = renderHook(() => useFocusTrap(true));
+    const container = document.createElement("div");
+    const btn1 = document.createElement("button");
+    const btn2 = document.createElement("button");
+    container.append(btn1, btn2);
+    document.body.appendChild(container);
+
+    result.current(container);
+    vi.runAllTimers();
+    btn2.focus();
+
+    const event = new KeyboardEvent("keydown", { key: "Tab", bubbles: true });
+    document.dispatchEvent(event);
+
+    expect(document.activeElement).toBe(btn1);
+    container.remove();
+  });
+});

package/src/hooks/{useFocusTrap/useFocusTrap.ts → use-focus-trap/use-focus-trap.ts}

@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useRef } from "react";
-import { scopeTab } from "./scopeTab";
+import { scopeTab } from "./scope-tab";
 import { FOCUS_SELECTOR, focusable, tabbable } from "./tabbable";
 
-function useFocusTrap(active = true): (instance: HTMLElement | null) => void {
+export function useFocusTrap(active = true): (instance: HTMLElement | null) => void {
   const ref = useRef<HTMLElement | null>(null);
 
   const focusNode = (node: HTMLElement) => {
@@ -75,4 +75,3 @@ function useFocusTrap(active = true): (instance: HTMLElement | null) => void {
   return setRef;
 }
 
-export default useFocusTrap;

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

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

package/src/hooks/{useHotkey/__docs__/useHotkey.stories.tsx → use-hotkey/use-hotkey.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
 import { HTMLProps, ReactNode, useState } from "react";
-import { cn } from "../../../lib";
-import useHotkey from "../useHotkey";
+import { cn } from "../../lib";
+import { useHotkey } from "../use-hotkey";
 
 const meta: Meta = {
   title: "hooks/useHotkey",

package/src/hooks/{useHotkey/__test__/useHotkey.test.tsx → use-hotkey/use-hotkey.test.tsx}

@@ -1,7 +1,7 @@
-import { render, waitFor } from "@testing-library/react";
+import { render, screen, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import { keyboard } from "../../../utils/tests/keyboard";
-import useHotkey, { HotkeyOptions } from "../useHotkey";
+import { keyboard } from "../../utils/tests/keyboard";
+import { useHotkey, HotkeyOptions } from "../use-hotkey";
 
 describe("useHotkey hook", () => {
   it("should be defined", () => {
@@ -102,4 +102,35 @@ describe("useHotkey hook", () => {
       expect(handler).toHaveBeenCalledTimes(2);
     });
   });
+
+  it("does not call handler when watch=false", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("f", handler, { watch: false });
+      return null;
+    };
+    render(<TestComponent />);
+    keyboard(document, { key: "f" });
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  it("does not call handler when keydown originates from an input field", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("z", handler);
+      return <input data-testid="input" />;
+    };
+    render(<TestComponent />);
+
+    const input = screen.getByTestId("input");
+    input.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+    );
+
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/hooks/{useHotkey/useHotkey.ts → use-hotkey/use-hotkey.ts}

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
-import { useEventListener } from "../useEventListener";
-import { createListener } from "./__utils__";
+import { useEventListener } from "../use-event-listener";
+import { createListener } from "./utils";
 
 export type Keys = string | string[];
 export type HotkeyEventName = "keydown" | "keypress" | "keyup";
@@ -11,7 +11,7 @@ export type HotkeyOptions = {
   ignoreInputFields?: boolean;
 };
 
-function useHotkey(
+export function useHotkey(
   keys: string | string[],
   handler: (event: KeyboardEvent) => void,
   options: HotkeyOptions = {},
@@ -31,4 +31,3 @@ function useHotkey(
   return useEventListener(eventName, listener);
 }
 
-export default useHotkey;

package/src/hooks/use-is-visible/index.ts

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

package/src/hooks/{useIsVisible/__doc__/useIsVisible.stories.tsx → use-is-visible/use-is-visible.stories.tsx}

@@ -1,8 +1,8 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
 import { ArrowDown } from "lucide-react";
 import { ReactNode } from "react";
-import { createToastManager, ToastProvider } from "../../../components/toast";
-import useIsVisible from "../useIsVisible";
+import { createToastManager, ToastProvider } from "../../components/toast";
+import { useIsVisible } from "../use-is-visible";
 
 const toastManager = createToastManager();
 

package/src/hooks/use-is-visible/use-is-visible.test.tsx

@@ -0,0 +1,135 @@
+import { act, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useIsVisible } from "./use-is-visible";
+
+// IntersectionObserver isn't available in jsdom. Provide a controllable mock.
+type ObserverCallback = IntersectionObserverCallback;
+
+let observerCallback: ObserverCallback | null = null;
+let observedEl: Element | null = null;
+
+class IntersectionObserverMock implements IntersectionObserver {
+  readonly root = null;
+  readonly rootMargin = "0px";
+  readonly thresholds = [0];
+
+  constructor(cb: ObserverCallback) {
+    observerCallback = cb;
+  }
+
+  observe(el: Element) {
+    observedEl = el;
+  }
+  unobserve() {
+    observedEl = null;
+  }
+  disconnect() {}
+  takeRecords() {
+    return [];
+  }
+}
+
+vi.stubGlobal("IntersectionObserver", IntersectionObserverMock);
+
+function makeEntry(isIntersecting: boolean): IntersectionObserverEntry {
+  return { isIntersecting } as IntersectionObserverEntry;
+}
+
+function Fixture({
+  onVisible,
+}: {
+  onVisible?: () => void;
+}) {
+  const { ref, isVisible } = useIsVisible<HTMLDivElement>({ onVisible });
+  return (
+    <div ref={ref} data-testid="target">
+      {isVisible ? "visible" : "hidden"}
+    </div>
+  );
+}
+
+describe("useIsVisible", () => {
+  it("starts as hidden", () => {
+    render(<Fixture />);
+    expect(screen.getByTestId("target")).toHaveTextContent("hidden");
+  });
+
+  it("becomes visible when IntersectionObserver fires with isIntersecting=true", () => {
+    render(<Fixture />);
+
+    act(() => {
+      observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+    });
+
+    expect(screen.getByTestId("target")).toHaveTextContent("visible");
+  });
+
+  it("goes back to hidden when isIntersecting=false", () => {
+    render(<Fixture />);
+
+    act(() => {
+      observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+    });
+    act(() => {
+      observerCallback?.([makeEntry(false)], {} as IntersectionObserver);
+    });
+
+    expect(screen.getByTestId("target")).toHaveTextContent("hidden");
+  });
+
+  it("calls onVisible when element becomes visible", () => {
+    const onVisible = vi.fn();
+    render(<Fixture onVisible={onVisible} />);
+
+    act(() => {
+      observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+    });
+
+    expect(onVisible).toHaveBeenCalledOnce();
+  });
+
+  it("does not call onVisible when element becomes hidden", () => {
+    const onVisible = vi.fn();
+    render(<Fixture onVisible={onVisible} />);
+
+    act(() => {
+      observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+    });
+    onVisible.mockClear();
+
+    act(() => {
+      observerCallback?.([makeEntry(false)], {} as IntersectionObserver);
+    });
+
+    expect(onVisible).not.toHaveBeenCalled();
+  });
+
+  it("observes the DOM element", () => {
+    render(<Fixture />);
+    expect(observedEl).not.toBeNull();
+  });
+
+  it("calls unobserve when observer options change (cleanup while mounted)", () => {
+    const unobserveSpy = vi.spyOn(
+      IntersectionObserverMock.prototype,
+      "unobserve",
+    );
+
+    function Resettable({ margin }: { margin: string }) {
+      const { ref, isVisible } = useIsVisible<HTMLDivElement>({
+        rootMargin: margin,
+      });
+      return (
+        <div ref={ref} data-testid="resettable">
+          {isVisible ? "visible" : "hidden"}
+        </div>
+      );
+    }
+
+    const { rerender } = render(<Resettable margin="0px" />);
+    rerender(<Resettable margin="10px" />);
+
+    expect(unobserveSpy).toHaveBeenCalled();
+    unobserveSpy.mockRestore();
+  });
+});

package/src/hooks/{useIsVisible/useIsVisible.tsx → use-is-visible/use-is-visible.tsx}

@@ -9,7 +9,7 @@ interface UseIsVisibleReturn<T> {
   isVisible: boolean;
 }
 
-function useIsVisible<T extends HTMLElement>({
+export function useIsVisible<T extends HTMLElement>({
   onVisible,
   root = null,
   rootMargin = "0px",
@@ -47,4 +47,3 @@ function useIsVisible<T extends HTMLElement>({
   return { ref, isVisible };
 }
 
-export default useIsVisible;

package/src/hooks/use-local-storage/index.ts

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