@tanstack/hotkeys 0.8.0 → 0.9.0

package/src/key.types.ts

@@ -0,0 +1,268 @@
+import type { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from './_named-keys'
+
+/**
+ * All supported modifier key names, including aliases.
+ * - Control/Ctrl: The Control key
+ * - Shift: The Shift key
+ * - Alt/Option: The Alt key (Option on macOS)
+ * - Command/Cmd: The Command key (macOS only)
+ * - CommandOrControl/Mod: Command on macOS, Control on other platforms
+ */
+export type Modifier =
+  | 'Control'
+  | 'Ctrl'
+  | 'Shift'
+  | 'Alt'
+  | 'Option'
+  | 'Command'
+  | 'Cmd'
+  | 'CommandOrControl'
+  | 'Mod'
+
+/**
+ * Canonical modifier names that map to KeyboardEvent properties.
+ */
+export type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta'
+
+/**
+ * Letter keys A-Z (case-insensitive in matching).
+ */
+export type LetterKey =
+  | 'A'
+  | 'B'
+  | 'C'
+  | 'D'
+  | 'E'
+  | 'F'
+  | 'G'
+  | 'H'
+  | 'I'
+  | 'J'
+  | 'K'
+  | 'L'
+  | 'M'
+  | 'N'
+  | 'O'
+  | 'P'
+  | 'Q'
+  | 'R'
+  | 'S'
+  | 'T'
+  | 'U'
+  | 'V'
+  | 'W'
+  | 'X'
+  | 'Y'
+  | 'Z'
+
+/**
+ * Number keys 0-9.
+ */
+export type NumberKey =
+  | '0'
+  | '1'
+  | '2'
+  | '3'
+  | '4'
+  | '5'
+  | '6'
+  | '7'
+  | '8'
+  | '9'
+
+/**
+ * Function keys F1-F24, supported as both logical keys and physical codes.
+ */
+export type FunctionKey =
+  | 'F1'
+  | 'F2'
+  | 'F3'
+  | 'F4'
+  | 'F5'
+  | 'F6'
+  | 'F7'
+  | 'F8'
+  | 'F9'
+  | 'F10'
+  | 'F11'
+  | 'F12'
+  | 'F13'
+  | 'F14'
+  | 'F15'
+  | 'F16'
+  | 'F17'
+  | 'F18'
+  | 'F19'
+  | 'F20'
+  | 'F21'
+  | 'F22'
+  | 'F23'
+  | 'F24'
+
+/**
+ * Navigation keys for cursor movement.
+ */
+export type NavigationKey =
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'Home'
+  | 'End'
+  | 'PageUp'
+  | 'PageDown'
+
+/**
+ * Editing and special keys.
+ */
+export type EditingKey =
+  | 'Enter'
+  | 'Escape'
+  | 'Space'
+  | 'Tab'
+  | 'Backspace'
+  | 'Delete'
+
+/**
+ * Printable punctuation glyphs used in keyboard shortcuts. Matching uses the
+ * final KeyboardEvent.key glyph, independent of which layout produced it.
+ */
+export type PunctuationKey =
+  | '/'
+  | '['
+  | ']'
+  | '\\'
+  | '='
+  | '-'
+  | ','
+  | '.'
+  | ';'
+  | '`'
+  | "'"
+  | '+'
+  | '?'
+  | '!'
+  | '@'
+  | '#'
+  | '$'
+  | '%'
+  | '^'
+  | '&'
+  | '*'
+  | '('
+  | ')'
+  | '_'
+  | '{'
+  | '}'
+  | '|'
+  | ':'
+  | '"'
+  | '<'
+  | '>'
+  | '~'
+
+/** Additional named logical keys, including media, browser, lock, and input-mode keys. */
+export type NamedKey =
+  | (typeof SHARED_NAMED_KEYS)[number]
+  | (typeof LOGICAL_ONLY_NAMED_KEYS)[number]
+
+/** Supported logical key names other than printable punctuation. */
+export type NonPunctuationKey =
+  | LetterKey
+  | NumberKey
+  | EditingKey
+  | NavigationKey
+  | FunctionKey
+  | NamedKey
+
+/**
+ * Supported physical KeyboardEvent.code names, independent of keyboard layout.
+ * Letter, digit, numpad, and sided modifier names use finite template unions.
+ * `Unidentified` is excluded because it cannot identify a physical key.
+ *
+ * @see https://www.w3.org/TR/uievents-code/
+ */
+export type PhysicalKeyCode =
+  | `Key${LetterKey}`
+  | `Digit${NumberKey}`
+  | `Numpad${NumberKey}`
+  | `${'Alt' | 'Control' | 'Meta' | 'Shift'}${'Left' | 'Right'}`
+  | EditingKey
+  | NavigationKey
+  | FunctionKey
+  | (typeof SHARED_NAMED_KEYS)[number]
+  | 'Backquote'
+  | 'Backslash'
+  | 'BracketLeft'
+  | 'BracketRight'
+  | 'Comma'
+  | 'Equal'
+  | 'IntlBackslash'
+  | 'IntlRo'
+  | 'IntlYen'
+  | 'Minus'
+  | 'Period'
+  | 'Quote'
+  | 'Semicolon'
+  | 'Slash'
+  | `Lang${1 | 2 | 3 | 4 | 5}`
+  | `Numpad${
+      | 'Add'
+      | 'Backspace'
+      | 'Clear'
+      | 'ClearEntry'
+      | 'Comma'
+      | 'Decimal'
+      | 'Divide'
+      | 'Enter'
+      | 'Equal'
+      | 'Hash'
+      | 'MemoryAdd'
+      | 'MemoryClear'
+      | 'MemoryRecall'
+      | 'MemoryStore'
+      | 'MemorySubtract'
+      | 'Multiply'
+      | 'ParenLeft'
+      | 'ParenRight'
+      | 'Star'
+      | 'Subtract'}`
+  | 'LaunchApp1'
+  | 'LaunchApp2'
+  | 'MediaSelect'
+  | 'Sleep'
+  | 'Turbo'
+  | 'Abort'
+  | 'Resume'
+  | 'Suspend'
+
+/**
+ * An explicit physical key token. All codes use brackets, including names such
+ * as `[Enter]` that also exist as logical keys. Invalid code names are rejected
+ * by TypeScript, and supported names are available in autocomplete.
+ */
+export type PhysicalKey = `[${PhysicalKeyCode}]`
+
+/** Supported logical key names, excluding bracketed physical-code syntax. */
+export type LogicalKey = NonPunctuationKey | PunctuationKey
+
+/** All supported logical keys and bracketed physical key tokens. */
+export type Key = LogicalKey | PhysicalKey
+
+/**
+ * Includes both modifier keys and regular keys.
+ */
+export type IndividualKey = CanonicalModifier | Key
+
+/** Keyboard event properties normalized for internal matching and recording. */
+export interface NormalizedKeyboardEvent {
+  key: string
+  code: string
+  ctrl: boolean
+  shift: boolean
+  alt: boolean
+  meta: boolean
+  altGraph: boolean
+  location: number
+  isComposing: boolean
+}

package/src/match.ts

@@ -1,21 +1,27 @@
-import {
-  PUNCTUATION_CODE_MAP,
-  detectPlatform,
-  isSingleLetterKey,
-  normalizeKeyName,
-} from './constants'
-import { parseHotkey } from './parse'
+import { matchKeyboardEvent } from './_match'
+import { parseHotkey, parseRegisterableHotkey } from './parse'
+import { detectPlatform } from './platform'
+import { keysEqual } from './_keyboard-event'
 import type {
   Hotkey,
   HotkeyCallback,
   HotkeyCallbackContext,
   ParsedHotkey,
-} from './hotkey'
+  RegisterableHotkey,
+} from './hotkey.types'
+
+export interface KeyboardEventMatch {
+  matched: boolean
+  score: 0 | 1 | 2 | 3
+  source?: 'key' | 'code' | 'fallback'
+  identity?: { key: string; code: string }
+}
 
 /**
  * Checks if a KeyboardEvent matches a hotkey.
  *
- * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+ * Logical bindings use `event.key`, with a fallback to `code`
  * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
  * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
  * Letter keys are matched case-insensitively.
@@ -45,85 +51,7 @@ export function matchesKeyboardEvent(
   hotkey: Hotkey | ParsedHotkey,
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
 ): boolean {
-  const parsed =
-    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
-
-  // Check modifiers
-  if (event.ctrlKey !== parsed.ctrl) {
-    return false
-  }
-  if (event.shiftKey !== parsed.shift) {
-    return false
-  }
-  if (event.altKey !== parsed.alt) {
-    return false
-  }
-  if (event.metaKey !== parsed.meta) {
-    return false
-  }
-
-  // Check key (case-insensitive for letters)
-  const eventKey = normalizeKeyName(event.key)
-  const hotkeyKey = parsed.key
-
-  // For single-character keys (not dead keys), try direct event.key match first
-  if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {
-    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {
-      return true
-    }
-
-    // If event.key is a letter, we usually trust the keyboard layout.
-    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).
-    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).
-    //
-    // For non-ASCII letters WITH Alt held down: fall through to the event.code
-    // fallback. macOS Option+letter combinations produce non-ASCII letters as
-    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but
-    // event.code still reflects the physical key. We want Alt+A to match even
-    // when Option+A fires event.key='å'.
-    if (
-      isSingleLetterKey(eventKey) &&
-      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)
-    ) {
-      return false
-    }
-  }
-
-  // Fallback to event.code for dead keys or single-char mismatches where
-  // event.key is a non-letter special character.
-  // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'
-  // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'
-  if (
-    event.code &&
-    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))
-  ) {
-    // fallback for letter keys (common with mac option + letter)
-    if (event.code.startsWith('Key')) {
-      const codeLetter = event.code.slice(3)
-      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {
-        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()
-      }
-    }
-
-    // fallback for number keys (common with mac option + num)
-    if (event.code.startsWith('Digit')) {
-      const codeDigit = event.code.slice(5)
-      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {
-        return codeDigit === hotkeyKey
-      }
-    }
-    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).
-    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),
-    // but event.code still reports the physical key.
-    if (event.code in PUNCTUATION_CODE_MAP) {
-      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey
-    }
-
-    return false
-  }
-
-  // For special keys, compare exactly (after normalization)
-  return eventKey === hotkeyKey
+  return matchKeyboardEvent(event, hotkey, platform).matched
 }
 
 /**
@@ -187,7 +115,7 @@ export function createHotkeyHandler(
   }
 }
 
-type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }
+export type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }
 
 /**
  * Creates a handler that matches multiple hotkeys.
@@ -253,7 +181,30 @@ function formatParsedHotkey(parsed: ParsedHotkey): Hotkey {
   if (parsed.alt) parts.push('Alt')
   if (parsed.shift) parts.push('Shift')
   if (parsed.meta) parts.push('Meta')
-  parts.push(parsed.key)
+  parts.push(parsed.code !== undefined ? `[${parsed.code}]` : parsed.key)
 
   return parts.join('+') as Hotkey
 }
+
+/**
+ * Compares normalized binding identity, including all four modifiers.
+ * Aliases resolve on the supplied platform. A physical code and a logical key
+ * remain distinct even when one keyboard event could match both.
+ */
+export function areHotkeysEqual(
+  left: RegisterableHotkey,
+  right: RegisterableHotkey,
+  platform = detectPlatform(),
+): boolean {
+  const a = parseRegisterableHotkey(left, platform)
+  const b = parseRegisterableHotkey(right, platform)
+  return (
+    a.ctrl === b.ctrl &&
+    a.alt === b.alt &&
+    a.shift === b.shift &&
+    a.meta === b.meta &&
+    (a.code !== undefined || b.code !== undefined
+      ? a.code === b.code
+      : keysEqual(a.key, b.key))
+  )
+}

