@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/sequence.d.ts

@@ -0,0 +1,109 @@
+import { Hotkey, HotkeyCallback } from "./hotkey.js";
+import { HotkeyOptions } from "./hotkey-manager.js";
+
+//#region src/sequence.d.ts
+/**
+ * Options for hotkey sequence matching.
+ */
+interface SequenceOptions extends HotkeyOptions {
+  /** Timeout between keys in milliseconds. Default: 1000 */
+  timeout?: number;
+}
+/**
+ * A sequence of hotkeys for Vim-style shortcuts.
+ *
+ * @example
+ * ```ts
+ * const gotoTop: HotkeySequence = ['G', 'G']  // gg
+ * const deleteLine: HotkeySequence = ['D', 'D']  // dd
+ * const deleteWord: HotkeySequence = ['D', 'I', 'W']  // diw
+ * ```
+ */
+type HotkeySequence = Array<Hotkey>;
+/**
+ * Manages keyboard sequence matching for Vim-style shortcuts.
+ *
+ * This class allows registering multi-key sequences like 'g g' or 'd d'
+ * that trigger callbacks when the full sequence is pressed within
+ * a configurable timeout.
+ *
+ * @example
+ * ```ts
+ * const matcher = SequenceManager.getInstance()
+ *
+ * // Register 'g g' to go to top
+ * const unregister = matcher.register(['G', 'G'], (event, context) => {
+ *   scrollToTop()
+ * }, { timeout: 500 })
+ *
+ * // Later, to unregister:
+ * unregister()
+ * ```
+ */
+declare class SequenceManager {
+  #private;
+  private constructor();
+  /**
+   * Gets the singleton instance of SequenceManager.
+   */
+  static getInstance(): SequenceManager;
+  /**
+   * Resets the singleton instance. Useful for testing.
+   */
+  static resetInstance(): void;
+  /**
+   * Registers a hotkey sequence handler.
+   *
+   * @param sequence - Array of hotkey strings that form the sequence
+   * @param callback - Function to call when the sequence is completed
+   * @param options - Options for the sequence behavior
+   * @returns A function to unregister the sequence
+   */
+  register(sequence: HotkeySequence, callback: HotkeyCallback, options?: SequenceOptions): () => void;
+  /**
+   * Resets all sequence progress.
+   */
+  resetAll(): void;
+  /**
+   * Gets the number of registered sequences.
+   */
+  getRegistrationCount(): number;
+  /**
+   * Destroys the manager and removes all listeners.
+   */
+  destroy(): void;
+}
+/**
+ * Gets the singleton SequenceManager instance.
+ * Convenience function for accessing the manager.
+ */
+declare function getSequenceManager(): SequenceManager;
+/**
+ * Creates a simple sequence matcher for one-off use.
+ *
+ * @param sequence - The sequence of hotkeys to match
+ * @param options - Options including timeout
+ * @returns An object with match() and reset() methods
+ *
+ * @example
+ * ```ts
+ * const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
+ *
+ * document.addEventListener('keydown', (event) => {
+ *   if (matcher.match(event)) {
+ *     console.log('Sequence matched!')
+ *   }
+ * })
+ * ```
+ */
+declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
+  timeout?: number;
+  platform?: 'mac' | 'windows' | 'linux';
+}): {
+  match: (event: KeyboardEvent) => boolean;
+  reset: () => void;
+  getProgress: () => number;
+};
+//#endregion
+export { HotkeySequence, SequenceManager, SequenceOptions, createSequenceMatcher, getSequenceManager };
+//# sourceMappingURL=sequence.d.ts.map

package/dist/sequence.js

