@tanstack/hotkeys 0.7.1 → 0.9.0

package/dist/display-labels.d.cts

@@ -0,0 +1,93 @@
+import { CanonicalModifier } from "./key.types.cjs";
+
+//#region src/display-labels.d.ts
+/**
+ * Modifier key symbols for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style symbols
+ * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+ * a native macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+ * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+ * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+ * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+ * ```
+ */
+declare const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string>;
+/**
+ * Modifier key labels for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style text labels
+ * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.
+ * This provides a familiar macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_LABELS['Control'] // 'control'
+ * MAC_MODIFIER_LABELS['Alt'] // 'option'
+ * MAC_MODIFIER_LABELS['Shift'] // 'shift'
+ * MAC_MODIFIER_LABELS['Meta'] // 'cmd'
+ * ```
+ */
+declare const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+/**
+ * Modifier key labels for Windows/Linux display.
+ *
+ * Used by formatting functions to display hotkeys with standard text labels
+ * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+ * This provides a familiar Windows/Linux look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+ * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+ * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+ * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+ * ```
+ */
+declare const WINDOWS_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+declare const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+declare const PUNCTUATION_KEY_DISPLAY_LABELS: {
+  readonly '`': "Backquote";
+  readonly '\\': "Backslash";
+  readonly '[': "Left Bracket";
+  readonly ']': "Right Bracket";
+  readonly ',': "Comma";
+  readonly '=': "Equal";
+  readonly '-': "Minus";
+  readonly '.': "Period";
+  readonly ';': "Semicolon";
+};
+/**
+ * Special key symbols for display formatting.
+ *
+ * Maps certain keys to their visual symbols for better readability in hotkey displays.
+ * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+ * instead of text labels.
+ *
+ * @example
+ * ```ts
+ * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+ * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+ * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+ * KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+ * ```
+ */
+declare const KEY_DISPLAY_SYMBOLS: {
+  readonly ArrowUp: "↑";
+  readonly ArrowDown: "↓";
+  readonly ArrowLeft: "←";
+  readonly ArrowRight: "→";
+  readonly Enter: "↵";
+  readonly Escape: "Esc";
+  readonly Backspace: "⌫";
+  readonly Delete: "⌦";
+  readonly Tab: "⇥";
+  readonly Space: "␣";
+};
+//#endregion
+export { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS };
+//# sourceMappingURL=display-labels.d.cts.map

package/dist/display-labels.d.ts

@@ -0,0 +1,93 @@
+import { CanonicalModifier } from "./key.types.js";
+
+//#region src/display-labels.d.ts
+/**
+ * Modifier key symbols for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style symbols
+ * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+ * a native macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+ * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+ * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+ * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+ * ```
+ */
+declare const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string>;
+/**
+ * Modifier key labels for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style text labels
+ * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.
+ * This provides a familiar macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_LABELS['Control'] // 'control'
+ * MAC_MODIFIER_LABELS['Alt'] // 'option'
+ * MAC_MODIFIER_LABELS['Shift'] // 'shift'
+ * MAC_MODIFIER_LABELS['Meta'] // 'cmd'
+ * ```
+ */
+declare const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+/**
+ * Modifier key labels for Windows/Linux display.
+ *
+ * Used by formatting functions to display hotkeys with standard text labels
+ * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+ * This provides a familiar Windows/Linux look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+ * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+ * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+ * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+ * ```
+ */
+declare const WINDOWS_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+declare const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string>;
+declare const PUNCTUATION_KEY_DISPLAY_LABELS: {
+  readonly '`': "Backquote";
+  readonly '\\': "Backslash";
+  readonly '[': "Left Bracket";
+  readonly ']': "Right Bracket";
+  readonly ',': "Comma";
+  readonly '=': "Equal";
+  readonly '-': "Minus";
+  readonly '.': "Period";
+  readonly ';': "Semicolon";
+};
+/**
+ * Special key symbols for display formatting.
+ *
+ * Maps certain keys to their visual symbols for better readability in hotkey displays.
+ * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+ * instead of text labels.
+ *
+ * @example
+ * ```ts
+ * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+ * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+ * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+ * KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+ * ```
+ */
+declare const KEY_DISPLAY_SYMBOLS: {
+  readonly ArrowUp: "↑";
+  readonly ArrowDown: "↓";
+  readonly ArrowLeft: "←";
+  readonly ArrowRight: "→";
+  readonly Enter: "↵";
+  readonly Escape: "Esc";
+  readonly Backspace: "⌫";
+  readonly Delete: "⌦";
+  readonly Tab: "⇥";
+  readonly Space: "␣";
+};
+//#endregion
+export { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS };
+//# sourceMappingURL=display-labels.d.ts.map