package/src/parse.ts

@@ -1,25 +1,24 @@
 import {
-  MODIFIER_ALIASES,
-  MODIFIER_ORDER,
-  detectPlatform,
-  normalizeKeyName,
-  resolveModifier,
-} from './constants'
+  assertLogicalKey,
+  normalizeKeyboardEvent,
+  splitHotkeyParts,
+} from './_keyboard-event'
+import { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from './constants'
+import { detectPlatform, resolveModifier } from './platform'
+import type { CanonicalModifier, Key } from './key.types'
 import type {
-  CanonicalModifier,
   Hotkey,
-  Key,
   ParsedHotkey,
   RawHotkey,
   RegisterableHotkey,
-} from './hotkey'
+} from './hotkey.types'
 
 /**
  * Parses a hotkey string into its component parts.
  *
  * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey object with the key and modifier flags
+ * @returns A ParsedHotkey with either logical key or physical code and modifier flags
  *
  * @example
  * ```ts
@@ -32,7 +31,7 @@ export function parseHotkey(
   hotkey: Hotkey | (string & {}),
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
 ): ParsedHotkey {
-  const parts = hotkey.split('+')
+  const parts = splitHotkeyParts(hotkey)
   const modifiers: Set<CanonicalModifier> = new Set()
   let key = ''
 
@@ -65,8 +64,9 @@ export function parseHotkey(
     key = normalizeKeyName(parts[parts.length - 1]!.trim())
   }
 
+  const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1]
   return {
-    key,
+    ...(code !== undefined ? { code } : { key }),
     ctrl: modifiers.has('Control'),
     shift: modifiers.has('Shift'),
     alt: modifiers.has('Alt'),
@@ -100,6 +100,7 @@ export function rawHotkeyToParsedHotkey(
   raw: RawHotkey,
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
 ): ParsedHotkey {
+  if (raw.code === undefined) assertLogicalKey(raw.key)
   let ctrl = raw.ctrl ?? false
   const shift = raw.shift ?? false
   const alt = raw.alt ?? false
@@ -129,7 +130,9 @@ export function rawHotkeyToParsedHotkey(
     }
   })
   return {
-    key: raw.key,
+    ...(raw.code !== undefined
+      ? { code: raw.code }
+      : { key: normalizeKeyName(raw.key) }),
     ctrl,
     shift,
     alt,
@@ -147,6 +150,7 @@ function normalizedHotkeyStringFromParsed(
   parsed: ParsedHotkey,
   platform: 'mac' | 'windows' | 'linux',
 ): Hotkey {
+  if (parsed.code === undefined) assertLogicalKey(parsed.key)
   const canUseMod =
     platform === 'mac'
       ? parsed.meta && !parsed.ctrl
@@ -170,7 +174,11 @@ function normalizedHotkeyStringFromParsed(
     }
   }
 
-  parts.push(normalizeKeyName(parsed.key))
+  parts.push(
+    parsed.code !== undefined
+      ? `[${parsed.code}]`
+      : normalizeKeyName(parsed.key),
+  )
   return parts.join('+') as Hotkey
 }
 
@@ -263,22 +271,31 @@ export function isModifierKey(
  * })
  * ```
  */
