@tanstack/hotkeys 0.1.3 → 0.3.0

package/dist/format.cjs

@@ -3,6 +3,21 @@ const require_parse = require('./parse.cjs');
 
 //#region src/format.ts
 /**
+* Converts a hotkey sequence array to a display string.
+*
+* @param sequence - Array of hotkey strings that form the sequence
+* @returns A space-separated string (e.g. ['G','G'] → 'G G')
+*
+* @example
+* ```ts
+* formatHotkeySequence(['G', 'G'])      // 'G G'
+* formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
+* ```
+*/
+function formatHotkeySequence(sequence) {
+	return sequence.join(" ");
+}
+/**
 * Converts a ParsedHotkey back to a hotkey string.
 *
 * @param parsed - The parsed hotkey object
@@ -173,6 +188,7 @@ function formatKeyForDebuggingDisplay(key, options = {}) {
 //#endregion
 exports.formatForDisplay = formatForDisplay;
 exports.formatHotkey = formatHotkey;
+exports.formatHotkeySequence = formatHotkeySequence;
 exports.formatKeyForDebuggingDisplay = formatKeyForDebuggingDisplay;
 exports.formatWithLabels = formatWithLabels;
 //# sourceMappingURL=format.cjs.map

package/dist/format.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"format.cjs","names":["MODIFIER_ORDER","detectPlatform","parseHotkey","MAC_MODIFIER_SYMBOLS","KEY_DISPLAY_SYMBOLS","STANDARD_MODIFIER_LABELS"],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ORDER,\n  STANDARD_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S).\n * On Windows/Linux, uses text (Ctrl+Shift+S).\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⇧⌘S'\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: Hotkey | (string & {}) | ParsedHotkey,\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  if (platform === 'mac') {\n    return formatForMac(parsed)\n  }\n\n  return formatForStandard(parsed)\n}\n\n/**\n * Formats a hotkey for macOS display using symbols.\n */\nfunction formatForMac(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in macOS order (typically Control, Option, Shift, Command)\n  // But we'll use our canonical order and just use symbols\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(MAC_MODIFIER_SYMBOLS[modifier])\n    }\n  }\n\n  // Add the key (use symbol if available, otherwise the key itself)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Mac, modifiers are typically concatenated without separators\n  return parts.join('')\n}\n\n/**\n * Formats a hotkey for Windows/Linux display using text labels.\n */\nfunction formatForStandard(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(STANDARD_MODIFIER_LABELS[modifier])\n    }\n  }\n\n  // Add the key (use symbol/short form if available)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Windows/Linux, use + as separator\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey using platform-agnostic labels.\n * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param platform - The target platform\n * @returns A formatted string with platform-appropriate labels\n */\nexport function formatWithLabels(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const parts: Array<string> = []\n\n  // Custom labels for more readable output\n  const labels: Record<string, string> = {\n    Control: 'Ctrl',\n    Alt: platform === 'mac' ? 'Option' : 'Alt',\n    Shift: 'Shift',\n    Meta: platform === 'mac' ? 'Cmd' : 'Win',\n  }\n\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(labels[modifier] ?? modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n// =============================================================================\n// Debugging Display Labels\n// =============================================================================\n\n/**\n * Maps canonical modifier names to debugging-friendly labels per platform.\n */\nconst MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {\n  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },\n  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },\n  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },\n}\n\n/**\n * Options for formatting a single key for debugging display.\n */\nexport interface FormatKeyDebuggingOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /**\n   * Whether the input value comes from `event.key` or `event.code`.\n   *\n   * - `'key'` (default): Applies rich platform-aware formatting (modifier\n   *   labels, special-key symbols, etc.).\n   * - `'code'`: Returns the value unchanged — physical key codes like\n   *   `\"MetaLeft\"` or `\"KeyA\"` are already descriptive for debugging.\n   */\n  source?: 'key' | 'code'\n}\n\n/**\n * Formats a single key name for debugging/devtools display.\n *\n * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,\n * this function formats individual key names (from `event.key`) with rich\n * platform-aware labels suitable for debugging tools and developer-facing displays.\n *\n * Features:\n * - Modifier keys show their platform role (e.g., \"Mod (Cmd)\" for Meta on Mac)\n * - On macOS, modifier keys are prefixed with their symbol (e.g., \"⌘ Mod (Cmd)\")\n * - Special keys use display symbols (ArrowUp -> \"↑\", Escape -> \"Esc\")\n * - Regular keys pass through unchanged\n *\n * @param key - A single key name (e.g., \"Meta\", \"Shift\", \"ArrowUp\", \"A\")\n * @param options - Formatting options\n * @returns A formatted label suitable for debugging display\n *\n * @example\n * ```ts\n * // On macOS:\n * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'\n * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'\n * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'\n * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'\n *\n * // On Windows:\n * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'\n * formatKeyForDebuggingDisplay('Meta')    // 'Win'\n *\n * // Special keys (all platforms):\n * formatKeyForDebuggingDisplay('ArrowUp') // '↑'\n * formatKeyForDebuggingDisplay('Escape')  // 'Esc'\n * formatKeyForDebuggingDisplay('Space')   // '␣'\n *\n * // Regular keys pass through:\n * formatKeyForDebuggingDisplay('A')       // 'A'\n *\n * // With source: 'code', values pass through unchanged:\n * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'\n * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'\n * ```\n */\nexport function formatKeyForDebuggingDisplay(\n  key: string,\n  options: FormatKeyDebuggingOptions = {},\n): string {\n  // For event.code values, pass through unchanged — they're already\n  // descriptive for debugging (e.g. \"MetaLeft\", \"KeyA\", \"ShiftRight\").\n  if (options.source === 'code') {\n    return key\n  }\n\n  const platform = options.platform ?? detectPlatform()\n\n  // Check if it's a modifier key\n  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]\n  if (modLabel) {\n    // On Mac, prefix modifier labels with their symbol\n    if (platform === 'mac') {\n      const symbol =\n        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]\n      if (symbol) {\n        return `${symbol} ${modLabel}`\n      }\n    }\n    return modLabel\n  }\n\n  // Check if it's a special key with a display symbol\n  const symbol = KEY_DISPLAY_SYMBOLS[key]\n  if (symbol) {\n    return symbol\n  }\n\n  // Regular key — pass through\n  return key\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYA,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CACrD,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,aAAa,MACf,QAAO,aAAa,OAAO;AAG7B,QAAO,kBAAkB,OAAO;;;;;AAMlC,SAAS,aAAa,QAA8B;CAClD,MAAM,QAAuB,EAAE;AAI/B,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKG,uCAAqB,UAAU;CAK9C,MAAM,aAAaC,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,GAAG;;;;;AAMvB,SAAS,kBAAkB,QAA8B;CACvD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYJ,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKK,2CAAyB,UAAU;CAKlD,MAAM,aAAaD,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;AAWxB,SAAgB,iBACd,QACA,WAAwCH,kCAAgB,EAChD;CACR,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,QAAuB,EAAE;CAG/B,MAAM,SAAiC;EACrC,SAAS;EACT,KAAK,aAAa,QAAQ,WAAW;EACrC,OAAO;EACP,MAAM,aAAa,QAAQ,QAAQ;EACpC;AAED,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,OAAO,aAAa,SAAS;AAK5C,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;AAUxB,MAAM,wBAAgE;CACpE,KAAK;EAAE,MAAM;EAAa,SAAS;EAAQ,KAAK;EAAO,OAAO;EAAS;CACvE,SAAS;EAAE,SAAS;EAAc,MAAM;EAAO,KAAK;EAAO,OAAO;EAAS;CAC3E,OAAO;EAAE,SAAS;EAAc,MAAM;EAAS,KAAK;EAAO,OAAO;EAAS;CAC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DD,SAAgB,6BACd,KACA,UAAqC,EAAE,EAC/B;AAGR,KAAI,QAAQ,WAAW,OACrB,QAAO;CAGT,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CAGrD,MAAM,WAAW,sBAAsB,YAAY;AACnD,KAAI,UAAU;AAEZ,MAAI,aAAa,OAAO;GACtB,MAAM,SACJE,uCAAqB;AACvB,OAAI,OACF,QAAO,GAAG,OAAO,GAAG;;AAGxB,SAAO;;CAIT,MAAM,SAASC,sCAAoB;AACnC,KAAI,OACF,QAAO;AAIT,QAAO"}
+{"version":3,"file":"format.cjs","names":["MODIFIER_ORDER","detectPlatform","parseHotkey","MAC_MODIFIER_SYMBOLS","KEY_DISPLAY_SYMBOLS","STANDARD_MODIFIER_LABELS"],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ORDER,\n  STANDARD_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'\n\n/**\n * Converts a hotkey sequence array to a display string.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @returns A space-separated string (e.g. ['G','G'] → 'G G')\n *\n * @example\n * ```ts\n * formatHotkeySequence(['G', 'G'])      // 'G G'\n * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'\n * ```\n */\nexport function formatHotkeySequence(sequence: Array<Hotkey>): string {\n  return sequence.join(' ')\n}\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S).\n * On Windows/Linux, uses text (Ctrl+Shift+S).\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⇧⌘S'\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: Hotkey | (string & {}) | ParsedHotkey,\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  if (platform === 'mac') {\n    return formatForMac(parsed)\n  }\n\n  return formatForStandard(parsed)\n}\n\n/**\n * Formats a hotkey for macOS display using symbols.\n */\nfunction formatForMac(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in macOS order (typically Control, Option, Shift, Command)\n  // But we'll use our canonical order and just use symbols\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(MAC_MODIFIER_SYMBOLS[modifier])\n    }\n  }\n\n  // Add the key (use symbol if available, otherwise the key itself)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Mac, modifiers are typically concatenated without separators\n  return parts.join('')\n}\n\n/**\n * Formats a hotkey for Windows/Linux display using text labels.\n */\nfunction formatForStandard(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(STANDARD_MODIFIER_LABELS[modifier])\n    }\n  }\n\n  // Add the key (use symbol/short form if available)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Windows/Linux, use + as separator\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey using platform-agnostic labels.\n * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param platform - The target platform\n * @returns A formatted string with platform-appropriate labels\n */\nexport function formatWithLabels(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const parts: Array<string> = []\n\n  // Custom labels for more readable output\n  const labels: Record<string, string> = {\n    Control: 'Ctrl',\n    Alt: platform === 'mac' ? 'Option' : 'Alt',\n    Shift: 'Shift',\n    Meta: platform === 'mac' ? 'Cmd' : 'Win',\n  }\n\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(labels[modifier] ?? modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n// =============================================================================\n// Debugging Display Labels\n// =============================================================================\n\n/**\n * Maps canonical modifier names to debugging-friendly labels per platform.\n */\nconst MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {\n  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },\n  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },\n  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },\n}\n\n/**\n * Options for formatting a single key for debugging display.\n */\nexport interface FormatKeyDebuggingOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /**\n   * Whether the input value comes from `event.key` or `event.code`.\n   *\n   * - `'key'` (default): Applies rich platform-aware formatting (modifier\n   *   labels, special-key symbols, etc.).\n   * - `'code'`: Returns the value unchanged — physical key codes like\n   *   `\"MetaLeft\"` or `\"KeyA\"` are already descriptive for debugging.\n   */\n  source?: 'key' | 'code'\n}\n\n/**\n * Formats a single key name for debugging/devtools display.\n *\n * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,\n * this function formats individual key names (from `event.key`) with rich\n * platform-aware labels suitable for debugging tools and developer-facing displays.\n *\n * Features:\n * - Modifier keys show their platform role (e.g., \"Mod (Cmd)\" for Meta on Mac)\n * - On macOS, modifier keys are prefixed with their symbol (e.g., \"⌘ Mod (Cmd)\")\n * - Special keys use display symbols (ArrowUp -> \"↑\", Escape -> \"Esc\")\n * - Regular keys pass through unchanged\n *\n * @param key - A single key name (e.g., \"Meta\", \"Shift\", \"ArrowUp\", \"A\")\n * @param options - Formatting options\n * @returns A formatted label suitable for debugging display\n *\n * @example\n * ```ts\n * // On macOS:\n * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'\n * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'\n * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'\n * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'\n *\n * // On Windows:\n * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'\n * formatKeyForDebuggingDisplay('Meta')    // 'Win'\n *\n * // Special keys (all platforms):\n * formatKeyForDebuggingDisplay('ArrowUp') // '↑'\n * formatKeyForDebuggingDisplay('Escape')  // 'Esc'\n * formatKeyForDebuggingDisplay('Space')   // '␣'\n *\n * // Regular keys pass through:\n * formatKeyForDebuggingDisplay('A')       // 'A'\n *\n * // With source: 'code', values pass through unchanged:\n * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'\n * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'\n * ```\n */\nexport function formatKeyForDebuggingDisplay(\n  key: string,\n  options: FormatKeyDebuggingOptions = {},\n): string {\n  // For event.code values, pass through unchanged — they're already\n  // descriptive for debugging (e.g. \"MetaLeft\", \"KeyA\", \"ShiftRight\").\n  if (options.source === 'code') {\n    return key\n  }\n\n  const platform = options.platform ?? detectPlatform()\n\n  // Check if it's a modifier key\n  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]\n  if (modLabel) {\n    // On Mac, prefix modifier labels with their symbol\n    if (platform === 'mac') {\n      const symbol =\n        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]\n      if (symbol) {\n        return `${symbol} ${modLabel}`\n      }\n    }\n    return modLabel\n  }\n\n  // Check if it's a special key with a display symbol\n  const symbol = KEY_DISPLAY_SYMBOLS[key]\n  if (symbol) {\n    return symbol\n  }\n\n  // Regular key — pass through\n  return key\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,SAAgB,qBAAqB,UAAiC;AACpE,QAAO,SAAS,KAAK,IAAI;;;;;;;;;;;;;;AAe3B,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYA,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CACrD,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,aAAa,MACf,QAAO,aAAa,OAAO;AAG7B,QAAO,kBAAkB,OAAO;;;;;AAMlC,SAAS,aAAa,QAA8B;CAClD,MAAM,QAAuB,EAAE;AAI/B,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKG,uCAAqB,UAAU;CAK9C,MAAM,aAAaC,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,GAAG;;;;;AAMvB,SAAS,kBAAkB,QAA8B;CACvD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYJ,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAKK,2CAAyB,UAAU;CAKlD,MAAM,aAAaD,sCAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;AAWxB,SAAgB,iBACd,QACA,WAAwCH,kCAAgB,EAChD;CACR,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,QAAuB,EAAE;CAG/B,MAAM,SAAiC;EACrC,SAAS;EACT,KAAK,aAAa,QAAQ,WAAW;EACrC,OAAO;EACP,MAAM,aAAa,QAAQ,QAAQ;EACpC;AAED,MAAK,MAAM,YAAYF,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,OAAO,aAAa,SAAS;AAK5C,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;AAUxB,MAAM,wBAAgE;CACpE,KAAK;EAAE,MAAM;EAAa,SAAS;EAAQ,KAAK;EAAO,OAAO;EAAS;CACvE,SAAS;EAAE,SAAS;EAAc,MAAM;EAAO,KAAK;EAAO,OAAO;EAAS;CAC3E,OAAO;EAAE,SAAS;EAAc,MAAM;EAAS,KAAK;EAAO,OAAO;EAAS;CAC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DD,SAAgB,6BACd,KACA,UAAqC,EAAE,EAC/B;AAGR,KAAI,QAAQ,WAAW,OACrB,QAAO;CAGT,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CAGrD,MAAM,WAAW,sBAAsB,YAAY;AACnD,KAAI,UAAU;AAEZ,MAAI,aAAa,OAAO;GACtB,MAAM,SACJE,uCAAqB;AACvB,OAAI,OACF,QAAO,GAAG,OAAO,GAAG;;AAGxB,SAAO;;CAIT,MAAM,SAASC,sCAAoB;AACnC,KAAI,OACF,QAAO;AAIT,QAAO"}

package/dist/format.d.cts

@@ -1,6 +1,19 @@
 import { FormatDisplayOptions, Hotkey, ParsedHotkey } from "./hotkey.cjs";
 
 //#region src/format.d.ts
+/**
+ * Converts a hotkey sequence array to a display string.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence
+ * @returns A space-separated string (e.g. ['G','G'] → 'G G')
+ *
+ * @example
+ * ```ts
+ * formatHotkeySequence(['G', 'G'])      // 'G G'
+ * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
+ * ```
+ */
+declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
 /**
  * Converts a ParsedHotkey back to a hotkey string.
  *
@@ -106,5 +119,5 @@ interface FormatKeyDebuggingOptions {
  */
 declare function formatKeyForDebuggingDisplay(key: string, options?: FormatKeyDebuggingOptions): string;
 //#endregion
-export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels };
 //# sourceMappingURL=format.d.cts.map

