@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/recorder.d.ts

@@ -0,0 +1,108 @@
+import { Hotkey } from "./hotkey.js";
+import { Store } from "@tanstack/store";
+
+//#region src/recorder.d.ts
+/**
+ * State interface for the HotkeyRecorder.
+ */
+interface HotkeyRecorderState {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** The currently recorded hotkey (for live preview) */
+  recordedHotkey: Hotkey | null;
+}
+/**
+ * Options for configuring a HotkeyRecorder instance.
+ */
+interface HotkeyRecorderOptions {
+  /** Callback when a hotkey is successfully recorded */
+  onRecord: (hotkey: Hotkey) => void;
+  /** Optional callback when recording is cancelled (Escape pressed) */
+  onCancel?: () => void;
+  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */
+  onClear?: () => void;
+}
+/**
+ * Framework-agnostic class for recording keyboard shortcuts.
+ *
+ * This class handles all the complexity of capturing keyboard events,
+ * converting them to hotkey strings, and handling edge cases like
+ * Escape to cancel or Backspace/Delete to clear.
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - State can be accessed via `recorder.store.state` when using the class directly
+ * - When using framework adapters (React), use `useStore` hooks for reactive state
+ *
+ * @example
+ * ```ts
+ * const recorder = new HotkeyRecorder({
+ *   onRecord: (hotkey) => {
+ *     console.log('Recorded:', hotkey)
+ *   },
+ *   onCancel: () => {
+ *     console.log('Recording cancelled')
+ *   },
+ * })
+ *
+ * // Start recording
+ * recorder.start()
+ *
+ * // Access state directly
+ * console.log(recorder.store.state.isRecording) // true
+ *
+ * // Subscribe to changes with TanStack Store
+ * const unsubscribe = recorder.store.subscribe(() => {
+ *   console.log('Recording:', recorder.store.state.isRecording)
+ * })
+ *
+ * // Cleanup
+ * recorder.destroy()
+ * unsubscribe()
+ * ```
+ */
+declare class HotkeyRecorder {
+  #private;
+  /**
+   * The TanStack Store instance containing the recorder state.
+   * Use this to subscribe to state changes or access current state.
+   */
+  readonly store: Store<HotkeyRecorderState>;
+  constructor(options: HotkeyRecorderOptions);
+  /**
+   * Updates the recorder options, including callbacks.
+   * This allows framework adapters to sync callback changes without recreating the recorder.
+   */
+  setOptions(options: Partial<HotkeyRecorderOptions>): void;
+  /**
+   * Start recording a new hotkey.
+   *
+   * Sets up a keydown event listener that captures keyboard events
+   * and converts them to hotkey strings. Recording continues until
+   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
+   */
+  start(): void;
+  /**
+   * Stop recording (same as cancel, but doesn't call onCancel).
+   *
+   * Removes the event listener and resets the recording state.
+   */
+  stop(): void;
+  /**
+   * Cancel recording without saving.
+   *
+   * Removes the event listener, resets the recording state, and calls
+   * the onCancel callback if provided.
+   */
+  cancel(): void;
+  /**
+   * Clean up event listeners and reset state.
+   *
+   * Call this when you're done with the recorder to ensure
+   * all event listeners are properly removed.
+   */
+  destroy(): void;
+}
+//#endregion
+export { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState };
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.js