-export function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {
-  const normalizedKey = normalizeKeyName(event.key)
+export function parseKeyboardEvent(
+  event: KeyboardEvent,
+  platform?: 'mac' | 'windows' | 'linux',
+): ParsedHotkey {
+  const normalized = normalizeKeyboardEvent(event, platform)
+  // AltGraph is a character-production modifier, not an ordinary Control+Alt
+  // shortcut. Record the produced glyph instead of a synthetic Ctrl+Alt chord.
+  const ctrl = normalized.altGraph ? false : normalized.ctrl
+  const alt = normalized.altGraph ? false : normalized.alt
+  // Shift is a real modifier even during AltGraph input; preserve it for replay.
+  const shift = normalized.shift
 
   // Build modifiers array in canonical order
   const modifiers: Array<CanonicalModifier> = []
-  if (event.ctrlKey) modifiers.push('Control')
-  if (event.altKey) modifiers.push('Alt')
-  if (event.shiftKey) modifiers.push('Shift')
-  if (event.metaKey) modifiers.push('Meta')
+  if (ctrl) modifiers.push('Control')
+  if (alt) modifiers.push('Alt')
+  if (shift) modifiers.push('Shift')
+  if (normalized.meta) modifiers.push('Meta')
 
   return {
-    key: normalizedKey,
-    ctrl: event.ctrlKey,
-    shift: event.shiftKey,
-    alt: event.altKey,
-    meta: event.metaKey,
+    key: normalized.key,
+    ctrl,
+    shift,
+    alt,
+    meta: normalized.meta,
     modifiers,
   }
 }
@@ -293,7 +310,10 @@ export function normalizeHotkeyFromEvent(
   event: KeyboardEvent,
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
 ): Hotkey {
-  return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform)
+  return normalizedHotkeyStringFromParsed(
+    parseKeyboardEvent(event, platform),
+    platform,
+  )
 }
 
 /**
@@ -320,9 +340,30 @@ export function hasNonModifierKey(
   const parsed =
     typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
 
+  if (parsed.code !== undefined) {
+    // Physical modifier codes identify a side, but still are not action keys.
+    return (
+      parsed.code.length > 0 &&
+      !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code)
+    )
+  }
+
   // Check if the key part is actually a modifier
   const keyIsModifier = isModifierKey(parsed.key)
 
   // A valid hotkey must have a non-modifier key
   return !keyIsModifier && parsed.key.length > 0
 }
+
+/**
+ * Parses a string or raw binding, resolving Mod for the supplied platform.
+ * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+ */
+export function parseRegisterableHotkey(
+  hotkey: RegisterableHotkey,
+  platform = detectPlatform(),
+): ParsedHotkey {
+  return typeof hotkey === 'string'
+    ? parseHotkey(hotkey, platform)
+    : rawHotkeyToParsedHotkey(hotkey, platform)
+}

package/src/platform.ts

@@ -0,0 +1,66 @@
+import type { CanonicalModifier } from './key.types'
+
+/**
+ * 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'
+}
+
+/**
+ * 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
+}