@tanstack/hotkeys 0.15.0 → 0.16.0

package/dist/hotkey.types.d.ts

@@ -11,7 +11,7 @@ import { CanonicalModifier, Key, LogicalKey } from "./key.types.js";
  * This enables cross-platform hotkey definitions that automatically adapt to the platform.
  * For example, `Mod+S` becomes `Command+S` on Mac and `Ctrl+S` on Windows/Linux.
  */
-export type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
+export type SingleModifierHotkeyChord = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
 /**
  * Two modifier + key combinations.
  *
@@ -21,7 +21,7 @@ export type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Ke
  *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-export type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${Key}` | `Control+Meta+${Key}` | `Alt+Shift+${Key}` | `Alt+Meta+${Key}` | `Shift+Meta+${Key}` | `Mod+Alt+${Key}` | `Mod+Shift+${Key}`;
+export type TwoModifierHotkeyChord = `Control+Alt+${Key}` | `Control+Shift+${Key}` | `Control+Meta+${Key}` | `Alt+Shift+${Key}` | `Alt+Meta+${Key}` | `Shift+Meta+${Key}` | `Mod+Alt+${Key}` | `Mod+Shift+${Key}`;
 /**
  * Three modifier + key combinations.
  *
@@ -31,7 +31,7 @@ export type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${Key}` |
  *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-export type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
+export type ThreeModifierHotkeyChord = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
 /**
  * Four modifier + key combinations.
  *
@@ -44,7 +44,7 @@ export type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta
  * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
  * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
  */
-export type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
+export type FourModifierHotkeyChord = `Control+Alt+Shift+Meta+${Key}`;
 /**
  * A type-safe hotkey string.
  *
@@ -97,7 +97,7 @@ export type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
  * const windowsOnly: HotkeyChord = 'Control+S' // Ctrl+S on Windows/Linux only
  * ```
  */
