@tanstack/hotkeys 0.8.0 → 0.9.0

package/src/recorder-options.ts

@@ -0,0 +1,34 @@
+import type { Hotkey, ParsedHotkey } from './hotkey.types'
+import type { HotkeyConflict, HotkeyConflictOptions } from './conflicts'
+
+/** Event property used to record a binding. Physical codes are the default. */
+export type RecorderKeyMode = 'code' | 'key'
+
+export interface RecorderRejection {
+  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation'
+  message: string
+  hotkey?: Hotkey
+  sequence?: Array<Hotkey>
+  conflicts?: Array<HotkeyConflict>
+}
+
+export interface RecorderOptions {
+  /** Physical code recording is the default. Choose key to record logical characters. */
+  recordBy?: RecorderKeyMode
+  /** Platform used for Mod and AltGraph handling. Defaults to platform detection. */
+  platform?: 'mac' | 'windows' | 'linux'
+  /** Opt in to live-registry conflicts, including sequence prefixes. Default: false. */
+  detectConflicts?: boolean | HotkeyConflictOptions
+  /** Rejected candidates leave recording active. */
+  onReject?: (rejection: RecorderRejection) => void
+}
+
+export interface HotkeyRecorderValidationContext {
+  event: KeyboardEvent
+  parsedHotkey: ParsedHotkey
+}
+
+export interface HotkeySequenceRecorderValidationContext {
+  events: ReadonlyArray<KeyboardEvent>
+  parsedSequence: ReadonlyArray<ParsedHotkey>
+}

package/src/sequence-manager.ts

@@ -1,24 +1,28 @@
 import { Store } from '@tanstack/store'
+import { isRecordingEvent } from './_recording-guard'
 import { formatHotkeySequence } from './format'
-import { detectPlatform, normalizeKeyName } from './constants'
+import { detectPlatform } from './platform'
+import { normalizeKeyName } from './constants'
 import { isModifierKey, parseHotkey } from './parse'
-import { matchesKeyboardEvent } from './match'
+import { areHotkeysEqual, matchesKeyboardEvent } from './match'
+import { matchKeyboardEvent } from './_match'
+import { normalizeKeyboardEvent } from './_keyboard-event'
 import {
   defaultHotkeyOptions,
   getDefaultIgnoreInputs,
   handleConflict,
-  isEventForTarget,
-  shouldIgnoreInputEvent,
-} from './manager.utils'
+  optionsEqual,
+} from './_registration'
+import { isEventForTarget, shouldIgnoreInputEvent } from './_event-target'
 import type { HotkeyOptions } from './hotkey-manager'
 import type {
   Hotkey,
   HotkeyCallback,
   HotkeyCallbackContext,
   ParsedHotkey,
-} from './hotkey'
+} from './hotkey.types'
 
-type Target = HTMLElement | Document | Window
+export type Target = HTMLElement | Document | Window
 
 /**
  * Options for hotkey sequence matching.
@@ -35,7 +39,7 @@ export interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
  * Each element is one step (a `Hotkey` string). Steps may include modifiers;
  * the same modifier can appear on consecutive steps (e.g. `Shift+R` then
  * `Shift+T`). Modifier-only key events do not advance or reset matching—see
- * `SequenceManager`.
+ * `SequenceManager`. Automatic keydown repeats and IME composition are also ignored.
  *
  * @example
  * ```ts
@@ -62,13 +66,6 @@ function generateSequenceId(): string {
   return `sequence_${++sequenceIdCounter}`
 }
 
-/**
- * Returns a canonical string for sequence conflict comparison.
- */
-function sequenceKey(sequence: HotkeySequence): string {
-  return sequence.join('|')
-}
-
 /**
  * View of a sequence registration for devtools display.
  * Progress fields reflect an in-progress match (between first key and completion or timeout).
@@ -90,7 +87,7 @@ export interface SequenceRegistrationView {
 /**
  * Internal representation of a sequence registration.
  */
