@tanstack/hotkeys 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -1,14 +1,18 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_constants = require('./constants.cjs');
+const require_display_labels = require('./display-labels.cjs');
+const require_platform = require('./platform.cjs');
 const require_parse = require('./parse.cjs');
 const require_format = require('./format.cjs');
+const require_validate = require('./validate.cjs');
 const require_match = require('./match.cjs');
+const require_hint = require('./hint.cjs');
 const require_hotkey_manager = require('./hotkey-manager.cjs');
+const require_sequence_manager = require('./sequence-manager.cjs');
+const require_conflicts = require('./conflicts.cjs');
 const require_key_state_tracker = require('./key-state-tracker.cjs');
 const require_hotkey_recorder = require('./hotkey-recorder.cjs');
 const require_hotkey_sequence_recorder = require('./hotkey-sequence-recorder.cjs');
-const require_sequence_manager = require('./sequence-manager.cjs');
-const require_validate = require('./validate.cjs');
 
 exports.ALL_KEYS = require_constants.ALL_KEYS;
 exports.DEFAULT_SEQUENCE_TIMEOUT = require_sequence_manager.DEFAULT_SEQUENCE_TIMEOUT;
@@ -17,12 +21,12 @@ exports.FUNCTION_KEYS = require_constants.FUNCTION_KEYS;
 exports.HotkeyManager = require_hotkey_manager.HotkeyManager;
 exports.HotkeyRecorder = require_hotkey_recorder.HotkeyRecorder;
 exports.HotkeySequenceRecorder = require_hotkey_sequence_recorder.HotkeySequenceRecorder;
-exports.KEY_DISPLAY_SYMBOLS = require_constants.KEY_DISPLAY_SYMBOLS;
+exports.KEY_DISPLAY_SYMBOLS = require_display_labels.KEY_DISPLAY_SYMBOLS;
 exports.KeyStateTracker = require_key_state_tracker.KeyStateTracker;
 exports.LETTER_KEYS = require_constants.LETTER_KEYS;
-exports.LINUX_MODIFIER_LABELS = require_constants.LINUX_MODIFIER_LABELS;
-exports.MAC_MODIFIER_LABELS = require_constants.MAC_MODIFIER_LABELS;
-exports.MAC_MODIFIER_SYMBOLS = require_constants.MAC_MODIFIER_SYMBOLS;
+exports.LINUX_MODIFIER_LABELS = require_display_labels.LINUX_MODIFIER_LABELS;
+exports.MAC_MODIFIER_LABELS = require_display_labels.MAC_MODIFIER_LABELS;
+exports.MAC_MODIFIER_SYMBOLS = require_display_labels.MAC_MODIFIER_SYMBOLS;
 exports.MODIFIER_ALIASES = require_constants.MODIFIER_ALIASES;
 exports.MODIFIER_KEYS = require_constants.MODIFIER_KEYS;
 exports.MODIFIER_ORDER = require_constants.MODIFIER_ORDER;
@@ -30,15 +34,17 @@ exports.NAVIGATION_KEYS = require_constants.NAVIGATION_KEYS;
 exports.NUMBER_KEYS = require_constants.NUMBER_KEYS;
 exports.PUNCTUATION_CODE_MAP = require_constants.PUNCTUATION_CODE_MAP;
 exports.PUNCTUATION_KEYS = require_constants.PUNCTUATION_KEYS;
-exports.PUNCTUATION_KEY_DISPLAY_LABELS = require_constants.PUNCTUATION_KEY_DISPLAY_LABELS;
+exports.PUNCTUATION_KEY_DISPLAY_LABELS = require_display_labels.PUNCTUATION_KEY_DISPLAY_LABELS;
 exports.SequenceManager = require_sequence_manager.SequenceManager;
-exports.WINDOWS_MODIFIER_LABELS = require_constants.WINDOWS_MODIFIER_LABELS;
+exports.WINDOWS_MODIFIER_LABELS = require_display_labels.WINDOWS_MODIFIER_LABELS;
+exports.areHotkeysEqual = require_match.areHotkeysEqual;
 exports.assertValidHotkey = require_validate.assertValidHotkey;
 exports.checkHotkey = require_validate.checkHotkey;
 exports.createHotkeyHandler = require_match.createHotkeyHandler;
 exports.createMultiHotkeyHandler = require_match.createMultiHotkeyHandler;
 exports.createSequenceMatcher = require_sequence_manager.createSequenceMatcher;
-exports.detectPlatform = require_constants.detectPlatform;
+exports.detectPlatform = require_platform.detectPlatform;
+exports.findHotkeyConflicts = require_conflicts.findHotkeyConflicts;
 exports.formatForDisplay = require_format.formatForDisplay;
 exports.formatHotkey = require_format.formatHotkey;
 exports.formatHotkeySequence = require_format.formatHotkeySequence;
@@ -49,6 +55,7 @@ exports.getSequenceManager = require_sequence_manager.getSequenceManager;
 exports.hasNonModifierKey = require_parse.hasNonModifierKey;
 exports.isModifierKey = require_parse.isModifierKey;
 exports.isSingleLetterKey = require_constants.isSingleLetterKey;
+exports.matchesHeldModifiers = require_hint.matchesHeldModifiers;
 exports.matchesKeyboardEvent = require_match.matchesKeyboardEvent;
 exports.normalizeHotkey = require_parse.normalizeHotkey;
 exports.normalizeHotkeyFromEvent = require_parse.normalizeHotkeyFromEvent;
@@ -57,7 +64,8 @@ exports.normalizeKeyName = require_constants.normalizeKeyName;
 exports.normalizeRegisterableHotkey = require_parse.normalizeRegisterableHotkey;
 exports.parseHotkey = require_parse.parseHotkey;
 exports.parseKeyboardEvent = require_parse.parseKeyboardEvent;
+exports.parseRegisterableHotkey = require_parse.parseRegisterableHotkey;
 exports.rawHotkeyToParsedHotkey = require_parse.rawHotkeyToParsedHotkey;
-exports.resolveModifier = require_constants.resolveModifier;
+exports.resolveModifier = require_platform.resolveModifier;
 exports.toHotkeyRegistrationView = require_hotkey_manager.toHotkeyRegistrationView;
 exports.validateHotkey = require_validate.validateHotkey;

package/dist/index.d.cts

