@tanstack/hotkeys 0.24.0 → 0.25.0

package/dist/format.d.ts

@@ -1,6 +1,5 @@
-import { CanonicalModifier } from "./key.types.js";
 import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
-//#region src/format.d.ts
+import { CanonicalModifier } from "./key.types.js";
 /**
  * Converts a parsed hotkey back to a string, with each platform modifier
  * spelled out, such as `Control+Shift+S`. A parsed chord returns a string, and
@@ -105,5 +104,4 @@ export interface FormatDisplayOptions {
   separatorToken?: string | null;
   /** Separator between sequence steps. Default: a space. */
   sequenceSeparator?: string;
-}
-//#endregion
+}

package/dist/format.js

@@ -1,11 +1,11 @@
+import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { warnServerPlatform } from "./_server.js";
 import { MODIFIER_ORDER, 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 { warnServerPlatform } from "./_server.js";
-import { detectPlatform } from "./platform.js";
-import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 import { normalizeHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/format.ts
+// src/format.ts
 function formatHotkey(parsed) {
 	return Array.isArray(parsed) ? parsed.map((step) => formatParsedChord(step)) : formatParsedChord(parsed);
 }
@@ -72,5 +72,4 @@ function formatKey(segment, platform, modifierSymbols, keySymbols, options) {
 	return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
 }
 
-//#endregion
 export { formatForDisplay, formatHotkey };

package/dist/hint.d.ts

@@ -1,5 +1,4 @@
 import { RegisterableHotkey } from "./hotkey.types.js";
-//#region src/hint.d.ts
 export interface HeldModifierOptions {
   /** Resolve Mod for this platform. Defaults to platform detection. */
   platform?: 'mac' | 'windows' | 'linux';
@@ -18,5 +17,4 @@ export interface HeldModifierOptions {
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
  * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
  */
-export declare function matchesHeldModifiers(hotkey: RegisterableHotkey | null | undefined, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;
-//#endregion
+export declare function matchesHeldModifiers(hotkey: RegisterableHotkey | null | undefined, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;

package/dist/hint.js

@@ -1,7 +1,7 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 import { isHotkeySequence, parseHotkey } from "./parse.js";
 
-//#region src/hint.ts
+// src/hint.ts
 /**
 * Returns whether held modifiers should reveal a shortcut hint.
 * By default, any nonempty subset of the binding's modifiers qualifies; an
@@ -24,5 +24,4 @@ function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
 	return held.length > 0 && held.every((key) => modifiers.includes(key)) && (!options.exact || held.length === modifiers.length);
 }
 
-//#endregion
 export { matchesHeldModifiers };

package/dist/hotkey-manager.d.ts

@@ -1,7 +1,6 @@
 import { Store } from "./_store.js";
-import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
-//#region src/hotkey-manager.d.ts
+import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 /** An element, document, or window that hotkeys can listen on. */
 export type Target = HTMLElement | Document | Window;
 /**
@@ -421,5 +420,4 @@ export declare class HotkeyManager {
  * Convenience function for accessing the manager.
  */
 export declare function getHotkeyManager(): HotkeyManager;
-//#endregion
 export type { ConflictBehavior };

package/dist/hotkey-manager.js

@@ -1,18 +1,18 @@
-import { normalizeKeyName } from "./constants.js";
-import { detectPlatform } from "./platform.js";
+import { closesNativeLayer, getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { isKeyNameShape, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
-import { formatHotkey } from "./format.js";
+import { managerRef } from "./_manager-ref.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
+import { isRecordingEvent } from "./_recording-guard.js";
 import { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { closesNativeLayer, getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { createStore } from "./_store.js";
 import { TargetListeners } from "./_target-listeners.js";
-import { managerRef } from "./_manager-ref.js";
-import { isRecordingEvent } from "./_recording-guard.js";
+import { normalizeKeyName } from "./constants.js";
+import { formatHotkey } from "./format.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/hotkey-manager.ts
+// src/hotkey-manager.ts
 /** Whether a registration can fire now. Without a manager, scopes don't apply. */
 function getRegistrationStatus(options, manager) {
 	if (options.enabled === false) return "disabled";
@@ -248,7 +248,7 @@ var HotkeyManager = class HotkeyManager {
 		if (scope === "global") return () => {};
 		const { exclusive } = options;
 		const allow = exclusive ? exclusive === true ? [] : exclusive.allow : null;
-		if (process.env.NODE_ENV !== "production" && allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`Exclusive hotkey scope '${scope}' is already active. Hotkeys from both activations will fire; give each a unique scope.`);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`[hotkeys] Exclusive scope '${scope}' is already active`);
 		const activation = {
 			scope,
 			parent: options.parent ?? "global",
@@ -391,8 +391,8 @@ var HotkeyManager = class HotkeyManager {
 		}
 		const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
 		if (!steps.every(chordHasKey)) return inactiveHandle(callback);
-		if (process.env.NODE_ENV !== "production") {
-			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`Unknown key '${key}' in '${formatForMessage(registration.hotkey)}'. Key names are case-sensitive, such as 'Escape' and 'F1', so this hotkey may never fire.`);
+		if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`[hotkeys] Unknown key '${key}' in '${formatForMessage(registration.hotkey)}' (names are case-sensitive)`);
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
@@ -840,5 +840,4 @@ function getHotkeyManager() {
 	return HotkeyManager.getInstance();
 }
 
-//#endregion
 export { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView };

package/dist/hotkey-recorder.d.ts

@@ -1,12 +1,24 @@
 import { Store } from "./_store.js";
-import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
 import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
-//#region src/hotkey-recorder.d.ts
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
 /** Event property used to record a binding. Physical codes are the default. */
 export type RecorderKeyMode = 'code' | 'key';
+/**
+ * Why the recorder rejected a key press or a recording:
+ *
+ * - `'alt-graph'`: AltGr typed a character, which physical recording can't
+ *   record. Record by key to accept characters.
+ * - `'missing-code'`: the event has no usable physical key code.
+ * - `'whitespace'`: the key is a whitespace character, which a hotkey can't
+ *   hold.
+ * - `'validation'`: your `validate` callback rejected the recording.
+ * - `'conflict'`: the recording conflicts with registered hotkeys.
+ */
+export type RecorderRejectionReason = 'alt-graph' | 'missing-code' | 'whitespace' | 'validation' | 'conflict';
 export interface RecorderRejection {
-  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
-  message: string;
+  reason: RecorderRejectionReason;
+  /** The message your `validate` callback returned, when it returned one. */
+  message?: string;
   /** The rejected chord or sequence, when one was recorded. */
   hotkey?: Hotkey;
   conflicts?: Array<HotkeyConflict>;
@@ -74,7 +86,7 @@ interface HotkeyRecorderBaseOptions extends RecorderOptions {
 export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Default: 1 */
   maxSteps?: 1;
-  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  /** Return true to accept, or false or a message to reject while staying in recording mode. The message is passed to `onReject`. */
   validate?: (hotkey: HotkeyChord, context: HotkeyChordRecorderValidationContext) => boolean | string;
   /** Callback when a chord is successfully recorded */
   onRecord: (hotkey: HotkeyChord) => void;
@@ -86,7 +98,7 @@ export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
 export interface HotkeySequenceRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Reaching it commits automatically. Use `Infinity` for no limit. */
   maxSteps: number;
-  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  /** Return true to accept, or false or a message to reject while staying in recording mode. The message is passed to `onReject`. */
   validate?: (hotkey: Hotkey, context: HotkeyRecorderValidationContext) => boolean | string;
   /** Callback when a hotkey is successfully recorded */
   onRecord: (hotkey: Hotkey) => void;
@@ -178,4 +190,4 @@ export declare class HotkeyRecorder {
    */
   destroy(): void;
 }
-//#endregion
+export {};

package/dist/hotkey-recorder.js

@@ -1,13 +1,13 @@
-import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
-import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { isTypingEvent } from "./_event-target.js";
-import { createStore } from "./_store.js";
+import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
+import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
+import { createStore } from "./_store.js";
 import { findHotkeyConflicts } from "./conflicts.js";
-import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
+import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/hotkey-recorder.ts
+// src/hotkey-recorder.ts
 const initialState = {
 	isRecording: false,
 	steps: [],
@@ -157,8 +157,7 @@ var HotkeyRecorder = class {
 			if (chord === null) return;
 			if (splitChordParts(chord).some((part) => !part.trim())) {
 				options.onReject?.({
-					reason: "invalid",
-					message: "Whitespace keys cannot be recorded",
+					reason: "whitespace",
 					hotkey: chord
 				});
 				return;
@@ -211,7 +210,7 @@ var HotkeyRecorder = class {
 		if (accepted !== void 0 && accepted !== true) {
 			rejectAndKeepRecording({
 				reason: "validation",
-				message: typeof accepted === "string" ? accepted : `This ${single ? "shortcut" : "sequence"} is not allowed.`,
+				...typeof accepted === "string" && { message: accepted },
 				hotkey
 			});
 			return;
@@ -225,7 +224,6 @@ var HotkeyRecorder = class {
 			if (conflicts.length) {
 				rejectAndKeepRecording({
 					reason: "conflict",
-					message: `This ${single ? "shortcut" : "sequence"} conflicts with a registered hotkey.`,
 					hotkey,
 					conflicts
 				});
@@ -286,5 +284,4 @@ var HotkeyRecorder = class {
 	}
 };
 
-//#endregion
 export { HotkeyRecorder };

package/dist/hotkey.types.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier, Key, LogicalKey } from "./key.types.js";
-//#region src/hotkey.types.d.ts
 /**
  * Single modifier + key combinations.
  * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
@@ -269,5 +268,4 @@ export interface HotkeyMeta {
  * - `'replace'` - Unregister the existing registration and register the new one
  * - `'allow'` - Allow multiple registrations without warning
  */
-export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
-//#endregion
+export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/key-state-tracker.d.ts

@@ -1,5 +1,4 @@
 import { Store } from "./_store.js";
-//#region src/key-state-tracker.d.ts
 /**
  * State interface for the KeyStateTracker.
  */
@@ -100,5 +99,4 @@ export declare class KeyStateTracker {
  * Gets the singleton KeyStateTracker instance.
  * Convenience function for accessing the tracker.
  */
-export declare function getKeyStateTracker(): KeyStateTracker;
-//#endregion
+export declare function getKeyStateTracker(): KeyStateTracker;

package/dist/key-state-tracker.js

@@ -1,7 +1,7 @@
-import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 import { createStore } from "./_store.js";
+import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 
-//#region src/key-state-tracker.ts
+// src/key-state-tracker.ts
 /**
 * Returns the default state for KeyStateTracker.
 */
@@ -252,5 +252,4 @@ function getKeyStateTracker() {
 	return KeyStateTracker.getInstance();
 }
 
-//#endregion
 export { KeyStateTracker, getKeyStateTracker };

package/dist/key.types.d.ts

@@ -1,5 +1,4 @@
 import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
-//#region src/key.types.d.ts
 /**
  * All supported modifier key names, including aliases.
  * - Control/Ctrl: The Control key
@@ -44,12 +43,13 @@ export type NamedKey = (typeof SHARED_NAMED_KEYS)[number] | (typeof LOGICAL_ONLY
 export 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.
+ * Letter, digit, and numpad names use finite template unions. Modifier codes
+ * such as `ShiftLeft` are excluded, because modifier-only hotkeys aren't
+ * supported. `Unidentified` is excluded because it cannot identify a physical key.
  *
  * @see https://www.w3.org/TR/uievents-code/
  */
-export 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';
+export type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | 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
@@ -75,5 +75,4 @@ export interface NormalizedKeyboardEvent {
   altGraph: boolean;
   location: number;
   isComposing: boolean;
-}
-//#endregion
+}

package/dist/match.d.ts

@@ -1,6 +1,5 @@
-import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { HotkeyPlatform } from "./platform.js";
-//#region src/match.d.ts
+import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
 export interface KeyboardEventMatch {
   matched: boolean;
   score: 0 | 1 | 2 | 3;
@@ -22,7 +21,8 @@ export interface KeyboardEventMatch {
  * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
  * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
  * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
- * In these cases, `event.code` is used to determine the physical key.
+ * In these cases, `event.code` is used to determine the physical key. An
+ * `'Unidentified'` key also falls back to `code`, except on letter keys.
  *
  * @param event - The KeyboardEvent to check
  * @param chord - The chord string or parsed chord to match against
@@ -129,5 +129,4 @@ export declare function createSequenceMatcher(sequence: RegisterableHotkeySequen
   match: (event: KeyboardEvent) => boolean;
   reset: () => void;
   getProgress: () => number;
-};
-//#endregion
+};

package/dist/match.js

@@ -1,12 +1,12 @@
-import { normalizeKeyName } from "./constants.js";
-import { detectPlatform } from "./platform.js";
 import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
-import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { chordHasKey } from "./_registration.js";
+import { normalizeKeyName } from "./constants.js";
+import { formatHotkey } from "./format.js";
+import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/match.ts
+// src/match.ts
 /**
 * Checks if a KeyboardEvent matches a hotkey.
 *
@@ -19,7 +19,8 @@ import { chordHasKey } from "./_registration.js";
 * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
 * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
 * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
-* In these cases, `event.code` is used to determine the physical key.
+* In these cases, `event.code` is used to determine the physical key. An
+* `'Unidentified'` key also falls back to `code`, except on letter keys.
 *
 * @param event - The KeyboardEvent to check
 * @param chord - The chord string or parsed chord to match against
@@ -193,5 +194,4 @@ function createSequenceMatcher(sequence, options = {}) {
 	};
 }
 
-//#endregion
 export { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent };

package/dist/parse.d.ts

@@ -1,6 +1,5 @@
-import { Key } from "./key.types.js";
 import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
-//#region src/parse.d.ts
+import { Key } from "./key.types.js";
 type Platform = 'mac' | 'windows' | 'linux';
 /** A chord in any form: a string, a chord object, or an already-parsed chord. */
 type AnyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
@@ -103,4 +102,4 @@ export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: Plat
  * ```
  */
 export declare function hasNonModifierKey(chord: HotkeyChord | ParsedHotkeyChord | (string & {}), platform?: Platform): boolean;
-//#endregion
+export {};

package/dist/parse.js

@@ -1,8 +1,9 @@
+import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { chordHasKey } from "./_registration.js";
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
-//#region src/parse.ts
+// src/parse.ts
 /** Builds a ParsedHotkeyChord, listing held modifiers in canonical order. */
 function toParsedChord(identity, ctrl, shift, alt, meta) {
 	const held = {
@@ -31,21 +32,14 @@ function simplifyHotkey(hotkey) {
 	return isHotkeySequence(hotkey) && hotkey.length === 1 ? hotkey[0] : hotkey;
 }
 function parseChordString(chord, platform) {
-	const parts = splitChordParts(chord);
+	const parts = splitChordParts(chord).map((part) => part.trim());
+	const key = normalizeKeyName(parts.pop());
 	const modifiers = /* @__PURE__ */ new Set();
-	let key = "";
-	for (let i = 0; i < parts.length; i++) {
-		const part = parts[i].trim();
-		if (i === parts.length - 1) key = normalizeKeyName(part);
-		else {
-			const alias = modifierAlias(part);
-			if (alias) {
-				const resolved = resolveModifier(alias, platform);
-				modifiers.add(resolved);
-			} else if (parts.length === 1) key = normalizeKeyName(part);
-		}
+	for (const part of parts) {
+		const alias = modifierAlias(part);
+		if (!alias) return toParsedChord({ key: "" }, false, false, false, false);
+		modifiers.add(resolveModifier(alias, platform));
 	}
-	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
 	const code = physicalCodeOf(key);
 	return toParsedChord(code !== void 0 ? { code } : { key }, modifiers.has("Control"), modifiers.has("Shift"), modifiers.has("Alt"), modifiers.has("Meta"));
 }
@@ -145,10 +139,7 @@ function parseKeyboardEvent(event, platform) {
 * ```
 */
 function hasNonModifierKey(chord, platform = detectPlatform()) {
-	const parsed = typeof chord === "string" ? parseChordString(chord, platform) : chord;
-	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
-	return !isModifierKey(parsed.key) && parsed.key.length > 0;
+	return chordHasKey(typeof chord === "string" ? parseChordString(chord, platform) : chord);
 }
 
-//#endregion
 export { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey };

package/dist/platform.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier } from "./key.types.js";
-//#region src/platform.d.ts
 /** A platform for resolving `Mod` and formatting labels. */
 export type HotkeyPlatform = 'mac' | 'windows' | 'linux';
 /**
@@ -49,5 +48,4 @@ export declare function detectPlatform(userAgent?: string | null): HotkeyPlatfor
  * resolveModifier('Control', 'mac') // 'Control' (unchanged)
  * ```
  */
-export declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
-//#endregion
+export declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;

package/dist/platform.js

@@ -1,6 +1,6 @@
 import { isServerRuntime } from "./_server.js";
 
-//#region src/platform.ts
+// src/platform.ts
 /**
 * Detects a platform from a user agent string, or from the browser's
 * `navigator` when called without one.
@@ -65,5 +65,4 @@ function resolveModifier(modifier, platform = detectPlatform()) {
 	return modifier;
 }
 
-//#endregion
 export { detectPlatform, resolveModifier };