-export type HotkeyChord = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
+export type HotkeyChord = Key | SingleModifierHotkeyChord | TwoModifierHotkeyChord | ThreeModifierHotkeyChord | FourModifierHotkeyChord;
 /** Resolved modifier flags shared by both parsed binding variants. */
 export interface ParsedModifiers {
   /** Whether Control is required. */
@@ -112,31 +112,41 @@ export interface ParsedModifiers {
   modifiers: Array<CanonicalModifier>;
 }
 /**
- * A parsed binding matches either a logical key or a physical code, never both.
+ * A parsed chord matches either a logical key or a physical code, never both.
  * Check `code !== undefined` to narrow to a physical binding. Its logical
  * character is unknown without a keyboard event and is not stored in `key`.
  *
  * @example
  * parseHotkey('Alt+S') // { key: 'S', alt: true, ... }
- * parseHotkey('Alt+[KeyS]') // { code: 'KeyS', alt: true, ... } — no key property
+ * parseHotkey('Alt+[KeyS]') // { code: 'KeyS', alt: true, ... } with no key property
  */
-export type ParsedHotkey = ParsedModifiers & ({
+export type ParsedHotkeyChord = ParsedModifiers & ({
   key: LogicalKey | (string & {});
   code?: never;
 } | {
   code: string;
   key?: never;
 });
+/** Modifier flags shared by logical-key and physical-code registrations. */
+export interface RawModifiers {
+  /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
+  mod?: boolean;
+  /** Whether the Control key is required. Defaults to false. */
+  ctrl?: boolean;
+  /** Whether the Shift key is required. Defaults to false. */
+  shift?: boolean;
+  /** Whether the Alt key is required. Defaults to false. */
+  alt?: boolean;
+  /** Whether the Meta (Command) key is required. Defaults to false. */
+  meta?: boolean;
+}
 /**
- * A raw hotkey object for programmatic registration.
- *
- * Like `ParsedHotkey` but without `modifiers` (derived from booleans)
- * and with optional modifier booleans (default to `false` when omitted).
- * Use with `HotkeyManager.register()` and `useHotkey()` when you prefer
- * object form over a string.
+ * A chord written as an object instead of a string, for building chords from
+ * data. Set `key` for a logical key or `code` for a physical one, and set a
+ * boolean for each modifier. Omitted modifiers default to `false`.
  *
  * The `mod` modifier is platform-adaptive: Command on macOS, Control on Windows/Linux.
- * Pass `platform` when converting to ParsedHotkey (e.g., via `options.platform`).
+ * Sequence steps can be objects too: `[{ key: 'K', mod: true }, 'C']`.
  *
  * @example
  * ```ts
@@ -149,21 +159,7 @@ export type ParsedHotkey = ParsedModifiers & ({
  * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
  * ```
  */
-/** Modifier flags shared by logical-key and physical-code registrations. */
-export interface RawModifiers {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
-  mod?: boolean;
-  /** Whether the Control key is required. Defaults to false. */
-  ctrl?: boolean;
-  /** Whether the Shift key is required. Defaults to false. */
-  shift?: boolean;
-  /** Whether the Alt key is required. Defaults to false. */
-  alt?: boolean;
-  /** Whether the Meta (Command) key is required. Defaults to false. */
-  meta?: boolean;
-}
-export type RawHotkey = ({
+export type RawHotkeyChord = ({
   key: LogicalKey | (string & {});
   code?: never;
 } & RawModifiers) | ({
@@ -171,7 +167,9 @@ export type RawHotkey = ({
   key?: never;
 } & RawModifiers);
 /**
- * A sequence of chords pressed one after another (Vim-style), such as `['G', 'G']`.
+ * A sequence of chord strings pressed one after another (Vim-style), such as
+ * `['G', 'G']`. Registered sequences are stored in this form. To register
+ * steps written as objects, see {@link RegisterableHotkeySequence}.
  *
  * Steps may include modifiers; the same modifier can appear on consecutive
  * steps (e.g. `['Shift+R', 'Shift+T']`). Modifier-only key events do not
@@ -183,36 +181,64 @@ export type HotkeySequence = ReadonlyArray<HotkeyChord>;
  * A hotkey: one chord (`'Mod+S'`) or a sequence of chords (`['G', 'G']`).
  */
 export type Hotkey = HotkeyChord | HotkeySequence;
-/** A single chord as a type-safe string (`HotkeyChord`) or a raw object (`RawHotkey`). */
-export type RegisterableHotkeyChord = HotkeyChord | RawHotkey;
+/** A single chord as a type-safe string (`HotkeyChord`) or an object (`RawHotkeyChord`). */
+export type RegisterableHotkeyChord = HotkeyChord | RawHotkeyChord;
 /**
- * Anything that can be registered: a chord string, a raw chord object, or a sequence.
+ * A sequence whose steps are chord strings or chord objects, such as
+ * `['G', { key: 'H', shift: true }]`.
  */
-export type RegisterableHotkey = RegisterableHotkeyChord | HotkeySequence;
+export type RegisterableHotkeySequence = ReadonlyArray<RegisterableHotkeyChord>;
 /**
- * Context passed to hotkey callbacks along with the keyboard event.
+ * Anything that can be registered: a chord or a sequence, with each chord
+ * written as a string or an object.
  */
-export interface HotkeyCallbackContext {
-  /** The registered hotkey: a chord string or a sequence */
-  hotkey: Hotkey;
-  /** The parsed chord that completed the match (the last step of a sequence) */
-  parsedHotkey: ParsedHotkey;
+export type RegisterableHotkey = RegisterableHotkeyChord | RegisterableHotkeySequence;
+/** Context passed to a chord's callback. */
+export interface HotkeyChordCallbackContext {
+  kind: 'chord';
+  /** The registered chord */
+  hotkey: HotkeyChord;
+  /** The chord with `Mod` resolved for the registration's platform */
+  parsedChord: ParsedHotkeyChord;
+}
+/** Context passed to a sequence's callback. */
+export interface HotkeySequenceCallbackContext {
+  kind: 'sequence';
+  /** The registered sequence */
+  hotkey: HotkeySequence;
+  /** Each step with `Mod` resolved for the registration's platform */
+  parsedSequence: Array<ParsedHotkeyChord>;
 }
+/**
+ * Context passed to hotkey callbacks along with the keyboard event.
+ * Narrow with `kind` to read `parsedChord` or `parsedSequence`.
+ */
+export type HotkeyCallbackContext = HotkeyChordCallbackContext | HotkeySequenceCallbackContext;
+/**
+ * The callback context for a hotkey: chord context for chords (including
+ * one-step tuples), sequence context for sequences, and either when the kind
+ * is not known statically.
+ */
+export type HotkeyCallbackContextFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyCallbackContext : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordCallbackContext : T extends RegisterableHotkeySequence ? HotkeySequenceCallbackContext : HotkeyChordCallbackContext;
 /**
  * Callback function type for hotkey handlers.
  *
  * @param event - The keyboard event that triggered the hotkey
- * @param context - Additional context including the hotkey and parsed hotkey
+ * @param context - The registered hotkey and its parsed form. APIs that take
+ * one hotkey narrow it to chord or sequence context from the hotkey you pass.
  *
  * @example
  * ```ts
- * const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
- *   console.log(`Hotkey ${hotkey} was pressed`)
- *   console.log(`Modifiers:`, parsedHotkey.modifiers)
+ * const handler: HotkeyCallback = (event, context) => {
+ *   if (context.kind === 'chord') {
+ *     console.log(context.hotkey, context.parsedChord.modifiers)
+ *   } else {
+ *     console.log(context.hotkey.join(' '), context.parsedSequence.length)
+ *   }
  * }
  * ```
  */
-export type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
+export type HotkeyCallback<TContext extends HotkeyCallbackContext = HotkeyCallbackContext> = (event: KeyboardEvent, context: TContext) => void;
 /**
  * Metadata for hotkey registrations, chords and sequences alike.
  * Includes `name`, `description`, and `group` by default. Extend via declaration merging:

package/dist/index.d.ts

@@ -1,17 +1,16 @@
 import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
-import { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.js";
-import { HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
+import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
 import { DisplayHotkey, DisplayHotkeyChord, FormatDisplayOptions, formatForDisplay, formatHotkey } from "./format.js";
-import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
+import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { ValidatableHotkey, ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-import { CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
+import { CreateHotkeyChordHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, KeyboardEventMatch, MultiHotkeyChordHandler, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
 import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
-import { HotkeyRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.js";
-import { HotkeyChordRecorderOptions, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeySequenceRecorderOptions } from "./hotkey-recorder.js";
-export { ALL_KEYS, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkey, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyChord, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkey, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisteredAppHotkeys, SingleModifierHotkey, Target, ThreeModifierHotkey, TwoModifierHotkey, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, provideAppHotkeys, publishAppHotkeysStore, rawHotkeyToParsedHotkey, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/index.js

@@ -1,10 +1,10 @@
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
+import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { formatForDisplay, formatHotkey } from "./format.js";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
 import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { findHotkeyConflicts } from "./conflicts.js";
@@ -12,4 +12,4 @@ import { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isA
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
 
-export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, provideAppHotkeys, publishAppHotkeysStore, rawHotkeyToParsedHotkey, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/key-state-tracker.js

@@ -53,10 +53,8 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	store = new Store(getDefaultKeyStateTrackerState());
 	#heldEntries = /* @__PURE__ */ new Map();
-	#keydownListener = null;
-	#keyupListener = null;
-	#mouseListener = null;
-	#blurListener = null;
+	/** Window listeners as `[type, listener, capture]`, removed together on destroy. */
+	#listeners = [];
 	constructor() {
 		this.#setupListeners();
 	}
@@ -81,7 +79,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	#setupListeners() {
 		if (typeof document === "undefined") return;
-		this.#keydownListener = (event) => {
+		const onKeydown = (event) => {
 			let changed = this.#reconcileModifiers(event);
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
@@ -94,7 +92,7 @@ var KeyStateTracker = class KeyStateTracker {
 			}
 			if (changed) this.#syncState();
 		};
-		this.#keyupListener = (event) => {
+		const onKeyup = (event) => {
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
 			this.#heldEntries.delete(identity);
@@ -107,20 +105,43 @@ var KeyStateTracker = class KeyStateTracker {
 			}
 			this.#syncState();
 		};
-		this.#mouseListener = (event) => {
+		const onMouse = (event) => {
 			if (this.#reconcileModifiers(event)) this.#syncState();
 		};
-		this.#blurListener = () => {
+		const onBlur = () => {
 			if (this.#heldEntries.size > 0) {
 				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		window.addEventListener("keydown", this.#keydownListener, true);
-		window.addEventListener("keyup", this.#keyupListener, true);
-		window.addEventListener("mousemove", this.#mouseListener, true);
-		window.addEventListener("mousedown", this.#mouseListener, true);
-		window.addEventListener("blur", this.#blurListener);
+		this.#listeners = [
+			[
+				"keydown",
+				onKeydown,
+				true
+			],
+			[
+				"keyup",
+				onKeyup,
+				true
+			],
+			[
+				"mousemove",
+				onMouse,
+				true
+			],
+			[
+				"mousedown",
+				onMouse,
+				true
+			],
+			[
+				"blur",
+				onBlur,
+				false
+			]
+		];
+		for (const [type, listener, capture] of this.#listeners) window.addEventListener(type, listener, capture);
 	}
 	/**
 	* Removes modifiers whose release was missed without a window blur.
@@ -153,24 +174,8 @@ var KeyStateTracker = class KeyStateTracker {
 	* Removes the keyboard event listeners.
 	*/
 	#removeListeners() {
-		if (typeof document === "undefined") return;
-		if (this.#keydownListener) {
-			window.removeEventListener("keydown", this.#keydownListener, true);
-			this.#keydownListener = null;
-		}
-		if (this.#keyupListener) {
-			window.removeEventListener("keyup", this.#keyupListener, true);
-			this.#keyupListener = null;
-		}
-		if (this.#mouseListener) {
-			window.removeEventListener("mousemove", this.#mouseListener, true);
-			window.removeEventListener("mousedown", this.#mouseListener, true);
-			this.#mouseListener = null;
-		}
-		if (this.#blurListener) {
-			window.removeEventListener("blur", this.#blurListener);
-			this.#blurListener = null;
-		}
+		for (const [type, listener, capture] of this.#listeners) window.removeEventListener(type, listener, capture);
+		this.#listeners = [];
 	}
 	/**
 	* Gets an array of currently held key names.

package/dist/match.d.ts

@@ -1,4 +1,4 @@
-import { HotkeyCallback, HotkeyChord, HotkeySequence, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
 //#region src/match.d.ts
 export interface KeyboardEventMatch {
   matched: boolean;
@@ -24,9 +24,9 @@ export interface KeyboardEventMatch {
  * In these cases, `event.code` is used to determine the physical key.
  *
  * @param event - The KeyboardEvent to check
- * @param hotkey - The hotkey string or ParsedHotkey to match against
+ * @param chord - The chord string or parsed chord to match against
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns True if the event matches the hotkey
+ * @returns True if the event matches the chord
  *
  * @example
  * ```ts
@@ -38,29 +38,30 @@ export interface KeyboardEventMatch {
  * })
  * ```
  */
-export declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: HotkeyChord | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
+export declare function matchesKeyboardEvent(event: KeyboardEvent, chord: HotkeyChord | ParsedHotkeyChord, platform?: 'mac' | 'windows' | 'linux'): boolean;
 /**
- * Options for creating a hotkey handler.
+ * Options for creating a chord handler.
  */
-export interface CreateHotkeyHandlerOptions {
-  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+export interface CreateHotkeyChordHandlerOptions {
+  /** Prevent the default browser action when the chord matches. Defaults to true */
   preventDefault?: boolean;
-  /** Stop event propagation when the hotkey matches. Defaults to true */
+  /** Stop event propagation when the chord 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.
+ * Creates a keyboard event handler that calls the callback when the chord
+ * matches. For sequences, use `createSequenceMatcher`.
  *
- * @param hotkey - The hotkey string or ParsedHotkey to match
+ * @param chord - The chord string or parsed chord 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 }) => {
+ * const handler = createHotkeyChordHandler('Mod+S', (event, { hotkey, parsedChord }) => {
  *   console.log(`${hotkey} was pressed`)
  *   handleSave()
  * })
@@ -68,18 +69,18 @@ export interface CreateHotkeyHandlerOptions {
  * document.addEventListener('keydown', handler)
  * ```
  */
-export declare function createHotkeyHandler(hotkey: HotkeyChord | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
-export type MultiHotkeyHandler = { [K in HotkeyChord]?: HotkeyCallback; };
+export declare function createHotkeyChordHandler(chord: HotkeyChord | ParsedHotkeyChord, callback: HotkeyCallback<HotkeyChordCallbackContext>, options?: CreateHotkeyChordHandlerOptions): (event: KeyboardEvent) => void;
+export type MultiHotkeyChordHandler = { [K in HotkeyChord]?: HotkeyCallback<HotkeyChordCallbackContext>; };
 /**
- * Creates a handler that matches multiple hotkeys.
+ * Creates a handler that matches several chords.
  *
- * @param handlers - A map of hotkey strings to their handlers
+ * @param handlers - A map of chord 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({
+ * const handler = createMultiHotkeyChordHandler({
  *   'Mod+S': (event, { hotkey }) => handleSave(),
  *   'Mod+Z': (event, { hotkey }) => handleUndo(),
  *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
@@ -88,7 +89,7 @@ export type MultiHotkeyHandler = { [K in HotkeyChord]?: HotkeyCallback; };
  * document.addEventListener('keydown', handler)
  * ```
  */
-export declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+export declare function createMultiHotkeyChordHandler(handlers: MultiHotkeyChordHandler, options?: CreateHotkeyChordHandlerOptions): (event: KeyboardEvent) => void;
 /**
  * Compares normalized hotkey identity, including all four modifiers.
  * Sequences are equal when every step is equal; a one-step sequence equals its chord.
@@ -120,7 +121,7 @@ export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
  * })
  * ```
  */
-export declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
+export declare function createSequenceMatcher(sequence: RegisterableHotkeySequence, options?: {
   timeout?: number;
   platform?: 'mac' | 'windows' | 'linux';
 }): {

package/dist/match.js

@@ -1,8 +1,9 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey, parseRegisterableHotkey } from "./parse.js";
-import { matchKeyboardEvent } from "./_match.js";
+import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
+import { formatHotkey } from "./format.js";
+import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 
 //#region src/match.ts
 /**
@@ -20,9 +21,9 @@ import { matchKeyboardEvent } from "./_match.js";
 * In these cases, `event.code` is used to determine the physical key.
 *
 * @param event - The KeyboardEvent to check
-* @param hotkey - The hotkey string or ParsedHotkey to match against
+* @param chord - The chord string or parsed chord to match against
 * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns True if the event matches the hotkey
+* @returns True if the event matches the chord
 *
 * @example
 * ```ts
@@ -34,20 +35,21 @@ import { matchKeyboardEvent } from "./_match.js";
 * })
 * ```
 */
-function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
-	return matchKeyboardEvent(event, hotkey, platform).matched;
+function matchesKeyboardEvent(event, chord, platform = detectPlatform()) {
+	return matchKeyboardEvent(event, chord, platform).matched;
 }
 /**
-* Creates a keyboard event handler that calls the callback when the hotkey matches.
+* Creates a keyboard event handler that calls the callback when the chord
+* matches. For sequences, use `createSequenceMatcher`.
 *
-* @param hotkey - The hotkey string or ParsedHotkey to match
+* @param chord - The chord string or parsed chord 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 }) => {
+* const handler = createHotkeyChordHandler('Mod+S', (event, { hotkey, parsedChord }) => {
 *   console.log(`${hotkey} was pressed`)
 *   handleSave()
 * })
@@ -55,14 +57,15 @@ function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 * document.addEventListener('keydown', handler)
 * ```
 */
-function createHotkeyHandler(hotkey, callback, options = {}) {
+function createHotkeyChordHandler(chord, callback, options = {}) {
 	const { preventDefault = true, stopPropagation = true, platform } = options;
 	const resolvedPlatform = platform ?? detectPlatform();
-	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
-	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, resolvedPlatform) : hotkey;
+	const hotkeyString = typeof chord === "string" ? chord : formatHotkey(chord);
+	const parsed = typeof chord === "string" ? parseHotkey(chord, resolvedPlatform) : chord;
 	const context = {
+		kind: "chord",
 		hotkey: hotkeyString,
-		parsedHotkey: parsed
+		parsedChord: parsed
 	};
 	return (event) => {
 		if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
@@ -73,15 +76,15 @@ function createHotkeyHandler(hotkey, callback, options = {}) {
 	};
 }
 /**
-* Creates a handler that matches multiple hotkeys.
+* Creates a handler that matches several chords.
 *
-* @param handlers - A map of hotkey strings to their handlers
+* @param handlers - A map of chord 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({
+* const handler = createMultiHotkeyChordHandler({
 *   'Mod+S': (event, { hotkey }) => handleSave(),
 *   'Mod+Z': (event, { hotkey }) => handleUndo(),
 *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
@@ -90,7 +93,7 @@ function createHotkeyHandler(hotkey, callback, options = {}) {
 * document.addEventListener('keydown', handler)
 * ```
 */
-function createMultiHotkeyHandler(handlers, options = {}) {
+function createMultiHotkeyChordHandler(handlers, options = {}) {
 	const { preventDefault = true, stopPropagation = true, platform } = options;
 	const resolvedPlatform = platform ?? detectPlatform();
 	const parsedHandlers = Object.entries(handlers).filter((entry) => Boolean(entry[1])).map(([hotkey, handler]) => {
@@ -99,8 +102,9 @@ function createMultiHotkeyHandler(handlers, options = {}) {
 			parsed,
 			handler,
 			context: {
+				kind: "chord",
 				hotkey,
-				parsedHotkey: parsed
+				parsedChord: parsed
 			}
 		};
 	});
@@ -114,19 +118,6 @@ function createMultiHotkeyHandler(handlers, options = {}) {
 	};
 }
 /**
-* Formats a ParsedHotkey back to a hotkey string.
-* Used internally to provide the hotkey string in callback context.
-*/
-function formatParsedHotkey(parsed) {
-	const parts = [];
-	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.code !== void 0 ? `[${parsed.code}]` : parsed.key);
-	return parts.join("+");
-}
-/**
 * Compares normalized hotkey identity, including all four modifiers.
 * Sequences are equal when every step is equal; a one-step sequence equals its chord.
 * Aliases resolve on the supplied platform. A physical code and a logical key
@@ -135,12 +126,7 @@ function formatParsedHotkey(parsed) {
 function areHotkeysEqual(left, right, platform = detectPlatform()) {
 	const a = isHotkeySequence(left) ? left : [left];
 	const b = isHotkeySequence(right) ? right : [right];
-	return a.length === b.length && a.every((step, index) => areChordsEqual(step, b[index], platform));
-}
-function areChordsEqual(left, right, platform) {
-	const a = parseRegisterableHotkey(left, platform);
-	const b = parseRegisterableHotkey(right, platform);
-	return a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+	return a.length === b.length && a.every((step, index) => parsedChordsEqual(parseHotkey(step, platform), parseHotkey(b[index], platform)));
 }
 /** Default timeout between sequence steps (in milliseconds). */
 const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
@@ -169,7 +155,7 @@ const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
 function createSequenceMatcher(sequence, options = {}) {
 	const platform = options.platform ?? detectPlatform();
 	const timeout = options.timeout ?? 1e3;
-	const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform));
+	const parsedSequence = parseHotkey(sequence, platform);
 	let currentIndex = 0;
 	let lastKeyTime = 0;
 	return {
@@ -205,4 +191,4 @@ function createSequenceMatcher(sequence, options = {}) {
 }
 
 //#endregion
-export { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, matchesKeyboardEvent };
+export { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent };