@tanstack/lit-hotkeys 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/lit-hotkeys",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Lit adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -17,7 +17,8 @@
   "keywords": [
     "lit",
     "tanstack",
-    "keys"
+    "keys",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -30,10 +31,11 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.16.1"
+    "@tanstack/hotkeys": "0.17.0"
   },
   "devDependencies": {
     "lit": "^3.3.3"

package/skills/lit-hotkeys/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: lit-hotkeys
+description: >-
+  Use when adding or fixing keyboard shortcuts in Lit web components with
+  @tanstack/lit-hotkeys: the @hotkey decorator, HotkeyController with an
+  options function, element targets, scopes activated from the hotkey manager,
+  app hotkey and recorder controllers, held-key controllers, or replacing
+  keydown listeners in connectedCallback.
+metadata:
+  purpose: >-
+    Lit bindings for TanStack Hotkeys: the decorator, reactive controllers,
+    manager-activated scopes, and the Lit-specific mistakes to avoid.
+  type: framework
+  framework: lit
+  library: '@tanstack/lit-hotkeys'
+  library_version: '0.16.0'
+sources:
+  - src/decorators/hotkey.ts
+  - src/controllers/hotkey.ts
+  - src/controllers/app-hotkeys.ts
+  - src/controllers/hotkey-recorder.ts
+  - TanStack/hotkeys:docs/framework/lit/quick-start.md
+  - TanStack/hotkeys:docs/framework/lit/guides/app-hotkeys.md
+requires:
+  - '@tanstack/hotkeys#hotkeys-core'
+---
+
+# TanStack Hotkeys in Lit
+
+Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core`).
+
+```ts no-check
+import { LitElement, html } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
+import { HotkeyController, hotkey } from '@tanstack/lit-hotkeys'
+
+@customElement('my-editor')
+export class MyEditor extends LitElement {
+  @state() private dirty = false
+
+  @hotkey('Mod+K')
+  openSearch() {}
+
+  constructor() {
+    super()
+    this.addController(
+      new HotkeyController(
+        this,
+        'Mod+S',
+        () => this.save(),
+        () => ({ enabled: this.dirty }),
+      ),
+    )
+  }
+
+  save() {}
+
+  render() {
+    return html`<textarea @input=${() => (this.dirty = true)}></textarea>`
+  }
+}
+```
+
+## API
+
+| API                                                      | What it's for                                                                                                                                               |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@hotkey(hotkey, options?)`                              | Run the decorated method when the hotkey fires, with options fixed when the class is defined.                                                               |
+| `new HotkeyController(host, hotkey, callback, options?)` | Register a hotkey whose options can change; add it with `this.addController(...)`.                                                                          |
+| `provideAppHotkeys(appHotkeys, options?)`                | Declare app hotkeys and load the user's custom hotkeys once at startup, since Lit has no provider.                                                          |
+| `getHotkeyManager().activateScope(scope, options?)`      | Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off.                                                   |
+| `new AppHotkeysController(host)`                         | Read `appHotkeys`, the cheat sheet `list`, and `customHotkeys`, and change custom hotkeys with `setCustomHotkey`, `resetCustomHotkey`, and `findConflicts`. |
+| `new HotkeyRecorderController(host, options)`            | Record a chord or sequence the user presses, for a settings screen.                                                                                         |
+| `new HotkeyRegistrationsController(host)`                | Read `.hotkeys`, every registered hotkey with its options and `meta`.                                                                                       |
+| `new HotkeyHintController(host, hotkey, options?)`       | Read `.value`, whether held modifiers should reveal a shortcut's hint.                                                                                      |
+| `new KeyHoldController(host, key)`                       | Read `.value`, whether one key is held.                                                                                                                     |
+| `new HeldKeysController(host)`                           | Read `.value`, every key that's held right now.                                                                                                             |
+| `new HeldKeyCodesController(host)`                       | Read `.value`, which maps each held key to its physical `event.code`.                                                                                       |
+
+The package also re-exports `@tanstack/hotkeys`, such as `formatForDisplay`, `matchesKeyboardEvent`, and `defineAppHotkeys`.
+
+## Pitfalls
+
+- **Add `HotkeyController` to its host.** It is the only controller that doesn't add itself, so without `this.addController(...)` it never registers.
+- **`@hotkey` is a legacy decorator.** It needs `"experimentalDecorators": true` and `"useDefineForClassFields": false`; with standard decorators it fails with TS1241. Use `HotkeyController` in that case.
+- **Decorator options are fixed when the class is defined.** For options that read instance state, or a `target` from a `ref`, use `HotkeyController` with an options function, which reruns after each update.
+- **Release every scope you activate.** Lit has no provider, so a dialog activates its scope in `connectedCallback` with `this.release = getHotkeyManager().activateScope('dialog-1', { exclusive: true })` and calls `this.release()` in `disconnectedCallback`. A forgotten release keeps every other hotkey suspended. Give each open dialog its own scope name.
+
+When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Lit](references/app-hotkeys.md).
+
+## API discovery and docs
+
+Signatures: `node_modules/@tanstack/lit-hotkeys/dist/controllers/*.d.ts` and `dist/decorators/*.d.ts`. Guides: `https://tanstack.com/hotkeys/latest/docs/framework/lit/guides/<page>.md`, such as `hotkeys` or `app-hotkeys`.

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