package/dist/display-labels.js

@@ -0,0 +1,113 @@
+//#region src/display-labels.ts
+/**
+* Modifier key symbols for macOS display.
+*
+* Used by formatting functions to display hotkeys with macOS-style symbols
+* (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+* a native macOS look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+* MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+* MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+* MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+* ```
+*/
+const MAC_MODIFIER_SYMBOLS = {
+	Control: "⌃",
+	Alt: "⌥",
+	Shift: "⇧",
+	Meta: "⌘",
+	Mod: "⌘"
+};
+/**
+* Modifier key labels for macOS display.
+*
+* Used by formatting functions to display hotkeys with macOS-style text labels
+* (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.
+* This provides a familiar macOS look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* MAC_MODIFIER_LABELS['Control'] // 'control'
+* MAC_MODIFIER_LABELS['Alt'] // 'option'
+* MAC_MODIFIER_LABELS['Shift'] // 'shift'
+* MAC_MODIFIER_LABELS['Meta'] // 'cmd'
+* ```
+*/
+const MAC_MODIFIER_LABELS = {
+	Control: "Control",
+	Alt: "Option",
+	Shift: "Shift",
+	Meta: "Cmd",
+	Mod: "Cmd"
+};
+/**
+* Modifier key labels for Windows/Linux display.
+*
+* Used by formatting functions to display hotkeys with standard text labels
+* (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+* This provides a familiar Windows/Linux look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+* STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+* STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+* STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+* ```
+*/
+const WINDOWS_MODIFIER_LABELS = {
+	Control: "Ctrl",
+	Alt: "Alt",
+	Shift: "Shift",
+	Meta: "Win",
+	Mod: "Ctrl"
+};
+const LINUX_MODIFIER_LABELS = {
+	...WINDOWS_MODIFIER_LABELS,
+	Meta: "Super"
+};
+const PUNCTUATION_KEY_DISPLAY_LABELS = {
+	"`": "Backquote",
+	"\\": "Backslash",
+	"[": "Left Bracket",
+	"]": "Right Bracket",
+	",": "Comma",
+	"=": "Equal",
+	"-": "Minus",
+	".": "Period",
+	";": "Semicolon"
+};
+/**
+* Special key symbols for display formatting.
+*
+* Maps certain keys to their visual symbols for better readability in hotkey displays.
+* Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+* instead of text labels.
+*
+* @example
+* ```ts
+* KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+* KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+* KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+* KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+* ```
+*/
+const KEY_DISPLAY_SYMBOLS = {
+	ArrowUp: "↑",
+	ArrowDown: "↓",
+	ArrowLeft: "←",
+	ArrowRight: "→",
+	Enter: "↵",
+	Escape: "Esc",
+	Backspace: "⌫",
+	Delete: "⌦",
+	Tab: "⇥",
+	Space: "␣"
+};
+
+//#endregion
+export { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS };
+//# sourceMappingURL=display-labels.js.map