@@ -0,0 +1,240 @@
+import { detectPlatform } from "./constants.js";
+import { parseHotkey } from "./parse.js";
+import { matchesKeyboardEvent } from "./match.js";
+
+//#region src/sequence.ts
+/**
+* Default timeout between keys in a sequence (in milliseconds).
+*/
+const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
+let sequenceIdCounter = 0;
+/**
+* Generates a unique ID for sequence registrations.
+*/
+function generateSequenceId() {
+	return `sequence_${++sequenceIdCounter}`;
+}
+/**
+* Manages keyboard sequence matching for Vim-style shortcuts.
+*
+* This class allows registering multi-key sequences like 'g g' or 'd d'
+* that trigger callbacks when the full sequence is pressed within
+* a configurable timeout.
+*
+* @example
+* ```ts
+* const matcher = SequenceManager.getInstance()
+*
+* // Register 'g g' to go to top
+* const unregister = matcher.register(['G', 'G'], (event, context) => {
+*   scrollToTop()
+* }, { timeout: 500 })
+*
+* // Later, to unregister:
+* unregister()
+* ```
+*/
+var SequenceManager = class SequenceManager {
+	static #instance = null;
+	#registrations = /* @__PURE__ */ new Map();
+	#keydownListener = null;
+	#platform;
+	constructor() {
+		this.#platform = detectPlatform();
+	}
+	/**
+	* Gets the singleton instance of SequenceManager.
+	*/
+	static getInstance() {
+		if (!SequenceManager.#instance) SequenceManager.#instance = new SequenceManager();
+		return SequenceManager.#instance;
+	}
+	/**
+	* Resets the singleton instance. Useful for testing.
+	*/
+	static resetInstance() {
+		if (SequenceManager.#instance) {
+			SequenceManager.#instance.destroy();
+			SequenceManager.#instance = null;
+		}
+	}
+	/**
+	* Registers a hotkey sequence handler.
+	*
+	* @param sequence - Array of hotkey strings that form the sequence
+	* @param callback - Function to call when the sequence is completed
+	* @param options - Options for the sequence behavior
+	* @returns A function to unregister the sequence
+	*/
+	register(sequence, callback, options = {}) {
+		if (sequence.length === 0) throw new Error("Sequence must contain at least one hotkey");
+		const id = generateSequenceId();
+		const platform = options.platform ?? this.#platform;
+		const registration = {
+			id,
+			sequence,
+			parsedSequence: sequence.map((hotkey) => parseHotkey(hotkey, platform)),
+			callback,
+			options: {
+				timeout: DEFAULT_SEQUENCE_TIMEOUT,
+				preventDefault: true,
+				stopPropagation: true,
+				enabled: true,
+				...options,
+				platform
+			},
+			currentIndex: 0,
+			lastKeyTime: 0
+		};
+		this.#registrations.set(id, registration);
+		this.#ensureListener();
+		return () => {
+			this.#unregister(id);
+		};
+	}
+	/**
+	* Unregisters a sequence by its registration ID.
+	*/
+	#unregister(id) {
+		this.#registrations.delete(id);
+		if (this.#registrations.size === 0) this.#removeListener();
+	}
+	/**
+	* Ensures the keydown listener is attached.
+	*/
+	#ensureListener() {
+		if (typeof document === "undefined") return;
+		if (!this.#keydownListener) {
+			this.#keydownListener = this.#handleKeyDown.bind(this);
+			document.addEventListener("keydown", this.#keydownListener);
+		}
+	}
+	/**
+	* Removes the keydown listener.
+	*/
+	#removeListener() {
+		if (typeof document === "undefined") return;
+		if (this.#keydownListener) {
+			document.removeEventListener("keydown", this.#keydownListener);
+			this.#keydownListener = null;
+		}
+	}
+	/**
+	* Handles keydown events for sequence matching.
+	*/
+	#handleKeyDown(event) {
+		const now = Date.now();
+		for (const registration of this.#registrations.values()) {
+			if (!registration.options.enabled) continue;
+			const timeout = registration.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) registration.currentIndex = 0;
+			const expectedHotkey = registration.parsedSequence[registration.currentIndex];
+			if (!expectedHotkey) continue;
+			if (matchesKeyboardEvent(event, expectedHotkey, registration.options.platform)) {
+				registration.lastKeyTime = now;
+				registration.currentIndex++;
+				if (registration.currentIndex >= registration.parsedSequence.length) {
+					if (registration.options.preventDefault) event.preventDefault();
+					if (registration.options.stopPropagation) event.stopPropagation();
+					const context = {
+						hotkey: registration.sequence.join(" "),
+						parsedHotkey: registration.parsedSequence[registration.parsedSequence.length - 1]
+					};
+					registration.callback(event, context);
+					registration.currentIndex = 0;
+				}
+			} else if (registration.currentIndex > 0) {
+				const firstHotkey = registration.parsedSequence[0];
+				if (matchesKeyboardEvent(event, firstHotkey, registration.options.platform)) {
+					registration.currentIndex = 1;
+					registration.lastKeyTime = now;
+				} else registration.currentIndex = 0;
+			}
+		}
+	}
+	/**
+	* Resets all sequence progress.
+	*/
+	resetAll() {
+		for (const registration of this.#registrations.values()) {
+			registration.currentIndex = 0;
+			registration.lastKeyTime = 0;
+		}
+	}
+	/**
+	* Gets the number of registered sequences.
+	*/
+	getRegistrationCount() {
+		return this.#registrations.size;
+	}
+	/**
+	* Destroys the manager and removes all listeners.
+	*/
+	destroy() {
+		this.#removeListener();
+		this.#registrations.clear();
+	}
+};
+/**
+* Gets the singleton SequenceManager instance.
+* Convenience function for accessing the manager.
+*/
+function getSequenceManager() {
+	return SequenceManager.getInstance();
+}
+/**
+* Creates a simple sequence matcher for one-off use.
+*
+* @param sequence - The sequence of hotkeys to match
+* @param options - Options including timeout
+* @returns An object with match() and reset() methods
+*
+* @example
+* ```ts
+* const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })
+*
+* document.addEventListener('keydown', (event) => {
+*   if (matcher.match(event)) {
+*     console.log('Sequence matched!')
+*   }
+* })
+* ```
+*/
+function createSequenceMatcher(sequence, options = {}) {
+	const platform = options.platform ?? detectPlatform();
+	const timeout = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+	const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform));
+	let currentIndex = 0;
+	let lastKeyTime = 0;
+	return {
+		match(event) {
+			const now = Date.now();
+			if (currentIndex > 0 && now - lastKeyTime > timeout) currentIndex = 0;
+			const expected = parsedSequence[currentIndex];
+			if (!expected) return false;
+			if (matchesKeyboardEvent(event, expected, platform)) {
+				lastKeyTime = now;
+				currentIndex++;
+				if (currentIndex >= parsedSequence.length) {
+					currentIndex = 0;
+					return true;
+				}
+			} else if (currentIndex > 0) if (matchesKeyboardEvent(event, parsedSequence[0], platform)) {
+				currentIndex = 1;
+				lastKeyTime = now;
+			} else currentIndex = 0;
+			return false;
+		},
+		reset() {
+			currentIndex = 0;
+			lastKeyTime = 0;
+		},
+		getProgress() {
+			return currentIndex;
+		}
+	};
+}
+
+//#endregion
+export { SequenceManager, createSequenceMatcher, getSequenceManager };
+//# sourceMappingURL=sequence.js.map

