@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/match.cjs

@@ -1,153 +0,0 @@
-const require_constants = require('./constants.cjs');
-const require_parse = require('./parse.cjs');
-
-//#region src/match.ts
-/**
-* Checks if a KeyboardEvent matches a hotkey.
-*
-* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
-* for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
-* characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
-* Letter keys are matched case-insensitively.
-*
-* Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
-* character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
-* Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
-* In these cases, `event.code` is used to determine the physical key.
-*
-* @param event - The KeyboardEvent to check
-* @param hotkey - The hotkey string or ParsedHotkey to match against
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns True if the event matches the hotkey
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   if (matchesKeyboardEvent(event, 'Mod+S')) {
-*     event.preventDefault()
-*     handleSave()
-*   }
-* })
-* ```
-*/
-function matchesKeyboardEvent(event, hotkey, platform = require_constants.detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
-	if (event.ctrlKey !== parsed.ctrl) return false;
-	if (event.shiftKey !== parsed.shift) return false;
-	if (event.altKey !== parsed.alt) return false;
-	if (event.metaKey !== parsed.meta) return false;
-	const eventKey = require_constants.normalizeKeyName(event.key);
-	const hotkeyKey = parsed.key;
-	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (require_constants.isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
-	}
-	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
-		if (event.code.startsWith("Key")) {
-			const codeLetter = event.code.slice(3);
-			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
-		}
-		if (event.code.startsWith("Digit")) {
-			const codeDigit = event.code.slice(5);
-			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
-		}
-		if (event.code in require_constants.PUNCTUATION_CODE_MAP) return require_constants.PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
-		return false;
-	}
-	return eventKey === hotkeyKey;
-}
-/**
-* Creates a keyboard event handler that calls the callback when the hotkey matches.
-*
-* @param hotkey - The hotkey string or ParsedHotkey to match
-* @param callback - The function to call when the hotkey matches
-* @param options - Options for matching and handling
-* @returns A function that can be used as an event handler
-*
-* @example
-* ```ts
-* const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
-*   console.log(`${hotkey} was pressed`)
-*   handleSave()
-* })
-*
-* document.addEventListener('keydown', handler)
-* ```
-*/
-function createHotkeyHandler(hotkey, callback, options = {}) {
-	const { preventDefault = true, stopPropagation = true, platform } = options;
-	const resolvedPlatform = platform ?? require_constants.detectPlatform();
-	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
-	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, resolvedPlatform) : hotkey;
-	const context = {
-		hotkey: hotkeyString,
-		parsedHotkey: parsed
-	};
-	return (event) => {
-		if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
-			if (preventDefault) event.preventDefault();
-			if (stopPropagation) event.stopPropagation();
-			callback(event, context);
-		}
-	};
-}
-/**
-* Creates a handler that matches multiple hotkeys.
-*
-* @param handlers - A map of hotkey strings to their handlers
-* @param options - Options for matching and handling
-* @returns A function that can be used as an event handler
-*
-* @example
-* ```ts
-* const handler = createMultiHotkeyHandler({
-*   'Mod+S': (event, { hotkey }) => handleSave(),
-*   'Mod+Z': (event, { hotkey }) => handleUndo(),
-*   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
-* })
-*
-* document.addEventListener('keydown', handler)
-* ```
-*/
-function createMultiHotkeyHandler(handlers, options = {}) {
-	const { preventDefault = true, stopPropagation = true, platform } = options;
-	const resolvedPlatform = platform ?? require_constants.detectPlatform();
-	const parsedHandlers = Object.entries(handlers).filter((entry) => Boolean(entry[1])).map(([hotkey, handler]) => {
-		const parsed = require_parse.parseHotkey(hotkey, resolvedPlatform);
-		return {
-			parsed,
-			handler,
-			context: {
-				hotkey,
-				parsedHotkey: parsed
-			}
-		};
-	});
-	return (event) => {
-		for (const { parsed, handler, context } of parsedHandlers) if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
-			if (preventDefault) event.preventDefault();
-			if (stopPropagation) event.stopPropagation();
-			handler(event, context);
-			return;
-		}
-	};
-}
-/**
-* Formats a ParsedHotkey back to a hotkey string.
-* Used internally to provide the hotkey string in callback context.
-*/
-function formatParsedHotkey(parsed) {
-	const parts = [];
-	if (parsed.ctrl) parts.push("Control");
-	if (parsed.alt) parts.push("Alt");
-	if (parsed.shift) parts.push("Shift");
-	if (parsed.meta) parts.push("Meta");
-	parts.push(parsed.key);
-	return parts.join("+");
-}
-
-//#endregion
-exports.createHotkeyHandler = createHotkeyHandler;
-exports.createMultiHotkeyHandler = createMultiHotkeyHandler;
-exports.matchesKeyboardEvent = matchesKeyboardEvent;
-//# sourceMappingURL=match.cjs.map

