@tanstack/angular-hotkeys 0.15.1 → 0.17.0

package/dist/index.d.ts

@@ -6,7 +6,8 @@ import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { AngularHotkeyRecorder, injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
 import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
+import { injectHotkeyScopesState } from "./injectHotkeyScopesState.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, MaybeGetter, 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, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/index.js

@@ -6,9 +6,10 @@ import { injectHeldKeyCodes } from "./injectHeldKeyCodes.js";
 import { injectKeyHold } from "./injectKeyHold.js";
 import { injectHotkeyRecorder } from "./injectHotkeyRecorder.js";
 import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
+import { injectHotkeyScopesState } from "./injectHotkeyScopesState.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/injectHotkeyHint.d.ts

@@ -3,10 +3,11 @@ import { Signal } from "@angular/core";
 //#region src/injectHotkeyHint.d.ts
 /**
  * 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.
+ * The hint shows only while the hotkey can fire: some registration of it is
+ * enabled and in an active scope. Pass getters to track changing hotkeys and
+ * options. A sequence reveals its hint from its first step, and an app hotkey
+ * matches its registrations by id and uses its effective hotkey (false while
+ * unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
 export declare function injectHotkeyHint(hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions)): Signal<boolean>;
 //#endregion

package/dist/injectHotkeyHint.js

@@ -1,24 +1,27 @@
 import { injectHotkeysContext } from "./hotkeys-provider.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed } from "@angular/core";
 import { injectSelector } from "@tanstack/angular-store";
 
 //#region src/injectHotkeyHint.ts
 /**
 * 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.
+* The hint shows only while the hotkey can fire: some registration of it is
+* enabled and in an active scope. Pass getters to track changing hotkeys and
+* options. A sequence reveals its hint from its first step, and an app hotkey
+* matches its registrations by id and uses its effective hotkey (false while
+* unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
 */
 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);
 	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);
+		return resolved !== null && matchesHeldModifiers(resolved, held(), typeof options === "function" ? options() : options) && registrations().size > 0 && manager.hasActiveRegistration(value);
 	});
 }
 

package/dist/injectHotkeyScopesState.d.ts

@@ -0,0 +1,27 @@
+import { HotkeyScopesState } from "@tanstack/hotkeys";
+import { Signal } from "@angular/core";
+//#region src/injectHotkeyScopesState.d.ts
+/**
+ * Angular inject-based API that returns a signal of the hotkey manager's
+ * scope state: the active scopes, the exclusive scope that owns the keyboard,
+ * and the scopes it allows or suspends. Updates when scopes activate or
+ * release.
+ *
+ * @returns Signal of the current scope state
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     @if (scopes().exclusive; as exclusive) {
+ *       <p>Shortcuts belong to {{ exclusive }}</p>
+ *     }
+ *   `,
+ * })
+ * export class KeyboardOwnerComponent {
+ *   scopes = injectHotkeyScopesState()
+ * }
+ * ```
+ */
+export declare function injectHotkeyScopesState(): Signal<HotkeyScopesState>;
+//#endregion

package/dist/injectHotkeyScopesState.js

