@tanstack/hotkeys 0.0.1 → 0.1.0

package/src/match.ts

@@ -0,0 +1,222 @@
+import { detectPlatform, normalizeKeyName } from './constants'
+import { parseHotkey } from './parse'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyCallbackContext,
+  ParsedHotkey,
+} from './hotkey'
+
+/**
+ * Checks if a KeyboardEvent matches a hotkey.
+ *
+ * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
+ * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ *
+ * @param event - The KeyboardEvent to check
+ * @param hotkey - The hotkey string or ParsedHotkey to match against
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns True if the event matches the hotkey
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   if (matchesKeyboardEvent(event, 'Mod+S')) {
+ *     event.preventDefault()
+ *     handleSave()
+ *   }
+ * })
+ * ```
+ */
+export function matchesKeyboardEvent(
+  event: KeyboardEvent,
+  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 letters, compare case-insensitively
+  if (eventKey.length === 1 && hotkeyKey.length === 1) {
+    // First try matching with event.key
+    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {
+      return true
+    }
+
+    // Fallback to event.code for letter keys when event.key doesn't match
+    // This handles cases like Command+Option+T on macOS where event.key is '†' instead of 'T'
+    // event.code format for letter keys is "KeyA", "KeyB", etc. (always uppercase in browsers)
+    if (event.code && event.code.startsWith('Key')) {
+      const codeLetter = event.code.slice(3) // Remove "Key" prefix
+      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {
+        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()
+      }
+    }
+
+    // Fallback to event.code for digit keys when event.key doesn't match
+    // This handles cases like Shift+4 where event.key is '$' instead of '4'
+    // event.code format for digit keys is "Digit0", "Digit1", etc.
+    if (event.code && event.code.startsWith('Digit')) {
+      const codeDigit = event.code.slice(5) // Remove "Digit" prefix
+      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {
+        return codeDigit === hotkeyKey
+      }
+    }
+
+    return false
+  }
+
+  // For special keys, compare exactly (after normalization)
+  return eventKey === hotkeyKey
+}
+
+/**
+ * Options for creating a hotkey handler.
+ */
+export interface CreateHotkeyHandlerOptions {
+  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+  preventDefault?: boolean
+  /** Stop event propagation when the hotkey matches. Defaults to true */
+  stopPropagation?: boolean
+  /** The target platform for resolving 'Mod' */
+  platform?: 'mac' | 'windows' | 'linux'
+}
+
+/**
+ * Creates a keyboard event handler that calls the callback when the hotkey matches.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to match
+ * @param callback - The function to call when the hotkey matches
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
+ *   console.log(`${hotkey} was pressed`)
+ *   handleSave()
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+export function createHotkeyHandler(
+  hotkey: Hotkey | ParsedHotkey,
+  callback: HotkeyCallback,
+  options: CreateHotkeyHandlerOptions = {},
+): (event: KeyboardEvent) => void {
+  const { preventDefault = true, stopPropagation = true, platform } = options
+  const resolvedPlatform = platform ?? detectPlatform()
+
+  const hotkeyString: Hotkey =
+    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)
+  const parsed =
+    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey
+
+  const context: HotkeyCallbackContext = {
+    hotkey: hotkeyString,
+    parsedHotkey: parsed,
+  }
+
+  return (event: KeyboardEvent) => {
+    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+      if (preventDefault) {
+        event.preventDefault()
+      }
+      if (stopPropagation) {
+        event.stopPropagation()
+      }
+      callback(event, context)
+    }
+  }
+}
+
+type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }
+
+/**
+ * Creates a handler that matches multiple hotkeys.
+ *
+ * @param handlers - A map of hotkey strings to their handlers
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createMultiHotkeyHandler({
+ *   'Mod+S': (event, { hotkey }) => handleSave(),
+ *   'Mod+Z': (event, { hotkey }) => handleUndo(),
+ *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+export function createMultiHotkeyHandler(
+  handlers: MultiHotkeyHandler,
+  options: CreateHotkeyHandlerOptions = {},
+): (event: KeyboardEvent) => void {
+  const { preventDefault = true, stopPropagation = true, platform } = options
+  const resolvedPlatform = platform ?? detectPlatform()
+
+  // Pre-parse all hotkeys for efficiency
+  const parsedHandlers = Object.entries(handlers)
+    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))
+    .map(([hotkey, handler]) => {
+      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)
+      const context: HotkeyCallbackContext = {
+        hotkey: hotkey as Hotkey,
+        parsedHotkey: parsed,
+      }
+      return { parsed, handler, context }
+    })
+
+  return (event: KeyboardEvent) => {
+    for (const { parsed, handler, context } of parsedHandlers) {
+      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+        if (preventDefault) {
+          event.preventDefault()
+        }
+        if (stopPropagation) {
+          event.stopPropagation()
+        }
+        handler(event, context)
+        return // Only handle the first match
+      }
+    }
+  }
+}
+
+/**
+ * Formats a ParsedHotkey back to a hotkey string.
+ * Used internally to provide the hotkey string in callback context.
+ */
+function formatParsedHotkey(parsed: ParsedHotkey): Hotkey {
+  const parts: Array<string> = []
+
+  if (parsed.ctrl) parts.push('Control')
+  if (parsed.alt) parts.push('Alt')
+  if (parsed.shift) parts.push('Shift')
+  if (parsed.meta) parts.push('Meta')
+  parts.push(parsed.key)
+
+  return parts.join('+') as Hotkey
+}

