@tanstack/hotkeys 0.7.1 → 0.9.0

package/src/constants.ts

@@ -1,3 +1,4 @@
+import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from './_named-keys'
 import type {
   CanonicalModifier,
   EditingKey,
@@ -6,41 +7,7 @@ import type {
   NavigationKey,
   NumberKey,
   PunctuationKey,
-} from './hotkey'
-
-/**
- * Detects the current platform based on browser navigator properties.
- *
- * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
- * Control elsewhere) and for platform-specific hotkey formatting.
- *
- * @returns The detected platform: 'mac', 'windows', or 'linux'
- * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
- *
- * @example
- * ```ts
- * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
- * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
- * ```
- */
-export function detectPlatform(): 'mac' | 'windows' | 'linux' {
-  if (typeof navigator === 'undefined') {
-    return 'linux' // Default for SSR
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  const platform = navigator.platform?.toLowerCase() ?? ''
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  const userAgent = navigator.userAgent?.toLowerCase() ?? ''
-
-  if (platform.includes('mac') || userAgent.includes('mac')) {
-    return 'mac'
-  }
-  if (platform.includes('win') || userAgent.includes('win')) {
-    return 'windows'
-  }
-  return 'linux'
-}
+} from './key.types'
 
 /**
  * Canonical order for modifiers in normalized hotkey strings.
@@ -129,37 +96,6 @@ export const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {
   mod: 'Mod',
 }
 
-/**
- * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
- *
- * The 'Mod' token represents the "primary modifier" on each platform:
- * - macOS: 'Meta' (Command key ⌘)
- * - Windows/Linux: 'Control' (Ctrl key)
- *
- * This enables cross-platform hotkey definitions like 'Mod+S' that automatically
- * map to Command+S on Mac and Ctrl+S on Windows/Linux.
- *
- * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
- * @param platform - The target platform. Defaults to auto-detection.
- * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
- *
- * @example
- * ```ts
- * resolveModifier('Mod', 'mac') // 'Meta'
- * resolveModifier('Mod', 'windows') // 'Control'
- * resolveModifier('Control', 'mac') // 'Control' (unchanged)
- * ```
- */
-export function resolveModifier(
-  modifier: CanonicalModifier | 'Mod',
-  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
-): CanonicalModifier {
-  if (modifier === 'Mod') {
-    return platform === 'mac' ? 'Meta' : 'Control'
-  }
-  return modifier
-}
-
 /**
  * Set of all valid letter keys (A-Z).
  *
@@ -216,7 +152,7 @@ export const NUMBER_KEYS = new Set<NumberKey>([
 ])
 
 /**
- * Set of all valid function keys (F1-F12).
+ * Set of all valid function keys (F1-F24).
  *
  * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
  * Alt+F4 to close windows) and application-specific commands.
@@ -234,6 +170,18 @@ export const FUNCTION_KEYS = new Set<FunctionKey>([
   'F10',
   'F11',
   'F12',
+  'F13',
+  'F14',
+  'F15',
+  'F16',
+  'F17',
+  'F18',
+  'F19',
+  'F20',
+  'F21',
+  'F22',
+  'F23',
+  'F24',
 ])
 
 /**
@@ -293,6 +241,28 @@ export const PUNCTUATION_KEYS = new Set<PunctuationKey>([
   '.',
   ';',
   '`',
+  "'",
+  '+',
+  '?',
+  '!',
+  '@',
+  '#',
+  '$',
+  '%',
+  '^',
+  '&',
+  '*',
+  '(',
+  ')',
+  '_',
+  '{',
+  '}',
+  '|',
+  ':',
+  '"',
+  '<',
+  '>',
+  '~',
 ])
 
 /**
@@ -313,6 +283,7 @@ export const PUNCTUATION_CODE_MAP: Record<string, string> = {
   Equal: '=',
   Minus: '-',
   Period: '.',
+  Quote: "'",
   Semicolon: ';',
   Slash: '/',
 }
@@ -338,8 +309,15 @@ export const ALL_KEYS = new Set([
   ...NAVIGATION_KEYS,
   ...EDITING_KEYS,
   ...PUNCTUATION_KEYS,
+  ...SHARED_NAMED_KEYS,
+  ...LOGICAL_ONLY_NAMED_KEYS,
 ])
 
+// Share canonical spellings with validation, including newly supported named keys.
+const CANONICAL_KEY_NAMES = new Map<string, string>(
+  Array.from(ALL_KEYS, (key) => [key.toLowerCase(), key]),
+)
+
 /**
  * Maps key name aliases to their canonical form.
  *
@@ -360,6 +338,8 @@ export const ALL_KEYS = new Set([
  * ```
  */
 const KEY_ALIASES: Record<string, string> = {
+  Plus: '+',
+  plus: '+',
   // Escape variants
   Esc: 'Escape',
   esc: 'Escape',
@@ -471,133 +451,5 @@ export function normalizeKeyName(key: string): string {
     return upper.length === 1 ? upper : key
   }
 
-  // Check if it's a function key (normalize case)
-  const upperKey = key.toUpperCase()
-  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {
-    return upperKey
-  }
-
-  return key
+  return CANONICAL_KEY_NAMES.get(key.toLowerCase()) ?? key
 }
-
-// =============================================================================
-// Display Symbols
-// =============================================================================
-
-/**
- * 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'] // '⇧'
- * ```
- */
-export const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {
-  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'
- * ```
- */
-export const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {
-  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'
- * ```
- */
-export const WINDOWS_MODIFIER_LABELS: Record<
-  CanonicalModifier | 'Mod',
-  string
-> = {
-  Control: 'Ctrl',
-  Alt: 'Alt',
-  Shift: 'Shift',
-  Meta: 'Win',
-  Mod: 'Ctrl',
-}
-
-export const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =
-  {
-    ...WINDOWS_MODIFIER_LABELS,
-    Meta: 'Super',
-  }
-
-export const PUNCTUATION_KEY_DISPLAY_LABELS = {
-  '`': 'Backquote',
-  '\\': 'Backslash',
-  '[': 'Left Bracket',
-  ']': 'Right Bracket',
-  ',': 'Comma',
-  '=': 'Equal',
-  '-': 'Minus',
-  '.': 'Period',
-  ';': 'Semicolon',
-} as const satisfies Record<string, string>
-
-/**
- * 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'] // '␣'
- * ```
- */
-export const KEY_DISPLAY_SYMBOLS = {
-  ArrowUp: '↑',
-  ArrowDown: '↓',
-  ArrowLeft: '←',
-  ArrowRight: '→',
-  Enter: '↵',
-  Escape: 'Esc',
-  Backspace: '⌫',
-  Delete: '⌦',
-  Tab: '⇥',
-  Space: '␣',
-} as const satisfies Record<string, string>

package/src/display-labels.ts

@@ -0,0 +1,123 @@
+import type { CanonicalModifier } from './key.types'
+
+// =============================================================================
+// Display Symbols
+// =============================================================================
+
+/**
+ * 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'] // '⇧'
+ * ```
+ */
+export const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {
+  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'
+ * ```
+ */
+export const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {
+  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'
+ * ```
+ */
+export const WINDOWS_MODIFIER_LABELS: Record<
+  CanonicalModifier | 'Mod',
+  string
+> = {
+  Control: 'Ctrl',
+  Alt: 'Alt',
+  Shift: 'Shift',
+  Meta: 'Win',
+  Mod: 'Ctrl',
+}
+
+export const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =
+  {
+    ...WINDOWS_MODIFIER_LABELS,
+    Meta: 'Super',
+  }
+
+export const PUNCTUATION_KEY_DISPLAY_LABELS = {
+  '`': 'Backquote',
+  '\\': 'Backslash',
+  '[': 'Left Bracket',
+  ']': 'Right Bracket',
+  ',': 'Comma',
+  '=': 'Equal',
+  '-': 'Minus',
+  '.': 'Period',
+  ';': 'Semicolon',
+} as const satisfies Record<string, string>
+
+/**
+ * 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'] // '␣'
+ * ```
+ */
+export const KEY_DISPLAY_SYMBOLS = {
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  Enter: '↵',
+  Escape: 'Esc',
+  Backspace: '⌫',
+  Delete: '⌦',
+  Tab: '⇥',
+  Space: '␣',
+} as const satisfies Record<string, string>

package/src/format.ts

@@ -3,27 +3,28 @@ import {
   LINUX_MODIFIER_LABELS,
   MAC_MODIFIER_LABELS,
   MAC_MODIFIER_SYMBOLS,
-  MODIFIER_ALIASES,
-  MODIFIER_ORDER,
   PUNCTUATION_KEY_DISPLAY_LABELS,
   WINDOWS_MODIFIER_LABELS,
-  detectPlatform,
+} from './display-labels'
+import {
+  MODIFIER_ALIASES,
+  MODIFIER_ORDER,
+  PUNCTUATION_CODE_MAP,
+  normalizeKeyName,
 } from './constants'
+import { detectPlatform } from './platform'
+import { assertLogicalKey, splitHotkeyParts } from './_keyboard-event'
 import {
   isModifierKey,
   normalizeHotkeyFromParsed,
   normalizeRegisterableHotkey,
 } from './parse'
-import type {
-  CanonicalModifier,
-  FormatDisplayOptions,
-  Hotkey,
-  ParsedHotkey,
-  RegisterableHotkey,
-} from './hotkey'
+import type { CanonicalModifier } from './key.types'
+import type { Hotkey, ParsedHotkey, RegisterableHotkey } from './hotkey.types'
 
 /**
- * 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')
@@ -51,6 +52,7 @@ export function formatHotkeySequence(sequence: Array<Hotkey>): string {
  * ```
  */
 export function formatHotkey(parsed: ParsedHotkey): string {
+  if (parsed.code === undefined) assertLogicalKey(parsed.key)
   const parts: Array<string> = []
 
   // Add modifiers in canonical order
@@ -61,21 +63,27 @@ export function formatHotkey(parsed: ParsedHotkey): string {
   }
 
   // Add the key
-  parts.push(parsed.key)
+  parts.push(parsed.code !== undefined ? `[${parsed.code}]` : parsed.key)
 
   return parts.join('+')
 }
 
+export 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
@@ -90,45 +98,73 @@ export function formatHotkey(parsed: ParsedHotkey): string {
  * ```
  */
 export function formatForDisplay(
-  hotkey: RegisterableHotkey | (string & {}),
+  hotkey: DisplayHotkey,
+  options: FormatDisplayOptions & { parts: true },
+): Array<string>
+export function formatForDisplay(
+  hotkey: DisplayHotkey,
+  options?: FormatDisplayOptions & { parts?: false },
+): string
+export function formatForDisplay(
+  hotkey: DisplayHotkey,
+  options: FormatDisplayOptions,
+): string | Array<string>
+export function formatForDisplay(
+  hotkey: DisplayHotkey,
   options: FormatDisplayOptions = {},
-): string {
+): string | Array<string> {
   const platform = options.platform ?? detectPlatform()
-  const useSymbols = options.useSymbols ?? true
-  const separatorToken =
-    options.separatorToken ?? (platform === 'mac' && useSymbols ? ' ' : '+')
-  const normalizedHotkey = normalizeRegisterableHotkey(
-    hotkey as RegisterableHotkey,
-    platform,
-  )
-  return normalizedHotkey
-    .split('+')
-    .map((segment) => {
-      if (isModifierKey(segment)) {
-        const modifierToken = (MODIFIER_ALIASES[segment] ??
-          MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'
-        return platform === 'mac'
-          ? useSymbols
-            ? MAC_MODIFIER_SYMBOLS[modifierToken]
-            : MAC_MODIFIER_LABELS[modifierToken]
-          : platform === 'windows'
-            ? WINDOWS_MODIFIER_LABELS[modifierToken]
-            : LINUX_MODIFIER_LABELS[modifierToken]
-      } else {
-        const keyDisplaySymbol =
-          useSymbols &&
-          KEY_DISPLAY_SYMBOLS[segment as keyof typeof KEY_DISPLAY_SYMBOLS]
-        if (keyDisplaySymbol) return keyDisplaySymbol
-
-        const punctuationKeyDisplayLabel =
-          !useSymbols &&
-          PUNCTUATION_KEY_DISPLAY_LABELS[
-            segment as keyof typeof PUNCTUATION_KEY_DISPLAY_LABELS
-          ]
-        return punctuationKeyDisplayLabel || segment
-      }
-    })
-    .join(separatorToken)
+  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 normalized =
+    typeof hotkey === 'object' && 'modifiers' in hotkey
+      ? normalizeHotkeyFromParsed(hotkey, platform)
+      : normalizeRegisterableHotkey(hotkey as RegisterableHotkey, platform)
+  const parts = splitHotkeyParts(normalized).map((segment) => {
+    if (isModifierKey(segment)) {
+      const modifier = (MODIFIER_ALIASES[segment] ??
+        MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'
+      return platform === 'mac'
+        ? modifierSymbols
+          ? MAC_MODIFIER_SYMBOLS[modifier]
+          : MAC_MODIFIER_LABELS[modifier]
+        : platform === 'windows'
+          ? WINDOWS_MODIFIER_LABELS[modifier]
+          : LINUX_MODIFIER_LABELS[modifier]
+    }
+    const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(segment)?.[1]
+    const label = options.keyLabels?.[code ?? segment]
+    if (label !== undefined) return label
+    // Shorten conventional position labels for display only; stored identity is unchanged.
+    const numpad = code?.startsWith('Numpad') ?? false
+    let displayKey = code ?? segment
+    const mappedKey = code ? options.layoutMap?.get(code) : undefined
+    if (mappedKey) {
+      // Layout entries are logical labels; normalize their case and whitespace names.
+      displayKey = 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 = PUNCTUATION_CODE_MAP[code] ?? code
+    }
+    const labels = keySymbols
+      ? KEY_DISPLAY_SYMBOLS
+      : PUNCTUATION_KEY_DISPLAY_LABELS
+    const display =
+      (labels as Partial<Record<string, string>>)[displayKey] ?? displayKey
+    // Retain numpad identity while making longer names such as MemoryAdd readable.
+    return numpad
+      ? `Numpad ${display.replace(/([a-z])([A-Z])/g, '$1 $2')}`
+      : display
+  })
+  return options.parts ? parts : parts.join(separator)
 }
 
 /**
@@ -136,7 +172,30 @@ export function formatForDisplay(
  */
 export function formatWithLabels(
   hotkey: RegisterableHotkey,
-  options: Omit<FormatDisplayOptions, 'useSymbols'> = {},
+  options: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'> = {},
 ): string {
   return formatForDisplay(hotkey, { ...options, useSymbols: false })
 }
+
+/**
+ * Options for formatting hotkeys for display.
+ */
+export 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
+}

package/src/hint.ts

@@ -0,0 +1,42 @@
+import { MODIFIER_KEYS, normalizeKeyName } from './constants'
+import { parseRegisterableHotkey } from './parse'
+import type { CanonicalModifier } from './key.types'
+import type { RegisterableHotkey } from './hotkey.types'
+
+export interface HeldModifierOptions {
+  /** Resolve Mod for this platform. Defaults to platform detection. */
+  platform?: 'mac' | 'windows' | 'linux'
+  /** Require every binding modifier to be held. Default: false (nonempty subset). */
+  exact?: boolean
+}
+
+/**
+ * Returns whether held modifiers should reveal a shortcut hint.
+ * By default, any nonempty subset of the binding's modifiers qualifies; an
+ * unrelated modifier hides the hint. `exact` requires every binding modifier.
+ * Nonmodifier keys are ignored. This does not check registration or focus.
+ *
+ * @example
+ * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
+ * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
+ */
+export function matchesHeldModifiers(
+  hotkey: RegisterableHotkey,
+  heldKeys: ReadonlyArray<string>,
+  options: HeldModifierOptions = {},
+): boolean {
+  // AltGraph (AltGr) types alternate characters such as @ or € on many layouts.
+  // It can synthesize Ctrl+Alt; character entry should not reveal shortcut hints.
+  if (heldKeys.includes('AltGraph')) return false
+  const held = [
+    ...new Set(
+      heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)),
+    ),
+  ]
+  const { modifiers } = parseRegisterableHotkey(hotkey, options.platform)
+  return (
+    held.length > 0 &&
+    held.every((key) => modifiers.includes(key as CanonicalModifier)) &&
+    (!options.exact || held.length === modifiers.length)
+  )
+}