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

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

@@ -1,14 +1,35 @@
-export const isInputField = (element: HTMLElement): boolean => {
-  return (
-    element.tagName === "INPUT" ||
-    element.tagName === "TEXTAREA" ||
-    element.isContentEditable
-  );
-};
+import type { KeyboardEventLike } from "./match-and-run";
 
+/**
+ * Decides whether a keyboard event should be suppressed because it originated
+ * inside a form control or editable region.
+ *
+ * - Suppressed when the target's tag name is in `tagsToIgnore` (case-sensitive
+ *   uppercase tag names, e.g. `["INPUT","TEXTAREA","SELECT"]`). An empty list
+ *   suppresses nothing.
+ * - Suppressed when the target is `contentEditable`, unless
+ *   `triggerOnContentEditable` is `true`.
+ */
 export const shouldIgnoreEvent = (
-  event: KeyboardEvent,
-  ignoreInputFields: boolean,
+  event: KeyboardEventLike,
+  tagsToIgnore: string[],
+  triggerOnContentEditable: boolean,
 ): boolean => {
-  return ignoreInputFields && isInputField(event.target as HTMLElement);
+  const target = event.target as
+    | (Element & { isContentEditable?: boolean })
+    | null;
+  if (!target) return false;
+
+  if (
+    typeof target.tagName === "string" &&
+    tagsToIgnore.includes(target.tagName)
+  ) {
+    return true;
+  }
+
+  if (!triggerOnContentEditable && target.isContentEditable === true) {
+    return true;
+  }
+
+  return false;
 };

package/src/hooks/use-hotkey/utils/match-and-run.test.ts