package/dist/format.d.ts

@@ -1,6 +1,19 @@
 import { FormatDisplayOptions, Hotkey, ParsedHotkey } from "./hotkey.js";
 
 //#region src/format.d.ts
+/**
+ * Converts a hotkey sequence array to a display string.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence
+ * @returns A space-separated string (e.g. ['G','G'] → 'G G')
+ *
+ * @example
+ * ```ts
+ * formatHotkeySequence(['G', 'G'])      // 'G G'
+ * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
+ * ```
+ */
+declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
 /**
  * Converts a ParsedHotkey back to a hotkey string.
  *
@@ -106,5 +119,5 @@ interface FormatKeyDebuggingOptions {
  */
 declare function formatKeyForDebuggingDisplay(key: string, options?: FormatKeyDebuggingOptions): string;
 //#endregion
-export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels };
 //# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -3,6 +3,21 @@ import { parseHotkey } from "./parse.js";
 
 //#region src/format.ts
 /**
+* Converts a hotkey sequence array to a display string.
+*
+* @param sequence - Array of hotkey strings that form the sequence
+* @returns A space-separated string (e.g. ['G','G'] → 'G G')
+*
+* @example
+* ```ts
+* formatHotkeySequence(['G', 'G'])      // 'G G'
+* formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
+* ```
+*/
+function formatHotkeySequence(sequence) {
+	return sequence.join(" ");
+}
+/**
 * Converts a ParsedHotkey back to a hotkey string.
 *
 * @param parsed - The parsed hotkey object
@@ -171,5 +186,5 @@ function formatKeyForDebuggingDisplay(key, options = {}) {
 }
 
 //#endregion
-export { formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+export { formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels };
 //# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","names":[],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ORDER,\n  STANDARD_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S).\n * On Windows/Linux, uses text (Ctrl+Shift+S).\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⇧⌘S'\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: Hotkey | (string & {}) | ParsedHotkey,\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  if (platform === 'mac') {\n    return formatForMac(parsed)\n  }\n\n  return formatForStandard(parsed)\n}\n\n/**\n * Formats a hotkey for macOS display using symbols.\n */\nfunction formatForMac(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in macOS order (typically Control, Option, Shift, Command)\n  // But we'll use our canonical order and just use symbols\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(MAC_MODIFIER_SYMBOLS[modifier])\n    }\n  }\n\n  // Add the key (use symbol if available, otherwise the key itself)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Mac, modifiers are typically concatenated without separators\n  return parts.join('')\n}\n\n/**\n * Formats a hotkey for Windows/Linux display using text labels.\n */\nfunction formatForStandard(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(STANDARD_MODIFIER_LABELS[modifier])\n    }\n  }\n\n  // Add the key (use symbol/short form if available)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Windows/Linux, use + as separator\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey using platform-agnostic labels.\n * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param platform - The target platform\n * @returns A formatted string with platform-appropriate labels\n */\nexport function formatWithLabels(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const parts: Array<string> = []\n\n  // Custom labels for more readable output\n  const labels: Record<string, string> = {\n    Control: 'Ctrl',\n    Alt: platform === 'mac' ? 'Option' : 'Alt',\n    Shift: 'Shift',\n    Meta: platform === 'mac' ? 'Cmd' : 'Win',\n  }\n\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(labels[modifier] ?? modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n// =============================================================================\n// Debugging Display Labels\n// =============================================================================\n\n/**\n * Maps canonical modifier names to debugging-friendly labels per platform.\n */\nconst MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {\n  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },\n  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },\n  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },\n}\n\n/**\n * Options for formatting a single key for debugging display.\n */\nexport interface FormatKeyDebuggingOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /**\n   * Whether the input value comes from `event.key` or `event.code`.\n   *\n   * - `'key'` (default): Applies rich platform-aware formatting (modifier\n   *   labels, special-key symbols, etc.).\n   * - `'code'`: Returns the value unchanged — physical key codes like\n   *   `\"MetaLeft\"` or `\"KeyA\"` are already descriptive for debugging.\n   */\n  source?: 'key' | 'code'\n}\n\n/**\n * Formats a single key name for debugging/devtools display.\n *\n * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,\n * this function formats individual key names (from `event.key`) with rich\n * platform-aware labels suitable for debugging tools and developer-facing displays.\n *\n * Features:\n * - Modifier keys show their platform role (e.g., \"Mod (Cmd)\" for Meta on Mac)\n * - On macOS, modifier keys are prefixed with their symbol (e.g., \"⌘ Mod (Cmd)\")\n * - Special keys use display symbols (ArrowUp -> \"↑\", Escape -> \"Esc\")\n * - Regular keys pass through unchanged\n *\n * @param key - A single key name (e.g., \"Meta\", \"Shift\", \"ArrowUp\", \"A\")\n * @param options - Formatting options\n * @returns A formatted label suitable for debugging display\n *\n * @example\n * ```ts\n * // On macOS:\n * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'\n * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'\n * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'\n * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'\n *\n * // On Windows:\n * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'\n * formatKeyForDebuggingDisplay('Meta')    // 'Win'\n *\n * // Special keys (all platforms):\n * formatKeyForDebuggingDisplay('ArrowUp') // '↑'\n * formatKeyForDebuggingDisplay('Escape')  // 'Esc'\n * formatKeyForDebuggingDisplay('Space')   // '␣'\n *\n * // Regular keys pass through:\n * formatKeyForDebuggingDisplay('A')       // 'A'\n *\n * // With source: 'code', values pass through unchanged:\n * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'\n * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'\n * ```\n */\nexport function formatKeyForDebuggingDisplay(\n  key: string,\n  options: FormatKeyDebuggingOptions = {},\n): string {\n  // For event.code values, pass through unchanged — they're already\n  // descriptive for debugging (e.g. \"MetaLeft\", \"KeyA\", \"ShiftRight\").\n  if (options.source === 'code') {\n    return key\n  }\n\n  const platform = options.platform ?? detectPlatform()\n\n  // Check if it's a modifier key\n  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]\n  if (modLabel) {\n    // On Mac, prefix modifier labels with their symbol\n    if (platform === 'mac') {\n      const symbol =\n        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]\n      if (symbol) {\n        return `${symbol} ${modLabel}`\n      }\n    }\n    return modLabel\n  }\n\n  // Check if it's a special key with a display symbol\n  const symbol = KEY_DISPLAY_SYMBOLS[key]\n  if (symbol) {\n    return symbol\n  }\n\n  // Regular key — pass through\n  return key\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CACrD,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,aAAa,MACf,QAAO,aAAa,OAAO;AAG7B,QAAO,kBAAkB,OAAO;;;;;AAMlC,SAAS,aAAa,QAA8B;CAClD,MAAM,QAAuB,EAAE;AAI/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,qBAAqB,UAAU;CAK9C,MAAM,aAAa,oBAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,GAAG;;;;;AAMvB,SAAS,kBAAkB,QAA8B;CACvD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,yBAAyB,UAAU;CAKlD,MAAM,aAAa,oBAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;AAWxB,SAAgB,iBACd,QACA,WAAwC,gBAAgB,EAChD;CACR,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,QAAuB,EAAE;CAG/B,MAAM,SAAiC;EACrC,SAAS;EACT,KAAK,aAAa,QAAQ,WAAW;EACrC,OAAO;EACP,MAAM,aAAa,QAAQ,QAAQ;EACpC;AAED,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,OAAO,aAAa,SAAS;AAK5C,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;AAUxB,MAAM,wBAAgE;CACpE,KAAK;EAAE,MAAM;EAAa,SAAS;EAAQ,KAAK;EAAO,OAAO;EAAS;CACvE,SAAS;EAAE,SAAS;EAAc,MAAM;EAAO,KAAK;EAAO,OAAO;EAAS;CAC3E,OAAO;EAAE,SAAS;EAAc,MAAM;EAAS,KAAK;EAAO,OAAO;EAAS;CAC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DD,SAAgB,6BACd,KACA,UAAqC,EAAE,EAC/B;AAGR,KAAI,QAAQ,WAAW,OACrB,QAAO;CAGT,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CAGrD,MAAM,WAAW,sBAAsB,YAAY;AACnD,KAAI,UAAU;AAEZ,MAAI,aAAa,OAAO;GACtB,MAAM,SACJ,qBAAqB;AACvB,OAAI,OACF,QAAO,GAAG,OAAO,GAAG;;AAGxB,SAAO;;CAIT,MAAM,SAAS,oBAAoB;AACnC,KAAI,OACF,QAAO;AAIT,QAAO"}
+{"version":3,"file":"format.js","names":[],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ORDER,\n  STANDARD_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'\n\n/**\n * Converts a hotkey sequence array to a display string.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @returns A space-separated string (e.g. ['G','G'] → 'G G')\n *\n * @example\n * ```ts\n * formatHotkeySequence(['G', 'G'])      // 'G G'\n * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'\n * ```\n */\nexport function formatHotkeySequence(sequence: Array<Hotkey>): string {\n  return sequence.join(' ')\n}\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S).\n * On Windows/Linux, uses text (Ctrl+Shift+S).\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⇧⌘S'\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: Hotkey | (string & {}) | ParsedHotkey,\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  if (platform === 'mac') {\n    return formatForMac(parsed)\n  }\n\n  return formatForStandard(parsed)\n}\n\n/**\n * Formats a hotkey for macOS display using symbols.\n */\nfunction formatForMac(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in macOS order (typically Control, Option, Shift, Command)\n  // But we'll use our canonical order and just use symbols\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(MAC_MODIFIER_SYMBOLS[modifier])\n    }\n  }\n\n  // Add the key (use symbol if available, otherwise the key itself)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Mac, modifiers are typically concatenated without separators\n  return parts.join('')\n}\n\n/**\n * Formats a hotkey for Windows/Linux display using text labels.\n */\nfunction formatForStandard(parsed: ParsedHotkey): string {\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(STANDARD_MODIFIER_LABELS[modifier])\n    }\n  }\n\n  // Add the key (use symbol/short form if available)\n  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key\n  parts.push(keyDisplay)\n\n  // On Windows/Linux, use + as separator\n  return parts.join('+')\n}\n\n/**\n * Formats a hotkey using platform-agnostic labels.\n * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param platform - The target platform\n * @returns A formatted string with platform-appropriate labels\n */\nexport function formatWithLabels(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n  const parts: Array<string> = []\n\n  // Custom labels for more readable output\n  const labels: Record<string, string> = {\n    Control: 'Ctrl',\n    Alt: platform === 'mac' ? 'Option' : 'Alt',\n    Shift: 'Shift',\n    Meta: platform === 'mac' ? 'Cmd' : 'Win',\n  }\n\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(labels[modifier] ?? modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n// =============================================================================\n// Debugging Display Labels\n// =============================================================================\n\n/**\n * Maps canonical modifier names to debugging-friendly labels per platform.\n */\nconst MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {\n  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },\n  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },\n  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },\n}\n\n/**\n * Options for formatting a single key for debugging display.\n */\nexport interface FormatKeyDebuggingOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /**\n   * Whether the input value comes from `event.key` or `event.code`.\n   *\n   * - `'key'` (default): Applies rich platform-aware formatting (modifier\n   *   labels, special-key symbols, etc.).\n   * - `'code'`: Returns the value unchanged — physical key codes like\n   *   `\"MetaLeft\"` or `\"KeyA\"` are already descriptive for debugging.\n   */\n  source?: 'key' | 'code'\n}\n\n/**\n * Formats a single key name for debugging/devtools display.\n *\n * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,\n * this function formats individual key names (from `event.key`) with rich\n * platform-aware labels suitable for debugging tools and developer-facing displays.\n *\n * Features:\n * - Modifier keys show their platform role (e.g., \"Mod (Cmd)\" for Meta on Mac)\n * - On macOS, modifier keys are prefixed with their symbol (e.g., \"⌘ Mod (Cmd)\")\n * - Special keys use display symbols (ArrowUp -> \"↑\", Escape -> \"Esc\")\n * - Regular keys pass through unchanged\n *\n * @param key - A single key name (e.g., \"Meta\", \"Shift\", \"ArrowUp\", \"A\")\n * @param options - Formatting options\n * @returns A formatted label suitable for debugging display\n *\n * @example\n * ```ts\n * // On macOS:\n * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'\n * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'\n * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'\n * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'\n *\n * // On Windows:\n * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'\n * formatKeyForDebuggingDisplay('Meta')    // 'Win'\n *\n * // Special keys (all platforms):\n * formatKeyForDebuggingDisplay('ArrowUp') // '↑'\n * formatKeyForDebuggingDisplay('Escape')  // 'Esc'\n * formatKeyForDebuggingDisplay('Space')   // '␣'\n *\n * // Regular keys pass through:\n * formatKeyForDebuggingDisplay('A')       // 'A'\n *\n * // With source: 'code', values pass through unchanged:\n * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'\n * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'\n * ```\n */\nexport function formatKeyForDebuggingDisplay(\n  key: string,\n  options: FormatKeyDebuggingOptions = {},\n): string {\n  // For event.code values, pass through unchanged — they're already\n  // descriptive for debugging (e.g. \"MetaLeft\", \"KeyA\", \"ShiftRight\").\n  if (options.source === 'code') {\n    return key\n  }\n\n  const platform = options.platform ?? detectPlatform()\n\n  // Check if it's a modifier key\n  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]\n  if (modLabel) {\n    // On Mac, prefix modifier labels with their symbol\n    if (platform === 'mac') {\n      const symbol =\n        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]\n      if (symbol) {\n        return `${symbol} ${modLabel}`\n      }\n    }\n    return modLabel\n  }\n\n  // Check if it's a special key with a display symbol\n  const symbol = KEY_DISPLAY_SYMBOLS[key]\n  if (symbol) {\n    return symbol\n  }\n\n  // Regular key — pass through\n  return key\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,SAAgB,qBAAqB,UAAiC;AACpE,QAAO,SAAS,KAAK,IAAI;;;;;;;;;;;;;;AAe3B,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CACrD,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,aAAa,MACf,QAAO,aAAa,OAAO;AAG7B,QAAO,kBAAkB,OAAO;;;;;AAMlC,SAAS,aAAa,QAA8B;CAClD,MAAM,QAAuB,EAAE;AAI/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,qBAAqB,UAAU;CAK9C,MAAM,aAAa,oBAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,GAAG;;;;;AAMvB,SAAS,kBAAkB,QAA8B;CACvD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,yBAAyB,UAAU;CAKlD,MAAM,aAAa,oBAAoB,OAAO,QAAQ,OAAO;AAC7D,OAAM,KAAK,WAAW;AAGtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;AAWxB,SAAgB,iBACd,QACA,WAAwC,gBAAgB,EAChD;CACR,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;CAC/D,MAAM,QAAuB,EAAE;CAG/B,MAAM,SAAiC;EACrC,SAAS;EACT,KAAK,aAAa,QAAQ,WAAW;EACrC,OAAO;EACP,MAAM,aAAa,QAAQ,QAAQ;EACpC;AAED,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,OAAO,aAAa,SAAS;AAK5C,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;AAUxB,MAAM,wBAAgE;CACpE,KAAK;EAAE,MAAM;EAAa,SAAS;EAAQ,KAAK;EAAO,OAAO;EAAS;CACvE,SAAS;EAAE,SAAS;EAAc,MAAM;EAAO,KAAK;EAAO,OAAO;EAAS;CAC3E,OAAO;EAAE,SAAS;EAAc,MAAM;EAAS,KAAK;EAAO,OAAO;EAAS;CAC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DD,SAAgB,6BACd,KACA,UAAqC,EAAE,EAC/B;AAGR,KAAI,QAAQ,WAAW,OACrB,QAAO;CAGT,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CAGrD,MAAM,WAAW,sBAAsB,YAAY;AACnD,KAAI,UAAU;AAEZ,MAAI,aAAa,OAAO;GACtB,MAAM,SACJ,qBAAqB;AACvB,OAAI,OACF,QAAO,GAAG,OAAO,GAAG;;AAGxB,SAAO;;CAIT,MAAM,SAAS,oBAAoB;AACnC,KAAI,OACF,QAAO;AAIT,QAAO"}

package/dist/hotkey-manager.cjs

@@ -2,21 +2,10 @@ const require_constants = require('./constants.cjs');
 const require_parse = require('./parse.cjs');
 const require_format = require('./format.cjs');
 const require_match = require('./match.cjs');
+const require_manager_utils = require('./manager.utils.cjs');
 let _tanstack_store = require("@tanstack/store");
 
 //#region src/hotkey-manager.ts
-/**
-* Default options for hotkey registration.
-*/
-const defaultHotkeyOptions = {
-	preventDefault: true,
-	stopPropagation: true,
-	eventType: "keydown",
-	requireReset: false,
-	enabled: true,
-	ignoreInputs: true,
-	conflictBehavior: "warn"
-};
 let registrationIdCounter = 0;
 /**
 * Generates a unique ID for hotkey registrations.
@@ -25,15 +14,6 @@ function generateId() {
 	return `hotkey_${++registrationIdCounter}`;
 }
 /**
-* 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;
-}
-/**
 * Singleton manager for hotkey registrations.
 *
 * This class provides a centralized way to register and manage keyboard hotkeys.
@@ -127,15 +107,16 @@ var HotkeyManager = class HotkeyManager {
 		const target = options.target ?? document;
 		const conflictBehavior = options.conflictBehavior ?? "warn";
 		const conflictingRegistration = this.#findConflictingRegistration(hotkeyStr, target);
-		if (conflictingRegistration) this.#handleConflict(conflictingRegistration, hotkeyStr, conflictBehavior);
-		const resolvedIgnoreInputs = options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey);
+		if (conflictingRegistration) require_manager_utils.handleConflict(conflictingRegistration.id, hotkeyStr, conflictBehavior, (id) => this.#unregister(id));
+		const resolvedIgnoreInputs = options.ignoreInputs ?? require_manager_utils.getDefaultIgnoreInputs(parsedHotkey);
 		const registration = {
 			id,
 			hotkey: hotkeyStr,
 			parsedHotkey,
 			callback,
 			options: {
-				...defaultHotkeyOptions,
+				...require_manager_utils.defaultHotkeyOptions,
+				requireReset: false,
 				...options,
 				platform,
 				ignoreInputs: resolvedIgnoreInputs
@@ -239,10 +220,10 @@ var HotkeyManager = class HotkeyManager {
 		for (const id of targetRegs) {
 			const registration = this.registrations.state.get(id);
 			if (!registration) continue;
-			if (!this.#isEventForTarget(event, target)) continue;
+			if (!require_manager_utils.isEventForTarget(event, target)) continue;
 			if (!registration.options.enabled) continue;
 			if (registration.options.ignoreInputs !== false) {
-				if (this.#isInputElement(event.target)) {
+				if (require_manager_utils.isInputElement(event.target)) {
 					if (event.target !== registration.target) continue;
 				}
 			}
@@ -297,17 +278,6 @@ var HotkeyManager = class HotkeyManager {
 		};
 	}
 	/**
-	* Checks if an event is for the given target (originated from or bubbled to it).
-	*/
-	#isEventForTarget(event, target) {
-		if (target === document || target === window) return event.currentTarget === target || event.currentTarget === document.documentElement;
-		if (target instanceof HTMLElement) {
-			if (event.currentTarget === target) return true;
-			if (event.target instanceof Node && target.contains(event.target)) return true;
-		}
-		return false;
-	}
-	/**
 	* Finds an existing registration with the same hotkey and target.
 	*/
 	#findConflictingRegistration(hotkey, target) {
