@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/hooks/use-focus-trap/use-focus-trap.stories.tsx

@@ -0,0 +1,37 @@
+import { Meta } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button, Checkbox } from "../../components";
+import { useFocusTrap } from "../use-focus-trap";
+
+/**
+ * Hook que atrapa el focus en un scope
+ */
+const meta: Meta = {
+  title: "hooks/useFocusTrap",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [active, setActive] = useState(true);
+    const trapRefContainer = useFocusTrap();
+    const trapRef = useFocusTrap(active);
+
+    return (
+      <div ref={trapRefContainer} className="space-y-2">
+        <div className="py-4">
+          <Checkbox name="1" />
+          <div ref={trapRef}>
+            <Checkbox name="2" />
+            <Checkbox name="3" />
+          </div>
+          <Checkbox name="4" />
+        </div>
+        <Button onClick={() => setActive(!active)}>
+          {active ? "Desactivar" : "Activar"}
+        </Button>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,355 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { scopeTab } from "./scope-tab";
+import {
+  FOCUS_SELECTOR,
+  findTabbableDescendants,
+  focusable,
+  tabbable,
+} from "./tabbable";
+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/use-focus-trap/use-focus-trap.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef } from "react";
+import { scopeTab } from "./scope-tab";
+import { FOCUS_SELECTOR, focusable, tabbable } from "./tabbable";
+
+export function useFocusTrap(
+  active = true,
+): (instance: HTMLElement | null) => void {
+  const ref = useRef<HTMLElement | null>(null);
+
+  const focusNode = (node: HTMLElement) => {
+    let focusElement: HTMLElement | null =
+      node.querySelector("[data-autofocus]");
+
+    if (!focusElement) {
+      const children = Array.from<HTMLElement>(
+        node.querySelectorAll(FOCUS_SELECTOR),
+      );
+      focusElement =
+        children.find(tabbable) || children.find(focusable) || null;
+      if (!focusElement && focusable(node)) {
+        focusElement = node;
+      }
+    }
+
+    if (focusElement) {
+      focusElement.focus({ preventScroll: true });
+    }
+  };
+
+  const setRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (!active) {
+        return;
+      }
+
+      if (node === null) {
+        return;
+      }
+
+      if (ref.current === node) {
+        return;
+      }
+
+      if (node) {
+        // Delay processing the HTML node by a frame. This ensures focus is assigned correctly.
+        setTimeout(() => {
+          if (node.getRootNode()) {
+            focusNode(node);
+          }
+        });
+
+        ref.current = node;
+      } else {
+        ref.current = null;
+      }
+    },
+    [active],
+  );
+
+  useEffect(() => {
+    if (!active) {
+      return undefined;
+    }
+
+    ref.current && setTimeout(() => focusNode(ref.current!));
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Tab" && ref.current) {
+        scopeTab(ref.current, event);
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [active]);
+
+  return setRef;
+}

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

@@ -0,0 +1,9 @@
+export type {
+  HotkeyEventName,
+  HotkeyItem,
+  HotkeyItemOptions,
+  HotkeyOptions,
+  KeyboardEventLike,
+  Keys,
+} from "./use-hotkey";
+export { getHotkeyHandler, useHotkey } from "./use-hotkey";