@tanstack/react-hotkeys 0.13.0 → 0.14.1

package/dist/useHotkeySequence.js

@@ -1,119 +0,0 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { isRef } from "./utils.js";
-import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
-import { useEffect, useRef } from "react";
-
-//#region src/useHotkeySequence.ts
-/**
-* React hook for registering a keyboard shortcut sequence (Vim-style).
-*
-* This hook allows you to register multi-key sequences like 'g g' or 'd d'
-* that trigger when the full sequence is pressed within a timeout.
-*
-* Each step may include modifiers. You can chain the same modifier across
-* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
-* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
-* advance the sequence or reset progress.
-*
-* @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. `enabled: false` keeps the registration (visible in devtools)
-*   and only suppresses firing; the hook updates the existing handle instead of unregistering.
-*
-* @example
-* ```tsx
-* function VimEditor() {
-*   // 'g g' to go to top
-*   useHotkeySequence(['G', 'G'], () => {
-*     scrollToTop()
-*   })
-*
-*   // 'd d' to delete line
-*   useHotkeySequence(['D', 'D'], () => {
-*     deleteLine()
-*   })
-*
-*   // 'd i w' to delete inner word
-*   useHotkeySequence(['D', 'I', 'W'], () => {
-*     deleteInnerWord()
-*   }, { timeout: 500 })
-*
-*   // Same modifier on consecutive steps (bare Shift between chords is ignored)
-*   useHotkeySequence(['Shift+R', 'Shift+T'], () => {
-*     nextAction()
-*   })
-*
-*   return <div>...</div>
-* }
-* ```
-*/
-function useHotkeySequence(sequence, callback, options = {}) {
-	const mergedOptions = {
-		...useDefaultHotkeysOptions().hotkeySequence,
-		...options
-	};
-	const manager = getSequenceManager();
-	const registrationRef = useRef(null);
-	const callbackRef = useRef(callback);
-	const optionsRef = useRef(mergedOptions);
-	const managerRef = useRef(manager);
-	const sequenceRef = useRef(sequence);
-	callbackRef.current = callback;
-	optionsRef.current = mergedOptions;
-	managerRef.current = manager;
-	sequenceRef.current = sequence;
-	const prevTargetRef = useRef(null);
-	const prevSequenceRef = useRef(null);
-	const hotkeySequenceString = formatHotkeySequence(sequence);
-	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
-	useEffect(() => {
-		if (sequenceRef.current.length === 0) {
-			if (registrationRef.current?.isActive) {
-				registrationRef.current.unregister();
-				registrationRef.current = null;
-			}
-			prevTargetRef.current = null;
-			prevSequenceRef.current = null;
-			return;
-		}
-		const resolvedTarget = isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
-		if (!resolvedTarget) {
-			if (registrationRef.current?.isActive) {
-				registrationRef.current.unregister();
-				registrationRef.current = null;
-			}
-			prevTargetRef.current = null;
-			prevSequenceRef.current = null;
-			return;
-		}
-		const targetChanged = prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
-		const sequenceChanged = prevSequenceRef.current !== null && prevSequenceRef.current !== hotkeySequenceString;
-		if (registrationRef.current?.isActive && (targetChanged || sequenceChanged)) {
-			registrationRef.current.unregister();
-			registrationRef.current = null;
-		}
-		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(sequenceRef.current, (event, context) => callbackRef.current(event, context), {
-			...optionsRef.current,
-			target: resolvedTarget
-		});
-		prevTargetRef.current = resolvedTarget;
-		prevSequenceRef.current = hotkeySequenceString;
-	});
-	useEffect(() => {
-		return () => {
-			if (registrationRef.current?.isActive) {
-				registrationRef.current.unregister();
-				registrationRef.current = null;
-			}
-		};
-	}, []);
-	useEffect(() => {
-		if (registrationRef.current?.isActive) {
-			registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
-			registrationRef.current.setOptions(optionsWithoutTarget);
-		}
-	});
-}
-
-//#endregion
-export { useHotkeySequence };

package/dist/useHotkeySequenceRecorder.d.ts

