@tanstack/solid-hotkeys 0.12.1 → 0.14.0

package/README.md

@@ -67,6 +67,9 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > [!NOTE]
 > You may know **TanStack Hotkeys** by our adapter names, too!
 >
+> - [**Alpine Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/alpine/quick-start)
+> - [**Ember Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/ember/quick-start)
+> - [**Octane Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/octane/quick-start)
 > - [**React Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/react/react-hotkeys)
 > - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys)
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)

package/dist/HotkeysProvider.d.ts

@@ -1,21 +1,52 @@
-import { CreateHotkeyOptions } from "./createHotkey.js";
-import { CreateHotkeySequenceOptions } from "./createHotkeySequence.js";
-import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { CreateHotkeyCommonOptions } from "./createHotkey.js";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { JSX, ParentComponent } from "solid-js";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
-  hotkey?: Partial<CreateHotkeyOptions>;
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
-  hotkeySequence?: Partial<CreateHotkeySequenceOptions>;
+  /**
+   * Defaults for every hotkey registered by `createHotkey` and `createHotkeys`.
+   * `requireReset` applies to chords and `timeout` applies to sequences.
+   */
+  hotkey?: CreateHotkeyCommonOptions;
+  /** Defaults for every `createHotkeyRecorder`. */
+  hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
 interface HotkeysContextValue {
-  defaultOptions: HotkeysProviderOptions;
+  readonly appHotkeysStore: AppHotkeysStore | null;
+  readonly defaultOptions: HotkeysProviderOptions;
 }
 export interface HotkeysProviderProps {
   children: JSX.Element;
+  /**
+   * Every app hotkey, from `defineAppHotkeys`. Read when the provider is
+   * created; listed by `createAppHotkeyList` whether or not they are registered.
+   */
+  appHotkeys?: AppHotkeys;
+  /**
+   * Starting custom hotkeys, such as saved data. Read once; the provider owns
+   * the state afterwards. Invalid entries are ignored with a warning.
+   */
+  customHotkeys?: CustomHotkeys | null;
+  /** Called with the custom hotkeys after every change, ready to save. */
+  onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
   defaultOptions?: HotkeysProviderOptions;
 }
+/**
+ * Provides default options, app hotkeys, and the user's custom hotkeys.
+ *
+ * @example
+ * ```tsx
+ * <HotkeysProvider
+ *   appHotkeys={appHotkeys}
+ *   customHotkeys={JSON.parse(localStorage.getItem('hotkeys') ?? '{}')}
+ *   onCustomHotkeysChange={(custom) =>
+ *     localStorage.setItem('hotkeys', JSON.stringify(custom))
+ *   }
+ * >
+ *   <App />
+ * </HotkeysProvider>
+ * ```
+ */
 export declare const HotkeysProvider: ParentComponent<HotkeysProviderProps>;
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 export declare function useDefaultHotkeysOptions(): HotkeysProviderOptions;

package/dist/HotkeysProvider.js

@@ -1,11 +1,43 @@
+import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { createComponent } from "solid-js/web";
-import { createContext, useContext } from "solid-js";
+import { createContext, createEffect, onCleanup, onMount, useContext } from "solid-js";
 
 //#region src/HotkeysProvider.tsx
 const HotkeysContext = createContext(null);
 const DEFAULT_OPTIONS = {};
