@tanstack/angular-hotkeys 0.19.1 → 0.20.0

package/dist/_zone.js

@@ -0,0 +1,14 @@
+import { NgZone, inject } from "@angular/core";
+
+//#region src/_zone.ts
+/**
+* Runs `fn` outside the Angular zone, so core listeners it attaches don't
+* run change detection on every event. Zoneless apps call `fn` directly.
+* Must be called in an injection context.
+*/
+function runOutsideZone(fn) {
+	return inject(NgZone).runOutsideAngular(fn);
+}
+
+//#endregion
+export { runOutsideZone };

package/dist/hotkeys-provider.d.ts

@@ -62,7 +62,9 @@ export type MaybeGetter<T> = T | (() => T);
  * inherits app hotkeys and merges default options. With `scope`, hotkeys
  * injected in the component and its children fire only while it exists and
  * is enabled; with `exclusive`, only they fire. The scope activates when the
- * first hotkey in it is injected.
+ * first hotkey in it is injected. Angular creates the provider lazily, so a
+ * component with no hotkeys of its own calls `injectHotkeysContext()` to
+ * activate its scope.
  *
  * @example
  * ```ts
@@ -94,6 +96,21 @@ export type MaybeGetter<T> = T | (() => T);
  *
  * @example
  * ```ts
