@tanstack/hotkeys 0.8.0 → 0.9.0

package/src/hotkey-manager.ts

@@ -1,24 +1,27 @@
 import { Store } from '@tanstack/store'
-import { detectPlatform, normalizeKeyName } from './constants'
+import { isRecordingEvent } from './_recording-guard'
+import { areHotkeysEqual } from './match'
+import { detectPlatform } from './platform'
+import { normalizeKeyName } from './constants'
 import { formatHotkey } from './format'
 import { parseHotkey, rawHotkeyToParsedHotkey } from './parse'
-import { matchesKeyboardEvent } from './match'
+import { matchKeyboardEvent } from './_match'
 import {
   defaultHotkeyOptions,
   getDefaultIgnoreInputs,
   handleConflict,
-  isEventForTarget,
-  shouldIgnoreInputEvent,
-} from './manager.utils'
-import type { ConflictBehavior } from './manager.utils'
+  optionsEqual,
+} from './_registration'
+import { isEventForTarget, shouldIgnoreInputEvent } from './_event-target'
 import type {
+  ConflictBehavior,
   Hotkey,
   HotkeyCallback,
   HotkeyCallbackContext,
   HotkeyMeta,
   ParsedHotkey,
   RegisterableHotkey,
-} from './hotkey'
+} from './hotkey.types'
 
 export type { ConflictBehavior }
 