+/**
+* Provides default options, app hotkeys, and the user's custom hotkeys.
+*
+* @example
+* ```tsx
+* <HotkeysProvider
+*   appHotkeys={appHotkeys}
+*   customHotkeys={JSON.parse(localStorage.getItem('hotkeys') ?? '{}')}
+*   onCustomHotkeysChange={(custom) =>
+*     localStorage.setItem('hotkeys', JSON.stringify(custom))
+*   }
+* >
+*   <App />
+* </HotkeysProvider>
+* ```
+*/
 const HotkeysProvider = (props) => {
-	const contextValue = { defaultOptions: props.defaultOptions ?? DEFAULT_OPTIONS };
+	const store = props.appHotkeys ? new AppHotkeysStore(props.appHotkeys, {
+		customHotkeys: props.customHotkeys,
+		onCustomHotkeysChange: (custom) => props.onCustomHotkeysChange?.(custom)
+	}) : null;
+	createEffect(() => {
+		if (props.appHotkeys) store?.setAppHotkeys(props.appHotkeys);
+	});
+	onMount(() => {
+		if (store) onCleanup(publishAppHotkeysStore(store));
+	});
+	const contextValue = {
+		appHotkeysStore: store,
+		get defaultOptions() {
+			return props.defaultOptions ?? DEFAULT_OPTIONS;
+		}
+	};
 	return createComponent(HotkeysContext.Provider, {
 		value: contextValue,
 		get children() {
@@ -17,7 +49,7 @@ function useHotkeysContext() {
 	return useContext(HotkeysContext);
 }
 function useDefaultHotkeysOptions() {
-	return useContext(HotkeysContext)?.defaultOptions ?? {};
+	return useContext(HotkeysContext)?.defaultOptions ?? DEFAULT_OPTIONS;
 }
 
 //#endregion

package/dist/appHotkeys.d.ts

@@ -0,0 +1,42 @@
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotkeys } from "@tanstack/hotkeys";
+//#region src/appHotkeys.d.ts
+/**
+ * Returns an accessor for the effective app hotkeys from `HotkeysProvider`,
+ * typed by `Register`: each declaration with the user's custom hotkey applied.
+ *
+ * @example
+ * ```tsx
+ * const hotkeys = useAppHotkeys()
+ * createHotkey(() => hotkeys()['doc.save'], () => save())
+ * ```
+ */
+export declare function useAppHotkeys(): () => RegisteredAppHotkeys;
+/**
+ * Lists every app hotkey with its live status, in declaration order, for
+ * cheat sheets and settings screens. App hotkeys whose components have not
+ * mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+ */
+export declare function createAppHotkeyList(): () => Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>;
+/** Custom hotkey state and actions returned by `useCustomHotkeys`. */
+export interface UseCustomHotkeysResult {
+  /** The user's hotkeys that differ from the defaults. */
+  customHotkeys: () => CustomHotkeys;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it.
+   * Returns conflicting app hotkeys; when any exist, nothing changes.
+   */
+  setCustomHotkey: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey | null) => Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  resetCustomHotkey: (id: keyof RegisteredAppHotkeys & string) => void;
+  /** Restores every default hotkey. */
+  resetCustomHotkeys: () => void;
+  /** Other app hotkeys that would collide if `id` used `hotkey`. */
+  findConflicts: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey) => Array<AppHotkey>;
+}
+/**
+ * Reads and changes the user's custom hotkeys. Changes apply to every
+ * registered app hotkey immediately and are passed to the provider's
+ * `onCustomHotkeysChange`, ready to save.
+ */
+export declare function useCustomHotkeys(): UseCustomHotkeysResult;
+//#endregion

package/dist/appHotkeys.js

@@ -0,0 +1,64 @@
+import { useAppHotkeysStoreSource } from "./defaultOptions.js";
+import { createHotkeyRegistrations } from "./createHotkeyRegistrations.js";
+import { createMemo } from "solid-js";
+
+//#region src/appHotkeys.ts
+function useRequiredStore(name) {
+	const source = useAppHotkeysStoreSource();
+	if (!source.store) throw new Error(`${name} requires a HotkeysProvider with an appHotkeys prop`);
+	return {
+		store: source.store,
+		state: source.state
+	};
+}
+/**
+* Returns an accessor for the effective app hotkeys from `HotkeysProvider`,
+* typed by `Register`: each declaration with the user's custom hotkey applied.
+*
+* @example
+* ```tsx
+* const hotkeys = useAppHotkeys()
+* createHotkey(() => hotkeys()['doc.save'], () => save())
+* ```
+*/
+function useAppHotkeys() {
+	const { store, state } = useRequiredStore("useAppHotkeys");
+	return createMemo(() => {
+		state();
+		return store.appHotkeys;
+	});
+}
+/**
+* Lists every app hotkey with its live status, in declaration order, for
+* cheat sheets and settings screens. App hotkeys whose components have not
+* mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+*/
+function createAppHotkeyList() {
+	const { store, state } = useRequiredStore("createAppHotkeyList");
+	const registrations = createHotkeyRegistrations();
+	return createMemo(() => {
+		state();
+		return store.getList(registrations());
+	});
+}
+/**
+* Reads and changes the user's custom hotkeys. Changes apply to every
+* registered app hotkey immediately and are passed to the provider's
+* `onCustomHotkeysChange`, ready to save.
+*/
+function useCustomHotkeys() {
+	const { store, state } = useRequiredStore("useCustomHotkeys");
+	return {
+		customHotkeys: createMemo(() => {
+			state();
+			return store.customHotkeys;
+		}),
+		setCustomHotkey: (id, hotkey) => store.setCustomHotkey(id, hotkey),
+		resetCustomHotkey: (id) => store.resetCustomHotkey(id),
+		resetCustomHotkeys: () => store.resetCustomHotkeys(),
+		findConflicts: (id, hotkey) => store.findConflicts(id, hotkey)
+	};
+}
+
+//#endregion
+export { createAppHotkeyList, useAppHotkeys, useCustomHotkeys };

package/dist/createHotkey.d.ts

@@ -1,69 +1,42 @@
-import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/createHotkey.d.ts
-export interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a direct DOM element, an accessor (for reactive targets that become
-   * available after mount), or null. Defaults to document.
-   * When using scoped targets, pass an accessor: () => ({ target: elementSignal() })
-   * so the hotkey waits for the element to be attached before registering.
-   */
-  target?: HTMLElement | Document | Window | null;
-}
 /**
- * SolidJS primitive for registering a keyboard hotkey.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * The callback receives both the keyboard event and a context object
- * containing the hotkey string and parsed hotkey.
- *
- * This primitive automatically tracks reactive dependencies and updates
- * the registration when options or the callback change.
- *
- * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
- * @param callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey behavior
- *
- * @example
- * ```tsx
- * function SaveButton() {
- *   const [count, setCount] = createSignal(0)
- *
- *   // Callback always has access to latest count value
- *   createHotkey('Mod+S', (event, { hotkey }) => {
- *     console.log(`Save triggered, count is ${count()}`)
- *     handleSave()
- *   })
- *
- *   return <button onClick={() => setCount(c => c + 1)}>Count: {count()}</button>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Modal(props) {
- *   // enabled option is reactive
- *   createHotkey('Escape', () => {
- *     props.onClose()
- *   }, () => ({ enabled: props.isOpen }))
+ * The element to listen on. A `null` target skips registration, so pass an
+ * accessor such as `() => ({ target: element() })` for elements that attach
+ * after mount.
+ */
+export type CreateHotkeyTarget = Target | null;
+/** Options shared by chords and sequences. */
+export type CreateHotkeyOptions = AdapterHotkeyOptions<CreateHotkeyTarget>;
+/** Options for a chord such as `'Mod+S'`. */
+export type CreateHotkeyChordOptions = AdapterChordOptions<CreateHotkeyTarget>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type CreateHotkeySequenceOptions = AdapterSequenceOptions<CreateHotkeyTarget>;
+/** Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it. */
+export type CreateHotkeyCommonOptions = AdapterCommonOptions<CreateHotkeyTarget>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type CreateHotkeyOptionsFor<T extends RegisterableHotkey> = AdapterOptionsFor<T, CreateHotkeyTarget>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type CreateAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, CreateHotkeyTarget>;
+type MaybeAccessor<T> = T | (() => T);
+/**
+ * Solid primitive for registering a hotkey: a chord such as `'Mod+S'`, a
+ * sequence such as `['G', 'G']`, or an app hotkey from `defineAppHotkeys`.
+ * The hotkey and options may be accessors.
  *
- *   return <Show when={props.isOpen}>
- *     <div class="modal">...</div>
- *   </Show>
- * }
- * ```
+ * Chords accept `requireReset`; sequences accept `timeout`. A one-step
+ * sequence registers as its chord. An app hotkey uses its effective hotkey
+ * from `HotkeysProvider` (including the user's custom hotkey) and its
+ * declared meta and options, and registers nothing while unbound.
  *
  * @example
  * ```tsx
- * function Editor() {
- *   const [editorRef, setEditorRef] = createSignal<HTMLDivElement | null>(null)
- *
- *   // Scoped to a specific element - use accessor so hotkey waits for ref
- *   createHotkey('Mod+S', save, () => ({ target: editorRef() }))
- *
- *   return <div ref={setEditorRef}>...</div>
- * }
+ * createHotkey('Mod+S', () => save())
+ * createHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
+ * createHotkey('Escape', () => close(), () => ({ enabled: isOpen() }))
  * ```
  */
