@tanstack/angular-hotkeys 0.14.5 → 0.15.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/hotkeys-provider.d.ts

@@ -1,6 +1,7 @@
 import { InjectHotkeyCommonOptions } from "./injectHotkey.js";
 import { AppHotkeys, AppHotkeysState, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { InjectionToken, Provider, Signal } from "@angular/core";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/hotkeys-provider.d.ts
 export interface HotkeysProviderOptions {
   /**
@@ -13,7 +14,19 @@ export interface HotkeysProviderOptions {
 }
 /** Options for `provideHotkeys`. */
 export interface ProvideHotkeysOptions {
+  /** Merged with the parent provider's defaults. */
   defaultOptions?: HotkeysProviderOptions;
+  /**
+   * See `HotkeysProviderScopeProps['scope']`. Getters, here and for
+   * `exclusive` and `enabled`, run in the provider's injection context, so
+   * they can `inject()` the component that provides them and read its
+   * signals.
+   */
+  scope?: MaybeGetter<HotkeysProviderScopeProps['scope']>;
+  /** See `HotkeysProviderScopeProps['exclusive']`. */
+  exclusive?: MaybeGetter<HotkeysProviderScopeProps['exclusive']>;
+  /** See `HotkeysProviderScopeProps['enabled']`. */
+  enabled?: MaybeGetter<HotkeysProviderScopeProps['enabled']>;
   /**
    * Every app hotkey, from `defineAppHotkeys`. Listed by
    * `injectAppHotkeyList` whether or not they are registered.
@@ -28,16 +41,27 @@ export interface ProvideHotkeysOptions {
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
 }
 export interface HotkeysContextValue {
+  /** Merged with every ancestor provider's defaults, including `hotkey.scope`. */
   readonly defaultOptions: HotkeysProviderOptions;
+  /** Whether this provider and every ancestor are enabled. */
+  readonly enabled: Signal<boolean>;
   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>;
+/** A value, or a signal or getter that returns it. */
+export type MaybeGetter<T> = T | (() => T);
 /**
  * Provides default options, app hotkeys, and the user's custom hotkeys to an
  * injector, such as the application or a component.
  *
+ * Provide it in a component to create a hotkey scope. A nested provider
+ * 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.
+ *
  * @example
  * ```ts
  * bootstrapApplication(App, {
@@ -51,6 +75,39 @@ export declare const HOTKEYS_INJECTION_TOKEN: InjectionToken<HotkeysContextValue
  *   ],
  * })
  * ```
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'app-edit-dialog',
+ *   providers: [provideHotkeys({ scope: 'edit-dialog', exclusive: true })],
+ *   template: `...`,
+ * })
+ * export class EditDialog {
+ *   constructor() {
+ *     injectHotkey('Escape', () => this.close())
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // A scope that follows the providing component's input.
+ * @Component({
+ *   selector: 'app-folder',
+ *   providers: [
+ *     provideHotkeys({
+ *       scope: () => inject(Folder).name(),
+ *       enabled: () => inject(Folder).current(),
+ *     }),
+ *   ],
+ *   template: `...`,
+ * })
+ * export class Folder {
+ *   readonly name = input.required<string>()
+ *   readonly current = input(false)
+ * }
+ * ```
  */
 export declare function provideHotkeys(options?: ProvideHotkeysOptions): Provider;
 export declare function injectHotkeysContext(): HotkeysContextValue;

package/dist/hotkeys-provider.js

@@ -1,20 +1,73 @@
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
-import { DestroyRef, InjectionToken, inject, signal } from "@angular/core";
+import { DestroyRef, InjectionToken, Injector, computed, effect, inject, runInInjectionContext, signal } from "@angular/core";
+import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/hotkeys-provider.ts
 const NO_APP_HOTKEYS = signal(null).asReadonly();
+const ROOT_CONTEXT = {
+	defaultOptions: {},
+	enabled: signal(true).asReadonly(),
+	appHotkeysStore: null,
+	appHotkeysState: NO_APP_HOTKEYS
+};
 const HOTKEYS_INJECTION_TOKEN = new InjectionToken("HOTKEYS_INJECTION_TOKEN", {
 	providedIn: "root",
-	factory: () => ({
-		defaultOptions: {},
-		appHotkeysStore: null,
-		appHotkeysState: NO_APP_HOTKEYS
-	})
+	factory: () => ROOT_CONTEXT
 });
+/** Creates a provider's context. Runs in an injection context. */
+function createHotkeysContext(options) {
+	const injector = inject(Injector);
+	const read = (value) => typeof value === "function" ? runInInjectionContext(injector, value) : value;
+	const parent = inject(HOTKEYS_INJECTION_TOKEN, {
+		skipSelf: true,
+		optional: true
+	}) ?? ROOT_CONTEXT;
+	const destroyRef = inject(DestroyRef);
+	const { appHotkeys, customHotkeys, onCustomHotkeysChange } = options;
+	let store = null;
+	let appHotkeysState = parent.appHotkeysState;
+	if (appHotkeys) {
+		store = new AppHotkeysStore(appHotkeys, {
+			customHotkeys,
+			onCustomHotkeysChange
+		});
+		const state = signal(store.store.state);
+		const subscription = store.store.subscribe(() => state.set(store.store.state));
+		destroyRef.onDestroy(() => subscription.unsubscribe());
+		if (typeof document !== "undefined") destroyRef.onDestroy(publishAppHotkeysStore(store));
+		appHotkeysState = state.asReadonly();
+	}
+	const enabled = computed(() => parent.enabled() && read(options.enabled) !== false);
+	const defaultOptions = computed(() => mergeHotkeysProviderDefaults(parent.defaultOptions, options.defaultOptions, read(options.scope)));
+	const scopeKey = computed(() => getHotkeysProviderScopeKey({
+		scope: read(options.scope),
+		exclusive: read(options.exclusive),
+		active: enabled(),
+		parent: parent.defaultOptions.hotkey?.scope
+	}));
+	if (typeof document !== "undefined") effect((onCleanup) => {
+		const key = scopeKey();
+		if (key) onCleanup(activateHotkeysProviderScope(key));
+	});
+	return {
+		get defaultOptions() {
+			return defaultOptions();
+		},
+		enabled,
+		appHotkeysStore: store ?? parent.appHotkeysStore,
+		appHotkeysState
+	};
+}
 /**
 * Provides default options, app hotkeys, and the user's custom hotkeys to an
 * injector, such as the application or a component.
 *
+* Provide it in a component to create a hotkey scope. A nested provider
+* 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.
+*
 * @example
 * ```ts
 * bootstrapApplication(App, {
@@ -28,32 +81,44 @@ const HOTKEYS_INJECTION_TOKEN = new InjectionToken("HOTKEYS_INJECTION_TOKEN", {
 *   ],
 * })
 * ```
+*
+* @example
+* ```ts
+* @Component({
+*   selector: 'app-edit-dialog',
+*   providers: [provideHotkeys({ scope: 'edit-dialog', exclusive: true })],
+*   template: `...`,
+* })
+* export class EditDialog {
+*   constructor() {
+*     injectHotkey('Escape', () => this.close())
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* // A scope that follows the providing component's input.
+* @Component({
+*   selector: 'app-folder',
+*   providers: [
+*     provideHotkeys({
+*       scope: () => inject(Folder).name(),
+*       enabled: () => inject(Folder).current(),
+*     }),
+*   ],
+*   template: `...`,
+* })
+* export class Folder {
+*   readonly name = input.required<string>()
+*   readonly current = input(false)
+* }
+* ```
 */
 function provideHotkeys(options = {}) {
 	return {
 		provide: HOTKEYS_INJECTION_TOKEN,
-		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()
-			};
-		}
+		useFactory: () => createHotkeysContext(options)
 	};
 }
 function injectHotkeysContext() {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, MaybeGetter, ProvideHotkeysOptions, injectDefaultHotkeysOptions, injectHotkeysContext, provideHotkeys } from "./hotkeys-provider.js";
 import { InjectHotkeyDefinition, injectHotkeys } from "./injectHotkeys.js";
 import { injectHeldKeys } from "./injectHeldKeys.js";
 import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
@@ -9,4 +9,4 @@ import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { InjectCustomHotkeysResult, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-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 };
+export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, MaybeGetter, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/injectAppHotkeys.d.ts

@@ -7,9 +7,9 @@ import { Signal } from "@angular/core";
  *
  * @example
  * ```ts
- * hotkeys = injectAppHotkeys()
+ * appHotkeys = injectAppHotkeys()
  * constructor() {
- *   injectHotkey(() => this.hotkeys()['doc.save'], () => this.save())
+ *   injectHotkey(() => this.appHotkeys()['doc.save'], () => this.save())
  * }
  * ```
  */

package/dist/injectAppHotkeys.js

@@ -17,9 +17,9 @@ function injectRequiredStore(name) {
 *
 * @example
 * ```ts
-* hotkeys = injectAppHotkeys()
+* appHotkeys = injectAppHotkeys()
 * constructor() {
-*   injectHotkey(() => this.hotkeys()['doc.save'], () => this.save())
+*   injectHotkey(() => this.appHotkeys()['doc.save'], () => this.save())
 * }
 * ```
 */

package/dist/injectHotkey.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey, Target } from "@tanstack/hotkeys";
 import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/injectHotkey.d.ts
 /**
@@ -43,5 +43,5 @@ type MaybeGetter<T> = T | (() => T);
  * ```
  */
 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;
+export declare function injectHotkey<const T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeGetter<InjectHotkeyOptionsFor<T>>): void;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.14.5",
+  "version": "0.15.0",
   "description": "Angular adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -36,7 +36,7 @@
   ],
   "dependencies": {
     "@tanstack/angular-store": "^0.11.2",
-    "@tanstack/hotkeys": "0.15.1"
+    "@tanstack/hotkeys": "0.16.0"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",