@tanstack/hotkeys 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,13 +1,13 @@
 import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, 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, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.cjs";
-import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.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 { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.cjs";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.cjs";
 import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.cjs";
-import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.cjs";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.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, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, 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, validateHotkey };

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, 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, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { FormatKeyDebuggingOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.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 { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager } from "./hotkey-manager.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
-import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.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, FormatKeyDebuggingOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, LETTER_KEYS, LetterKey, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, NAVIGATION_KEYS, NUMBER_KEYS, NavigationKey, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, STANDARD_MODIFIER_LABELS, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, ValidationResult, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, validateHotkey };
+export { ALL_KEYS, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FunctionKey, HeldKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyManager, HotkeyOptions, HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRegistration, HotkeyRegistrationHandle, HotkeySequence, HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState, 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, validateHotkey };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, isSingleLetterKey, normalizeKeyName, resolveModifier } from "./constants.js";
-import { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
-import { formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels } from "./format.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 { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey } from "./parse.js";
+import { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
 import { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
 import { HotkeyManager, getHotkeyManager } from "./hotkey-manager.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
@@ -9,4 +9,4 @@ 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, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, SequenceManager, assertValidHotkey, checkHotkey, convertToModFormat, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, detectPlatform, formatForDisplay, formatHotkey, formatHotkeySequence, formatKeyForDebuggingDisplay, formatWithLabels, getHotkeyManager, getKeyStateTracker, getSequenceManager, hasNonModifierKey, isModifier, isModifierKey, isSingleLetterKey, keyboardEventToHotkey, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey, resolveModifier, 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, 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, validateHotkey };

package/dist/parse.cjs

@@ -87,39 +87,67 @@ function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatfor
 	};
 }
 /**
+* Serializes a parsed hotkey to the canonical string form used for registration
+* and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
+* otherwise full `Control+Alt+Shift+Meta` order.
+*/
+function normalizedHotkeyStringFromParsed(parsed, platform) {
+	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
+	const parts = [];
+	if (canUseMod) {
+		parts.push("Mod");
+		if (parsed.alt) parts.push("Alt");
+		if (parsed.shift) parts.push("Shift");
+	} else for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
+	parts.push(require_constants.normalizeKeyName(parsed.key));
+	return parts.join("+");
+}
+/**
 * Normalizes a hotkey string to its canonical form.
 *
-* The canonical form uses:
-* - Full modifier names (Control, Alt, Shift, Meta)
-* - Modifiers in order: Control+Alt+Shift+Meta
-* - Uppercase letters for single-character keys
-* - Proper casing for special keys (Escape, not escape)
+* - When `Mod` is allowed for the platform (Command on Mac without Control;
+*   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+*   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+* - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+* - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
 *
 * @param hotkey - The hotkey string to normalize
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
 * @returns The normalized hotkey string
 *
 * @example
 * ```ts
-* normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
-* normalizeHotkey('ctrl+a') // 'Control+A'
+* normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+* normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
 * normalizeHotkey('esc') // 'Escape'
 * ```
 */
 function normalizeHotkey(hotkey, platform = require_constants.detectPlatform()) {
-	const parsed = parseHotkey(hotkey, platform);
-	const parts = [];
-	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
-	return parts.join("+");
+	return normalizedHotkeyStringFromParsed(parseHotkey(hotkey, platform), platform);
+}
+/**
+* Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
+*/
+function normalizeHotkeyFromParsed(parsed, platform = require_constants.detectPlatform()) {
+	return normalizedHotkeyStringFromParsed(parsed, platform);
 }
 /**
-* Checks if a string represents a modifier key.
+* Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+* Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+*/
+function normalizeRegisterableHotkey(hotkey, platform = require_constants.detectPlatform()) {
+	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
+}
+/**
+* Checks if a string is a recognized modifier token (including aliases).
 *
-* @param key - The string to check
+* For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+* spellings like `OS` / `Win` match the same alias table.
+*
+* @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
 * @returns True if the string is a recognized modifier
 */
