@tanstack/hotkeys 0.7.1 → 0.9.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_hotkeys.png" alt="TanStack Hotkeys" />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/hotkeys.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/hotkeys.png"
+      alt="TanStack Hotkeys"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />

package/dist/{manager.utils.js → _event-target.cjs}

@@ -1,25 +1,5 @@
-//#region src/manager.utils.ts
-/**
-* Default options for hotkey/sequence registration.
-* Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
-*/
-const defaultHotkeyOptions = {
-	preventDefault: true,
-	stopPropagation: true,
-	eventType: "keydown",
-	enabled: true,
-	ignoreInputs: true,
-	conflictBehavior: "warn"
-};
-/**
-* Computes the default ignoreInputs value based on the hotkey.
-* Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
-*/
-function getDefaultIgnoreInputs(parsedHotkey) {
-	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
-	if (parsedHotkey.key === "Escape") return false;
-	return true;
-}
+
+//#region src/_event-target.ts
 /**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
@@ -86,24 +66,8 @@ function isEventForTarget(event, target) {
 	}
 	return false;
 }
-/**
-* Handles conflicts between registrations based on conflict behavior.
-*
-* @param conflictingId - The ID of the conflicting registration
-* @param keyDisplay - Display string for the conflicting key/sequence (for error messages)
-* @param conflictBehavior - How to handle the conflict
-* @param unregister - Function to unregister by ID
-*/
-function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
-	if (conflictBehavior === "allow") return;
-	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
-		return;
-	}
-	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
-	unregister(conflictingId);
-}
 
 //#endregion
-export { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, isEventForTarget, isInputElement, shouldIgnoreInputEvent };
-//# sourceMappingURL=manager.utils.js.map
+exports.isEventForTarget = isEventForTarget;
+exports.shouldIgnoreInputEvent = shouldIgnoreInputEvent;
+//# sourceMappingURL=_event-target.cjs.map

package/dist/_event-target.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_event-target.cjs","names":[],"sources":["../src/_event-target.ts"],"sourcesContent":["/**\n * Checks if an element is an input-like element that should be ignored for hotkeys.\n *\n * This includes:\n * - HTMLInputElement (all input types except button, submit, reset)\n * - HTMLTextAreaElement\n * - HTMLSelectElement\n * - Elements with contentEditable enabled\n *\n * Button-type inputs (button, submit, reset) are excluded so hotkeys like\n * Mod+S and Escape fire when the user has tabbed to a form button.\n */\nexport function isInputElement(element: EventTarget | null): boolean {\n  if (!element) {\n    return false\n  }\n\n  if (element instanceof HTMLInputElement) {\n    const type = element.type.toLowerCase()\n    if (type === 'button' || type === 'submit' || type === 'reset') {\n      return false\n    }\n    return true\n  }\n\n  if (\n    element instanceof HTMLTextAreaElement ||\n    element instanceof HTMLSelectElement\n  ) {\n    return true\n  }\n\n  // Check for contenteditable elements (includes \"true\", \"\", \"plaintext-only\",\n  // and inherited contenteditable from ancestor elements)\n  if (element instanceof HTMLElement && element.isContentEditable) {\n    return true\n  }\n\n  return false\n}\n\n/**\n * Returns the focused element for the document associated with where hotkey\n * listeners are attached (listener root). Use this instead of the global\n * `document.activeElement` so registrations scoped to an iframe (or another\n * document) read focus from the correct tree.\n */\nexport function getActiveElementForListenerTarget(\n  target: HTMLElement | Document | Window,\n): Element | null {\n  if (typeof document === 'undefined') {\n    return null\n  }\n\n  // Document first (nodeType covers environments where `document instanceof Document` is false)\n  if (\n    (typeof Document !== 'undefined' && target instanceof Document) ||\n    (typeof Node !== 'undefined' &&\n      (target as Node).nodeType === Node.DOCUMENT_NODE)\n  ) {\n    return (target as Document).activeElement\n  }\n\n  if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {\n    return target.ownerDocument.activeElement ?? null\n  }\n\n  // Window (global or iframe): avoid relying on `instanceof Window` alone (test DOM quirks)\n  return (target as Window).document.activeElement ?? null\n}\n\n/**\n * Returns whether an event should be ignored because it originated from an\n * input-like element other than the registration target.\n *\n * This checks:\n * - the currently focused element for the listener target\n * - the event's composed path (for shadow DOM)\n * - the event target as a final fallback\n */\nexport function shouldIgnoreInputEvent(\n  event: KeyboardEvent,\n  listenerTarget: HTMLElement | Document | Window,\n  registrationTarget: HTMLElement | Document | Window,\n): boolean {\n  const focused = getActiveElementForListenerTarget(listenerTarget)\n  if (focused && isInputElement(focused) && focused !== registrationTarget) {\n    return true\n  }\n\n  if (\n    event\n      .composedPath()\n      .some(\n        (element) => isInputElement(element) && element !== registrationTarget,\n      )\n  ) {\n    return true\n  }\n\n  return isInputElement(event.target) && event.target !== registrationTarget\n}\n\n/**\n * Checks if an event is for the given target (originated from or bubbled to it).\n *\n * For document/window targets, also accepts document.documentElement as currentTarget\n * to handle Brave and other browsers where currentTarget may be documentElement\n * instead of document when listeners are attached to document.\n */\nexport function isEventForTarget(\n  event: KeyboardEvent,\n  target: HTMLElement | Document | Window,\n): boolean {\n  // For Document and Window, verify that our handler was indeed called for this target.\n  //\n  // Browser compatibility note:\n  // Per the DOM spec, event.currentTarget should equal the element the listener was\n  // attached to. However, some Chromium-based browsers (notably Brave) exhibit\n  // non-standard behavior where event.currentTarget is set to document.documentElement\n  // (<html>) instead of document when a listener is attached to document.\n  // This may be related to privacy/fingerprinting protections.\n  //\n  // To ensure cross-browser compatibility, we accept both the expected target\n  // and document.documentElement as valid currentTarget values.\n  // See: https://dom.spec.whatwg.org/#dom-event-currenttarget\n  if (target === document || target === window) {\n    return (\n      event.currentTarget === target ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For Window, accept window, document, or document.documentElement (browser quirks)\n  if (target === window) {\n    return (\n      event.currentTarget === window ||\n      event.currentTarget === document ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For HTMLElement, check if event originated from or bubbled to the element\n  if (target instanceof HTMLElement) {\n    // Check if the event's currentTarget is the target (capturing/bubbling)\n    if (event.currentTarget === target) {\n      return true\n    }\n\n    // Check if the event's target is a descendant of our target\n    if (event.target instanceof Node && target.contains(event.target)) {\n      return true\n    }\n  }\n\n  return false\n}\n"],"mappings":";;;;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAsC;AACnE,KAAI,CAAC,QACH,QAAO;AAGT,KAAI,mBAAmB,kBAAkB;EACvC,MAAM,OAAO,QAAQ,KAAK,aAAa;AACvC,MAAI,SAAS,YAAY,SAAS,YAAY,SAAS,QACrD,QAAO;AAET,SAAO;;AAGT,KACE,mBAAmB,uBACnB,mBAAmB,kBAEnB,QAAO;AAKT,KAAI,mBAAmB,eAAe,QAAQ,kBAC5C,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,kCACd,QACgB;AAChB,KAAI,OAAO,aAAa,YACtB,QAAO;AAIT,KACG,OAAO,aAAa,eAAe,kBAAkB,YACrD,OAAO,SAAS,eACd,OAAgB,aAAa,KAAK,cAErC,QAAQ,OAAoB;AAG9B,KAAI,OAAO,gBAAgB,eAAe,kBAAkB,YAC1D,QAAO,OAAO,cAAc,iBAAiB;AAI/C,QAAQ,OAAkB,SAAS,iBAAiB;;;;;;;;;;;AAYtD,SAAgB,uBACd,OACA,gBACA,oBACS;CACT,MAAM,UAAU,kCAAkC,eAAe;AACjE,KAAI,WAAW,eAAe,QAAQ,IAAI,YAAY,mBACpD,QAAO;AAGT,KACE,MACG,cAAc,CACd,MACE,YAAY,eAAe,QAAQ,IAAI,YAAY,mBACrD,CAEH,QAAO;AAGT,QAAO,eAAe,MAAM,OAAO,IAAI,MAAM,WAAW;;;;;;;;;AAU1D,SAAgB,iBACd,OACA,QACS;AAaT,KAAI,WAAW,YAAY,WAAW,OACpC,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,WAAW,OACb,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,YACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,kBAAkB,aAAa;AAEjC,MAAI,MAAM,kBAAkB,OAC1B,QAAO;AAIT,MAAI,MAAM,kBAAkB,QAAQ,OAAO,SAAS,MAAM,OAAO,CAC/D,QAAO;;AAIX,QAAO"}

package/dist/{manager.utils.cjs → _event-target.js}

@@ -1,26 +1,4 @@
-
-//#region src/manager.utils.ts
-/**
-* Default options for hotkey/sequence registration.
-* Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
-*/
-const defaultHotkeyOptions = {
-	preventDefault: true,
-	stopPropagation: true,
-	eventType: "keydown",
-	enabled: true,
-	ignoreInputs: true,
-	conflictBehavior: "warn"
-};
-/**
-* Computes the default ignoreInputs value based on the hotkey.
-* Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
-*/
-function getDefaultIgnoreInputs(parsedHotkey) {
-	if (parsedHotkey.ctrl || parsedHotkey.meta) return false;
-	if (parsedHotkey.key === "Escape") return false;
-	return true;
-}
+//#region src/_event-target.ts
 /**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
@@ -87,29 +65,7 @@ function isEventForTarget(event, target) {
 	}
 	return false;
 }
-/**
-* Handles conflicts between registrations based on conflict behavior.
-*
-* @param conflictingId - The ID of the conflicting registration
-* @param keyDisplay - Display string for the conflicting key/sequence (for error messages)
-* @param conflictBehavior - How to handle the conflict
-* @param unregister - Function to unregister by ID
-*/
-function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
-	if (conflictBehavior === "allow") return;
-	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
-		return;
-	}
-	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
-	unregister(conflictingId);
-}
 
 //#endregion
