@tanstack/hotkeys 0.6.2 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/dist/format.cjs +3 -1
  2. package/dist/format.cjs.map +1 -1
  3. package/dist/format.d.cts +1 -0
  4. package/dist/format.d.ts +1 -0
  5. package/dist/format.js +3 -1
  6. package/dist/format.js.map +1 -1
  7. package/dist/hotkey.d.cts +2 -0
  8. package/dist/hotkey.d.ts +2 -0
  9. package/package.json +1 -1
  10. package/src/format.ts +4 -1
  11. package/src/hotkey.ts +2 -0
package/dist/format.cjs CHANGED
@@ -40,6 +40,7 @@ function formatHotkey(parsed) {
40
40
  *
41
41
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
42
42
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
43
+ * The separator can be customized with `separatorToken`.
43
44
  *
44
45
  * @param hotkey - The hotkey string or ParsedHotkey to format
45
46
  * @param options - Formatting options
@@ -60,6 +61,7 @@ function formatHotkey(parsed) {
60
61
  function formatForDisplay(hotkey, options = {}) {
61
62
  const platform = options.platform ?? require_constants.detectPlatform();
62
63
  const useSymbols = options.useSymbols ?? true;
64
+ const separatorToken = options.separatorToken ?? (platform === "mac" && useSymbols ? " " : "+");
63
65
  return require_parse.normalizeRegisterableHotkey(hotkey, platform).split("+").map((segment) => {
64
66
  if (require_parse.isModifierKey(segment)) {
65
67
  const modifierToken = require_constants.MODIFIER_ALIASES[segment] ?? require_constants.MODIFIER_ALIASES[segment.toLowerCase()];
@@ -69,7 +71,7 @@ function formatForDisplay(hotkey, options = {}) {
69
71
  if (keyDisplaySymbol) return keyDisplaySymbol;
70
72
  return !useSymbols && require_constants.PUNCTUATION_KEY_DISPLAY_LABELS[segment] || segment;
71
73
  }
72
- }).join(platform === "mac" && useSymbols ? " " : "+");
74
+ }).join(separatorToken);
73
75
  }
74
76
  /**
75
77
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
package/dist/format.cjs.map CHANGED
@@ -1 +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 *\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 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(platform === 'mac' && useSymbols ? ' ' : '+')\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;;;;;;;;;;;;;;;;;;;;;;;;AAyBxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAYC,kCAAgB;CACrD,MAAM,aAAa,QAAQ,cAAc;AAKzC,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,aAAa,SAAS,aAAa,MAAM,IAAI;;;;;AAMvD,SAAgB,iBACd,QACA,UAAoD,EAAE,EAC9C;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}
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"}
package/dist/format.d.cts CHANGED
@@ -32,6 +32,7 @@ declare function formatHotkey(parsed: ParsedHotkey): string;
32
32
  *
33
33
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
34
34
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
35
+ * The separator can be customized with `separatorToken`.
35
36
  *
36
37
  * @param hotkey - The hotkey string or ParsedHotkey to format
37
38
  * @param options - Formatting options
package/dist/format.d.ts CHANGED
@@ -32,6 +32,7 @@ declare function formatHotkey(parsed: ParsedHotkey): string;
32
32
  *
33
33
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
34
34
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
35
+ * The separator can be customized with `separatorToken`.
35
36
  *
36
37
  * @param hotkey - The hotkey string or ParsedHotkey to format
37
38
  * @param options - Formatting options
package/dist/format.js CHANGED
@@ -40,6 +40,7 @@ function formatHotkey(parsed) {
40
40
  *
41
41
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
42
42
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
43
+ * The separator can be customized with `separatorToken`.
43
44
  *
44
45
  * @param hotkey - The hotkey string or ParsedHotkey to format
45
46
  * @param options - Formatting options
@@ -60,6 +61,7 @@ function formatHotkey(parsed) {
60
61
  function formatForDisplay(hotkey, options = {}) {
61
62
  const platform = options.platform ?? detectPlatform();
62
63
  const useSymbols = options.useSymbols ?? true;
64
+ const separatorToken = options.separatorToken ?? (platform === "mac" && useSymbols ? " " : "+");
63
65
  return normalizeRegisterableHotkey(hotkey, platform).split("+").map((segment) => {
64
66
  if (isModifierKey(segment)) {
65
67
  const modifierToken = MODIFIER_ALIASES[segment] ?? MODIFIER_ALIASES[segment.toLowerCase()];
@@ -69,7 +71,7 @@ function formatForDisplay(hotkey, options = {}) {
69
71
  if (keyDisplaySymbol) return keyDisplaySymbol;
70
72
  return !useSymbols && PUNCTUATION_KEY_DISPLAY_LABELS[segment] || segment;
71
73
  }
72
- }).join(platform === "mac" && useSymbols ? " " : "+");
74
+ }).join(separatorToken);
73
75
  }
74
76
  /**
75
77
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
package/dist/format.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"format.js","names":[],"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 *\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 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(platform === 'mac' && useSymbols ? ' ' : '+')\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,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,aAAa,QAAQ,cAAc;AAKzC,QAJyB,4BACvB,QACA,SACD,CAEE,MAAM,IAAI,CACV,KAAK,YAAY;AAChB,MAAI,cAAc,QAAQ,EAAE;GAC1B,MAAM,gBAAiB,iBAAiB,YACtC,iBAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,aACE,qBAAqB,iBACrB,oBAAoB,iBACtB,aAAa,YACX,wBAAwB,iBACxB,sBAAsB;SACvB;GACL,MAAM,mBACJ,cACA,oBAAoB;AACtB,OAAI,iBAAkB,QAAO;AAO7B,UAJE,CAAC,cACD,+BACE,YAEiC;;GAEvC,CACD,KAAK,aAAa,SAAS,aAAa,MAAM,IAAI;;;;;AAMvD,SAAgB,iBACd,QACA,UAAoD,EAAE,EAC9C;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}
1
+ {"version":3,"file":"format.js","names":[],"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,YAAY,eACrB,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,YAAY,gBAAgB;CACrD,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,iBACJ,QAAQ,mBAAmB,aAAa,SAAS,aAAa,MAAM;AAKtE,QAJyB,4BACvB,QACA,SACD,CAEE,MAAM,IAAI,CACV,KAAK,YAAY;AAChB,MAAI,cAAc,QAAQ,EAAE;GAC1B,MAAM,gBAAiB,iBAAiB,YACtC,iBAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,aACE,qBAAqB,iBACrB,oBAAoB,iBACtB,aAAa,YACX,wBAAwB,iBACxB,sBAAsB;SACvB;GACL,MAAM,mBACJ,cACA,oBAAoB;AACtB,OAAI,iBAAkB,QAAO;AAO7B,UAJE,CAAC,cACD,+BACE,YAEiC;;GAEvC,CACD,KAAK,eAAe;;;;;AAMzB,SAAgB,iBACd,QACA,UAAoD,EAAE,EAC9C;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}
package/dist/hotkey.d.cts CHANGED
@@ -239,6 +239,8 @@ interface FormatDisplayOptions {
239
239
  platform?: 'mac' | 'windows' | 'linux';
240
240
  /** Whether to use symbols for the display. Defaults to true. */
241
241
  useSymbols?: boolean;
242
+ /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
243
+ separatorToken?: string | null;
242
244
  }