-interface SequenceRegistration {
+export interface SequenceRegistration {
   id: string
   sequence: HotkeySequence
   parsedSequence: Array<ParsedHotkey>
@@ -253,7 +250,7 @@ export class SequenceManager {
 
     // Check for existing registrations with the same sequence and target
     const conflictingRegistration = this.#findConflictingSequence(
-      sequence,
+      parsedSequence,
       target,
     )
 
@@ -325,7 +322,10 @@ export class SequenceManager {
       },
       setOptions: (newOptions: Partial<SequenceOptions>) => {
         const reg = manager.#registrations.get(id)
-        if (reg) {
+        if (
+          reg &&
+          !optionsEqual(reg.options, { ...reg.options, ...newOptions })
+        ) {
           reg.options = { ...reg.options, ...newOptions }
           manager.registrations.setState((prev) =>
             new Map(prev).set(id, toRegistrationView(reg)),
@@ -438,6 +438,22 @@ export class SequenceManager {
     target: Target,
     eventType: 'keydown' | 'keyup',
   ): void {
+    if (isRecordingEvent(event)) {
+      for (const id of this.#targetRegistrations.get(target) ?? []) {
+        const registration = this.#registrations.get(id)
+        if (registration && registration.currentIndex > 0) {
+          registration.currentIndex = 0
+          this.#syncRegistrationView(registration)
+        }
+      }
+      return
+    }
+    if (
+      (event.type === 'keydown' && event.repeat) ||
+      normalizeKeyboardEvent(event).isComposing
+    ) {
+      return
+    }
     // Skip modifier-only events so pressing e.g. Shift before Shift+C does not reset the sequence.
     if (isModifierKey(normalizeKeyName(event.key))) {
       return
@@ -449,6 +465,9 @@ export class SequenceManager {
     }
 
     const now = Date.now()
+    // Score eligible next steps (or restarts) before advancing any sequence.
+    const candidates = new Map<string, { score: number; nextIndex: number }>()
+    let bestScore = 0
 
     registrationIds: for (const id of targetRegs) {
       const registration = this.#registrations.get(id)
@@ -493,15 +512,30 @@ export class SequenceManager {
         continue
       }
 
-      if (
-        matchesKeyboardEvent(
+      let match = matchKeyboardEvent(
+        event,
+        expectedHotkey,
+        registration.options.platform,
+      )
+      let nextIndex = registration.currentIndex + 1
+      if (!match.matched && registration.currentIndex > 0) {
+        match = matchKeyboardEvent(
           event,
-          expectedHotkey,
+          registration.parsedSequence[0]!,
           registration.options.platform,
         )
-      ) {
+        nextIndex = 1
+      }
+      candidates.set(id, { score: match.score, nextIndex })
+      bestScore = Math.max(bestScore, match.score)
+    }
+
+    for (const [id, candidate] of candidates) {
+      const registration = this.#registrations.get(id)
+      if (!registration || !registration.options.enabled) continue
+      if (candidate.score > 0 && candidate.score === bestScore) {
         registration.lastKeyTime = now
-        registration.currentIndex++
+        registration.currentIndex = candidate.nextIndex
 
         if (registration.currentIndex >= registration.parsedSequence.length) {
           if (registration.options.preventDefault) {
@@ -530,36 +564,27 @@ export class SequenceManager {
           this.#syncRegistrationView(registration)
         }
       } else if (registration.currentIndex > 0) {
-        const firstHotkey = registration.parsedSequence[0]!
-        if (
-          matchesKeyboardEvent(
-            event,
-            firstHotkey,
-            registration.options.platform,
-          )
-        ) {
-          registration.currentIndex = 1
-          registration.lastKeyTime = now
-        } else {
-          registration.currentIndex = 0
-        }
+        // A mismatched or weaker candidate cannot carry stale progress forward.
+        registration.currentIndex = 0
         this.#syncRegistrationView(registration)
       }
     }
   }
 
   /**
-   * Finds an existing registration with the same sequence and target.
+   * Compares resolved step identities without changing the supplied sequence strings.
    */
   #findConflictingSequence(
-    sequence: HotkeySequence,
+    parsedSequence: Array<ParsedHotkey>,
     target: Target,
   ): SequenceRegistration | null {
-    const key = sequenceKey(sequence)
     for (const registration of this.#registrations.values()) {
       if (
-        sequenceKey(registration.sequence) === key &&
-        registration.target === target
+        registration.target === target &&
+        registration.parsedSequence.length === parsedSequence.length &&
+        parsedSequence.every((step, index) =>
+          areHotkeysEqual(step, registration.parsedSequence[index]!),
+        )
       ) {
         return registration
       }
@@ -600,7 +625,9 @@ export class SequenceManager {
     const syntheticEvent = new KeyboardEvent(
       registration.options.eventType ?? 'keydown',
       {
-        key: lastParsed.key,
+        ...(lastParsed.code !== undefined
+          ? { code: lastParsed.code }
+          : { key: lastParsed.key }),
         ctrlKey: lastParsed.ctrl,
         shiftKey: lastParsed.shift,
         altKey: lastParsed.alt,
@@ -691,6 +718,14 @@ export function createSequenceMatcher(
 
   return {
     match(event: KeyboardEvent): boolean {
+      // These events are not sequence steps and must not refresh the timeout.
+      if (
+        (event.type === 'keydown' && event.repeat) ||
+        normalizeKeyboardEvent(event, platform).isComposing ||
+        isModifierKey(normalizeKeyName(event.key))
+      ) {
+        return false
+      }
       const now = Date.now()
 
       if (currentIndex > 0 && now - lastKeyTime > timeout) {

package/src/validate.ts

@@ -1,5 +1,6 @@
-import { ALL_KEYS, MODIFIER_ALIASES } from './constants'
-import type { Hotkey, ValidationResult } from './hotkey'
+import { ALL_KEYS, MODIFIER_ALIASES, normalizeKeyName } from './constants'
+import { splitHotkeyParts } from './_keyboard-event'
+import type { Hotkey } from './hotkey.types'
 
 /**
  * Validates a hotkey string and returns any warnings or errors.
@@ -36,7 +37,7 @@ export function validateHotkey(
     }
   }
 
-  const parts = hotkey.split('+').map((p) => p.trim())
+  const parts = splitHotkeyParts(hotkey).map((p) => p.trim())
 
   // Must have at least one part (the key)
   if (parts.length === 0 || parts.some((p) => p === '')) {
@@ -60,8 +61,18 @@ export function validateHotkey(
     }
   }
 
+  if (
+    keyPart.length > 1 &&
+    (keyPart.startsWith('[') || keyPart.endsWith(']')) &&
+    !/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(keyPart)
+  ) {
+    errors.push(
+      'Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]',
+    )
+  }
+
   // Check if key is known
-  const normalizedKey = normalizeKeyForValidation(keyPart)
+  const normalizedKey = normalizeKeyName(keyPart)
   if (!isKnownKey(normalizedKey) && !isKnownKey(keyPart)) {
     warnings.push(
       `Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`,
@@ -75,27 +86,12 @@ export function validateHotkey(
   }
 }
 
-/**
- * Normalizes a key for validation checking.
- */
-function normalizeKeyForValidation(key: string): string {
-  // Single letter to uppercase
-  if (key.length === 1 && /^[a-zA-Z]$/.test(key)) {
-    return key.toUpperCase()
-  }
-
-  // Function keys to uppercase
-  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: string): boolean {
+  if (/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(key)) return true
+  if (Array.from(key).length === 1) return true
   // Check direct match
   if (ALL_KEYS.has(key as any)) {
     return true
@@ -169,3 +165,15 @@ export function checkHotkey(hotkey: Hotkey | (string & {})): boolean {
 
   return result.valid
 }
+
+/**
+ * Result of validating a hotkey string.
+ */
+export interface ValidationResult {
+  /** Whether the hotkey is valid (can still have warnings) */
+  valid: boolean
+  /** Warning messages about potential issues */
+  warnings: Array<string>
+  /** Error messages about invalid syntax */
+  errors: Array<string>
+}

package/dist/manager.utils.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"manager.utils.cjs","names":[],"sources":["../src/manager.utils.ts"],"sourcesContent":["import type { ParsedHotkey } from './hotkey'\n\n/**\n * Behavior when registering a hotkey/sequence that conflicts with an existing registration.\n *\n * - `'warn'` - Log a warning to the console but allow both registrations (default)\n * - `'error'` - Throw an error and prevent the new registration\n * - `'replace'` - Unregister the existing registration and register the new one\n * - `'allow'` - Allow multiple registrations without warning\n */\nexport type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow'\n\n/**\n * Default options for hotkey/sequence registration.\n * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).\n */\nexport const defaultHotkeyOptions = {\n  preventDefault: true,\n  stopPropagation: true,\n  eventType: 'keydown' as const,\n  enabled: true,\n  ignoreInputs: true,\n  conflictBehavior: 'warn' as ConflictBehavior,\n}\n\n/**\n * Computes the default ignoreInputs value based on the hotkey.\n * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.\n */\nexport function getDefaultIgnoreInputs(parsedHotkey: ParsedHotkey): boolean {\n  if (parsedHotkey.ctrl || parsedHotkey.meta) return false // Mod+S, Ctrl+C, etc.\n  if (parsedHotkey.key === 'Escape') return false // Close modal, etc.\n  return true // Single keys, Shift+key, Alt+key\n}\n\n/**\n * Checks if an element is an input-like element that should be ignored for hotkeys.\n *\n * This includes:\n * - HTMLInputElement (all input types except button, submit, reset)\n * - HTMLTextAreaElement\n * - HTMLSelectElement\n * - Elements with contentEditable enabled\n *\n * Button-type inputs (button, submit, reset) are excluded so hotkeys like\n * Mod+S and Escape fire when the user has tabbed to a form button.\n */\nexport function isInputElement(element: EventTarget | null): boolean {\n  if (!element) {\n    return false\n  }\n\n  if (element instanceof HTMLInputElement) {\n    const type = element.type.toLowerCase()\n    if (type === 'button' || type === 'submit' || type === 'reset') {\n      return false\n    }\n    return true\n  }\n\n  if (\n    element instanceof HTMLTextAreaElement ||\n    element instanceof HTMLSelectElement\n  ) {\n    return true\n  }\n\n  // Check for contenteditable elements (includes \"true\", \"\", \"plaintext-only\",\n  // and inherited contenteditable from ancestor elements)\n  if (element instanceof HTMLElement && element.isContentEditable) {\n    return true\n  }\n\n  return false\n}\n\n/**\n * Returns the focused element for the document associated with where hotkey\n * listeners are attached (listener root). Use this instead of the global\n * `document.activeElement` so registrations scoped to an iframe (or another\n * document) read focus from the correct tree.\n */\nexport function getActiveElementForListenerTarget(\n  target: HTMLElement | Document | Window,\n): Element | null {\n  if (typeof document === 'undefined') {\n    return null\n  }\n\n  // Document first (nodeType covers environments where `document instanceof Document` is false)\n  if (\n    (typeof Document !== 'undefined' && target instanceof Document) ||\n    (typeof Node !== 'undefined' &&\n      (target as Node).nodeType === Node.DOCUMENT_NODE)\n  ) {\n    return (target as Document).activeElement\n  }\n\n  if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {\n    return target.ownerDocument.activeElement ?? null\n  }\n\n  // Window (global or iframe): avoid relying on `instanceof Window` alone (test DOM quirks)\n  return (target as Window).document.activeElement ?? null\n}\n\n/**\n * Returns whether an event should be ignored because it originated from an\n * input-like element other than the registration target.\n *\n * This checks:\n * - the currently focused element for the listener target\n * - the event's composed path (for shadow DOM)\n * - the event target as a final fallback\n */\nexport function shouldIgnoreInputEvent(\n  event: KeyboardEvent,\n  listenerTarget: HTMLElement | Document | Window,\n  registrationTarget: HTMLElement | Document | Window,\n): boolean {\n  const focused = getActiveElementForListenerTarget(listenerTarget)\n  if (focused && isInputElement(focused) && focused !== registrationTarget) {\n    return true\n  }\n\n  if (\n    event\n      .composedPath()\n      .some(\n        (element) => isInputElement(element) && element !== registrationTarget,\n      )\n  ) {\n    return true\n  }\n\n  return isInputElement(event.target) && event.target !== registrationTarget\n}\n\n/**\n * Checks if an event is for the given target (originated from or bubbled to it).\n *\n * For document/window targets, also accepts document.documentElement as currentTarget\n * to handle Brave and other browsers where currentTarget may be documentElement\n * instead of document when listeners are attached to document.\n */\nexport function isEventForTarget(\n  event: KeyboardEvent,\n  target: HTMLElement | Document | Window,\n): boolean {\n  // For Document and Window, verify that our handler was indeed called for this target.\n  //\n  // Browser compatibility note:\n  // Per the DOM spec, event.currentTarget should equal the element the listener was\n  // attached to. However, some Chromium-based browsers (notably Brave) exhibit\n  // non-standard behavior where event.currentTarget is set to document.documentElement\n  // (<html>) instead of document when a listener is attached to document.\n  // This may be related to privacy/fingerprinting protections.\n  //\n  // To ensure cross-browser compatibility, we accept both the expected target\n  // and document.documentElement as valid currentTarget values.\n  // See: https://dom.spec.whatwg.org/#dom-event-currenttarget\n  if (target === document || target === window) {\n    return (\n      event.currentTarget === target ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For Window, accept window, document, or document.documentElement (browser quirks)\n  if (target === window) {\n    return (\n      event.currentTarget === window ||\n      event.currentTarget === document ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For HTMLElement, check if event originated from or bubbled to the element\n  if (target instanceof HTMLElement) {\n    // Check if the event's currentTarget is the target (capturing/bubbling)\n    if (event.currentTarget === target) {\n      return true\n    }\n\n    // Check if the event's target is a descendant of our target\n    if (event.target instanceof Node && target.contains(event.target)) {\n      return true\n    }\n  }\n\n  return false\n}\n\n/**\n * Handles conflicts between registrations based on conflict behavior.\n *\n * @param conflictingId - The ID of the conflicting registration\n * @param keyDisplay - Display string for the conflicting key/sequence (for error messages)\n * @param conflictBehavior - How to handle the conflict\n * @param unregister - Function to unregister by ID\n */\nexport function handleConflict(\n  conflictingId: string,\n  keyDisplay: string,\n  conflictBehavior: ConflictBehavior,\n  unregister: (id: string) => void,\n): void {\n  if (conflictBehavior === 'allow') {\n    return\n  }\n\n  if (conflictBehavior === 'warn') {\n    console.warn(\n      `'${keyDisplay}' is already registered. Multiple handlers will be triggered. ` +\n        `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n        `or conflictBehavior: 'allow' to suppress this warning.`,\n    )\n    return\n  }\n\n  if (conflictBehavior === 'error') {\n    throw new Error(\n      `'${keyDisplay}' is already registered. ` +\n        `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n        `or conflictBehavior: 'allow' to allow multiple registrations.`,\n    )\n  }\n\n  // At this point, conflictBehavior must be 'replace'\n  unregister(conflictingId)\n}\n"],"mappings":";;;;;;AAgBA,MAAa,uBAAuB;CAClC,gBAAgB;CAChB,iBAAiB;CACjB,WAAW;CACX,SAAS;CACT,cAAc;CACd,kBAAkB;CACnB;;;;;AAMD,SAAgB,uBAAuB,cAAqC;AAC1E,KAAI,aAAa,QAAQ,aAAa,KAAM,QAAO;AACnD,KAAI,aAAa,QAAQ,SAAU,QAAO;AAC1C,QAAO;;;;;;;;;;;;;;AAeT,SAAgB,eAAe,SAAsC;AACnE,KAAI,CAAC,QACH,QAAO;AAGT,KAAI,mBAAmB,kBAAkB;EACvC,MAAM,OAAO,QAAQ,KAAK,aAAa;AACvC,MAAI,SAAS,YAAY,SAAS,YAAY,SAAS,QACrD,QAAO;AAET,SAAO;;AAGT,KACE,mBAAmB,uBACnB,mBAAmB,kBAEnB,QAAO;AAKT,KAAI,mBAAmB,eAAe,QAAQ,kBAC5C,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,kCACd,QACgB;AAChB,KAAI,OAAO,aAAa,YACtB,QAAO;AAIT,KACG,OAAO,aAAa,eAAe,kBAAkB,YACrD,OAAO,SAAS,eACd,OAAgB,aAAa,KAAK,cAErC,QAAQ,OAAoB;AAG9B,KAAI,OAAO,gBAAgB,eAAe,kBAAkB,YAC1D,QAAO,OAAO,cAAc,iBAAiB;AAI/C,QAAQ,OAAkB,SAAS,iBAAiB;;;;;;;;;;;AAYtD,SAAgB,uBACd,OACA,gBACA,oBACS;CACT,MAAM,UAAU,kCAAkC,eAAe;AACjE,KAAI,WAAW,eAAe,QAAQ,IAAI,YAAY,mBACpD,QAAO;AAGT,KACE,MACG,cAAc,CACd,MACE,YAAY,eAAe,QAAQ,IAAI,YAAY,mBACrD,CAEH,QAAO;AAGT,QAAO,eAAe,MAAM,OAAO,IAAI,MAAM,WAAW;;;;;;;;;AAU1D,SAAgB,iBACd,OACA,QACS;AAaT,KAAI,WAAW,YAAY,WAAW,OACpC,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,WAAW,OACb,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,YACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,kBAAkB,aAAa;AAEjC,MAAI,MAAM,kBAAkB,OAC1B,QAAO;AAIT,MAAI,MAAM,kBAAkB,QAAQ,OAAO,SAAS,MAAM,OAAO,CAC/D,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,SAAgB,eACd,eACA,YACA,kBACA,YACM;AACN,KAAI,qBAAqB,QACvB;AAGF,KAAI,qBAAqB,QAAQ;AAC/B,UAAQ,KACN,IAAI,WAAW,uLAGhB;AACD;;AAGF,KAAI,qBAAqB,QACvB,OAAM,IAAI,MACR,IAAI,WAAW,yJAGhB;AAIH,YAAW,cAAc"}

package/dist/manager.utils.d.cts

@@ -1,13 +0,0 @@
-//#region src/manager.utils.d.ts
-/**
- * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
- *
- * - `'warn'` - Log a warning to the console but allow both registrations (default)
- * - `'error'` - Throw an error and prevent the new registration
- * - `'replace'` - Unregister the existing registration and register the new one
- * - `'allow'` - Allow multiple registrations without warning
- */
-type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
-//#endregion
-export { ConflictBehavior };
-//# sourceMappingURL=manager.utils.d.cts.map

package/dist/manager.utils.d.ts

@@ -1,13 +0,0 @@
-//#region src/manager.utils.d.ts
-/**
- * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
- *
- * - `'warn'` - Log a warning to the console but allow both registrations (default)
- * - `'error'` - Throw an error and prevent the new registration
- * - `'replace'` - Unregister the existing registration and register the new one
- * - `'allow'` - Allow multiple registrations without warning
- */
-type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
-//#endregion
-export { ConflictBehavior };
-//# sourceMappingURL=manager.utils.d.ts.map

package/dist/manager.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"manager.utils.js","names":[],"sources":["../src/manager.utils.ts"],"sourcesContent":["import type { ParsedHotkey } from './hotkey'\n\n/**\n * Behavior when registering a hotkey/sequence that conflicts with an existing registration.\n *\n * - `'warn'` - Log a warning to the console but allow both registrations (default)\n * - `'error'` - Throw an error and prevent the new registration\n * - `'replace'` - Unregister the existing registration and register the new one\n * - `'allow'` - Allow multiple registrations without warning\n */\nexport type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow'\n\n/**\n * Default options for hotkey/sequence registration.\n * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).\n */\nexport const defaultHotkeyOptions = {\n  preventDefault: true,\n  stopPropagation: true,\n  eventType: 'keydown' as const,\n  enabled: true,\n  ignoreInputs: true,\n  conflictBehavior: 'warn' as ConflictBehavior,\n}\n\n/**\n * Computes the default ignoreInputs value based on the hotkey.\n * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.\n */\nexport function getDefaultIgnoreInputs(parsedHotkey: ParsedHotkey): boolean {\n  if (parsedHotkey.ctrl || parsedHotkey.meta) return false // Mod+S, Ctrl+C, etc.\n  if (parsedHotkey.key === 'Escape') return false // Close modal, etc.\n  return true // Single keys, Shift+key, Alt+key\n}\n\n/**\n * Checks if an element is an input-like element that should be ignored for hotkeys.\n *\n * This includes:\n * - HTMLInputElement (all input types except button, submit, reset)\n * - HTMLTextAreaElement\n * - HTMLSelectElement\n * - Elements with contentEditable enabled\n *\n * Button-type inputs (button, submit, reset) are excluded so hotkeys like\n * Mod+S and Escape fire when the user has tabbed to a form button.\n */\nexport function isInputElement(element: EventTarget | null): boolean {\n  if (!element) {\n    return false\n  }\n\n  if (element instanceof HTMLInputElement) {\n    const type = element.type.toLowerCase()\n    if (type === 'button' || type === 'submit' || type === 'reset') {\n      return false\n    }\n    return true\n  }\n\n  if (\n    element instanceof HTMLTextAreaElement ||\n    element instanceof HTMLSelectElement\n  ) {\n    return true\n  }\n\n  // Check for contenteditable elements (includes \"true\", \"\", \"plaintext-only\",\n  // and inherited contenteditable from ancestor elements)\n  if (element instanceof HTMLElement && element.isContentEditable) {\n    return true\n  }\n\n  return false\n}\n\n/**\n * Returns the focused element for the document associated with where hotkey\n * listeners are attached (listener root). Use this instead of the global\n * `document.activeElement` so registrations scoped to an iframe (or another\n * document) read focus from the correct tree.\n */\nexport function getActiveElementForListenerTarget(\n  target: HTMLElement | Document | Window,\n): Element | null {\n  if (typeof document === 'undefined') {\n    return null\n  }\n\n  // Document first (nodeType covers environments where `document instanceof Document` is false)\n  if (\n    (typeof Document !== 'undefined' && target instanceof Document) ||\n    (typeof Node !== 'undefined' &&\n      (target as Node).nodeType === Node.DOCUMENT_NODE)\n  ) {\n    return (target as Document).activeElement\n  }\n\n  if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {\n    return target.ownerDocument.activeElement ?? null\n  }\n\n  // Window (global or iframe): avoid relying on `instanceof Window` alone (test DOM quirks)\n  return (target as Window).document.activeElement ?? null\n}\n\n/**\n * Returns whether an event should be ignored because it originated from an\n * input-like element other than the registration target.\n *\n * This checks:\n * - the currently focused element for the listener target\n * - the event's composed path (for shadow DOM)\n * - the event target as a final fallback\n */\nexport function shouldIgnoreInputEvent(\n  event: KeyboardEvent,\n  listenerTarget: HTMLElement | Document | Window,\n  registrationTarget: HTMLElement | Document | Window,\n): boolean {\n  const focused = getActiveElementForListenerTarget(listenerTarget)\n  if (focused && isInputElement(focused) && focused !== registrationTarget) {\n    return true\n  }\n\n  if (\n    event\n      .composedPath()\n      .some(\n        (element) => isInputElement(element) && element !== registrationTarget,\n      )\n  ) {\n    return true\n  }\n\n  return isInputElement(event.target) && event.target !== registrationTarget\n}\n\n/**\n * Checks if an event is for the given target (originated from or bubbled to it).\n *\n * For document/window targets, also accepts document.documentElement as currentTarget\n * to handle Brave and other browsers where currentTarget may be documentElement\n * instead of document when listeners are attached to document.\n */\nexport function isEventForTarget(\n  event: KeyboardEvent,\n  target: HTMLElement | Document | Window,\n): boolean {\n  // For Document and Window, verify that our handler was indeed called for this target.\n  //\n  // Browser compatibility note:\n  // Per the DOM spec, event.currentTarget should equal the element the listener was\n  // attached to. However, some Chromium-based browsers (notably Brave) exhibit\n  // non-standard behavior where event.currentTarget is set to document.documentElement\n  // (<html>) instead of document when a listener is attached to document.\n  // This may be related to privacy/fingerprinting protections.\n  //\n  // To ensure cross-browser compatibility, we accept both the expected target\n  // and document.documentElement as valid currentTarget values.\n  // See: https://dom.spec.whatwg.org/#dom-event-currenttarget\n  if (target === document || target === window) {\n    return (\n      event.currentTarget === target ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For Window, accept window, document, or document.documentElement (browser quirks)\n  if (target === window) {\n    return (\n      event.currentTarget === window ||\n      event.currentTarget === document ||\n      event.currentTarget === document.documentElement\n    )\n  }\n\n  // For HTMLElement, check if event originated from or bubbled to the element\n  if (target instanceof HTMLElement) {\n    // Check if the event's currentTarget is the target (capturing/bubbling)\n    if (event.currentTarget === target) {\n      return true\n    }\n\n    // Check if the event's target is a descendant of our target\n    if (event.target instanceof Node && target.contains(event.target)) {\n      return true\n    }\n  }\n\n  return false\n}\n\n/**\n * Handles conflicts between registrations based on conflict behavior.\n *\n * @param conflictingId - The ID of the conflicting registration\n * @param keyDisplay - Display string for the conflicting key/sequence (for error messages)\n * @param conflictBehavior - How to handle the conflict\n * @param unregister - Function to unregister by ID\n */\nexport function handleConflict(\n  conflictingId: string,\n  keyDisplay: string,\n  conflictBehavior: ConflictBehavior,\n  unregister: (id: string) => void,\n): void {\n  if (conflictBehavior === 'allow') {\n    return\n  }\n\n  if (conflictBehavior === 'warn') {\n    console.warn(\n      `'${keyDisplay}' is already registered. Multiple handlers will be triggered. ` +\n        `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n        `or conflictBehavior: 'allow' to suppress this warning.`,\n    )\n    return\n  }\n\n  if (conflictBehavior === 'error') {\n    throw new Error(\n      `'${keyDisplay}' is already registered. ` +\n        `Use conflictBehavior: 'replace' to replace the existing handler, ` +\n        `or conflictBehavior: 'allow' to allow multiple registrations.`,\n    )\n  }\n\n  // At this point, conflictBehavior must be 'replace'\n  unregister(conflictingId)\n}\n"],"mappings":";;;;;AAgBA,MAAa,uBAAuB;CAClC,gBAAgB;CAChB,iBAAiB;CACjB,WAAW;CACX,SAAS;CACT,cAAc;CACd,kBAAkB;CACnB;;;;;AAMD,SAAgB,uBAAuB,cAAqC;AAC1E,KAAI,aAAa,QAAQ,aAAa,KAAM,QAAO;AACnD,KAAI,aAAa,QAAQ,SAAU,QAAO;AAC1C,QAAO;;;;;;;;;;;;;;AAeT,SAAgB,eAAe,SAAsC;AACnE,KAAI,CAAC,QACH,QAAO;AAGT,KAAI,mBAAmB,kBAAkB;EACvC,MAAM,OAAO,QAAQ,KAAK,aAAa;AACvC,MAAI,SAAS,YAAY,SAAS,YAAY,SAAS,QACrD,QAAO;AAET,SAAO;;AAGT,KACE,mBAAmB,uBACnB,mBAAmB,kBAEnB,QAAO;AAKT,KAAI,mBAAmB,eAAe,QAAQ,kBAC5C,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,kCACd,QACgB;AAChB,KAAI,OAAO,aAAa,YACtB,QAAO;AAIT,KACG,OAAO,aAAa,eAAe,kBAAkB,YACrD,OAAO,SAAS,eACd,OAAgB,aAAa,KAAK,cAErC,QAAQ,OAAoB;AAG9B,KAAI,OAAO,gBAAgB,eAAe,kBAAkB,YAC1D,QAAO,OAAO,cAAc,iBAAiB;AAI/C,QAAQ,OAAkB,SAAS,iBAAiB;;;;;;;;;;;AAYtD,SAAgB,uBACd,OACA,gBACA,oBACS;CACT,MAAM,UAAU,kCAAkC,eAAe;AACjE,KAAI,WAAW,eAAe,QAAQ,IAAI,YAAY,mBACpD,QAAO;AAGT,KACE,MACG,cAAc,CACd,MACE,YAAY,eAAe,QAAQ,IAAI,YAAY,mBACrD,CAEH,QAAO;AAGT,QAAO,eAAe,MAAM,OAAO,IAAI,MAAM,WAAW;;;;;;;;;AAU1D,SAAgB,iBACd,OACA,QACS;AAaT,KAAI,WAAW,YAAY,WAAW,OACpC,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,WAAW,OACb,QACE,MAAM,kBAAkB,UACxB,MAAM,kBAAkB,YACxB,MAAM,kBAAkB,SAAS;AAKrC,KAAI,kBAAkB,aAAa;AAEjC,MAAI,MAAM,kBAAkB,OAC1B,QAAO;AAIT,MAAI,MAAM,kBAAkB,QAAQ,OAAO,SAAS,MAAM,OAAO,CAC/D,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,SAAgB,eACd,eACA,YACA,kBACA,YACM;AACN,KAAI,qBAAqB,QACvB;AAGF,KAAI,qBAAqB,QAAQ;AAC/B,UAAQ,KACN,IAAI,WAAW,uLAGhB;AACD;;AAGF,KAAI,qBAAqB,QACvB,OAAM,IAAI,MACR,IAAI,WAAW,yJAGhB;AAIH,YAAW,cAAc"}

package/dist/recorder-chord.cjs

@@ -1,18 +0,0 @@
-const require_constants = require('./constants.cjs');
-const require_parse = require('./parse.cjs');
-
-//#region src/recorder-chord.ts
-/**
-* Parses a keydown event into a single normalized hotkey chord, or null if
-* the event should be ignored (modifier-only or invalid).
-*/
-function hotkeyChordFromKeydown(event, platform) {
-	if (require_parse.isModifierKey(require_constants.normalizeKeyName(event.key))) return null;
-	const finalHotkey = require_parse.normalizeHotkeyFromEvent(event, platform);
-	if (!require_parse.hasNonModifierKey(finalHotkey, platform)) return null;
-	return finalHotkey;
-}
-
-//#endregion
-exports.hotkeyChordFromKeydown = hotkeyChordFromKeydown;
-//# sourceMappingURL=recorder-chord.cjs.map

package/dist/recorder-chord.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"recorder-chord.cjs","names":["isModifierKey","normalizeKeyName","normalizeHotkeyFromEvent","hasNonModifierKey"],"sources":["../src/recorder-chord.ts"],"sourcesContent":["import { normalizeKeyName } from './constants'\nimport {\n  hasNonModifierKey,\n  isModifierKey,\n  normalizeHotkeyFromEvent,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * Parses a keydown event into a single normalized hotkey chord, or null if\n * the event should be ignored (modifier-only or invalid).\n */\nexport function hotkeyChordFromKeydown(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey | null {\n  if (isModifierKey(normalizeKeyName(event.key))) {\n    return null\n  }\n  const finalHotkey = normalizeHotkeyFromEvent(event, platform)\n  if (!hasNonModifierKey(finalHotkey, platform)) {\n    return null\n  }\n  return finalHotkey\n}\n"],"mappings":";;;;;;;;AAYA,SAAgB,uBACd,OACA,UACe;AACf,KAAIA,4BAAcC,mCAAiB,MAAM,IAAI,CAAC,CAC5C,QAAO;CAET,MAAM,cAAcC,uCAAyB,OAAO,SAAS;AAC7D,KAAI,CAACC,gCAAkB,aAAa,SAAS,CAC3C,QAAO;AAET,QAAO"}

package/dist/recorder-chord.js

@@ -1,18 +0,0 @@
-import { normalizeKeyName } from "./constants.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkeyFromEvent } from "./parse.js";
-
-//#region src/recorder-chord.ts
-/**
-* Parses a keydown event into a single normalized hotkey chord, or null if
-* the event should be ignored (modifier-only or invalid).
-*/
-function hotkeyChordFromKeydown(event, platform) {
-	if (isModifierKey(normalizeKeyName(event.key))) return null;
-	const finalHotkey = normalizeHotkeyFromEvent(event, platform);
-	if (!hasNonModifierKey(finalHotkey, platform)) return null;
-	return finalHotkey;
-}
-
-//#endregion
-export { hotkeyChordFromKeydown };
-//# sourceMappingURL=recorder-chord.js.map

package/dist/recorder-chord.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recorder-chord.js","names":[],"sources":["../src/recorder-chord.ts"],"sourcesContent":["import { normalizeKeyName } from './constants'\nimport {\n  hasNonModifierKey,\n  isModifierKey,\n  normalizeHotkeyFromEvent,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * Parses a keydown event into a single normalized hotkey chord, or null if\n * the event should be ignored (modifier-only or invalid).\n */\nexport function hotkeyChordFromKeydown(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey | null {\n  if (isModifierKey(normalizeKeyName(event.key))) {\n    return null\n  }\n  const finalHotkey = normalizeHotkeyFromEvent(event, platform)\n  if (!hasNonModifierKey(finalHotkey, platform)) {\n    return null\n  }\n  return finalHotkey\n}\n"],"mappings":";;;;;;;;AAYA,SAAgB,uBACd,OACA,UACe;AACf,KAAI,cAAc,iBAAiB,MAAM,IAAI,CAAC,CAC5C,QAAO;CAET,MAAM,cAAc,yBAAyB,OAAO,SAAS;AAC7D,KAAI,CAAC,kBAAkB,aAAa,SAAS,CAC3C,QAAO;AAET,QAAO"}

package/src/recorder-chord.ts

@@ -1,25 +0,0 @@
-import { normalizeKeyName } from './constants'
-import {
-  hasNonModifierKey,
-  isModifierKey,
-  normalizeHotkeyFromEvent,
-} from './parse'
-import type { Hotkey } from './hotkey'
-
-/**
- * Parses a keydown event into a single normalized hotkey chord, or null if
- * the event should be ignored (modifier-only or invalid).
- */
-export function hotkeyChordFromKeydown(
-  event: KeyboardEvent,
-  platform: 'mac' | 'windows' | 'linux',
-): Hotkey | null {
-  if (isModifierKey(normalizeKeyName(event.key))) {
-    return null
-  }
-  const finalHotkey = normalizeHotkeyFromEvent(event, platform)
-  if (!hasNonModifierKey(finalHotkey, platform)) {
-    return null
-  }
-  return finalHotkey
-}