package/dist/match.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyName","isSingleLetterKey","PUNCTUATION_CODE_MAP"],"sources":["../src/match.ts"],"sourcesContent":["import {\n  PUNCTUATION_CODE_MAP,\n  detectPlatform,\n  isSingleLetterKey,\n  normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single-character keys (not dead keys), try direct event.key match first\n  if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // If event.key is a letter, we usually trust the keyboard layout.\n    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n    //\n    // For non-ASCII letters WITH Alt held down: fall through to the event.code\n    // fallback. macOS Option+letter combinations produce non-ASCII letters as\n    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n    // event.code still reflects the physical key. We want Alt+A to match even\n    // when Option+A fires event.key='å'.\n    if (\n      isSingleLetterKey(eventKey) &&\n      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)\n    ) {\n      return false\n    }\n  }\n\n  // Fallback to event.code for dead keys or single-char mismatches where\n  // event.key is a non-letter special character.\n  // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n  // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n  if (\n    event.code &&\n    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))\n  ) {\n    // fallback for letter keys (common with mac option + letter)\n    if (event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3)\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // fallback for number keys (common with mac option + num)\n    if (event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5)\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n    // but event.code still reports the physical key.\n    if (event.code in PUNCTUATION_CODE_MAP) {\n      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}

package/dist/match.d.cts

@@ -1,85 +0,0 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.cjs";
-
-//#region src/match.d.ts
-/**
- * Checks if a KeyboardEvent matches a hotkey.
- *
- * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
- * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
- * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
- * Letter keys are matched case-insensitively.
- *
- * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
- * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
- * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
- * In these cases, `event.code` is used to determine the physical key.
- *
- * @param event - The KeyboardEvent to check
- * @param hotkey - The hotkey string or ParsedHotkey to match against
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns True if the event matches the hotkey
- *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   if (matchesKeyboardEvent(event, 'Mod+S')) {
- *     event.preventDefault()
- *     handleSave()
- *   }
- * })
- * ```
- */
-declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
-/**
- * Options for creating a hotkey handler.
- */
-interface CreateHotkeyHandlerOptions {
-  /** Prevent the default browser action when the hotkey matches. Defaults to true */
-  preventDefault?: boolean;
-  /** Stop event propagation when the hotkey matches. Defaults to true */
-  stopPropagation?: boolean;
-  /** The target platform for resolving 'Mod' */
-  platform?: 'mac' | 'windows' | 'linux';
-}
-/**
- * Creates a keyboard event handler that calls the callback when the hotkey matches.
- *
- * @param hotkey - The hotkey string or ParsedHotkey to match
- * @param callback - The function to call when the hotkey matches
- * @param options - Options for matching and handling
- * @returns A function that can be used as an event handler
- *
- * @example
- * ```ts
- * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
- *   console.log(`${hotkey} was pressed`)
- *   handleSave()
- * })
- *
- * document.addEventListener('keydown', handler)
- * ```
- */
-declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
-/**
- * Creates a handler that matches multiple hotkeys.
- *
- * @param handlers - A map of hotkey strings to their handlers
- * @param options - Options for matching and handling
- * @returns A function that can be used as an event handler
- *
- * @example
- * ```ts
- * const handler = createMultiHotkeyHandler({
- *   'Mod+S': (event, { hotkey }) => handleSave(),
- *   'Mod+Z': (event, { hotkey }) => handleUndo(),
- *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
- * })
- *
- * document.addEventListener('keydown', handler)
- * ```
- */
-declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-//#endregion
-export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
-//# sourceMappingURL=match.d.cts.map

package/dist/match.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import {\n  PUNCTUATION_CODE_MAP,\n  detectPlatform,\n  isSingleLetterKey,\n  normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single-character keys (not dead keys), try direct event.key match first\n  if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // If event.key is a letter, we usually trust the keyboard layout.\n    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n    //\n    // For non-ASCII letters WITH Alt held down: fall through to the event.code\n    // fallback. macOS Option+letter combinations produce non-ASCII letters as\n    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n    // event.code still reflects the physical key. We want Alt+A to match even\n    // when Option+A fires event.key='å'.\n    if (\n      isSingleLetterKey(eventKey) &&\n      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)\n    ) {\n      return false\n    }\n  }\n\n  // Fallback to event.code for dead keys or single-char mismatches where\n  // event.key is a non-letter special character.\n  // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n  // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n  if (\n    event.code &&\n    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))\n  ) {\n    // fallback for letter keys (common with mac option + letter)\n    if (event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3)\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // fallback for number keys (common with mac option + num)\n    if (event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5)\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n    // but event.code still reports the physical key.\n    if (event.code in PUNCTUATION_CODE_MAP) {\n      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}

package/dist/parse.cjs

@@ -1,228 +0,0 @@
-const require_constants = require('./constants.cjs');
-
-//#region src/parse.ts
-/**
-* Parses a hotkey string into its component parts.
-*
-* @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey object with the key and modifier flags
-*
-* @example
-* ```ts
-* parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
-* parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
-* parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
-* ```
-*/
-function parseHotkey(hotkey, platform = require_constants.detectPlatform()) {
-	const parts = hotkey.split("+");
-	const modifiers = /* @__PURE__ */ new Set();
-	let key = "";
-	for (let i = 0; i < parts.length; i++) {
-		const part = parts[i].trim();
-		if (i === parts.length - 1) key = require_constants.normalizeKeyName(part);
-		else {
-			const alias = require_constants.MODIFIER_ALIASES[part] ?? require_constants.MODIFIER_ALIASES[part.toLowerCase()];
-			if (alias) {
-				const resolved = require_constants.resolveModifier(alias, platform);
-				modifiers.add(resolved);
-			} else if (parts.length === 1) key = require_constants.normalizeKeyName(part);
-		}
-	}
-	if (!key && parts.length > 0) key = require_constants.normalizeKeyName(parts[parts.length - 1].trim());
-	return {
-		key,
-		ctrl: modifiers.has("Control"),
-		shift: modifiers.has("Shift"),
-		alt: modifiers.has("Alt"),
-		meta: modifiers.has("Meta"),
-		modifiers: require_constants.MODIFIER_ORDER.filter((m) => modifiers.has(m))
-	};
-}
-/**
-* Converts a RawHotkey object to a ParsedHotkey.
-* Optional modifier booleans default to false; modifiers array is derived from them.
-* When `mod` is true, it is resolved to Control or Meta based on platform.
-*
-* @param raw - The raw hotkey object
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey suitable for matching and formatting
-*
-* @example
-* ```ts
-* rawHotkeyToParsedHotkey({ key: 'Escape' })
-* // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
-*
-* rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
-* // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
-*
-* rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
-* // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
-* ```
-*/
-function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatform()) {
-	let ctrl = raw.ctrl ?? false;
-	const shift = raw.shift ?? false;
-	const alt = raw.alt ?? false;
-	let meta = raw.meta ?? false;
-	if (raw.mod) if (require_constants.resolveModifier("Mod", platform) === "Control") ctrl = true;
-	else meta = true;
-	const modifiers = require_constants.MODIFIER_ORDER.filter((m) => {
-		switch (m) {
-			case "Control": return ctrl;
-			case "Shift": return shift;
-			case "Alt": return alt;
-			case "Meta": return meta;
-			default: return false;
-		}
-	});
-	return {
-		key: raw.key,
-		ctrl,
-		shift,
-		alt,
-		meta,
-		modifiers
-	};
-}
-/**
-* Serializes a parsed hotkey to the canonical string form used for registration
-* and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
-* otherwise full `Control+Alt+Shift+Meta` order.
-*/
-function normalizedHotkeyStringFromParsed(parsed, platform) {
-	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
-	const parts = [];
-	if (canUseMod) {
-		parts.push("Mod");
-		if (parsed.alt) parts.push("Alt");
-		if (parsed.shift) parts.push("Shift");
-	} else for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(require_constants.normalizeKeyName(parsed.key));
-	return parts.join("+");
-}
-/**
-* Normalizes a hotkey string to its canonical form.
-*
-* - When `Mod` is allowed for the platform (Command on Mac without Control;
-*   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
-*   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
-* - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
-* - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
-*
-* @param hotkey - The hotkey string to normalize
-* @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
-* @returns The normalized hotkey string
-*
-* @example
-* ```ts
-* normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
-* normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
-* normalizeHotkey('esc') // 'Escape'
-* ```
-*/
-function normalizeHotkey(hotkey, platform = require_constants.detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseHotkey(hotkey, platform), platform);
-}
-/**
-* Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
-*/
-function normalizeHotkeyFromParsed(parsed, platform = require_constants.detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parsed, platform);
-}
-/**
-* Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
-* Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
-*/
-function normalizeRegisterableHotkey(hotkey, platform = require_constants.detectPlatform()) {
-	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
-}
-/**
-* Checks if a string is a recognized modifier token (including aliases).
-*
-* For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
-* spellings like `OS` / `Win` match the same alias table.
-*
-* @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
-* @returns True if the string is a recognized modifier
-*/
-function isModifierKey(key) {
-	return key in require_constants.MODIFIER_ALIASES || key.toLowerCase() in require_constants.MODIFIER_ALIASES;
-}
-/**
-* Parses a KeyboardEvent into a ParsedHotkey object.
-*
-* This function extracts the key and modifier state from a keyboard event
-* and converts it into the same format used by `parseHotkey()`.
-*
-* @param event - The KeyboardEvent to parse
-* @param platform - The target platform for resolving modifiers (defaults to auto-detection)
-* @returns A ParsedHotkey object representing the keyboard event
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   const parsed = parseKeyboardEvent(event)
-*   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
-* })
-* ```
-*/
-function parseKeyboardEvent(event) {
-	const normalizedKey = require_constants.normalizeKeyName(event.key);
-	const modifiers = [];
-	if (event.ctrlKey) modifiers.push("Control");
-	if (event.altKey) modifiers.push("Alt");
-	if (event.shiftKey) modifiers.push("Shift");
-	if (event.metaKey) modifiers.push("Meta");
-	return {
-		key: normalizedKey,
-		ctrl: event.ctrlKey,
-		shift: event.shiftKey,
-		alt: event.altKey,
-		meta: event.metaKey,
-		modifiers
-	};
-}
-/**
-* Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
-*
-* @param event - The keyboard event (typically `keydown`)
-* @param platform - Target platform for `Mod` eligibility
-*/
-function normalizeHotkeyFromEvent(event, platform = require_constants.detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
-}
-/**
-* Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
-*
-* This is useful for validating that a recorded hotkey is complete and not
-* just a combination of modifiers without an action key.
-*
-* @param hotkey - The hotkey string or ParsedHotkey to check
-* @param platform - The target platform for parsing (defaults to auto-detection)
-* @returns True if the hotkey contains at least one non-modifier key
-*
-* @example
-* ```ts
-* hasNonModifierKey('Control+Shift+S') // true
-* hasNonModifierKey('Control+Shift') // false (no action key)
-* hasNonModifierKey(parseHotkey('Mod+A')) // true
-* ```
-*/
-function hasNonModifierKey(hotkey, platform = require_constants.detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
-	return !isModifierKey(parsed.key) && parsed.key.length > 0;
-}
-
-//#endregion
-exports.hasNonModifierKey = hasNonModifierKey;
-exports.isModifierKey = isModifierKey;
-exports.normalizeHotkey = normalizeHotkey;
-exports.normalizeHotkeyFromEvent = normalizeHotkeyFromEvent;
-exports.normalizeHotkeyFromParsed = normalizeHotkeyFromParsed;
-exports.normalizeRegisterableHotkey = normalizeRegisterableHotkey;
-exports.parseHotkey = parseHotkey;
-exports.parseKeyboardEvent = parseKeyboardEvent;
-exports.rawHotkeyToParsedHotkey = rawHotkeyToParsedHotkey;
-//# sourceMappingURL=parse.cjs.map