package/dist/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","names":["#instance","#platform","#registrations","#ensureListener","#unregister","#removeListener","#keydownListener","#handleKeyDown"],"sources":["../src/sequence.ts"],"sourcesContent":["import { detectPlatform } from './constants'\nimport { parseHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport type { HotkeyOptions } from './hotkey-manager'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Options for hotkey sequence matching.\n */\nexport interface SequenceOptions extends HotkeyOptions {\n  /** Timeout between keys in milliseconds. Default: 1000 */\n  timeout?: number\n}\n\n/**\n * A sequence of hotkeys for Vim-style shortcuts.\n *\n * @example\n * ```ts\n * const gotoTop: HotkeySequence = ['G', 'G']  // gg\n * const deleteLine: HotkeySequence = ['D', 'D']  // dd\n * const deleteWord: HotkeySequence = ['D', 'I', 'W']  // diw\n * ```\n */\nexport type HotkeySequence = Array<Hotkey>\n\n/**\n * Default timeout between keys in a sequence (in milliseconds).\n */\nconst DEFAULT_SEQUENCE_TIMEOUT = 1000\n\nlet sequenceIdCounter = 0\n\n/**\n * Generates a unique ID for sequence registrations.\n */\nfunction generateSequenceId(): string {\n  return `sequence_${++sequenceIdCounter}`\n}\n\n/**\n * Internal representation of a sequence registration.\n */\ninterface SequenceRegistration {\n  id: string\n  sequence: HotkeySequence\n  parsedSequence: Array<ParsedHotkey>\n  callback: HotkeyCallback\n  options: SequenceOptions\n  currentIndex: number\n  lastKeyTime: number\n}\n\n/**\n * Manages keyboard sequence matching for Vim-style shortcuts.\n *\n * This class allows registering multi-key sequences like 'g g' or 'd d'\n * that trigger callbacks when the full sequence is pressed within\n * a configurable timeout.\n *\n * @example\n * ```ts\n * const matcher = SequenceManager.getInstance()\n *\n * // Register 'g g' to go to top\n * const unregister = matcher.register(['G', 'G'], (event, context) => {\n *   scrollToTop()\n * }, { timeout: 500 })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class SequenceManager {\n  static #instance: SequenceManager | null = null\n\n  #registrations: Map<string, SequenceRegistration> = new Map()\n  #keydownListener: ((event: KeyboardEvent) => void) | null = null\n  #platform: 'mac' | 'windows' | 'linux'\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of SequenceManager.\n   */\n  static getInstance(): SequenceManager {\n    if (!SequenceManager.#instance) {\n      SequenceManager.#instance = new SequenceManager()\n    }\n    return SequenceManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (SequenceManager.#instance) {\n      SequenceManager.#instance.destroy()\n      SequenceManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey sequence handler.\n   *\n   * @param sequence - Array of hotkey strings that form the sequence\n   * @param callback - Function to call when the sequence is completed\n   * @param options - Options for the sequence behavior\n   * @returns A function to unregister the sequence\n   */\n  register(\n    sequence: HotkeySequence,\n    callback: HotkeyCallback,\n    options: SequenceOptions = {},\n  ): () => void {\n    if (sequence.length === 0) {\n      throw new Error('Sequence must contain at least one hotkey')\n    }\n\n    const id = generateSequenceId()\n    const platform = options.platform ?? this.#platform\n    const parsedSequence = sequence.map((hotkey) =>\n      parseHotkey(hotkey, platform),\n    )\n\n    const registration: SequenceRegistration = {\n      id,\n      sequence,\n      parsedSequence,\n      callback,\n      options: {\n        timeout: DEFAULT_SEQUENCE_TIMEOUT,\n        preventDefault: true,\n        stopPropagation: true,\n        enabled: true,\n        ...options,\n        platform,\n      },\n      currentIndex: 0,\n      lastKeyTime: 0,\n    }\n\n    this.#registrations.set(id, registration)\n    this.#ensureListener()\n\n    return () => {\n      this.#unregister(id)\n    }\n  }\n\n  /**\n   * Unregisters a sequence by its registration ID.\n   */\n  #unregister(id: string): void {\n    this.#registrations.delete(id)\n\n    if (this.#registrations.size === 0) {\n      this.#removeListener()\n    }\n  }\n\n  /**\n   * Ensures the keydown listener is attached.\n   */\n  #ensureListener(): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    if (!this.#keydownListener) {\n      this.#keydownListener = this.#handleKeyDown.bind(this)\n      document.addEventListener('keydown', this.#keydownListener)\n    }\n  }\n\n  /**\n   * Removes the keydown listener.\n   */\n  #removeListener(): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    if (this.#keydownListener) {\n      document.removeEventListener('keydown', this.#keydownListener)\n      this.#keydownListener = null\n    }\n  }\n\n  /**\n   * Handles keydown events for sequence matching.\n   */\n  #handleKeyDown(event: KeyboardEvent): void {\n    const now = Date.now()\n\n    for (const registration of this.#registrations.values()) {\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      const timeout = registration.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT\n\n      // Check if sequence has timed out\n      if (\n        registration.currentIndex > 0 &&\n        now - registration.lastKeyTime > timeout\n      ) {\n        // Reset the sequence\n        registration.currentIndex = 0\n      }\n\n      const expectedHotkey =\n        registration.parsedSequence[registration.currentIndex]\n      if (!expectedHotkey) {\n        continue\n      }\n\n      // Check if current key matches the expected key in sequence\n      if (\n        matchesKeyboardEvent(\n          event,\n          expectedHotkey,\n          registration.options.platform,\n        )\n      ) {\n        registration.lastKeyTime = now\n        registration.currentIndex++\n\n        // Check if sequence is complete\n        if (registration.currentIndex >= registration.parsedSequence.length) {\n          // Sequence complete!\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          const context: HotkeyCallbackContext = {\n            hotkey: registration.sequence.join(' ') as Hotkey,\n            parsedHotkey:\n              registration.parsedSequence[\n                registration.parsedSequence.length - 1\n              ]!,\n          }\n\n          registration.callback(event, context)\n\n          // Reset for next sequence\n          registration.currentIndex = 0\n        }\n      } else if (registration.currentIndex > 0) {\n        // Key didn't match and we were in the middle of a sequence\n        // Check if it matches the start of the sequence (for overlapping sequences)\n        const firstHotkey = registration.parsedSequence[0]!\n        if (\n          matchesKeyboardEvent(\n            event,\n            firstHotkey,\n            registration.options.platform,\n          )\n        ) {\n          registration.currentIndex = 1\n          registration.lastKeyTime = now\n        } else {\n          // Reset the sequence\n          registration.currentIndex = 0\n        }\n      }\n    }\n  }\n\n  /**\n   * Resets all sequence progress.\n   */\n  resetAll(): void {\n    for (const registration of this.#registrations.values()) {\n      registration.currentIndex = 0\n      registration.lastKeyTime = 0\n    }\n  }\n\n  /**\n   * Gets the number of registered sequences.\n   */\n  getRegistrationCount(): number {\n    return this.#registrations.size\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    this.#removeListener()\n    this.#registrations.clear()\n  }\n}\n\n/**\n * Gets the singleton SequenceManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getSequenceManager(): SequenceManager {\n  return SequenceManager.getInstance()\n}\n\n/**\n * Creates a simple sequence matcher for one-off use.\n *\n * @param sequence - The sequence of hotkeys to match\n * @param options - Options including timeout\n * @returns An object with match() and reset() methods\n *\n * @example\n * ```ts\n * const matcher = createSequenceMatcher(['G', 'G'], { timeout: 500 })\n *\n * document.addEventListener('keydown', (event) => {\n *   if (matcher.match(event)) {\n *     console.log('Sequence matched!')\n *   }\n * })\n * ```\n */\nexport function createSequenceMatcher(\n  sequence: HotkeySequence,\n  options: { timeout?: number; platform?: 'mac' | 'windows' | 'linux' } = {},\n): {\n  match: (event: KeyboardEvent) => boolean\n  reset: () => void\n  getProgress: () => number\n} {\n  const platform = options.platform ?? detectPlatform()\n  const timeout = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT\n  const parsedSequence = sequence.map((hotkey) => parseHotkey(hotkey, platform))\n\n  let currentIndex = 0\n  let lastKeyTime = 0\n\n  return {\n    match(event: KeyboardEvent): boolean {\n      const now = Date.now()\n\n      // Check timeout\n      if (currentIndex > 0 && now - lastKeyTime > timeout) {\n        currentIndex = 0\n      }\n\n      const expected = parsedSequence[currentIndex]\n      if (!expected) {\n        return false\n      }\n\n      if (matchesKeyboardEvent(event, expected, platform)) {\n        lastKeyTime = now\n        currentIndex++\n\n        if (currentIndex >= parsedSequence.length) {\n          currentIndex = 0\n          return true\n        }\n      } else if (currentIndex > 0) {\n        // Check if it matches start of sequence\n        if (matchesKeyboardEvent(event, parsedSequence[0]!, platform)) {\n          currentIndex = 1\n          lastKeyTime = now\n        } else {\n          currentIndex = 0\n        }\n      }\n\n      return false\n    },\n\n    reset(): void {\n      currentIndex = 0\n      lastKeyTime = 0\n    },\n\n    getProgress(): number {\n      return currentIndex\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/validate.cjs