@@ -1,22 +0,0 @@
-import { HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
-//#region src/useHotkeySequenceRecorder.d.ts
-export interface ReactHotkeySequenceRecorder {
-  /** Whether recording is currently active */
-  isRecording: boolean;
-  /** Chords captured in the current session */
-  steps: HotkeySequence;
-  /** Last committed sequence */
-  recordedSequence: HotkeySequence | null;
-  startRecording: () => void;
-  stopRecording: () => void;
-  cancelRecording: () => void;
-  /** Commit current steps (no-op if empty) */
-  commitRecording: () => void;
-}
-/**
- * React hook for recording multi-chord sequences (Vim-style shortcuts).
- *
- * @param options - Configuration options for the hotkey sequence recorder
- */
-export declare function useHotkeySequenceRecorder(options: HotkeySequenceRecorderOptions): ReactHotkeySequenceRecorder;
-//#endregion

package/dist/useHotkeySequenceRecorder.js

@@ -1,40 +0,0 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { HotkeySequenceRecorder } from "@tanstack/hotkeys";
-import { useEffect, useRef } from "react";
-import { useSelector } from "@tanstack/react-store";
-
-//#region src/useHotkeySequenceRecorder.ts
-/**
-* React hook for recording multi-chord sequences (Vim-style shortcuts).
-*
-* @param options - Configuration options for the hotkey sequence recorder
-*/
-function useHotkeySequenceRecorder(options) {
-	const mergedOptions = {
-		...useDefaultHotkeysOptions().hotkeySequenceRecorder,
-		...options
-	};
-	const recorderRef = useRef(null);
-	if (!recorderRef.current) recorderRef.current = new HotkeySequenceRecorder(mergedOptions);
-	recorderRef.current.setOptions(mergedOptions);
-	const isRecording = useSelector(recorderRef.current.store, (state) => state.isRecording);
-	const steps = useSelector(recorderRef.current.store, (state) => state.steps);
-	const recordedSequence = useSelector(recorderRef.current.store, (state) => state.recordedSequence);
-	useEffect(() => {
-		return () => {
-			recorderRef.current?.destroy();
-		};
-	}, []);
-	return {
-		isRecording,
-		steps,
-		recordedSequence,
-		startRecording: () => recorderRef.current?.start(),
-		stopRecording: () => recorderRef.current?.stop(),
-		cancelRecording: () => recorderRef.current?.cancel(),
-		commitRecording: () => recorderRef.current?.commit()
-	};
-}
-
-//#endregion
-export { useHotkeySequenceRecorder };

package/dist/useHotkeySequences.d.ts

@@ -1,60 +0,0 @@
-import { UseHotkeySequenceOptions } from "./useHotkeySequence.js";
-import { HotkeyCallback, HotkeySequence } from "@tanstack/hotkeys";
-//#region src/useHotkeySequences.d.ts
-/**
- * A single sequence definition for use with `useHotkeySequences`.
- */
-export interface UseHotkeySequenceDefinition {
-  /** Array of hotkey strings that form the sequence */
-  sequence: HotkeySequence;
-  /** The function to call when the sequence is completed */
-  callback: HotkeyCallback;
-  /** Per-sequence options (merged on top of commonOptions) */
-  options?: UseHotkeySequenceOptions;
-}
-/**
- * React hook for registering multiple keyboard shortcut sequences at once (Vim-style).
- *
- * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
- * register variable-length lists without violating the rules of hooks.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * Callbacks and options are synced on every render to avoid stale closures.
- *
- * Definitions with an empty `sequence` are skipped (no registration).
- *
- * @param definitions - Array of sequence definitions to register
- * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
- *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
- *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
- *   via `setOptions` (no unregister/re-register churn).
- *
- * @example
- * ```tsx
- * function VimPalette() {
- *   useHotkeySequences([
- *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *     { sequence: ['D', 'D'], callback: () => deleteLine() },
- *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function DynamicSequences({ items }) {
- *   useHotkeySequences(
- *     items.map((item) => ({
- *       sequence: item.chords,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-export declare function useHotkeySequences(definitions: Array<UseHotkeySequenceDefinition>, commonOptions?: UseHotkeySequenceOptions): void;
-//#endregion

package/dist/useHotkeySequences.js

@@ -1,125 +0,0 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { isRef } from "./utils.js";
-import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
-import { useEffect, useRef } from "react";
-
-//#region src/useHotkeySequences.ts
-/**
-* React hook for registering multiple keyboard shortcut sequences at once (Vim-style).
-*
-* Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
-* register variable-length lists without violating the rules of hooks.
-*
-* Options are merged in this order:
-* HotkeysProvider defaults < commonOptions < per-definition options
-*
-* Callbacks and options are synced on every render to avoid stale closures.
-*
-* Definitions with an empty `sequence` are skipped (no registration).
-*
-* @param definitions - Array of sequence definitions to register
-* @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
-*   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
-*   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
-*   via `setOptions` (no unregister/re-register churn).
-*
-* @example
-* ```tsx
-* function VimPalette() {
-*   useHotkeySequences([
-*     { sequence: ['G', 'G'], callback: () => scrollToTop() },
-*     { sequence: ['D', 'D'], callback: () => deleteLine() },
-*     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
-*   ])
-* }
-* ```
-*
-* @example
-* ```tsx
-* function DynamicSequences({ items }) {
-*   useHotkeySequences(
-*     items.map((item) => ({
-*       sequence: item.chords,
-*       callback: item.action,
-*       options: { enabled: item.enabled },
-*     })),
-*     { preventDefault: true },
-*   )
-* }
-* ```
-*/
-function useHotkeySequences(definitions, commonOptions = {}) {
-	const defaultOptions = useDefaultHotkeysOptions().hotkeySequence;
-	const manager = getSequenceManager();
-	const registrationsRef = useRef(/* @__PURE__ */ new Map());
-	const definitionsRef = useRef(definitions);
-	const sequenceStringsRef = useRef([]);
-	const commonOptionsRef = useRef(commonOptions);
-	const defaultOptionsRef = useRef(defaultOptions);
-	const managerRef = useRef(manager);
-	const sequenceStrings = definitions.map((def) => formatHotkeySequence(def.sequence));
-	definitionsRef.current = definitions;
-	sequenceStringsRef.current = sequenceStrings;
-	commonOptionsRef.current = commonOptions;
-	defaultOptionsRef.current = defaultOptions;
-	managerRef.current = manager;
-	useEffect(() => {
-		const prevRegistrations = registrationsRef.current;
-		const nextRegistrations = /* @__PURE__ */ new Map();
-		const rows = [];
-		for (let i = 0; i < definitionsRef.current.length; i++) {
-			const def = definitionsRef.current[i];
-			const seqStr = sequenceStringsRef.current[i];
-			const seq = def.sequence;
-			if (seq.length === 0) continue;
-			const mergedOptions = {
-				...defaultOptionsRef.current,
-				...commonOptionsRef.current,
-				...def.options
-			};
-			const resolvedTarget = isRef(mergedOptions.target) ? mergedOptions.target.current : mergedOptions.target ?? (typeof document !== "undefined" ? document : null);
-			if (!resolvedTarget) continue;
-			const registrationKey = `${i}:${seqStr}`;
-			rows.push({
-				registrationKey,
-				def,
-				seq,
-				seqStr,
-				mergedOptions,
-				resolvedTarget
-			});
-		}
-		const nextKeys = new Set(rows.map((r) => r.registrationKey));
-		for (const [key, record] of prevRegistrations) if (!nextKeys.has(key) && record.handle.isActive) record.handle.unregister();
-		for (const row of rows) {
-			const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row;
-			const existing = prevRegistrations.get(registrationKey);
-			if (existing?.handle.isActive && existing.target === resolvedTarget) {
-				existing.handle.callback = def.callback;
-				const { target: _target, ...optionsWithoutTarget } = mergedOptions;
-				existing.handle.setOptions(optionsWithoutTarget);
-				nextRegistrations.set(registrationKey, existing);
-				continue;
-			}
-			if (existing?.handle.isActive) existing.handle.unregister();
-			const handle = managerRef.current.register(seq, def.callback, {
-				...mergedOptions,
-				target: resolvedTarget
-			});
-			nextRegistrations.set(registrationKey, {
-				handle,
-				target: resolvedTarget
-			});
-		}
-		registrationsRef.current = nextRegistrations;
-	});
-	useEffect(() => {
-		return () => {
-			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
-			registrationsRef.current = /* @__PURE__ */ new Map();
-		};
-	}, []);
-}
-
-//#endregion
-export { useHotkeySequences };