+ * // An overlay with no hotkeys that suspends the page's hotkeys.
+ * @Component({
+ *   selector: 'app-loading-overlay',
+ *   providers: [provideHotkeys({ scope: 'loading', exclusive: true })],
+ *   template: `...`,
+ * })
+ * export class LoadingOverlay {
+ *   constructor() {
+ *     injectHotkeysContext()
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
  * // A scope that follows the providing component's input.
  * @Component({
  *   selector: 'app-folder',
@@ -112,6 +129,10 @@ export type MaybeGetter<T> = T | (() => T);
  * ```
  */
 export declare function provideHotkeys(options?: ProvideHotkeysOptions): Provider;
+/**
+ * Returns the nearest provider's context. Injecting it activates that
+ * provider's scope.
+ */
 export declare function injectHotkeysContext(): HotkeysContextValue;
 export declare function injectDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/hotkeys-provider.js

@@ -71,7 +71,9 @@ function createHotkeysContext(options) {
 * inherits app hotkeys and merges default options. With `scope`, hotkeys
 * injected in the component and its children fire only while it exists and
 * is enabled; with `exclusive`, only they fire. The scope activates when the
-* first hotkey in it is injected.
+* first hotkey in it is injected. Angular creates the provider lazily, so a
+* component with no hotkeys of its own calls `injectHotkeysContext()` to
+* activate its scope.
 *
 * @example
 * ```ts
@@ -103,6 +105,21 @@ function createHotkeysContext(options) {
 *
 * @example
 * ```ts
+* // An overlay with no hotkeys that suspends the page's hotkeys.
+* @Component({
+*   selector: 'app-loading-overlay',
+*   providers: [provideHotkeys({ scope: 'loading', exclusive: true })],
+*   template: `...`,
+* })
+* export class LoadingOverlay {
+*   constructor() {
+*     injectHotkeysContext()
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
 * // A scope that follows the providing component's input.
 * @Component({
 *   selector: 'app-folder',
@@ -126,6 +143,10 @@ function provideHotkeys(options = {}) {
 		useFactory: () => createHotkeysContext(options)
 	};
 }
+/**
+* Returns the nearest provider's context. Injecting it activates that
+* provider's scope.
+*/
 function injectHotkeysContext() {
 	return inject(HOTKEYS_INJECTION_TOKEN);
 }

package/dist/injectHeldKeyCodes.js

@@ -1,4 +1,5 @@
 import { injectSelector } from "./_injectSelector.js";
+import { runOutsideZone } from "./_zone.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 
 //#region src/injectHeldKeyCodes.ts
@@ -26,7 +27,7 @@ import { getKeyStateTracker } from "@tanstack/hotkeys";
 * ```
 */
 function injectHeldKeyCodes() {
-	const tracker = getKeyStateTracker();
+	const tracker = runOutsideZone(getKeyStateTracker);
 	return injectSelector(tracker.store, (state) => state.heldCodes);
 }
 

package/dist/injectHeldKeys.js

@@ -1,4 +1,5 @@
 import { injectSelector } from "./_injectSelector.js";
+import { runOutsideZone } from "./_zone.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 
 //#region src/injectHeldKeys.ts
@@ -21,7 +22,7 @@ import { getKeyStateTracker } from "@tanstack/hotkeys";
 * ```
 */
 function injectHeldKeys() {
-	const tracker = getKeyStateTracker();
+	const tracker = runOutsideZone(getKeyStateTracker);
 	return injectSelector(tracker.store, (state) => state.heldKeys);
 }
 

package/dist/injectHotkey.d.ts

@@ -1,12 +1,13 @@
 import { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { ElementRef, Signal } from "@angular/core";
 import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/injectHotkey.d.ts
 /**
- * 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.
+ * The element to listen on: an element, an `ElementRef`, or a signal of
+ * either, such as `viewChild<ElementRef>('panel')`. A `null` target, or a
+ * signal of `undefined`, skips registration until the element exists.
  */
-export type InjectHotkeyTarget = Target | null;
+export type InjectHotkeyTarget = Target | ElementRef<Target> | Signal<Target | ElementRef<Target> | null | undefined> | null;
 /** Options shared by chords and sequences. */
 export type InjectHotkeyOptions = AdapterHotkeyOptions<InjectHotkeyTarget>;
 /** Options for a chord such as `'Mod+S'`. */

package/dist/injectHotkeyHint.js

@@ -1,5 +1,6 @@
 import { injectHotkeysContext } from "./hotkeys-provider.js";
 import { injectSelector } from "./_injectSelector.js";
+import { runOutsideZone } from "./_zone.js";
 import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed } from "@angular/core";
 
@@ -17,7 +18,7 @@ function injectHotkeyHint(hotkey, options = {}) {
 	const context = injectHotkeysContext();
 	const manager = getHotkeyManager();
 	const registrations = injectSelector(manager.registrations, (state) => state);
-	const held = injectSelector(getKeyStateTracker().store, (state) => state.heldKeys);
+	const held = injectSelector(runOutsideZone(getKeyStateTracker).store, (state) => state.heldKeys);
 	return computed(() => {
 		context.appHotkeysState();
 		const value = typeof hotkey === "function" ? hotkey() : hotkey;

package/dist/injectHotkeyRecorder.js

@@ -1,23 +1,33 @@
 import { injectDefaultHotkeysOptions } from "./hotkeys-provider.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
-import { DestroyRef, computed, effect, inject, linkedSignal, untracked } from "@angular/core";
+import { DestroyRef, NgZone, computed, effect, inject, linkedSignal, untracked } from "@angular/core";
 import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/injectHotkeyRecorder.ts
 function injectHotkeyRecorder(options) {
 	const defaultOptions = injectDefaultHotkeysOptions();
 	const destroyRef = inject(DestroyRef);
-	const recorderSignal = computed(() => untracked(() => {
-		const resolvedOptions = typeof options === "function" ? options() : options;
-		return new HotkeyRecorder(withDefaults(defaultOptions.hotkeyRecorder, resolvedOptions));
-	}));
+	const zone = inject(NgZone);
+	const resolve = () => {
+		const resolved = withDefaults(defaultOptions.hotkeyRecorder, typeof options === "function" ? options() : options);
+		for (const key of [
+			"onRecord",
+			"onCancel",
+			"onClear",
+			"onReject"
+		]) {
+			const callback = resolved[key];
+			if (callback) resolved[key] = (...args) => zone.run(callback, null, args);
+		}
+		return resolved;
+	};
+	const recorderSignal = computed(() => untracked(() => new HotkeyRecorder(resolve())));
 	const recorderStore = computed(() => untracked(() => recorderSignal().store));
 	const isRecording = injectLazyStore(recorderStore, (state) => state.isRecording);
 	const steps = injectLazyStore(recorderStore, (state) => state.steps);
 	const recordedHotkey = injectLazyStore(recorderStore, (state) => state.recordedHotkey);
 	effect(() => {
-		const resolved = typeof options === "function" ? options() : options;
-		recorderSignal().setOptions(withDefaults(defaultOptions.hotkeyRecorder, resolved));
+		recorderSignal().setOptions(resolve());
 	});
 	destroyRef.onDestroy(() => {
 		recorderSignal().destroy();
@@ -26,7 +36,7 @@ function injectHotkeyRecorder(options) {
 		isRecording,
 		steps,
 		recordedHotkey,
-		startRecording: () => recorderSignal().start(),
+		startRecording: () => zone.runOutsideAngular(() => recorderSignal().start()),
 		stopRecording: () => recorderSignal().stop(),
 		cancelRecording: () => recorderSignal().cancel(),
 		commitRecording: () => recorderSignal().commit()

package/dist/injectHotkeys.d.ts

@@ -13,7 +13,9 @@ export type InjectHotkeyDefinition = AdapterHotkeyDefinition<InjectHotkeyTarget>
  * Options merge in this order: provider defaults, app hotkey declaration,
  * commonOptions, per-hotkey options. Each option applies only to the kinds
  * that support it. Unbound app hotkeys and empty sequences register nothing.
- * A `null` target skips registration until it is set.
+ * A target may be an element, an `ElementRef`, or a signal of either, such
+ * as `viewChild('panel')`. A `null` target, or a signal of `undefined`, skips
+ * registration until the element exists.
  *
  * @example
  * ```ts

package/dist/injectHotkeys.js

@@ -1,5 +1,5 @@
 import { injectHotkeysContext } from "./hotkeys-provider.js";
-import { DestroyRef, effect, inject, untracked } from "@angular/core";
+import { DestroyRef, ElementRef, NgZone, effect, inject, untracked } from "@angular/core";
 import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
 
 //#region src/injectHotkeys.ts
@@ -10,7 +10,9 @@ import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkey
 * Options merge in this order: provider defaults, app hotkey declaration,
 * commonOptions, per-hotkey options. Each option applies only to the kinds
 * that support it. Unbound app hotkeys and empty sequences register nothing.
-* A `null` target skips registration until it is set.
+* A target may be an element, an `ElementRef`, or a signal of either, such
+* as `viewChild('panel')`. A `null` target, or a signal of `undefined`, skips
+* registration until the element exists.
 *
 * @example
 * ```ts
@@ -22,6 +24,7 @@ import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkey
 */
 function injectHotkeys(hotkeys, commonOptions = {}) {
 	const context = injectHotkeysContext();
+	const zone = inject(NgZone);
 	const bindings = createHotkeyBindings();
 	inject(DestroyRef).onDestroy(() => bindings.destroy());
 	effect(() => {
@@ -30,9 +33,16 @@ function injectHotkeys(hotkeys, commonOptions = {}) {
 			appHotkeysStore: context.appHotkeysStore,
 			defaults: context.defaultOptions.hotkey,
 			commonOptions: typeof commonOptions === "function" ? commonOptions() : commonOptions,
-			resolveTarget: (target) => target
+			resolveTarget: (target) => {
+				const value = typeof target === "function" ? target() : target;
+				return (value instanceof ElementRef ? value.nativeElement : value) ?? null;
+			}
 		});
-		untracked(() => bindings.update(definitions));
+		for (const definition of definitions) {
+			const callback = definition.callback;
+			definition.callback = (...args) => zone.run(callback, null, args);
+		}
+		untracked(() => zone.runOutsideAngular(() => bindings.update(definitions)));
 	});
 }
 

package/dist/injectKeyHold.js

@@ -1,4 +1,5 @@
 import { injectSelector } from "./_injectSelector.js";
+import { runOutsideZone } from "./_zone.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 import { computed } from "@angular/core";
 
@@ -37,7 +38,7 @@ import { computed } from "@angular/core";
 * ```
 */
 function injectKeyHold(key) {
-	const tracker = getKeyStateTracker();
+	const tracker = runOutsideZone(getKeyStateTracker);
 	const heldKeysSelector = injectSelector(tracker.store, (state) => state.heldKeys);
 	return computed(() => {
 		const normalizedKey = (typeof key === "function" ? key() : key).toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Angular adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.0"
+    "@tanstack/hotkeys": "0.22.1"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",
@@ -47,7 +47,8 @@
     "@angular/common": "^22.2.1",
     "@angular/core": "^22.2.1",
     "@angular/platform-browser-dynamic": "^22.2.1",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "zone.js": "~0.16.3"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/skills/angular-hotkeys/SKILL.md

@@ -48,13 +48,8 @@ export class PanelComponent {
       () => this.save(),
       () => ({ enabled: this.isDirty() }),
     )
-    injectHotkey(
-      'Escape',
-      () => this.close(),
-      () => ({
-        target: this.panel()?.nativeElement ?? null,
-      }),
-    )
+    // A viewChild signal target registers once the element renders.
+    injectHotkey('Escape', () => this.close(), { target: this.panel })
   }
 
   save() {}
@@ -69,7 +64,7 @@ export class PanelComponent {
 | `injectHotkey(hotkey, callback, options?)`   | Register one chord, sequence, or app hotkey for the component's or service's lifetime; options can be a function that reads signals.                                                               |
 | `injectHotkeys(definitions, commonOptions?)` | Register several hotkeys, or a function returning a list built from data, in one call.                                                                                                             |
 | `provideHotkeys(options)`                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys in the app config or a component's `providers`.                                                                 |
-| `injectHotkeysContext()`                     | Read the nearest provided defaults and enabled state, or `null` without a provider.                                                                                                                |
+| `injectHotkeysContext()`                     | Read the nearest provided defaults and enabled state. Activates that provider's scope.                                                                                                             |
 | `injectDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                         |
 | `injectAppHotkeys()`                         | Get a signal of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
 | `injectAppHotkeyList()`                      | Get a signal listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
@@ -116,7 +111,9 @@ A component's `providers` apply to the component itself, so it can register its
 
 ## Pitfalls
 
-- **Pass options as a function.** `{ enabled: this.isDirty() }` is read once, in the constructor. A `viewChild` read there is `undefined`, and an undefined target means `document`. Use `() => ({ ... })`.
+- **Pass options as a function.** `{ enabled: this.isDirty() }` is read once, in the constructor. Use `() => ({ ... })`.
+- **Pass the `viewChild` signal as `target`, not its value.** `this.panel()` in the constructor is `undefined`, and an undefined target means `document`. `{ target: this.panel }` waits for the element.
+- **An exclusive provider with no hotkeys never activates.** Angular creates providers lazily. Call `injectHotkeysContext()` in the component's constructor to activate the scope.
 - **Replace `@HostListener('document:keydown')` and `(keydown.control.s)` bindings with `injectHotkey`.**
 - **Register runtime lists in the constructor.** `injectHotkey` throws outside an injection context, such as in `ngOnInit`. For hotkeys from data, use `injectHotkeys(() => this.items().map(...))`.
 - **Call the inject functions directly.** A shortcut service or `injectShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, signal options, and app hotkeys.