243
245
  /**
244
246
  * Result of validating a hotkey string.
package/dist/hotkey.d.ts CHANGED
@@ -239,6 +239,8 @@ interface FormatDisplayOptions {
239
239
  platform?: 'mac' | 'windows' | 'linux';
240
240
  /** Whether to use symbols for the display. Defaults to true. */
241
241
  useSymbols?: boolean;
242
+ /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
243
+ separatorToken?: string | null;
242
244
  }
243
245
  /**
244
246
  * Result of validating a hotkey string.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/hotkeys",
3
- "version": "0.6.2",
3
+ "version": "0.6.3",
4
4
  "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
5
5
  "author": "Tanner Linsley",
6
6
  "license": "MIT",
package/src/format.ts CHANGED
@@ -71,6 +71,7 @@ export function formatHotkey(parsed: ParsedHotkey): string {
71
71
  *
72
72
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
73
73
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
74
+ * The separator can be customized with `separatorToken`.
74
75
  *
75
76
  * @param hotkey - The hotkey string or ParsedHotkey to format
76
77
  * @param options - Formatting options
@@ -94,6 +95,8 @@ export function formatForDisplay(
94
95
  ): string {
95
96
  const platform = options.platform ?? detectPlatform()
96
97
  const useSymbols = options.useSymbols ?? true
98
+ const separatorToken =
99
+ options.separatorToken ?? (platform === 'mac' && useSymbols ? ' ' : '+')
97
100
  const normalizedHotkey = normalizeRegisterableHotkey(
98
101
  hotkey as RegisterableHotkey,
99
102
  platform,
@@ -125,7 +128,7 @@ export function formatForDisplay(
125
128
  return punctuationKeyDisplayLabel || segment
126
129
  }
127
130
  })
128
- .join(platform === 'mac' && useSymbols ? ' ' : '+')
131
+ .join(separatorToken)
129
132
  }
130
133
 
131
134
  /**
package/src/hotkey.ts CHANGED
@@ -370,6 +370,8 @@ export interface FormatDisplayOptions {
370
370
  platform?: 'mac' | 'windows' | 'linux'
371
371
  /** Whether to use symbols for the display. Defaults to true. */
372
372
  useSymbols?: boolean
373
+ /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
374
+ separatorToken?: string | null
373
375
  }
374
376
 
375
377
  /**