@tanstack/hotkeys 0.0.1 → 0.0.2

package/dist/validate.js

@@ -0,0 +1,114 @@
+import { ALL_KEYS, MODIFIER_ALIASES } from "./constants.js";
+
+//#region src/validate.ts
+/**
+* Validates a hotkey string and returns any warnings or errors.
+*
+* Checks for:
+* - Valid syntax (modifier+...+key format)
+* - Known modifiers
+* - Known keys
+*
+* @param hotkey - The hotkey string to validate
+* @returns A ValidationResult with validity status, warnings, and errors
+*
+* @example
+* ```ts
+* validateHotkey('Mod+S')
+* // { valid: true, warnings: [], errors: [] }
+*
+* validateHotkey('')
+* // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+* ```
+*/
+function validateHotkey(hotkey) {
+	const warnings = [];
+	const errors = [];
+	if (!hotkey || hotkey.trim() === "") return {
+		valid: false,
+		warnings: [],
+		errors: ["Hotkey cannot be empty"]
+	};
+	const parts = hotkey.split("+").map((p) => p.trim());
+	if (parts.length === 0 || parts.some((p) => p === "")) return {
+		valid: false,
+		warnings: [],
+		errors: ["Invalid hotkey format: empty parts detected"]
+	};
+	const modifierParts = parts.slice(0, -1);
+	const keyPart = parts[parts.length - 1];
+	for (const modifier of modifierParts) if (!(MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()])) errors.push(`Unknown modifier: '${modifier}'`);
+	if (!isKnownKey(normalizeKeyForValidation(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	return {
+		valid: errors.length === 0,
+		warnings,
+		errors
+	};
+}
+/**
+* Normalizes a key for validation checking.
+*/
+function normalizeKeyForValidation(key) {
+	if (key.length === 1 && /^[a-zA-Z]$/.test(key)) return key.toUpperCase();
+	if (/^f([1-9]|1[0-2])$/i.test(key)) return key.toUpperCase();
+	return key;
+}
+/**
+* Checks if a key is in the known keys set.
+*/
+function isKnownKey(key) {
+	if (ALL_KEYS.has(key)) return true;
+	if (key.length === 1 && ALL_KEYS.has(key.toUpperCase())) return true;
+	return key in {
+		Esc: true,
+		Return: true,
+		Space: true,
+		" ": true,
+		Del: true,
+		Up: true,
+		Down: true,
+		Left: true,
+		Right: true
+	};
+}
+/**
+* Validates a hotkey and throws an error if invalid.
+* Useful for development-time validation.
+*
+* @param hotkey - The hotkey string to validate
+* @throws Error if the hotkey is invalid
+*
+* @example
+* ```ts
+* assertValidHotkey('Mod+S') // OK
+* assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+* ```
+*/
+function assertValidHotkey(hotkey) {
+	const result = validateHotkey(hotkey);
+	if (!result.valid) throw new Error(`Invalid hotkey '${hotkey}': ${result.errors.join(", ")}`);
+}
+/**
+* Validates a hotkey and logs warnings to the console.
+* Useful for development-time feedback.
+*
+* @param hotkey - The hotkey string to validate
+* @returns True if the hotkey is valid (may still have warnings)
+*
+* @example
+* ```ts
+* checkHotkey('Alt+C')
+* // Console: Warning: Alt+C may not work reliably on macOS...
+* // Returns: true
+* ```
+*/
+function checkHotkey(hotkey) {
+	const result = validateHotkey(hotkey);
+	if (result.errors.length > 0) console.error(`Hotkey '${hotkey}' errors:`, result.errors.join("; "));
+	if (result.warnings.length > 0) console.warn(`Hotkey '${hotkey}' warnings:`, result.warnings.join("; "));
+	return result.valid;
+}
+
+//#endregion
+export { assertValidHotkey, checkHotkey, validateHotkey };
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","names":[],"sources":["../src/validate.ts"],"sourcesContent":["import { ALL_KEYS, MODIFIER_ALIASES } from './constants'\nimport type { Hotkey, ValidationResult } from './hotkey'\n\n/**\n * Validates a hotkey string and returns any warnings or errors.\n *\n * Checks for:\n * - Valid syntax (modifier+...+key format)\n * - Known modifiers\n * - Known keys\n *\n * @param hotkey - The hotkey string to validate\n * @returns A ValidationResult with validity status, warnings, and errors\n *\n * @example\n * ```ts\n * validateHotkey('Mod+S')\n * // { valid: true, warnings: [], errors: [] }\n *\n * validateHotkey('')\n * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }\n * ```\n */\nexport function validateHotkey(\n  hotkey: Hotkey | (string & {}),\n): ValidationResult {\n  const warnings: Array<string> = []\n  const errors: Array<string> = []\n\n  // Check for empty string\n  if (!hotkey || hotkey.trim() === '') {\n    return {\n      valid: false,\n      warnings: [],\n      errors: ['Hotkey cannot be empty'],\n    }\n  }\n\n  const parts = hotkey.split('+').map((p) => p.trim())\n\n  // Must have at least one part (the key)\n  if (parts.length === 0 || parts.some((p) => p === '')) {\n    return {\n      valid: false,\n      warnings: [],\n      errors: ['Invalid hotkey format: empty parts detected'],\n    }\n  }\n\n  // Validate modifiers (all parts except the last)\n  const modifierParts = parts.slice(0, -1)\n  const keyPart = parts[parts.length - 1]!\n\n  // Check for unknown modifiers\n  for (const modifier of modifierParts) {\n    const normalized =\n      MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()]\n    if (!normalized) {\n      errors.push(`Unknown modifier: '${modifier}'`)\n    }\n  }\n\n  // Check if key is known\n  const normalizedKey = normalizeKeyForValidation(keyPart)\n  if (!isKnownKey(normalizedKey) && !isKnownKey(keyPart)) {\n    warnings.push(\n      `Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`,\n    )\n  }\n\n  return {\n    valid: errors.length === 0,\n    warnings,\n    errors,\n  }\n}\n\n/**\n * Normalizes a key for validation checking.\n */\nfunction normalizeKeyForValidation(key: string): string {\n  // Single letter to uppercase\n  if (key.length === 1 && /^[a-zA-Z]$/.test(key)) {\n    return key.toUpperCase()\n  }\n\n  // Function keys to uppercase\n  if (/^f([1-9]|1[0-2])$/i.test(key)) {\n    return key.toUpperCase()\n  }\n\n  return key\n}\n\n/**\n * Checks if a key is in the known keys set.\n */\nfunction isKnownKey(key: string): boolean {\n  // Check direct match\n  if (ALL_KEYS.has(key as any)) {\n    return true\n  }\n\n  // Check uppercase version for letters\n  if (key.length === 1 && ALL_KEYS.has(key.toUpperCase() as any)) {\n    return true\n  }\n\n  // Check common aliases\n  const aliases: Record<string, boolean> = {\n    Esc: true,\n    Return: true,\n    Space: true,\n    ' ': true,\n    Del: true,\n    Up: true,\n    Down: true,\n    Left: true,\n    Right: true,\n  }\n\n  return key in aliases\n}\n\n/**\n * Validates a hotkey and throws an error if invalid.\n * Useful for development-time validation.\n *\n * @param hotkey - The hotkey string to validate\n * @throws Error if the hotkey is invalid\n *\n * @example\n * ```ts\n * assertValidHotkey('Mod+S') // OK\n * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty\n * ```\n */\nexport function assertValidHotkey(hotkey: Hotkey | (string & {})): void {\n  const result = validateHotkey(hotkey)\n  if (!result.valid) {\n    throw new Error(`Invalid hotkey '${hotkey}': ${result.errors.join(', ')}`)\n  }\n}\n\n/**\n * Validates a hotkey and logs warnings to the console.\n * Useful for development-time feedback.\n *\n * @param hotkey - The hotkey string to validate\n * @returns True if the hotkey is valid (may still have warnings)\n *\n * @example\n * ```ts\n * checkHotkey('Alt+C')\n * // Console: Warning: Alt+C may not work reliably on macOS...\n * // Returns: true\n * ```\n */\nexport function checkHotkey(hotkey: Hotkey | (string & {})): boolean {\n  const result = validateHotkey(hotkey)\n\n  if (result.errors.length > 0) {\n    console.error(`Hotkey '${hotkey}' errors:`, result.errors.join('; '))\n  }\n\n  if (result.warnings.length > 0) {\n    console.warn(`Hotkey '${hotkey}' warnings:`, result.warnings.join('; '))\n  }\n\n  return result.valid\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,eACd,QACkB;CAClB,MAAM,WAA0B,EAAE;CAClC,MAAM,SAAwB,EAAE;AAGhC,KAAI,CAAC,UAAU,OAAO,MAAM,KAAK,GAC/B,QAAO;EACL,OAAO;EACP,UAAU,EAAE;EACZ,QAAQ,CAAC,yBAAyB;EACnC;CAGH,MAAM,QAAQ,OAAO,MAAM,IAAI,CAAC,KAAK,MAAM,EAAE,MAAM,CAAC;AAGpD,KAAI,MAAM,WAAW,KAAK,MAAM,MAAM,MAAM,MAAM,GAAG,CACnD,QAAO;EACL,OAAO;EACP,UAAU,EAAE;EACZ,QAAQ,CAAC,8CAA8C;EACxD;CAIH,MAAM,gBAAgB,MAAM,MAAM,GAAG,GAAG;CACxC,MAAM,UAAU,MAAM,MAAM,SAAS;AAGrC,MAAK,MAAM,YAAY,cAGrB,KAAI,EADF,iBAAiB,aAAa,iBAAiB,SAAS,aAAa,GAErE,QAAO,KAAK,sBAAsB,SAAS,GAAG;AAMlD,KAAI,CAAC,WADiB,0BAA0B,QAAQ,CAC1B,IAAI,CAAC,WAAW,QAAQ,CACpD,UAAS,KACP,iBAAiB,QAAQ,+DAC1B;AAGH,QAAO;EACL,OAAO,OAAO,WAAW;EACzB;EACA;EACD;;;;;AAMH,SAAS,0BAA0B,KAAqB;AAEtD,KAAI,IAAI,WAAW,KAAK,aAAa,KAAK,IAAI,CAC5C,QAAO,IAAI,aAAa;AAI1B,KAAI,qBAAqB,KAAK,IAAI,CAChC,QAAO,IAAI,aAAa;AAG1B,QAAO;;;;;AAMT,SAAS,WAAW,KAAsB;AAExC,KAAI,SAAS,IAAI,IAAW,CAC1B,QAAO;AAIT,KAAI,IAAI,WAAW,KAAK,SAAS,IAAI,IAAI,aAAa,CAAQ,CAC5D,QAAO;AAgBT,QAAO,OAZkC;EACvC,KAAK;EACL,QAAQ;EACR,OAAO;EACP,KAAK;EACL,KAAK;EACL,IAAI;EACJ,MAAM;EACN,MAAM;EACN,OAAO;EACR;;;;;;;;;;;;;;;AAkBH,SAAgB,kBAAkB,QAAsC;CACtE,MAAM,SAAS,eAAe,OAAO;AACrC,KAAI,CAAC,OAAO,MACV,OAAM,IAAI,MAAM,mBAAmB,OAAO,KAAK,OAAO,OAAO,KAAK,KAAK,GAAG;;;;;;;;;;;;;;;;AAkB9E,SAAgB,YAAY,QAAyC;CACnE,MAAM,SAAS,eAAe,OAAO;AAErC,KAAI,OAAO,OAAO,SAAS,EACzB,SAAQ,MAAM,WAAW,OAAO,YAAY,OAAO,OAAO,KAAK,KAAK,CAAC;AAGvE,KAAI,OAAO,SAAS,SAAS,EAC3B,SAAQ,KAAK,WAAW,OAAO,cAAc,OAAO,SAAS,KAAK,KAAK,CAAC;AAG1E,QAAO,OAAO"}

package/package.json

@@ -1,10 +1,58 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tanstack/hotkeys",
+  "version": "0.0.2",
+  "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "tanstack",
+    "keys",
+    "hotkeys",
+    "keyboard",
+    "shortcuts",
+    "keybindings",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/store": "^0.8.0"
+  },
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,514 @@
+import type {
+  CanonicalModifier,
+  EditingKey,
+  FunctionKey,
+  LetterKey,
+  NavigationKey,
+  NumberKey,
+  PunctuationKey,
+} from './hotkey'
+
+// =============================================================================
+// Platform Detection
+// =============================================================================
+
+/**
+ * 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
+  }
+
+  const platform = navigator.platform.toLowerCase()
+  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'
+}
+
+// =============================================================================
+// Modifier Aliases
+// =============================================================================
+
+/**
+ * Canonical order for modifiers in normalized hotkey strings.
+ *
+ * Defines the standard order in which modifiers should appear when formatting
+ * hotkeys. This ensures consistent, predictable output across the library.
+ *
+ * Order: Control → Alt → Shift → Meta
+ *
+ * @example
+ * ```ts
+ * // Input: 'Shift+Control+Meta+S'
+ * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)
+ * ```
+ */
+export const MODIFIER_ORDER: Array<CanonicalModifier> = [
+  'Control',
+  'Alt',
+  'Shift',
+  'Meta',
+]
+
+/**
+ * Set of canonical modifier key names for fast lookup.
+ *
+ * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when
+ * a modifier is released so we can clear non-modifier keys whose keyup events
+ * may have been swallowed by the OS (e.g. macOS Cmd+key combos).
+ */
+export const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)
+
+/**
+ * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
+ *
+ * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')
+ * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the
+ * platform-adaptive 'Mod' token.
+ *
+ * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`
+ * based on the detected platform (Command on Mac, Control elsewhere).
+ *
+ * @remarks Case-insensitive lookups are supported via lowercase variants
+ *
+ * @example
+ * ```ts
+ * MODIFIER_ALIASES['Ctrl'] // 'Control'
+ * MODIFIER_ALIASES['Cmd'] // 'Meta'
+ * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)
+ * ```
+ */
+export const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {
+  // Control variants
+  Control: 'Control',
+  Ctrl: 'Control',
+  control: 'Control',
+  ctrl: 'Control',
+
+  // Shift variants
+  Shift: 'Shift',
+  shift: 'Shift',
+
+  // Alt variants
+  Alt: 'Alt',
+  Option: 'Alt',
+  alt: 'Alt',
+  option: 'Alt',
+
+  // Meta/Command variants
+  Command: 'Meta',
+  Cmd: 'Meta',
+  Meta: 'Meta',
+  command: 'Meta',
+  cmd: 'Meta',
+  meta: 'Meta',
+
+  // Platform-adaptive (resolved at runtime)
+  CommandOrControl: 'Mod',
+  Mod: 'Mod',
+  commandorcontrol: '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
+}
+
+// =============================================================================
+// Valid Keys
+// =============================================================================
+
+/**
+ * Set of all valid letter keys (A-Z).
+ *
+ * Used for validation and type checking. Letter keys are matched case-insensitively
+ * in hotkey matching, but normalized to uppercase in canonical form.
+ */
+export const LETTER_KEYS = new Set<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',
+])
+
+/**
+ * Set of all valid number keys (0-9).
+ *
+ * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid
+ * layout-dependent behavior.
+ */
+export const NUMBER_KEYS = new Set<NumberKey>([
+  '0',
+  '1',
+  '2',
+  '3',
+  '4',
+  '5',
+  '6',
+  '7',
+  '8',
+  '9',
+])
+
+/**
+ * Set of all valid function keys (F1-F12).
+ *
+ * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
+ * Alt+F4 to close windows) and application-specific commands.
+ */
+export const FUNCTION_KEYS = new Set<FunctionKey>([
+  'F1',
+  'F2',
+  'F3',
+  'F4',
+  'F5',
+  'F6',
+  'F7',
+  'F8',
+  'F9',
+  'F10',
+  'F11',
+  'F12',
+])
+
+/**
+ * Set of all valid navigation keys for cursor movement and document navigation.
+ *
+ * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).
+ * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
+ * navigation shortcuts (Alt+ArrowLeft for back).
+ */
+export const NAVIGATION_KEYS = new Set<NavigationKey>([
+  'ArrowUp',
+  'ArrowDown',
+  'ArrowLeft',
+  'ArrowRight',
+  'Home',
+  'End',
+  'PageUp',
+  'PageDown',
+])
+
+/**
+ * Set of all valid editing and special keys.
+ *
+ * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and
+ * special actions (Escape, Space). These keys are frequently combined with modifiers
+ * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
+ */
+export const EDITING_KEYS = new Set<EditingKey>([
+  'Enter',
+  'Escape',
+  'Space',
+  'Tab',
+  'Backspace',
+  'Delete',
+])
+
+/**
+ * Set of all valid punctuation keys commonly used in keyboard shortcuts.
+ *
+ * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,
+ * typically US keyboard layout). Common shortcuts include:
+ * - `Mod+/` - Toggle comment
+ * - `Mod+[` / `Mod+]` - Indent/outdent
+ * - `Mod+=` / `Mod+-` - Zoom in/out
+ *
+ * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
+ */
+export const PUNCTUATION_KEYS = new Set<PunctuationKey>([
+  '/',
+  '[',
+  ']',
+  '\\',
+  '=',
+  '-',
+  ',',
+  '.',
+  '`',
+])
+
+/**
+ * Set of all valid non-modifier keys.
+ *
+ * This is the union of all key type sets (letters, numbers, function keys, navigation,
+ * editing, and punctuation). Used primarily for validation to check if a key string
+ * is recognized and will have type-safe autocomplete support.
+ *
+ * @see {@link LETTER_KEYS}
+ * @see {@link NUMBER_KEYS}
+ * @see {@link FUNCTION_KEYS}
+ * @see {@link NAVIGATION_KEYS}
+ * @see {@link EDITING_KEYS}
+ * @see {@link PUNCTUATION_KEYS}
+ */
+export const ALL_KEYS = new Set([
+  ...LETTER_KEYS,
+  ...NUMBER_KEYS,
+  ...FUNCTION_KEYS,
+  ...NAVIGATION_KEYS,
+  ...EDITING_KEYS,
+  ...PUNCTUATION_KEYS,
+])
+
+/**
+ * Maps key name aliases to their canonical form.
+ *
+ * Handles common variations and alternative names for keys to provide a more
+ * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and
+ * they'll all normalize to 'Escape'.
+ *
+ * This map is used internally by `normalizeKeyName()` to convert user input
+ * into the canonical key names used throughout the library.
+ *
+ * @remarks Case-insensitive lookups are supported via lowercase variants
+ *
+ * @example
+ * ```ts
+ * KEY_ALIASES['Esc'] // 'Escape'
+ * KEY_ALIASES['Del'] // 'Delete'
+ * KEY_ALIASES['Up'] // 'ArrowUp'
+ * ```
+ */
+const KEY_ALIASES: Record<string, string> = {
+  // Escape variants
+  Esc: 'Escape',
+  esc: 'Escape',
+  escape: 'Escape',
+
+  // Enter variants
+  Return: 'Enter',
+  return: 'Enter',
+  enter: 'Enter',
+
+  // Space variants
+  ' ': 'Space',
+  space: 'Space',
+  Spacebar: 'Space',
+  spacebar: 'Space',
+
+  // Tab variants
+  tab: 'Tab',
+
+  // Backspace variants
+  backspace: 'Backspace',
+
+  // Delete variants
+  Del: 'Delete',
+  del: 'Delete',
+  delete: 'Delete',
+
+  // Arrow key variants
+  Up: 'ArrowUp',
+  up: 'ArrowUp',
+  arrowup: 'ArrowUp',
+  Down: 'ArrowDown',
+  down: 'ArrowDown',
+  arrowdown: 'ArrowDown',
+  Left: 'ArrowLeft',
+  left: 'ArrowLeft',
+  arrowleft: 'ArrowLeft',
+  Right: 'ArrowRight',
+  right: 'ArrowRight',
+  arrowright: 'ArrowRight',
+
+  // Navigation variants
+  home: 'Home',
+  end: 'End',
+  pageup: 'PageUp',
+  pagedown: 'PageDown',
+  PgUp: 'PageUp',
+  PgDn: 'PageDown',
+  pgup: 'PageUp',
+  pgdn: 'PageDown',
+}
+
+/**
+ * Normalizes a key name to its canonical form.
+ *
+ * Converts various key name formats (aliases, case variations) into the standard
+ * canonical names used throughout the library. This enables a more forgiving API
+ * where users can write keys in different ways and still get correct behavior.
+ *
+ * Normalization rules:
+ * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
+ * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
+ * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
+ * 4. Other keys → returned as-is (already canonical or unknown)
+ *
+ * @param key - The key name to normalize (can be an alias, lowercase, etc.)
+ * @returns The canonical key name
+ *
+ * @example
+ * ```ts
+ * normalizeKeyName('esc') // 'Escape'
+ * normalizeKeyName('a') // 'A'
+ * normalizeKeyName('f1') // 'F1'
+ * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
+ * ```
+ */
+export function normalizeKeyName(key: string): string {
+  // Check aliases first
+  if (key in KEY_ALIASES) {
+    return KEY_ALIASES[key]!
+  }
+
+  // Check if it's a single letter (normalize to uppercase)
+  if (key.length === 1 && /^[a-zA-Z]$/.test(key)) {
+    return key.toUpperCase()
+  }
+
+  // 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
+}
+
+// =============================================================================
+// 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, string> = {
+  Control: '⌃',
+  Alt: '⌥',
+  Shift: '⇧',
+  Meta: '⌘',
+}
+
+/**
+ * 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 STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {
+  Control: 'Ctrl',
+  Alt: 'Alt',
+  Shift: 'Shift',
+  Meta: 'Win',
+}
+
+/**
+ * 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: Record<string, string> = {
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  Enter: '↵',
+  Escape: 'Esc',
+  Backspace: '⌫',
+  Delete: '⌦',
+  Tab: '⇥',
+  Space: '␣',
+}