@tanstack/angular-hotkeys 0.15.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.15.1",
+  "version": "0.16.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.17.0"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",

package/skills/angular-hotkeys/SKILL.md

@@ -0,0 +1,127 @@
+---
+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 and `meta`.                                                            |
+| `injectHotkeyHint(hotkey, options?)`         | Get a signal of whether held modifiers should reveal a shortcut's hint.                                                              |
+| `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),
+  }))
+}
+```