@tanstack/angular-hotkeys 0.13.0 → 0.14.1

package/dist/hotkeys-provider.d.ts

@@ -1,19 +1,58 @@
-import { InjectHotkeyOptions } from "./injectHotkey.js";
-import { InjectHotkeySequenceOptions } from "./injectHotkeySequence.js";
-import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
-import { InjectionToken, StaticProvider } from "@angular/core";
+import { InjectHotkeyCommonOptions } from "./injectHotkey.js";
+import { AppHotkeys, AppHotkeysState, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { InjectionToken, Provider, Signal } from "@angular/core";
 //#region src/hotkeys-provider.d.ts
 export interface HotkeysProviderOptions {
-  hotkey?: Partial<InjectHotkeyOptions>;
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
-  hotkeySequence?: Partial<InjectHotkeySequenceOptions>;
+  /**
+   * Defaults for every hotkey registered by `injectHotkey` and `injectHotkeys`.
+   * `requireReset` applies to chords and `timeout` applies to sequences.
+   */
+  hotkey?: InjectHotkeyCommonOptions;
+  /** Defaults for every `injectHotkeyRecorder`. */
+  hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
+}
+/** Options for `provideHotkeys`. */
+export interface ProvideHotkeysOptions {
+  defaultOptions?: HotkeysProviderOptions;
+  /**
+   * Every app hotkey, from `defineAppHotkeys`. Listed by
+   * `injectAppHotkeyList` 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;
 }
 export interface HotkeysContextValue {
   readonly defaultOptions: HotkeysProviderOptions;
+  readonly appHotkeysStore: AppHotkeysStore | null;
+  /** Tracks app hotkeys and custom hotkeys so signals and effects re-run. */
+  readonly appHotkeysState: Signal<AppHotkeysState | null>;
 }
 export declare const HOTKEYS_INJECTION_TOKEN: InjectionToken<HotkeysContextValue>;
-export declare function provideHotkeys(defaultOptions: HotkeysProviderOptions): StaticProvider;
+/**
+ * Provides default options, app hotkeys, and the user's custom hotkeys to an
+ * injector, such as the application or a component.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [
+ *     provideHotkeys({
+ *       appHotkeys,
+ *       customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *       onCustomHotkeysChange: (custom) =>
+ *         localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function provideHotkeys(options?: ProvideHotkeysOptions): Provider;
 export declare function injectHotkeysContext(): HotkeysContextValue;
 export declare function injectDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/hotkeys-provider.js

@@ -1,14 +1,59 @@
-import { InjectionToken, inject } from "@angular/core";
+import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import { DestroyRef, InjectionToken, inject, signal } from "@angular/core";
 
 //#region src/hotkeys-provider.ts
+const NO_APP_HOTKEYS = signal(null).asReadonly();
 const HOTKEYS_INJECTION_TOKEN = new InjectionToken("HOTKEYS_INJECTION_TOKEN", {
 	providedIn: "root",
-	factory: () => ({ defaultOptions: {} })
+	factory: () => ({
+		defaultOptions: {},
+		appHotkeysStore: null,
+		appHotkeysState: NO_APP_HOTKEYS
+	})
 });
-function provideHotkeys(defaultOptions) {
+/**
+* Provides default options, app hotkeys, and the user's custom hotkeys to an
+* injector, such as the application or a component.
+*
+* @example
+* ```ts
+* bootstrapApplication(App, {
+*   providers: [
+*     provideHotkeys({
+*       appHotkeys,
+*       customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+*       onCustomHotkeysChange: (custom) =>
+*         localStorage.setItem('hotkeys', JSON.stringify(custom)),
+*     }),
+*   ],
+* })
+* ```
+*/
+function provideHotkeys(options = {}) {
 	return {
 		provide: HOTKEYS_INJECTION_TOKEN,
-		useValue: { defaultOptions }
+		useFactory: () => {
+			const defaultOptions = options.defaultOptions ?? {};
+			if (!options.appHotkeys) return {
+				defaultOptions,
+				appHotkeysStore: null,
+				appHotkeysState: NO_APP_HOTKEYS
+			};
+			const store = new AppHotkeysStore(options.appHotkeys, {
+				customHotkeys: options.customHotkeys,
+				onCustomHotkeysChange: options.onCustomHotkeysChange
+			});
+			const state = signal(store.store.state);
+			const subscription = store.store.subscribe(() => state.set(store.store.state));
+			const destroyRef = inject(DestroyRef);
+			destroyRef.onDestroy(() => subscription.unsubscribe());
+			if (typeof document !== "undefined") destroyRef.onDestroy(publishAppHotkeysStore(store));
+			return {
+				defaultOptions,
+				appHotkeysStore: store,
+				appHotkeysState: state.asReadonly()
+			};
+		}
 	};
 }
 function injectHotkeysContext() {

package/dist/index.d.ts

@@ -1,14 +1,12 @@
-import { InjectHotkeyOptions, injectHotkey } from "./injectHotkey.js";
-import { InjectHotkeySequenceOptions, injectHotkeySequence } from "./injectHotkeySequence.js";
-import { HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, injectDefaultHotkeysOptions, injectHotkeysContext, provideHotkeys } from "./hotkeys-provider.js";
+import { InjectAppHotkeyOptions, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, injectHotkey } from "./injectHotkey.js";
+import { HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, ProvideHotkeysOptions, injectDefaultHotkeysOptions, injectHotkeysContext, provideHotkeys } from "./hotkeys-provider.js";
 import { InjectHotkeyDefinition, injectHotkeys } from "./injectHotkeys.js";
-import { InjectHotkeySequenceDefinition, injectHotkeySequences } from "./injectHotkeySequences.js";
 import { injectHeldKeys } from "./injectHeldKeys.js";
 import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { AngularHotkeyRecorder, injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
-import { HotkeyRegistrationsResult, injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
-import { AngularHotkeySequenceRecorder, injectHotkeySequenceRecorder } from "./injectHotkeySequenceRecorder.js";
+import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
+import { InjectCustomHotkeysResult, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { AngularHotkeyRecorder, AngularHotkeySequenceRecorder, HOTKEYS_INJECTION_TOKEN, HotkeyRegistrationsResult, HotkeysContextValue, HotkeysProviderOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeySequenceDefinition, InjectHotkeySequenceOptions, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeySequence, injectHotkeySequenceRecorder, injectHotkeySequences, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/index.js

@@ -1,16 +1,14 @@
 import { HOTKEYS_INJECTION_TOKEN, injectDefaultHotkeysOptions, injectHotkeysContext, provideHotkeys } from "./hotkeys-provider.js";
-import { injectHotkey } from "./injectHotkey.js";
 import { injectHotkeys } from "./injectHotkeys.js";
-import { injectHotkeySequence } from "./injectHotkeySequence.js";
-import { injectHotkeySequences } from "./injectHotkeySequences.js";
+import { injectHotkey } from "./injectHotkey.js";
 import { injectHeldKeys } from "./injectHeldKeys.js";
 import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
 import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
-import { injectHotkeySequenceRecorder } from "./injectHotkeySequenceRecorder.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
+import { injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HOTKEYS_INJECTION_TOKEN, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeySequence, injectHotkeySequenceRecorder, injectHotkeySequences, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/injectAppHotkeys.d.ts

@@ -0,0 +1,45 @@
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotkeys } from "@tanstack/hotkeys";
+import { Signal } from "@angular/core";
+//#region src/injectAppHotkeys.d.ts
+/**
+ * Returns a signal of the effective app hotkeys from `provideHotkeys`, typed
+ * by `Register`: each declaration with the user's custom hotkey applied.
+ *
+ * @example
+ * ```ts
+ * hotkeys = injectAppHotkeys()
+ * constructor() {
+ *   injectHotkey(() => this.hotkeys()['doc.save'], () => this.save())
+ * }
+ * ```
+ */
+export declare function injectAppHotkeys(): Signal<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 injectAppHotkeyList(): Signal<Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>>;
+/** Custom hotkey state and actions returned by `injectCustomHotkeys`. */
+export interface InjectCustomHotkeysResult {
+  /** The user's hotkeys that differ from the defaults. */
+  readonly customHotkeys: Signal<CustomHotkeys>;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it.
+   * Returns conflicting app hotkeys; when any exist, nothing changes.
+   */
+  readonly setCustomHotkey: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey | null) => Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  readonly resetCustomHotkey: (id: keyof RegisteredAppHotkeys & string) => void;
+  /** Restores every default hotkey. */
+  readonly resetCustomHotkeys: () => void;
+  /** Other app hotkeys that would collide if `id` used `hotkey`. */
+  readonly 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 `onCustomHotkeysChange`
+ * from `provideHotkeys`, ready to save.
+ */
+export declare function injectCustomHotkeys(): InjectCustomHotkeysResult;
+//#endregion

package/dist/injectAppHotkeys.js

@@ -0,0 +1,66 @@
+import { injectHotkeysContext } from "./hotkeys-provider.js";
+import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
+import { computed } from "@angular/core";
+
+//#region src/injectAppHotkeys.ts
+function injectRequiredStore(name) {
+	const context = injectHotkeysContext();
+	if (!context.appHotkeysStore) throw new Error(`${name} requires provideHotkeys with appHotkeys`);
+	return {
+		store: context.appHotkeysStore,
+		state: context.appHotkeysState
+	};
+}
+/**
+* Returns a signal of the effective app hotkeys from `provideHotkeys`, typed
+* by `Register`: each declaration with the user's custom hotkey applied.
+*
+* @example
+* ```ts
+* hotkeys = injectAppHotkeys()
+* constructor() {
+*   injectHotkey(() => this.hotkeys()['doc.save'], () => this.save())
+* }
+* ```
+*/
+function injectAppHotkeys() {
+	const { store, state } = injectRequiredStore("injectAppHotkeys");
+	return computed(() => {
+		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 injectAppHotkeyList() {
+	const { store, state } = injectRequiredStore("injectAppHotkeyList");
+	const registrations = injectHotkeyRegistrations();
+	return computed(() => {
+		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 `onCustomHotkeysChange`
+* from `provideHotkeys`, ready to save.
+*/
+function injectCustomHotkeys() {
+	const { store, state } = injectRequiredStore("injectCustomHotkeys");
+	return {
+		customHotkeys: computed(() => {
+			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 { injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys };

package/dist/injectHotkey.d.ts

@@ -1,72 +1,47 @@
-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/injectHotkey.d.ts
-export interface InjectHotkeyOptions 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;
-}
 /**
- * Angular inject-based API 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.
- *
- * Call in an injection context (e.g. constructor or field initializer).
- * Uses effect() to track reactive dependencies and update registration
- * when options or the callback change.
- * `enabled: false` keeps the registration (visible in devtools) and only suppresses firing; the same
- * handle is updated instead of unregistering and re-registering when identity is unchanged.
- *
- * @param hotkey - The hotkey string (e.g. 'Mod+S', 'Escape') or getter function
- * @param callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey behavior, or getter for reactive options
- *
- * @example
- * ```ts
- * @Component({ ... })
- * export class SaveButtonComponent {
- *   private readonly saveCount = signal(0)
- *
- *   constructor() {
- *     injectHotkey('Mod+S', (event, { hotkey }) => {
- *       event.preventDefault()
- *       this.saveCount.update(c => c + 1)
- *     })
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * @Component({ ... })
- * export class ModalComponent {
- *   isOpen = signal(true)
+ * The element to listen on. A `null` target skips registration, so pass a
+ * getter such as `() => ({ target: this.element() })` for elements that
+ * attach after the view renders.
+ */
+export type InjectHotkeyTarget = Target | null;
+/** Options shared by chords and sequences. */
+export type InjectHotkeyOptions = AdapterHotkeyOptions<InjectHotkeyTarget>;
+/** Options for a chord such as `'Mod+S'`. */
+export type InjectHotkeyChordOptions = AdapterChordOptions<InjectHotkeyTarget>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type InjectHotkeySequenceOptions = AdapterSequenceOptions<InjectHotkeyTarget>;
+/** Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it. */
+export type InjectHotkeyCommonOptions = AdapterCommonOptions<InjectHotkeyTarget>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type InjectHotkeyOptionsFor<T extends RegisterableHotkey> = AdapterOptionsFor<T, InjectHotkeyTarget>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type InjectAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, InjectHotkeyTarget>;
+type MaybeGetter<T> = T | (() => T);
+/**
+ * Angular inject-based API 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 getters that read signals.
  *
- *   constructor() {
- *     injectHotkey('Escape', () => this.close(), () => ({ enabled: this.isOpen() }))
- *   }
- * }
- * ```
+ * Chords accept `requireReset`; sequences accept `timeout`. A one-step
+ * sequence registers as its chord. An app hotkey uses its effective hotkey
+ * from `provideHotkeys` (including the user's custom hotkey) and its declared
+ * meta and options, and registers nothing while unbound.
  *
  * @example
  * ```ts
  * @Component({ ... })
  * export class EditorComponent {
- *   private readonly editorRef = viewChild<ElementRef<HTMLDivElement>>('editorRef')
- *
  *   constructor() {
- *     injectHotkey('Mod+B', () => this.toggleBold(), () => ({
- *       target: this.editorRef()?.nativeElement ?? null,
- *     }))
+ *     injectHotkey('Mod+S', () => this.save())
+ *     injectHotkey(['G', 'G'], () => this.scrollToTop(), { timeout: 500 })
+ *     injectHotkey('Escape', () => this.close(), () => ({ enabled: this.isOpen() }))
  *   }
  * }
  * ```
  */
-export declare function injectHotkey(hotkey: RegisterableHotkey | (() => RegisterableHotkey), callback: HotkeyCallback, options?: InjectHotkeyOptions | (() => InjectHotkeyOptions)): void;
+export declare function injectHotkey<T extends AppHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<InjectAppHotkeyOptions<T>>): void;
+export declare function injectHotkey<T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<InjectHotkeyOptionsFor<T>>): void;
 //#endregion

package/dist/injectHotkey.js

@@ -1,121 +1,12 @@
-import { injectDefaultHotkeysOptions } from "./hotkeys-provider.js";
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
-import { DestroyRef, effect, inject } from "@angular/core";
+import { injectHotkeys } from "./injectHotkeys.js";
 
 //#region src/injectHotkey.ts
-/**
-* Angular inject-based API 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.
-*
-* Call in an injection context (e.g. constructor or field initializer).
-* Uses effect() to track reactive dependencies and update registration
-* when options or the callback change.
-* `enabled: false` keeps the registration (visible in devtools) and only suppresses firing; the same
-* handle is updated instead of unregistering and re-registering when identity is unchanged.
-*
-* @param hotkey - The hotkey string (e.g. 'Mod+S', 'Escape') or getter function
-* @param callback - The function to call when the hotkey is pressed
-* @param options - Options for the hotkey behavior, or getter for reactive options
-*
-* @example
-* ```ts
-* @Component({ ... })
-* export class SaveButtonComponent {
-*   private readonly saveCount = signal(0)
-*
-*   constructor() {
-*     injectHotkey('Mod+S', (event, { hotkey }) => {
-*       event.preventDefault()
-*       this.saveCount.update(c => c + 1)
-*     })
-*   }
-* }
-* ```
-*
-* @example
-* ```ts
-* @Component({ ... })
-* export class ModalComponent {
-*   isOpen = signal(true)
-*
-*   constructor() {
-*     injectHotkey('Escape', () => this.close(), () => ({ enabled: this.isOpen() }))
-*   }
-* }
-* ```
-*
-* @example
-* ```ts
-* @Component({ ... })
-* export class EditorComponent {
-*   private readonly editorRef = viewChild<ElementRef<HTMLDivElement>>('editorRef')
-*
-*   constructor() {
-*     injectHotkey('Mod+B', () => this.toggleBold(), () => ({
-*       target: this.editorRef()?.nativeElement ?? null,
-*     }))
-*   }
-* }
-* ```
-*/
 function injectHotkey(hotkey, callback, options = {}) {
-	const defaultOptions = injectDefaultHotkeysOptions();
-	const manager = getHotkeyManager();
-	const destroyRef = inject(DestroyRef);
-	let registration = null;
-	let lastHotkeyString = null;
-	let lastTarget = null;
-	destroyRef.onDestroy(() => {
-		if (registration?.isActive) {
-			registration.unregister();
-			registration = null;
-		}
-		lastHotkeyString = null;
-		lastTarget = null;
-	});
-	effect(() => {
-		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;
-		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;
-	});
+	injectHotkeys(() => [{
+		hotkey: typeof hotkey === "function" ? hotkey() : hotkey,
+		callback,
+		options: typeof options === "function" ? options() : options
+	}]);
 }
 
 //#endregion

package/dist/injectHotkeyHint.d.ts

@@ -1,12 +1,12 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 import { Signal } from "@angular/core";
 //#region src/injectHotkeyHint.d.ts
 /**
- * Returns a computed signal indicating whether held modifiers reveal this shortcut.
- * Call in an injection context; pass signal getters for changing inputs.
- * 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 a signal indicating whether held modifiers reveal this shortcut.
+ * Pass getters to track changing hotkeys and options. 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 injectHotkeyHint(hotkey: RegisterableHotkey | (() => RegisterableHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): Signal<boolean>;
+export declare function injectHotkeyHint(hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): Signal<boolean>;
 //#endregion

package/dist/injectHotkeyHint.js

@@ -1,18 +1,25 @@
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { injectHotkeysContext } from "./hotkeys-provider.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed } from "@angular/core";
 import { injectSelector } from "@tanstack/angular-store";
 
 //#region src/injectHotkeyHint.ts
 /**
-* Returns a computed signal indicating whether held modifiers reveal this shortcut.
-* Call in an injection context; pass signal getters for changing inputs.
-* 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 a signal indicating whether held modifiers reveal this shortcut.
+* Pass getters to track changing hotkeys and options. 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 injectHotkeyHint(hotkey, options = {}) {
+	const context = injectHotkeysContext();
 	const held = injectSelector(getKeyStateTracker().store, (state) => state.heldKeys);
-	return computed(() => matchesHeldModifiers(typeof hotkey === "function" ? hotkey() : hotkey, held(), typeof options === "function" ? options() : options));
+	return computed(() => {
+		context.appHotkeysState();
+		const value = typeof hotkey === "function" ? hotkey() : hotkey;
+		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, context.appHotkeysStore).hotkey : value;
+		return resolved !== null && matchesHeldModifiers(resolved, held(), typeof options === "function" ? options() : options);
+	});
 }
 
 //#endregion

package/dist/injectHotkeyRecorder.d.ts

@@ -1,23 +1,29 @@
-import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { Hotkey, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 //#region src/injectHotkeyRecorder.d.ts
-export interface AngularHotkeyRecorder {
+export interface AngularHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
   /** Whether recording is currently active */
   readonly isRecording: () => boolean;
-  /** The currently recorded hotkey (for live preview) */
-  readonly recordedHotkey: () => Hotkey | null;
+  /** Chords recorded so far in a multi-step recording (for live preview) */
+  readonly steps: () => HotkeySequence;
+  /** The last committed hotkey */
+  readonly recordedHotkey: () => THotkey | null;
   /** Start recording a new hotkey */
   readonly startRecording: () => void;
-  /** Stop recording (same as cancel) */
+  /** Stop recording without calling onCancel */
   readonly stopRecording: () => void;
-  /** Cancel recording without saving */
+  /** Cancel recording and call onCancel */
   readonly cancelRecording: () => void;
+  /** Commit the recorded steps now (multi-step recordings) */
+  readonly commitRecording: () => void;
 }
 /**
  * Angular inject-based API for recording keyboard shortcuts.
  *
- * Thin wrapper around the framework-agnostic HotkeyRecorder class: captures
- * keyboard events, converts them to hotkey strings, and handles Escape to
- * cancel or Backspace/Delete to clear.
+ * 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. Escape cancels;
+ * Backspace/Delete removes the last step or clears.
  *
  * @param options - Configuration options for the recorder (or getter)
  * @returns Object with recording state signals and control functions
@@ -41,5 +47,9 @@ export interface AngularHotkeyRecorder {
  * }
  * ```
  */
-export declare function injectHotkeyRecorder(options: HotkeyRecorderOptions | (() => HotkeyRecorderOptions)): AngularHotkeyRecorder;
+export declare function injectHotkeyRecorder(options: HotkeyChordRecorderOptions): AngularHotkeyRecorder<HotkeyChord>;
+export declare function injectHotkeyRecorder(options: HotkeySequenceRecorderOptions): AngularHotkeyRecorder;
+export declare function injectHotkeyRecorder(options: () => HotkeySequenceRecorderOptions): AngularHotkeyRecorder;
+export declare function injectHotkeyRecorder(options: () => HotkeyChordRecorderOptions): AngularHotkeyRecorder<HotkeyChord>;
+export declare function injectHotkeyRecorder(options: () => HotkeyRecorderOptions): AngularHotkeyRecorder;
 //#endregion