@@ -0,0 +1,116 @@
+const require_constants = require('./constants.cjs');
+
+//#region src/validate.ts
+/**
+* Validates a hotkey string and returns any warnings or errors.
+*
+* Checks for:
+* - Valid syntax (modifier+...+key format)
+* - Known modifiers
+* - Known keys
+*
+* @param hotkey - The hotkey string to validate
+* @returns A ValidationResult with validity status, warnings, and errors
+*
+* @example
+* ```ts
+* validateHotkey('Mod+S')
+* // { valid: true, warnings: [], errors: [] }
+*
+* validateHotkey('')
+* // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+* ```
+*/
+function validateHotkey(hotkey) {
+	const warnings = [];
+	const errors = [];
+	if (!hotkey || hotkey.trim() === "") return {
+		valid: false,
+		warnings: [],
+		errors: ["Hotkey cannot be empty"]
+	};
+	const parts = hotkey.split("+").map((p) => p.trim());
+	if (parts.length === 0 || parts.some((p) => p === "")) return {
+		valid: false,
+		warnings: [],
+		errors: ["Invalid hotkey format: empty parts detected"]
+	};
+	const modifierParts = parts.slice(0, -1);
+	const keyPart = parts[parts.length - 1];
+	for (const modifier of modifierParts) if (!(require_constants.MODIFIER_ALIASES[modifier] ?? require_constants.MODIFIER_ALIASES[modifier.toLowerCase()])) errors.push(`Unknown modifier: '${modifier}'`);
+	if (!isKnownKey(normalizeKeyForValidation(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	return {
+		valid: errors.length === 0,
+		warnings,
+		errors
+	};
+}
+/**
+* Normalizes a key for validation checking.
+*/
+function normalizeKeyForValidation(key) {
+	if (key.length === 1 && /^[a-zA-Z]$/.test(key)) return key.toUpperCase();
+	if (/^f([1-9]|1[0-2])$/i.test(key)) return key.toUpperCase();
+	return key;
+}
+/**
+* Checks if a key is in the known keys set.
+*/
+function isKnownKey(key) {
+	if (require_constants.ALL_KEYS.has(key)) return true;
+	if (key.length === 1 && require_constants.ALL_KEYS.has(key.toUpperCase())) return true;
+	return key in {
+		Esc: true,
+		Return: true,
+		Space: true,
+		" ": true,
+		Del: true,
+		Up: true,
+		Down: true,
+		Left: true,
+		Right: true
+	};
+}
+/**
+* Validates a hotkey and throws an error if invalid.
+* Useful for development-time validation.
+*
+* @param hotkey - The hotkey string to validate
+* @throws Error if the hotkey is invalid
+*
+* @example
+* ```ts
+* assertValidHotkey('Mod+S') // OK
+* assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+* ```
+*/
+function assertValidHotkey(hotkey) {
+	const result = validateHotkey(hotkey);
+	if (!result.valid) throw new Error(`Invalid hotkey '${hotkey}': ${result.errors.join(", ")}`);
+}
+/**
+* Validates a hotkey and logs warnings to the console.
+* Useful for development-time feedback.
+*
+* @param hotkey - The hotkey string to validate
+* @returns True if the hotkey is valid (may still have warnings)
+*
+* @example
+* ```ts
+* checkHotkey('Alt+C')
+* // Console: Warning: Alt+C may not work reliably on macOS...
+* // Returns: true
+* ```
+*/
+function checkHotkey(hotkey) {
+	const result = validateHotkey(hotkey);
+	if (result.errors.length > 0) console.error(`Hotkey '${hotkey}' errors:`, result.errors.join("; "));
+	if (result.warnings.length > 0) console.warn(`Hotkey '${hotkey}' warnings:`, result.warnings.join("; "));
+	return result.valid;
+}
+
+//#endregion
+exports.assertValidHotkey = assertValidHotkey;
+exports.checkHotkey = checkHotkey;
+exports.validateHotkey = validateHotkey;
+//# sourceMappingURL=validate.cjs.map

package/dist/validate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.cjs","names":["MODIFIER_ALIASES","ALL_KEYS"],"sources":["../src/validate.ts"],"sourcesContent":["import { ALL_KEYS, MODIFIER_ALIASES } from './constants'\nimport type { Hotkey, ValidationResult } from './hotkey'\n\n/**\n * Validates a hotkey string and returns any warnings or errors.\n *\n * Checks for:\n * - Valid syntax (modifier+...+key format)\n * - Known modifiers\n * - Known keys\n *\n * @param hotkey - The hotkey string to validate\n * @returns A ValidationResult with validity status, warnings, and errors\n *\n * @example\n * ```ts\n * validateHotkey('Mod+S')\n * // { valid: true, warnings: [], errors: [] }\n *\n * validateHotkey('')\n * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }\n * ```\n */\nexport function validateHotkey(\n  hotkey: Hotkey | (string & {}),\n): ValidationResult {\n  const warnings: Array<string> = []\n  const errors: Array<string> = []\n\n  // Check for empty string\n  if (!hotkey || hotkey.trim() === '') {\n    return {\n      valid: false,\n      warnings: [],\n      errors: ['Hotkey cannot be empty'],\n    }\n  }\n\n  const parts = hotkey.split('+').map((p) => p.trim())\n\n  // Must have at least one part (the key)\n  if (parts.length === 0 || parts.some((p) => p === '')) {\n    return {\n      valid: false,\n      warnings: [],\n      errors: ['Invalid hotkey format: empty parts detected'],\n    }\n  }\n\n  // Validate modifiers (all parts except the last)\n  const modifierParts = parts.slice(0, -1)\n  const keyPart = parts[parts.length - 1]!\n\n  // Check for unknown modifiers\n  for (const modifier of modifierParts) {\n    const normalized =\n      MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()]\n    if (!normalized) {\n      errors.push(`Unknown modifier: '${modifier}'`)\n    }\n  }\n\n  // Check if key is known\n  const normalizedKey = normalizeKeyForValidation(keyPart)\n  if (!isKnownKey(normalizedKey) && !isKnownKey(keyPart)) {\n    warnings.push(\n      `Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`,\n    )\n  }\n\n  return {\n    valid: errors.length === 0,\n    warnings,\n    errors,\n  }\n}\n\n/**\n * Normalizes a key for validation checking.\n */\nfunction normalizeKeyForValidation(key: string): string {\n  // Single letter to uppercase\n  if (key.length === 1 && /^[a-zA-Z]$/.test(key)) {\n    return key.toUpperCase()\n  }\n\n  // Function keys to uppercase\n  if (/^f([1-9]|1[0-2])$/i.test(key)) {\n    return key.toUpperCase()\n  }\n\n  return key\n}\n\n/**\n * Checks if a key is in the known keys set.\n */\nfunction isKnownKey(key: string): boolean {\n  // Check direct match\n  if (ALL_KEYS.has(key as any)) {\n    return true\n  }\n\n  // Check uppercase version for letters\n  if (key.length === 1 && ALL_KEYS.has(key.toUpperCase() as any)) {\n    return true\n  }\n\n  // Check common aliases\n  const aliases: Record<string, boolean> = {\n    Esc: true,\n    Return: true,\n    Space: true,\n    ' ': true,\n    Del: true,\n    Up: true,\n    Down: true,\n    Left: true,\n    Right: true,\n  }\n\n  return key in aliases\n}\n\n/**\n * Validates a hotkey and throws an error if invalid.\n * Useful for development-time validation.\n *\n * @param hotkey - The hotkey string to validate\n * @throws Error if the hotkey is invalid\n *\n * @example\n * ```ts\n * assertValidHotkey('Mod+S') // OK\n * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty\n * ```\n */\nexport function assertValidHotkey(hotkey: Hotkey | (string & {})): void {\n  const result = validateHotkey(hotkey)\n  if (!result.valid) {\n    throw new Error(`Invalid hotkey '${hotkey}': ${result.errors.join(', ')}`)\n  }\n}\n\n/**\n * Validates a hotkey and logs warnings to the console.\n * Useful for development-time feedback.\n *\n * @param hotkey - The hotkey string to validate\n * @returns True if the hotkey is valid (may still have warnings)\n *\n * @example\n * ```ts\n * checkHotkey('Alt+C')\n * // Console: Warning: Alt+C may not work reliably on macOS...\n * // Returns: true\n * ```\n */\nexport function checkHotkey(hotkey: Hotkey | (string & {})): boolean {\n  const result = validateHotkey(hotkey)\n\n  if (result.errors.length > 0) {\n    console.error(`Hotkey '${hotkey}' errors:`, result.errors.join('; '))\n  }\n\n  if (result.warnings.length > 0) {\n    console.warn(`Hotkey '${hotkey}' warnings:`, result.warnings.join('; '))\n  }\n\n  return result.valid\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,eACd,QACkB;CAClB,MAAM,WAA0B,EAAE;CAClC,MAAM,SAAwB,EAAE;AAGhC,KAAI,CAAC,UAAU,OAAO,MAAM,KAAK,GAC/B,QAAO;EACL,OAAO;EACP,UAAU,EAAE;EACZ,QAAQ,CAAC,yBAAyB;EACnC;CAGH,MAAM,QAAQ,OAAO,MAAM,IAAI,CAAC,KAAK,MAAM,EAAE,MAAM,CAAC;AAGpD,KAAI,MAAM,WAAW,KAAK,MAAM,MAAM,MAAM,MAAM,GAAG,CACnD,QAAO;EACL,OAAO;EACP,UAAU,EAAE;EACZ,QAAQ,CAAC,8CAA8C;EACxD;CAIH,MAAM,gBAAgB,MAAM,MAAM,GAAG,GAAG;CACxC,MAAM,UAAU,MAAM,MAAM,SAAS;AAGrC,MAAK,MAAM,YAAY,cAGrB,KAAI,EADFA,mCAAiB,aAAaA,mCAAiB,SAAS,aAAa,GAErE,QAAO,KAAK,sBAAsB,SAAS,GAAG;AAMlD,KAAI,CAAC,WADiB,0BAA0B,QAAQ,CAC1B,IAAI,CAAC,WAAW,QAAQ,CACpD,UAAS,KACP,iBAAiB,QAAQ,+DAC1B;AAGH,QAAO;EACL,OAAO,OAAO,WAAW;EACzB;EACA;EACD;;;;;AAMH,SAAS,0BAA0B,KAAqB;AAEtD,KAAI,IAAI,WAAW,KAAK,aAAa,KAAK,IAAI,CAC5C,QAAO,IAAI,aAAa;AAI1B,KAAI,qBAAqB,KAAK,IAAI,CAChC,QAAO,IAAI,aAAa;AAG1B,QAAO;;;;;AAMT,SAAS,WAAW,KAAsB;AAExC,KAAIC,2BAAS,IAAI,IAAW,CAC1B,QAAO;AAIT,KAAI,IAAI,WAAW,KAAKA,2BAAS,IAAI,IAAI,aAAa,CAAQ,CAC5D,QAAO;AAgBT,QAAO,OAZkC;EACvC,KAAK;EACL,QAAQ;EACR,OAAO;EACP,KAAK;EACL,KAAK;EACL,IAAI;EACJ,MAAM;EACN,MAAM;EACN,OAAO;EACR;;;;;;;;;;;;;;;AAkBH,SAAgB,kBAAkB,QAAsC;CACtE,MAAM,SAAS,eAAe,OAAO;AACrC,KAAI,CAAC,OAAO,MACV,OAAM,IAAI,MAAM,mBAAmB,OAAO,KAAK,OAAO,OAAO,KAAK,KAAK,GAAG;;;;;;;;;;;;;;;;AAkB9E,SAAgB,YAAY,QAAyC;CACnE,MAAM,SAAS,eAAe,OAAO;AAErC,KAAI,OAAO,OAAO,SAAS,EACzB,SAAQ,MAAM,WAAW,OAAO,YAAY,OAAO,OAAO,KAAK,KAAK,CAAC;AAGvE,KAAI,OAAO,SAAS,SAAS,EAC3B,SAAQ,KAAK,WAAW,OAAO,cAAc,OAAO,SAAS,KAAK,KAAK,CAAC;AAG1E,QAAO,OAAO"}

package/dist/validate.d.cts

@@ -0,0 +1,56 @@
+import { Hotkey, ValidationResult } from "./hotkey.cjs";
+
+//#region src/validate.d.ts
+/**
+ * Validates a hotkey string and returns any warnings or errors.
+ *
+ * Checks for:
+ * - Valid syntax (modifier+...+key format)
+ * - Known modifiers
+ * - Known keys
+ *
+ * @param hotkey - The hotkey string to validate
+ * @returns A ValidationResult with validity status, warnings, and errors
+ *
+ * @example
+ * ```ts
+ * validateHotkey('Mod+S')
+ * // { valid: true, warnings: [], errors: [] }
+ *
+ * validateHotkey('')
+ * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+ * ```
+ */
+declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResult;
+/**
+ * Validates a hotkey and throws an error if invalid.
+ * Useful for development-time validation.
+ *
+ * @param hotkey - The hotkey string to validate
+ * @throws Error if the hotkey is invalid
+ *
+ * @example
+ * ```ts
+ * assertValidHotkey('Mod+S') // OK
+ * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+ * ```
+ */
+declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
+/**
+ * Validates a hotkey and logs warnings to the console.
+ * Useful for development-time feedback.
+ *
+ * @param hotkey - The hotkey string to validate
+ * @returns True if the hotkey is valid (may still have warnings)
+ *
+ * @example
+ * ```ts
+ * checkHotkey('Alt+C')
+ * // Console: Warning: Alt+C may not work reliably on macOS...
+ * // Returns: true
+ * ```
+ */
+declare function checkHotkey(hotkey: Hotkey | (string & {})): boolean;
+//#endregion
+export { assertValidHotkey, checkHotkey, validateHotkey };
+//# sourceMappingURL=validate.d.cts.map

package/dist/validate.d.ts

@@ -0,0 +1,56 @@
+import { Hotkey, ValidationResult } from "./hotkey.js";
+
+//#region src/validate.d.ts
+/**
+ * Validates a hotkey string and returns any warnings or errors.
+ *
+ * Checks for:
+ * - Valid syntax (modifier+...+key format)
+ * - Known modifiers
+ * - Known keys
+ *
+ * @param hotkey - The hotkey string to validate
+ * @returns A ValidationResult with validity status, warnings, and errors
+ *
+ * @example
+ * ```ts
+ * validateHotkey('Mod+S')
+ * // { valid: true, warnings: [], errors: [] }
+ *
+ * validateHotkey('')
+ * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+ * ```
+ */
+declare function validateHotkey(hotkey: Hotkey | (string & {})): ValidationResult;
+/**
+ * Validates a hotkey and throws an error if invalid.
+ * Useful for development-time validation.
+ *
+ * @param hotkey - The hotkey string to validate
+ * @throws Error if the hotkey is invalid
+ *
+ * @example
+ * ```ts
+ * assertValidHotkey('Mod+S') // OK
+ * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+ * ```
+ */
+declare function assertValidHotkey(hotkey: Hotkey | (string & {})): void;
+/**
+ * Validates a hotkey and logs warnings to the console.
+ * Useful for development-time feedback.
+ *
+ * @param hotkey - The hotkey string to validate
+ * @returns True if the hotkey is valid (may still have warnings)
+ *
+ * @example
+ * ```ts
+ * checkHotkey('Alt+C')
+ * // Console: Warning: Alt+C may not work reliably on macOS...
+ * // Returns: true
+ * ```
+ */
+declare function checkHotkey(hotkey: Hotkey | (string & {})): boolean;
+//#endregion
+export { assertValidHotkey, checkHotkey, validateHotkey };
+//# sourceMappingURL=validate.d.ts.map