@tanstack/hotkeys 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/store": "^0.9.2"
+    "@tanstack/store": "^0.9.3"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/src/constants.ts

@@ -8,10 +8,6 @@ import type {
   PunctuationKey,
 } from './hotkey'
 
-// =============================================================================
-// Platform Detection
-// =============================================================================
-
 /**
  * Detects the current platform based on browser navigator properties.
  *
@@ -46,10 +42,6 @@ export function detectPlatform(): 'mac' | 'windows' | 'linux' {
   return 'linux'
 }
 
-// =============================================================================
-// Modifier Aliases
-// =============================================================================
-
 /**
  * Canonical order for modifiers in normalized hotkey strings.
  *
@@ -124,6 +116,12 @@ export const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {
   cmd: 'Meta',
   meta: 'Meta',
 
+  // DOM `KeyboardEvent.key` spellings for the meta / Windows key
+  OS: 'Meta',
+  os: 'Meta',
+  Win: 'Meta',
+  win: 'Meta',
+
   // Platform-adaptive (resolved at runtime)
   CommandOrControl: 'Mod',
   Mod: 'Mod',
@@ -162,10 +160,6 @@ export function resolveModifier(
   return modifier
 }
 
-// =============================================================================
-// Valid Keys
-// =============================================================================
-
 /**
  * Set of all valid letter keys (A-Z).
  *
@@ -311,16 +305,16 @@ export const PUNCTUATION_KEYS = new Set<PunctuationKey>([
  * fallbacks for letters and digits.
  */
 export const PUNCTUATION_CODE_MAP: Record<string, string> = {
-  Minus: '-',
-  Equal: '=',
-  Slash: '/',
+  Backquote: '`',
+  Backslash: '\\',
   BracketLeft: '[',
   BracketRight: ']',
-  Backslash: '\\',
   Comma: ',',
+  Equal: '=',
+  Minus: '-',
   Period: '.',
-  Backquote: '`',
   Semicolon: ';',
+  Slash: '/',
 }
 
 /**
@@ -446,6 +440,20 @@ export function isSingleLetterKey(key: string): boolean {
   return /^\p{Letter}$/u.test(key)
 }
 
+/**
+ * Normalizes a key name to its canonical form.
+ *
+ * @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) {
@@ -488,11 +496,35 @@ export function normalizeKeyName(key: string): string {
  * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
  * ```
  */
-export const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {
+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',
 }
 
 /**
@@ -510,13 +542,35 @@ export const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string> = {
  * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
  * ```
  */