@@ -0,0 +1,203 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { HotkeyItem, KeyboardEventLike } from "./match-and-run";
+import { matchAndRun } from "./match-and-run";
+
+const DEFAULT_IGNORE = ["INPUT", "TEXTAREA", "SELECT"];
+
+type EventOverrides = Partial<
+  Pick<KeyboardEventLike, "shiftKey" | "ctrlKey" | "altKey" | "metaKey">
+> & {
+  key: string;
+  target?: EventTarget | null;
+};
+
+const makeEvent = (overrides: EventOverrides): KeyboardEventLike => ({
+  key: overrides.key,
+  shiftKey: overrides.shiftKey ?? false,
+  ctrlKey: overrides.ctrlKey ?? false,
+  altKey: overrides.altKey ?? false,
+  metaKey: overrides.metaKey ?? false,
+  target: overrides.target ?? null,
+  preventDefault: vi.fn(),
+});
+
+const makeTarget = (props: {
+  tagName?: string;
+  isContentEditable?: boolean;
+}): EventTarget =>
+  ({
+    tagName: props.tagName,
+    isContentEditable: props.isContentEditable ?? false,
+  }) as unknown as EventTarget;
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("matchAndRun", () => {
+  it("calls the handler when a single binding matches the main key", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({ key: "k" });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(event);
+  });
+
+  it("dispatches each matching binding independently", () => {
+    const handlerA = vi.fn();
+    const handlerB = vi.fn();
+    const items: HotkeyItem[] = [
+      ["a", handlerA],
+      ["b", handlerB],
+    ];
+
+    matchAndRun(makeEvent({ key: "b" }), items, DEFAULT_IGNORE);
+
+    expect(handlerB).toHaveBeenCalledTimes(1);
+    expect(handlerA).not.toHaveBeenCalled();
+  });
+
+  it("matches only the exact modifier set (extra modifier rejects)", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["ctrl+k", handler]];
+
+    matchAndRun(makeEvent({ key: "k", ctrlKey: true }), items, DEFAULT_IGNORE);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    handler.mockClear();
+    matchAndRun(
+      makeEvent({ key: "k", ctrlKey: true, shiftKey: true }),
+      items,
+      DEFAULT_IGNORE,
+    );
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("resolves mod to meta on Apple and rejects the opposite (ctrl)", () => {
+    vi.stubGlobal("navigator", { platform: "MacIntel" });
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["mod+k", handler]];
+
+    matchAndRun(makeEvent({ key: "k", metaKey: true }), items, DEFAULT_IGNORE);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    handler.mockClear();
+    matchAndRun(makeEvent({ key: "k", ctrlKey: true }), items, DEFAULT_IGNORE);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("resolves mod to ctrl on non-Apple and rejects the opposite (meta)", () => {
+    vi.stubGlobal("navigator", { platform: "Win32" });
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["mod+k", handler]];
+
+    matchAndRun(makeEvent({ key: "k", ctrlKey: true }), items, DEFAULT_IGNORE);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    handler.mockClear();
+    matchAndRun(makeEvent({ key: "k", metaKey: true }), items, DEFAULT_IGNORE);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("ignores events whose target tag is in tagsToIgnore", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({
+      key: "k",
+      target: makeTarget({ tagName: "INPUT" }),
+    });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("ignores SELECT targets by default", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({
+      key: "k",
+      target: makeTarget({ tagName: "SELECT" }),
+    });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("ignores contentEditable targets by default", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({
+      key: "k",
+      target: makeTarget({ tagName: "DIV", isContentEditable: true }),
+    });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("fires on contentEditable when triggerOnContentEditable is true", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [
+      ["k", handler, { triggerOnContentEditable: true }],
+    ];
+    const event = makeEvent({
+      key: "k",
+      target: makeTarget({ tagName: "DIV", isContentEditable: true }),
+    });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores nothing when tagsToIgnore is empty (INPUT still fires)", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({
+      key: "k",
+      target: makeTarget({ tagName: "INPUT" }),
+    });
+
+    matchAndRun(event, items, []);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls preventDefault by default before the handler", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({ key: "k" });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(event.preventDefault).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call preventDefault when the binding opts out", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler, { preventDefault: false }]];
+    const event = makeEvent({ key: "k" });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("does not fire when no binding matches", () => {
+    const handler = vi.fn();
+    const items: HotkeyItem[] = [["k", handler]];
+    const event = makeEvent({ key: "j" });
+
+    matchAndRun(event, items, DEFAULT_IGNORE);
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/use-hotkey/utils/match-and-run.ts

@@ -0,0 +1,62 @@
+import { shouldIgnoreEvent } from "./is-input-field";
+import { matchKeyModifiers } from "./match-key-modifiers";
+
+/**
+ * Structural subset of a keyboard event used by the matching core. Both the
+ * DOM `KeyboardEvent` (used by `useHotkey`) and React's synthetic
+ * `KeyboardEvent` (used by `getHotkeyHandler`) satisfy this shape, so the core
+ * stays React-free and requires no casts at either call site.
+ */
+export type KeyboardEventLike = Pick<
+  KeyboardEvent,
+  "key" | "shiftKey" | "ctrlKey" | "altKey" | "metaKey"
+> & {
+  target: EventTarget | null;
+  preventDefault: () => void;
+};
+
+/**
+ * Per-binding options. Defaults: `preventDefault` true,
+ * `triggerOnContentEditable` false, `tagsToIgnore` is resolved by the caller
+ * (`useHotkey` passes its configured list; `getHotkeyHandler` passes `[]`).
+ */
+export type HotkeyItemOptions = {
+  preventDefault?: boolean;
+  triggerOnContentEditable?: boolean;
+};
+
+/** A single hotkey binding: `[key, handler, options?]`. */
+export type HotkeyItem = [
+  key: string,
+  handler: (event: KeyboardEventLike) => void,
+  options?: HotkeyItemOptions,
+];
+
+/**
+ * The shared matching engine. For each binding it:
+ * 1. skips the event if the target should be ignored (tag / contentEditable);
+ * 2. parses the binding key (resolving `mod` to `meta`/`ctrl` per platform);
+ * 3. strictly matches the main key and all four modifiers;
+ * 4. calls `preventDefault` (unless opted out) then the handler.
+ *
+ * `tagsToIgnore` is a core parameter: `useHotkey` passes its configured list,
+ * while `getHotkeyHandler` passes `[]` (element-scoped, so it ignores nothing).
+ */
+export const matchAndRun = (
+  event: KeyboardEventLike,
+  items: HotkeyItem[],
+  tagsToIgnore: string[],
+): void => {
+  for (const [key, handler, options] of items) {
+    const triggerOnContentEditable = options?.triggerOnContentEditable ?? false;
+    if (shouldIgnoreEvent(event, tagsToIgnore, triggerOnContentEditable)) {
+      continue;
+    }
+
+    if (!matchKeyModifiers(event, key)) continue;
+
+    const preventDefault = options?.preventDefault ?? true;
+    if (preventDefault) event.preventDefault();
+    handler(event);
+  }
+};

package/src/hooks/use-hotkey/utils/match-key-modifiers.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { KeyboardEventLike } from "./match-and-run";
+import { matchKeyModifiers } from "./match-key-modifiers";
+
+const makeEvent = (
+  overrides: Partial<KeyboardEventLike> & { key: string },
+): KeyboardEventLike => ({
+  key: overrides.key,
+  shiftKey: overrides.shiftKey ?? false,
+  ctrlKey: overrides.ctrlKey ?? false,
+  altKey: overrides.altKey ?? false,
+  metaKey: overrides.metaKey ?? false,
+  target: null,
+  preventDefault: vi.fn(),
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("matchKeyModifiers", () => {
+  it("matches a bare key with no modifiers", () => {
+    expect(matchKeyModifiers(makeEvent({ key: "k" }), "k")).toBe(true);
+  });
+
+  it("is case-insensitive on the main key", () => {
+    expect(matchKeyModifiers(makeEvent({ key: "K" }), "k")).toBe(true);
+  });
+
+  it("requires the exact modifier set", () => {
+    expect(
+      matchKeyModifiers(makeEvent({ key: "k", ctrlKey: true }), "ctrl+k"),
+    ).toBe(true);
+    expect(
+      matchKeyModifiers(
+        makeEvent({ key: "k", ctrlKey: true, shiftKey: true }),
+        "ctrl+k",
+      ),
+    ).toBe(false);
+  });
+
+  it("rejects when a required modifier is missing", () => {
+    expect(matchKeyModifiers(makeEvent({ key: "k" }), "ctrl+k")).toBe(false);
+  });
+
+  it("resolves mod to meta on Apple and requires ctrl absent", () => {
+    vi.stubGlobal("navigator", { platform: "MacIntel" });
+    expect(
+      matchKeyModifiers(makeEvent({ key: "k", metaKey: true }), "mod+k"),
+    ).toBe(true);
+    expect(
+      matchKeyModifiers(makeEvent({ key: "k", ctrlKey: true }), "mod+k"),
+    ).toBe(false);
+  });
+
+  it("resolves mod to ctrl on non-Apple and requires meta absent", () => {
+    vi.stubGlobal("navigator", { platform: "Win32" });
+    expect(
+      matchKeyModifiers(makeEvent({ key: "k", ctrlKey: true }), "mod+k"),
+    ).toBe(true);
+    expect(
+      matchKeyModifiers(makeEvent({ key: "k", metaKey: true }), "mod+k"),
+    ).toBe(false);
+  });
+});

package/src/hooks/use-hotkey/utils/match-key-modifiers.ts

@@ -1,25 +1,52 @@
-export const getKeyModifiers = (key: string) => {
+import { isAppleDevice } from "../../internal";
+import type { KeyboardEventLike } from "./match-and-run";
+
+type ParsedKey = {
+  mainKey: string;
+  shift: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  meta: boolean;
+};
+
+/**
+ * Parses a hotkey string (e.g. `"mod+shift+k"`) into its main key and the
+ * exact set of required modifiers. `mod` resolves to `meta` on Apple platforms
+ * and `ctrl` elsewhere; the opposite modifier is then required to be absent
+ * (it stays `false` here, enforcing the strict exact-match rule).
+ */
+export const getKeyModifiers = (key: string): ParsedKey => {
   const parts = key.toLowerCase().split("+");
-  const mainKey = parts.pop()!;
+  const mainKey = parts.pop() ?? "";
+
+  const hasMod = parts.includes("mod");
+  const modIsMeta = hasMod && isAppleDevice();
+  const modIsCtrl = hasMod && !isAppleDevice();
+
   return {
     mainKey,
-    isShift: parts.includes("shift"),
-    isCtrl: parts.includes("ctrl"),
-    isAlt: parts.includes("alt"),
-    isMeta: parts.includes("meta"),
+    shift: parts.includes("shift"),
+    ctrl: parts.includes("ctrl") || modIsCtrl,
+    alt: parts.includes("alt"),
+    meta: parts.includes("meta") || modIsMeta,
   };
 };
 
+/**
+ * Returns `true` only when the event's main key matches AND every modifier
+ * state (shift/ctrl/alt/meta) exactly equals the parsed requirement. This is a
+ * strict match: any extra or missing modifier rejects the binding.
+ */
 export const matchKeyModifiers = (
-  event: KeyboardEvent,
+  event: KeyboardEventLike,
   key: string,
 ): boolean => {
-  const { mainKey, isShift, isCtrl, isAlt, isMeta } = getKeyModifiers(key);
+  const { mainKey, shift, ctrl, alt, meta } = getKeyModifiers(key);
   return (
     event.key.toLowerCase() === mainKey &&
-    event.shiftKey === isShift &&
-    event.ctrlKey === isCtrl &&
-    event.altKey === isAlt &&
-    event.metaKey === isMeta
+    event.shiftKey === shift &&
+    event.ctrlKey === ctrl &&
+    event.altKey === alt &&
+    event.metaKey === meta
   );
 };