@tanstack/hotkeys 0.9.0 → 0.10.0

package/dist/hotkey.types.d.cts

@@ -1,236 +0,0 @@
-import { CanonicalModifier, Key, LogicalKey } from "./key.types.cjs";
-
-//#region src/hotkey.types.d.ts
-/**
- * Single modifier + key combinations.
- * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
- *
- * The `Mod` modifier is platform-adaptive:
- * - **macOS**: Resolves to `Meta` (Command key ⌘)
- * - **Windows/Linux**: Resolves to `Control` (Ctrl key)
- *
- * 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.
- */
-type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
-/**
- * Two modifier + key combinations.
- *
- * **Platform-adaptive `Mod` combinations:**
- * - `Mod+Alt` and `Mod+Shift` are included (safe on all platforms)
- * - `Mod+Control` and `Mod+Meta` are excluded because they create duplicate modifiers:
- *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
- *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
- */
-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}`;
-/**
- * Three modifier + key combinations.
- *
- * **Platform-adaptive `Mod` combinations:**
- * - `Mod+Alt+Shift` is included (safe on all platforms)
- * - `Mod+Control+Shift` and `Mod+Shift+Meta` are excluded because they create duplicate modifiers:
- *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
- *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
- */
-type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
-/**
- * Four modifier + key combinations.
- *
- * Only the canonical `Control+Alt+Shift+Meta` combination is included.
- *
- * **Why no `Mod` combinations?**
- * Since `Mod` resolves to either `Control` (Windows/Linux) or `Meta` (macOS), any
- * four-modifier combination with `Mod` would create duplicate modifiers on one platform.
- * For example:
- * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
- * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
- */
-type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
-/**
- * A type-safe hotkey string.
- *
- * Provides autocomplete for:
- * - All single keys (letters, numbers, function keys, navigation, editing, punctuation)
- * - Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
- * - Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
- * - Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
- * - Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
- *
- * ## Modifier Names
- *
- * Use canonical modifier names:
- * - `Control` (not Ctrl) - The Control key
- * - `Alt` (not Option) - The Alt key (Option on macOS)
- * - `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
- * - `Shift` - The Shift key
- *
- * ## Platform-Adaptive `Mod` Modifier
- *
- * The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
- * to the "primary modifier" on each platform:
- *
- * - **macOS**: `Mod` → `Meta` (Command key ⌘)
- * - **Windows/Linux**: `Mod` → `Control` (Ctrl key)
- *
- * This enables cross-platform hotkey definitions that work correctly on all platforms
- * without platform-specific code. The `Mod` modifier is resolved at runtime based on
- * the detected platform.
- *
- * **When to use `Mod` vs platform-specific modifiers:**
- * - Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
- * - Use `Meta` or `Control` when you need platform-specific behavior
- * - Use `Mod` when you want your shortcuts to follow platform conventions automatically
- *
- * **Limitations:**
- * - `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
- *   modifiers on one platform)
- * - In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
- *
- * @example
- * ```ts
- * // Cross-platform shortcuts (recommended)
- * const save: Hotkey = 'Mod+S'           // Command+S on Mac, Ctrl+S on Windows/Linux
- * const saveAs: Hotkey = 'Mod+Shift+S'   // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
- * const comment: Hotkey = 'Mod+/'       // Command+/ on Mac, Ctrl+/ elsewhere
- *
- * // Platform-specific shortcuts
- * const macOnly: Hotkey = 'Meta+S'       // Command+S on Mac only
- * const windowsOnly: Hotkey = 'Control+S' // Ctrl+S on Windows/Linux only
- * ```
- */
-type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
-/** Resolved modifier flags shared by both parsed binding variants. */
-interface ParsedModifiers {
-  /** Whether Control is required. */
-  ctrl: boolean;
-  /** Whether Shift is required. */
-  shift: boolean;
-  /** Whether Alt is required. */
-  alt: boolean;
-  /** Whether Meta (Command) is required. */
-  meta: boolean;
-  /** Required modifiers in canonical order. */
-  modifiers: Array<CanonicalModifier>;
-}
-/**
- * A parsed binding 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
- */
-type ParsedHotkey = ParsedModifiers & ({
-  key: LogicalKey | (string & {});
-  code?: never;
-} | {
-  code: string;
-  key?: never;
-});
-/**
- * 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.
- *
- * The `mod` modifier is platform-adaptive: Command on macOS, Control on Windows/Linux.
- * Pass `platform` when converting to ParsedHotkey (e.g., via `options.platform`).
- *
- * @example
- * ```ts
- * useHotkey({ key: 'S', mod: true }, handler)             // Mod+S (cross-platform)
- * useHotkey({ key: 'S', ctrl: true }, handler)            // Control+S
- * useHotkey({ key: 'Escape' }, handler)                   // Escape (no modifiers)
- * useHotkey({ key: 'A', shift: true, meta: true }, handler) // Shift+Meta+A
- * useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
- * useHotkey({ code: 'KeyW', mod: true }, handler)           // Physical Mod+KeyW
- * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
- * ```
- */
-/** Modifier flags shared by logical-key and physical-code registrations. */
-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;
-}
-type RawHotkey = ({
-  key: LogicalKey | (string & {});
-  code?: never;
-} & RawModifiers) | ({
-  code: string;
-  key?: never;
-} & RawModifiers);
-/**
- * A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
- * Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
- */
-type RegisterableHotkey = Hotkey | RawHotkey;
-/**
- * Context passed to hotkey callbacks along with the keyboard event.
- */
-interface HotkeyCallbackContext {
-  /** The original hotkey string that was registered */
-  hotkey: Hotkey;
-  /** The parsed representation of the hotkey */
-  parsedHotkey: ParsedHotkey;
-}
-/**
- * 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
- *
- * @example
- * ```ts
- * const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
- *   console.log(`Hotkey ${hotkey} was pressed`)
- *   console.log(`Modifiers:`, parsedHotkey.modifiers)
- * }
- * ```
- */
-type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
-/**
- * Metadata for hotkey and sequence registrations.
- * Includes `name`, `description`, and `group` by default. Extend via declaration merging:
- *
- * @example
- * ```ts
- * declare module '@tanstack/hotkeys' {
- *   interface HotkeyMeta {
- *     category?: string
- *     icon?: string
- *   }
- * }
- * ```
- */
-interface HotkeyMeta {
-  /** Human-readable name for this hotkey (e.g., "Save Document") */
-  name?: string;
-  /** Description of what this hotkey does */
-  description?: string;
-  /** Optional display group. Does not affect matching or scope. */
-  group?: string;
-}
-/**
- * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
- *
- * - `'warn'` - Log a warning to the console but allow both registrations (default)
- * - `'error'` - Throw an error and prevent the new registration
- * - `'replace'` - Unregister the existing registration and register the new one
- * - `'allow'` - Allow multiple registrations without warning
- */
-type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
-//#endregion
-export { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey };
-//# sourceMappingURL=hotkey.types.d.cts.map

package/dist/index.cjs

@@ -1,71 +0,0 @@
-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');
-
-exports.ALL_KEYS = require_constants.ALL_KEYS;
-exports.DEFAULT_SEQUENCE_TIMEOUT = require_sequence_manager.DEFAULT_SEQUENCE_TIMEOUT;
-exports.EDITING_KEYS = require_constants.EDITING_KEYS;
-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_display_labels.KEY_DISPLAY_SYMBOLS;
-exports.KeyStateTracker = require_key_state_tracker.KeyStateTracker;
-exports.LETTER_KEYS = require_constants.LETTER_KEYS;
-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;
-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_display_labels.PUNCTUATION_KEY_DISPLAY_LABELS;
-exports.SequenceManager = require_sequence_manager.SequenceManager;
-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_platform.detectPlatform;
-exports.findHotkeyConflicts = require_conflicts.findHotkeyConflicts;
-exports.formatForDisplay = require_format.formatForDisplay;
-exports.formatHotkey = require_format.formatHotkey;
-exports.formatHotkeySequence = require_format.formatHotkeySequence;
-exports.formatWithLabels = require_format.formatWithLabels;
-exports.getHotkeyManager = require_hotkey_manager.getHotkeyManager;
-exports.getKeyStateTracker = require_key_state_tracker.getKeyStateTracker;
-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;
-exports.normalizeHotkeyFromParsed = require_parse.normalizeHotkeyFromParsed;
-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_platform.resolveModifier;
-exports.toHotkeyRegistrationView = require_hotkey_manager.toHotkeyRegistrationView;
-exports.validateHotkey = require_validate.validateHotkey;

package/dist/index.d.cts

@@ -1,18 +0,0 @@
-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 { HotkeyRecorderValidationContext, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.cjs";
-import { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState } from "./hotkey-recorder.cjs";
-import { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState } from "./hotkey-sequence-recorder.cjs";
-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/key-state-tracker.cjs

@@ -1,197 +0,0 @@
-const require_constants = require('./constants.cjs');
-let _tanstack_store = require("@tanstack/store");
-
-//#region src/key-state-tracker.ts
-/**
-* Returns the default state for KeyStateTracker.
-*/
-function getDefaultKeyStateTrackerState() {
-	return {
-		heldKeys: [],
-		heldCodes: {}
-	};
-}
-/**
-* Singleton tracker for currently held keyboard keys.
-*
-* This class maintains a list of all keys currently being pressed,
-* which is useful for:
-* - Displaying currently held keys to users
-* - Custom shortcut recording for rebinding
-* - Complex chord detection
-*
-* State Management:
-* - Uses TanStack Store for reactive state management
-* - State can be accessed via `tracker.store.state` when using the class directly
-* - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state
-*
-* @example
-* ```ts
-* const tracker = KeyStateTracker.getInstance()
-*
-* // Access state directly
-* console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']
-*
-* // Subscribe to changes with TanStack Store
-* const unsubscribe = tracker.store.subscribe(() => {
-*   console.log('Currently held:', tracker.store.state.heldKeys)
-* })
-*
-* // Check current state
-* console.log(tracker.getHeldKeys()) // ['Control', 'Shift']
-* console.log(tracker.isKeyHeld('Control')) // true
-*
-* // Cleanup
-* unsubscribe()
-* ```
-*/
-var KeyStateTracker = class KeyStateTracker {
-	static #instance = null;
-	#heldEntries = /* @__PURE__ */ new Map();
-	#keydownListener = null;
-	#keyupListener = null;
-	#blurListener = null;
-	constructor() {
-		this.store = new _tanstack_store.Store(getDefaultKeyStateTrackerState());
-		this.#setupListeners();
-	}
-	/**
-	* Gets the singleton instance of KeyStateTracker.
-	*/
-	static getInstance() {
-		if (!KeyStateTracker.#instance) KeyStateTracker.#instance = new KeyStateTracker();
-		return KeyStateTracker.#instance;
-	}
-	/**
-	* Resets the singleton instance. Useful for testing.
-	*/
-	static resetInstance() {
-		if (KeyStateTracker.#instance) {
-			KeyStateTracker.#instance.destroy();
-			KeyStateTracker.#instance = null;
-		}
-	}
-	/**
-	* Sets up the keyboard event listeners.
-	*/
-	#setupListeners() {
-		if (typeof document === "undefined") return;
-		this.#keydownListener = (event) => {
-			const key = require_constants.normalizeKeyName(event.key);
-			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);
-			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 [entryIdentity, entry] of this.#heldEntries) if (!require_constants.MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
-			}
-			this.#syncState();
-		};
-		this.#blurListener = () => {
-			if (this.#heldEntries.size > 0) {
-				this.#heldEntries.clear();
-				this.#syncState();
-			}
-		};
-		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,
-			heldCodes
-		}));
-	}
-	/**
-	* Removes the keyboard event listeners.
-	*/
-	#removeListeners() {
-		if (typeof document === "undefined") return;
-		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener, true);
-			this.#keydownListener = null;
-		}
-		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener, true);
-			this.#keyupListener = null;
-		}
-		if (this.#blurListener) {
-			window.removeEventListener("blur", this.#blurListener);
-			this.#blurListener = null;
-		}
-	}
-	/**
-	* Gets an array of currently held key names.
-	*
-	* @returns Array of key names currently being pressed
-	*/
-	getHeldKeys() {
-		return this.store.state.heldKeys;
-	}
-	/**
-	* Checks if a specific key is currently being held.
-	*
-	* @param key - The key name to check (case-insensitive)
-	* @returns True if the key is currently held
-	*/
-	isKeyHeld(key) {
-		const normalizedKey = require_constants.normalizeKeyName(key);
-		return Array.from(this.#heldEntries.values()).some((entry) => entry.key === normalizedKey);
-	}
-	/**
-	* Checks if any of the given keys are currently held.
-	*
-	* @param keys - Array of key names to check
-	* @returns True if any of the keys are currently held
-	*/
-	isAnyKeyHeld(keys) {
-		return keys.some((key) => this.isKeyHeld(key));
-	}
-	/**
-	* Checks if all of the given keys are currently held.
-	*
-	* @param keys - Array of key names to check
-	* @returns True if all of the keys are currently held
-	*/
-	areAllKeysHeld(keys) {
-		return keys.every((key) => this.isKeyHeld(key));
-	}
-	/**
-	* Destroys the tracker and removes all listeners.
-	*/
-	destroy() {
-		this.#removeListeners();
-		this.#heldEntries.clear();
-		this.store.setState(() => getDefaultKeyStateTrackerState());
-	}
-};
-/**
-* Gets the singleton KeyStateTracker instance.
-* Convenience function for accessing the tracker.
-*/
-function getKeyStateTracker() {
-	return KeyStateTracker.getInstance();
-}
-
-//#endregion
-exports.KeyStateTracker = KeyStateTracker;
-exports.getKeyStateTracker = getKeyStateTracker;
-//# sourceMappingURL=key-state-tracker.cjs.map

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

@@ -1 +0,0 @@
-{"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.d.cts

@@ -1,107 +0,0 @@
-import { Store } from "@tanstack/store";
-
-//#region src/key-state-tracker.d.ts
-/**
- * State interface for the KeyStateTracker.
- */
-interface KeyStateTrackerState {
-  /**
-   * Array of currently held key names (normalized, e.g. "Control", "A").
-   */
-  heldKeys: Array<string>;
-  /**
-   * Map from normalized key name to the physical `event.code` (e.g. "KeyA", "ShiftLeft").
-   * Useful for debugging which physical key was pressed.
-   */
-  heldCodes: Record<string, string>;
-}
-/**
- * Singleton tracker for currently held keyboard keys.
- *
- * This class maintains a list of all keys currently being pressed,
- * which is useful for:
- * - Displaying currently held keys to users
- * - Custom shortcut recording for rebinding
- * - Complex chord detection
- *
- * State Management:
- * - Uses TanStack Store for reactive state management
- * - State can be accessed via `tracker.store.state` when using the class directly
- * - When using framework adapters (React), use `useHeldKeys` and `useHeldKeyCodes` hooks for reactive state
- *
- * @example
- * ```ts
- * const tracker = KeyStateTracker.getInstance()
- *
- * // Access state directly
- * console.log(tracker.store.state.heldKeys) // ['Control', 'Shift']
- *
- * // Subscribe to changes with TanStack Store
- * const unsubscribe = tracker.store.subscribe(() => {
- *   console.log('Currently held:', tracker.store.state.heldKeys)
- * })
- *
- * // Check current state
- * console.log(tracker.getHeldKeys()) // ['Control', 'Shift']
- * console.log(tracker.isKeyHeld('Control')) // true
- *
- * // Cleanup
- * unsubscribe()
- * ```
- */
-declare class KeyStateTracker {
-  #private;
-  /**
-   * The TanStack Store instance containing the tracker state.
-   * Use this to subscribe to state changes or access current state.
-   */
-  readonly store: Store<KeyStateTrackerState>;
-  private constructor();
-  /**
-   * Gets the singleton instance of KeyStateTracker.
-   */
-  static getInstance(): KeyStateTracker;
-  /**
-   * Resets the singleton instance. Useful for testing.
-   */
-  static resetInstance(): void;
-  /**
-   * Gets an array of currently held key names.
-   *
-   * @returns Array of key names currently being pressed
-   */
-  getHeldKeys(): Array<string>;
-  /**
-   * Checks if a specific key is currently being held.
-   *
-   * @param key - The key name to check (case-insensitive)
-   * @returns True if the key is currently held
-   */
-  isKeyHeld(key: string): boolean;
-  /**
-   * Checks if any of the given keys are currently held.
-   *
-   * @param keys - Array of key names to check
-   * @returns True if any of the keys are currently held
-   */
-  isAnyKeyHeld(keys: Array<string>): boolean;
-  /**
-   * Checks if all of the given keys are currently held.
-   *
-   * @param keys - Array of key names to check
-   * @returns True if all of the keys are currently held
-   */
-  areAllKeysHeld(keys: Array<string>): boolean;
-  /**
-   * Destroys the tracker and removes all listeners.
-   */
-  destroy(): void;
-}
-/**
- * Gets the singleton KeyStateTracker instance.
- * Convenience function for accessing the tracker.
- */
-declare function getKeyStateTracker(): KeyStateTracker;
-//#endregion
-export { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker };
-//# sourceMappingURL=key-state-tracker.d.cts.map