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

package/src/hooks/use-event-listener/use-event-listener.test.tsx

@@ -1,5 +1,6 @@
 import { screen } from "@testing-library/dom";
-import { render, waitFor } from "@testing-library/react";
+import { fireEvent, render, renderHook } from "@testing-library/react";
+import { useRef } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { click } from "../../utils/tests";
 import { useEventListener } from "../use-event-listener";
@@ -9,21 +10,87 @@ describe("useEventListener hook", () => {
     expect(useEventListener).toBeDefined();
   });
 
-  it("should handle event", () => {
-    const handleEvent = vi.fn();
+  it("listens on window by default when no target is passed", () => {
+    const handler = vi.fn();
+    renderHook(() => useEventListener("resize", handler));
+
+    fireEvent(window, new Event("resize"));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("listens on an element passed by ref", () => {
+    const handler = vi.fn();
     const Component = () => {
-      const ref = useEventListener<"click", HTMLDivElement>(
-        "click",
-        handleEvent,
-      );
+      const ref = useRef<HTMLDivElement>(null);
+      useEventListener("click", handler, ref);
       return <div ref={ref} data-testid="target" />;
     };
     render(<Component />);
 
     click(screen.getByTestId("target"));
 
-    waitFor(() => {
-      expect(handleEvent).toHaveBeenCalled();
-    });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("listens on document when passed directly", () => {
+    const handler = vi.fn();
+    renderHook(() => useEventListener("keydown", handler, document));
+
+    fireEvent.keyDown(document.body);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("always calls the latest listener without re-attaching", () => {
+    const addSpy = vi.spyOn(window, "addEventListener");
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ cb }) => useEventListener("resize", cb),
+      {
+        initialProps: { cb: first },
+      },
+    );
+    const attachCountAfterMount = addSpy.mock.calls.filter(
+      ([type]) => type === "resize",
+    ).length;
+
+    rerender({ cb: second });
+    fireEvent(window, new Event("resize"));
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+    // listener identity change must not re-attach
+    expect(addSpy.mock.calls.filter(([type]) => type === "resize").length).toBe(
+      attachCountAfterMount,
+    );
+
+    addSpy.mockRestore();
+  });
+
+  it("removes the listener on unmount", () => {
+    const removeSpy = vi.spyOn(window, "removeEventListener");
+    const { unmount } = renderHook(() => useEventListener("resize", () => {}));
+
+    unmount();
+
+    expect(removeSpy).toHaveBeenCalledWith(
+      "resize",
+      expect.any(Function),
+      undefined,
+    );
+    removeSpy.mockRestore();
+  });
+
+  it("does not call the listener after unmount", () => {
+    const handler = vi.fn();
+    const { unmount } = renderHook(() => useEventListener("resize", handler));
+
+    unmount();
+    fireEvent(window, new Event("resize"));
+
+    expect(handler).not.toHaveBeenCalled();
   });
 });

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

@@ -1,24 +1,84 @@
-import { useEffect, useRef } from "react";
+import { type RefObject, useEffect } from "react";
+import { isBrowser, useLatestRef } from "../internal";
 
+type ListenableTarget = Window | Document | HTMLElement | MediaQueryList;
+
+type TargetArg<T extends ListenableTarget> = T | RefObject<T | null> | null;
+
+const resolveTarget = (
+  target: TargetArg<ListenableTarget> | undefined,
+): EventTarget | null => {
+  if (target == null) return isBrowser ? window : null;
+  if ("current" in target) return target.current;
+  return target;
+};
+
+/**
+ * Subscribe to a DOM event with automatic cleanup. The `listener` is read
+ * through an internal ref (handler-stable pattern), so passing an inline
+ * function never re-attaches the underlying listener on every render.
+ *
+ * The target is explicit and selected by overload:
+ * - omit it to listen on `window` (the default);
+ * - pass a `RefObject` or the element itself for an `HTMLElement`;
+ * - pass `document` for document-level events;
+ * - pass a `MediaQueryList` for media query changes.
+ *
+ * SSR-safe: the effect no-ops when there is no DOM.
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  type: K,
+  listener: (event: WindowEventMap[K]) => void,
+  target?: Window | RefObject<Window | null> | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  target: Document | RefObject<Document | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
 export function useEventListener<
   K extends keyof HTMLElementEventMap,
   T extends HTMLElement = HTMLElement,
 >(
   type: K,
-  listener: (this: T, ev: HTMLElementEventMap[K]) => void,
+  listener: (event: HTMLElementEventMap[K]) => void,
+  target: T | RefObject<T | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener<K extends keyof MediaQueryListEventMap>(
+  type: K,
+  listener: (event: MediaQueryListEventMap[K]) => void,
+  target: MediaQueryList | RefObject<MediaQueryList | null>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+export function useEventListener(
+  type: string,
+  listener: (event: Event) => void,
+  target?: TargetArg<ListenableTarget>,
   options?: boolean | AddEventListenerOptions,
-) {
-  const ref = useRef<T | null>(null);
+): void {
+  const listenerRef = useLatestRef(listener);
+  const optionsRef = useLatestRef(options);
+
+  const capture = typeof options === "boolean" ? options : options?.capture;
+  const once = typeof options === "object" ? options.once : undefined;
+  const passive = typeof options === "object" ? options.passive : undefined;
 
   useEffect(() => {
-    const target = ref.current ?? document;
+    if (!isBrowser) return;
 
-    target.addEventListener(type, listener as EventListener, options);
-    return () => {
-      target.removeEventListener(type, listener as EventListener, options);
+    const node = resolveTarget(target);
+    if (!node) return;
+
+    const handler = (event: Event) => {
+      listenerRef.current(event);
     };
-  }, [type, listener, options]);
 
-  return ref;
+    node.addEventListener(type, handler, optionsRef.current);
+    return () => {
+      node.removeEventListener(type, handler, optionsRef.current);
+    };
+  }, [type, target, capture, once, passive]);
 }
-

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

@@ -1,7 +1,12 @@
 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 {
+  FOCUS_SELECTOR,
+  findTabbableDescendants,
+  focusable,
+  tabbable,
+} from "./tabbable";
 import { useFocusTrap } from "./use-focus-trap";
 
 // ─── tabbable.ts ─────────────────────────────────────────────────────────────
@@ -151,7 +156,11 @@ describe("scopeTab", () => {
   });
 
   it("calls preventDefault when no tabbable descendants", () => {
-    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    const event = {
+      key: "Tab",
+      shiftKey: false,
+      preventDefault: vi.fn(),
+    } as any;
     scopeTab(container, event);
     expect(event.preventDefault).toHaveBeenCalledOnce();
   });
@@ -162,7 +171,11 @@ describe("scopeTab", () => {
     container.append(btn1, btn2);
     btn2.focus();
 
-    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    const event = {
+      key: "Tab",
+      shiftKey: false,
+      preventDefault: vi.fn(),
+    } as any;
     scopeTab(container, event);
 
     expect(event.preventDefault).toHaveBeenCalledOnce();
@@ -175,7 +188,11 @@ describe("scopeTab", () => {
     container.append(btn1, btn2);
     btn1.focus();
 
-    const event = { key: "Tab", shiftKey: true, preventDefault: vi.fn() } as any;
+    const event = {
+      key: "Tab",
+      shiftKey: true,
+      preventDefault: vi.fn(),
+    } as any;
     scopeTab(container, event);
 
     expect(event.preventDefault).toHaveBeenCalledOnce();
@@ -189,7 +206,11 @@ describe("scopeTab", () => {
     container.append(btn1, btn2, btn3);
     btn1.focus();
 
-    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    const event = {
+      key: "Tab",
+      shiftKey: false,
+      preventDefault: vi.fn(),
+    } as any;
     scopeTab(container, event);
 
     expect(event.preventDefault).not.toHaveBeenCalled();
@@ -206,7 +227,11 @@ describe("scopeTab", () => {
     container.append(btn, radio1, radio2);
     radio1.focus();
 
-    const event = { key: "Tab", shiftKey: false, preventDefault: vi.fn() } as any;
+    const event = {
+      key: "Tab",
+      shiftKey: false,
+      preventDefault: vi.fn(),
+    } as any;
     scopeTab(container, event);
 
     expect(event.preventDefault).toHaveBeenCalledOnce();

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

@@ -2,7 +2,9 @@ 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 {
+export function useFocusTrap(
+  active = true,
+): (instance: HTMLElement | null) => void {
   const ref = useRef<HTMLElement | null>(null);
 
   const focusNode = (node: HTMLElement) => {
@@ -74,4 +76,3 @@ export function useFocusTrap(active = true): (instance: HTMLElement | null) => v
 
   return setRef;
 }
-

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

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