@tanstack/preact-hotkeys 0.13.0 → 0.14.0

package/dist/useHotkeyRecorder.d.ts

@@ -1,54 +1,58 @@
-import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { Hotkey, HotkeyChord, HotkeyChordRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 //#region src/useHotkeyRecorder.d.ts
-export interface PreactHotkeyRecorder {
+export interface PreactHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
   /** Whether recording is currently active */
   isRecording: boolean;
-  /** The currently recorded hotkey (for live preview) */
-  recordedHotkey: Hotkey | null;
+  /** Chords recorded so far in a multi-step recording (for live preview) */
+  steps: HotkeySequence;
+  /** The last committed hotkey */
+  recordedHotkey: THotkey | null;
   /** Start recording a new hotkey */
   startRecording: () => void;
-  /** Stop recording (same as cancel) */
+  /** Stop recording without calling onCancel */
   stopRecording: () => void;
-  /** Cancel recording without saving */
+  /** Cancel recording and call onCancel */
   cancelRecording: () => void;
+  /** Commit the recorded steps now (multi-step recordings) */
+  commitRecording: () => void;
 }
 /**
  * Preact hook for recording keyboard shortcuts.
  *
- * This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
- * class, managing 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.
+ * With the default `maxSteps: 1`, the first valid chord is recorded and
+ * `onRecord` receives a chord such as `'Mod+S'`. With a larger `maxSteps`, each
+ * chord adds a step; the recording commits on Enter (unless
+ * `commitKeys: 'none'`), after `idleTimeoutMs`, or when it reaches `maxSteps`,
+ * and `onRecord` receives a chord (one step) or a sequence.
+ *
+ * Escape cancels. Backspace/Delete removes the last step, or calls `onClear`
+ * when nothing is recorded.
  *
  * @param options - Configuration options for the recorder
- * @returns An object with recording state and control functions
+ * @returns The recorder state and controls
  *
  * @example
  * ```tsx
- * function ShortcutSettings() {
+ * function ShortcutInput() {
  *   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')
- *
- *   const recorder = useHotkeyRecorder({
- *     onRecord: (hotkey) => {
- *       setShortcut(hotkey)
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
+ *   const recorder = useHotkeyRecorder({ onRecord: setShortcut })
  *
  *   return (
- *     <div>
- *       <button onClick={recorder.startRecording}>
- *         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
- *       </button>
- *       {recorder.recordedHotkey && (
- *         <div>Recording: {recorder.recordedHotkey}</div>
- *       )}
- *     </div>
+ *     <button onClick={recorder.startRecording}>
+ *       {recorder.isRecording ? 'Press keys…' : formatForDisplay(shortcut)}
+ *     </button>
  *   )
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * const recorder = useHotkeyRecorder({
+ *   maxSteps: 3,
+ *   onRecord: (hotkey) => setShortcut(hotkey), // 'Mod+S' or ['G', 'H']
+ * })
+ * ```
  */
-export declare function useHotkeyRecorder(options: HotkeyRecorderOptions): PreactHotkeyRecorder;
+export declare function useHotkeyRecorder(options: HotkeyChordRecorderOptions): PreactHotkeyRecorder<HotkeyChord>;
+export declare function useHotkeyRecorder(options: HotkeySequenceRecorderOptions): PreactHotkeyRecorder;
 //#endregion

package/dist/useHotkeyRecorder.js

@@ -4,44 +4,6 @@ import { useEffect, useRef } from "preact/hooks";
 import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHotkeyRecorder.ts
-/**
-* Preact hook for recording keyboard shortcuts.
-*
-* This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
-* class, managing 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.
-*
-* @param options - Configuration options for the recorder
-* @returns An object with recording state and control functions
-*
-* @example
-* ```tsx
-* function ShortcutSettings() {
-*   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')
-*
-*   const recorder = useHotkeyRecorder({
-*     onRecord: (hotkey) => {
-*       setShortcut(hotkey)
-*     },
-*     onCancel: () => {
-*       console.log('Recording cancelled')
-*     },
-*   })
-*
-*   return (
-*     <div>
-*       <button onClick={recorder.startRecording}>
-*         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
-*       </button>
-*       {recorder.recordedHotkey && (
-*         <div>Recording: {recorder.recordedHotkey}</div>
-*       )}
-*     </div>
-*   )
-* }
-* ```
-*/
 function useHotkeyRecorder(options) {
 	const mergedOptions = {
 		...useDefaultHotkeysOptions().hotkeyRecorder,
@@ -50,8 +12,10 @@ function useHotkeyRecorder(options) {
 	const recorderRef = useRef(null);
 	if (!recorderRef.current) recorderRef.current = new HotkeyRecorder(mergedOptions);
 	recorderRef.current.setOptions(mergedOptions);
-	const isRecording = useSelector(recorderRef.current.store, (state) => state.isRecording);
-	const recordedHotkey = useSelector(recorderRef.current.store, (state) => state.recordedHotkey);
+	const recorder = recorderRef.current;
+	const isRecording = useSelector(recorder.store, (state) => state.isRecording);
+	const steps = useSelector(recorder.store, (state) => state.steps);
+	const recordedHotkey = useSelector(recorder.store, (state) => state.recordedHotkey);
 	useEffect(() => {
 		return () => {
 			recorderRef.current?.destroy();
@@ -59,10 +23,12 @@ function useHotkeyRecorder(options) {
 	}, []);
 	return {
 		isRecording,
+		steps,
 		recordedHotkey,
 		startRecording: () => recorderRef.current?.start(),
 		stopRecording: () => recorderRef.current?.stop(),
-		cancelRecording: () => recorderRef.current?.cancel()
+		cancelRecording: () => recorderRef.current?.cancel(),
+		commitRecording: () => recorderRef.current?.commit()
 	};
 }
 

package/dist/useHotkeyRegistrations.d.ts

@@ -1,23 +1,30 @@
-import { HotkeyRegistrationView, SequenceRegistrationView } from "@tanstack/hotkeys";
+import { HotkeyRegistrationView } from "@tanstack/hotkeys";
 //#region src/useHotkeyRegistrations.d.ts
 /**
- * Return type for useHotkeyRegistrations.
- */
-export interface HotkeyRegistrationsResult {
-  /** All registered hotkeys (public view, no callbacks) */
-  hotkeys: Array<HotkeyRegistrationView>;
-  /** All registered sequences */
-  sequences: Array<SequenceRegistrationView>;
-}
-/**
- * Preact hook that reactively reads all hotkey and sequence registrations
- * from the singleton managers.
+ * Preact hook that reactively reads every hotkey registration, chords and
+ * sequences, from the singleton HotkeyManager. Narrow each view with `kind`.
+ *
+ * This hook does NOT require the HotkeysProvider. It re-renders when
+ * registrations change, including trigger counts and sequence progress.
+ *
+ * @returns All registrations, without callbacks
  *
- * This is a standalone hook that does NOT require the HotkeysProvider.
- * It subscribes to both HotkeyManager and SequenceManager stores and
- * re-renders when registrations change.
+ * @example
+ * ```tsx
+ * function ShortcutPalette() {
+ *   const registrations = useHotkeyRegistrations()
  *
- * @returns Object with `hotkeys` and `sequences` arrays
+ *   return (
+ *     <ul>
+ *       {registrations.map((reg) => (
+ *         <li key={reg.id}>
+ *           {reg.options.meta?.name}: {formatForDisplay(reg.hotkey)}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
  */
-export declare function useHotkeyRegistrations(): HotkeyRegistrationsResult;
+export declare function useHotkeyRegistrations(): Array<HotkeyRegistrationView>;
 //#endregion

package/dist/useHotkeyRegistrations.js

@@ -1,27 +1,35 @@
-import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
-import { useMemo } from "preact/hooks";
+import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHotkeyRegistrations.ts
 /**
-* Preact hook that reactively reads all hotkey and sequence registrations
-* from the singleton managers.
+* Preact hook that reactively reads every hotkey registration, chords and
+* sequences, from the singleton HotkeyManager. Narrow each view with `kind`.
 *
-* This is a standalone hook that does NOT require the HotkeysProvider.
-* It subscribes to both HotkeyManager and SequenceManager stores and
-* re-renders when registrations change.
+* This hook does NOT require the HotkeysProvider. It re-renders when
+* registrations change, including trigger counts and sequence progress.
 *
-* @returns Object with `hotkeys` and `sequences` arrays
+* @returns All registrations, without callbacks
+*
+* @example
+* ```tsx
+* function ShortcutPalette() {
+*   const registrations = useHotkeyRegistrations()
+*
+*   return (
+*     <ul>
+*       {registrations.map((reg) => (
+*         <li key={reg.id}>
+*           {reg.options.meta?.name}: {formatForDisplay(reg.hotkey)}
+*         </li>
+*       ))}
+*     </ul>
+*   )
+* }
+* ```
 */
 function useHotkeyRegistrations() {
-	const hotkeyManager = getHotkeyManager();
-	const sequenceManager = getSequenceManager();
-	const hotkeyState = useSelector(hotkeyManager.registrations);
-	const sequenceState = useSelector(sequenceManager.registrations);
-	return {
-		hotkeys: useMemo(() => Array.from(hotkeyState.values()).map(toHotkeyRegistrationView), [hotkeyState]),
-		sequences: useMemo(() => Array.from(sequenceState.values()), [sequenceState])
-	};
+	return useSelector(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView));
 }
 
 //#endregion

package/dist/useHotkeys.d.ts

@@ -1,41 +1,32 @@
-import { UseHotkeyOptions } from "./useHotkey.js";
-import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { UseHotkeyCommonOptions, UseHotkeyTarget } from "./useHotkey.js";
+import { AdapterHotkeyDefinition } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkeys.d.ts
 /**
- * A single hotkey definition for use with `useHotkeys`.
+ * One hotkey for `useHotkeys`. Chords accept `requireReset`; sequences accept
+ * `timeout`; hotkeys of unknown kind accept only shared options.
  */
-export interface UseHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: RegisterableHotkey;
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback;
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: UseHotkeyOptions;
-}
+export type UseHotkeyDefinition = AdapterHotkeyDefinition<UseHotkeyTarget>;
 /**
- * Preact hook for registering multiple keyboard hotkeys at once.
+ * Preact hook for registering several hotkeys at once: chords, sequences, and
+ * app hotkeys. Accepts a dynamic array, so it is safe to use with
+ * variable-length lists without violating the rules of hooks.
  *
- * Uses the singleton HotkeyManager for efficient event handling.
- * Accepts a dynamic array of hotkey definitions, making it safe to use
- * with variable-length lists without violating the rules of hooks.
+ * Options merge in this order: provider defaults, app hotkey declaration,
+ * commonOptions, per-hotkey options. Each option applies only to the kinds
+ * that support it. Callbacks and options sync on every render.
  *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
+ * Per-row `enabled: false` keeps that registration (visible in devtools) and
+ * only suppresses firing. Unbound app hotkeys and empty sequences register nothing.
  *
- * Callbacks and options are synced on every render to avoid stale closures.
- *
- * @param hotkeys - Array of hotkey definitions to register
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
- *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` 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).
+ * @param hotkeys - Hotkeys to register
+ * @param commonOptions - Options applied to every hotkey (overridden by per-hotkey options)
  *
  * @example
  * ```tsx
  * function Editor() {
  *   useHotkeys([
  *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: ['G', 'G'], callback: () => scrollToTop(), options: { timeout: 500 } },
  *     { hotkey: 'Escape', callback: () => close() },
  *   ])
  * }
@@ -56,5 +47,5 @@ export interface UseHotkeyDefinition {
  * }
  * ```
  */
-export declare function useHotkeys(hotkeys: Array<UseHotkeyDefinition>, commonOptions?: UseHotkeyOptions): void;
+export declare function useHotkeys(hotkeys: ReadonlyArray<UseHotkeyDefinition>, commonOptions?: UseHotkeyCommonOptions): void;
 //#endregion

package/dist/useHotkeys.js

@@ -1,33 +1,31 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { isRef } from "./utils.js";
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
+import { useHotkeysContext } from "./HotkeysProvider.js";
+import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
+import { resolveTarget } from "./utils.js";
 import { useEffect, useRef } from "preact/hooks";
+import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeys.ts
 /**
-* Preact hook for registering multiple keyboard hotkeys at once.
+* Preact hook for registering several hotkeys at once: chords, sequences, and
+* app hotkeys. Accepts a dynamic array, so it is safe to use with
+* variable-length lists without violating the rules of hooks.
 *
-* Uses the singleton HotkeyManager for efficient event handling.
-* Accepts a dynamic array of hotkey definitions, making it safe to use
-* with variable-length lists without violating the rules of hooks.
+* Options merge in this order: provider defaults, app hotkey declaration,
+* commonOptions, per-hotkey options. Each option applies only to the kinds
+* that support it. Callbacks and options sync on every render.
 *
-* Options are merged in this order:
-* HotkeysProvider defaults < commonOptions < per-definition options
+* Per-row `enabled: false` keeps that registration (visible in devtools) and
+* only suppresses firing. Unbound app hotkeys and empty sequences register nothing.
 *
-* Callbacks and options are synced on every render to avoid stale closures.
-*
-* @param hotkeys - Array of hotkey definitions to register
-* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
-*   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` 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).
+* @param hotkeys - Hotkeys to register
+* @param commonOptions - Options applied to every hotkey (overridden by per-hotkey options)
 *
 * @example
 * ```tsx
 * function Editor() {
 *   useHotkeys([
 *     { hotkey: 'Mod+S', callback: () => save() },
-*     { hotkey: 'Mod+Z', callback: () => undo() },
+*     { hotkey: ['G', 'G'], callback: () => scrollToTop(), options: { timeout: 500 } },
 *     { hotkey: 'Escape', callback: () => close() },
 *   ])
 * }
@@ -49,72 +47,33 @@ import { useEffect, useRef } from "preact/hooks";
 * ```
 */
 function useHotkeys(hotkeys, commonOptions = {}) {
-	const defaultOptions = useDefaultHotkeysOptions().hotkey;
-	const manager = getHotkeyManager();
-	const platform = commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform();
-	const registrationsRef = useRef(/* @__PURE__ */ new Map());
-	const hotkeysRef = useRef(hotkeys);
-	const hotkeyStringsRef = useRef([]);
-	const commonOptionsRef = useRef(commonOptions);
-	const defaultOptionsRef = useRef(defaultOptions);
-	const managerRef = useRef(manager);
-	const hotkeyStrings = hotkeys.map((def) => normalizeRegisterableHotkey(def.hotkey, platform));
-	hotkeysRef.current = hotkeys;
-	hotkeyStringsRef.current = hotkeyStrings;
-	commonOptionsRef.current = commonOptions;
-	defaultOptionsRef.current = defaultOptions;
-	managerRef.current = manager;
+	const defaults = useHotkeysContext()?.defaultOptions.hotkey;
+	const appHotkeysStore = useAppHotkeysStoreState();
+	const latestRef = useRef({
+		hotkeys,
+		commonOptions,
+		defaults,
+		appHotkeysStore
+	});
+	latestRef.current = {
+		hotkeys,
+		commonOptions,
+		defaults,
+		appHotkeysStore
+	};
+	const bindingsRef = useRef(null);
 	useEffect(() => {
-		const prevRegistrations = registrationsRef.current;
-		const nextRegistrations = /* @__PURE__ */ new Map();
-		const rows = [];
-		for (let i = 0; i < hotkeysRef.current.length; i++) {
-			const def = hotkeysRef.current[i];
-			const hotkeyStr = hotkeyStringsRef.current[i];
-			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}:${hotkeyStr}`;
-			rows.push({
-				registrationKey,
-				def,
-				hotkeyStr,
-				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, hotkeyStr, 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(hotkeyStr, def.callback, {
-				...mergedOptions,
-				target: resolvedTarget
-			});
-			nextRegistrations.set(registrationKey, {
-				handle,
-				target: resolvedTarget
-			});
-		}
-		registrationsRef.current = nextRegistrations;
+		bindingsRef.current ??= createHotkeyBindings();
+		const { hotkeys, ...context } = latestRef.current;
+		bindingsRef.current.update(prepareHotkeyDefinitions(hotkeys, {
+			...context,
+			resolveTarget
+		}));
 	});
 	useEffect(() => {
 		return () => {
-			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
-			registrationsRef.current = /* @__PURE__ */ new Map();
+			bindingsRef.current?.destroy();
+			bindingsRef.current = null;
 		};
 	}, []);
 }

package/dist/utils.js

@@ -5,6 +5,13 @@
 function isRef(value) {
 	return value !== null && typeof value === "object" && "current" in value;
 }
+/**
+* Resolves a hook target. A ref that is still null skips registration;
+* a null target means document.
+*/
+function resolveTarget(target) {
+	return isRef(target) ? target.current : target ?? void 0;
+}
 
 //#endregion
-export { isRef };
+export { resolveTarget };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-hotkeys",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -33,13 +33,13 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.11.0",
-    "@tanstack/preact-store": "^0.13.4"
+    "@tanstack/hotkeys": "0.12.0",
+    "@tanstack/preact-store": "^0.13.5"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.6",
     "@testing-library/preact": "^3.2.4",
-    "preact": "^10.29.8"
+    "preact": "^11.0.1"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"

package/dist/useHotkeySequence.d.ts

@@ -1,56 +0,0 @@
-import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
-import { RefObject } from "preact";
-//#region src/useHotkeySequence.d.ts
-export interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a Preact ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?: RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
-}
-/**
- * Preact 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>
- * }
- * ```
- */
-export declare function useHotkeySequence(sequence: HotkeySequence, callback: HotkeyCallback, options?: UseHotkeySequenceOptions): void;
-//#endregion