package/src/parse.ts

@@ -0,0 +1,368 @@
+import {
+  MODIFIER_ALIASES,
+  MODIFIER_ORDER,
+  detectPlatform,
+  normalizeKeyName,
+  resolveModifier,
+} from './constants'
+import type {
+  CanonicalModifier,
+  Hotkey,
+  Key,
+  ParsedHotkey,
+  RawHotkey,
+} from './hotkey'
+
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
+ * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+export function parseHotkey(
+  hotkey: Hotkey | (string & {}),
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): ParsedHotkey {
+  const parts = hotkey.split('+')
+  const modifiers: Set<CanonicalModifier> = new Set()
+  let key = ''
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!.trim()
+
+    if (i === parts.length - 1) {
+      // Last part is always the key
+      key = normalizeKeyName(part)
+    } else {
+      // All other parts are modifiers
+      const alias =
+        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]
+
+      if (alias) {
+        const resolved = resolveModifier(alias, platform)
+        modifiers.add(resolved)
+      } else {
+        // Unknown modifier, treat as part of the key if it's the only part
+        // or ignore if there are more parts
+        if (parts.length === 1) {
+          key = normalizeKeyName(part)
+        }
+      }
+    }
+  }
+
+  // If no key was found (empty string), use the last part as-is
+  if (!key && parts.length > 0) {
+    key = normalizeKeyName(parts[parts.length - 1]!.trim())
+  }
+
+  return {
+    key,
+    ctrl: modifiers.has('Control'),
+    shift: modifiers.has('Shift'),
+    alt: modifiers.has('Alt'),
+    meta: modifiers.has('Meta'),
+    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),
+  }
+}
+
+/**
+ * Converts a RawHotkey object to a ParsedHotkey.
+ * Optional modifier booleans default to false; modifiers array is derived from them.
+ * When `mod` is true, it is resolved to Control or Meta based on platform.
+ *
+ * @param raw - The raw hotkey object
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns A ParsedHotkey suitable for matching and formatting
+ *
+ * @example
+ * ```ts
+ * rawHotkeyToParsedHotkey({ key: 'Escape' })
+ * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
+ * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
+ * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+export function rawHotkeyToParsedHotkey(
+  raw: RawHotkey,
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): ParsedHotkey {
+  let ctrl = raw.ctrl ?? false
+  const shift = raw.shift ?? false
+  const alt = raw.alt ?? false
+  let meta = raw.meta ?? false
+
+  if (raw.mod) {
+    const resolved = resolveModifier('Mod', platform)
+    if (resolved === 'Control') {
+      ctrl = true
+    } else {
+      meta = true
+    }
+  }
+
+  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {
+    switch (m) {
+      case 'Control':
+        return ctrl
+      case 'Shift':
+        return shift
+      case 'Alt':
+        return alt
+      case 'Meta':
+        return meta
+      default:
+        return false
+    }
+  })
+  return {
+    key: raw.key,
+    ctrl,
+    shift,
+    alt,
+    meta,
+    modifiers,
+  }
+}
+
+/**
+ * Normalizes a hotkey string to its canonical form.
+ *
+ * The canonical form uses:
+ * - Full modifier names (Control, Alt, Shift, Meta)
+ * - Modifiers in order: Control+Alt+Shift+Meta
+ * - Uppercase letters for single-character keys
+ * - Proper casing for special keys (Escape, not escape)
+ *
+ * @param hotkey - The hotkey string to normalize
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns The normalized hotkey string
+ *
+ * @example
+ * ```ts
+ * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
+ * normalizeHotkey('ctrl+a') // 'Control+A'
+ * normalizeHotkey('esc') // 'Escape'
+ * ```
+ */
+export function normalizeHotkey(
+  hotkey: Key | (string & {}),
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): string {
+  const parsed = parseHotkey(hotkey, platform)
+  const parts: Array<string> = []
+
+  // Add modifiers in canonical order
+  for (const modifier of MODIFIER_ORDER) {
+    if (parsed.modifiers.includes(modifier)) {
+      parts.push(modifier)
+    }
+  }
+
+  // Add the key
+  parts.push(parsed.key)
+
+  return parts.join('+')
+}
+
+/**
+ * Checks if a string represents a modifier key.
+ *
+ * @param key - The string to check
+ * @returns True if the string is a recognized modifier
+ */
+export function isModifier(key: string): boolean {
+  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES
+}
+
+/**
+ * Parses a KeyboardEvent into a ParsedHotkey object.
+ *
+ * This function extracts the key and modifier state from a keyboard event
+ * and converts it into the same format used by `parseHotkey()`.
+ *
+ * @param event - The KeyboardEvent to parse
+ * @param platform - The target platform for resolving modifiers (defaults to auto-detection)
+ * @returns A ParsedHotkey object representing the keyboard event
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const parsed = parseKeyboardEvent(event)
+ *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
+ * })
+ * ```
+ */
+export function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {
+  const normalizedKey = normalizeKeyName(event.key)
+
+  // 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')
+
+  return {
+    key: normalizedKey,
+    ctrl: event.ctrlKey,
+    shift: event.shiftKey,
+    alt: event.altKey,
+    meta: event.metaKey,
+    modifiers,
+  }
+}
+
+/**
+ * Converts a KeyboardEvent directly to a hotkey string.
+ *
+ * This is a convenience function that combines `parseKeyboardEvent()` and formatting.
+ * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
+ * and is suitable for use with `useHotkey()` and other hotkey functions.
+ *
+ * @param event - The KeyboardEvent to convert
+ * @param platform - The target platform (defaults to auto-detection)
+ * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const hotkey = keyboardEventToHotkey(event)
+ *   console.log(hotkey) // 'Control+Shift+S'
+ *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
+ * })
+ * ```
+ */
+export function keyboardEventToHotkey(event: KeyboardEvent): Hotkey {
+  const parsed = parseKeyboardEvent(event)
+
+  // Build hotkey string in canonical order (same as formatHotkey)
+  const parts: Array<string> = []
+  for (const modifier of MODIFIER_ORDER) {
+    if (parsed.modifiers.includes(modifier)) {
+      parts.push(modifier)
+    }
+  }
+  parts.push(parsed.key)
+
+  return parts.join('+') as Hotkey
+}
+
+/**
+ * Checks if a KeyboardEvent represents a modifier-only key press.
+ *
+ * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
+ * that don't have an associated character or action key. This is useful
+ * for filtering out modifier key presses when recording shortcuts.
+ *
+ * @param event - The KeyboardEvent to check
+ * @returns True if the event represents a modifier-only key
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   if (isModifierKey(event)) {
+ *     console.log('Modifier key pressed, waiting for action key...')
+ *     return
+ *   }
+ *   // Process non-modifier key
+ * })
+ * ```
+ */
+export function isModifierKey(event: KeyboardEvent): boolean {
+  const key = event.key
+  return (
+    key === 'Control' ||
+    key === 'Shift' ||
+    key === 'Alt' ||
+    key === 'Meta' ||
+    key === 'Command' ||
+    key === 'OS' ||
+    key === 'Win'
+  )
+}
+
+/**
+ * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
+ *
+ * This is useful for validating that a recorded hotkey is complete and not
+ * just a combination of modifiers without an action key.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to check
+ * @param platform - The target platform for parsing (defaults to auto-detection)
+ * @returns True if the hotkey contains at least one non-modifier key
+ *
+ * @example
+ * ```ts
+ * hasNonModifierKey('Control+Shift+S') // true
+ * hasNonModifierKey('Control+Shift') // false (no action key)
+ * hasNonModifierKey(parseHotkey('Mod+A')) // true
+ * ```
+ */
+export function hasNonModifierKey(
+  hotkey: Hotkey | ParsedHotkey | (string & {}),
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): boolean {
+  const parsed =
+    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey
+
+  // Check if the key part is actually a modifier
+  const keyIsModifier = isModifier(parsed.key)
+
+  // A valid hotkey must have a non-modifier key
+  return !keyIsModifier && parsed.key.length > 0
+}
+
+/**
+ * Converts a hotkey string to use 'Mod' format for portability.
+ *
+ * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
+ * This enables cross-platform hotkey definitions that work consistently.
+ *
+ * @param hotkey - The hotkey string to convert
+ * @param platform - The target platform (defaults to auto-detection)
+ * @returns The hotkey string with 'Mod' format applied
+ *
+ * @example
+ * ```ts
+ * convertToModFormat('Meta+S', 'mac') // 'Mod+S'
+ * convertToModFormat('Control+S', 'windows') // 'Mod+S'
+ * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
+ * ```
+ */
+export function convertToModFormat(
+  hotkey: Hotkey | (string & {}),
+  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
+): Hotkey {
+  const parsed = parseHotkey(hotkey, platform)
+
+  // Only convert if we have exactly one primary modifier
+  if (platform === 'mac' && parsed.meta && !parsed.ctrl) {
+    // Convert Meta to Mod on Mac
+    const parts = hotkey.split('+')
+    return parts
+      .map((part) => (part === 'Meta' ? 'Mod' : part))
+      .join('+') as Hotkey
+  } else if (platform !== 'mac' && parsed.ctrl && !parsed.meta) {
+    // Convert Control to Mod on Windows/Linux
+    const parts = hotkey.split('+')
+    return parts
+      .map((part) => (part === 'Control' ? 'Mod' : part))
+      .join('+') as Hotkey
+  }
+
+  // No conversion needed
+  return hotkey as Hotkey
+}