@tanstack/hotkeys 0.11.0 → 0.12.0

package/dist/hotkey-sequence-recorder.js

@@ -1,259 +0,0 @@
-import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isModifierKey, parseHotkey } from "./parse.js";
-import { validateHotkey } from "./validate.js";
-import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
-import { shouldIgnoreInputEvent } from "./_event-target.js";
-import { findHotkeyConflicts } from "./conflicts.js";
-import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
-import { Store } from "@tanstack/store";
-
-//#region src/hotkey-sequence-recorder.ts
-const defaultHotkeySequenceRecorderOptions = {
-	commitOnEnter: true,
-	commitKeys: "enter"
-};
-/** Resolves the Enter policy, with commitKeys: none overriding the legacy boolean. */
-function resolvedCommitOnEnter(options) {
-	if (options.commitKeys === "none") return false;
-	return options.commitOnEnter !== false;
-}
-/**
-* Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
-*
-* Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
-* when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
-* **Backspace/Delete** to remove the last step or clear when empty.
-*/
-var HotkeySequenceRecorder = class {
-	store = new Store({
-		isRecording: false,
-		steps: [],
-		recordedSequence: null
-	});
-	#keydownHandler = null;
-	#optionsSource;
-	#optionOverrides = {};
-	get #options() {
-		return {
-			...defaultHotkeySequenceRecorderOptions,
-			...typeof this.#optionsSource === "function" ? this.#optionsSource() : this.#optionsSource,
-			...this.#optionOverrides
-		};
-	}
-	#platform;
-	#events = [];
-	#idleTimer = null;
-	/** Options may be a getter to read current configuration during an active session. */
-	constructor(options) {
-		this.#optionsSource = options;
-		this.#platform = detectPlatform();
-	}
-	/** Merges current callbacks and options without discarding recorded steps. */
-	setOptions(options) {
-		this.#optionOverrides = {
-			...this.#optionOverrides,
-			...options
-		};
-	}
-	/** Cancels a pending idle commit so it cannot fire after editing or stopping. */
-	#clearIdleTimer() {
-		if (this.#idleTimer !== null) {
-			clearTimeout(this.#idleTimer);
-			this.#idleTimer = null;
-		}
-	}
-	/** Restarts optional idle commit after a step is recorded or edited. */
-	#scheduleIdleTimer() {
-		this.#clearIdleTimer();
-		const ms = this.#options.idleTimeoutMs;
-		if (ms === void 0 || ms <= 0) return;
-		if (this.store.state.steps.length === 0) return;
-		this.#idleTimer = setTimeout(() => {
-			this.#idleTimer = null;
-			if (!this.#keydownHandler) return;
-			if (this.store.state.steps.length >= 1) this.commit();
-		}, ms);
-	}
-	/** Publishes edited steps while preserving the remaining recorder state. */
-	#patchSteps(updater) {
-		this.store.setState((s) => ({
-			...s,
-			steps: updater(s.steps)
-		}));
-	}
-	/** Starts a fresh recording; repeated starts during an active session are ignored. */
-	start() {
-		if (this.#keydownHandler) return;
-		this.#clearIdleTimer();
-		this.#events = [];
-		beginRecording(this);
-		this.store.setState(() => ({
-			isRecording: true,
-			steps: [],
-			recordedSequence: null
-		}));
-		const handler = (event) => {
-			if (!this.#keydownHandler) return;
-			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && shouldIgnoreInputEvent(event, document, document)) return;
-			const platform = this.#options.platform ?? this.#platform;
-			if (normalizeKeyboardEvent(event, platform).isComposing) return;
-			captureRecordingEvent(event);
-			event.preventDefault();
-			event.stopPropagation();
-			if (event.repeat) return;
-			if (event.key === "Escape") {
-				this.cancel();
-				return;
-			}
-			if (event.key === "Backspace" || event.key === "Delete") {
-				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) {
-					if (this.store.state.steps.length === 0) {
-						this.stop();
-						this.#options.onClear?.();
-						return;
-					}
-					this.#events.pop();
-					this.#patchSteps((prev) => prev.slice(0, -1));
-					if (this.store.state.steps.length === 0) this.#clearIdleTimer();
-					else this.#scheduleIdleTimer();
-					return;
-				}
-			}
-			const enterCommits = resolvedCommitOnEnter(this.#options) && event.key === "Enter" && !event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey;
-			if (enterCommits && this.store.state.steps.length >= 1) {
-				this.commit();
-				return;
-			}
-			if (enterCommits && this.store.state.steps.length === 0) return;
-			if (isModifierKey(event.key) || event.key === "AltGraph") return;
-			const rejection = chordRejection(event, {
-				...this.#options,
-				platform
-			});
-			if (rejection) {
-				this.#options.onReject?.(rejection);
-				return;
-			}
-			const finalHotkey = hotkeyChordFromKeydown(event, platform, this.#options.recordBy);
-			if (finalHotkey === null) return;
-			const validation = validateHotkey(finalHotkey);
-			if (!validation.valid) {
-				this.#options.onReject?.({
-					reason: "invalid",
-					message: validation.errors.join("; "),
-					hotkey: finalHotkey
-				});
-				return;
-			}
-			this.#events.push(event);
-			this.#patchSteps((prev) => [...prev, finalHotkey]);
-			this.#scheduleIdleTimer();
-		};
-		this.#keydownHandler = handler;
-		this.#addListener(handler);
-	}
-	/**
-	* Commit the current steps as a sequence. No-op if fewer than one step.
-	*/
-	commit() {
-		const steps = this.store.state.steps;
-		if (steps.length < 1) return;
-		const sequence = [...steps];
-		const platform = this.#options.platform ?? this.#platform;
-		this.#clearIdleTimer();
-		const accepted = this.#options.validate?.(sequence, {
-			events: [...this.#events],
-			parsedSequence: sequence.map((step) => parseHotkey(step, platform))
-		});
-		if (accepted !== void 0 && accepted !== true) {
-			this.#options.onReject?.({
-				reason: "validation",
-				message: typeof accepted === "string" ? accepted : "This sequence is not allowed.",
-				sequence
-			});
-			return;
-		}
-		if (this.#options.detectConflicts) {
-			const conflicts = findHotkeyConflicts(sequence, {
-				...typeof this.#options.detectConflicts === "object" ? this.#options.detectConflicts : {},
-				platform,
-				events: this.#events
-			});
-			if (conflicts.length) {
-				this.#options.onReject?.({
-					reason: "conflict",
-					message: "This sequence conflicts with a registered binding.",
-					sequence,
-					conflicts
-				});
-				return;
-			}
-		}
-		endRecording(this);
-		this.#events = [];
-		if (this.#keydownHandler) {
-			this.#removeListener(this.#keydownHandler);
-			this.#keydownHandler = null;
-		}
-		this.#clearIdleTimer();
-		this.store.setState(() => ({
-			isRecording: false,
-			steps: [],
-			recordedSequence: sequence
-		}));
-		this.#options.onRecord(sequence);
-	}
-	/** Stops and discards in-progress steps without invoking onCancel. */
-	stop() {
-		endRecording(this);
-		this.#events = [];
-		if (this.#keydownHandler) {
-			this.#removeListener(this.#keydownHandler);
-			this.#keydownHandler = null;
-		}
-		this.#clearIdleTimer();
-		this.store.setState(() => ({
-			isRecording: false,
-			steps: [],
-			recordedSequence: null
-		}));
-	}
-	/** Stops, discards in-progress steps, and notifies onCancel. */
-	cancel() {
-		endRecording(this);
-		this.#events = [];
-		if (this.#keydownHandler) {
-			this.#removeListener(this.#keydownHandler);
-			this.#keydownHandler = null;
-		}
-		this.#clearIdleTimer();
-		this.store.setState(() => ({
-			isRecording: false,
-			steps: [],
-			recordedSequence: null
-		}));
-		this.#options.onCancel?.();
-	}
-	/** Captures keydowns before application handlers, with an SSR-safe document check. */
-	#addListener(handler) {
-		if (typeof document === "undefined") return;
-		document.addEventListener("keydown", handler, true);
-	}
-	/** Detaches the capture listener when recording ends. */
-	#removeListener(handler) {
-		if (typeof document === "undefined") return;
-		document.removeEventListener("keydown", handler, true);
-	}
-	destroy() {
-		this.stop();
-		this.store.setState(() => ({
-			isRecording: false,
-			steps: [],
-			recordedSequence: null
-		}));
-	}
-};
-
-//#endregion
-export { HotkeySequenceRecorder };

