@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/format.d.cts

@@ -0,0 +1,110 @@
+import { FormatDisplayOptions, Hotkey, ParsedHotkey } from "./hotkey.cjs";
+
+//#region src/format.d.ts
+/**
+ * Converts a ParsedHotkey back to a hotkey string.
+ *
+ * @param parsed - The parsed hotkey object
+ * @returns A hotkey string in canonical form
+ *
+ * @example
+ * ```ts
+ * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
+ * // Returns: 'Control+Shift+S'
+ * ```
+ */
+declare function formatHotkey(parsed: ParsedHotkey): string;
+/**
+ * Formats a hotkey for display in a user interface.
+ *
+ * On macOS, uses symbols (⌘⇧S).
+ * On Windows/Linux, uses text (Ctrl+Shift+S).
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param options - Formatting options
+ * @returns A formatted string suitable for display
+ *
+ * @example
+ * ```ts
+ * formatForDisplay('Mod+Shift+S', { platform: 'mac' })
+ * // Returns: '⇧⌘S'
+ *
+ * formatForDisplay('Mod+Shift+S', { platform: 'windows' })
+ * // Returns: 'Ctrl+Shift+S'
+ *
+ * formatForDisplay('Escape')
+ * // Returns: 'Esc' (on all platforms)
+ * ```
+ */
+declare function formatForDisplay(hotkey: Hotkey | (string & {}) | ParsedHotkey, options?: FormatDisplayOptions): string;
+/**
+ * Formats a hotkey using platform-agnostic labels.
+ * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param platform - The target platform
+ * @returns A formatted string with platform-appropriate labels
+ */
+declare function formatWithLabels(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+/**
+ * Options for formatting a single key for debugging display.
+ */
+interface FormatKeyDebuggingOptions {
+  /** The target platform. Defaults to auto-detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /**
+   * Whether the input value comes from `event.key` or `event.code`.
+   *
+   * - `'key'` (default): Applies rich platform-aware formatting (modifier
+   *   labels, special-key symbols, etc.).
+   * - `'code'`: Returns the value unchanged — physical key codes like
+   *   `"MetaLeft"` or `"KeyA"` are already descriptive for debugging.
+   */
+  source?: 'key' | 'code';
+}
+/**
+ * Formats a single key name for debugging/devtools display.
+ *
+ * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
+ * this function formats individual key names (from `event.key`) with rich
+ * platform-aware labels suitable for debugging tools and developer-facing displays.
+ *
+ * Features:
+ * - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
+ * - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
+ * - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
+ * - Regular keys pass through unchanged
+ *
+ * @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
+ * @param options - Formatting options
+ * @returns A formatted label suitable for debugging display
+ *
+ * @example
+ * ```ts
+ * // On macOS:
+ * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
+ * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
+ * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
+ * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
+ *
+ * // On Windows:
+ * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
+ * formatKeyForDebuggingDisplay('Meta')    // 'Win'
+ *
+ * // Special keys (all platforms):
+ * formatKeyForDebuggingDisplay('ArrowUp') // '↑'
+ * formatKeyForDebuggingDisplay('Escape')  // 'Esc'
+ * formatKeyForDebuggingDisplay('Space')   // '␣'
+ *
+ * // Regular keys pass through:
+ * formatKeyForDebuggingDisplay('A')       // 'A'
+ *
+ * // With source: 'code', values pass through unchanged:
+ * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
+ * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
+ * ```
+ */
+declare function formatKeyForDebuggingDisplay(key: string, options?: FormatKeyDebuggingOptions): string;
+//#endregion
+export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+//# sourceMappingURL=format.d.cts.map

package/dist/format.d.ts

@@ -0,0 +1,110 @@
+import { FormatDisplayOptions, Hotkey, ParsedHotkey } from "./hotkey.js";
+
+//#region src/format.d.ts
+/**
+ * Converts a ParsedHotkey back to a hotkey string.
+ *
+ * @param parsed - The parsed hotkey object
+ * @returns A hotkey string in canonical form
+ *
+ * @example
+ * ```ts
+ * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
+ * // Returns: 'Control+Shift+S'
+ * ```
+ */
+declare function formatHotkey(parsed: ParsedHotkey): string;
+/**
+ * Formats a hotkey for display in a user interface.
+ *
+ * On macOS, uses symbols (⌘⇧S).
+ * On Windows/Linux, uses text (Ctrl+Shift+S).
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param options - Formatting options
+ * @returns A formatted string suitable for display
+ *
+ * @example
+ * ```ts
+ * formatForDisplay('Mod+Shift+S', { platform: 'mac' })
+ * // Returns: '⇧⌘S'
+ *
+ * formatForDisplay('Mod+Shift+S', { platform: 'windows' })
+ * // Returns: 'Ctrl+Shift+S'
+ *
+ * formatForDisplay('Escape')
+ * // Returns: 'Esc' (on all platforms)
+ * ```
+ */
+declare function formatForDisplay(hotkey: Hotkey | (string & {}) | ParsedHotkey, options?: FormatDisplayOptions): string;
+/**
+ * Formats a hotkey using platform-agnostic labels.
+ * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param platform - The target platform
+ * @returns A formatted string with platform-appropriate labels
+ */
+declare function formatWithLabels(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+/**
+ * Options for formatting a single key for debugging display.
+ */
+interface FormatKeyDebuggingOptions {
+  /** The target platform. Defaults to auto-detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /**
+   * Whether the input value comes from `event.key` or `event.code`.
+   *
+   * - `'key'` (default): Applies rich platform-aware formatting (modifier
+   *   labels, special-key symbols, etc.).
+   * - `'code'`: Returns the value unchanged — physical key codes like
+   *   `"MetaLeft"` or `"KeyA"` are already descriptive for debugging.
+   */
+  source?: 'key' | 'code';
+}
+/**
+ * Formats a single key name for debugging/devtools display.
+ *
+ * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
+ * this function formats individual key names (from `event.key`) with rich
+ * platform-aware labels suitable for debugging tools and developer-facing displays.
+ *
+ * Features:
+ * - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
+ * - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
+ * - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
+ * - Regular keys pass through unchanged
+ *
+ * @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
+ * @param options - Formatting options
+ * @returns A formatted label suitable for debugging display
+ *
+ * @example
+ * ```ts
+ * // On macOS:
+ * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
+ * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
+ * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
+ * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
+ *
+ * // On Windows:
+ * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
+ * formatKeyForDebuggingDisplay('Meta')    // 'Win'
+ *
+ * // Special keys (all platforms):
+ * formatKeyForDebuggingDisplay('ArrowUp') // '↑'
+ * formatKeyForDebuggingDisplay('Escape')  // 'Esc'
+ * formatKeyForDebuggingDisplay('Space')   // '␣'
+ *
+ * // Regular keys pass through:
+ * formatKeyForDebuggingDisplay('A')       // 'A'
+ *
+ * // With source: 'code', values pass through unchanged:
+ * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
+ * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
+ * ```
+ */
+declare function formatKeyForDebuggingDisplay(key: string, options?: FormatKeyDebuggingOptions): string;
+//#endregion
+export { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,175 @@
+import { KEY_DISPLAY_SYMBOLS, MAC_MODIFIER_SYMBOLS, MODIFIER_ORDER, STANDARD_MODIFIER_LABELS, detectPlatform } from "./constants.js";
+import { parseHotkey } from "./parse.js";
+
+//#region src/format.ts
+/**
+* Converts a ParsedHotkey back to a hotkey string.
+*
+* @param parsed - The parsed hotkey object
+* @returns A hotkey string in canonical form
+*
+* @example
+* ```ts
+* formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })
+* // Returns: 'Control+Shift+S'
+* ```
+*/
+function formatHotkey(parsed) {
+	const parts = [];
+	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+/**
+* Formats a hotkey for display in a user interface.
+*
+* On macOS, uses symbols (⌘⇧S).
+* On Windows/Linux, uses text (Ctrl+Shift+S).
+*
+* @param hotkey - The hotkey string or ParsedHotkey to format
+* @param options - Formatting options
+* @returns A formatted string suitable for display
+*
+* @example
+* ```ts
+* formatForDisplay('Mod+Shift+S', { platform: 'mac' })
+* // Returns: '⇧⌘S'
+*
+* formatForDisplay('Mod+Shift+S', { platform: 'windows' })
+* // Returns: 'Ctrl+Shift+S'
+*
+* formatForDisplay('Escape')
+* // Returns: 'Esc' (on all platforms)
+* ```
+*/
+function formatForDisplay(hotkey, options = {}) {
+	const platform = options.platform ?? detectPlatform();
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	if (platform === "mac") return formatForMac(parsed);
+	return formatForStandard(parsed);
+}
+/**
+* Formats a hotkey for macOS display using symbols.
+*/
+function formatForMac(parsed) {
+	const parts = [];
+	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(MAC_MODIFIER_SYMBOLS[modifier]);
+	const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key;
+	parts.push(keyDisplay);
+	return parts.join("");
+}
+/**
+* Formats a hotkey for Windows/Linux display using text labels.
+*/
+function formatForStandard(parsed) {
+	const parts = [];
+	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(STANDARD_MODIFIER_LABELS[modifier]);
+	const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key;
+	parts.push(keyDisplay);
+	return parts.join("+");
+}
+/**
+* Formats a hotkey using platform-agnostic labels.
+* Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
+*
+* @param hotkey - The hotkey string or ParsedHotkey to format
+* @param platform - The target platform
+* @returns A formatted string with platform-appropriate labels
+*/
+function formatWithLabels(hotkey, platform = detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	const parts = [];
+	const labels = {
+		Control: "Ctrl",
+		Alt: platform === "mac" ? "Option" : "Alt",
+		Shift: "Shift",
+		Meta: platform === "mac" ? "Cmd" : "Win"
+	};
+	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(labels[modifier] ?? modifier);
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+/**
+* Maps canonical modifier names to debugging-friendly labels per platform.
+*/
+const MODIFIER_DEBUG_LABELS = {
+	mac: {
+		Meta: "Mod (Cmd)",
+		Control: "Ctrl",
+		Alt: "Opt",
+		Shift: "Shift"
+	},
+	windows: {
+		Control: "Mod (Ctrl)",
+		Meta: "Win",
+		Alt: "Alt",
+		Shift: "Shift"
+	},
+	linux: {
+		Control: "Mod (Ctrl)",
+		Meta: "Super",
+		Alt: "Alt",
+		Shift: "Shift"
+	}
+};
+/**
+* Formats a single key name for debugging/devtools display.
+*
+* Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
+* this function formats individual key names (from `event.key`) with rich
+* platform-aware labels suitable for debugging tools and developer-facing displays.
+*
+* Features:
+* - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
+* - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
+* - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
+* - Regular keys pass through unchanged
+*
+* @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
+* @param options - Formatting options
+* @returns A formatted label suitable for debugging display
+*
+* @example
+* ```ts
+* // On macOS:
+* formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
+* formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
+* formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
+* formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
+*
+* // On Windows:
+* formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
+* formatKeyForDebuggingDisplay('Meta')    // 'Win'
+*
+* // Special keys (all platforms):
+* formatKeyForDebuggingDisplay('ArrowUp') // '↑'
+* formatKeyForDebuggingDisplay('Escape')  // 'Esc'
+* formatKeyForDebuggingDisplay('Space')   // '␣'
+*
+* // Regular keys pass through:
+* formatKeyForDebuggingDisplay('A')       // 'A'
+*
+* // With source: 'code', values pass through unchanged:
+* formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
+* formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
+* ```
+*/
+function formatKeyForDebuggingDisplay(key, options = {}) {
+	if (options.source === "code") return key;
+	const platform = options.platform ?? detectPlatform();
+	const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key];
+	if (modLabel) {
+		if (platform === "mac") {
+			const symbol = MAC_MODIFIER_SYMBOLS[key];
+			if (symbol) return `${symbol} ${modLabel}`;
+		}
+		return modLabel;
+	}
+	const symbol = KEY_DISPLAY_SYMBOLS[key];
+	if (symbol) return symbol;
+	return key;
+}
+
+//#endregion
+export { formatForDisplay, formatHotkey, formatKeyForDebuggingDisplay, formatWithLabels };
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +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"}