@@ -0,0 +1,32 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+import { injectSelector } from "@tanstack/angular-store";
+
+//#region src/injectHotkeyScopesState.ts
+/**
+* Angular inject-based API that returns a signal of the hotkey manager's
+* scope state: the active scopes, the exclusive scope that owns the keyboard,
+* and the scopes it allows or suspends. Updates when scopes activate or
+* release.
+*
+* @returns Signal of the current scope state
+*
+* @example
+* ```ts
+* @Component({
+*   template: `
+*     @if (scopes().exclusive; as exclusive) {
+*       <p>Shortcuts belong to {{ exclusive }}</p>
+*     }
+*   `,
+* })
+* export class KeyboardOwnerComponent {
+*   scopes = injectHotkeyScopesState()
+* }
+* ```
+*/
+function injectHotkeyScopesState() {
+	return injectSelector(getHotkeyManager().scopes, (state) => state);
+}
+
+//#endregion
+export { injectHotkeyScopesState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Angular adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -19,7 +19,8 @@
     "tanstack",
     "hotkeys",
     "keyboard",
-    "shortcuts"
+    "shortcuts",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -32,11 +33,12 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
     "@tanstack/angular-store": "^0.11.2",
-    "@tanstack/hotkeys": "0.16.1"
+    "@tanstack/hotkeys": "0.18.0"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",

package/skills/angular-hotkeys/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: angular-hotkeys
+description: >-
+  Use when adding or fixing keyboard shortcuts in an Angular app with
+  @tanstack/angular-hotkeys: injectHotkey and injectHotkeys in an injection
+  context, signal-driven options, viewChild targets, provideHotkeys defaults
+  and component scopes, app hotkey injectors, recorders, held-key and hint
+  injectors, or replacing @HostListener keydown handlers.
+metadata:
+  purpose: >-
+    Angular bindings for TanStack Hotkeys: inject functions, signal-driven
+    options, provideHotkeys scopes, and the Angular-specific mistakes to avoid.
+  type: framework
+  framework: angular
+  library: '@tanstack/angular-hotkeys'
+  library_version: '0.15.0'
+sources:
+  - src/injectHotkey.ts
+  - src/injectHotkeys.ts
+  - src/hotkeys-provider.ts
+  - src/injectAppHotkeys.ts
+  - src/injectHotkeyRecorder.ts
+  - TanStack/hotkeys:docs/framework/angular/quick-start.md
+  - TanStack/hotkeys:docs/framework/angular/guides/provide-hotkeys-and-scopes.md
+requires:
+  - '@tanstack/hotkeys#hotkeys-core'
+---
+
+# TanStack Hotkeys in Angular
+
+Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).
+
+```ts
+import { Component, ElementRef, signal, viewChild } from '@angular/core'
+import { injectHotkey } from '@tanstack/angular-hotkeys'
+
+@Component({
+  selector: 'app-panel',
+  template: `<div #panel tabindex="0" (input)="isDirty.set(true)">Panel</div>`,
+})
+export class PanelComponent {
+  readonly isDirty = signal(false)
+  private readonly panel = viewChild<ElementRef<HTMLDivElement>>('panel')
+
+  constructor() {
+    injectHotkey(
+      'Mod+S',
+      () => this.save(),
+      () => ({ enabled: this.isDirty() }),
+    )
+    injectHotkey(
+      'Escape',
+      () => this.close(),
+      () => ({
+        target: this.panel()?.nativeElement ?? null,
+      }),
+    )
+  }
+
+  save() {}
+  close() {}
+}
+```
+
+## API
+
+| API                                          | What it's for                                                                                                                                                                                      |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                                                                |
+| `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.                                                                                                       |
+| `injectCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                              |
+| `injectHotkeyRecorder(options)`              | Record a chord or sequence the user presses, for a settings screen.                                                                                                                                |
+| `injectHotkeyRegistrations()`                | Get a signal listing every registered hotkey with its options, `meta`, and `status` (whether it's enabled and in an active scope).                                                                 |
+| `injectHotkeyScopesState()`                  | Get a signal of the active scopes and the exclusive scope that owns the keyboard.                                                                                                                  |
+| `injectHotkeyHint(hotkey, options?)`         | Get a signal of whether held modifiers should reveal a shortcut's hint. False unless a registration of the hotkey can fire: enabled, in an active scope, and with focus inside its element target. |
+| `injectKeyHold(key)`                         | Get a signal of whether one key is held.                                                                                                                                                           |
+| `injectHeldKeys()`                           | Get a signal of every key that's held right now.                                                                                                                                                   |
+| `injectHeldKeyCodes()`                       | Get a signal mapping each held key to its physical `event.code`.                                                                                                                                   |
+
+The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.
+
+No provider is required. Call the inject functions in a constructor or field initializer.
+
+## A dialog that owns the keyboard
+
+```ts
+import { Component, InjectionToken, inject, output } from '@angular/core'
+import { injectHotkey, provideHotkeys } from '@tanstack/angular-hotkeys'
+
+let nextDialogId = 0
+const DIALOG_SCOPE = new InjectionToken<string>('DIALOG_SCOPE')
+
+@Component({
+  selector: 'app-dialog',
+  providers: [
+    { provide: DIALOG_SCOPE, useFactory: () => `dialog-${++nextDialogId}` },
+    provideHotkeys({ scope: () => inject(DIALOG_SCOPE), exclusive: true }),
+  ],
+  template: `<div role="dialog"><ng-content /></div>`,
+})
+export class DialogComponent {
+  readonly closed = output()
+
+  constructor() {
+    injectHotkey('Escape', () => this.closed.emit())
+  }
+}
+```
+
+A component's `providers` apply to the component itself, so it can register its own scoped hotkeys. A fixed `scope: 'dialog'` would give every open dialog the same scope; the per-instance token gives each its own.
+
+## 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 `() => ({ ... })`.
+- **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.
+
+When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Angular](references/app-hotkeys.md).
+
+## API discovery and docs
+
+Signatures: `node_modules/@tanstack/angular-hotkeys/dist/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/angular/guides/<page>.md`, such as `hotkeys`, `provide-hotkeys-and-scopes`, or `app-hotkeys`. Devtools (Angular 21+): `hotkeysDevtoolsPlugin()` from `@tanstack/angular-hotkeys-devtools` with `provideTanStackDevtools`.

package/skills/angular-hotkeys/references/app-hotkeys.md

@@ -0,0 +1,80 @@
+# App hotkeys in Angular
+
+The `@tanstack/hotkeys#app-hotkeys` skill owns the rules. This is the Angular wiring.
+
+```ts
+// app-hotkeys.ts
+import { defineAppHotkeys } from '@tanstack/angular-hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' } },
+  'help.shortcuts': { hotkey: 'Mod+/', meta: { name: 'Keyboard shortcuts' } },
+})
+
+declare module '@tanstack/angular-hotkeys' {
+  interface Register {
+    appHotkeys: typeof appHotkeys
+  }
+}
+```
+
+```ts
+import { provideHotkeys } from '@tanstack/angular-hotkeys'
+import type { CustomHotkeys } from '@tanstack/angular-hotkeys'
+import { appHotkeys } from './app-hotkeys'
+
+const saved: CustomHotkeys = JSON.parse(localStorage.getItem('hotkeys') ?? '{}')
+
+export const appConfig = {
+  providers: [
+    provideHotkeys({
+      appHotkeys,
+      customHotkeys: saved,
+      onCustomHotkeysChange: (custom) =>
+        localStorage.setItem('hotkeys', JSON.stringify(custom)),
+    }),
+  ],
+}
+```
+
+When saved shortcuts come from a server, load them before `bootstrapApplication`. `injectAppHotkeys()` returns a signal, so register inside a function: `injectHotkey(() => this.appHotkeys()['doc.save'], () => this.save())`. Build a cheat sheet from `injectAppHotkeyList()`.
+
+A settings row records with `injectHotkeyRecorder` and saves through `injectCustomHotkeys`:
+
+```ts
+import { Component, computed, input } from '@angular/core'
+import {
+  formatForDisplay,
+  injectAppHotkeys,
+  injectCustomHotkeys,
+  injectHotkeyRecorder,
+} from '@tanstack/angular-hotkeys'
+import type { AppHotkeyId } from '@tanstack/angular-hotkeys'
+
+@Component({
+  selector: 'app-shortcut-row',
+  template: `
+    {{ appHotkey().meta?.name }}:
+    {{ appHotkey().hotkey ? format(appHotkey().hotkey!) : 'Unassigned' }}
+    <button (click)="recorder.startRecording()">Change</button>
+    <button (click)="custom.resetCustomHotkey(id())">Reset</button>
+  `,
+})
+export class ShortcutRowComponent {
+  readonly id = input.required<AppHotkeyId>()
+  readonly appHotkeys = injectAppHotkeys()
+  readonly appHotkey = computed(() => this.appHotkeys()[this.id()])
+  readonly custom = injectCustomHotkeys()
+  readonly format = formatForDisplay
+
+  readonly recorder = injectHotkeyRecorder(() => ({
+    maxSteps: Infinity,
+    validate: (hotkey) => {
+      const [conflict] = this.custom.findConflicts(this.id(), hotkey)
+      return conflict ? `Used by ${conflict.meta?.name ?? conflict.id}` : true
+    },
+    onRecord: (hotkey) => this.custom.setCustomHotkey(this.id(), hotkey),
+    onClear: () => this.custom.setCustomHotkey(this.id(), null),
+  }))
+}
+```