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

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

@@ -1,14 +1,18 @@
-import { render, screen, waitFor } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { keyboard } from "../../utils/tests/keyboard";
-import { useHotkey, HotkeyOptions } from "../use-hotkey";
+import { getHotkeyHandler, type HotkeyOptions, useHotkey } from "../use-hotkey";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
 
 describe("useHotkey hook", () => {
   it("should be defined", () => {
     expect(useHotkey).toBeDefined();
   });
 
-  it("should call handler on keydown event", async () => {
+  it("calls handler on a matching keydown event", async () => {
     const handler = vi.fn();
     const TestComponent = () => {
       useHotkey("a", handler);
@@ -16,17 +20,14 @@ describe("useHotkey hook", () => {
     };
 
     render(<TestComponent />);
-
-    keyboard(document, {
-      key: "a",
-    });
+    keyboard(document, { key: "a" });
 
     await waitFor(() => {
-      expect(handler).toHaveBeenCalled();
+      expect(handler).toHaveBeenCalledTimes(1);
     });
   });
 
-  it("should call handler with correct key combination", async () => {
+  it("matches an exact key combination", async () => {
     const handler = vi.fn();
     const TestComponent = () => {
       useHotkey("ctrl+a", handler);
@@ -34,18 +35,29 @@ describe("useHotkey hook", () => {
     };
 
     render(<TestComponent />);
+    keyboard(document, { key: "a", ctrlKey: true });
 
-    keyboard(document, {
-      key: "a",
-      ctrlKey: true,
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
     });
+  });
+
+  it("rejects when an extra modifier is pressed", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("ctrl+a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+    keyboard(document, { key: "a", ctrlKey: true, shiftKey: true });
 
     await waitFor(() => {
-      expect(handler).toHaveBeenCalled();
+      expect(handler).not.toHaveBeenCalled();
     });
   });
 
-  it("should prevent default action if preventDefault is true", async () => {
+  it("calls preventDefault by default", async () => {
     const handler = vi.fn();
     const TestComponent = () => {
       useHotkey("b", handler);
@@ -53,7 +65,6 @@ describe("useHotkey hook", () => {
     };
 
     render(<TestComponent />);
-
     const event = new KeyboardEvent("keydown", { key: "b" });
     Object.defineProperty(event, "preventDefault", { value: vi.fn() });
     document.dispatchEvent(event);
@@ -63,7 +74,7 @@ describe("useHotkey hook", () => {
     });
   });
 
-  it("should not prevent default action if preventDefault is false", async () => {
+  it("does not call preventDefault when preventDefault is false", async () => {
     const handler = vi.fn();
     const options: HotkeyOptions = { preventDefault: false };
     const TestComponent = () => {
@@ -81,7 +92,7 @@ describe("useHotkey hook", () => {
     });
   });
 
-  it("should handle multiple keys", async () => {
+  it("shares one handler across an array of keys", async () => {
     const handler = vi.fn();
     const TestComponent = () => {
       useHotkey(["d", "e"], handler);
@@ -89,48 +100,289 @@ describe("useHotkey hook", () => {
     };
 
     render(<TestComponent />);
-
-    keyboard(document, {
-      key: "d",
-    });
-
-    keyboard(document, {
-      key: "e",
-    });
+    keyboard(document, { key: "d" });
+    keyboard(document, { key: "e" });
 
     await waitFor(() => {
       expect(handler).toHaveBeenCalledTimes(2);
     });
   });
 
-  it("does not call handler when watch=false", async () => {
+  it("does not call handler when watch is 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 () => {
+  it("listens on keyup when eventName is 'keyup'", async () => {
     const handler = vi.fn();
     const TestComponent = () => {
-      useHotkey("z", handler);
-      return <input data-testid="input" />;
+      useHotkey("g", handler, { eventName: "keyup" });
+      return null;
     };
+
     render(<TestComponent />);
 
-    const input = screen.getByTestId("input");
-    input.dispatchEvent(
-      new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+    keyboard(document, { key: "g" }, "keydown");
+    await waitFor(() => {
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    keyboard(document, { key: "g" }, "keyup");
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("array-of-tuples form", () => {
+    it("dispatches each binding independently", async () => {
+      const handlerA = vi.fn();
+      const handlerB = vi.fn();
+      const TestComponent = () => {
+        useHotkey([
+          ["a", handlerA],
+          ["b", handlerB],
+        ]);
+        return null;
+      };
+
+      render(<TestComponent />);
+      keyboard(document, { key: "b" });
+
+      await waitFor(() => {
+        expect(handlerB).toHaveBeenCalledTimes(1);
+        expect(handlerA).not.toHaveBeenCalled();
+      });
+    });
+
+    it("honors per-binding preventDefault override", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey([["a", handler, { preventDefault: false }]]);
+        return null;
+      };
+
+      render(<TestComponent />);
+      const event = new KeyboardEvent("keydown", { key: "a" });
+      Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+      document.dispatchEvent(event);
+
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+        expect(event.preventDefault).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("platform-aware mod", () => {
+    it("matches meta (⌘) and rejects ctrl on Apple", async () => {
+      vi.stubGlobal("navigator", { platform: "MacIntel" });
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("mod+k", handler);
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      keyboard(document, { key: "k", ctrlKey: true });
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+
+      keyboard(document, { key: "k", metaKey: true });
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    it("matches ctrl and rejects meta on non-Apple", async () => {
+      vi.stubGlobal("navigator", { platform: "Win32" });
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("mod+k", handler);
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      keyboard(document, { key: "k", metaKey: true });
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+
+      keyboard(document, { key: "k", ctrlKey: true });
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("tag and contentEditable suppression", () => {
+    it("does not fire when the event 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();
+      });
+    });
+
+    it("fires from an input when tagsToIgnore is empty", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("z", handler, { tagsToIgnore: [] });
+        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).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    it("fires from a contentEditable target when triggerOnContentEditable is true", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("z", handler, { triggerOnContentEditable: true });
+        return (
+          <div
+            contentEditable
+            data-testid="editable"
+            suppressContentEditableWarning
+          />
+        );
+      };
+
+      render(<TestComponent />);
+      const editable = screen.getByTestId("editable");
+      editable.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "z", bubbles: true }),
+      );
+
+      await waitFor(() => {
+        expect(handler).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("lifecycle", () => {
+    it("removes the document listener on unmount", async () => {
+      const handler = vi.fn();
+      const TestComponent = () => {
+        useHotkey("u", handler);
+        return null;
+      };
+
+      const { unmount } = render(<TestComponent />);
+      unmount();
+      keyboard(document, { key: "u" });
+
+      await waitFor(() => {
+        expect(handler).not.toHaveBeenCalled();
+      });
+    });
+
+    it("invokes the latest handler after a re-render without re-binding", async () => {
+      const first = vi.fn();
+      const second = vi.fn();
+      const TestComponent = ({ handler }: { handler: () => void }) => {
+        useHotkey("r", handler);
+        return null;
+      };
+
+      const { rerender } = render(<TestComponent handler={first} />);
+      rerender(<TestComponent handler={second} />);
+
+      keyboard(document, { key: "r" });
+
+      await waitFor(() => {
+        expect(second).toHaveBeenCalledTimes(1);
+        expect(first).not.toHaveBeenCalled();
+      });
+    });
+  });
+});
+
+describe("getHotkeyHandler", () => {
+  it("returns a handler that fires on a matching key", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["a", handler]])}
+      />
     );
 
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), { key: "a" });
+
     await waitFor(() => {
-      expect(handler).not.toHaveBeenCalled();
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("shares mod behavior (Ctrl+K on non-Apple)", async () => {
+    vi.stubGlobal("navigator", { platform: "Win32" });
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["mod+k", handler]])}
+      />
+    );
+
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), {
+      key: "k",
+      ctrlKey: true,
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("does NOT suppress the input tag it is attached to", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => (
+      <input
+        data-testid="scoped"
+        onKeyDown={getHotkeyHandler([["mod+enter", handler]])}
+      />
+    );
+
+    render(<TestComponent />);
+    fireEvent.keyDown(screen.getByTestId("scoped"), {
+      key: "Enter",
+      ctrlKey: true,
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
     });
   });
 });

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

@@ -1,33 +1,157 @@
-import { useCallback } from "react";
 import { useEventListener } from "../use-event-listener";
-import { createListener } from "./utils";
+import {
+  type HotkeyItem,
+  type HotkeyItemOptions,
+  type KeyboardEventLike,
+  matchAndRun,
+} from "./utils";
 
+export type { HotkeyItem, HotkeyItemOptions, KeyboardEventLike };
+
+/** A single key string or a list of key strings sharing one handler. */
 export type Keys = string | string[];
-export type HotkeyEventName = "keydown" | "keypress" | "keyup";
-export type HotkeyOptions = {
+
+/** Supported listener event names. `"keypress"` is removed in v2. */
+export type HotkeyEventName = "keydown" | "keyup";
+
+/**
+ * Options for the single-binding `useHotkey(keys, handler, options)` form.
+ * Combines hook-level concerns (`watch`, `eventName`, `tagsToIgnore`) with the
+ * per-binding behavior (`preventDefault`, `triggerOnContentEditable`).
+ */
+export type HotkeyOptions = HotkeyItemOptions & {
+  /** Listen while `true` (default). When `false`, no handler fires. */
   watch?: boolean;
+  /** DOM event to listen for. Default `"keydown"`. */
   eventName?: HotkeyEventName;
-  preventDefault?: boolean;
-  ignoreInputFields?: boolean;
+  /**
+   * Tag names whose events are ignored. Default
+   * `["INPUT", "TEXTAREA", "SELECT"]`. Pass `[]` to ignore nothing.
+   */
+  tagsToIgnore?: string[];
 };
 
+const DEFAULT_TAGS_TO_IGNORE = ["INPUT", "TEXTAREA", "SELECT"];
+
+/**
+ * Bind one or more keyboard shortcuts at the `document` level.
+ *
+ * Two forms are supported:
+ *
+ * 1. Single binding — `useHotkey(keys, handler, options?)` where `keys` is a
+ *    string or string array sharing one handler.
+ * 2. Multiple bindings — `useHotkey(bindings)` where `bindings` is a list of
+ *    `[key, handler, options?]` tuples, each dispatched independently.
+ *
+ * Matching is strict: every required modifier (`shift`/`ctrl`/`alt`/`meta`)
+ * must be pressed and no other modifier may be. `mod` resolves to `meta` (⌘)
+ * on Apple platforms and `ctrl` elsewhere. Events originating in `tagsToIgnore`
+ * tags (or contentEditable regions) are suppressed unless opted out.
+ *
+ * The handler is read through a ref, so passing an inline function never
+ * re-attaches the underlying listener. SSR-safe: no DOM access on the server.
+ *
+ * @example
+ * useHotkey("mod+k", () => openPalette());
+ * useHotkey([["a", onA], ["b", onB, { preventDefault: false }]]);
+ */
 export function useHotkey(
-  keys: string | string[],
-  handler: (event: KeyboardEvent) => void,
-  options: HotkeyOptions = {},
-) {
+  keys: Keys,
+  handler: (event: KeyboardEventLike) => void,
+  options?: HotkeyOptions,
+): void;
+export function useHotkey(
+  bindings: HotkeyItem[],
+  options?: HotkeyOptions,
+): void;
+export function useHotkey(
+  keysOrBindings: Keys | HotkeyItem[],
+  handlerOrOptions?: ((event: KeyboardEventLike) => void) | HotkeyOptions,
+  maybeOptions?: HotkeyOptions,
+): void {
+  const isArrayForm =
+    Array.isArray(keysOrBindings) && typeof handlerOrOptions !== "function";
+
+  const options: HotkeyOptions = isArrayForm
+    ? ((handlerOrOptions as HotkeyOptions | undefined) ?? {})
+    : (maybeOptions ?? {});
+
   const {
     eventName = "keydown",
-    preventDefault = true,
-    ignoreInputFields = true,
     watch = true,
+    preventDefault = true,
+    triggerOnContentEditable = false,
+    tagsToIgnore = DEFAULT_TAGS_TO_IGNORE,
   } = options;
 
-  const listener = useCallback(
-    createListener(keys, handler, preventDefault, ignoreInputFields, watch),
-    [keys, handler, preventDefault, ignoreInputFields, watch],
-  );
+  const items: HotkeyItem[] = isArrayForm
+    ? (keysOrBindings as HotkeyItem[])
+    : normalizeSingle(
+        keysOrBindings as Keys,
+        handlerOrOptions as (event: KeyboardEventLike) => void,
+        { preventDefault, triggerOnContentEditable },
+      );
 
-  return useEventListener(eventName, listener);
+  const listener = (event: KeyboardEvent) => {
+    if (!watch) return;
+    matchAndRun(event, items, tagsToIgnore);
+  };
+
+  useEventListener(eventName, listener, document);
 }
 
+const normalizeSingle = (
+  keys: Keys,
+  handler: (event: KeyboardEventLike) => void,
+  perItemOptions: HotkeyItemOptions,
+): HotkeyItem[] => {
+  const keyList = Array.isArray(keys) ? keys : [keys];
+  return keyList.map((key) => [key, handler, perItemOptions]);
+};
+
+/**
+ * Build an element-scoped `onKeyDown` handler. Shares the same
+ * strict-modifier and `mod` behavior as {@link useHotkey}.
+ *
+ * Two forms are supported:
+ *
+ * 1. Single binding — `getHotkeyHandler(keys, handler, options?)`.
+ * 2. Multiple bindings — `getHotkeyHandler(bindings)` where `bindings` is a
+ *    list of `[key, handler, options?]` tuples.
+ *
+ * Because it is attached to an element's `onKeyDown`, it applies NO tag
+ * suppression — it has no `tagsToIgnore` and matches regardless of the target
+ * tag (including the `<input>` it is attached to).
+ *
+ * @example
+ * <input onKeyDown={getHotkeyHandler("mod+enter", submit)} />
+ * <input onKeyDown={getHotkeyHandler([["mod+enter", submit], ["escape", cancel]])} />
+ */
+export function getHotkeyHandler(
+  keys: Keys,
+  handler: (event: KeyboardEventLike) => void,
+  options?: HotkeyItemOptions,
+): (event: KeyboardEventLike) => void;
+export function getHotkeyHandler(
+  bindings: HotkeyItem[],
+): (event: KeyboardEventLike) => void;
+export function getHotkeyHandler(
+  keysOrBindings: Keys | HotkeyItem[],
+  handler?: (event: KeyboardEventLike) => void,
+  options?: HotkeyItemOptions,
+): (event: KeyboardEventLike) => void {
+  const isArrayForm =
+    Array.isArray(keysOrBindings) && typeof handler !== "function";
+
+  const bindings: HotkeyItem[] = isArrayForm
+    ? (keysOrBindings as HotkeyItem[])
+    : normalizeSingle(
+        keysOrBindings as Keys,
+        handler as (event: KeyboardEventLike) => void,
+        options ?? {},
+      );
+
+  return (event: KeyboardEventLike) => {
+    matchAndRun(event, bindings, []);
+  };
+}

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

@@ -1,3 +1,8 @@
-export * from "./create-hotkey-listener";
-export * from "./is-input-field";
-export * from "./match-key-modifiers";
+export { shouldIgnoreEvent } from "./is-input-field";
+export type {
+  HotkeyItem,
+  HotkeyItemOptions,
+  KeyboardEventLike,
+} from "./match-and-run";
+export { matchAndRun } from "./match-and-run";
+export { getKeyModifiers, matchKeyModifiers } from "./match-key-modifiers";

package/src/hooks/use-hotkey/utils/is-input-field.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from "vitest";
+import { shouldIgnoreEvent } from "./is-input-field";
+import type { KeyboardEventLike } from "./match-and-run";
+
+const DEFAULT_IGNORE = ["INPUT", "TEXTAREA", "SELECT"];
+
+const makeEvent = (target: EventTarget | null): KeyboardEventLike => ({
+  key: "k",
+  shiftKey: false,
+  ctrlKey: false,
+  altKey: false,
+  metaKey: false,
+  target,
+  preventDefault: vi.fn(),
+});
+
+const makeTarget = (props: {
+  tagName?: string;
+  isContentEditable?: boolean;
+}): EventTarget =>
+  ({
+    tagName: props.tagName,
+    isContentEditable: props.isContentEditable ?? false,
+  }) as unknown as EventTarget;
+
+describe("shouldIgnoreEvent", () => {
+  it("ignores targets whose tag is in the list", () => {
+    const event = makeEvent(makeTarget({ tagName: "INPUT" }));
+    expect(shouldIgnoreEvent(event, DEFAULT_IGNORE, false)).toBe(true);
+  });
+
+  it("ignores SELECT and TEXTAREA by default", () => {
+    expect(
+      shouldIgnoreEvent(
+        makeEvent(makeTarget({ tagName: "SELECT" })),
+        DEFAULT_IGNORE,
+        false,
+      ),
+    ).toBe(true);
+    expect(
+      shouldIgnoreEvent(
+        makeEvent(makeTarget({ tagName: "TEXTAREA" })),
+        DEFAULT_IGNORE,
+        false,
+      ),
+    ).toBe(true);
+  });
+
+  it("does not ignore tags outside the list", () => {
+    const event = makeEvent(makeTarget({ tagName: "BUTTON" }));
+    expect(shouldIgnoreEvent(event, DEFAULT_IGNORE, false)).toBe(false);
+  });
+
+  it("ignores contentEditable when triggerOnContentEditable is false", () => {
+    const event = makeEvent(
+      makeTarget({ tagName: "DIV", isContentEditable: true }),
+    );
+    expect(shouldIgnoreEvent(event, DEFAULT_IGNORE, false)).toBe(true);
+  });
+
+  it("does not ignore contentEditable when triggerOnContentEditable is true", () => {
+    const event = makeEvent(
+      makeTarget({ tagName: "DIV", isContentEditable: true }),
+    );
+    expect(shouldIgnoreEvent(event, DEFAULT_IGNORE, true)).toBe(false);
+  });
+
+  it("ignores nothing when the list is empty and not contentEditable", () => {
+    const event = makeEvent(makeTarget({ tagName: "INPUT" }));
+    expect(shouldIgnoreEvent(event, [], false)).toBe(false);
+  });
+
+  it("returns false when there is no target", () => {
+    expect(shouldIgnoreEvent(makeEvent(null), DEFAULT_IGNORE, false)).toBe(
+      false,
+    );
+  });
+});