@@ -60,6 +63,8 @@ export interface HotkeyRegistration {
   callback: HotkeyCallback
   /** Whether this registration has fired and needs reset (for requireReset) */
   hasFired: boolean
+  /** The concrete key/code that activated a requireReset registration. */
+  activeMatch?: { key: string; code: string }
   /** The original hotkey string */
   hotkey: Hotkey
   /** Unique identifier for this registration */
@@ -378,7 +383,10 @@ export class HotkeyManager {
       setOptions: (newOptions: Partial<HotkeyOptions>) => {
         manager.registrations.setState((prev) => {
           const reg = prev.get(id)
-          if (reg) {
+          if (
+            reg &&
+            !optionsEqual(reg.options, { ...reg.options, ...newOptions })
+          ) {
             const next = new Map(prev)
             next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })
             return next
@@ -476,11 +484,52 @@ export class HotkeyManager {
     target: HTMLElement | Document | Window,
     eventType: 'keydown' | 'keyup',
   ): void {
+    // Releases clear latches even when focus or enabled state now prevents callbacks.
+    if (eventType === 'keyup') {
+      for (const id of this.#targetRegistrations.get(target) ?? []) {
+        const registration = this.registrations.state.get(id)
+        if (
+          registration?.hasFired &&
+          this.#shouldResetRegistration(registration, event)
+        ) {
+          registration.hasFired = false
+          registration.activeMatch = undefined
+        }
+      }
+    }
+    if (isRecordingEvent(event)) return
     const targetRegs = this.#targetRegistrations.get(target)
     if (!targetRegs) {
       return
     }
 
+    const matches = new Map<string, ReturnType<typeof matchKeyboardEvent>>()
+    let bestScore = 0
+
+    // Exact logical/explicit-code matches outrank compatibility fallbacks.
+    for (const id of targetRegs) {
+      const registration = this.registrations.state.get(id)
+      if (
+        !registration ||
+        !registration.options.enabled ||
+        registration.options.eventType !== eventType ||
+        !isEventForTarget(event, target) ||
+        (registration.options.ignoreInputs !== false &&
+          shouldIgnoreInputEvent(event, target, registration.target))
+      ) {
+        continue
+      }
+      const result = matchKeyboardEvent(
+        event,
+        registration.parsedHotkey,
+        registration.options.platform,
+      )
+      if (result.matched) {
+        matches.set(id, result)
+        bestScore = Math.max(bestScore, result.score)
+      }
+    }
+
     for (const id of targetRegs) {
       const registration = this.registrations.state.get(id)
       if (!registration) {
@@ -509,14 +558,9 @@ export class HotkeyManager {
           continue
         }
 
-        // Check if the hotkey matches first
-        const matches = matchesKeyboardEvent(
-          event,
-          registration.parsedHotkey,
-          registration.options.platform,
-        )
+        const match = matches.get(id)
 
-        if (matches) {
+        if (match?.matched && match.score === bestScore) {
           // Always apply preventDefault/stopPropagation if the hotkey matches,
           // even when requireReset is active and has already fired
           if (registration.options.preventDefault) {
@@ -533,6 +577,7 @@ export class HotkeyManager {
             // Mark as fired if requireReset is enabled
             if (registration.options.requireReset) {
               registration.hasFired = true
+              registration.activeMatch = match.identity
             }
           }
         }
@@ -540,23 +585,11 @@ export class HotkeyManager {
       // Handle keyup events
       else {
         if (registration.options.eventType === 'keyup') {
-          if (
-            matchesKeyboardEvent(
-              event,
-              registration.parsedHotkey,
-              registration.options.platform,
-            )
-          ) {
+          const match = matches.get(id)
+          if (match?.matched && match.score === bestScore) {
             this.#executeHotkeyCallback(registration, event)
           }
         }
-
-        // Reset hasFired when any key in the hotkey is released
-        if (registration.options.requireReset && registration.hasFired) {
-          if (this.#shouldResetRegistration(registration, event)) {
-            registration.hasFired = false
-          }
-        }
       }
     }
   }
@@ -620,7 +653,14 @@ export class HotkeyManager {
     target: HTMLElement | Document | Window,
   ): HotkeyRegistration | null {
     for (const registration of this.registrations.state.values()) {
-      if (registration.hotkey === hotkey && registration.target === target) {
+      if (
+        areHotkeysEqual(
+          registration.hotkey,
+          hotkey,
+          registration.options.platform,
+        ) &&
+        registration.target === target
+      ) {
         return registration
       }
     }
@@ -637,17 +677,24 @@ export class HotkeyManager {
     const parsed = registration.parsedHotkey
     const releasedKey = normalizeKeyName(event.key)
 
-    // Reset if the main key is released
-    // Compare case-insensitively for single-letter keys
-    const parsedKeyNormalized =
-      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key
-    const releasedKeyNormalized =
-      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey
-
-    if (releasedKeyNormalized === parsedKeyNormalized) {
+    if (
+      registration.activeMatch?.code &&
+      event.code === registration.activeMatch.code
+    ) {
       return true
     }
 
+    // Compare the release against the identity this binding actually stores.
+    if (parsed.code !== undefined) {
+      if (event.code === parsed.code) return true
+    } else {
+      const parsedKeyNormalized =
+        parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key
+      const releasedKeyNormalized =
+        releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey
+      if (releasedKeyNormalized === parsedKeyNormalized) return true
+    }
+
     // Reset if any required modifier is released
     // Use normalized key names and check against canonical modifier names
     if (parsed.ctrl && releasedKey === 'Control') {
@@ -683,7 +730,9 @@ export class HotkeyManager {
     const syntheticEvent = new KeyboardEvent(
       registration.options.eventType ?? 'keydown',
       {
-        key: parsed.key,
+        ...(parsed.code !== undefined
+          ? { code: parsed.code }
+          : { key: parsed.key }),
         ctrlKey: parsed.ctrl,
         shiftKey: parsed.shift,
         altKey: parsed.alt,
@@ -725,7 +774,13 @@ export class HotkeyManager {
     target?: HTMLElement | Document | Window,
   ): boolean {
     for (const registration of this.registrations.state.values()) {
-      if (registration.hotkey === hotkey) {
+      if (
+        areHotkeysEqual(
+          registration.hotkey,
+          hotkey,
+          registration.options.platform,
+        )
+      ) {
         // If target is specified, both must match
         if (target === undefined || registration.target === target) {
           return true

package/src/hotkey-recorder.ts

@@ -1,8 +1,21 @@
 import { Store } from '@tanstack/store'
-import { detectPlatform } from './constants'
-import { isInputElement } from './manager.utils'
-import { hotkeyChordFromKeydown } from './recorder-chord'
-import type { Hotkey } from './hotkey'
+import { findHotkeyConflicts } from './conflicts'
+import {
+  beginRecording,
+  captureRecordingEvent,
+  endRecording,
+} from './_recording-guard'
+import { chordRejection, hotkeyChordFromKeydown } from './_recorder-chord'
+import { normalizeKeyboardEvent } from './_keyboard-event'
+import { isModifierKey, parseHotkey } from './parse'
+import { validateHotkey } from './validate'
+import { detectPlatform } from './platform'
+import { shouldIgnoreInputEvent } from './_event-target'
+import type {
+  HotkeyRecorderValidationContext,
+  RecorderOptions,
+} from './recorder-options'
+import type { Hotkey } from './hotkey.types'
 
 /**
  * State interface for the HotkeyRecorder.
@@ -17,7 +30,12 @@ export interface HotkeyRecorderState {
 /**
  * Options for configuring a HotkeyRecorder instance.
  */
-export interface HotkeyRecorderOptions {
+export interface HotkeyRecorderOptions extends RecorderOptions {
+  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  validate?: (
+    hotkey: Hotkey,
+    context: HotkeyRecorderValidationContext,
+  ) => boolean | string
   /** Callback when a hotkey is successfully recorded */
   onRecord: (hotkey: Hotkey) => void
   /** Optional callback when recording is cancelled (Escape pressed) */
@@ -116,6 +134,7 @@ export class HotkeyRecorder {
       return
     }
 
+    beginRecording(this)
     // Update store state
     this.store.setState(() => ({
       isRecording: true,
@@ -132,16 +151,19 @@ export class HotkeyRecorder {
       // If ignoreInputs is enabled (default) and focus is in an input element,
       // let the event pass through so the user can type normally.
       // Escape is the exception — it should always cancel recording.
-      if (this.#options.ignoreInputs !== false) {
-        const activeEl =
-          typeof document !== 'undefined' ? document.activeElement : null
-        if (isInputElement(activeEl) && event.key !== 'Escape') {
-          return
-        }
-      }
+      if (
+        this.#options.ignoreInputs !== false &&
+        event.key !== 'Escape' &&
+        shouldIgnoreInputEvent(event, document, document)
+      )
+        return
 
+      const platform = this.#options.platform ?? this.#platform
+      if (normalizeKeyboardEvent(event, platform).isComposing) return
+      captureRecordingEvent(event)
       event.preventDefault()
       event.stopPropagation()
+      if (event.repeat) return
 
       // Handle Escape to cancel
       if (event.key === 'Escape') {
@@ -157,18 +179,70 @@ export class HotkeyRecorder {
           !event.altKey &&
           !event.metaKey
         ) {
-          this.#options.onClear?.()
-          this.#options.onRecord('' as Hotkey)
           this.stop()
+          this.#options.onClear?.()
           return
         }
       }
 
-      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
+      if (isModifierKey(event.key) || event.key === 'AltGraph') return
+      const rejection = chordRejection(event, { ...this.#options, platform })
+      if (rejection) {
+        this.#options.onReject?.(rejection)
+        return
+      }
+      const finalHotkey = hotkeyChordFromKeydown(
+        event,
+        platform,
+        this.#options.recordBy,
+      )
       if (finalHotkey === null) {
         return
       }
 
+      const validation = validateHotkey(finalHotkey)
+      if (!validation.valid) {
+        this.#options.onReject?.({
+          reason: 'invalid',
+          message: validation.errors.join('; '),
+          hotkey: finalHotkey,
+        })
+        return
+      }
+      const accepted = this.#options.validate?.(finalHotkey, {
+        event,
+        parsedHotkey: parseHotkey(finalHotkey, platform),
+      })
+      if (accepted !== undefined && accepted !== true) {
+        this.#options.onReject?.({
+          reason: 'validation',
+          message:
+            typeof accepted === 'string'
+              ? accepted
+              : 'This shortcut is not allowed.',
+          hotkey: finalHotkey,
+        })
+        return
+      }
+      if (this.#options.detectConflicts) {
+        const conflicts = findHotkeyConflicts(finalHotkey, {
+          ...(typeof this.#options.detectConflicts === 'object'
+            ? this.#options.detectConflicts
+            : {}),
+          platform,
+          events: [event],
+        })
+        if (conflicts.length) {
+          this.#options.onReject?.({
+            reason: 'conflict',
+            message: 'This shortcut conflicts with a registered binding.',
+            hotkey: finalHotkey,
+            conflicts,
+          })
+          return
+        }
+      }
+      endRecording(this)
       // Remove listener FIRST to prevent any additional events
       const handlerToRemove = this.#keydownHandler as
         | ((event: KeyboardEvent) => void)
@@ -198,6 +272,7 @@ export class HotkeyRecorder {
    * Removes the event listener and resets the recording state.
    */
   stop(): void {
+    endRecording(this)
     // Remove event listener immediately
     if (this.#keydownHandler) {
       this.#removeListener(this.#keydownHandler)
@@ -218,6 +293,7 @@ export class HotkeyRecorder {
    * the onCancel callback if provided.
    */
   cancel(): void {
+    endRecording(this)
     // Remove event listener immediately
     if (this.#keydownHandler) {
       this.#removeListener(this.#keydownHandler)

package/src/hotkey-sequence-recorder.ts

@@ -1,7 +1,20 @@
 import { Store } from '@tanstack/store'
-import { detectPlatform } from './constants'
-import { isInputElement } from './manager.utils'
-import { hotkeyChordFromKeydown } from './recorder-chord'
+import { findHotkeyConflicts } from './conflicts'
+import {
+  beginRecording,
+  captureRecordingEvent,
+  endRecording,
+} from './_recording-guard'
+import { chordRejection, hotkeyChordFromKeydown } from './_recorder-chord'
+import { normalizeKeyboardEvent } from './_keyboard-event'
+import { isModifierKey, parseHotkey } from './parse'
+import { validateHotkey } from './validate'
+import { detectPlatform } from './platform'
+import { shouldIgnoreInputEvent } from './_event-target'
+import type {
+  HotkeySequenceRecorderValidationContext,
+  RecorderOptions,
+} from './recorder-options'
 import type { HotkeySequence } from './sequence-manager'
 
 /**
@@ -26,8 +39,13 @@ export interface HotkeySequenceRecorderState {
 /**
  * Options for configuring a HotkeySequenceRecorder instance.
  */
-export interface HotkeySequenceRecorderOptions {
-  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+export interface HotkeySequenceRecorderOptions extends RecorderOptions {
+  /** Validate the completed sequence. Rejection preserves the steps for editing. */
+  validate?: (
+    sequence: HotkeySequence,
+    context: HotkeySequenceRecorderValidationContext,
+  ) => boolean | string
+  /** Callback when a sequence is successfully recorded */
   onRecord: (sequence: HotkeySequence) => void
   /** Optional callback when recording is cancelled (Escape pressed) */
   onCancel?: () => void
@@ -66,6 +84,7 @@ const defaultHotkeySequenceRecorderOptions: Pick<
   commitKeys: 'enter',
 }
 
+/** Resolves the Enter policy, with commitKeys: none overriding the legacy boolean. */
 function resolvedCommitOnEnter(
   options: HotkeySequenceRecorderOptions,
 ): boolean {
@@ -93,6 +112,7 @@ export class HotkeySequenceRecorder {
   #keydownHandler: ((event: KeyboardEvent) => void) | null = null
   #options: HotkeySequenceRecorderOptions
   #platform: 'mac' | 'windows' | 'linux'
+  #events: Array<KeyboardEvent> = []
   #idleTimer: ReturnType<typeof setTimeout> | null = null
 
   constructor(options: HotkeySequenceRecorderOptions) {
@@ -103,6 +123,7 @@ export class HotkeySequenceRecorder {
     this.#platform = detectPlatform()
   }
 
+  /** Merges current callbacks and options without discarding recorded steps. */
   setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {
     this.#options = {
       ...defaultHotkeySequenceRecorderOptions,
@@ -111,6 +132,7 @@ export class HotkeySequenceRecorder {
     }
   }
 
+  /** Cancels a pending idle commit so it cannot fire after editing or stopping. */
   #clearIdleTimer(): void {
     if (this.#idleTimer !== null) {
       clearTimeout(this.#idleTimer)
@@ -118,6 +140,7 @@ export class HotkeySequenceRecorder {
     }
   }
 
+  /** Restarts optional idle commit after a step is recorded or edited. */
   #scheduleIdleTimer(): void {
     this.#clearIdleTimer()
     const ms = this.#options.idleTimeoutMs
@@ -139,6 +162,7 @@ export class HotkeySequenceRecorder {
     }, ms)
   }
 
+  /** Publishes edited steps while preserving the remaining recorder state. */
   #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {
     this.store.setState((s) => ({
       ...s,
@@ -146,12 +170,15 @@ export class HotkeySequenceRecorder {
     }))
   }
 
+  /** Starts a fresh recording; repeated starts during an active session are ignored. */
   start(): void {
     if (this.#keydownHandler) {
       return
     }
 
     this.#clearIdleTimer()
+    this.#events = []
+    beginRecording(this)
     this.store.setState(() => ({
       isRecording: true,
       steps: [],
@@ -166,16 +193,19 @@ export class HotkeySequenceRecorder {
       // If ignoreInputs is enabled (default) and focus is in an input element,
       // let the event pass through so the user can type normally.
       // Escape is the exception — it should always cancel recording.
-      if (this.#options.ignoreInputs !== false) {
-        const activeEl =
-          typeof document !== 'undefined' ? document.activeElement : null
-        if (isInputElement(activeEl) && event.key !== 'Escape') {
-          return
-        }
-      }
+      if (
+        this.#options.ignoreInputs !== false &&
+        event.key !== 'Escape' &&
+        shouldIgnoreInputEvent(event, document, document)
+      )
+        return
 
+      const platform = this.#options.platform ?? this.#platform
+      if (normalizeKeyboardEvent(event, platform).isComposing) return
+      captureRecordingEvent(event)
       event.preventDefault()
       event.stopPropagation()
+      if (event.repeat) return
 
       if (event.key === 'Escape') {
         this.cancel()
@@ -191,11 +221,11 @@ export class HotkeySequenceRecorder {
         ) {
           const steps = this.store.state.steps
           if (steps.length === 0) {
+            this.stop()
             this.#options.onClear?.()
-            this.#options.onRecord([])
-            this.#finishWithoutCommitCallback()
             return
           }
+          this.#events.pop()
           this.#patchSteps((prev) => prev.slice(0, -1))
           const next = this.store.state.steps
           if (next.length === 0) {
@@ -224,11 +254,31 @@ export class HotkeySequenceRecorder {
         return
       }
 
-      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)
+      if (isModifierKey(event.key) || event.key === 'AltGraph') return
+      const rejection = chordRejection(event, { ...this.#options, platform })
+      if (rejection) {
+        this.#options.onReject?.(rejection)
+        return
+      }
+      const finalHotkey = hotkeyChordFromKeydown(
+        event,
+        platform,
+        this.#options.recordBy,
+      )
       if (finalHotkey === null) {
         return
       }
 
+      const validation = validateHotkey(finalHotkey)
+      if (!validation.valid) {
+        this.#options.onReject?.({
+          reason: 'invalid',
+          message: validation.errors.join('; '),
+          hotkey: finalHotkey,
+        })
+        return
+      }
+      this.#events.push(event)
       this.#patchSteps((prev) => [...prev, finalHotkey])
       this.#scheduleIdleTimer()
     }
@@ -247,6 +297,43 @@ export class HotkeySequenceRecorder {
     }
 
     const sequence = [...steps]
+    const platform = this.#options.platform ?? this.#platform
+    this.#clearIdleTimer()
+    const accepted = this.#options.validate?.(sequence, {
+      events: [...this.#events],
+      parsedSequence: sequence.map((step) => parseHotkey(step, platform)),
+    })
+    if (accepted !== undefined && accepted !== true) {
+      this.#options.onReject?.({
+        reason: 'validation',
+        message:
+          typeof accepted === 'string'
+            ? accepted
+            : 'This sequence is not allowed.',
+        sequence,
+      })
+      return
+    }
+    if (this.#options.detectConflicts) {
+      const conflicts = findHotkeyConflicts(sequence, {
+        ...(typeof this.#options.detectConflicts === 'object'
+          ? this.#options.detectConflicts
+          : {}),
+        platform,
+        events: this.#events,
+      })
+      if (conflicts.length) {
+        this.#options.onReject?.({
+          reason: 'conflict',
+          message: 'This sequence conflicts with a registered binding.',
+          sequence,
+          conflicts,
+        })
+        return
+      }
+    }
+    endRecording(this)
+    this.#events = []
 
     if (this.#keydownHandler) {
       this.#removeListener(this.#keydownHandler)
@@ -263,20 +350,10 @@ export class HotkeySequenceRecorder {
     this.#options.onRecord(sequence)
   }
 
-  #finishWithoutCommitCallback(): void {
-    if (this.#keydownHandler) {
-      this.#removeListener(this.#keydownHandler)
-      this.#keydownHandler = null
-    }
-    this.#clearIdleTimer()
-    this.store.setState(() => ({
-      isRecording: false,
-      steps: [],
-      recordedSequence: null,
-    }))
-  }
-
+  /** Stops and discards in-progress steps without invoking onCancel. */
   stop(): void {
+    endRecording(this)
+    this.#events = []
     if (this.#keydownHandler) {
       this.#removeListener(this.#keydownHandler)
       this.#keydownHandler = null
@@ -289,7 +366,10 @@ export class HotkeySequenceRecorder {
     }))
   }
 
+  /** Stops, discards in-progress steps, and notifies onCancel. */
   cancel(): void {
+    endRecording(this)
+    this.#events = []
     if (this.#keydownHandler) {
       this.#removeListener(this.#keydownHandler)
       this.#keydownHandler = null
@@ -303,6 +383,7 @@ export class HotkeySequenceRecorder {
     this.#options.onCancel?.()
   }
 
+  /** Captures keydowns before application handlers, with an SSR-safe document check. */
   #addListener(handler: (event: KeyboardEvent) => void): void {
     if (typeof document === 'undefined') {
       return
@@ -310,6 +391,7 @@ export class HotkeySequenceRecorder {
     document.addEventListener('keydown', handler, true)
   }
 
+  /** Detaches the capture listener when recording ends. */
   #removeListener(handler: (event: KeyboardEvent) => void): void {
     if (typeof document === 'undefined') {
       return