-function isModifier(key) {
+function isModifierKey(key) {
 	return key in require_constants.MODIFIER_ALIASES || key.toLowerCase() in require_constants.MODIFIER_ALIASES;
 }
 /**
@@ -157,56 +185,13 @@ function parseKeyboardEvent(event) {
 	};
 }
 /**
-* Converts a KeyboardEvent directly to a hotkey string.
-*
-* This is a convenience function that combines `parseKeyboardEvent()` and formatting.
-* The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
-* and is suitable for use with `useHotkey()` and other hotkey functions.
-*
-* @param event - The KeyboardEvent to convert
-* @param platform - The target platform (defaults to auto-detection)
-* @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   const hotkey = keyboardEventToHotkey(event)
-*   console.log(hotkey) // 'Control+Shift+S'
-*   useHotkey(hotkey, () => console.log('Shortcut triggered'))
-* })
-* ```
-*/
-function keyboardEventToHotkey(event) {
-	const parsed = parseKeyboardEvent(event);
-	const parts = [];
-	for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
-	return parts.join("+");
-}
-/**
-* Checks if a KeyboardEvent represents a modifier-only key press.
+* Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
 *
-* Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
-* that don't have an associated character or action key. This is useful
-* for filtering out modifier key presses when recording shortcuts.
-*
-* @param event - The KeyboardEvent to check
-* @returns True if the event represents a modifier-only key
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   if (isModifierKey(event)) {
-*     console.log('Modifier key pressed, waiting for action key...')
-*     return
-*   }
-*   // Process non-modifier key
-* })
-* ```
+* @param event - The keyboard event (typically `keydown`)
+* @param platform - Target platform for `Mod` eligibility
 */
-function isModifierKey(event) {
-	const key = event.key;
-	return key === "Control" || key === "Shift" || key === "Alt" || key === "Meta" || key === "Command" || key === "OS" || key === "Win";
+function normalizeHotkeyFromEvent(event, platform = require_constants.detectPlatform()) {
+	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -227,39 +212,16 @@ function isModifierKey(event) {
 */
 function hasNonModifierKey(hotkey, platform = require_constants.detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
-	return !isModifier(parsed.key) && parsed.key.length > 0;
-}
-/**
-* Converts a hotkey string to use 'Mod' format for portability.
-*
-* On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
-* This enables cross-platform hotkey definitions that work consistently.
-*
-* @param hotkey - The hotkey string to convert
-* @param platform - The target platform (defaults to auto-detection)
-* @returns The hotkey string with 'Mod' format applied
-*
-* @example
-* ```ts
-* convertToModFormat('Meta+S', 'mac') // 'Mod+S'
-* convertToModFormat('Control+S', 'windows') // 'Mod+S'
-* convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
-* ```
-*/
-function convertToModFormat(hotkey, platform = require_constants.detectPlatform()) {
-	const parsed = parseHotkey(hotkey, platform);
-	if (platform === "mac" && parsed.meta && !parsed.ctrl) return hotkey.split("+").map((part) => part === "Meta" ? "Mod" : part).join("+");
-	else if (platform !== "mac" && parsed.ctrl && !parsed.meta) return hotkey.split("+").map((part) => part === "Control" ? "Mod" : part).join("+");
-	return hotkey;
+	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
 
 //#endregion
-exports.convertToModFormat = convertToModFormat;
 exports.hasNonModifierKey = hasNonModifierKey;
-exports.isModifier = isModifier;
 exports.isModifierKey = isModifierKey;
-exports.keyboardEventToHotkey = keyboardEventToHotkey;
 exports.normalizeHotkey = normalizeHotkey;
+exports.normalizeHotkeyFromEvent = normalizeHotkeyFromEvent;
+exports.normalizeHotkeyFromParsed = normalizeHotkeyFromParsed;
+exports.normalizeRegisterableHotkey = normalizeRegisterableHotkey;
 exports.parseHotkey = parseHotkey;
 exports.parseKeyboardEvent = parseKeyboardEvent;
 exports.rawHotkeyToParsedHotkey = rawHotkeyToParsedHotkey;

package/dist/parse.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"parse.cjs","names":["detectPlatform","normalizeKeyName","MODIFIER_ALIASES","resolveModifier","MODIFIER_ORDER"],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  detectPlatform,\n  normalizeKeyName,\n  resolveModifier,\n} from './constants'\nimport type {\n  CanonicalModifier,\n  Hotkey,\n  Key,\n  ParsedHotkey,\n  RawHotkey,\n} from './hotkey'\n\n/**\n * Parses a hotkey string into its component parts.\n *\n * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey object with the key and modifier flags\n *\n * @example\n * ```ts\n * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }\n * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function parseHotkey(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  const parts = hotkey.split('+')\n  const modifiers: Set<CanonicalModifier> = new Set()\n  let key = ''\n\n  for (let i = 0; i < parts.length; i++) {\n    const part = parts[i]!.trim()\n\n    if (i === parts.length - 1) {\n      // Last part is always the key\n      key = normalizeKeyName(part)\n    } else {\n      // All other parts are modifiers\n      const alias =\n        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]\n\n      if (alias) {\n        const resolved = resolveModifier(alias, platform)\n        modifiers.add(resolved)\n      } else {\n        // Unknown modifier, treat as part of the key if it's the only part\n        // or ignore if there are more parts\n        if (parts.length === 1) {\n          key = normalizeKeyName(part)\n        }\n      }\n    }\n  }\n\n  // If no key was found (empty string), use the last part as-is\n  if (!key && parts.length > 0) {\n    key = normalizeKeyName(parts[parts.length - 1]!.trim())\n  }\n\n  return {\n    key,\n    ctrl: modifiers.has('Control'),\n    shift: modifiers.has('Shift'),\n    alt: modifiers.has('Alt'),\n    meta: modifiers.has('Meta'),\n    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),\n  }\n}\n\n/**\n * Converts a RawHotkey object to a ParsedHotkey.\n * Optional modifier booleans default to false; modifiers array is derived from them.\n * When `mod` is true, it is resolved to Control or Meta based on platform.\n *\n * @param raw - The raw hotkey object\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey suitable for matching and formatting\n *\n * @example\n * ```ts\n * rawHotkeyToParsedHotkey({ key: 'Escape' })\n * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')\n * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')\n * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function rawHotkeyToParsedHotkey(\n  raw: RawHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  let ctrl = raw.ctrl ?? false\n  const shift = raw.shift ?? false\n  const alt = raw.alt ?? false\n  let meta = raw.meta ?? false\n\n  if (raw.mod) {\n    const resolved = resolveModifier('Mod', platform)\n    if (resolved === 'Control') {\n      ctrl = true\n    } else {\n      meta = true\n    }\n  }\n\n  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {\n    switch (m) {\n      case 'Control':\n        return ctrl\n      case 'Shift':\n        return shift\n      case 'Alt':\n        return alt\n      case 'Meta':\n        return meta\n      default:\n        return false\n    }\n  })\n  return {\n    key: raw.key,\n    ctrl,\n    shift,\n    alt,\n    meta,\n    modifiers,\n  }\n}\n\n/**\n * Normalizes a hotkey string to its canonical form.\n *\n * The canonical form uses:\n * - Full modifier names (Control, Alt, Shift, Meta)\n * - Modifiers in order: Control+Alt+Shift+Meta\n * - Uppercase letters for single-character keys\n * - Proper casing for special keys (Escape, not escape)\n *\n * @param hotkey - The hotkey string to normalize\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns The normalized hotkey string\n *\n * @example\n * ```ts\n * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'\n * normalizeHotkey('ctrl+a') // 'Control+A'\n * normalizeHotkey('esc') // 'Escape'\n * ```\n */\nexport function normalizeHotkey(\n  hotkey: Key | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed = parseHotkey(hotkey, platform)\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Checks if a string represents a modifier key.\n *\n * @param key - The string to check\n * @returns True if the string is a recognized modifier\n */\nexport function isModifier(key: string): boolean {\n  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES\n}\n\n/**\n * Parses a KeyboardEvent into a ParsedHotkey object.\n *\n * This function extracts the key and modifier state from a keyboard event\n * and converts it into the same format used by `parseHotkey()`.\n *\n * @param event - The KeyboardEvent to parse\n * @param platform - The target platform for resolving modifiers (defaults to auto-detection)\n * @returns A ParsedHotkey object representing the keyboard event\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const parsed = parseKeyboardEvent(event)\n *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }\n * })\n * ```\n */\nexport function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {\n  const normalizedKey = normalizeKeyName(event.key)\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (event.ctrlKey) modifiers.push('Control')\n  if (event.altKey) modifiers.push('Alt')\n  if (event.shiftKey) modifiers.push('Shift')\n  if (event.metaKey) modifiers.push('Meta')\n\n  return {\n    key: normalizedKey,\n    ctrl: event.ctrlKey,\n    shift: event.shiftKey,\n    alt: event.altKey,\n    meta: event.metaKey,\n    modifiers,\n  }\n}\n\n/**\n * Converts a KeyboardEvent directly to a hotkey string.\n *\n * This is a convenience function that combines `parseKeyboardEvent()` and formatting.\n * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)\n * and is suitable for use with `useHotkey()` and other hotkey functions.\n *\n * @param event - The KeyboardEvent to convert\n * @param platform - The target platform (defaults to auto-detection)\n * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const hotkey = keyboardEventToHotkey(event)\n *   console.log(hotkey) // 'Control+Shift+S'\n *   useHotkey(hotkey, () => console.log('Shortcut triggered'))\n * })\n * ```\n */\nexport function keyboardEventToHotkey(event: KeyboardEvent): Hotkey {\n  const parsed = parseKeyboardEvent(event)\n\n  // Build hotkey string in canonical order (same as formatHotkey)\n  const parts: Array<string> = []\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Checks if a KeyboardEvent represents a modifier-only key press.\n *\n * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.\n * that don't have an associated character or action key. This is useful\n * for filtering out modifier key presses when recording shortcuts.\n *\n * @param event - The KeyboardEvent to check\n * @returns True if the event represents a modifier-only key\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (isModifierKey(event)) {\n *     console.log('Modifier key pressed, waiting for action key...')\n *     return\n *   }\n *   // Process non-modifier key\n * })\n * ```\n */\nexport function isModifierKey(event: KeyboardEvent): boolean {\n  const key = event.key\n  return (\n    key === 'Control' ||\n    key === 'Shift' ||\n    key === 'Alt' ||\n    key === 'Meta' ||\n    key === 'Command' ||\n    key === 'OS' ||\n    key === 'Win'\n  )\n}\n\n/**\n * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.\n *\n * This is useful for validating that a recorded hotkey is complete and not\n * just a combination of modifiers without an action key.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to check\n * @param platform - The target platform for parsing (defaults to auto-detection)\n * @returns True if the hotkey contains at least one non-modifier key\n *\n * @example\n * ```ts\n * hasNonModifierKey('Control+Shift+S') // true\n * hasNonModifierKey('Control+Shift') // false (no action key)\n * hasNonModifierKey(parseHotkey('Mod+A')) // true\n * ```\n */\nexport function hasNonModifierKey(\n  hotkey: Hotkey | ParsedHotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check if the key part is actually a modifier\n  const keyIsModifier = isModifier(parsed.key)\n\n  // A valid hotkey must have a non-modifier key\n  return !keyIsModifier && parsed.key.length > 0\n}\n\n/**\n * Converts a hotkey string to use 'Mod' format for portability.\n *\n * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.\n * This enables cross-platform hotkey definitions that work consistently.\n *\n * @param hotkey - The hotkey string to convert\n * @param platform - The target platform (defaults to auto-detection)\n * @returns The hotkey string with 'Mod' format applied\n *\n * @example\n * ```ts\n * convertToModFormat('Meta+S', 'mac') // 'Mod+S'\n * convertToModFormat('Control+S', 'windows') // 'Mod+S'\n * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)\n * ```\n */\nexport function convertToModFormat(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  const parsed = parseHotkey(hotkey, platform)\n\n  // Only convert if we have exactly one primary modifier\n  if (platform === 'mac' && parsed.meta && !parsed.ctrl) {\n    // Convert Meta to Mod on Mac\n    const parts = hotkey.split('+')\n    return parts\n      .map((part) => (part === 'Meta' ? 'Mod' : part))\n      .join('+') as Hotkey\n  } else if (platform !== 'mac' && parsed.ctrl && !parsed.meta) {\n    // Convert Control to Mod on Windows/Linux\n    const parts = hotkey.split('+')\n    return parts\n      .map((part) => (part === 'Control' ? 'Mod' : part))\n      .join('+') as Hotkey\n  }\n\n  // No conversion needed\n  return hotkey as Hotkey\n}\n"],"mappings":"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"}
+{"version":3,"file":"parse.cjs","names":["detectPlatform","normalizeKeyName","MODIFIER_ALIASES","resolveModifier","MODIFIER_ORDER"],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  detectPlatform,\n  normalizeKeyName,\n  resolveModifier,\n} from './constants'\nimport type {\n  CanonicalModifier,\n  Hotkey,\n  Key,\n  ParsedHotkey,\n  RawHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\n/**\n * Parses a hotkey string into its component parts.\n *\n * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey object with the key and modifier flags\n *\n * @example\n * ```ts\n * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }\n * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function parseHotkey(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  const parts = hotkey.split('+')\n  const modifiers: Set<CanonicalModifier> = new Set()\n  let key = ''\n\n  for (let i = 0; i < parts.length; i++) {\n    const part = parts[i]!.trim()\n\n    if (i === parts.length - 1) {\n      // Last part is always the key\n      key = normalizeKeyName(part)\n    } else {\n      // All other parts are modifiers\n      const alias =\n        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]\n\n      if (alias) {\n        const resolved = resolveModifier(alias, platform)\n        modifiers.add(resolved)\n      } else {\n        // Unknown modifier, treat as part of the key if it's the only part\n        // or ignore if there are more parts\n        if (parts.length === 1) {\n          key = normalizeKeyName(part)\n        }\n      }\n    }\n  }\n\n  // If no key was found (empty string), use the last part as-is\n  if (!key && parts.length > 0) {\n    key = normalizeKeyName(parts[parts.length - 1]!.trim())\n  }\n\n  return {\n    key,\n    ctrl: modifiers.has('Control'),\n    shift: modifiers.has('Shift'),\n    alt: modifiers.has('Alt'),\n    meta: modifiers.has('Meta'),\n    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),\n  }\n}\n\n/**\n * Converts a RawHotkey object to a ParsedHotkey.\n * Optional modifier booleans default to false; modifiers array is derived from them.\n * When `mod` is true, it is resolved to Control or Meta based on platform.\n *\n * @param raw - The raw hotkey object\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey suitable for matching and formatting\n *\n * @example\n * ```ts\n * rawHotkeyToParsedHotkey({ key: 'Escape' })\n * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')\n * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')\n * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function rawHotkeyToParsedHotkey(\n  raw: RawHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  let ctrl = raw.ctrl ?? false\n  const shift = raw.shift ?? false\n  const alt = raw.alt ?? false\n  let meta = raw.meta ?? false\n\n  if (raw.mod) {\n    const resolved = resolveModifier('Mod', platform)\n    if (resolved === 'Control') {\n      ctrl = true\n    } else {\n      meta = true\n    }\n  }\n\n  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {\n    switch (m) {\n      case 'Control':\n        return ctrl\n      case 'Shift':\n        return shift\n      case 'Alt':\n        return alt\n      case 'Meta':\n        return meta\n      default:\n        return false\n    }\n  })\n  return {\n    key: raw.key,\n    ctrl,\n    shift,\n    alt,\n    meta,\n    modifiers,\n  }\n}\n\n/**\n * Serializes a parsed hotkey to the canonical string form used for registration\n * and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;\n * otherwise full `Control+Alt+Shift+Meta` order.\n */\nfunction normalizedHotkeyStringFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey {\n  const canUseMod =\n    platform === 'mac'\n      ? parsed.meta && !parsed.ctrl\n      : parsed.ctrl && !parsed.meta\n\n  const parts: Array<string> = []\n\n  if (canUseMod) {\n    parts.push('Mod')\n    if (parsed.alt) {\n      parts.push('Alt')\n    }\n    if (parsed.shift) {\n      parts.push('Shift')\n    }\n  } else {\n    for (const modifier of MODIFIER_ORDER) {\n      if (parsed.modifiers.includes(modifier)) {\n        parts.push(modifier)\n      }\n    }\n  }\n\n  parts.push(normalizeKeyName(parsed.key))\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Normalizes a hotkey string to its canonical form.\n *\n * - When `Mod` is allowed for the platform (Command on Mac without Control;\n *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,\n *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).\n * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.\n * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).\n *\n * @param hotkey - The hotkey string to normalize\n * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)\n * @returns The normalized hotkey string\n *\n * @example\n * ```ts\n * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'\n * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'\n * normalizeHotkey('esc') // 'Escape'\n * ```\n */\nexport function normalizeHotkey(\n  hotkey: Key | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(\n    parseHotkey(hotkey, platform),\n    platform,\n  )\n}\n\n/**\n * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.\n */\nexport function normalizeHotkeyFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parsed, platform)\n}\n\n/**\n * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.\n * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.\n */\nexport function normalizeRegisterableHotkey(\n  hotkey: RegisterableHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return typeof hotkey === 'string'\n    ? normalizeHotkey(hotkey, platform)\n    : normalizeHotkeyFromParsed(\n        rawHotkeyToParsedHotkey(hotkey, platform),\n        platform,\n      )\n}\n\n/**\n * Checks if a string is a recognized modifier token (including aliases).\n *\n * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM\n * spellings like `OS` / `Win` match the same alias table.\n *\n * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)\n * @returns True if the string is a recognized modifier\n */\nexport function isModifierKey(\n  key: Key | (string & {}),\n): key is keyof typeof MODIFIER_ALIASES {\n  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES\n}\n\n/**\n * Parses a KeyboardEvent into a ParsedHotkey object.\n *\n * This function extracts the key and modifier state from a keyboard event\n * and converts it into the same format used by `parseHotkey()`.\n *\n * @param event - The KeyboardEvent to parse\n * @param platform - The target platform for resolving modifiers (defaults to auto-detection)\n * @returns A ParsedHotkey object representing the keyboard event\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const parsed = parseKeyboardEvent(event)\n *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }\n * })\n * ```\n */\nexport function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {\n  const normalizedKey = normalizeKeyName(event.key)\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (event.ctrlKey) modifiers.push('Control')\n  if (event.altKey) modifiers.push('Alt')\n  if (event.shiftKey) modifiers.push('Shift')\n  if (event.metaKey) modifiers.push('Meta')\n\n  return {\n    key: normalizedKey,\n    ctrl: event.ctrlKey,\n    shift: event.shiftKey,\n    alt: event.altKey,\n    meta: event.metaKey,\n    modifiers,\n  }\n}\n\n/**\n * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.\n *\n * @param event - The keyboard event (typically `keydown`)\n * @param platform - Target platform for `Mod` eligibility\n */\nexport function normalizeHotkeyFromEvent(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform)\n}\n\n/**\n * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.\n *\n * This is useful for validating that a recorded hotkey is complete and not\n * just a combination of modifiers without an action key.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to check\n * @param platform - The target platform for parsing (defaults to auto-detection)\n * @returns True if the hotkey contains at least one non-modifier key\n *\n * @example\n * ```ts\n * hasNonModifierKey('Control+Shift+S') // true\n * hasNonModifierKey('Control+Shift') // false (no action key)\n * hasNonModifierKey(parseHotkey('Mod+A')) // true\n * ```\n */\nexport function hasNonModifierKey(\n  hotkey: Hotkey | ParsedHotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check if the key part is actually a modifier\n  const keyIsModifier = isModifierKey(parsed.key)\n\n  // A valid hotkey must have a non-modifier key\n  return !keyIsModifier && parsed.key.length > 0\n}\n"],"mappings":"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"}

package/dist/parse.d.cts

@@ -1,4 +1,5 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey } from "./hotkey.cjs";
+import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { MODIFIER_ALIASES } from "./constants.cjs";
 
 //#region src/parse.d.ts
 /**
@@ -41,31 +42,43 @@ declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'win
 /**
  * Normalizes a hotkey string to its canonical form.
  *
- * The canonical form uses:
- * - Full modifier names (Control, Alt, Shift, Meta)
- * - Modifiers in order: Control+Alt+Shift+Meta
- * - Uppercase letters for single-character keys
- * - Proper casing for special keys (Escape, not escape)
+ * - When `Mod` is allowed for the platform (Command on Mac without Control;
+ *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+ *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+ * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+ * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
  *
  * @param hotkey - The hotkey string to normalize
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
  * @returns The normalized hotkey string
  *
  * @example
  * ```ts
- * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
- * normalizeHotkey('ctrl+a') // 'Control+A'
+ * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+ * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
-declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
+ */
+declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+ * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+ */
+declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
- * Checks if a string represents a modifier key.
+ * Checks if a string is a recognized modifier token (including aliases).
+ *
+ * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+ * spellings like `OS` / `Win` match the same alias table.
  *
- * @param key - The string to check
+ * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-declare function isModifier(key: string): boolean;
+declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
 /**
  * Parses a KeyboardEvent into a ParsedHotkey object.
  *
@@ -86,48 +99,12 @@ declare function isModifier(key: string): boolean;
  */
 declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
 /**
- * Converts a KeyboardEvent directly to a hotkey string.
- *
- * This is a convenience function that combines `parseKeyboardEvent()` and formatting.
- * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
- * and is suitable for use with `useHotkey()` and other hotkey functions.
- *
- * @param event - The KeyboardEvent to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
+ * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   const hotkey = keyboardEventToHotkey(event)
- *   console.log(hotkey) // 'Control+Shift+S'
- *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
- * })
- * ```
+ * @param event - The keyboard event (typically `keydown`)
+ * @param platform - Target platform for `Mod` eligibility
  */
-declare function keyboardEventToHotkey(event: KeyboardEvent): Hotkey;
-/**
- * Checks if a KeyboardEvent represents a modifier-only key press.
- *
- * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
- * that don't have an associated character or action key. This is useful
- * for filtering out modifier key presses when recording shortcuts.
- *
- * @param event - The KeyboardEvent to check
- * @returns True if the event represents a modifier-only key
- *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   if (isModifierKey(event)) {
- *     console.log('Modifier key pressed, waiting for action key...')
- *     return
- *   }
- *   // Process non-modifier key
- * })
- * ```
- */
-declare function isModifierKey(event: KeyboardEvent): boolean;
+declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
  *
@@ -146,24 +123,6 @@ declare function isModifierKey(event: KeyboardEvent): boolean;
  * ```
  */
 declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
-/**
- * Converts a hotkey string to use 'Mod' format for portability.
- *
- * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
- * This enables cross-platform hotkey definitions that work consistently.
- *
- * @param hotkey - The hotkey string to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns The hotkey string with 'Mod' format applied
- *
- * @example
- * ```ts
- * convertToModFormat('Meta+S', 'mac') // 'Mod+S'
- * convertToModFormat('Control+S', 'windows') // 'Mod+S'
- * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
- * ```
- */
-declare function convertToModFormat(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 //#endregion
-export { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.d.cts.map

package/dist/parse.d.ts

@@ -1,4 +1,5 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey } from "./hotkey.js";
+import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.js";
+import { MODIFIER_ALIASES } from "./constants.js";
 
 //#region src/parse.d.ts
 /**
@@ -41,31 +42,43 @@ declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'win
 /**
  * Normalizes a hotkey string to its canonical form.
  *
- * The canonical form uses:
- * - Full modifier names (Control, Alt, Shift, Meta)
- * - Modifiers in order: Control+Alt+Shift+Meta
- * - Uppercase letters for single-character keys
- * - Proper casing for special keys (Escape, not escape)
+ * - When `Mod` is allowed for the platform (Command on Mac without Control;
+ *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+ *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+ * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+ * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
  *
  * @param hotkey - The hotkey string to normalize
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
  * @returns The normalized hotkey string
  *
  * @example
  * ```ts
- * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
- * normalizeHotkey('ctrl+a') // 'Control+A'
+ * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+ * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
-declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
+ */
+declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+ * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+ */
+declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
- * Checks if a string represents a modifier key.
+ * Checks if a string is a recognized modifier token (including aliases).
+ *
+ * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+ * spellings like `OS` / `Win` match the same alias table.
  *
- * @param key - The string to check
+ * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-declare function isModifier(key: string): boolean;
+declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
 /**
  * Parses a KeyboardEvent into a ParsedHotkey object.
  *
@@ -86,48 +99,12 @@ declare function isModifier(key: string): boolean;
  */
 declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
 /**
- * Converts a KeyboardEvent directly to a hotkey string.
- *
- * This is a convenience function that combines `parseKeyboardEvent()` and formatting.
- * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
- * and is suitable for use with `useHotkey()` and other hotkey functions.
- *
- * @param event - The KeyboardEvent to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
+ * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   const hotkey = keyboardEventToHotkey(event)
- *   console.log(hotkey) // 'Control+Shift+S'
- *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
- * })
- * ```
+ * @param event - The keyboard event (typically `keydown`)
+ * @param platform - Target platform for `Mod` eligibility
  */
-declare function keyboardEventToHotkey(event: KeyboardEvent): Hotkey;
-/**
- * Checks if a KeyboardEvent represents a modifier-only key press.
- *
- * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
- * that don't have an associated character or action key. This is useful
- * for filtering out modifier key presses when recording shortcuts.
- *
- * @param event - The KeyboardEvent to check
- * @returns True if the event represents a modifier-only key
- *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   if (isModifierKey(event)) {
- *     console.log('Modifier key pressed, waiting for action key...')
- *     return
- *   }
- *   // Process non-modifier key
- * })
- * ```
- */
-declare function isModifierKey(event: KeyboardEvent): boolean;
+declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
  *
@@ -146,24 +123,6 @@ declare function isModifierKey(event: KeyboardEvent): boolean;
  * ```
  */
 declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
-/**
- * Converts a hotkey string to use 'Mod' format for portability.
- *
- * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
- * This enables cross-platform hotkey definitions that work consistently.
- *
- * @param hotkey - The hotkey string to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns The hotkey string with 'Mod' format applied
- *
- * @example
- * ```ts
- * convertToModFormat('Meta+S', 'mac') // 'Mod+S'
- * convertToModFormat('Control+S', 'windows') // 'Mod+S'
- * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
- * ```
- */
-declare function convertToModFormat(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 //#endregion
-export { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.d.ts.map