package/dist/display-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-labels.js","names":[],"sources":["../src/display-labels.ts"],"sourcesContent":["import type { CanonicalModifier } from './key.types'\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n  Mod: '⌘',\n}\n\n/**\n * Modifier key labels for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style text labels\n * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.\n * This provides a familiar macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_LABELS['Control'] // 'control'\n * MAC_MODIFIER_LABELS['Alt'] // 'option'\n * MAC_MODIFIER_LABELS['Shift'] // 'shift'\n * MAC_MODIFIER_LABELS['Meta'] // 'cmd'\n * ```\n */\nexport const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: 'Control',\n  Alt: 'Option',\n  Shift: 'Shift',\n  Meta: 'Cmd',\n  Mod: 'Cmd',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const WINDOWS_MODIFIER_LABELS: Record<\n  CanonicalModifier | 'Mod',\n  string\n> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n  Mod: 'Ctrl',\n}\n\nexport const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =\n  {\n    ...WINDOWS_MODIFIER_LABELS,\n    Meta: 'Super',\n  }\n\nexport const PUNCTUATION_KEY_DISPLAY_LABELS = {\n  '`': 'Backquote',\n  '\\\\': 'Backslash',\n  '[': 'Left Bracket',\n  ']': 'Right Bracket',\n  ',': 'Comma',\n  '=': 'Equal',\n  '-': 'Minus',\n  '.': 'Period',\n  ';': 'Semicolon',\n} as const satisfies Record<string, string>\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n} as const satisfies Record<string, string>\n"],"mappings":";;;;;;;;;;;;;;;;AAqBA,MAAa,uBAAkE;CAC7E,SAAS;CACT,KAAK;CACL,OAAO;CACP,MAAM;CACN,KAAK;CACN;;;;;;;;;;;;;;;;AAiBD,MAAa,sBAAiE;CAC5E,SAAS;CACT,KAAK;CACL,OAAO;CACP,MAAM;CACN,KAAK;CACN;;;;;;;;;;;;;;;;AAiBD,MAAa,0BAGT;CACF,SAAS;CACT,KAAK;CACL,OAAO;CACP,MAAM;CACN,KAAK;CACN;AAED,MAAa,wBACX;CACE,GAAG;CACH,MAAM;CACP;AAEH,MAAa,iCAAiC;CAC5C,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACN;;;;;;;;;;;;;;;;AAiBD,MAAa,sBAAsB;CACjC,SAAS;CACT,WAAW;CACX,WAAW;CACX,YAAY;CACZ,OAAO;CACP,QAAQ;CACR,WAAW;CACX,QAAQ;CACR,KAAK;CACL,OAAO;CACR"}

package/dist/format.cjs

@@ -1,9 +1,13 @@
 const require_constants = require('./constants.cjs');
+const require_display_labels = require('./display-labels.cjs');
+const require_platform = require('./platform.cjs');
+const require__keyboard_event = require('./_keyboard-event.cjs');
 const require_parse = require('./parse.cjs');
 
 //#region src/format.ts
 /**
-* Converts a hotkey sequence array to a display string.
+* Joins stored sequence steps with spaces, preserving physical code tokens.
+* For user-facing labels, call formatForDisplay on each step instead.
 *
 * @param sequence - Array of hotkey strings that form the sequence
 * @returns A space-separated string (e.g. ['G','G'] → 'G G')
@@ -30,48 +34,38 @@ function formatHotkeySequence(sequence) {
 * ```
 */
 function formatHotkey(parsed) {
+	if (parsed.code === void 0) require__keyboard_event.assertLogicalKey(parsed.key);
 	const parts = [];
 	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
 	return parts.join("+");
 }
