@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/parse.cjs

@@ -0,0 +1,266 @@
+const require_constants = require('./constants.cjs');
+
+//#region src/parse.ts
+/**
+* Parses a hotkey string into its component parts.
+*
+* @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
+* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @returns A ParsedHotkey object with the key and modifier flags
+*
+* @example
+* ```ts
+* parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+* parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
+* parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+* ```
+*/
+function parseHotkey(hotkey, platform = require_constants.detectPlatform()) {
+	const parts = hotkey.split("+");
+	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 = require_constants.normalizeKeyName(part);
+		else {
+			const alias = require_constants.MODIFIER_ALIASES[part] ?? require_constants.MODIFIER_ALIASES[part.toLowerCase()];
+			if (alias) {
+				const resolved = require_constants.resolveModifier(alias, platform);
+				modifiers.add(resolved);
+			} else if (parts.length === 1) key = require_constants.normalizeKeyName(part);
+		}
+	}
+	if (!key && parts.length > 0) key = require_constants.normalizeKeyName(parts[parts.length - 1].trim());
+	return {
+		key,
+		ctrl: modifiers.has("Control"),
+		shift: modifiers.has("Shift"),
+		alt: modifiers.has("Alt"),
+		meta: modifiers.has("Meta"),
+		modifiers: require_constants.MODIFIER_ORDER.filter((m) => modifiers.has(m))
+	};
+}
+/**
+* Converts a RawHotkey object to a ParsedHotkey.
+* Optional modifier booleans default to false; modifiers array is derived from them.
+* When `mod` is true, it is resolved to Control or Meta based on platform.
+*
+* @param raw - The raw hotkey object
+* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @returns A ParsedHotkey suitable for matching and formatting
+*
+* @example
+* ```ts
+* rawHotkeyToParsedHotkey({ key: 'Escape' })
+* // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
+*
+* rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
+* // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+*
+* rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
+* // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+* ```
+*/
+function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatform()) {
+	let ctrl = raw.ctrl ?? false;
+	const shift = raw.shift ?? false;
+	const alt = raw.alt ?? false;
+	let meta = raw.meta ?? false;
+	if (raw.mod) if (require_constants.resolveModifier("Mod", platform) === "Control") ctrl = true;
+	else meta = true;
+	const modifiers = require_constants.MODIFIER_ORDER.filter((m) => {
+		switch (m) {
+			case "Control": return ctrl;
+			case "Shift": return shift;
+			case "Alt": return alt;
+			case "Meta": return meta;
+			default: return false;
+		}
+	});
+	return {
+		key: raw.key,
+		ctrl,
+		shift,
+		alt,
+		meta,
+		modifiers
+	};
+}
+/**
+* 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)
+*
+* @param hotkey - The hotkey string to normalize
+* @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('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("+");
+}
+/**
+* Checks if a string represents a modifier key.
+*
+* @param key - The string to check
+* @returns True if the string is a recognized modifier
+*/
+function isModifier(key) {
+	return key in require_constants.MODIFIER_ALIASES || key.toLowerCase() in require_constants.MODIFIER_ALIASES;
+}
+/**
+* Parses a KeyboardEvent into a ParsedHotkey object.
+*
+* This function extracts the key and modifier state from a keyboard event
+* and converts it into the same format used by `parseHotkey()`.
+*
+* @param event - The KeyboardEvent to parse
+* @param platform - The target platform for resolving modifiers (defaults to auto-detection)
+* @returns A ParsedHotkey object representing the keyboard event
+*
+* @example
+* ```ts
+* document.addEventListener('keydown', (event) => {
+*   const parsed = parseKeyboardEvent(event)
+*   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
+* })
+* ```
+*/
+function parseKeyboardEvent(event) {
+	const normalizedKey = require_constants.normalizeKeyName(event.key);
+	const modifiers = [];
+	if (event.ctrlKey) modifiers.push("Control");
+	if (event.altKey) modifiers.push("Alt");
+	if (event.shiftKey) modifiers.push("Shift");
+	if (event.metaKey) modifiers.push("Meta");
+	return {
+		key: normalizedKey,
+		ctrl: event.ctrlKey,
+		shift: event.shiftKey,
+		alt: event.altKey,
+		meta: event.metaKey,
+		modifiers
+	};
+}
+/**
+* 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.
+*
+* 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
+* })
+* ```
+*/
+function isModifierKey(event) {
+	const key = event.key;
+	return key === "Control" || key === "Shift" || key === "Alt" || key === "Meta" || key === "Command" || key === "OS" || key === "Win";
+}
+/**
+* Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
+*
+* This is useful for validating that a recorded hotkey is complete and not
+* just a combination of modifiers without an action key.
+*
+* @param hotkey - The hotkey string or ParsedHotkey to check
+* @param platform - The target platform for parsing (defaults to auto-detection)
+* @returns True if the hotkey contains at least one non-modifier key
+*
+* @example
+* ```ts
+* hasNonModifierKey('Control+Shift+S') // true
+* hasNonModifierKey('Control+Shift') // false (no action key)
+* hasNonModifierKey(parseHotkey('Mod+A')) // true
+* ```
+*/
+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;
+}
+
+//#endregion
+exports.convertToModFormat = convertToModFormat;
+exports.hasNonModifierKey = hasNonModifierKey;
+exports.isModifier = isModifier;
+exports.isModifierKey = isModifierKey;
+exports.keyboardEventToHotkey = keyboardEventToHotkey;
+exports.normalizeHotkey = normalizeHotkey;
+exports.parseHotkey = parseHotkey;
+exports.parseKeyboardEvent = parseKeyboardEvent;
+exports.rawHotkeyToParsedHotkey = rawHotkeyToParsedHotkey;
+//# sourceMappingURL=parse.cjs.map