@@ -315,44 +285,6 @@ var HotkeyManager = class HotkeyManager {
 		return null;
 	}
 	/**
-	* Handles conflicts between hotkey registrations based on conflict behavior.
-	*/
-	#handleConflict(conflictingRegistration, hotkey, conflictBehavior) {
-		if (conflictBehavior === "allow") return;
-		if (conflictBehavior === "warn") {
-			console.warn(`Hotkey '${hotkey}' 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(`Hotkey '${hotkey}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
-		this.#unregister(conflictingRegistration.id);
-	}
-	/**
-	* Checks if an element is an input-like element that should be ignored.
-	*
-	* This includes:
-	* - HTMLInputElement (all input types except button, submit, reset)
-	* - HTMLTextAreaElement
-	* - HTMLSelectElement
-	* - Elements with contentEditable enabled
-	*
-	* Button-type inputs (button, submit, reset) are excluded so hotkeys like
-	* Mod+S and Escape fire when the user has tabbed to a form button.
-	*/
-	#isInputElement(element) {
-		if (!element) return false;
-		if (element instanceof HTMLInputElement) {
-			const type = element.type.toLowerCase();
-			if (type === "button" || type === "submit" || type === "reset") return false;
-			return true;
-		}
-		if (element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) return true;
-		if (element instanceof HTMLElement) {
-			const contentEditable = element.contentEditable;
-			if (contentEditable === "true" || contentEditable === "") return true;
-		}
-		return false;
-	}
-	/**
 	* Determines if a registration should be reset based on the keyup event.
 	*/
 	#shouldResetRegistration(registration, event) {

