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

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-hover/index.ts

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

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

@@ -0,0 +1,90 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useHover } from "./use-hover";
+
+/**
+ * Track whether the pointer is over a specific element.
+ *
+ * Returns a `ref` callback you attach to the target element and a
+ * `hovered` boolean that flips while the pointer is inside its bounds.
+ * Powered by `mouseenter` / `mouseleave` — children inside the target
+ * do **not** flicker the state on and off.
+ *
+ * ```tsx
+ * const { ref, hovered } = useHover<HTMLDivElement>();
+ *
+ * <div ref={ref} className={hovered ? "bg-accent" : ""}>
+ *   Hover me
+ * </div>
+ * ```
+ *
+ * Optional callbacks for imperative side effects (analytics, prefetch,
+ * audio) — they receive the native `MouseEvent` and don't force a render:
+ *
+ * ```tsx
+ * useHover<HTMLAnchorElement>({
+ *   onHoverStart: () => prefetch("/dashboard"),
+ *   onHoverEnd: (event) => log("left", event.clientX, event.clientY),
+ * });
+ * ```
+ *
+ * Good to know:
+ * - `ref` is a callback ref (not a `RefObject`). Pass it straight to a
+ *   DOM element — you can't read `.current` from outside the hook.
+ * - Listeners are attached when the ref binds and removed when it
+ *   detaches (unmount, ref reassignment, conditional rendering). No
+ *   memory leaks.
+ * - The callback identity is read fresh on every event, so passing
+ *   inline arrow functions is safe — no re-attaching, no stale closure.
+ * - Generic param controls the element type:
+ *   `useHover<HTMLButtonElement>()` types the ref for a `<button>`.
+ */
+const meta: Meta<typeof useHover> = {
+  title: "hooks/useHover",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useHover>;
+
+/**
+ * Move the pointer over the card. Background and label update in
+ * real time. Notice the child elements (the icon and the caption) do
+ * **not** flicker the state — `mouseenter` ignores child traversals.
+ */
+export const Default: Story = {
+  render: () => {
+    const { ref, hovered } = useHover<HTMLDivElement>();
+
+    return (
+      <div
+        ref={ref}
+        style={{
+          width: 280,
+          padding: 24,
+          borderRadius: 12,
+          cursor: "pointer",
+          transition: "background-color 150ms, transform 150ms",
+          transform: hovered ? "translateY(-2px)" : "translateY(0)",
+        }}
+        className={
+          hovered
+            ? "border border-primary bg-primary/10 text-primary"
+            : "border border-border bg-card"
+        }
+      >
+        <div className="flex items-center gap-3">
+          <span style={{ fontSize: 28 }}>{hovered ? "👋" : "🙂"}</span>
+          <div className="flex flex-col">
+            <span className="text-sm font-medium">
+              {hovered ? "Hovering" : "Hover me"}
+            </span>
+            <span className="text-xs text-muted-foreground">
+              hovered = {String(hovered)}
+            </span>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};

package/src/hooks/use-hover/use-hover.test.tsx

@@ -0,0 +1,93 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useHover } from "./use-hover";
+
+function HoverTarget({
+  onHoverStart,
+  onHoverEnd,
+}: {
+  onHoverStart?: (event: MouseEvent) => void;
+  onHoverEnd?: (event: MouseEvent) => void;
+}) {
+  const { ref, hovered } = useHover<HTMLDivElement>({
+    onHoverStart,
+    onHoverEnd,
+  });
+  return (
+    <div ref={ref} data-testid="target">
+      {hovered ? "hovered" : "idle"}
+    </div>
+  );
+}
+
+describe("useHover", () => {
+  it("starts in the idle state", () => {
+    render(<HoverTarget />);
+    expect(screen.getByTestId("target")).toHaveTextContent("idle");
+  });
+
+  it("flips hovered to true on mouseenter and back on mouseleave", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.mouseLeave(target);
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("ignores mouseover/mouseout (which bubble from children)", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseOver(target);
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("invokes onHoverStart with the MouseEvent on enter", () => {
+    const onHoverStart = vi.fn();
+    render(<HoverTarget onHoverStart={onHoverStart} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+
+    expect(onHoverStart).toHaveBeenCalledTimes(1);
+    expect(onHoverStart.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
+  });
+
+  it("invokes onHoverEnd with the MouseEvent on leave", () => {
+    const onHoverEnd = vi.fn();
+    render(<HoverTarget onHoverEnd={onHoverEnd} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    fireEvent.mouseLeave(target);
+
+    expect(onHoverEnd).toHaveBeenCalledTimes(1);
+    expect(onHoverEnd.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
+  });
+
+  it("uses the latest callback identity without re-attaching listeners", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<HoverTarget onHoverStart={first} />);
+    const target = screen.getByTestId("target");
+
+    rerender(<HoverTarget onHoverStart={second} />);
+    fireEvent.mouseEnter(target);
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes listeners on unmount", () => {
+    const { unmount } = render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.mouseEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    expect(() => unmount()).not.toThrow();
+  });
+});

package/src/hooks/use-hover/use-hover.tsx

@@ -0,0 +1,45 @@
+import { type RefCallback, useCallback, useRef, useState } from "react";
+
+export interface UseHoverInput {
+  /** Fired when the pointer enters the target element. Receives the native MouseEvent. */
+  onHoverStart?: (event: MouseEvent) => void;
+  /** Fired when the pointer leaves the target element. Receives the native MouseEvent. */
+  onHoverEnd?: (event: MouseEvent) => void;
+}
+
+export interface UseHoverReturnValue<T extends HTMLElement = HTMLElement> {
+  hovered: boolean;
+  ref: RefCallback<T>;
+}
+
+export function useHover<T extends HTMLElement = HTMLElement>(
+  options: UseHoverInput = {},
+): UseHoverReturnValue<T> {
+  const [hovered, setHovered] = useState(false);
+  const callbacksRef = useRef(options);
+  callbacksRef.current = options;
+
+  const ref: RefCallback<T> = useCallback((node) => {
+    if (!node) return;
+
+    const handleEnter = (event: MouseEvent) => {
+      setHovered(true);
+      callbacksRef.current.onHoverStart?.(event);
+    };
+    const handleLeave = (event: MouseEvent) => {
+      setHovered(false);
+      callbacksRef.current.onHoverEnd?.(event);
+    };
+
+    node.addEventListener("mouseenter", handleEnter);
+    node.addEventListener("mouseleave", handleLeave);
+
+    return () => {
+      node.removeEventListener("mouseenter", handleEnter);
+      node.removeEventListener("mouseleave", handleLeave);
+      setHovered(false);
+    };
+  }, []);
+
+  return { hovered, ref };
+}

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();