package/dist/parse.cjs.map

@@ -0,0 +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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"}

package/dist/parse.d.cts

@@ -0,0 +1,169 @@
+import { Hotkey, Key, ParsedHotkey, RawHotkey } from "./hotkey.cjs";
+
+//#region src/parse.d.ts
+/**
+ * Parses a hotkey string into its component parts.
+ *
+ * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns A ParsedHotkey object with the key and modifier flags
+ *
+ * @example
+ * ```ts
+ * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
+ * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+/**
+ * Converts a RawHotkey object to a ParsedHotkey.
+ * Optional modifier booleans default to false; modifiers array is derived from them.
+ * When `mod` is true, it is resolved to Control or Meta based on platform.
+ *
+ * @param raw - The raw hotkey object
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns A ParsedHotkey suitable for matching and formatting
+ *
+ * @example
+ * ```ts
+ * rawHotkeyToParsedHotkey({ key: 'Escape' })
+ * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
+ * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
+ * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+/**
+ * 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)
+ *
+ * @param hotkey - The hotkey string to normalize
+ * @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('esc') // 'Escape'
+ * ```
+ */
+declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+/**
+ * Checks if a string represents a modifier key.
+ *
+ * @param key - The string to check
+ * @returns True if the string is a recognized modifier
+ */
+declare function isModifier(key: string): boolean;
+/**
+ * Parses a KeyboardEvent into a ParsedHotkey object.
+ *
+ * This function extracts the key and modifier state from a keyboard event
+ * and converts it into the same format used by `parseHotkey()`.
+ *
+ * @param event - The KeyboardEvent to parse
+ * @param platform - The target platform for resolving modifiers (defaults to auto-detection)
+ * @returns A ParsedHotkey object representing the keyboard event
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const parsed = parseKeyboardEvent(event)
+ *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
+ * })
+ * ```
+ */
+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')
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const hotkey = keyboardEventToHotkey(event)
+ *   console.log(hotkey) // 'Control+Shift+S'
+ *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
+ * })
+ * ```
+ */
+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;
+/**
+ * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
+ *
+ * This is useful for validating that a recorded hotkey is complete and not
+ * just a combination of modifiers without an action key.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to check
+ * @param platform - The target platform for parsing (defaults to auto-detection)
+ * @returns True if the hotkey contains at least one non-modifier key
+ *
+ * @example
+ * ```ts
+ * hasNonModifierKey('Control+Shift+S') // true
+ * hasNonModifierKey('Control+Shift') // false (no action key)
+ * hasNonModifierKey(parseHotkey('Mod+A')) // true
+ * ```
+ */
+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 };
+//# sourceMappingURL=parse.d.cts.map

package/dist/parse.d.ts

@@ -0,0 +1,169 @@
+import { Hotkey, Key, ParsedHotkey, RawHotkey } from "./hotkey.js";
+
+//#region src/parse.d.ts
+/**
+ * Parses a hotkey string into its component parts.
+ *
+ * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns A ParsedHotkey object with the key and modifier flags
+ *
+ * @example
+ * ```ts
+ * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }
+ * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+/**
+ * Converts a RawHotkey object to a ParsedHotkey.
+ * Optional modifier booleans default to false; modifiers array is derived from them.
+ * When `mod` is true, it is resolved to Control or Meta based on platform.
+ *
+ * @param raw - The raw hotkey object
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns A ParsedHotkey suitable for matching and formatting
+ *
+ * @example
+ * ```ts
+ * rawHotkeyToParsedHotkey({ key: 'Escape' })
+ * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')
+ * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }
+ *
+ * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')
+ * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
+ * ```
+ */
+declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+/**
+ * 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)
+ *
+ * @param hotkey - The hotkey string to normalize
+ * @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('esc') // 'Escape'
+ * ```
+ */
+declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+/**
+ * Checks if a string represents a modifier key.
+ *
+ * @param key - The string to check
+ * @returns True if the string is a recognized modifier
+ */
+declare function isModifier(key: string): boolean;
+/**
+ * Parses a KeyboardEvent into a ParsedHotkey object.
+ *
+ * This function extracts the key and modifier state from a keyboard event
+ * and converts it into the same format used by `parseHotkey()`.
+ *
+ * @param event - The KeyboardEvent to parse
+ * @param platform - The target platform for resolving modifiers (defaults to auto-detection)
+ * @returns A ParsedHotkey object representing the keyboard event
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const parsed = parseKeyboardEvent(event)
+ *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }
+ * })
+ * ```
+ */
+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')
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   const hotkey = keyboardEventToHotkey(event)
+ *   console.log(hotkey) // 'Control+Shift+S'
+ *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
+ * })
+ * ```
+ */
+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;
+/**
+ * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
+ *
+ * This is useful for validating that a recorded hotkey is complete and not
+ * just a combination of modifiers without an action key.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to check
+ * @param platform - The target platform for parsing (defaults to auto-detection)
+ * @returns True if the hotkey contains at least one non-modifier key
+ *
+ * @example
+ * ```ts
+ * hasNonModifierKey('Control+Shift+S') // true
+ * hasNonModifierKey('Control+Shift') // false (no action key)
+ * hasNonModifierKey(parseHotkey('Mod+A')) // true
+ * ```
+ */
+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 };
+//# sourceMappingURL=parse.d.ts.map