-/**
-* Formats a hotkey for display in a user interface.
-*
-* On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
-* On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
-* The separator can be customized with `separatorToken`.
-*
-* @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' (symbols separated by spaces on macOS)
-*
-* 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 ?? require_constants.detectPlatform();
-	const useSymbols = options.useSymbols ?? true;
-	const separatorToken = options.separatorToken ?? (platform === "mac" && useSymbols ? " " : "+");
-	return require_parse.normalizeRegisterableHotkey(hotkey, platform).split("+").map((segment) => {
+	const platform = options.platform ?? require_platform.detectPlatform();
+	const symbols = options.useSymbols ?? true;
+	const modifierSymbols = typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
+	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;
+	const separator = options.separatorToken ?? (platform === "mac" && modifierSymbols ? " " : "+");
+	const parts = require__keyboard_event.splitHotkeyParts(typeof hotkey === "object" && "modifiers" in hotkey ? require_parse.normalizeHotkeyFromParsed(hotkey, platform) : require_parse.normalizeRegisterableHotkey(hotkey, platform)).map((segment) => {
 		if (require_parse.isModifierKey(segment)) {
-			const modifierToken = require_constants.MODIFIER_ALIASES[segment] ?? require_constants.MODIFIER_ALIASES[segment.toLowerCase()];
-			return platform === "mac" ? useSymbols ? require_constants.MAC_MODIFIER_SYMBOLS[modifierToken] : require_constants.MAC_MODIFIER_LABELS[modifierToken] : platform === "windows" ? require_constants.WINDOWS_MODIFIER_LABELS[modifierToken] : require_constants.LINUX_MODIFIER_LABELS[modifierToken];
-		} else {
-			const keyDisplaySymbol = useSymbols && require_constants.KEY_DISPLAY_SYMBOLS[segment];
-			if (keyDisplaySymbol) return keyDisplaySymbol;
-			return !useSymbols && require_constants.PUNCTUATION_KEY_DISPLAY_LABELS[segment] || segment;
+			const modifier = require_constants.MODIFIER_ALIASES[segment] ?? require_constants.MODIFIER_ALIASES[segment.toLowerCase()];
+			return platform === "mac" ? modifierSymbols ? require_display_labels.MAC_MODIFIER_SYMBOLS[modifier] : require_display_labels.MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? require_display_labels.WINDOWS_MODIFIER_LABELS[modifier] : require_display_labels.LINUX_MODIFIER_LABELS[modifier];
 		}
-	}).join(separatorToken);
+		const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(segment)?.[1];
+		const label = options.keyLabels?.[code ?? segment];
+		if (label !== void 0) return label;
+		const numpad = code?.startsWith("Numpad") ?? false;
+		let displayKey = code ?? segment;
+		const mappedKey = code ? options.layoutMap?.get(code) : void 0;
+		if (mappedKey) displayKey = require_constants.normalizeKeyName(mappedKey);
+		else if (code) if (/^Key[A-Z]$/.test(code)) displayKey = code.slice(3);
+		else if (/^Digit[0-9]$/.test(code)) displayKey = code.slice(5);
+		else if (numpad) displayKey = code.slice(6);
+		else displayKey = require_constants.PUNCTUATION_CODE_MAP[code] ?? code;
+		const display = (keySymbols ? require_display_labels.KEY_DISPLAY_SYMBOLS : require_display_labels.PUNCTUATION_KEY_DISPLAY_LABELS)[displayKey] ?? displayKey;
+		return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
+	});
+	return options.parts ? parts : parts.join(separator);
 }
 /**
 * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.

package/dist/format.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"format.cjs","names":["MODIFIER_ORDER","detectPlatform","normalizeRegisterableHotkey","isModifierKey","MODIFIER_ALIASES","MAC_MODIFIER_SYMBOLS","MAC_MODIFIER_LABELS","WINDOWS_MODIFIER_LABELS","LINUX_MODIFIER_LABELS","KEY_DISPLAY_SYMBOLS","PUNCTUATION_KEY_DISPLAY_LABELS"],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  LINUX_MODIFIER_LABELS,\n  MAC_MODIFIER_LABELS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  PUNCTUATION_KEY_DISPLAY_LABELS,\n  WINDOWS_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport {\n  isModifierKey,\n  normalizeHotkeyFromParsed,\n  normalizeRegisterableHotkey,\n} from './parse'\nimport type {\n  CanonicalModifier,\n  FormatDisplayOptions,\n  Hotkey,\n  ParsedHotkey,\n  RegisterableHotkey,\n} 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) in the same modifier order as {@link normalizeHotkeyFromParsed}.\n * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.\n * The separator can be customized with `separatorToken`.\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' (symbols separated by spaces on macOS)\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: RegisterableHotkey | (string & {}),\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const useSymbols = options.useSymbols ?? true\n  const separatorToken =\n    options.separatorToken ?? (platform === 'mac' && useSymbols ? ' ' : '+')\n  const normalizedHotkey = normalizeRegisterableHotkey(\n    hotkey as RegisterableHotkey,\n    platform,\n  )\n  return normalizedHotkey\n    .split('+')\n    .map((segment) => {\n      if (isModifierKey(segment)) {\n        const modifierToken = (MODIFIER_ALIASES[segment] ??\n          MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'\n        return platform === 'mac'\n          ? useSymbols\n            ? MAC_MODIFIER_SYMBOLS[modifierToken]\n            : MAC_MODIFIER_LABELS[modifierToken]\n          : platform === 'windows'\n            ? WINDOWS_MODIFIER_LABELS[modifierToken]\n            : LINUX_MODIFIER_LABELS[modifierToken]\n      } else {\n        const keyDisplaySymbol =\n          useSymbols &&\n          KEY_DISPLAY_SYMBOLS[segment as keyof typeof KEY_DISPLAY_SYMBOLS]\n        if (keyDisplaySymbol) return keyDisplaySymbol\n\n        const punctuationKeyDisplayLabel =\n          !useSymbols &&\n          PUNCTUATION_KEY_DISPLAY_LABELS[\n            segment as keyof typeof PUNCTUATION_KEY_DISPLAY_LABELS\n          ]\n        return punctuationKeyDisplayLabel || segment\n      }\n    })\n    .join(separatorToken)\n}\n\n/**\n * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.\n */\nexport function formatWithLabels(\n  hotkey: RegisterableHotkey,\n  options: Omit<FormatDisplayOptions, 'useSymbols'> = {},\n): string {\n  return formatForDisplay(hotkey, { ...options, useSymbols: false })\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoCA,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;;;;;;;;;;;;;;;;;;;;;;;;;AA0BxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CACrD,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,iBACJ,QAAQ,mBAAmB,aAAa,SAAS,aAAa,MAAM;AAKtE,QAJyBC,0CACvB,QACA,SACD,CAEE,MAAM,IAAI,CACV,KAAK,YAAY;AAChB,MAAIC,4BAAc,QAAQ,EAAE;GAC1B,MAAM,gBAAiBC,mCAAiB,YACtCA,mCAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,aACEC,uCAAqB,iBACrBC,sCAAoB,iBACtB,aAAa,YACXC,0CAAwB,iBACxBC,wCAAsB;SACvB;GACL,MAAM,mBACJ,cACAC,sCAAoB;AACtB,OAAI,iBAAkB,QAAO;AAO7B,UAJE,CAAC,cACDC,iDACE,YAEiC;;GAEvC,CACD,KAAK,eAAe;;;;;AAMzB,SAAgB,iBACd,QACA,UAAoD,EAAE,EAC9C;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}
+{"version":3,"file":"format.cjs","names":["MODIFIER_ORDER","detectPlatform","splitHotkeyParts","normalizeHotkeyFromParsed","normalizeRegisterableHotkey","isModifierKey","MODIFIER_ALIASES","MAC_MODIFIER_SYMBOLS","MAC_MODIFIER_LABELS","WINDOWS_MODIFIER_LABELS","LINUX_MODIFIER_LABELS","normalizeKeyName","PUNCTUATION_CODE_MAP","KEY_DISPLAY_SYMBOLS","PUNCTUATION_KEY_DISPLAY_LABELS"],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  LINUX_MODIFIER_LABELS,\n  MAC_MODIFIER_LABELS,\n  MAC_MODIFIER_SYMBOLS,\n  PUNCTUATION_KEY_DISPLAY_LABELS,\n  WINDOWS_MODIFIER_LABELS,\n} from './display-labels'\nimport {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  PUNCTUATION_CODE_MAP,\n  normalizeKeyName,\n} from './constants'\nimport { detectPlatform } from './platform'\nimport { assertLogicalKey, splitHotkeyParts } from './_keyboard-event'\nimport {\n  isModifierKey,\n  normalizeHotkeyFromParsed,\n  normalizeRegisterableHotkey,\n} from './parse'\nimport type { CanonicalModifier } from './key.types'\nimport type { Hotkey, ParsedHotkey, RegisterableHotkey } from './hotkey.types'\n\n/**\n * Joins stored sequence steps with spaces, preserving physical code tokens.\n * For user-facing labels, call formatForDisplay on each step instead.\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  if (parsed.code === undefined) assertLogicalKey(parsed.key)\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.code !== undefined ? `[${parsed.code}]` : parsed.key)\n\n  return parts.join('+')\n}\n\nexport type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {})\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.\n * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.\n * The separator can be customized with `separatorToken`.\n * Physical codes use conventional display labels: `[KeyS]` becomes `S` and\n * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout\n * or change matching. Supply a resolved `layoutMap` for layout-aware labels;\n * `keyLabels` overrides both layout entries and fallback labels.\n *\n * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey\n * @param options - Formatting options\n * @returns Display text, or individual key labels when parts is true\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)\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: DisplayHotkey,\n  options: FormatDisplayOptions & { parts: true },\n): Array<string>\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options?: FormatDisplayOptions & { parts?: false },\n): string\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options: FormatDisplayOptions,\n): string | Array<string>\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options: FormatDisplayOptions = {},\n): string | Array<string> {\n  const platform = options.platform ?? detectPlatform()\n  const symbols = options.useSymbols ?? true\n  const modifierSymbols =\n    typeof symbols === 'boolean' ? symbols : (symbols.modifiers ?? true)\n  const keySymbols =\n    typeof symbols === 'boolean' ? symbols : (symbols.keys ?? true)\n  const separator =\n    options.separatorToken ??\n    (platform === 'mac' && modifierSymbols ? ' ' : '+')\n  const normalized =\n    typeof hotkey === 'object' && 'modifiers' in hotkey\n      ? normalizeHotkeyFromParsed(hotkey, platform)\n      : normalizeRegisterableHotkey(hotkey as RegisterableHotkey, platform)\n  const parts = splitHotkeyParts(normalized).map((segment) => {\n    if (isModifierKey(segment)) {\n      const modifier = (MODIFIER_ALIASES[segment] ??\n        MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'\n      return platform === 'mac'\n        ? modifierSymbols\n          ? MAC_MODIFIER_SYMBOLS[modifier]\n          : MAC_MODIFIER_LABELS[modifier]\n        : platform === 'windows'\n          ? WINDOWS_MODIFIER_LABELS[modifier]\n          : LINUX_MODIFIER_LABELS[modifier]\n    }\n    const code = /^\\[([A-Za-z][A-Za-z0-9]*)\\]$/.exec(segment)?.[1]\n    const label = options.keyLabels?.[code ?? segment]\n    if (label !== undefined) return label\n    // Shorten conventional position labels for display only; stored identity is unchanged.\n    const numpad = code?.startsWith('Numpad') ?? false\n    let displayKey = code ?? segment\n    const mappedKey = code ? options.layoutMap?.get(code) : undefined\n    if (mappedKey) {\n      // Layout entries are logical labels; normalize their case and whitespace names.\n      displayKey = normalizeKeyName(mappedKey)\n    } else if (code) {\n      if (/^Key[A-Z]$/.test(code)) displayKey = code.slice(3)\n      else if (/^Digit[0-9]$/.test(code)) displayKey = code.slice(5)\n      else if (numpad) displayKey = code.slice(6)\n      else displayKey = PUNCTUATION_CODE_MAP[code] ?? code\n    }\n    const labels = keySymbols\n      ? KEY_DISPLAY_SYMBOLS\n      : PUNCTUATION_KEY_DISPLAY_LABELS\n    const display =\n      (labels as Partial<Record<string, string>>)[displayKey] ?? displayKey\n    // Retain numpad identity while making longer names such as MemoryAdd readable.\n    return numpad\n      ? `Numpad ${display.replace(/([a-z])([A-Z])/g, '$1 $2')}`\n      : display\n  })\n  return options.parts ? parts : parts.join(separator)\n}\n\n/**\n * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.\n */\nexport function formatWithLabels(\n  hotkey: RegisterableHotkey,\n  options: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'> = {},\n): string {\n  return formatForDisplay(hotkey, { ...options, useSymbols: false })\n}\n\n/**\n * Options for formatting hotkeys for display.\n */\nexport interface FormatDisplayOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Whether to use symbols for the display. Defaults to true. */\n  useSymbols?: boolean | { modifiers?: boolean; keys?: boolean }\n  /** Return individual key labels instead of a joined string. Default: false. */\n  parts?: boolean\n  /**\n   * An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.\n   * Used only for physical bindings. Mapped keys receive normal display formatting;\n   * missing or empty entries use conventional fallback labels. The caller owns\n   * loading and refreshing the map; this formatter never calls browser APIs.\n   */\n  layoutMap?: { get: (code: string) => string | undefined }\n  /** Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching. */\n  keyLabels?: Readonly<Record<string, string>>\n  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */\n  separatorToken?: string | null\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,qBAAqB,UAAiC;AACpE,QAAO,SAAS,KAAK,IAAI;;;;;;;;;;;;;;AAe3B,SAAgB,aAAa,QAA8B;AACzD,KAAI,OAAO,SAAS,OAAW,0CAAiB,OAAO,IAAI;CAC3D,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAYA,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,SAAS,SAAY,IAAI,OAAO,KAAK,KAAK,OAAO,IAAI;AAEvE,QAAO,MAAM,KAAK,IAAI;;AA4CxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EACV;CACxB,MAAM,WAAW,QAAQ,YAAYC,iCAAgB;CACrD,MAAM,UAAU,QAAQ,cAAc;CACtC,MAAM,kBACJ,OAAO,YAAY,YAAY,UAAW,QAAQ,aAAa;CACjE,MAAM,aACJ,OAAO,YAAY,YAAY,UAAW,QAAQ,QAAQ;CAC5D,MAAM,YACJ,QAAQ,mBACP,aAAa,SAAS,kBAAkB,MAAM;CAKjD,MAAM,QAAQC,yCAHZ,OAAO,WAAW,YAAY,eAAe,SACzCC,wCAA0B,QAAQ,SAAS,GAC3CC,0CAA4B,QAA8B,SAAS,CAC/B,CAAC,KAAK,YAAY;AAC1D,MAAIC,4BAAc,QAAQ,EAAE;GAC1B,MAAM,WAAYC,mCAAiB,YACjCA,mCAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,kBACEC,4CAAqB,YACrBC,2CAAoB,YACtB,aAAa,YACXC,+CAAwB,YACxBC,6CAAsB;;EAE9B,MAAM,OAAO,+BAA+B,KAAK,QAAQ,GAAG;EAC5D,MAAM,QAAQ,QAAQ,YAAY,QAAQ;AAC1C,MAAI,UAAU,OAAW,QAAO;EAEhC,MAAM,SAAS,MAAM,WAAW,SAAS,IAAI;EAC7C,IAAI,aAAa,QAAQ;EACzB,MAAM,YAAY,OAAO,QAAQ,WAAW,IAAI,KAAK,GAAG;AACxD,MAAI,UAEF,cAAaC,mCAAiB,UAAU;WAC/B,KACT,KAAI,aAAa,KAAK,KAAK,CAAE,cAAa,KAAK,MAAM,EAAE;WAC9C,eAAe,KAAK,KAAK,CAAE,cAAa,KAAK,MAAM,EAAE;WACrD,OAAQ,cAAa,KAAK,MAAM,EAAE;MACtC,cAAaC,uCAAqB,SAAS;EAKlD,MAAM,WAHS,aACXC,6CACAC,uDAE0C,eAAe;AAE7D,SAAO,SACH,UAAU,QAAQ,QAAQ,mBAAmB,QAAQ,KACrD;GACJ;AACF,QAAO,QAAQ,QAAQ,QAAQ,MAAM,KAAK,UAAU;;;;;AAMtD,SAAgB,iBACd,QACA,UAA8D,EAAE,EACxD;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}

package/dist/format.d.cts

@@ -1,8 +1,9 @@
-import { FormatDisplayOptions, Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.cjs";
 
 //#region src/format.d.ts
 /**
- * Converts a hotkey sequence array to a display string.
+ * Joins stored sequence steps with spaces, preserving physical code tokens.
+ * For user-facing labels, call formatForDisplay on each step instead.
  *
  * @param sequence - Array of hotkey strings that form the sequence
  * @returns A space-separated string (e.g. ['G','G'] → 'G G')
@@ -27,16 +28,21 @@ declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
  * ```
  */
 declare function formatHotkey(parsed: ParsedHotkey): string;
+type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
 /**
  * Formats a hotkey for display in a user interface.
  *
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  * The separator can be customized with `separatorToken`.
+ * Physical codes use conventional display labels: `[KeyS]` becomes `S` and
+ * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
+ * or change matching. Supply a resolved `layoutMap` for layout-aware labels;
+ * `keyLabels` overrides both layout entries and fallback labels.
  *
- * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey
  * @param options - Formatting options
- * @returns A formatted string suitable for display
+ * @returns Display text, or individual key labels when parts is true
  *
  * @example
  * ```ts
@@ -50,11 +56,44 @@ declare function formatHotkey(parsed: ParsedHotkey): string;
  * // Returns: 'Esc' (on all platforms)
  * ```
  */
-declare function formatForDisplay(hotkey: RegisterableHotkey | (string & {}), options?: FormatDisplayOptions): string;
+declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions & {
+  parts: true;
+}): Array<string>;
+declare function formatForDisplay(hotkey: DisplayHotkey, options?: FormatDisplayOptions & {
+  parts?: false;
+}): string;
+declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions): string | Array<string>;
 /**
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */
-declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols'>): string;
+declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'>): string;
+/**
+ * Options for formatting hotkeys for display.
+ */
+interface FormatDisplayOptions {
+  /** The target platform. Defaults to auto-detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Whether to use symbols for the display. Defaults to true. */
+  useSymbols?: boolean | {
+    modifiers?: boolean;
+    keys?: boolean;
+  };
+  /** Return individual key labels instead of a joined string. Default: false. */
+  parts?: boolean;
+  /**
+   * An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.
+   * Used only for physical bindings. Mapped keys receive normal display formatting;
+   * missing or empty entries use conventional fallback labels. The caller owns
+   * loading and refreshing the map; this formatter never calls browser APIs.
+   */
+  layoutMap?: {
+    get: (code: string) => string | undefined;
+  };
+  /** Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching. */
+  keyLabels?: Readonly<Record<string, string>>;
+  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
+  separatorToken?: string | null;
+}
 //#endregion