package/dist/parse.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"parse.cjs","names":["detectPlatform","normalizeKeyName","MODIFIER_ALIASES","resolveModifier","MODIFIER_ORDER"],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  detectPlatform,\n  normalizeKeyName,\n  resolveModifier,\n} from './constants'\nimport type {\n  CanonicalModifier,\n  Hotkey,\n  Key,\n  ParsedHotkey,\n  RawHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\n/**\n * Parses a hotkey string into its component parts.\n *\n * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey object with the key and modifier flags\n *\n * @example\n * ```ts\n * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }\n * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function parseHotkey(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  const parts = hotkey.split('+')\n  const modifiers: Set<CanonicalModifier> = new Set()\n  let key = ''\n\n  for (let i = 0; i < parts.length; i++) {\n    const part = parts[i]!.trim()\n\n    if (i === parts.length - 1) {\n      // Last part is always the key\n      key = normalizeKeyName(part)\n    } else {\n      // All other parts are modifiers\n      const alias =\n        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]\n\n      if (alias) {\n        const resolved = resolveModifier(alias, platform)\n        modifiers.add(resolved)\n      } else {\n        // Unknown modifier, treat as part of the key if it's the only part\n        // or ignore if there are more parts\n        if (parts.length === 1) {\n          key = normalizeKeyName(part)\n        }\n      }\n    }\n  }\n\n  // If no key was found (empty string), use the last part as-is\n  if (!key && parts.length > 0) {\n    key = normalizeKeyName(parts[parts.length - 1]!.trim())\n  }\n\n  return {\n    key,\n    ctrl: modifiers.has('Control'),\n    shift: modifiers.has('Shift'),\n    alt: modifiers.has('Alt'),\n    meta: modifiers.has('Meta'),\n    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),\n  }\n}\n\n/**\n * Converts a RawHotkey object to a ParsedHotkey.\n * Optional modifier booleans default to false; modifiers array is derived from them.\n * When `mod` is true, it is resolved to Control or Meta based on platform.\n *\n * @param raw - The raw hotkey object\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey suitable for matching and formatting\n *\n * @example\n * ```ts\n * rawHotkeyToParsedHotkey({ key: 'Escape' })\n * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')\n * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')\n * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function rawHotkeyToParsedHotkey(\n  raw: RawHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  let ctrl = raw.ctrl ?? false\n  const shift = raw.shift ?? false\n  const alt = raw.alt ?? false\n  let meta = raw.meta ?? false\n\n  if (raw.mod) {\n    const resolved = resolveModifier('Mod', platform)\n    if (resolved === 'Control') {\n      ctrl = true\n    } else {\n      meta = true\n    }\n  }\n\n  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {\n    switch (m) {\n      case 'Control':\n        return ctrl\n      case 'Shift':\n        return shift\n      case 'Alt':\n        return alt\n      case 'Meta':\n        return meta\n      default:\n        return false\n    }\n  })\n  return {\n    key: raw.key,\n    ctrl,\n    shift,\n    alt,\n    meta,\n    modifiers,\n  }\n}\n\n/**\n * Serializes a parsed hotkey to the canonical string form used for registration\n * and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;\n * otherwise full `Control+Alt+Shift+Meta` order.\n */\nfunction normalizedHotkeyStringFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey {\n  const canUseMod =\n    platform === 'mac'\n      ? parsed.meta && !parsed.ctrl\n      : parsed.ctrl && !parsed.meta\n\n  const parts: Array<string> = []\n\n  if (canUseMod) {\n    parts.push('Mod')\n    if (parsed.alt) {\n      parts.push('Alt')\n    }\n    if (parsed.shift) {\n      parts.push('Shift')\n    }\n  } else {\n    for (const modifier of MODIFIER_ORDER) {\n      if (parsed.modifiers.includes(modifier)) {\n        parts.push(modifier)\n      }\n    }\n  }\n\n  parts.push(normalizeKeyName(parsed.key))\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Normalizes a hotkey string to its canonical form.\n *\n * - When `Mod` is allowed for the platform (Command on Mac without Control;\n *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,\n *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).\n * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.\n * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).\n *\n * @param hotkey - The hotkey string to normalize\n * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)\n * @returns The normalized hotkey string\n *\n * @example\n * ```ts\n * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'\n * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'\n * normalizeHotkey('esc') // 'Escape'\n * ```\n */\nexport function normalizeHotkey(\n  hotkey: Key | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(\n    parseHotkey(hotkey, platform),\n    platform,\n  )\n}\n\n/**\n * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.\n */\nexport function normalizeHotkeyFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parsed, platform)\n}\n\n/**\n * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.\n * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.\n */\nexport function normalizeRegisterableHotkey(\n  hotkey: RegisterableHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return typeof hotkey === 'string'\n    ? normalizeHotkey(hotkey, platform)\n    : normalizeHotkeyFromParsed(\n        rawHotkeyToParsedHotkey(hotkey, platform),\n        platform,\n      )\n}\n\n/**\n * Checks if a string is a recognized modifier token (including aliases).\n *\n * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM\n * spellings like `OS` / `Win` match the same alias table.\n *\n * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)\n * @returns True if the string is a recognized modifier\n */\nexport function isModifierKey(\n  key: Key | (string & {}),\n): key is keyof typeof MODIFIER_ALIASES {\n  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES\n}\n\n/**\n * Parses a KeyboardEvent into a ParsedHotkey object.\n *\n * This function extracts the key and modifier state from a keyboard event\n * and converts it into the same format used by `parseHotkey()`.\n *\n * @param event - The KeyboardEvent to parse\n * @param platform - The target platform for resolving modifiers (defaults to auto-detection)\n * @returns A ParsedHotkey object representing the keyboard event\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const parsed = parseKeyboardEvent(event)\n *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }\n * })\n * ```\n */\nexport function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {\n  const normalizedKey = normalizeKeyName(event.key)\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (event.ctrlKey) modifiers.push('Control')\n  if (event.altKey) modifiers.push('Alt')\n  if (event.shiftKey) modifiers.push('Shift')\n  if (event.metaKey) modifiers.push('Meta')\n\n  return {\n    key: normalizedKey,\n    ctrl: event.ctrlKey,\n    shift: event.shiftKey,\n    alt: event.altKey,\n    meta: event.metaKey,\n    modifiers,\n  }\n}\n\n/**\n * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.\n *\n * @param event - The keyboard event (typically `keydown`)\n * @param platform - Target platform for `Mod` eligibility\n */\nexport function normalizeHotkeyFromEvent(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform)\n}\n\n/**\n * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.\n *\n * This is useful for validating that a recorded hotkey is complete and not\n * just a combination of modifiers without an action key.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to check\n * @param platform - The target platform for parsing (defaults to auto-detection)\n * @returns True if the hotkey contains at least one non-modifier key\n *\n * @example\n * ```ts\n * hasNonModifierKey('Control+Shift+S') // true\n * hasNonModifierKey('Control+Shift') // false (no action key)\n * hasNonModifierKey(parseHotkey('Mod+A')) // true\n * ```\n */\nexport function hasNonModifierKey(\n  hotkey: Hotkey | ParsedHotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check if the key part is actually a modifier\n  const keyIsModifier = isModifierKey(parsed.key)\n\n  // A valid hotkey must have a non-modifier key\n  return !keyIsModifier && parsed.key.length > 0\n}\n"],"mappings":"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"}