-exports.defaultHotkeyOptions = defaultHotkeyOptions;
-exports.getDefaultIgnoreInputs = getDefaultIgnoreInputs;
-exports.handleConflict = handleConflict;
-exports.isEventForTarget = isEventForTarget;
-exports.isInputElement = isInputElement;
-exports.shouldIgnoreInputEvent = shouldIgnoreInputEvent;
-//# sourceMappingURL=manager.utils.cjs.map
+export { isEventForTarget, shouldIgnoreInputEvent };
+//# sourceMappingURL=_event-target.js.map

package/dist/_event-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_event-target.js","names":[],"sources":["../src/_event-target.ts"],"sourcesContent":["/**\n * Checks if an element is an input-like element that should be ignored for hotkeys.\n *\n * This includes:\n * - HTMLInputElement (all input types except button, submit, reset)\n * - HTMLTextAreaElement\n * - HTMLSelectElement\n * - Elements with contentEditable enabled\n *\n * Button-type inputs (button, submit, reset) are excluded so hotkeys like\n * Mod+S and Escape fire when the user has tabbed to a form button.\n */\nexport function isInputElement(element: EventTarget | null): boolean {\n  if (!element) {\n    return false\n  }\n\n  if (element instanceof HTMLInputElement) {\n    const type = element.type.toLowerCase()\n    if (type === 'button' || type === 'submit' || type === 'reset') {\n      return false\n    }\n    return true\n  }\n\n  if (\n    element instanceof HTMLTextAreaElement ||\n    element instanceof HTMLSelectElement\n  ) {\n    return true\n  }\n\n  // Check for contenteditable elements (includes \"true\", \"\", \"plaintext-only\",\n  // and inherited contenteditable from ancestor elements)\n  if (element instanceof HTMLElement && element.isContentEditable) {\n    return true\n  }\n\n  return false\n}\n\n/**\n * Returns the focused element for the document associated with where hotkey\n * listeners are attached (listener root). Use this instead of the global\n * `document.activeElement` so registrations scoped to an iframe (or another\n * document) read focus from the correct tree.\n */\nexport function getActiveElementForListenerTarget(\n  target: HTMLElement | Document | Window,\n): Element | null {\n  if (typeof document === 'undefined') {\n    return null\n  }\n\n  // Document first (nodeType covers environments where `document instanceof Document` is false)\n  if (\n    (typeof Document !== 'undefined' && target instanceof Document) ||\n    (typeof Node !== 'undefined' &&\n      (target as Node).nodeType === Node.DOCUMENT_NODE)\n  ) {\n    return (target as Document).activeElement\n  }\n\n  if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {\n    return target.ownerDocument.activeElement ?? null\n  }\n\n  // Window (global or iframe): avoid relying on `instanceof Window` alone (test DOM quirks)\n  return (target as Window).document.activeElement ?? null\n}\n\n/**\n * Returns whether an event should be ignored because it originated from an\n * input-like element other than the registration target.\n *\n * This checks:\n * - the currently focused element for the listener target\n * - the event's composed path (for shadow DOM)\n * - the event target as a final fallback\n */\nexport function shouldIgnoreInputEvent(\n  event: KeyboardEvent,\n  listenerTarget: HTMLElement | Document | Window,\n  registrationTarget: HTMLElement | Document | Window,\n): boolean {\n  const focused = getActiveElementForListenerTarget(listenerTarget)\n  if (focused && isInputElement(focused) && focused !== registrationTarget) {\n    return true\n  }\n\n  if (\n    event\n      .composedPath()\n      .some(\n        (element) => isInputElement(element) && element !== registrationTarget,\n      )\n  ) {\n    return true\n  }\n\n  return isInputElement(event.target) && event.target !== registrationTarget\n}\n\n/**\n * Checks if an event is for the given target (originated from or bubbled to it).\n *\n * For document/window targets, also accepts document.documentElement as currentTarget\n * to handle Brave and other browsers where currentTarget may be documentElement\n * instead of document when listeners are attached to document.\n */\nexport function isEventForTarget(\n  event: KeyboardEvent,\n  target: HTMLElement | Document | Window,\n): boolean {\n  // For Document and Window, verify that our handler was indeed called for this target.\n  //\n  // Browser compatibility note:\n  // Per the DOM spec, event.currentTarget should equal the element the listener was\n  // attached to. However, some Chromium-based browsers (notably Brave) exhibit\n  // non-standard behavior where event.currentTarget is set to document.documentElement\n  // (<html>) instead of document when a listener is attached to document.\n  // This may be related to privacy/fingerprinting protections.\n  //\n  // To ensure cross-browser compatibility, we accept both the expected target\n  // and document.documentElement as valid currentTarget values.\n  // See: https://dom.spec.whatwg.org/#dom-event-currenttarget\n  if (target === document || target === window) {\n    return (\n      event.currentTarget === target ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For Window, accept window, document, or document.documentElement (browser quirks)\n  if (target === window) {\n    return (\n      event.currentTarget === window ||\n      event.currentTarget === document ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For HTMLElement, check if event originated from or bubbled to the element\n  if (target instanceof HTMLElement) {\n    // Check if the event's currentTarget is the target (capturing/bubbling)\n    if (event.currentTarget === target) {\n      return true\n    }\n\n    // Check if the event's target is a descendant of our target\n    if (event.target instanceof Node && target.contains(event.target)) {\n      return true\n    }\n  }\n\n  return false\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAsC;AACnE,KAAI,CAAC,QACH,QAAO;AAGT,KAAI,mBAAmB,kBAAkB;EACvC,MAAM,OAAO,QAAQ,KAAK,aAAa;AACvC,MAAI,SAAS,YAAY,SAAS,YAAY,SAAS,QACrD,QAAO;AAET,SAAO;;AAGT,KACE,mBAAmB,uBACnB,mBAAmB,kBAEnB,QAAO;AAKT,KAAI,mBAAmB,eAAe,QAAQ,kBAC5C,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,kCACd,QACgB;AAChB,KAAI,OAAO,aAAa,YACtB,QAAO;AAIT,KACG,OAAO,aAAa,eAAe,kBAAkB,YACrD,OAAO,SAAS,eACd,OAAgB,aAAa,KAAK,cAErC,QAAQ,OAAoB;AAG9B,KAAI,OAAO,gBAAgB,eAAe,kBAAkB,YAC1D,QAAO,OAAO,cAAc,iBAAiB;AAI/C,QAAQ,OAAkB,SAAS,iBAAiB;;;;;;;;;;;AAYtD,SAAgB,uBACd,OACA,gBACA,oBACS;CACT,MAAM,UAAU,kCAAkC,eAAe;AACjE,KAAI,WAAW,eAAe,QAAQ,IAAI,YAAY,mBACpD,QAAO;AAGT,KACE,MACG,cAAc,CACd,MACE,YAAY,eAAe,QAAQ,IAAI,YAAY,mBACrD,CAEH,QAAO;AAGT,QAAO,eAAe,MAAM,OAAO,IAAI,MAAM,WAAW;;;;;;;;;AAU1D,SAAgB,iBACd,OACA,QACS;AAaT,KAAI,WAAW,YAAY,WAAW,OACpC,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,WAAW,OACb,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,YACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,kBAAkB,aAAa;AAEjC,MAAI,MAAM,kBAAkB,OAC1B,QAAO;AAIT,MAAI,MAAM,kBAAkB,QAAQ,OAAO,SAAS,MAAM,OAAO,CAC/D,QAAO;;AAIX,QAAO"}

package/dist/_keyboard-event.cjs

@@ -0,0 +1,83 @@
+const require_constants = require('./constants.cjs');
+
+//#region src/_keyboard-event.ts
+/** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
+function normalizeKeyboardEvent(event, platform) {
+	let altGraph = false;
+	try {
+		altGraph = platform !== "mac" && typeof event.getModifierState === "function" && event.getModifierState("AltGraph");
+	} catch {}
+	const key = (event.key || "").normalize("NFC");
+	return {
+		key: require_constants.normalizeKeyName(key),
+		code: event.code || "",
+		ctrl: Boolean(event.ctrlKey),
+		shift: Boolean(event.shiftKey),
+		alt: Boolean(event.altKey),
+		meta: Boolean(event.metaKey),
+		altGraph,
+		location: event.location,
+		isComposing: Boolean(event.isComposing) || key === "Process" || key === "Unidentified"
+	};
+}
+/**
+* Maps familiar positions to compatibility fallback keys for the logical matcher.
+* This assumes conventional positions, not the active layout; never use it to
+* turn recorded physical bindings into logical bindings or display labels.
+*/
+function codeToLogicalKey(code) {
+	if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase();
+	if (/^Digit[0-9]$/i.test(code)) return code.slice(5);
+	if (/^Numpad[0-9]$/i.test(code)) return code.slice(6);
+	const punctuation = require_constants.PUNCTUATION_CODE_MAP[code];
+	if (punctuation) return punctuation;
+	return {
+		NumpadAdd: "+",
+		NumpadSubtract: "-",
+		NumpadMultiply: "*",
+		NumpadDivide: "/",
+		NumpadDecimal: ".",
+		NumpadEnter: "Enter",
+		Space: "Space"
+	}[code];
+}
+/** Tests for one Unicode code point, including characters represented by a surrogate pair. */
+function isPrintableKey(key) {
+	return key !== "" && Array.from(key).length === 1;
+}
+/** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
+function splitHotkeyParts(hotkey) {
+	if (!hotkey.endsWith("+")) return hotkey.split("+");
+	const parts = hotkey.slice(0, -1).split("+");
+	if (parts.at(-1) === "") parts.pop();
+	parts.push("+");
+	return parts;
+}
+/** Identifies ASCII letters whose layout-produced value takes precedence over positional fallbacks. */
+function isAsciiLetter(key) {
+	return /^[A-Za-z]$/.test(key);
+}
+/** Identifies a single Latin-script character, including accented letters. */
+function isLatinLetter(key) {
+	return /^\p{Script_Extensions=Latin}$/u.test(key);
+}
+/** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */
+function keysEqual(left, right) {
+	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) return left.localeCompare(right, void 0, { sensitivity: "accent" }) === 0;
+	return left === right;
+}
+/** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
+function assertLogicalKey(key) {
+	if (/^\[.*\]$/s.test(key.trim())) throw new Error("Logical key must not contain a bracketed physical code. Use the code field instead.");
+}
+
+//#endregion
+exports.assertLogicalKey = assertLogicalKey;
+exports.codeToLogicalKey = codeToLogicalKey;
+exports.isAsciiLetter = isAsciiLetter;
+exports.isLatinLetter = isLatinLetter;
+exports.isPrintableKey = isPrintableKey;
+exports.keysEqual = keysEqual;
+exports.normalizeKeyboardEvent = normalizeKeyboardEvent;
+exports.splitHotkeyParts = splitHotkeyParts;
+//# sourceMappingURL=_keyboard-event.cjs.map

package/dist/_keyboard-event.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_keyboard-event.cjs","names":["normalizeKeyName","PUNCTUATION_CODE_MAP"],"sources":["../src/_keyboard-event.ts"],"sourcesContent":["import { PUNCTUATION_CODE_MAP, normalizeKeyName } from './constants'\nimport type { NormalizedKeyboardEvent } from './key.types'\n\n/** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */\nexport function normalizeKeyboardEvent(\n  event: KeyboardEvent,\n  platform?: 'mac' | 'windows' | 'linux',\n): NormalizedKeyboardEvent {\n  let altGraph = false\n  try {\n    // WebKit reports AltGraph for Option on some macOS keyboard layouts. Option\n    // remains a normal Alt shortcut modifier there, so only use this signal on\n    // Windows/Linux where AltGraph synthesizes Control+Alt.\n    altGraph =\n      platform !== 'mac' &&\n      typeof event.getModifierState === 'function' &&\n      event.getModifierState('AltGraph')\n  } catch {\n    // Synthetic events and older browsers may not implement this reliably.\n  }\n\n  const key = (event.key || '').normalize('NFC')\n  return {\n    key: normalizeKeyName(key),\n    code: event.code || '',\n    ctrl: Boolean(event.ctrlKey),\n    shift: Boolean(event.shiftKey),\n    alt: Boolean(event.altKey),\n    meta: Boolean(event.metaKey),\n    altGraph,\n    location: event.location,\n    isComposing:\n      Boolean(event.isComposing) || key === 'Process' || key === 'Unidentified',\n  }\n}\n\n/**\n * Maps familiar positions to compatibility fallback keys for the logical matcher.\n * This assumes conventional positions, not the active layout; never use it to\n * turn recorded physical bindings into logical bindings or display labels.\n */\nexport function codeToLogicalKey(code: string): string | undefined {\n  if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase()\n  if (/^Digit[0-9]$/i.test(code)) return code.slice(5)\n  if (/^Numpad[0-9]$/i.test(code)) return code.slice(6)\n\n  const punctuation = PUNCTUATION_CODE_MAP[code]\n  if (punctuation) return punctuation\n\n  const named: Record<string, string> = {\n    NumpadAdd: '+',\n    NumpadSubtract: '-',\n    NumpadMultiply: '*',\n    NumpadDivide: '/',\n    NumpadDecimal: '.',\n    NumpadEnter: 'Enter',\n    Space: 'Space',\n  }\n  return named[code]\n}\n\n/** Tests for one Unicode code point, including characters represented by a surrogate pair. */\nexport function isPrintableKey(key: string): boolean {\n  return key !== '' && Array.from(key).length === 1\n}\n\n/** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */\nexport function splitHotkeyParts(hotkey: string): Array<string> {\n  if (!hotkey.endsWith('+')) return hotkey.split('+')\n  const parts = hotkey.slice(0, -1).split('+')\n  if (parts.at(-1) === '') parts.pop()\n  parts.push('+')\n  return parts\n}\n\n/** Identifies ASCII letters whose layout-produced value takes precedence over positional fallbacks. */\nexport function isAsciiLetter(key: string): boolean {\n  return /^[A-Za-z]$/.test(key)\n}\n\n/** Identifies a single Latin-script character, including accented letters. */\nexport function isLatinLetter(key: string): boolean {\n  return /^\\p{Script_Extensions=Latin}$/u.test(key)\n}\n\n/** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */\nexport function keysEqual(left: string, right: string): boolean {\n  if (/^\\p{Letter}$/u.test(left) && /^\\p{Letter}$/u.test(right)) {\n    return left.localeCompare(right, undefined, { sensitivity: 'accent' }) === 0\n  }\n  return left === right\n}\n\n/** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */\nexport function assertLogicalKey(key: string): void {\n  if (/^\\[.*\\]$/s.test(key.trim())) {\n    throw new Error(\n      'Logical key must not contain a bracketed physical code. Use the code field instead.',\n    )\n  }\n}\n"],"mappings":";;;;AAIA,SAAgB,uBACd,OACA,UACyB;CACzB,IAAI,WAAW;AACf,KAAI;AAIF,aACE,aAAa,SACb,OAAO,MAAM,qBAAqB,cAClC,MAAM,iBAAiB,WAAW;SAC9B;CAIR,MAAM,OAAO,MAAM,OAAO,IAAI,UAAU,MAAM;AAC9C,QAAO;EACL,KAAKA,mCAAiB,IAAI;EAC1B,MAAM,MAAM,QAAQ;EACpB,MAAM,QAAQ,MAAM,QAAQ;EAC5B,OAAO,QAAQ,MAAM,SAAS;EAC9B,KAAK,QAAQ,MAAM,OAAO;EAC1B,MAAM,QAAQ,MAAM,QAAQ;EAC5B;EACA,UAAU,MAAM;EAChB,aACE,QAAQ,MAAM,YAAY,IAAI,QAAQ,aAAa,QAAQ;EAC9D;;;;;;;AAQH,SAAgB,iBAAiB,MAAkC;AACjE,KAAI,cAAc,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE,CAAC,aAAa;AAChE,KAAI,gBAAgB,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE;AACpD,KAAI,iBAAiB,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE;CAErD,MAAM,cAAcC,uCAAqB;AACzC,KAAI,YAAa,QAAO;AAWxB,QATsC;EACpC,WAAW;EACX,gBAAgB;EAChB,gBAAgB;EAChB,cAAc;EACd,eAAe;EACf,aAAa;EACb,OAAO;EACR,CACY;;;AAIf,SAAgB,eAAe,KAAsB;AACnD,QAAO,QAAQ,MAAM,MAAM,KAAK,IAAI,CAAC,WAAW;;;AAIlD,SAAgB,iBAAiB,QAA+B;AAC9D,KAAI,CAAC,OAAO,SAAS,IAAI,CAAE,QAAO,OAAO,MAAM,IAAI;CACnD,MAAM,QAAQ,OAAO,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI;AAC5C,KAAI,MAAM,GAAG,GAAG,KAAK,GAAI,OAAM,KAAK;AACpC,OAAM,KAAK,IAAI;AACf,QAAO;;;AAIT,SAAgB,cAAc,KAAsB;AAClD,QAAO,aAAa,KAAK,IAAI;;;AAI/B,SAAgB,cAAc,KAAsB;AAClD,QAAO,iCAAiC,KAAK,IAAI;;;AAInD,SAAgB,UAAU,MAAc,OAAwB;AAC9D,KAAI,gBAAgB,KAAK,KAAK,IAAI,gBAAgB,KAAK,MAAM,CAC3D,QAAO,KAAK,cAAc,OAAO,QAAW,EAAE,aAAa,UAAU,CAAC,KAAK;AAE7E,QAAO,SAAS;;;AAIlB,SAAgB,iBAAiB,KAAmB;AAClD,KAAI,YAAY,KAAK,IAAI,MAAM,CAAC,CAC9B,OAAM,IAAI,MACR,sFACD"}

package/dist/_keyboard-event.js

@@ -0,0 +1,76 @@
+import { PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+
+//#region src/_keyboard-event.ts
+/** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
+function normalizeKeyboardEvent(event, platform) {
+	let altGraph = false;
+	try {
+		altGraph = platform !== "mac" && typeof event.getModifierState === "function" && event.getModifierState("AltGraph");
+	} catch {}
+	const key = (event.key || "").normalize("NFC");
+	return {
+		key: normalizeKeyName(key),
+		code: event.code || "",
+		ctrl: Boolean(event.ctrlKey),
+		shift: Boolean(event.shiftKey),
+		alt: Boolean(event.altKey),
+		meta: Boolean(event.metaKey),
+		altGraph,
+		location: event.location,
+		isComposing: Boolean(event.isComposing) || key === "Process" || key === "Unidentified"
+	};
+}
+/**
+* Maps familiar positions to compatibility fallback keys for the logical matcher.
+* This assumes conventional positions, not the active layout; never use it to
+* turn recorded physical bindings into logical bindings or display labels.
+*/
+function codeToLogicalKey(code) {
+	if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase();
+	if (/^Digit[0-9]$/i.test(code)) return code.slice(5);
+	if (/^Numpad[0-9]$/i.test(code)) return code.slice(6);
+	const punctuation = PUNCTUATION_CODE_MAP[code];
+	if (punctuation) return punctuation;
+	return {
+		NumpadAdd: "+",
+		NumpadSubtract: "-",
+		NumpadMultiply: "*",
+		NumpadDivide: "/",
+		NumpadDecimal: ".",
+		NumpadEnter: "Enter",
+		Space: "Space"
+	}[code];
+}
+/** Tests for one Unicode code point, including characters represented by a surrogate pair. */
+function isPrintableKey(key) {
+	return key !== "" && Array.from(key).length === 1;
+}
+/** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
+function splitHotkeyParts(hotkey) {
+	if (!hotkey.endsWith("+")) return hotkey.split("+");
+	const parts = hotkey.slice(0, -1).split("+");
+	if (parts.at(-1) === "") parts.pop();
+	parts.push("+");
+	return parts;
+}
+/** Identifies ASCII letters whose layout-produced value takes precedence over positional fallbacks. */
+function isAsciiLetter(key) {
+	return /^[A-Za-z]$/.test(key);
+}
+/** Identifies a single Latin-script character, including accented letters. */
+function isLatinLetter(key) {
+	return /^\p{Script_Extensions=Latin}$/u.test(key);
+}
+/** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */
+function keysEqual(left, right) {
+	if (/^\p{Letter}$/u.test(left) && /^\p{Letter}$/u.test(right)) return left.localeCompare(right, void 0, { sensitivity: "accent" }) === 0;
+	return left === right;
+}
+/** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */
+function assertLogicalKey(key) {
+	if (/^\[.*\]$/s.test(key.trim())) throw new Error("Logical key must not contain a bracketed physical code. Use the code field instead.");
+}
+
+//#endregion
+export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent, splitHotkeyParts };
+//# sourceMappingURL=_keyboard-event.js.map

package/dist/_keyboard-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_keyboard-event.js","names":[],"sources":["../src/_keyboard-event.ts"],"sourcesContent":["import { PUNCTUATION_CODE_MAP, normalizeKeyName } from './constants'\nimport type { NormalizedKeyboardEvent } from './key.types'\n\n/** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */\nexport function normalizeKeyboardEvent(\n  event: KeyboardEvent,\n  platform?: 'mac' | 'windows' | 'linux',\n): NormalizedKeyboardEvent {\n  let altGraph = false\n  try {\n    // WebKit reports AltGraph for Option on some macOS keyboard layouts. Option\n    // remains a normal Alt shortcut modifier there, so only use this signal on\n    // Windows/Linux where AltGraph synthesizes Control+Alt.\n    altGraph =\n      platform !== 'mac' &&\n      typeof event.getModifierState === 'function' &&\n      event.getModifierState('AltGraph')\n  } catch {\n    // Synthetic events and older browsers may not implement this reliably.\n  }\n\n  const key = (event.key || '').normalize('NFC')\n  return {\n    key: normalizeKeyName(key),\n    code: event.code || '',\n    ctrl: Boolean(event.ctrlKey),\n    shift: Boolean(event.shiftKey),\n    alt: Boolean(event.altKey),\n    meta: Boolean(event.metaKey),\n    altGraph,\n    location: event.location,\n    isComposing:\n      Boolean(event.isComposing) || key === 'Process' || key === 'Unidentified',\n  }\n}\n\n/**\n * Maps familiar positions to compatibility fallback keys for the logical matcher.\n * This assumes conventional positions, not the active layout; never use it to\n * turn recorded physical bindings into logical bindings or display labels.\n */\nexport function codeToLogicalKey(code: string): string | undefined {\n  if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase()\n  if (/^Digit[0-9]$/i.test(code)) return code.slice(5)\n  if (/^Numpad[0-9]$/i.test(code)) return code.slice(6)\n\n  const punctuation = PUNCTUATION_CODE_MAP[code]\n  if (punctuation) return punctuation\n\n  const named: Record<string, string> = {\n    NumpadAdd: '+',\n    NumpadSubtract: '-',\n    NumpadMultiply: '*',\n    NumpadDivide: '/',\n    NumpadDecimal: '.',\n    NumpadEnter: 'Enter',\n    Space: 'Space',\n  }\n  return named[code]\n}\n\n/** Tests for one Unicode code point, including characters represented by a surrogate pair. */\nexport function isPrintableKey(key: string): boolean {\n  return key !== '' && Array.from(key).length === 1\n}\n\n/** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */\nexport function splitHotkeyParts(hotkey: string): Array<string> {\n  if (!hotkey.endsWith('+')) return hotkey.split('+')\n  const parts = hotkey.slice(0, -1).split('+')\n  if (parts.at(-1) === '') parts.pop()\n  parts.push('+')\n  return parts\n}\n\n/** Identifies ASCII letters whose layout-produced value takes precedence over positional fallbacks. */\nexport function isAsciiLetter(key: string): boolean {\n  return /^[A-Za-z]$/.test(key)\n}\n\n/** Identifies a single Latin-script character, including accented letters. */\nexport function isLatinLetter(key: string): boolean {\n  return /^\\p{Script_Extensions=Latin}$/u.test(key)\n}\n\n/** Compares letters without case, preserving accents and avoiding expansions such as ß → SS. */\nexport function keysEqual(left: string, right: string): boolean {\n  if (/^\\p{Letter}$/u.test(left) && /^\\p{Letter}$/u.test(right)) {\n    return left.localeCompare(right, undefined, { sensitivity: 'accent' }) === 0\n  }\n  return left === right\n}\n\n/** Rejects reserved physical-token syntax in logical object fields while allowing Unicode characters. */\nexport function assertLogicalKey(key: string): void {\n  if (/^\\[.*\\]$/s.test(key.trim())) {\n    throw new Error(\n      'Logical key must not contain a bracketed physical code. Use the code field instead.',\n    )\n  }\n}\n"],"mappings":";;;;AAIA,SAAgB,uBACd,OACA,UACyB;CACzB,IAAI,WAAW;AACf,KAAI;AAIF,aACE,aAAa,SACb,OAAO,MAAM,qBAAqB,cAClC,MAAM,iBAAiB,WAAW;SAC9B;CAIR,MAAM,OAAO,MAAM,OAAO,IAAI,UAAU,MAAM;AAC9C,QAAO;EACL,KAAK,iBAAiB,IAAI;EAC1B,MAAM,MAAM,QAAQ;EACpB,MAAM,QAAQ,MAAM,QAAQ;EAC5B,OAAO,QAAQ,MAAM,SAAS;EAC9B,KAAK,QAAQ,MAAM,OAAO;EAC1B,MAAM,QAAQ,MAAM,QAAQ;EAC5B;EACA,UAAU,MAAM;EAChB,aACE,QAAQ,MAAM,YAAY,IAAI,QAAQ,aAAa,QAAQ;EAC9D;;;;;;;AAQH,SAAgB,iBAAiB,MAAkC;AACjE,KAAI,cAAc,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE,CAAC,aAAa;AAChE,KAAI,gBAAgB,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE;AACpD,KAAI,iBAAiB,KAAK,KAAK,CAAE,QAAO,KAAK,MAAM,EAAE;CAErD,MAAM,cAAc,qBAAqB;AACzC,KAAI,YAAa,QAAO;AAWxB,QATsC;EACpC,WAAW;EACX,gBAAgB;EAChB,gBAAgB;EAChB,cAAc;EACd,eAAe;EACf,aAAa;EACb,OAAO;EACR,CACY;;;AAIf,SAAgB,eAAe,KAAsB;AACnD,QAAO,QAAQ,MAAM,MAAM,KAAK,IAAI,CAAC,WAAW;;;AAIlD,SAAgB,iBAAiB,QAA+B;AAC9D,KAAI,CAAC,OAAO,SAAS,IAAI,CAAE,QAAO,OAAO,MAAM,IAAI;CACnD,MAAM,QAAQ,OAAO,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI;AAC5C,KAAI,MAAM,GAAG,GAAG,KAAK,GAAI,OAAM,KAAK;AACpC,OAAM,KAAK,IAAI;AACf,QAAO;;;AAIT,SAAgB,cAAc,KAAsB;AAClD,QAAO,aAAa,KAAK,IAAI;;;AAI/B,SAAgB,cAAc,KAAsB;AAClD,QAAO,iCAAiC,KAAK,IAAI;;;AAInD,SAAgB,UAAU,MAAc,OAAwB;AAC9D,KAAI,gBAAgB,KAAK,KAAK,IAAI,gBAAgB,KAAK,MAAM,CAC3D,QAAO,KAAK,cAAc,OAAO,QAAW,EAAE,aAAa,UAAU,CAAC,KAAK;AAE7E,QAAO,SAAS;;;AAIlB,SAAgB,iBAAiB,KAAmB;AAClD,KAAI,YAAY,KAAK,IAAI,MAAM,CAAC,CAC9B,OAAM,IAAI,MACR,sFACD"}

package/dist/_match.cjs

@@ -0,0 +1,49 @@
+const require_platform = require('./platform.cjs');
+const require__keyboard_event = require('./_keyboard-event.cjs');
+const require_parse = require('./parse.cjs');
+
+//#region src/_match.ts
+/** Matches an event and reports the winning candidate and release identity. */
+function matchKeyboardEvent(event, hotkey, platform = require_platform.detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
+	const normalized = require__keyboard_event.normalizeKeyboardEvent(event, platform);
+	const noMatch = {
+		matched: false,
+		score: 0
+	};
+	if (normalized.isComposing && (parsed.code !== void 0 || require__keyboard_event.isPrintableKey(parsed.key))) return noMatch;
+	if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch;
+	if (parsed.code !== void 0) {
+		if (!modifiersMatch(normalized, parsed, false)) return noMatch;
+		return normalized.code === parsed.code ? matched("code", 3) : noMatch;
+	}
+	const direct = require__keyboard_event.keysEqual(normalized.key, parsed.key);
+	const implicitShift = direct && require__keyboard_event.isPrintableKey(normalized.key) && !/^\p{Letter}$/u.test(normalized.key) && !parsed.shift;
+	if (direct && modifiersMatch(normalized, parsed, implicitShift)) return matched("key", implicitShift ? 2 : 3);
+	if (require__keyboard_event.isAsciiLetter(normalized.key) || require__keyboard_event.isLatinLetter(normalized.key) && normalized.code.startsWith("Key") && !normalized.alt) return noMatch;
+	if (!modifiersMatch(normalized, parsed, false)) return noMatch;
+	const fallbackKey = require__keyboard_event.codeToLogicalKey(normalized.code);
+	return fallbackKey !== void 0 && require__keyboard_event.keysEqual(fallbackKey, parsed.key) ? matched("fallback", 1) : noMatch;
+	function matched(source, score) {
+		return {
+			matched: true,
+			score,
+			source,
+			identity: {
+				key: normalized.key,
+				code: normalized.code
+			}
+		};
+	}
+}
+/** Compares modifiers, excluding synthetic AltGr flags and optionally allowing Shift used to type a glyph. */
+function modifiersMatch(event, parsed, allowImplicitShift) {
+	const ctrl = event.altGraph ? false : event.ctrl;
+	const alt = event.altGraph ? false : event.alt;
+	if (ctrl !== parsed.ctrl || alt !== parsed.alt || event.meta !== parsed.meta) return false;
+	return event.shift === parsed.shift || allowImplicitShift && event.shift;
+}
+
+//#endregion
+exports.matchKeyboardEvent = matchKeyboardEvent;
+//# sourceMappingURL=_match.cjs.map

package/dist/_match.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyboardEvent","isPrintableKey","keysEqual","isAsciiLetter","isLatinLetter","codeToLogicalKey"],"sources":["../src/_match.ts"],"sourcesContent":["import { detectPlatform } from './platform'\nimport {\n  codeToLogicalKey,\n  isAsciiLetter,\n  isLatinLetter,\n  isPrintableKey,\n  keysEqual,\n  normalizeKeyboardEvent,\n} from './_keyboard-event'\nimport { parseHotkey } from './parse'\nimport type { KeyboardEventMatch } from './match'\nimport type { Hotkey, ParsedHotkey } from './hotkey.types'\n\n/** Matches an event and reports the winning candidate and release identity. */\nexport function matchKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): KeyboardEventMatch {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const normalized = normalizeKeyboardEvent(event, platform)\n  const noMatch: KeyboardEventMatch = { matched: false, score: 0 }\n\n  if (\n    normalized.isComposing &&\n    (parsed.code !== undefined || isPrintableKey(parsed.key))\n  )\n    return noMatch\n  if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch\n\n  if (parsed.code !== undefined) {\n    if (!modifiersMatch(normalized, parsed, false)) return noMatch\n    return normalized.code === parsed.code ? matched('code', 3) : noMatch\n  }\n\n  const direct = keysEqual(normalized.key, parsed.key)\n  const implicitShift =\n    direct &&\n    isPrintableKey(normalized.key) &&\n    !/^\\p{Letter}$/u.test(normalized.key) &&\n    !parsed.shift\n\n  if (direct && modifiersMatch(normalized, parsed, implicitShift)) {\n    return matched('key', implicitShift ? 2 : 3)\n  }\n\n  // ASCII alphabetic output is authoritative for Dvorak/Colemak/AZERTY.\n  // Native Latin letters are also authoritative on Key* positions; Alt is the\n  // exception because macOS Option commonly transforms a shortcut's glyph.\n  if (\n    isAsciiLetter(normalized.key) ||\n    (isLatinLetter(normalized.key) &&\n      normalized.code.startsWith('Key') &&\n      !normalized.alt)\n  ) {\n    return noMatch\n  }\n\n  if (!modifiersMatch(normalized, parsed, false)) return noMatch\n  const fallbackKey = codeToLogicalKey(normalized.code)\n  return fallbackKey !== undefined && keysEqual(fallbackKey, parsed.key)\n    ? matched('fallback', 1)\n    : noMatch\n\n  // Preserve the triggering code so keyup can reset a shortcut even if its character changes.\n  function matched(\n    source: 'key' | 'code' | 'fallback',\n    score: 1 | 2 | 3,\n  ): KeyboardEventMatch {\n    return {\n      matched: true,\n      score,\n      source,\n      identity: { key: normalized.key, code: normalized.code },\n    }\n  }\n}\n\n/** Compares modifiers, excluding synthetic AltGr flags and optionally allowing Shift used to type a glyph. */\nfunction modifiersMatch(\n  event: ReturnType<typeof normalizeKeyboardEvent>,\n  parsed: ParsedHotkey,\n  allowImplicitShift: boolean,\n): boolean {\n  const ctrl = event.altGraph ? false : event.ctrl\n  const alt = event.altGraph ? false : event.alt\n  if (\n    ctrl !== parsed.ctrl ||\n    alt !== parsed.alt ||\n    event.meta !== parsed.meta\n  ) {\n    return false\n  }\n  return event.shift === parsed.shift || (allowImplicitShift && event.shift)\n}\n"],"mappings":";;;;;;AAcA,SAAgB,mBACd,OACA,QACA,WAAwCA,iCAAgB,EACpC;CACpB,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,aAAaC,+CAAuB,OAAO,SAAS;CAC1D,MAAM,UAA8B;EAAE,SAAS;EAAO,OAAO;EAAG;AAEhE,KACE,WAAW,gBACV,OAAO,SAAS,UAAaC,uCAAe,OAAO,IAAI,EAExD,QAAO;AACT,KAAI,WAAW,aAAa,OAAO,QAAQ,OAAO,KAAM,QAAO;AAE/D,KAAI,OAAO,SAAS,QAAW;AAC7B,MAAI,CAAC,eAAe,YAAY,QAAQ,MAAM,CAAE,QAAO;AACvD,SAAO,WAAW,SAAS,OAAO,OAAO,QAAQ,QAAQ,EAAE,GAAG;;CAGhE,MAAM,SAASC,kCAAU,WAAW,KAAK,OAAO,IAAI;CACpD,MAAM,gBACJ,UACAD,uCAAe,WAAW,IAAI,IAC9B,CAAC,gBAAgB,KAAK,WAAW,IAAI,IACrC,CAAC,OAAO;AAEV,KAAI,UAAU,eAAe,YAAY,QAAQ,cAAc,CAC7D,QAAO,QAAQ,OAAO,gBAAgB,IAAI,EAAE;AAM9C,KACEE,sCAAc,WAAW,IAAI,IAC5BC,sCAAc,WAAW,IAAI,IAC5B,WAAW,KAAK,WAAW,MAAM,IACjC,CAAC,WAAW,IAEd,QAAO;AAGT,KAAI,CAAC,eAAe,YAAY,QAAQ,MAAM,CAAE,QAAO;CACvD,MAAM,cAAcC,yCAAiB,WAAW,KAAK;AACrD,QAAO,gBAAgB,UAAaH,kCAAU,aAAa,OAAO,IAAI,GAClE,QAAQ,YAAY,EAAE,GACtB;CAGJ,SAAS,QACP,QACA,OACoB;AACpB,SAAO;GACL,SAAS;GACT;GACA;GACA,UAAU;IAAE,KAAK,WAAW;IAAK,MAAM,WAAW;IAAM;GACzD;;;;AAKL,SAAS,eACP,OACA,QACA,oBACS;CACT,MAAM,OAAO,MAAM,WAAW,QAAQ,MAAM;CAC5C,MAAM,MAAM,MAAM,WAAW,QAAQ,MAAM;AAC3C,KACE,SAAS,OAAO,QAChB,QAAQ,OAAO,OACf,MAAM,SAAS,OAAO,KAEtB,QAAO;AAET,QAAO,MAAM,UAAU,OAAO,SAAU,sBAAsB,MAAM"}

package/dist/_match.js

@@ -0,0 +1,49 @@
+import { detectPlatform } from "./platform.js";
+import { codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { parseHotkey } from "./parse.js";
+
+//#region src/_match.ts
+/** Matches an event and reports the winning candidate and release identity. */
+function matchKeyboardEvent(event, hotkey, platform = detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	const normalized = normalizeKeyboardEvent(event, platform);
+	const noMatch = {
+		matched: false,
+		score: 0
+	};
+	if (normalized.isComposing && (parsed.code !== void 0 || isPrintableKey(parsed.key))) return noMatch;
+	if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch;
+	if (parsed.code !== void 0) {
+		if (!modifiersMatch(normalized, parsed, false)) return noMatch;
+		return normalized.code === parsed.code ? matched("code", 3) : noMatch;
+	}
+	const direct = keysEqual(normalized.key, parsed.key);
+	const implicitShift = direct && isPrintableKey(normalized.key) && !/^\p{Letter}$/u.test(normalized.key) && !parsed.shift;
+	if (direct && modifiersMatch(normalized, parsed, implicitShift)) return matched("key", implicitShift ? 2 : 3);
+	if (isAsciiLetter(normalized.key) || isLatinLetter(normalized.key) && normalized.code.startsWith("Key") && !normalized.alt) return noMatch;
+	if (!modifiersMatch(normalized, parsed, false)) return noMatch;
+	const fallbackKey = codeToLogicalKey(normalized.code);
+	return fallbackKey !== void 0 && keysEqual(fallbackKey, parsed.key) ? matched("fallback", 1) : noMatch;
+	function matched(source, score) {
+		return {
+			matched: true,
+			score,
+			source,
+			identity: {
+				key: normalized.key,
+				code: normalized.code
+			}
+		};
+	}
+}
+/** Compares modifiers, excluding synthetic AltGr flags and optionally allowing Shift used to type a glyph. */
+function modifiersMatch(event, parsed, allowImplicitShift) {
+	const ctrl = event.altGraph ? false : event.ctrl;
+	const alt = event.altGraph ? false : event.alt;
+	if (ctrl !== parsed.ctrl || alt !== parsed.alt || event.meta !== parsed.meta) return false;
+	return event.shift === parsed.shift || allowImplicitShift && event.shift;
+}
+
+//#endregion
+export { matchKeyboardEvent };
+//# sourceMappingURL=_match.js.map

package/dist/_match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_match.js","names":[],"sources":["../src/_match.ts"],"sourcesContent":["import { detectPlatform } from './platform'\nimport {\n  codeToLogicalKey,\n  isAsciiLetter,\n  isLatinLetter,\n  isPrintableKey,\n  keysEqual,\n  normalizeKeyboardEvent,\n} from './_keyboard-event'\nimport { parseHotkey } from './parse'\nimport type { KeyboardEventMatch } from './match'\nimport type { Hotkey, ParsedHotkey } from './hotkey.types'\n\n/** Matches an event and reports the winning candidate and release identity. */\nexport function matchKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): KeyboardEventMatch {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const normalized = normalizeKeyboardEvent(event, platform)\n  const noMatch: KeyboardEventMatch = { matched: false, score: 0 }\n\n  if (\n    normalized.isComposing &&\n    (parsed.code !== undefined || isPrintableKey(parsed.key))\n  )\n    return noMatch\n  if (normalized.altGraph && (parsed.ctrl || parsed.alt)) return noMatch\n\n  if (parsed.code !== undefined) {\n    if (!modifiersMatch(normalized, parsed, false)) return noMatch\n    return normalized.code === parsed.code ? matched('code', 3) : noMatch\n  }\n\n  const direct = keysEqual(normalized.key, parsed.key)\n  const implicitShift =\n    direct &&\n    isPrintableKey(normalized.key) &&\n    !/^\\p{Letter}$/u.test(normalized.key) &&\n    !parsed.shift\n\n  if (direct && modifiersMatch(normalized, parsed, implicitShift)) {\n    return matched('key', implicitShift ? 2 : 3)\n  }\n\n  // ASCII alphabetic output is authoritative for Dvorak/Colemak/AZERTY.\n  // Native Latin letters are also authoritative on Key* positions; Alt is the\n  // exception because macOS Option commonly transforms a shortcut's glyph.\n  if (\n    isAsciiLetter(normalized.key) ||\n    (isLatinLetter(normalized.key) &&\n      normalized.code.startsWith('Key') &&\n      !normalized.alt)\n  ) {\n    return noMatch\n  }\n\n  if (!modifiersMatch(normalized, parsed, false)) return noMatch\n  const fallbackKey = codeToLogicalKey(normalized.code)\n  return fallbackKey !== undefined && keysEqual(fallbackKey, parsed.key)\n    ? matched('fallback', 1)\n    : noMatch\n\n  // Preserve the triggering code so keyup can reset a shortcut even if its character changes.\n  function matched(\n    source: 'key' | 'code' | 'fallback',\n    score: 1 | 2 | 3,\n  ): KeyboardEventMatch {\n    return {\n      matched: true,\n      score,\n      source,\n      identity: { key: normalized.key, code: normalized.code },\n    }\n  }\n}\n\n/** Compares modifiers, excluding synthetic AltGr flags and optionally allowing Shift used to type a glyph. */\nfunction modifiersMatch(\n  event: ReturnType<typeof normalizeKeyboardEvent>,\n  parsed: ParsedHotkey,\n  allowImplicitShift: boolean,\n): boolean {\n  const ctrl = event.altGraph ? false : event.ctrl\n  const alt = event.altGraph ? false : event.alt\n  if (\n    ctrl !== parsed.ctrl ||\n    alt !== parsed.alt ||\n    event.meta !== parsed.meta\n  ) {\n    return false\n  }\n  return event.shift === parsed.shift || (allowImplicitShift && event.shift)\n}\n"],"mappings":";;;;;;AAcA,SAAgB,mBACd,OACA,QACA,WAAwC,gBAAgB,EACpC;CACpB,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,aAAa,uBAAuB,OAAO,SAAS;CAC1D,MAAM,UAA8B;EAAE,SAAS;EAAO,OAAO;EAAG;AAEhE,KACE,WAAW,gBACV,OAAO,SAAS,UAAa,eAAe,OAAO,IAAI,EAExD,QAAO;AACT,KAAI,WAAW,aAAa,OAAO,QAAQ,OAAO,KAAM,QAAO;AAE/D,KAAI,OAAO,SAAS,QAAW;AAC7B,MAAI,CAAC,eAAe,YAAY,QAAQ,MAAM,CAAE,QAAO;AACvD,SAAO,WAAW,SAAS,OAAO,OAAO,QAAQ,QAAQ,EAAE,GAAG;;CAGhE,MAAM,SAAS,UAAU,WAAW,KAAK,OAAO,IAAI;CACpD,MAAM,gBACJ,UACA,eAAe,WAAW,IAAI,IAC9B,CAAC,gBAAgB,KAAK,WAAW,IAAI,IACrC,CAAC,OAAO;AAEV,KAAI,UAAU,eAAe,YAAY,QAAQ,cAAc,CAC7D,QAAO,QAAQ,OAAO,gBAAgB,IAAI,EAAE;AAM9C,KACE,cAAc,WAAW,IAAI,IAC5B,cAAc,WAAW,IAAI,IAC5B,WAAW,KAAK,WAAW,MAAM,IACjC,CAAC,WAAW,IAEd,QAAO;AAGT,KAAI,CAAC,eAAe,YAAY,QAAQ,MAAM,CAAE,QAAO;CACvD,MAAM,cAAc,iBAAiB,WAAW,KAAK;AACrD,QAAO,gBAAgB,UAAa,UAAU,aAAa,OAAO,IAAI,GAClE,QAAQ,YAAY,EAAE,GACtB;CAGJ,SAAS,QACP,QACA,OACoB;AACpB,SAAO;GACL,SAAS;GACT;GACA;GACA,UAAU;IAAE,KAAK,WAAW;IAAK,MAAM,WAAW;IAAM;GACzD;;;;AAKL,SAAS,eACP,OACA,QACA,oBACS;CACT,MAAM,OAAO,MAAM,WAAW,QAAQ,MAAM;CAC5C,MAAM,MAAM,MAAM,WAAW,QAAQ,MAAM;AAC3C,KACE,SAAS,OAAO,QAChB,QAAQ,OAAO,OACf,MAAM,SAAS,OAAO,KAEtB,QAAO;AAET,QAAO,MAAM,UAAU,OAAO,SAAU,sBAAsB,MAAM"}

package/dist/_named-keys.cjs

@@ -0,0 +1,68 @@
+
+//#region src/_named-keys.ts
+/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
+const SHARED_NAMED_KEYS = [
+	"CapsLock",
+	"ContextMenu",
+	"Convert",
+	"KanaMode",
+	"NonConvert",
+	"Help",
+	"Insert",
+	"NumLock",
+	"Fn",
+	"FnLock",
+	"PrintScreen",
+	"ScrollLock",
+	"Pause",
+	"BrowserBack",
+	"BrowserFavorites",
+	"BrowserForward",
+	"BrowserHome",
+	"BrowserRefresh",
+	"BrowserSearch",
+	"BrowserStop",
+	"Eject",
+	"LaunchMail",
+	"MediaPlayPause",
+	"MediaStop",
+	"MediaTrackNext",
+	"MediaTrackPrevious",
+	"Power",
+	"AudioVolumeDown",
+	"AudioVolumeMute",
+	"AudioVolumeUp",
+	"WakeUp",
+	"Hyper",
+	"Super",
+	"Again",
+	"Copy",
+	"Cut",
+	"Find",
+	"Open",
+	"Paste",
+	"Props",
+	"Select",
+	"Undo",
+	"Hiragana",
+	"Katakana"
+];
+/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
+const LOGICAL_ONLY_NAMED_KEYS = [
+	"Clear",
+	"Cancel",
+	"Standby",
+	"LaunchApplication1",
+	"LaunchApplication2",
+	"LaunchMediaPlayer",
+	"HangulMode",
+	"HanjaMode",
+	"Zenkaku",
+	"Hankaku",
+	"ZenkakuHankaku"
+];
+
+//#endregion
+exports.LOGICAL_ONLY_NAMED_KEYS = LOGICAL_ONLY_NAMED_KEYS;
+exports.SHARED_NAMED_KEYS = SHARED_NAMED_KEYS;
+//# sourceMappingURL=_named-keys.cjs.map

package/dist/_named-keys.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_named-keys.cjs","names":[],"sources":["../src/_named-keys.ts"],"sourcesContent":["/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */\nexport const SHARED_NAMED_KEYS = [\n  'CapsLock',\n  'ContextMenu',\n  'Convert',\n  'KanaMode',\n  'NonConvert',\n  'Help',\n  'Insert',\n  'NumLock',\n  'Fn',\n  'FnLock',\n  'PrintScreen',\n  'ScrollLock',\n  'Pause',\n  'BrowserBack',\n  'BrowserFavorites',\n  'BrowserForward',\n  'BrowserHome',\n  'BrowserRefresh',\n  'BrowserSearch',\n  'BrowserStop',\n  'Eject',\n  'LaunchMail',\n  'MediaPlayPause',\n  'MediaStop',\n  'MediaTrackNext',\n  'MediaTrackPrevious',\n  'Power',\n  'AudioVolumeDown',\n  'AudioVolumeMute',\n  'AudioVolumeUp',\n  'WakeUp',\n  'Hyper',\n  'Super',\n  'Again',\n  'Copy',\n  'Cut',\n  'Find',\n  'Open',\n  'Paste',\n  'Props',\n  'Select',\n  'Undo',\n  'Hiragana',\n  'Katakana',\n] as const\n\n/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */\nexport const LOGICAL_ONLY_NAMED_KEYS = [\n  'Clear',\n  'Cancel',\n  'Standby',\n  'LaunchApplication1',\n  'LaunchApplication2',\n  'LaunchMediaPlayer',\n  'HangulMode',\n  'HanjaMode',\n  'Zenkaku',\n  'Hankaku',\n  'ZenkakuHankaku',\n] as const\n"],"mappings":";;;AACA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;AAGD,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD"}

package/dist/_named-keys.d.cts

@@ -0,0 +1,8 @@
+//#region src/_named-keys.d.ts
+/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
+declare const SHARED_NAMED_KEYS: readonly ["CapsLock", "ContextMenu", "Convert", "KanaMode", "NonConvert", "Help", "Insert", "NumLock", "Fn", "FnLock", "PrintScreen", "ScrollLock", "Pause", "BrowserBack", "BrowserFavorites", "BrowserForward", "BrowserHome", "BrowserRefresh", "BrowserSearch", "BrowserStop", "Eject", "LaunchMail", "MediaPlayPause", "MediaStop", "MediaTrackNext", "MediaTrackPrevious", "Power", "AudioVolumeDown", "AudioVolumeMute", "AudioVolumeUp", "WakeUp", "Hyper", "Super", "Again", "Copy", "Cut", "Find", "Open", "Paste", "Props", "Select", "Undo", "Hiragana", "Katakana"];
+/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
+declare const LOGICAL_ONLY_NAMED_KEYS: readonly ["Clear", "Cancel", "Standby", "LaunchApplication1", "LaunchApplication2", "LaunchMediaPlayer", "HangulMode", "HanjaMode", "Zenkaku", "Hankaku", "ZenkakuHankaku"];
+//#endregion
+export { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS };
+//# sourceMappingURL=_named-keys.d.cts.map

package/dist/_named-keys.d.ts

@@ -0,0 +1,8 @@
+//#region src/_named-keys.d.ts
+/** Names defined for both KeyboardEvent.key and KeyboardEvent.code, beyond the basic key groups. */
+declare const SHARED_NAMED_KEYS: readonly ["CapsLock", "ContextMenu", "Convert", "KanaMode", "NonConvert", "Help", "Insert", "NumLock", "Fn", "FnLock", "PrintScreen", "ScrollLock", "Pause", "BrowserBack", "BrowserFavorites", "BrowserForward", "BrowserHome", "BrowserRefresh", "BrowserSearch", "BrowserStop", "Eject", "LaunchMail", "MediaPlayPause", "MediaStop", "MediaTrackNext", "MediaTrackPrevious", "Power", "AudioVolumeDown", "AudioVolumeMute", "AudioVolumeUp", "WakeUp", "Hyper", "Super", "Again", "Copy", "Cut", "Find", "Open", "Paste", "Props", "Select", "Undo", "Hiragana", "Katakana"];
+/** Logical counterparts whose physical positions use different names (for example Sleep and Lang1). */
+declare const LOGICAL_ONLY_NAMED_KEYS: readonly ["Clear", "Cancel", "Standby", "LaunchApplication1", "LaunchApplication2", "LaunchMediaPlayer", "HangulMode", "HanjaMode", "Zenkaku", "Hankaku", "ZenkakuHankaku"];
+//#endregion
+export { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS };
+//# sourceMappingURL=_named-keys.d.ts.map