@@ -0,0 +1,177 @@
+import { detectPlatform } from "./constants.js";
+import { convertToModFormat, hasNonModifierKey, isModifierKey, keyboardEventToHotkey } from "./parse.js";
+import { Store } from "@tanstack/store";
+
+//#region src/recorder.ts
+/**
+* Framework-agnostic class for recording keyboard shortcuts.
+*
+* This class handles all the complexity of capturing keyboard events,
+* converting them to hotkey strings, and handling edge cases like
+* Escape to cancel or Backspace/Delete to clear.
+*
+* State Management:
+* - Uses TanStack Store for reactive state management
+* - State can be accessed via `recorder.store.state` when using the class directly
+* - When using framework adapters (React), use `useStore` hooks for reactive state
+*
+* @example
+* ```ts
+* const recorder = new HotkeyRecorder({
+*   onRecord: (hotkey) => {
+*     console.log('Recorded:', hotkey)
+*   },
+*   onCancel: () => {
+*     console.log('Recording cancelled')
+*   },
+* })
+*
+* // Start recording
+* recorder.start()
+*
+* // Access state directly
+* console.log(recorder.store.state.isRecording) // true
+*
+* // Subscribe to changes with TanStack Store
+* const unsubscribe = recorder.store.subscribe(() => {
+*   console.log('Recording:', recorder.store.state.isRecording)
+* })
+*
+* // Cleanup
+* recorder.destroy()
+* unsubscribe()
+* ```
+*/
+var HotkeyRecorder = class {
+	#keydownHandler = null;
+	#options;
+	#platform;
+	constructor(options) {
+		this.store = new Store({
+			isRecording: false,
+			recordedHotkey: null
+		});
+		this.#options = options;
+		this.#platform = detectPlatform();
+	}
+	/**
+	* Updates the recorder options, including callbacks.
+	* This allows framework adapters to sync callback changes without recreating the recorder.
+	*/
+	setOptions(options) {
+		this.#options = {
+			...this.#options,
+			...options
+		};
+	}
+	/**
+	* Start recording a new hotkey.
+	*
+	* Sets up a keydown event listener that captures keyboard events
+	* and converts them to hotkey strings. Recording continues until
+	* a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.
+	*/
+	start() {
+		if (this.#keydownHandler) return;
+		this.store.setState(() => ({
+			isRecording: true,
+			recordedHotkey: null
+		}));
+		const handler = (event) => {
+			if (!this.#keydownHandler) return;
+			event.preventDefault();
+			event.stopPropagation();
+			if (event.key === "Escape") {
+				this.cancel();
+				return;
+			}
+			if (event.key === "Backspace" || event.key === "Delete") {
+				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) {
+					this.#options.onClear?.();
+					this.#options.onRecord("");
+					this.stop();
+					return;
+				}
+			}
+			if (isModifierKey(event)) return;
+			const finalHotkey = convertToModFormat(keyboardEventToHotkey(event), this.#platform);
+			if (hasNonModifierKey(finalHotkey, this.#platform)) {
+				const handlerToRemove = this.#keydownHandler;
+				if (handlerToRemove) {
+					this.#removeListener(handlerToRemove);
+					this.#keydownHandler = null;
+				}
+				this.store.setState(() => ({
+					isRecording: false,
+					recordedHotkey: finalHotkey
+				}));
+				this.#options.onRecord(finalHotkey);
+			}
+		};
+		this.#keydownHandler = handler;
+		this.#addListener(handler);
+	}
+	/**
+	* Stop recording (same as cancel, but doesn't call onCancel).
+	*
+	* Removes the event listener and resets the recording state.
+	*/
+	stop() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.store.setState(() => ({
+			isRecording: false,
+			recordedHotkey: null
+		}));
+	}
+	/**
+	* Cancel recording without saving.
+	*
+	* Removes the event listener, resets the recording state, and calls
+	* the onCancel callback if provided.
+	*/
+	cancel() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.store.setState(() => ({
+			isRecording: false,
+			recordedHotkey: null
+		}));
+		this.#options.onCancel?.();
+	}
+	/**
+	* Adds the keydown event listener to the document.
+	*/
+	#addListener(handler) {
+		if (typeof document === "undefined") return;
+		document.addEventListener("keydown", handler, true);
+	}
+	/**
+	* Removes the keydown event listener from the document.
+	*/
+	#removeListener(handler) {
+		if (typeof document === "undefined") return;
+		document.removeEventListener("keydown", handler, true);
+	}
+	/**
+	* Clean up event listeners and reset state.
+	*
+	* Call this when you're done with the recorder to ensure
+	* all event listeners are properly removed.
+	*/
+	destroy() {
+		this.stop();
+		this.store.setState(() => ({
+			isRecording: false,
+			recordedHotkey: null
+		}));
+	}
+};
+
+//#endregion
+export { HotkeyRecorder };
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport {\n  convertToModFormat,\n  hasNonModifierKey,\n  isModifierKey,\n  keyboardEventToHotkey,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      // Ignore pure modifier keys (wait for a non-modifier key)\n      if (isModifierKey(event)) {\n        return\n      }\n\n      // Convert event to hotkey string using library function\n      const hotkey = keyboardEventToHotkey(event)\n\n      // Always convert to Mod format for portability\n      const finalHotkey = convertToModFormat(hotkey, this.#platform)\n\n      // Validate: must have at least one non-modifier key\n      if (hasNonModifierKey(finalHotkey, this.#platform)) {\n        // Remove listener FIRST to prevent any additional events\n        const handlerToRemove = this.#keydownHandler as\n          | ((event: KeyboardEvent) => void)\n          | null\n        if (handlerToRemove) {\n          this.#removeListener(handlerToRemove)\n          this.#keydownHandler = null\n        }\n\n        // Update store state immediately\n        this.store.setState(() => ({\n          isRecording: false,\n          recordedHotkey: finalHotkey,\n        }))\n\n        // Call callback AFTER listener is removed and state is set\n        this.#options.onRecord(finalHotkey)\n      }\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAGF,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKF,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;AAKJ,OAAI,cAAc,MAAM,CACtB;GAOF,MAAM,cAAc,mBAHL,sBAAsB,MAAM,EAGI,MAAKC,SAAU;AAG9D,OAAI,kBAAkB,aAAa,MAAKA,SAAU,EAAE;IAElD,MAAM,kBAAkB,MAAKC;AAG7B,QAAI,iBAAiB;AACnB,WAAKC,eAAgB,gBAAgB;AACrC,WAAKD,iBAAkB;;AAIzB,SAAK,MAAM,gBAAgB;KACzB,aAAa;KACb,gBAAgB;KACjB,EAAE;AAGH,UAAKF,QAAS,SAAS,YAAY;;;AAIvC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}

package/dist/sequence.cjs

@@ -0,0 +1,242 @@
+const require_constants = require('./constants.cjs');
+const require_parse = require('./parse.cjs');
+const require_match = require('./match.cjs');
+
+//#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 = require_constants.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) => require_parse.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 (require_match.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 (require_match.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 ?? require_constants.detectPlatform();
+	const timeout = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+	const parsedSequence = sequence.map((hotkey) => require_parse.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 (require_match.matchesKeyboardEvent(event, expected, platform)) {
+				lastKeyTime = now;
+				currentIndex++;
+				if (currentIndex >= parsedSequence.length) {
+					currentIndex = 0;
+					return true;
+				}
+			} else if (currentIndex > 0) if (require_match.matchesKeyboardEvent(event, parsedSequence[0], platform)) {
+				currentIndex = 1;
+				lastKeyTime = now;
+			} else currentIndex = 0;
+			return false;
+		},
+		reset() {
+			currentIndex = 0;
+			lastKeyTime = 0;
+		},
+		getProgress() {
+			return currentIndex;
+		}
+	};
+}
+
+//#endregion
+exports.SequenceManager = SequenceManager;
+exports.createSequenceMatcher = createSequenceMatcher;
+exports.getSequenceManager = getSequenceManager;
+//# sourceMappingURL=sequence.cjs.map

package/dist/sequence.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.cjs","names":["#instance","#platform","detectPlatform","parseHotkey","#registrations","#ensureListener","#unregister","#removeListener","#keydownListener","#handleKeyDown","matchesKeyboardEvent"],"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/sequence.d.cts

@@ -0,0 +1,109 @@
+import { Hotkey, HotkeyCallback } from "./hotkey.cjs";
+import { HotkeyOptions } from "./hotkey-manager.cjs";
+
+//#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.cts.map