@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/match.cjs

@@ -0,0 +1,143 @@
+const require_constants = require('./constants.cjs');
+const require_parse = require('./parse.cjs');
+
+//#region src/match.ts
+/**
+* Checks if a KeyboardEvent matches a hotkey.
+*
+* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+* for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
+* (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+*
+* @param event - The KeyboardEvent to check
+* @param hotkey - The hotkey string or ParsedHotkey to match against
+* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @returns True if the event matches the hotkey
+*
+* @example
+* ```ts
+* document.addEventListener('keydown', (event) => {
+*   if (matchesKeyboardEvent(event, 'Mod+S')) {
+*     event.preventDefault()
+*     handleSave()
+*   }
+* })
+* ```
+*/
+function matchesKeyboardEvent(event, hotkey, platform = require_constants.detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
+	if (event.ctrlKey !== parsed.ctrl) return false;
+	if (event.shiftKey !== parsed.shift) return false;
+	if (event.altKey !== parsed.alt) return false;
+	if (event.metaKey !== parsed.meta) return false;
+	const eventKey = require_constants.normalizeKeyName(event.key);
+	const hotkeyKey = parsed.key;
+	if (eventKey.length === 1 && hotkeyKey.length === 1) {
+		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
+		if (event.code && event.code.startsWith("Key")) {
+			const codeLetter = event.code.slice(3);
+			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
+		}
+		if (event.code && event.code.startsWith("Digit")) {
+			const codeDigit = event.code.slice(5);
+			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
+		}
+		return false;
+	}
+	return eventKey === hotkeyKey;
+}
+/**
+* Creates a keyboard event handler that calls the callback when the hotkey matches.
+*
+* @param hotkey - The hotkey string or ParsedHotkey to match
+* @param callback - The function to call when the hotkey matches
+* @param options - Options for matching and handling
+* @returns A function that can be used as an event handler
+*
+* @example
+* ```ts
+* const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
+*   console.log(`${hotkey} was pressed`)
+*   handleSave()
+* })
+*
+* document.addEventListener('keydown', handler)
+* ```
+*/
+function createHotkeyHandler(hotkey, callback, options = {}) {
+	const { preventDefault = true, stopPropagation = true, platform } = options;
+	const resolvedPlatform = platform ?? require_constants.detectPlatform();
+	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
+	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, resolvedPlatform) : hotkey;
+	const context = {
+		hotkey: hotkeyString,
+		parsedHotkey: parsed
+	};
+	return (event) => {
+		if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+			if (preventDefault) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			callback(event, context);
+		}
+	};
+}
+/**
+* Creates a handler that matches multiple hotkeys.
+*
+* @param handlers - A map of hotkey strings to their handlers
+* @param options - Options for matching and handling
+* @returns A function that can be used as an event handler
+*
+* @example
+* ```ts
+* const handler = createMultiHotkeyHandler({
+*   'Mod+S': (event, { hotkey }) => handleSave(),
+*   'Mod+Z': (event, { hotkey }) => handleUndo(),
+*   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
+* })
+*
+* document.addEventListener('keydown', handler)
+* ```
+*/
+function createMultiHotkeyHandler(handlers, options = {}) {
+	const { preventDefault = true, stopPropagation = true, platform } = options;
+	const resolvedPlatform = platform ?? require_constants.detectPlatform();
+	const parsedHandlers = Object.entries(handlers).filter((entry) => Boolean(entry[1])).map(([hotkey, handler]) => {
+		const parsed = require_parse.parseHotkey(hotkey, resolvedPlatform);
+		return {
+			parsed,
+			handler,
+			context: {
+				hotkey,
+				parsedHotkey: parsed
+			}
+		};
+	});
+	return (event) => {
+		for (const { parsed, handler, context } of parsedHandlers) if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+			if (preventDefault) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			handler(event, context);
+			return;
+		}
+	};
+}
+/**
+* Formats a ParsedHotkey back to a hotkey string.
+* Used internally to provide the hotkey string in callback context.
+*/
+function formatParsedHotkey(parsed) {
+	const parts = [];
+	if (parsed.ctrl) parts.push("Control");
+	if (parsed.alt) parts.push("Alt");
+	if (parsed.shift) parts.push("Shift");
+	if (parsed.meta) parts.push("Meta");
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+
+//#endregion
+exports.createHotkeyHandler = createHotkeyHandler;
+exports.createMultiHotkeyHandler = createMultiHotkeyHandler;
+exports.matchesKeyboardEvent = matchesKeyboardEvent;
+//# sourceMappingURL=match.cjs.map

package/dist/match.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyName"],"sources":["../src/match.ts"],"sourcesContent":["import { detectPlatform, normalizeKeyName } from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters\n * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single letters, compare case-insensitively\n  if (eventKey.length === 1 && hotkeyKey.length === 1) {\n    // First try matching with event.key\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // Fallback to event.code for letter keys when event.key doesn't match\n    // This handles cases like Command+Option+T on macOS where event.key is '†' instead of 'T'\n    // event.code format for letter keys is \"KeyA\", \"KeyB\", etc. (always uppercase in browsers)\n    if (event.code && event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3) // Remove \"Key\" prefix\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // Fallback to event.code for digit keys when event.key doesn't match\n    // This handles cases like Shift+4 where event.key is '$' instead of '4'\n    // event.code format for digit keys is \"Digit0\", \"Digit1\", etc.\n    if (event.code && event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5) // Remove \"Digit\" prefix\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,qBACd,OACA,QACA,WAAwCA,kCAAgB,EAC/C;CACT,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,SAAS,GAAG;AAG/D,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;AAET,KAAI,MAAM,aAAa,OAAO,MAC5B,QAAO;AAET,KAAI,MAAM,WAAW,OAAO,IAC1B,QAAO;AAET,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;CAIT,MAAM,WAAWC,mCAAiB,MAAM,IAAI;CAC5C,MAAM,YAAY,OAAO;AAGzB,KAAI,SAAS,WAAW,KAAK,UAAU,WAAW,GAAG;AAEnD,MAAI,SAAS,aAAa,KAAK,UAAU,aAAa,CACpD,QAAO;AAMT,MAAI,MAAM,QAAQ,MAAM,KAAK,WAAW,MAAM,EAAE;GAC9C,MAAM,aAAa,MAAM,KAAK,MAAM,EAAE;AACtC,OAAI,WAAW,WAAW,KAAK,aAAa,KAAK,WAAW,CAC1D,QAAO,WAAW,aAAa,KAAK,UAAU,aAAa;;AAO/D,MAAI,MAAM,QAAQ,MAAM,KAAK,WAAW,QAAQ,EAAE;GAChD,MAAM,YAAY,MAAM,KAAK,MAAM,EAAE;AACrC,OAAI,UAAU,WAAW,KAAK,UAAU,KAAK,UAAU,CACrD,QAAO,cAAc;;AAIzB,SAAO;;AAIT,QAAO,aAAa;;;;;;;;;;;;;;;;;;;;AAiCtB,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYF,kCAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAWC,0BAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYD,kCAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAASC,0BAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI"}

package/dist/match.d.cts

@@ -0,0 +1,79 @@
+import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.cjs";
+
+//#region src/match.d.ts
+/**
+ * Checks if a KeyboardEvent matches a hotkey.
+ *
+ * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
+ * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ *
+ * @param event - The KeyboardEvent to check
+ * @param hotkey - The hotkey string or ParsedHotkey to match against
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns True if the event matches the hotkey
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   if (matchesKeyboardEvent(event, 'Mod+S')) {
+ *     event.preventDefault()
+ *     handleSave()
+ *   }
+ * })
+ * ```
+ */
+declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
+/**
+ * Options for creating a hotkey handler.
+ */
+interface CreateHotkeyHandlerOptions {
+  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+  preventDefault?: boolean;
+  /** Stop event propagation when the hotkey matches. Defaults to true */
+  stopPropagation?: boolean;
+  /** The target platform for resolving 'Mod' */
+  platform?: 'mac' | 'windows' | 'linux';
+}
+/**
+ * Creates a keyboard event handler that calls the callback when the hotkey matches.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to match
+ * @param callback - The function to call when the hotkey matches
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
+ *   console.log(`${hotkey} was pressed`)
+ *   handleSave()
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
+/**
+ * Creates a handler that matches multiple hotkeys.
+ *
+ * @param handlers - A map of hotkey strings to their handlers
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createMultiHotkeyHandler({
+ *   'Mod+S': (event, { hotkey }) => handleSave(),
+ *   'Mod+Z': (event, { hotkey }) => handleUndo(),
+ *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+//#endregion
+export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+//# sourceMappingURL=match.d.cts.map

package/dist/match.d.ts

@@ -0,0 +1,79 @@
+import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.js";
+
+//#region src/match.d.ts
+/**
+ * Checks if a KeyboardEvent matches a hotkey.
+ *
+ * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
+ * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+ *
+ * @param event - The KeyboardEvent to check
+ * @param hotkey - The hotkey string or ParsedHotkey to match against
+ * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @returns True if the event matches the hotkey
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('keydown', (event) => {
+ *   if (matchesKeyboardEvent(event, 'Mod+S')) {
+ *     event.preventDefault()
+ *     handleSave()
+ *   }
+ * })
+ * ```
+ */
+declare function matchesKeyboardEvent(event: KeyboardEvent, hotkey: Hotkey | ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): boolean;
+/**
+ * Options for creating a hotkey handler.
+ */
+interface CreateHotkeyHandlerOptions {
+  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+  preventDefault?: boolean;
+  /** Stop event propagation when the hotkey matches. Defaults to true */
+  stopPropagation?: boolean;
+  /** The target platform for resolving 'Mod' */
+  platform?: 'mac' | 'windows' | 'linux';
+}
+/**
+ * Creates a keyboard event handler that calls the callback when the hotkey matches.
+ *
+ * @param hotkey - The hotkey string or ParsedHotkey to match
+ * @param callback - The function to call when the hotkey matches
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
+ *   console.log(`${hotkey} was pressed`)
+ *   handleSave()
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+declare function createHotkeyHandler(hotkey: Hotkey | ParsedHotkey, callback: HotkeyCallback, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
+/**
+ * Creates a handler that matches multiple hotkeys.
+ *
+ * @param handlers - A map of hotkey strings to their handlers
+ * @param options - Options for matching and handling
+ * @returns A function that can be used as an event handler
+ *
+ * @example
+ * ```ts
+ * const handler = createMultiHotkeyHandler({
+ *   'Mod+S': (event, { hotkey }) => handleSave(),
+ *   'Mod+Z': (event, { hotkey }) => handleUndo(),
+ *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
+ * })
+ *
+ * document.addEventListener('keydown', handler)
+ * ```
+ */
+declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+//#endregion
+export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+//# sourceMappingURL=match.d.ts.map

package/dist/match.js

@@ -0,0 +1,141 @@
+import { detectPlatform, normalizeKeyName } from "./constants.js";
+import { parseHotkey } from "./parse.js";
+
+//#region src/match.ts
+/**
+* Checks if a KeyboardEvent matches a hotkey.
+*
+* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+* for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
+* (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+*
+* @param event - The KeyboardEvent to check
+* @param hotkey - The hotkey string or ParsedHotkey to match against
+* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @returns True if the event matches the hotkey
+*
+* @example
+* ```ts
+* document.addEventListener('keydown', (event) => {
+*   if (matchesKeyboardEvent(event, 'Mod+S')) {
+*     event.preventDefault()
+*     handleSave()
+*   }
+* })
+* ```
+*/
+function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	if (event.ctrlKey !== parsed.ctrl) return false;
+	if (event.shiftKey !== parsed.shift) return false;
+	if (event.altKey !== parsed.alt) return false;
+	if (event.metaKey !== parsed.meta) return false;
+	const eventKey = normalizeKeyName(event.key);
+	const hotkeyKey = parsed.key;
+	if (eventKey.length === 1 && hotkeyKey.length === 1) {
+		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
+		if (event.code && event.code.startsWith("Key")) {
+			const codeLetter = event.code.slice(3);
+			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
+		}
+		if (event.code && event.code.startsWith("Digit")) {
+			const codeDigit = event.code.slice(5);
+			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
+		}
+		return false;
+	}
+	return eventKey === hotkeyKey;
+}
+/**
+* Creates a keyboard event handler that calls the callback when the hotkey matches.
+*
+* @param hotkey - The hotkey string or ParsedHotkey to match
+* @param callback - The function to call when the hotkey matches
+* @param options - Options for matching and handling
+* @returns A function that can be used as an event handler
+*
+* @example
+* ```ts
+* const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {
+*   console.log(`${hotkey} was pressed`)
+*   handleSave()
+* })
+*
+* document.addEventListener('keydown', handler)
+* ```
+*/
+function createHotkeyHandler(hotkey, callback, options = {}) {
+	const { preventDefault = true, stopPropagation = true, platform } = options;
+	const resolvedPlatform = platform ?? detectPlatform();
+	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
+	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, resolvedPlatform) : hotkey;
+	const context = {
+		hotkey: hotkeyString,
+		parsedHotkey: parsed
+	};
+	return (event) => {
+		if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+			if (preventDefault) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			callback(event, context);
+		}
+	};
+}
+/**
+* Creates a handler that matches multiple hotkeys.
+*
+* @param handlers - A map of hotkey strings to their handlers
+* @param options - Options for matching and handling
+* @returns A function that can be used as an event handler
+*
+* @example
+* ```ts
+* const handler = createMultiHotkeyHandler({
+*   'Mod+S': (event, { hotkey }) => handleSave(),
+*   'Mod+Z': (event, { hotkey }) => handleUndo(),
+*   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),
+* })
+*
+* document.addEventListener('keydown', handler)
+* ```
+*/
+function createMultiHotkeyHandler(handlers, options = {}) {
+	const { preventDefault = true, stopPropagation = true, platform } = options;
+	const resolvedPlatform = platform ?? detectPlatform();
+	const parsedHandlers = Object.entries(handlers).filter((entry) => Boolean(entry[1])).map(([hotkey, handler]) => {
+		const parsed = parseHotkey(hotkey, resolvedPlatform);
+		return {
+			parsed,
+			handler,
+			context: {
+				hotkey,
+				parsedHotkey: parsed
+			}
+		};
+	});
+	return (event) => {
+		for (const { parsed, handler, context } of parsedHandlers) if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {
+			if (preventDefault) event.preventDefault();
+			if (stopPropagation) event.stopPropagation();
+			handler(event, context);
+			return;
+		}
+	};
+}
+/**
+* Formats a ParsedHotkey back to a hotkey string.
+* Used internally to provide the hotkey string in callback context.
+*/
+function formatParsedHotkey(parsed) {
+	const parts = [];
+	if (parsed.ctrl) parts.push("Control");
+	if (parsed.alt) parts.push("Alt");
+	if (parsed.shift) parts.push("Shift");
+	if (parsed.meta) parts.push("Meta");
+	parts.push(parsed.key);
+	return parts.join("+");
+}
+
+//#endregion
+export { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+//# sourceMappingURL=match.js.map

package/dist/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import { detectPlatform, normalizeKeyName } from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters\n * (e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single letters, compare case-insensitively\n  if (eventKey.length === 1 && hotkeyKey.length === 1) {\n    // First try matching with event.key\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // Fallback to event.code for letter keys when event.key doesn't match\n    // This handles cases like Command+Option+T on macOS where event.key is '†' instead of 'T'\n    // event.code format for letter keys is \"KeyA\", \"KeyB\", etc. (always uppercase in browsers)\n    if (event.code && event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3) // Remove \"Key\" prefix\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // Fallback to event.code for digit keys when event.key doesn't match\n    // This handles cases like Shift+4 where event.key is '$' instead of '4'\n    // event.code format for digit keys is \"Digit0\", \"Digit1\", etc.\n    if (event.code && event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5) // Remove \"Digit\" prefix\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,qBACd,OACA,QACA,WAAwC,gBAAgB,EAC/C;CACT,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;AAG/D,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;AAET,KAAI,MAAM,aAAa,OAAO,MAC5B,QAAO;AAET,KAAI,MAAM,WAAW,OAAO,IAC1B,QAAO;AAET,KAAI,MAAM,YAAY,OAAO,KAC3B,QAAO;CAIT,MAAM,WAAW,iBAAiB,MAAM,IAAI;CAC5C,MAAM,YAAY,OAAO;AAGzB,KAAI,SAAS,WAAW,KAAK,UAAU,WAAW,GAAG;AAEnD,MAAI,SAAS,aAAa,KAAK,UAAU,aAAa,CACpD,QAAO;AAMT,MAAI,MAAM,QAAQ,MAAM,KAAK,WAAW,MAAM,EAAE;GAC9C,MAAM,aAAa,MAAM,KAAK,MAAM,EAAE;AACtC,OAAI,WAAW,WAAW,KAAK,aAAa,KAAK,WAAW,CAC1D,QAAO,WAAW,aAAa,KAAK,UAAU,aAAa;;AAO/D,MAAI,MAAM,QAAQ,MAAM,KAAK,WAAW,QAAQ,EAAE;GAChD,MAAM,YAAY,MAAM,KAAK,MAAM,EAAE;AACrC,OAAI,UAAU,WAAW,KAAK,UAAU,KAAK,UAAU,CACrD,QAAO,cAAc;;AAIzB,SAAO;;AAIT,QAAO,aAAa;;;;;;;;;;;;;;;;;;;;AAiCtB,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAAS,YAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI"}