-export const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {
+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.
  *
@@ -532,7 +586,7 @@ export const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string> = {
  * KEY_DISPLAY_SYMBOLS['Space'] // '␣'
  * ```
  */
-export const KEY_DISPLAY_SYMBOLS: Record<string, string> = {
+export const KEY_DISPLAY_SYMBOLS = {
   ArrowUp: '↑',
   ArrowDown: '↓',
   ArrowLeft: '←',
@@ -543,4 +597,4 @@ export const KEY_DISPLAY_SYMBOLS: Record<string, string> = {
   Delete: '⌦',
   Tab: '⇥',
   Space: '␣',
-}
+} as const satisfies Record<string, string>

package/src/format.ts

@@ -1,12 +1,26 @@
 import {
   KEY_DISPLAY_SYMBOLS,
+  LINUX_MODIFIER_LABELS,
+  MAC_MODIFIER_LABELS,
   MAC_MODIFIER_SYMBOLS,
+  MODIFIER_ALIASES,
   MODIFIER_ORDER,
-  STANDARD_MODIFIER_LABELS,
+  PUNCTUATION_KEY_DISPLAY_LABELS,
+  WINDOWS_MODIFIER_LABELS,
   detectPlatform,
 } from './constants'
-import { parseHotkey } from './parse'
-import type { FormatDisplayOptions, Hotkey, ParsedHotkey } from './hotkey'
+import {
+  isModifierKey,
+  normalizeHotkeyFromParsed,
+  normalizeRegisterableHotkey,
+} from './parse'
+import type {
+  CanonicalModifier,
+  FormatDisplayOptions,
+  Hotkey,
+  ParsedHotkey,
+  RegisterableHotkey,
+} from './hotkey'
 
 /**
  * Converts a hotkey sequence array to a display string.
@@ -55,8 +69,8 @@ export function formatHotkey(parsed: ParsedHotkey): string {
 /**
  * Formats a hotkey for display in a user interface.
  *
- * On macOS, uses symbols (⌘⇧S).
- * On Windows/Linux, uses text (Ctrl+Shift+S).
+ * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
+ * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  *
  * @param hotkey - The hotkey string or ParsedHotkey to format
  * @param options - Formatting options
@@ -65,7 +79,7 @@ export function formatHotkey(parsed: ParsedHotkey): string {
  * @example
  * ```ts
  * formatForDisplay('Mod+Shift+S', { platform: 'mac' })
- * // Returns: '⇧⌘S'
+ * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)
  *
  * formatForDisplay('Mod+Shift+S', { platform: 'windows' })
  * // Returns: 'Ctrl+Shift+S'
@@ -75,203 +89,51 @@ export function formatHotkey(parsed: ParsedHotkey): string {
  * ```
  */
 export function formatForDisplay(
-  hotkey: Hotkey | (string & {}) | ParsedHotkey,
+  hotkey: RegisterableHotkey | (string & {}),
   options: FormatDisplayOptions = {},
 ): string {
   const platform = options.platform ?? detectPlatform()
-  const parsed =
-    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
-
-  if (platform === 'mac') {
-    return formatForMac(parsed)
-  }
-
-  return formatForStandard(parsed)
-}
-
-/**
- * Formats a hotkey for macOS display using symbols.
- */
-function formatForMac(parsed: ParsedHotkey): string {
-  const parts: Array<string> = []
-
-  // Add modifiers in macOS order (typically Control, Option, Shift, Command)
-  // But we'll use our canonical order and just use symbols
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(MAC_MODIFIER_SYMBOLS[modifier])
-    }
-  }
-
-  // Add the key (use symbol if available, otherwise the key itself)
-  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key
-  parts.push(keyDisplay)
-
-  // On Mac, modifiers are typically concatenated without separators
-  return parts.join('')
-}
-
-/**
- * Formats a hotkey for Windows/Linux display using text labels.
- */
-function formatForStandard(parsed: ParsedHotkey): string {
-  const parts: Array<string> = []
-
-  // Add modifiers in canonical order
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(STANDARD_MODIFIER_LABELS[modifier])
-    }
-  }
-
-  // Add the key (use symbol/short form if available)
-  const keyDisplay = KEY_DISPLAY_SYMBOLS[parsed.key] ?? parsed.key
-  parts.push(keyDisplay)
-
-  // On Windows/Linux, use + as separator
-  return parts.join('+')
+  const useSymbols = options.useSymbols ?? true
+  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(platform === 'mac' && useSymbols ? ' ' : '+')
 }
 
 /**
- * Formats a hotkey using platform-agnostic labels.
- * Uses 'Cmd' on Mac and 'Ctrl' for Control, etc.
- *
- * @param hotkey - The hotkey string or ParsedHotkey to format
- * @param platform - The target platform
- * @returns A formatted string with platform-appropriate labels
+ * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */
 export function formatWithLabels(
-  hotkey: Hotkey | (string & {}),
-  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
-): string {
-  const parsed =
-    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
-  const parts: Array<string> = []
-
-  // Custom labels for more readable output
-  const labels: Record<string, string> = {
-    Control: 'Ctrl',
-    Alt: platform === 'mac' ? 'Option' : 'Alt',
-    Shift: 'Shift',
-    Meta: platform === 'mac' ? 'Cmd' : 'Win',
-  }
-
-  for (const modifier of MODIFIER_ORDER) {
-    if (parsed.modifiers.includes(modifier)) {
-      parts.push(labels[modifier] ?? modifier)
-    }
-  }
-
-  // Add the key
-  parts.push(parsed.key)
-
-  return parts.join('+')
-}
-
-// =============================================================================
-// Debugging Display Labels
-// =============================================================================
-
-/**
- * Maps canonical modifier names to debugging-friendly labels per platform.
- */
-const MODIFIER_DEBUG_LABELS: Record<string, Record<string, string>> = {
-  mac: { Meta: 'Mod (Cmd)', Control: 'Ctrl', Alt: 'Opt', Shift: 'Shift' },
-  windows: { Control: 'Mod (Ctrl)', Meta: 'Win', Alt: 'Alt', Shift: 'Shift' },
-  linux: { Control: 'Mod (Ctrl)', Meta: 'Super', Alt: 'Alt', Shift: 'Shift' },
-}
-
-/**
- * Options for formatting a single key for debugging display.
- */
-export interface FormatKeyDebuggingOptions {
-  /** The target platform. Defaults to auto-detection. */
-  platform?: 'mac' | 'windows' | 'linux'
-  /**
-   * Whether the input value comes from `event.key` or `event.code`.
-   *
-   * - `'key'` (default): Applies rich platform-aware formatting (modifier
-   *   labels, special-key symbols, etc.).
-   * - `'code'`: Returns the value unchanged — physical key codes like
-   *   `"MetaLeft"` or `"KeyA"` are already descriptive for debugging.
-   */
-  source?: 'key' | 'code'
-}
-
-/**
- * Formats a single key name for debugging/devtools display.
- *
- * Unlike `formatForDisplay` which formats full hotkey strings for end-user UIs,
- * this function formats individual key names (from `event.key`) with rich
- * platform-aware labels suitable for debugging tools and developer-facing displays.
- *
- * Features:
- * - Modifier keys show their platform role (e.g., "Mod (Cmd)" for Meta on Mac)
- * - On macOS, modifier keys are prefixed with their symbol (e.g., "⌘ Mod (Cmd)")
- * - Special keys use display symbols (ArrowUp -> "↑", Escape -> "Esc")
- * - Regular keys pass through unchanged
- *
- * @param key - A single key name (e.g., "Meta", "Shift", "ArrowUp", "A")
- * @param options - Formatting options
- * @returns A formatted label suitable for debugging display
- *
- * @example
- * ```ts
- * // On macOS:
- * formatKeyForDebuggingDisplay('Meta')    // '⌘ Mod (Cmd)'
- * formatKeyForDebuggingDisplay('Control') // '⌃ Ctrl'
- * formatKeyForDebuggingDisplay('Alt')     // '⌥ Opt'
- * formatKeyForDebuggingDisplay('Shift')   // '⇧ Shift'
- *
- * // On Windows:
- * formatKeyForDebuggingDisplay('Control') // 'Mod (Ctrl)'
- * formatKeyForDebuggingDisplay('Meta')    // 'Win'
- *
- * // Special keys (all platforms):
- * formatKeyForDebuggingDisplay('ArrowUp') // '↑'
- * formatKeyForDebuggingDisplay('Escape')  // 'Esc'
- * formatKeyForDebuggingDisplay('Space')   // '␣'
- *
- * // Regular keys pass through:
- * formatKeyForDebuggingDisplay('A')       // 'A'
- *
- * // With source: 'code', values pass through unchanged:
- * formatKeyForDebuggingDisplay('MetaLeft', { source: 'code' })  // 'MetaLeft'
- * formatKeyForDebuggingDisplay('KeyA', { source: 'code' })      // 'KeyA'
- * ```
- */
-export function formatKeyForDebuggingDisplay(
-  key: string,
-  options: FormatKeyDebuggingOptions = {},
+  hotkey: RegisterableHotkey,
+  options: Omit<FormatDisplayOptions, 'useSymbols'> = {},
 ): string {
-  // For event.code values, pass through unchanged — they're already
-  // descriptive for debugging (e.g. "MetaLeft", "KeyA", "ShiftRight").
-  if (options.source === 'code') {
-    return key
-  }
-
-  const platform = options.platform ?? detectPlatform()
-
-  // Check if it's a modifier key
-  const modLabel = MODIFIER_DEBUG_LABELS[platform]?.[key]
-  if (modLabel) {
-    // On Mac, prefix modifier labels with their symbol
-    if (platform === 'mac') {
-      const symbol =
-        MAC_MODIFIER_SYMBOLS[key as keyof typeof MAC_MODIFIER_SYMBOLS]
-      if (symbol) {
-        return `${symbol} ${modLabel}`
-      }
-    }
-    return modLabel
-  }
-
-  // Check if it's a special key with a display symbol
-  const symbol = KEY_DISPLAY_SYMBOLS[key]
-  if (symbol) {
-    return symbol
-  }
-
-  // Regular key — pass through
-  return key
+  return formatForDisplay(hotkey, { ...options, useSymbols: false })
 }

package/src/hotkey-manager.ts

@@ -27,7 +27,11 @@ export type { ConflictBehavior }
 export interface HotkeyOptions {
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
   conflictBehavior?: ConflictBehavior
-  /** Whether the hotkey is enabled. Defaults to true */
+  /**
+   * Soft-disable: when `false`, the callback does not run but the registration
+   * stays in `HotkeyManager` (and in devtools). Toggling this should update the
+   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.
+   */
   enabled?: boolean
   /** The event type to listen for. Defaults to 'keydown' */
   eventType?: 'keydown' | 'keyup'

package/src/hotkey.ts

@@ -368,6 +368,8 @@ export type RegisterableHotkey = Hotkey | RawHotkey
 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
 }
 
 /**