@@ -0,0 +1,71 @@
+# App hotkeys in Lit
+
+The `@tanstack/hotkeys#app-hotkeys` skill owns the rules. This is the Lit wiring.
+
+```ts
+// app-hotkeys.ts
+import { defineAppHotkeys } from '@tanstack/lit-hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' } },
+  'help.shortcuts': { hotkey: 'Mod+/', meta: { name: 'Keyboard shortcuts' } },
+})
+
+declare module '@tanstack/lit-hotkeys' {
+  interface Register {
+    appHotkeys: typeof appHotkeys
+  }
+}
+```
+
+```ts
+// main.ts, before any element renders
+import { provideAppHotkeys } from '@tanstack/lit-hotkeys'
+import { appHotkeys } from './app-hotkeys'
+
+provideAppHotkeys(appHotkeys, {
+  customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+  onCustomHotkeysChange: (custom) =>
+    localStorage.setItem('hotkeys', JSON.stringify(custom)),
+})
+```
+
+`AppHotkeysController` throws until `provideAppHotkeys` has run. When saved shortcuts come from a server, await them first. Register with `@hotkey(appHotkeys['doc.save'])` or `HotkeyController`; both follow the user's custom hotkey. `AppHotkeysController` has `list` for a cheat sheet, plus `setCustomHotkey`, `findConflicts`, and `resetCustomHotkey`.
+
+A settings row records with `HotkeyRecorderController`:
+
+```ts no-check
+import { LitElement, html } from 'lit'
+import { property } from 'lit/decorators.js'
+import {
+  AppHotkeysController,
+  HotkeyRecorderController,
+  formatForDisplay,
+} from '@tanstack/lit-hotkeys'
+import type { AppHotkeyId } from '@tanstack/lit-hotkeys'
+
+export class ShortcutRow extends LitElement {
+  @property() hotkeyId!: AppHotkeyId
+  private app = new AppHotkeysController(this)
+  private recorder = new HotkeyRecorderController(this, () => ({
+    maxSteps: Infinity,
+    validate: (hotkey) => {
+      const [conflict] = this.app.findConflicts(this.hotkeyId, hotkey)
+      return conflict ? `Used by ${conflict.meta?.name ?? conflict.id}` : true
+    },
+    onRecord: (hotkey) => this.app.setCustomHotkey(this.hotkeyId, hotkey),
+    onClear: () => this.app.setCustomHotkey(this.hotkeyId, null),
+  }))
+
+  render() {
+    const { meta, hotkey } = this.app.appHotkeys[this.hotkeyId]
+    return html`
+      ${meta?.name}: ${hotkey ? formatForDisplay(hotkey) : 'Unassigned'}
+      <button @click=${() => this.recorder.startRecording()}>Change</button>
+      <button @click=${() => this.app.resetCustomHotkey(this.hotkeyId)}>
+        Reset
+      </button>
+    `
+  }
+}
+```