-export declare function createHotkey(hotkey: RegisterableHotkey | (() => RegisterableHotkey), callback: HotkeyCallback, options?: CreateHotkeyOptions | (() => CreateHotkeyOptions)): void;
+export declare function createHotkey<T extends AppHotkey>(hotkey: MaybeAccessor<T>, callback: HotkeyCallback, options?: MaybeAccessor<CreateAppHotkeyOptions<T>>): void;
+export declare function createHotkey<T extends RegisterableHotkey>(hotkey: MaybeAccessor<T>, callback: HotkeyCallback, options?: MaybeAccessor<CreateHotkeyOptionsFor<T>>): void;
 //#endregion

package/dist/createHotkey.js

@@ -1,119 +1,12 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
-import { createEffect, onCleanup, untrack } from "solid-js";
+import { createHotkeys } from "./createHotkeys.js";
 
 //#region src/createHotkey.ts
-/**
-* SolidJS primitive for registering a keyboard hotkey.
-*
-* Uses the singleton HotkeyManager for efficient event handling.
-* The callback receives both the keyboard event and a context object
-* containing the hotkey string and parsed hotkey.
-*
-* This primitive automatically tracks reactive dependencies and updates
-* the registration when options or the callback change.
-*
-* @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
-* @param callback - The function to call when the hotkey is pressed
-* @param options - Options for the hotkey behavior
-*
-* @example
-* ```tsx
-* function SaveButton() {
-*   const [count, setCount] = createSignal(0)
-*
-*   // Callback always has access to latest count value
-*   createHotkey('Mod+S', (event, { hotkey }) => {
-*     console.log(`Save triggered, count is ${count()}`)
-*     handleSave()
-*   })
-*
-*   return <button onClick={() => setCount(c => c + 1)}>Count: {count()}</button>
-* }
-* ```
-*
-* @example
-* ```tsx
-* function Modal(props) {
-*   // enabled option is reactive
-*   createHotkey('Escape', () => {
-*     props.onClose()
-*   }, () => ({ enabled: props.isOpen }))
-*
-*   return <Show when={props.isOpen}>
-*     <div class="modal">...</div>
-*   </Show>
-* }
-* ```
-*
-* @example
-* ```tsx
-* function Editor() {
-*   const [editorRef, setEditorRef] = createSignal<HTMLDivElement | null>(null)
-*
-*   // Scoped to a specific element - use accessor so hotkey waits for ref
-*   createHotkey('Mod+S', save, () => ({ target: editorRef() }))
-*
-*   return <div ref={setEditorRef}>...</div>
-* }
-* ```
-*/
 function createHotkey(hotkey, callback, options = {}) {
-	const defaultOptions = useDefaultHotkeysOptions();
-	const manager = getHotkeyManager();
-	let registration = null;
-	let lastHotkeyString = null;
-	let lastTarget = null;
-	onCleanup(() => {
-		if (registration?.isActive) {
-			registration.unregister();
-			registration = null;
-		}
-		lastHotkeyString = null;
-		lastTarget = null;
-	});
-	createEffect(() => {
-		const resolvedHotkey = typeof hotkey === "function" ? hotkey() : hotkey;
-		const resolvedOptions = typeof options === "function" ? options() : options;
-		const mergedOptions = {
-			...defaultOptions.hotkey,
-			...resolvedOptions
-		};
-		const platform = mergedOptions.platform ?? detectPlatform();
-		const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform);
-		const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
-		if (!resolvedTarget) {
-			if (registration?.isActive) {
-				registration.unregister();
-				registration = null;
-			}
-			lastHotkeyString = null;
-			lastTarget = null;
-			return;
-		}
-		const { target: _target, ...optionsWithoutTarget } = mergedOptions;
-		untrack(() => {
-			if (registration?.isActive && lastHotkeyString === hotkeyString && lastTarget === resolvedTarget) {
-				registration.callback = callback;
-				registration.setOptions(optionsWithoutTarget);
-				return;
-			}
-			if (registration?.isActive) {
-				registration.unregister();
-				registration = null;
-			}
-			registration = manager.register(hotkeyString, callback, {
-				...optionsWithoutTarget,
-				target: resolvedTarget
-			});
-			if (registration.isActive) {
-				registration.callback = callback;
-				registration.setOptions(optionsWithoutTarget);
-			}
-			lastHotkeyString = hotkeyString;
-			lastTarget = resolvedTarget;
-		});
-	});
+	createHotkeys(() => [{
+		hotkey: typeof hotkey === "function" ? hotkey() : hotkey,
+		callback,
+		options: typeof options === "function" ? options() : options
+	}]);
 }
 
 //#endregion