@@ -1,13 +1,18 @@
-import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult } from "./hotkey.cjs";
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, 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, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.cjs";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.cjs";
-import { ConflictBehavior } from "./manager.utils.cjs";
+import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.cjs";
+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.cjs";
+import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.cjs";
+import { detectPlatform, resolveModifier } from "./platform.cjs";
+import { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.cjs";
+import { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.cjs";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.cjs";
+import { ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.cjs";
+import { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.cjs";
+import { HeldModifierOptions, matchesHeldModifiers } from "./hint.cjs";
 import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.cjs";
+import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, Target, createSequenceMatcher, getSequenceManager } from "./sequence-manager.cjs";
+import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.cjs";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.cjs";
-import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.cjs";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.cjs";
+import { HotkeyRecorderValidationContext, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.cjs";
 import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./hotkey-recorder.cjs";
-import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.cjs";
 import { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState } from "./hotkey-sequence-recorder.cjs";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.cjs";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, DisplayHotkey, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkey, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, HotkeySequenceRecorderValidationContext, 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, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, SingleModifierHotkey, Target, ThreeModifierHotkey, TwoModifierHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };

package/dist/index.d.ts

@@ -1,13 +1,18 @@
-import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult } from "./hotkey.js";
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, 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, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
-import { ConflictBehavior } from "./manager.utils.js";
+import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.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 { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.js";
+import { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
+import { ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
+import { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, Target, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
+import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
-import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { HotkeyRecorderValidationContext, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.js";
 import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./hotkey-recorder.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState } from "./hotkey-sequence-recorder.js";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
-export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, DisplayHotkey, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkey, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, HotkeySequenceRecorderValidationContext, 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, RegisterableHotkey, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, SingleModifierHotkey, Target, ThreeModifierHotkey, TwoModifierHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };

package/dist/index.js

@@ -1,12 +1,16 @@
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, 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, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.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 { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
 import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
-import { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
+import { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
+import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
+import { findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
 import { HotkeySequenceRecorder } from "./hotkey-sequence-recorder.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, SequenceManager, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
-import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
 
-export { ALL_KEYS, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, HotkeySequenceRecorder, 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, SequenceManager, WINDOWS_MODIFIER_LABELS, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, HotkeySequenceRecorder, 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, SequenceManager, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey, resolveModifier, toHotkeyRegistrationView, validateHotkey };

package/dist/key-state-tracker.cjs

@@ -47,8 +47,7 @@ function getDefaultKeyStateTrackerState() {
 */
 var KeyStateTracker = class KeyStateTracker {
 	static #instance = null;
-	#heldKeysSet = /* @__PURE__ */ new Set();
-	#heldCodesMap = /* @__PURE__ */ new Map();
+	#heldEntries = /* @__PURE__ */ new Map();
 	#keydownListener = null;
 	#keyupListener = null;
 	#blurListener = null;
@@ -79,44 +78,46 @@ var KeyStateTracker = class KeyStateTracker {
 		if (typeof document === "undefined") return;
 		this.#keydownListener = (event) => {
 			const key = require_constants.normalizeKeyName(event.key);
-			if (!this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.add(key);
-				this.#heldCodesMap.set(key, event.code);
+			const identity = event.code || `key:${key}`;
+			if (!this.#heldEntries.has(identity)) {
+				this.#heldEntries.set(identity, {
+					key,
+					code: event.code
+				});
 				this.#syncState();
 			}
 		};
 		this.#keyupListener = (event) => {
 			const key = require_constants.normalizeKeyName(event.key);
-			if (this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.delete(key);
-				this.#heldCodesMap.delete(key);
+			const identity = event.code || `key:${key}`;
+			this.#heldEntries.delete(identity);
+			if (!event.code) {
+				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
 			if (require_constants.MODIFIER_KEYS.has(key)) {
-				for (const heldKey of this.#heldKeysSet) if (!require_constants.MODIFIER_KEYS.has(heldKey)) {
-					this.#heldKeysSet.delete(heldKey);
-					this.#heldCodesMap.delete(heldKey);
-				}
+				for (const [entryIdentity, entry] of this.#heldEntries) if (!require_constants.MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#syncState();
 		};
 		this.#blurListener = () => {
-			if (this.#heldKeysSet.size > 0) {
-				this.#heldKeysSet.clear();
-				this.#heldCodesMap.clear();
+			if (this.#heldEntries.size > 0) {
+				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		document.addEventListener("keydown", this.#keydownListener);
-		document.addEventListener("keyup", this.#keyupListener);
+		document.addEventListener("keydown", this.#keydownListener, true);
+		document.addEventListener("keyup", this.#keyupListener, true);
 		window.addEventListener("blur", this.#blurListener);
 	}
 	/**
 	* Syncs the internal Set to the Store state.
 	*/
 	#syncState() {
+		const heldKeys = Array.from(new Set(Array.from(this.#heldEntries.values(), (entry) => entry.key)));
+		const heldCodes = Object.fromEntries(Array.from(this.#heldEntries.values(), (entry) => [entry.key, entry.code]));
 		this.store.setState(() => ({
-			heldKeys: Array.from(this.#heldKeysSet),
-			heldCodes: Object.fromEntries(this.#heldCodesMap)
+			heldKeys,
+			heldCodes
 		}));
 	}
 	/**
@@ -125,11 +126,11 @@ var KeyStateTracker = class KeyStateTracker {
 	#removeListeners() {
 		if (typeof document === "undefined") return;
 		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener);
+			document.removeEventListener("keydown", this.#keydownListener, true);
 			this.#keydownListener = null;
 		}
 		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener);
+			document.removeEventListener("keyup", this.#keyupListener, true);
 			this.#keyupListener = null;
 		}
 		if (this.#blurListener) {
@@ -153,7 +154,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	isKeyHeld(key) {
 		const normalizedKey = require_constants.normalizeKeyName(key);
-		return this.#heldKeysSet.has(normalizedKey);
+		return Array.from(this.#heldEntries.values()).some((entry) => entry.key === normalizedKey);
 	}
 	/**
 	* Checks if any of the given keys are currently held.
@@ -178,8 +179,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	destroy() {
 		this.#removeListeners();
-		this.#heldKeysSet.clear();
-		this.#heldCodesMap.clear();
+		this.#heldEntries.clear();
 		this.store.setState(() => getDefaultKeyStateTrackerState());
 	}
 };

package/dist/key-state-tracker.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"key-state-tracker.cjs","names":["#instance","Store","#setupListeners","#keydownListener","normalizeKeyName","#heldKeysSet","#heldCodesMap","#syncState","#keyupListener","MODIFIER_KEYS","#blurListener","#removeListeners"],"sources":["../src/key-state-tracker.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { MODIFIER_KEYS, normalizeKeyName } from './constants'\n\n/**\n * State interface for the KeyStateTracker.\n */\nexport interface KeyStateTrackerState {\n  /**\n   * Array of currently held key names (normalized, e.g. \"Control\", \"A\").\n   */\n  heldKeys: Array<string>\n  /**\n   * Map from normalized key name to the physical `event.code` (e.g. \"KeyA\", \"ShiftLeft\").\n   * Useful for debugging which physical key was pressed.\n   */\n  heldCodes: Record<string, string>\n}\n\n/**\n * Returns the default state for KeyStateTracker.\n */\nfunction getDefaultKeyStateTrackerState(): KeyStateTrackerState {\n  return {\n    heldKeys: [],\n    heldCodes: {},\n  }\n}\n\n/**\n * Singleton tracker for currently held keyboard keys.\n *\n * This class maintains a list of all keys currently being pressed,\n * which is useful for:\n * - Displaying currently held keys to users\n * - Custom shortcut recording for rebinding\n * - Complex chord detection\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `tracker.store.state` when using the class directly\n * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state\n *\n * @example\n * ```ts\n * const tracker = KeyStateTracker.getInstance()\n *\n * // Access state directly\n * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = tracker.store.subscribe(() => {\n *   console.log('Currently held:', tracker.store.state.heldKeys)\n * })\n *\n * // Check current state\n * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']\n * console.log(tracker.isKeyHeld('Control')) // true\n *\n * // Cleanup\n * unsubscribe()\n * ```\n */\nexport class KeyStateTracker {\n  static #instance: KeyStateTracker | null = null\n\n  /**\n   * The TanStack Store instance containing the tracker state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<KeyStateTrackerState> = new Store(\n    getDefaultKeyStateTrackerState(),\n  )\n\n  #heldKeysSet: Set<string> = new Set()\n  #heldCodesMap: Map<string, string> = new Map()\n  #keydownListener: ((event: KeyboardEvent) => void) | null = null\n  #keyupListener: ((event: KeyboardEvent) => void) | null = null\n  #blurListener: (() => void) | null = null\n\n  private constructor() {\n    this.#setupListeners()\n  }\n\n  /**\n   * Gets the singleton instance of KeyStateTracker.\n   */\n  static getInstance(): KeyStateTracker {\n    if (!KeyStateTracker.#instance) {\n      KeyStateTracker.#instance = new KeyStateTracker()\n    }\n    return KeyStateTracker.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (KeyStateTracker.#instance) {\n      KeyStateTracker.#instance.destroy()\n      KeyStateTracker.#instance = null\n    }\n  }\n\n  /**\n   * Sets up the keyboard event listeners.\n   */\n  #setupListeners(): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    this.#keydownListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      if (!this.#heldKeysSet.has(key)) {\n        this.#heldKeysSet.add(key)\n        this.#heldCodesMap.set(key, event.code)\n        this.#syncState()\n      }\n    }\n\n    this.#keyupListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      if (this.#heldKeysSet.has(key)) {\n        this.#heldKeysSet.delete(key)\n        this.#heldCodesMap.delete(key)\n      }\n\n      // When a modifier key is released, clear any non-modifier keys still\n      // marked as held. On macOS, the OS intercepts modifier+key combos\n      // (e.g. Cmd+S) and swallows the keyup event for the non-modifier key,\n      // leaving it permanently stuck in the held set.\n      if (MODIFIER_KEYS.has(key)) {\n        for (const heldKey of this.#heldKeysSet) {\n          if (!MODIFIER_KEYS.has(heldKey)) {\n            this.#heldKeysSet.delete(heldKey)\n            this.#heldCodesMap.delete(heldKey)\n          }\n        }\n      }\n\n      this.#syncState()\n    }\n\n    // Clear all keys when window loses focus (keys might be released while not focused)\n    this.#blurListener = () => {\n      if (this.#heldKeysSet.size > 0) {\n        this.#heldKeysSet.clear()\n        this.#heldCodesMap.clear()\n        this.#syncState()\n      }\n    }\n\n    document.addEventListener('keydown', this.#keydownListener)\n    document.addEventListener('keyup', this.#keyupListener)\n    window.addEventListener('blur', this.#blurListener)\n  }\n\n  /**\n   * Syncs the internal Set to the Store state.\n   */\n  #syncState(): void {\n    this.store.setState(() => ({\n      heldKeys: Array.from(this.#heldKeysSet),\n      heldCodes: Object.fromEntries(this.#heldCodesMap),\n    }))\n  }\n\n  /**\n   * Removes the keyboard event listeners.\n   */\n  #removeListeners(): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    if (this.#keydownListener) {\n      document.removeEventListener('keydown', this.#keydownListener)\n      this.#keydownListener = null\n    }\n\n    if (this.#keyupListener) {\n      document.removeEventListener('keyup', this.#keyupListener)\n      this.#keyupListener = null\n    }\n\n    if (this.#blurListener) {\n      window.removeEventListener('blur', this.#blurListener)\n      this.#blurListener = null\n    }\n  }\n\n  /**\n   * Gets an array of currently held key names.\n   *\n   * @returns Array of key names currently being pressed\n   */\n  getHeldKeys(): Array<string> {\n    return this.store.state.heldKeys\n  }\n\n  /**\n   * Checks if a specific key is currently being held.\n   *\n   * @param key - The key name to check (case-insensitive)\n   * @returns True if the key is currently held\n   */\n  isKeyHeld(key: string): boolean {\n    const normalizedKey = normalizeKeyName(key)\n    return this.#heldKeysSet.has(normalizedKey)\n  }\n\n  /**\n   * Checks if any of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if any of the keys are currently held\n   */\n  isAnyKeyHeld(keys: Array<string>): boolean {\n    return keys.some((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Checks if all of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if all of the keys are currently held\n   */\n  areAllKeysHeld(keys: Array<string>): boolean {\n    return keys.every((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Destroys the tracker and removes all listeners.\n   */\n  destroy(): void {\n    this.#removeListeners()\n    this.#heldKeysSet.clear()\n    this.#heldCodesMap.clear()\n    this.store.setState(() => getDefaultKeyStateTrackerState())\n  }\n}\n\n/**\n * Gets the singleton KeyStateTracker instance.\n * Convenience function for accessing the tracker.\n */\nexport function getKeyStateTracker(): KeyStateTracker {\n  return KeyStateTracker.getInstance()\n}\n"],"mappings":";;;;;;;AAqBA,SAAS,iCAAuD;AAC9D,QAAO;EACL,UAAU,EAAE;EACZ,WAAW,EAAE;EACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCH,IAAa,kBAAb,MAAa,gBAAgB;CAC3B,QAAOA,WAAoC;CAU3C,+BAA4B,IAAI,KAAK;CACrC,gCAAqC,IAAI,KAAK;CAC9C,mBAA4D;CAC5D,iBAA0D;CAC1D,gBAAqC;CAErC,AAAQ,cAAc;eAVwB,IAAIC,sBAChD,gCAAgC,CACjC;AASC,QAAKC,gBAAiB;;;;;CAMxB,OAAO,cAA+B;AACpC,MAAI,CAAC,iBAAgBF,SACnB,kBAAgBA,WAAY,IAAI,iBAAiB;AAEnD,SAAO,iBAAgBA;;;;;CAMzB,OAAO,gBAAsB;AAC3B,MAAI,iBAAgBA,UAAW;AAC7B,oBAAgBA,SAAU,SAAS;AACnC,oBAAgBA,WAAY;;;;;;CAOhC,kBAAwB;AACtB,MAAI,OAAO,aAAa,YACtB;AAGF,QAAKG,mBAAoB,UAAyB;GAChD,MAAM,MAAMC,mCAAiB,MAAM,IAAI;AACvC,OAAI,CAAC,MAAKC,YAAa,IAAI,IAAI,EAAE;AAC/B,UAAKA,YAAa,IAAI,IAAI;AAC1B,UAAKC,aAAc,IAAI,KAAK,MAAM,KAAK;AACvC,UAAKC,WAAY;;;AAIrB,QAAKC,iBAAkB,UAAyB;GAC9C,MAAM,MAAMJ,mCAAiB,MAAM,IAAI;AACvC,OAAI,MAAKC,YAAa,IAAI,IAAI,EAAE;AAC9B,UAAKA,YAAa,OAAO,IAAI;AAC7B,UAAKC,aAAc,OAAO,IAAI;;AAOhC,OAAIG,gCAAc,IAAI,IAAI,EACxB;SAAK,MAAM,WAAW,MAAKJ,YACzB,KAAI,CAACI,gCAAc,IAAI,QAAQ,EAAE;AAC/B,WAAKJ,YAAa,OAAO,QAAQ;AACjC,WAAKC,aAAc,OAAO,QAAQ;;;AAKxC,SAAKC,WAAY;;AAInB,QAAKG,qBAAsB;AACzB,OAAI,MAAKL,YAAa,OAAO,GAAG;AAC9B,UAAKA,YAAa,OAAO;AACzB,UAAKC,aAAc,OAAO;AAC1B,UAAKC,WAAY;;;AAIrB,WAAS,iBAAiB,WAAW,MAAKJ,gBAAiB;AAC3D,WAAS,iBAAiB,SAAS,MAAKK,cAAe;AACvD,SAAO,iBAAiB,QAAQ,MAAKE,aAAc;;;;;CAMrD,aAAmB;AACjB,OAAK,MAAM,gBAAgB;GACzB,UAAU,MAAM,KAAK,MAAKL,YAAa;GACvC,WAAW,OAAO,YAAY,MAAKC,aAAc;GAClD,EAAE;;;;;CAML,mBAAyB;AACvB,MAAI,OAAO,aAAa,YACtB;AAGF,MAAI,MAAKH,iBAAkB;AACzB,YAAS,oBAAoB,WAAW,MAAKA,gBAAiB;AAC9D,SAAKA,kBAAmB;;AAG1B,MAAI,MAAKK,eAAgB;AACvB,YAAS,oBAAoB,SAAS,MAAKA,cAAe;AAC1D,SAAKA,gBAAiB;;AAGxB,MAAI,MAAKE,cAAe;AACtB,UAAO,oBAAoB,QAAQ,MAAKA,aAAc;AACtD,SAAKA,eAAgB;;;;;;;;CASzB,cAA6B;AAC3B,SAAO,KAAK,MAAM,MAAM;;;;;;;;CAS1B,UAAU,KAAsB;EAC9B,MAAM,gBAAgBN,mCAAiB,IAAI;AAC3C,SAAO,MAAKC,YAAa,IAAI,cAAc;;;;;;;;CAS7C,aAAa,MAA8B;AACzC,SAAO,KAAK,MAAM,QAAQ,KAAK,UAAU,IAAI,CAAC;;;;;;;;CAShD,eAAe,MAA8B;AAC3C,SAAO,KAAK,OAAO,QAAQ,KAAK,UAAU,IAAI,CAAC;;;;;CAMjD,UAAgB;AACd,QAAKM,iBAAkB;AACvB,QAAKN,YAAa,OAAO;AACzB,QAAKC,aAAc,OAAO;AAC1B,OAAK,MAAM,eAAe,gCAAgC,CAAC;;;;;;;AAQ/D,SAAgB,qBAAsC;AACpD,QAAO,gBAAgB,aAAa"}
+{"version":3,"file":"key-state-tracker.cjs","names":["#instance","Store","#setupListeners","#keydownListener","normalizeKeyName","#heldEntries","#syncState","#keyupListener","MODIFIER_KEYS","#blurListener","#removeListeners"],"sources":["../src/key-state-tracker.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { MODIFIER_KEYS, normalizeKeyName } from './constants'\n\n/**\n * State interface for the KeyStateTracker.\n */\nexport interface KeyStateTrackerState {\n  /**\n   * Array of currently held key names (normalized, e.g. \"Control\", \"A\").\n   */\n  heldKeys: Array<string>\n  /**\n   * Map from normalized key name to the physical `event.code` (e.g. \"KeyA\", \"ShiftLeft\").\n   * Useful for debugging which physical key was pressed.\n   */\n  heldCodes: Record<string, string>\n}\n\n/**\n * Returns the default state for KeyStateTracker.\n */\nfunction getDefaultKeyStateTrackerState(): KeyStateTrackerState {\n  return {\n    heldKeys: [],\n    heldCodes: {},\n  }\n}\n\n/**\n * Singleton tracker for currently held keyboard keys.\n *\n * This class maintains a list of all keys currently being pressed,\n * which is useful for:\n * - Displaying currently held keys to users\n * - Custom shortcut recording for rebinding\n * - Complex chord detection\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `tracker.store.state` when using the class directly\n * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state\n *\n * @example\n * ```ts\n * const tracker = KeyStateTracker.getInstance()\n *\n * // Access state directly\n * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = tracker.store.subscribe(() => {\n *   console.log('Currently held:', tracker.store.state.heldKeys)\n * })\n *\n * // Check current state\n * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']\n * console.log(tracker.isKeyHeld('Control')) // true\n *\n * // Cleanup\n * unsubscribe()\n * ```\n */\nexport class KeyStateTracker {\n  static #instance: KeyStateTracker | null = null\n\n  /**\n   * The TanStack Store instance containing the tracker state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<KeyStateTrackerState> = new Store(\n    getDefaultKeyStateTrackerState(),\n  )\n\n  #heldEntries: Map<string, { key: string; code: string }> = new Map()\n  #keydownListener: ((event: KeyboardEvent) => void) | null = null\n  #keyupListener: ((event: KeyboardEvent) => void) | null = null\n  #blurListener: (() => void) | null = null\n\n  private constructor() {\n    this.#setupListeners()\n  }\n\n  /**\n   * Gets the singleton instance of KeyStateTracker.\n   */\n  static getInstance(): KeyStateTracker {\n    if (!KeyStateTracker.#instance) {\n      KeyStateTracker.#instance = new KeyStateTracker()\n    }\n    return KeyStateTracker.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (KeyStateTracker.#instance) {\n      KeyStateTracker.#instance.destroy()\n      KeyStateTracker.#instance = null\n    }\n  }\n\n  /**\n   * Sets up the keyboard event listeners.\n   */\n  #setupListeners(): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    this.#keydownListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      const identity = event.code || `key:${key}`\n      if (!this.#heldEntries.has(identity)) {\n        this.#heldEntries.set(identity, { key, code: event.code })\n        this.#syncState()\n      }\n    }\n\n    this.#keyupListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      const identity = event.code || `key:${key}`\n      this.#heldEntries.delete(identity)\n\n      // Code-less keyup events can only be paired by their logical key.\n      if (!event.code) {\n        for (const [entryIdentity, entry] of this.#heldEntries) {\n          if (entry.key === key) this.#heldEntries.delete(entryIdentity)\n        }\n      }\n\n      // When a modifier key is released, clear any non-modifier keys still\n      // marked as held. On macOS, the OS intercepts modifier+key combos\n      // (e.g. Cmd+S) and swallows the keyup event for the non-modifier key,\n      // leaving it permanently stuck in the held set.\n      if (MODIFIER_KEYS.has(key)) {\n        for (const [entryIdentity, entry] of this.#heldEntries) {\n          if (!MODIFIER_KEYS.has(entry.key)) {\n            this.#heldEntries.delete(entryIdentity)\n          }\n        }\n      }\n\n      this.#syncState()\n    }\n\n    // Clear all keys when window loses focus (keys might be released while not focused)\n    this.#blurListener = () => {\n      if (this.#heldEntries.size > 0) {\n        this.#heldEntries.clear()\n        this.#syncState()\n      }\n    }\n\n    document.addEventListener('keydown', this.#keydownListener, true)\n    document.addEventListener('keyup', this.#keyupListener, true)\n    window.addEventListener('blur', this.#blurListener)\n  }\n\n  /**\n   * Syncs the internal Set to the Store state.\n   */\n  #syncState(): void {\n    const heldKeys = Array.from(\n      new Set(Array.from(this.#heldEntries.values(), (entry) => entry.key)),\n    )\n    const heldCodes = Object.fromEntries(\n      Array.from(this.#heldEntries.values(), (entry) => [\n        entry.key,\n        entry.code,\n      ]),\n    )\n    this.store.setState(() => ({\n      heldKeys,\n      heldCodes,\n    }))\n  }\n\n  /**\n   * Removes the keyboard event listeners.\n   */\n  #removeListeners(): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    if (this.#keydownListener) {\n      document.removeEventListener('keydown', this.#keydownListener, true)\n      this.#keydownListener = null\n    }\n\n    if (this.#keyupListener) {\n      document.removeEventListener('keyup', this.#keyupListener, true)\n      this.#keyupListener = null\n    }\n\n    if (this.#blurListener) {\n      window.removeEventListener('blur', this.#blurListener)\n      this.#blurListener = null\n    }\n  }\n\n  /**\n   * Gets an array of currently held key names.\n   *\n   * @returns Array of key names currently being pressed\n   */\n  getHeldKeys(): Array<string> {\n    return this.store.state.heldKeys\n  }\n\n  /**\n   * Checks if a specific key is currently being held.\n   *\n   * @param key - The key name to check (case-insensitive)\n   * @returns True if the key is currently held\n   */\n  isKeyHeld(key: string): boolean {\n    const normalizedKey = normalizeKeyName(key)\n    return Array.from(this.#heldEntries.values()).some(\n      (entry) => entry.key === normalizedKey,\n    )\n  }\n\n  /**\n   * Checks if any of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if any of the keys are currently held\n   */\n  isAnyKeyHeld(keys: Array<string>): boolean {\n    return keys.some((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Checks if all of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if all of the keys are currently held\n   */\n  areAllKeysHeld(keys: Array<string>): boolean {\n    return keys.every((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Destroys the tracker and removes all listeners.\n   */\n  destroy(): void {\n    this.#removeListeners()\n    this.#heldEntries.clear()\n    this.store.setState(() => getDefaultKeyStateTrackerState())\n  }\n}\n\n/**\n * Gets the singleton KeyStateTracker instance.\n * Convenience function for accessing the tracker.\n */\nexport function getKeyStateTracker(): KeyStateTracker {\n  return KeyStateTracker.getInstance()\n}\n"],"mappings":"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"}

package/dist/key-state-tracker.js

@@ -47,8 +47,7 @@ function getDefaultKeyStateTrackerState() {
 */
 var KeyStateTracker = class KeyStateTracker {
 	static #instance = null;
-	#heldKeysSet = /* @__PURE__ */ new Set();
-	#heldCodesMap = /* @__PURE__ */ new Map();
+	#heldEntries = /* @__PURE__ */ new Map();
 	#keydownListener = null;
 	#keyupListener = null;
 	#blurListener = null;
@@ -79,44 +78,46 @@ var KeyStateTracker = class KeyStateTracker {
 		if (typeof document === "undefined") return;
 		this.#keydownListener = (event) => {
 			const key = normalizeKeyName(event.key);
-			if (!this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.add(key);
-				this.#heldCodesMap.set(key, event.code);
+			const identity = event.code || `key:${key}`;
+			if (!this.#heldEntries.has(identity)) {
+				this.#heldEntries.set(identity, {
+					key,
+					code: event.code
+				});
 				this.#syncState();
 			}
 		};
 		this.#keyupListener = (event) => {
 			const key = normalizeKeyName(event.key);
-			if (this.#heldKeysSet.has(key)) {
-				this.#heldKeysSet.delete(key);
-				this.#heldCodesMap.delete(key);
+			const identity = event.code || `key:${key}`;
+			this.#heldEntries.delete(identity);
+			if (!event.code) {
+				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
 			if (MODIFIER_KEYS.has(key)) {
-				for (const heldKey of this.#heldKeysSet) if (!MODIFIER_KEYS.has(heldKey)) {
-					this.#heldKeysSet.delete(heldKey);
-					this.#heldCodesMap.delete(heldKey);
-				}
+				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#syncState();
 		};
 		this.#blurListener = () => {
-			if (this.#heldKeysSet.size > 0) {
-				this.#heldKeysSet.clear();
-				this.#heldCodesMap.clear();
+			if (this.#heldEntries.size > 0) {
+				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		document.addEventListener("keydown", this.#keydownListener);
-		document.addEventListener("keyup", this.#keyupListener);
+		document.addEventListener("keydown", this.#keydownListener, true);
+		document.addEventListener("keyup", this.#keyupListener, true);
 		window.addEventListener("blur", this.#blurListener);
 	}
 	/**
 	* Syncs the internal Set to the Store state.
 	*/
 	#syncState() {
+		const heldKeys = Array.from(new Set(Array.from(this.#heldEntries.values(), (entry) => entry.key)));
+		const heldCodes = Object.fromEntries(Array.from(this.#heldEntries.values(), (entry) => [entry.key, entry.code]));
 		this.store.setState(() => ({
-			heldKeys: Array.from(this.#heldKeysSet),
-			heldCodes: Object.fromEntries(this.#heldCodesMap)
+			heldKeys,
+			heldCodes
 		}));
 	}
 	/**
@@ -125,11 +126,11 @@ var KeyStateTracker = class KeyStateTracker {
 	#removeListeners() {
 		if (typeof document === "undefined") return;
 		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener);
+			document.removeEventListener("keydown", this.#keydownListener, true);
 			this.#keydownListener = null;
 		}
 		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener);
+			document.removeEventListener("keyup", this.#keyupListener, true);
 			this.#keyupListener = null;
 		}
 		if (this.#blurListener) {
@@ -153,7 +154,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	isKeyHeld(key) {
 		const normalizedKey = normalizeKeyName(key);
-		return this.#heldKeysSet.has(normalizedKey);
+		return Array.from(this.#heldEntries.values()).some((entry) => entry.key === normalizedKey);
 	}
 	/**
 	* Checks if any of the given keys are currently held.
@@ -178,8 +179,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	destroy() {
 		this.#removeListeners();
-		this.#heldKeysSet.clear();
-		this.#heldCodesMap.clear();
+		this.#heldEntries.clear();
 		this.store.setState(() => getDefaultKeyStateTrackerState());
 	}
 };

package/dist/key-state-tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"key-state-tracker.js","names":["#instance","#setupListeners","#keydownListener","#heldKeysSet","#heldCodesMap","#syncState","#keyupListener","#blurListener","#removeListeners"],"sources":["../src/key-state-tracker.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { MODIFIER_KEYS, normalizeKeyName } from './constants'\n\n/**\n * State interface for the KeyStateTracker.\n */\nexport interface KeyStateTrackerState {\n  /**\n   * Array of currently held key names (normalized, e.g. \"Control\", \"A\").\n   */\n  heldKeys: Array<string>\n  /**\n   * Map from normalized key name to the physical `event.code` (e.g. \"KeyA\", \"ShiftLeft\").\n   * Useful for debugging which physical key was pressed.\n   */\n  heldCodes: Record<string, string>\n}\n\n/**\n * Returns the default state for KeyStateTracker.\n */\nfunction getDefaultKeyStateTrackerState(): KeyStateTrackerState {\n  return {\n    heldKeys: [],\n    heldCodes: {},\n  }\n}\n\n/**\n * Singleton tracker for currently held keyboard keys.\n *\n * This class maintains a list of all keys currently being pressed,\n * which is useful for:\n * - Displaying currently held keys to users\n * - Custom shortcut recording for rebinding\n * - Complex chord detection\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `tracker.store.state` when using the class directly\n * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state\n *\n * @example\n * ```ts\n * const tracker = KeyStateTracker.getInstance()\n *\n * // Access state directly\n * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = tracker.store.subscribe(() => {\n *   console.log('Currently held:', tracker.store.state.heldKeys)\n * })\n *\n * // Check current state\n * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']\n * console.log(tracker.isKeyHeld('Control')) // true\n *\n * // Cleanup\n * unsubscribe()\n * ```\n */\nexport class KeyStateTracker {\n  static #instance: KeyStateTracker | null = null\n\n  /**\n   * The TanStack Store instance containing the tracker state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<KeyStateTrackerState> = new Store(\n    getDefaultKeyStateTrackerState(),\n  )\n\n  #heldKeysSet: Set<string> = new Set()\n  #heldCodesMap: Map<string, string> = new Map()\n  #keydownListener: ((event: KeyboardEvent) => void) | null = null\n  #keyupListener: ((event: KeyboardEvent) => void) | null = null\n  #blurListener: (() => void) | null = null\n\n  private constructor() {\n    this.#setupListeners()\n  }\n\n  /**\n   * Gets the singleton instance of KeyStateTracker.\n   */\n  static getInstance(): KeyStateTracker {\n    if (!KeyStateTracker.#instance) {\n      KeyStateTracker.#instance = new KeyStateTracker()\n    }\n    return KeyStateTracker.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (KeyStateTracker.#instance) {\n      KeyStateTracker.#instance.destroy()\n      KeyStateTracker.#instance = null\n    }\n  }\n\n  /**\n   * Sets up the keyboard event listeners.\n   */\n  #setupListeners(): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    this.#keydownListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      if (!this.#heldKeysSet.has(key)) {\n        this.#heldKeysSet.add(key)\n        this.#heldCodesMap.set(key, event.code)\n        this.#syncState()\n      }\n    }\n\n    this.#keyupListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      if (this.#heldKeysSet.has(key)) {\n        this.#heldKeysSet.delete(key)\n        this.#heldCodesMap.delete(key)\n      }\n\n      // When a modifier key is released, clear any non-modifier keys still\n      // marked as held. On macOS, the OS intercepts modifier+key combos\n      // (e.g. Cmd+S) and swallows the keyup event for the non-modifier key,\n      // leaving it permanently stuck in the held set.\n      if (MODIFIER_KEYS.has(key)) {\n        for (const heldKey of this.#heldKeysSet) {\n          if (!MODIFIER_KEYS.has(heldKey)) {\n            this.#heldKeysSet.delete(heldKey)\n            this.#heldCodesMap.delete(heldKey)\n          }\n        }\n      }\n\n      this.#syncState()\n    }\n\n    // Clear all keys when window loses focus (keys might be released while not focused)\n    this.#blurListener = () => {\n      if (this.#heldKeysSet.size > 0) {\n        this.#heldKeysSet.clear()\n        this.#heldCodesMap.clear()\n        this.#syncState()\n      }\n    }\n\n    document.addEventListener('keydown', this.#keydownListener)\n    document.addEventListener('keyup', this.#keyupListener)\n    window.addEventListener('blur', this.#blurListener)\n  }\n\n  /**\n   * Syncs the internal Set to the Store state.\n   */\n  #syncState(): void {\n    this.store.setState(() => ({\n      heldKeys: Array.from(this.#heldKeysSet),\n      heldCodes: Object.fromEntries(this.#heldCodesMap),\n    }))\n  }\n\n  /**\n   * Removes the keyboard event listeners.\n   */\n  #removeListeners(): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    if (this.#keydownListener) {\n      document.removeEventListener('keydown', this.#keydownListener)\n      this.#keydownListener = null\n    }\n\n    if (this.#keyupListener) {\n      document.removeEventListener('keyup', this.#keyupListener)\n      this.#keyupListener = null\n    }\n\n    if (this.#blurListener) {\n      window.removeEventListener('blur', this.#blurListener)\n      this.#blurListener = null\n    }\n  }\n\n  /**\n   * Gets an array of currently held key names.\n   *\n   * @returns Array of key names currently being pressed\n   */\n  getHeldKeys(): Array<string> {\n    return this.store.state.heldKeys\n  }\n\n  /**\n   * Checks if a specific key is currently being held.\n   *\n   * @param key - The key name to check (case-insensitive)\n   * @returns True if the key is currently held\n   */\n  isKeyHeld(key: string): boolean {\n    const normalizedKey = normalizeKeyName(key)\n    return this.#heldKeysSet.has(normalizedKey)\n  }\n\n  /**\n   * Checks if any of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if any of the keys are currently held\n   */\n  isAnyKeyHeld(keys: Array<string>): boolean {\n    return keys.some((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Checks if all of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if all of the keys are currently held\n   */\n  areAllKeysHeld(keys: Array<string>): boolean {\n    return keys.every((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Destroys the tracker and removes all listeners.\n   */\n  destroy(): void {\n    this.#removeListeners()\n    this.#heldKeysSet.clear()\n    this.#heldCodesMap.clear()\n    this.store.setState(() => getDefaultKeyStateTrackerState())\n  }\n}\n\n/**\n * Gets the singleton KeyStateTracker instance.\n * Convenience function for accessing the tracker.\n */\nexport function getKeyStateTracker(): KeyStateTracker {\n  return KeyStateTracker.getInstance()\n}\n"],"mappings":"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"}
+{"version":3,"file":"key-state-tracker.js","names":["#instance","#setupListeners","#keydownListener","#heldEntries","#syncState","#keyupListener","#blurListener","#removeListeners"],"sources":["../src/key-state-tracker.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { MODIFIER_KEYS, normalizeKeyName } from './constants'\n\n/**\n * State interface for the KeyStateTracker.\n */\nexport interface KeyStateTrackerState {\n  /**\n   * Array of currently held key names (normalized, e.g. \"Control\", \"A\").\n   */\n  heldKeys: Array<string>\n  /**\n   * Map from normalized key name to the physical `event.code` (e.g. \"KeyA\", \"ShiftLeft\").\n   * Useful for debugging which physical key was pressed.\n   */\n  heldCodes: Record<string, string>\n}\n\n/**\n * Returns the default state for KeyStateTracker.\n */\nfunction getDefaultKeyStateTrackerState(): KeyStateTrackerState {\n  return {\n    heldKeys: [],\n    heldCodes: {},\n  }\n}\n\n/**\n * Singleton tracker for currently held keyboard keys.\n *\n * This class maintains a list of all keys currently being pressed,\n * which is useful for:\n * - Displaying currently held keys to users\n * - Custom shortcut recording for rebinding\n * - Complex chord detection\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `tracker.store.state` when using the class directly\n * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state\n *\n * @example\n * ```ts\n * const tracker = KeyStateTracker.getInstance()\n *\n * // Access state directly\n * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = tracker.store.subscribe(() => {\n *   console.log('Currently held:', tracker.store.state.heldKeys)\n * })\n *\n * // Check current state\n * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']\n * console.log(tracker.isKeyHeld('Control')) // true\n *\n * // Cleanup\n * unsubscribe()\n * ```\n */\nexport class KeyStateTracker {\n  static #instance: KeyStateTracker | null = null\n\n  /**\n   * The TanStack Store instance containing the tracker state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<KeyStateTrackerState> = new Store(\n    getDefaultKeyStateTrackerState(),\n  )\n\n  #heldEntries: Map<string, { key: string; code: string }> = new Map()\n  #keydownListener: ((event: KeyboardEvent) => void) | null = null\n  #keyupListener: ((event: KeyboardEvent) => void) | null = null\n  #blurListener: (() => void) | null = null\n\n  private constructor() {\n    this.#setupListeners()\n  }\n\n  /**\n   * Gets the singleton instance of KeyStateTracker.\n   */\n  static getInstance(): KeyStateTracker {\n    if (!KeyStateTracker.#instance) {\n      KeyStateTracker.#instance = new KeyStateTracker()\n    }\n    return KeyStateTracker.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (KeyStateTracker.#instance) {\n      KeyStateTracker.#instance.destroy()\n      KeyStateTracker.#instance = null\n    }\n  }\n\n  /**\n   * Sets up the keyboard event listeners.\n   */\n  #setupListeners(): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    this.#keydownListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      const identity = event.code || `key:${key}`\n      if (!this.#heldEntries.has(identity)) {\n        this.#heldEntries.set(identity, { key, code: event.code })\n        this.#syncState()\n      }\n    }\n\n    this.#keyupListener = (event: KeyboardEvent) => {\n      const key = normalizeKeyName(event.key)\n      const identity = event.code || `key:${key}`\n      this.#heldEntries.delete(identity)\n\n      // Code-less keyup events can only be paired by their logical key.\n      if (!event.code) {\n        for (const [entryIdentity, entry] of this.#heldEntries) {\n          if (entry.key === key) this.#heldEntries.delete(entryIdentity)\n        }\n      }\n\n      // When a modifier key is released, clear any non-modifier keys still\n      // marked as held. On macOS, the OS intercepts modifier+key combos\n      // (e.g. Cmd+S) and swallows the keyup event for the non-modifier key,\n      // leaving it permanently stuck in the held set.\n      if (MODIFIER_KEYS.has(key)) {\n        for (const [entryIdentity, entry] of this.#heldEntries) {\n          if (!MODIFIER_KEYS.has(entry.key)) {\n            this.#heldEntries.delete(entryIdentity)\n          }\n        }\n      }\n\n      this.#syncState()\n    }\n\n    // Clear all keys when window loses focus (keys might be released while not focused)\n    this.#blurListener = () => {\n      if (this.#heldEntries.size > 0) {\n        this.#heldEntries.clear()\n        this.#syncState()\n      }\n    }\n\n    document.addEventListener('keydown', this.#keydownListener, true)\n    document.addEventListener('keyup', this.#keyupListener, true)\n    window.addEventListener('blur', this.#blurListener)\n  }\n\n  /**\n   * Syncs the internal Set to the Store state.\n   */\n  #syncState(): void {\n    const heldKeys = Array.from(\n      new Set(Array.from(this.#heldEntries.values(), (entry) => entry.key)),\n    )\n    const heldCodes = Object.fromEntries(\n      Array.from(this.#heldEntries.values(), (entry) => [\n        entry.key,\n        entry.code,\n      ]),\n    )\n    this.store.setState(() => ({\n      heldKeys,\n      heldCodes,\n    }))\n  }\n\n  /**\n   * Removes the keyboard event listeners.\n   */\n  #removeListeners(): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    if (this.#keydownListener) {\n      document.removeEventListener('keydown', this.#keydownListener, true)\n      this.#keydownListener = null\n    }\n\n    if (this.#keyupListener) {\n      document.removeEventListener('keyup', this.#keyupListener, true)\n      this.#keyupListener = null\n    }\n\n    if (this.#blurListener) {\n      window.removeEventListener('blur', this.#blurListener)\n      this.#blurListener = null\n    }\n  }\n\n  /**\n   * Gets an array of currently held key names.\n   *\n   * @returns Array of key names currently being pressed\n   */\n  getHeldKeys(): Array<string> {\n    return this.store.state.heldKeys\n  }\n\n  /**\n   * Checks if a specific key is currently being held.\n   *\n   * @param key - The key name to check (case-insensitive)\n   * @returns True if the key is currently held\n   */\n  isKeyHeld(key: string): boolean {\n    const normalizedKey = normalizeKeyName(key)\n    return Array.from(this.#heldEntries.values()).some(\n      (entry) => entry.key === normalizedKey,\n    )\n  }\n\n  /**\n   * Checks if any of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if any of the keys are currently held\n   */\n  isAnyKeyHeld(keys: Array<string>): boolean {\n    return keys.some((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Checks if all of the given keys are currently held.\n   *\n   * @param keys - Array of key names to check\n   * @returns True if all of the keys are currently held\n   */\n  areAllKeysHeld(keys: Array<string>): boolean {\n    return keys.every((key) => this.isKeyHeld(key))\n  }\n\n  /**\n   * Destroys the tracker and removes all listeners.\n   */\n  destroy(): void {\n    this.#removeListeners()\n    this.#heldEntries.clear()\n    this.store.setState(() => getDefaultKeyStateTrackerState())\n  }\n}\n\n/**\n * Gets the singleton KeyStateTracker instance.\n * Convenience function for accessing the tracker.\n */\nexport function getKeyStateTracker(): KeyStateTracker {\n  return KeyStateTracker.getInstance()\n}\n"],"mappings":";;;;;;;AAqBA,SAAS,iCAAuD;AAC9D,QAAO;EACL,UAAU,EAAE;EACZ,WAAW,EAAE;EACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCH,IAAa,kBAAb,MAAa,gBAAgB;CAC3B,QAAOA,WAAoC;CAU3C,+BAA2D,IAAI,KAAK;CACpE,mBAA4D;CAC5D,iBAA0D;CAC1D,gBAAqC;CAErC,AAAQ,cAAc;eATwB,IAAI,MAChD,gCAAgC,CACjC;AAQC,QAAKC,gBAAiB;;;;;CAMxB,OAAO,cAA+B;AACpC,MAAI,CAAC,iBAAgBD,SACnB,kBAAgBA,WAAY,IAAI,iBAAiB;AAEnD,SAAO,iBAAgBA;;;;;CAMzB,OAAO,gBAAsB;AAC3B,MAAI,iBAAgBA,UAAW;AAC7B,oBAAgBA,SAAU,SAAS;AACnC,oBAAgBA,WAAY;;;;;;CAOhC,kBAAwB;AACtB,MAAI,OAAO,aAAa,YACtB;AAGF,QAAKE,mBAAoB,UAAyB;GAChD,MAAM,MAAM,iBAAiB,MAAM,IAAI;GACvC,MAAM,WAAW,MAAM,QAAQ,OAAO;AACtC,OAAI,CAAC,MAAKC,YAAa,IAAI,SAAS,EAAE;AACpC,UAAKA,YAAa,IAAI,UAAU;KAAE;KAAK,MAAM,MAAM;KAAM,CAAC;AAC1D,UAAKC,WAAY;;;AAIrB,QAAKC,iBAAkB,UAAyB;GAC9C,MAAM,MAAM,iBAAiB,MAAM,IAAI;GACvC,MAAM,WAAW,MAAM,QAAQ,OAAO;AACtC,SAAKF,YAAa,OAAO,SAAS;AAGlC,OAAI,CAAC,MAAM,MACT;SAAK,MAAM,CAAC,eAAe,UAAU,MAAKA,YACxC,KAAI,MAAM,QAAQ,IAAK,OAAKA,YAAa,OAAO,cAAc;;AAQlE,OAAI,cAAc,IAAI,IAAI,EACxB;SAAK,MAAM,CAAC,eAAe,UAAU,MAAKA,YACxC,KAAI,CAAC,cAAc,IAAI,MAAM,IAAI,CAC/B,OAAKA,YAAa,OAAO,cAAc;;AAK7C,SAAKC,WAAY;;AAInB,QAAKE,qBAAsB;AACzB,OAAI,MAAKH,YAAa,OAAO,GAAG;AAC9B,UAAKA,YAAa,OAAO;AACzB,UAAKC,WAAY;;;AAIrB,WAAS,iBAAiB,WAAW,MAAKF,iBAAkB,KAAK;AACjE,WAAS,iBAAiB,SAAS,MAAKG,eAAgB,KAAK;AAC7D,SAAO,iBAAiB,QAAQ,MAAKC,aAAc;;;;;CAMrD,aAAmB;EACjB,MAAM,WAAW,MAAM,KACrB,IAAI,IAAI,MAAM,KAAK,MAAKH,YAAa,QAAQ,GAAG,UAAU,MAAM,IAAI,CAAC,CACtE;EACD,MAAM,YAAY,OAAO,YACvB,MAAM,KAAK,MAAKA,YAAa,QAAQ,GAAG,UAAU,CAChD,MAAM,KACN,MAAM,KACP,CAAC,CACH;AACD,OAAK,MAAM,gBAAgB;GACzB;GACA;GACD,EAAE;;;;;CAML,mBAAyB;AACvB,MAAI,OAAO,aAAa,YACtB;AAGF,MAAI,MAAKD,iBAAkB;AACzB,YAAS,oBAAoB,WAAW,MAAKA,iBAAkB,KAAK;AACpE,SAAKA,kBAAmB;;AAG1B,MAAI,MAAKG,eAAgB;AACvB,YAAS,oBAAoB,SAAS,MAAKA,eAAgB,KAAK;AAChE,SAAKA,gBAAiB;;AAGxB,MAAI,MAAKC,cAAe;AACtB,UAAO,oBAAoB,QAAQ,MAAKA,aAAc;AACtD,SAAKA,eAAgB;;;;;;;;CASzB,cAA6B;AAC3B,SAAO,KAAK,MAAM,MAAM;;;;;;;;CAS1B,UAAU,KAAsB;EAC9B,MAAM,gBAAgB,iBAAiB,IAAI;AAC3C,SAAO,MAAM,KAAK,MAAKH,YAAa,QAAQ,CAAC,CAAC,MAC3C,UAAU,MAAM,QAAQ,cAC1B;;;;;;;;CASH,aAAa,MAA8B;AACzC,SAAO,KAAK,MAAM,QAAQ,KAAK,UAAU,IAAI,CAAC;;;;;;;;CAShD,eAAe,MAA8B;AAC3C,SAAO,KAAK,OAAO,QAAQ,KAAK,UAAU,IAAI,CAAC;;;;;CAMjD,UAAgB;AACd,QAAKI,iBAAkB;AACvB,QAAKJ,YAAa,OAAO;AACzB,OAAK,MAAM,eAAe,gCAAgC,CAAC;;;;;;;AAQ/D,SAAgB,qBAAsC;AACpD,QAAO,gBAAgB,aAAa"}

package/dist/key.types.d.cts

@@ -0,0 +1,82 @@
+import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.cjs";
+
+//#region src/key.types.d.ts
+/**
+ * All supported modifier key names, including aliases.
+ * - Control/Ctrl: The Control key
+ * - Shift: The Shift key
+ * - Alt/Option: The Alt key (Option on macOS)
+ * - Command/Cmd: The Command key (macOS only)
+ * - CommandOrControl/Mod: Command on macOS, Control on other platforms
+ */
+type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
+/**
+ * Canonical modifier names that map to KeyboardEvent properties.
+ */
+type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
+/**
+ * Letter keys A-Z (case-insensitive in matching).
+ */
+type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+/**
+ * Number keys 0-9.
+ */
+type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/**
+ * Function keys F1-F24, supported as both logical keys and physical codes.
+ */
+type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24';
+/**
+ * Navigation keys for cursor movement.
+ */
+type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
+/**
+ * Editing and special keys.
+ */
+type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
+/**
+ * Printable punctuation glyphs used in keyboard shortcuts. Matching uses the
+ * final KeyboardEvent.key glyph, independent of which layout produced it.
+ */
+type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`' | "'" | '+' | '?' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '_' | '{' | '}' | '|' | ':' | '"' | '<' | '>' | '~';
+/** Additional named logical keys, including media, browser, lock, and input-mode keys. */
+type NamedKey = (typeof SHARED_NAMED_KEYS)[number] | (typeof LOGICAL_ONLY_NAMED_KEYS)[number];
+/** Supported logical key names other than printable punctuation. */
+type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey | NamedKey;
+/**
+ * Supported physical KeyboardEvent.code names, independent of keyboard layout.
+ * Letter, digit, numpad, and sided modifier names use finite template unions.
+ * `Unidentified` is excluded because it cannot identify a physical key.
+ *
+ * @see https://www.w3.org/TR/uievents-code/
+ */
+type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | `${'Alt' | 'Control' | 'Meta' | 'Shift'}${'Left' | 'Right'}` | EditingKey | NavigationKey | FunctionKey | (typeof SHARED_NAMED_KEYS)[number] | 'Backquote' | 'Backslash' | 'BracketLeft' | 'BracketRight' | 'Comma' | 'Equal' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'Minus' | 'Period' | 'Quote' | 'Semicolon' | 'Slash' | `Lang${1 | 2 | 3 | 4 | 5}` | `Numpad${'Add' | 'Backspace' | 'Clear' | 'ClearEntry' | 'Comma' | 'Decimal' | 'Divide' | 'Enter' | 'Equal' | 'Hash' | 'MemoryAdd' | 'MemoryClear' | 'MemoryRecall' | 'MemoryStore' | 'MemorySubtract' | 'Multiply' | 'ParenLeft' | 'ParenRight' | 'Star' | 'Subtract'}` | 'LaunchApp1' | 'LaunchApp2' | 'MediaSelect' | 'Sleep' | 'Turbo' | 'Abort' | 'Resume' | 'Suspend';
+/**
+ * An explicit physical key token. All codes use brackets, including names such
+ * as `[Enter]` that also exist as logical keys. Invalid code names are rejected
+ * by TypeScript, and supported names are available in autocomplete.
+ */
+type PhysicalKey = `[${PhysicalKeyCode}]`;
+/** Supported logical key names, excluding bracketed physical-code syntax. */
+type LogicalKey = NonPunctuationKey | PunctuationKey;
+/** All supported logical keys and bracketed physical key tokens. */
+type Key = LogicalKey | PhysicalKey;
+/**
+ * Includes both modifier keys and regular keys.
+ */
+type IndividualKey = CanonicalModifier | Key;
+/** Keyboard event properties normalized for internal matching and recording. */
+interface NormalizedKeyboardEvent {
+  key: string;
+  code: string;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  altGraph: boolean;
+  location: number;
+  isComposing: boolean;
+}
+//#endregion
+export { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey };
+//# sourceMappingURL=key.types.d.cts.map