package/dist/hotkey-manager.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#handleConflict","#targetRegistrations","#ensureListenersForTarget","#unregister","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","#isEventForTarget","#isInputElement","matchesKeyboardEvent","#executeHotkeyCallback","#shouldResetRegistration","#processTargetEvent","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform, normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\n/**\n * Behavior when registering a hotkey that conflicts with an existing registration.\n *\n * - `'warn'` - Log a warning to the console but allow both registrations (default)\n * - `'error'` - Throw an error and prevent the new registration\n * - `'replace'` - Unregister the existing hotkey and register the new one\n * - `'allow'` - Allow multiple registrations of the same hotkey without warning\n */\nexport type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow'\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /** Whether the hotkey is enabled. Defaults to true */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\n/**\n * Default options for hotkey registration.\n */\nconst defaultHotkeyOptions: Omit<\n  Required<HotkeyOptions>,\n  'platform' | 'target'\n> = {\n  preventDefault: true,\n  stopPropagation: true,\n  eventType: 'keydown',\n  requireReset: false,\n  enabled: true,\n  ignoreInputs: true,\n  conflictBehavior: 'warn',\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Computes the default ignoreInputs value based on the hotkey.\n * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.\n */\nfunction getDefaultIgnoreInputs(parsedHotkey: ParsedHotkey): boolean {\n  if (parsedHotkey.ctrl || parsedHotkey.meta) return false // Mod+S, Ctrl+C, etc.\n  if (parsedHotkey.key === 'Escape') return false // Close modal, etc.\n  return true // Single keys, Shift+key, Alt+key\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      this.#handleConflict(conflictingRegistration, hotkeyStr, conflictBehavior)\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (reg) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!this.#isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (this.#isInputElement(event.target)) {\n          // Don't ignore if the hotkey is explicitly scoped to this input element\n          if (event.target !== registration.target) {\n            continue\n          }\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        // Check if the hotkey matches first\n        const matches = matchesKeyboardEvent(\n          event,\n          registration.parsedHotkey,\n          registration.options.platform,\n        )\n\n        if (matches) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          if (\n            matchesKeyboardEvent(\n              event,\n              registration.parsedHotkey,\n              registration.options.platform,\n            )\n          ) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n\n        // Reset hasFired when any key in the hotkey is released\n        if (registration.options.requireReset && registration.hasFired) {\n          if (this.#shouldResetRegistration(registration, event)) {\n            registration.hasFired = false\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Checks if an event is for the given target (originated from or bubbled to it).\n   */\n  #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 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\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey && registration.target === target) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Handles conflicts between hotkey registrations based on conflict behavior.\n   */\n  #handleConflict(\n    conflictingRegistration: HotkeyRegistration,\n    hotkey: Hotkey,\n    conflictBehavior: ConflictBehavior,\n  ): void {\n    if (conflictBehavior === 'allow') {\n      return\n    }\n\n    if (conflictBehavior === 'warn') {\n      console.warn(\n        `Hotkey '${hotkey}' is already registered. Multiple handlers will be triggered. ` +\n          `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n          `or conflictBehavior: 'allow' to suppress this warning.`,\n      )\n      return\n    }\n\n    if (conflictBehavior === 'error') {\n      throw new Error(\n        `Hotkey '${hotkey}' is already registered. ` +\n          `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n          `or conflictBehavior: 'allow' to allow multiple registrations.`,\n      )\n    }\n\n    // At this point, conflictBehavior must be 'replace'\n    this.#unregister(conflictingRegistration.id)\n  }\n\n  /**\n   * Checks if an element is an input-like element that should be ignored.\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   */\n  #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\n    if (element instanceof HTMLElement) {\n      const contentEditable = element.contentEditable\n      if (contentEditable === 'true' || contentEditable === '') {\n        return true\n      }\n    }\n\n    return false\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    // Reset if the main key is released\n    // Compare case-insensitively for single-letter keys\n    const parsedKeyNormalized =\n      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n    const releasedKeyNormalized =\n      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n\n    if (releasedKeyNormalized === parsedKeyNormalized) {\n      return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        key: parsed.key,\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}
+{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#unregister","getDefaultIgnoreInputs","defaultHotkeyOptions","#targetRegistrations","#ensureListenersForTarget","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","isEventForTarget","isInputElement","matchesKeyboardEvent","#executeHotkeyCallback","#shouldResetRegistration","#processTargetEvent","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform, normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport {\n  defaultHotkeyOptions,\n  getDefaultIgnoreInputs,\n  handleConflict,\n  isEventForTarget,\n  isInputElement,\n} from './manager.utils'\nimport type { ConflictBehavior } from './manager.utils'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\nexport type { ConflictBehavior }\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /** Whether the hotkey is enabled. Defaults to true */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      handleConflict(\n        conflictingRegistration.id,\n        hotkeyStr,\n        conflictBehavior,\n        (id) => this.#unregister(id),\n      )\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      requireReset: false,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (reg) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (isInputElement(event.target)) {\n          // Don't ignore if the hotkey is explicitly scoped to this input element\n          if (event.target !== registration.target) {\n            continue\n          }\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        // Check if the hotkey matches first\n        const matches = matchesKeyboardEvent(\n          event,\n          registration.parsedHotkey,\n          registration.options.platform,\n        )\n\n        if (matches) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          if (\n            matchesKeyboardEvent(\n              event,\n              registration.parsedHotkey,\n              registration.options.platform,\n            )\n          ) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n\n        // Reset hasFired when any key in the hotkey is released\n        if (registration.options.requireReset && registration.hasFired) {\n          if (this.#shouldResetRegistration(registration, event)) {\n            registration.hasFired = false\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey && registration.target === target) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    // Reset if the main key is released\n    // Compare case-insensitively for single-letter keys\n    const parsedKeyNormalized =\n      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n    const releasedKeyNormalized =\n      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n\n    if (releasedKeyNormalized === parsedKeyNormalized) {\n      return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        key: parsed.key,\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}

package/dist/hotkey-manager.d.cts

@@ -1,16 +1,8 @@
 import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { ConflictBehavior } from "./manager.utils.cjs";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.d.ts
-/**
- * Behavior when registering a hotkey that conflicts with an existing registration.
- *
- * - `'warn'` - Log a warning to the console but allow both registrations (default)
- * - `'error'` - Throw an error and prevent the new registration
- * - `'replace'` - Unregister the existing hotkey and register the new one
- * - `'allow'` - Allow multiple registrations of the same hotkey without warning
- */
-type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
 /**
  * Options for registering a hotkey.
  */
@@ -203,5 +195,5 @@ declare class HotkeyManager {
  */
 declare function getHotkeyManager(): HotkeyManager;
 //#endregion
-export { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
 //# sourceMappingURL=hotkey-manager.d.cts.map

package/dist/hotkey-manager.d.ts

@@ -1,16 +1,8 @@
 import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
+import { ConflictBehavior } from "./manager.utils.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.d.ts
-/**
- * Behavior when registering a hotkey that conflicts with an existing registration.
- *
- * - `'warn'` - Log a warning to the console but allow both registrations (default)
- * - `'error'` - Throw an error and prevent the new registration
- * - `'replace'` - Unregister the existing hotkey and register the new one
- * - `'allow'` - Allow multiple registrations of the same hotkey without warning
- */
-type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
 /**
  * Options for registering a hotkey.
  */
@@ -203,5 +195,5 @@ declare class HotkeyManager {
  */
 declare function getHotkeyManager(): HotkeyManager;
 //#endregion
-export { ConflictBehavior, HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
 //# sourceMappingURL=hotkey-manager.d.ts.map