package/dist/createHotkeyHint.d.ts

@@ -1,11 +1,10 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 //#region src/createHotkeyHint.d.ts
 /**
- * Returns a boolean accessor indicating whether held modifiers reveal this shortcut.
- * Pass accessors to track changing bindings and options.
- * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. Combine with the action's enabled state before showing a badge.
- * This helper does not register a shortcut or check whether its target is focused.
+ * Returns an accessor indicating whether held modifiers reveal this shortcut.
+ * A sequence reveals its hint from its first step, and an app hotkey uses its
+ * effective hotkey (false while unbound). This helper does not register a
+ * shortcut or check whether its target is focused.
  */
-export declare function createHotkeyHint(hotkey: RegisterableHotkey | (() => RegisterableHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): () => boolean;
+export declare function createHotkeyHint(hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): () => boolean;
 //#endregion

package/dist/createHotkeyHint.js

@@ -1,18 +1,24 @@
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { useAppHotkeysStoreSource } from "./defaultOptions.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { createMemo } from "solid-js";
 import { useSelector } from "@tanstack/solid-store";
 
 //#region src/createHotkeyHint.ts
 /**
-* Returns a boolean accessor indicating whether held modifiers reveal this shortcut.
-* Pass accessors to track changing bindings and options.
-* Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
-* every modifier. Combine with the action's enabled state before showing a badge.
-* This helper does not register a shortcut or check whether its target is focused.
+* Returns an accessor indicating whether held modifiers reveal this shortcut.
+* A sequence reveals its hint from its first step, and an app hotkey uses its
+* effective hotkey (false while unbound). This helper does not register a
+* shortcut or check whether its target is focused.
 */
 function createHotkeyHint(hotkey, options = {}) {
+	const appHotkeys = useAppHotkeysStoreSource();
 	const held = useSelector(getKeyStateTracker().store, (state) => state.heldKeys);
-	return createMemo(() => matchesHeldModifiers(typeof hotkey === "function" ? hotkey() : hotkey, held(), typeof options === "function" ? options() : options));
+	return createMemo(() => {
+		appHotkeys.state();
+		const value = typeof hotkey === "function" ? hotkey() : hotkey;
+		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, appHotkeys.store).hotkey : value;
+		return resolved !== null && matchesHeldModifiers(resolved, held(), typeof options === "function" ? options() : options);
+	});
 }
 
 //#endregion