-export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
+export { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
 //# sourceMappingURL=format.d.cts.map

package/dist/format.d.ts

@@ -1,8 +1,9 @@
-import { FormatDisplayOptions, Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
+import { Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 
 //#region src/format.d.ts
 /**
- * Converts a hotkey sequence array to a display string.
+ * Joins stored sequence steps with spaces, preserving physical code tokens.
+ * For user-facing labels, call formatForDisplay on each step instead.
  *
  * @param sequence - Array of hotkey strings that form the sequence
  * @returns A space-separated string (e.g. ['G','G'] → 'G G')
@@ -27,16 +28,21 @@ declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
  * ```
  */
 declare function formatHotkey(parsed: ParsedHotkey): string;
+type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
 /**
  * Formats a hotkey for display in a user interface.
  *
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  * The separator can be customized with `separatorToken`.
+ * Physical codes use conventional display labels: `[KeyS]` becomes `S` and
+ * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
+ * or change matching. Supply a resolved `layoutMap` for layout-aware labels;
+ * `keyLabels` overrides both layout entries and fallback labels.
  *
- * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey
  * @param options - Formatting options
- * @returns A formatted string suitable for display
+ * @returns Display text, or individual key labels when parts is true
  *
  * @example
  * ```ts
@@ -50,11 +56,44 @@ declare function formatHotkey(parsed: ParsedHotkey): string;
  * // Returns: 'Esc' (on all platforms)
  * ```
  */
-declare function formatForDisplay(hotkey: RegisterableHotkey | (string & {}), options?: FormatDisplayOptions): string;
+declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions & {
+  parts: true;
+}): Array<string>;
+declare function formatForDisplay(hotkey: DisplayHotkey, options?: FormatDisplayOptions & {
+  parts?: false;
+}): string;
+declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions): string | Array<string>;
 /**
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */
-declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols'>): string;
+declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'>): string;
+/**
+ * Options for formatting hotkeys for display.
+ */
+interface FormatDisplayOptions {
+  /** The target platform. Defaults to auto-detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Whether to use symbols for the display. Defaults to true. */
+  useSymbols?: boolean | {
+    modifiers?: boolean;
+    keys?: boolean;
+  };
+  /** Return individual key labels instead of a joined string. Default: false. */
+  parts?: boolean;
+  /**
+   * An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.
+   * Used only for physical bindings. Mapped keys receive normal display formatting;
+   * missing or empty entries use conventional fallback labels. The caller owns
+   * loading and refreshing the map; this formatter never calls browser APIs.
+   */
+  layoutMap?: {
+    get: (code: string) => string | undefined;
+  };
+  /** Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching. */
+  keyLabels?: Readonly<Record<string, string>>;
+  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
+  separatorToken?: string | null;
+}
 //#endregion
-export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
+export { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
 //# sourceMappingURL=format.d.ts.map