package/dist/sequence-manager.d.ts

@@ -1,169 +0,0 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.types.js";
-import { HotkeyOptions } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
-//#region src/sequence-manager.d.ts
-export type Target = HTMLElement | Document | Window;
-/**
- * Options for hotkey sequence matching.
- * Extends HotkeyOptions but excludes requireReset (not applicable to sequences).
- */
-export interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
-  /** Timeout between keys in milliseconds. Default: 1000 */
-  timeout?: number;
-}
-/**
- * A sequence of hotkeys for Vim-style shortcuts.
- *
- * Each element is one step (a `Hotkey` string). Steps may include modifiers;
- * the same modifier can appear on consecutive steps (e.g. `Shift+R` then
- * `Shift+T`). Modifier-only key events do not advance or reset matching—see
- * `SequenceManager`. Automatic keydown repeats and IME composition are also ignored.
- *
- * @example
- * ```ts
- * const gotoTop: HotkeySequence = ['G', 'G']  // gg
- * const deleteLine: HotkeySequence = ['D', 'D']  // dd
- * const deleteWord: HotkeySequence = ['D', 'I', 'W']  // diw
- * const chainedShift: HotkeySequence = ['Shift+R', 'Shift+T']
- * ```
- */
-export type HotkeySequence = Array<Hotkey>;
-/**
- * Default timeout between keys in a sequence (in milliseconds).
- * Exported for consumers that display sequence state (e.g. devtools).
- */
-export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
-/**
- * View of a sequence registration for devtools display.
- * Progress fields reflect an in-progress match (between first key and completion or timeout).
- */
-export interface SequenceRegistrationView {
-  id: string;
-  sequence: HotkeySequence;
-  options: SequenceOptions;
-  target: Target;
-  triggerCount: number;
-  /** Whether this sequence has been triggered at least once. */
-  hasFired: boolean;
-  /** Steps matched in the current attempt (0 when idle or just completed). */
-  matchedStepCount: number;
-  /** `Date.now()` when the last step in the current attempt matched; 0 if none. */
-  partialMatchLastKeyTime: number;
-}
-/**
- * Internal representation of a sequence registration.
- */
-export interface SequenceRegistration {
-  id: string;
-  sequence: HotkeySequence;
-  parsedSequence: Array<ParsedHotkey>;
-  callback: HotkeyCallback;
-  options: SequenceOptions;
-  target: Target;
-  currentIndex: number;
-  lastKeyTime: number;
-  triggerCount: number;
-  hasFired: boolean;
-}
-/**
- * A handle returned from SequenceManager.register() that allows updating
- * the callback and options without re-registering the sequence.
- *
- * @example
- * ```ts
- * const handle = manager.register(['G', 'G'], callback, options)
- *
- * handle.callback = newCallback
- * handle.setOptions({ timeout: 500 })
- * handle.unregister()
- * ```
- */
-export interface SequenceRegistrationHandle {
-  readonly id: string;
-  readonly isActive: boolean;
-  callback: HotkeyCallback;
-  setOptions: (options: Partial<SequenceOptions>) => void;
-  unregister: () => void;
-}
-export declare class SequenceManager {
-  #private;
-  /**
-   * The TanStack Store containing sequence registration views for devtools.
-   * Subscribe to this to observe registration changes.
-   */
-  readonly registrations: Store<Map<string, SequenceRegistrationView>>;
-  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 handle to update or unregister the sequence
-   */
-  register(sequence: HotkeySequence, callback: HotkeyCallback, options?: SequenceOptions): SequenceRegistrationHandle;
-  /**
-   * Resets all sequence progress.
-   */
-  resetAll(): void;
-  /**
-   * Triggers a sequence's callback programmatically from devtools.
-   * Creates a synthetic KeyboardEvent from the last key in the sequence.
-   *
-   * @param id - The registration ID to trigger
-   * @returns True if the registration was found and triggered
-   */
-  triggerSequence(id: string): boolean;
-  /**
-   * 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.
- */
-export declare function getSequenceManager(): SequenceManager;
-/**
- * Creates a simple sequence matcher for one-off use.
- *
- * This is a low-level helper that does not support ignoreInputs, target,
- * or other HotkeyOptions. Callers must handle input filtering themselves
- * if attaching to document.
- *
- * @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!')
- *   }
- * })
- * ```
- */
-export declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
-  timeout?: number;
-  platform?: 'mac' | 'windows' | 'linux';
-}): {
-  match: (event: KeyboardEvent) => boolean;
-  reset: () => void;
-  getProgress: () => number;
-};
-//#endregion