package/dist/createHotkeyRecorder.d.ts

@@ -1,57 +1,38 @@
-import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { Hotkey, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 //#region src/createHotkeyRecorder.d.ts
-export interface SolidHotkeyRecorder {
+export interface SolidHotkeyRecorder<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;
 }
 /**
- * SolidJS primitive for recording keyboard shortcuts.
+ * Solid primitive for recording keyboard shortcuts. Options may be an accessor.
  *
- * This primitive 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.
- *
- * This primitive uses `useSelector` from `@tanstack/solid-store` to subscribe
- * to the recorder's store state (same pattern as useHotkeyRecorder in React).
- *
- * @param options - Configuration options for the recorder (or accessor function)
- * @returns An object with recording state signals and control functions
+ * With the default `maxSteps: 1`, the first valid chord is recorded. With a
+ * larger `maxSteps`, each chord adds a step; the recording commits on Enter
+ * (unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+ * `onRecord` receives a chord (one step) or a sequence.
  *
  * @example
  * ```tsx
- * function ShortcutSettings() {
- *   const [shortcut, setShortcut] = createSignal<Hotkey>('Mod+S')
- *
- *   const recorder = createHotkeyRecorder({
- *     onRecord: (hotkey) => {
- *       setShortcut(hotkey)
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
- *
- *   return (
- *     <div>
- *       <button onClick={recorder.startRecording}>
- *         {recorder.isRecording() ? 'Recording...' : 'Edit Shortcut'}
- *       </button>
- *       <Show when={recorder.recordedHotkey()}>
- *         <div>Recording: {recorder.recordedHotkey()}</div>
- *       </Show>
- *     </div>
- *   )
- * }
+ * const recorder = createHotkeyRecorder({ onRecord: setShortcut })
+ * const sequenceRecorder = createHotkeyRecorder({ maxSteps: 3, onRecord: setShortcut })
  * ```
  */
-export declare function createHotkeyRecorder(options: HotkeyRecorderOptions | (() => HotkeyRecorderOptions)): SolidHotkeyRecorder;
+export declare function createHotkeyRecorder(options: HotkeyChordRecorderOptions): SolidHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(options: HotkeySequenceRecorderOptions): SolidHotkeyRecorder;
+export declare function createHotkeyRecorder(options: () => HotkeySequenceRecorderOptions): SolidHotkeyRecorder;
+export declare function createHotkeyRecorder(options: () => HotkeyChordRecorderOptions): SolidHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(options: () => HotkeyRecorderOptions): SolidHotkeyRecorder;
 //#endregion