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

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

@@ -0,0 +1,157 @@
+import { useEventListener } from "../use-event-listener";
+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[];
+
+/** 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;
+  /**
+   * 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: 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",
+    watch = true,
+    preventDefault = true,
+    triggerOnContentEditable = false,
+    tagsToIgnore = DEFAULT_TAGS_TO_IGNORE,
+  } = options;
+
+  const items: HotkeyItem[] = isArrayForm
+    ? (keysOrBindings as HotkeyItem[])
+    : normalizeSingle(
+        keysOrBindings as Keys,
+        handlerOrOptions as (event: KeyboardEventLike) => void,
+        { preventDefault, triggerOnContentEditable },
+      );
+
+  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

@@ -0,0 +1,8 @@
+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,
+    );
+  });
+});

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

@@ -0,0 +1,35 @@
+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: KeyboardEventLike,
+  tagsToIgnore: string[],
+  triggerOnContentEditable: boolean,
+): boolean => {
+  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

@@ -0,0 +1,52 @@
+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 hasMod = parts.includes("mod");
+  const modIsMeta = hasMod && isAppleDevice();
+  const modIsCtrl = hasMod && !isAppleDevice();
+
+  return {
+    mainKey,
+    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: KeyboardEventLike,
+  key: string,
+): boolean => {
+  const { mainKey, shift, ctrl, alt, meta } = getKeyModifiers(key);
+  return (
+    event.key.toLowerCase() === mainKey &&
+    event.shiftKey === shift &&
+    event.ctrlKey === ctrl &&
+    event.altKey === alt &&
+    event.metaKey === meta
+  );
+};

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

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