@tanstack/lit-hotkeys 0.16.1 → 0.18.0

package/dist/controllers/hotkey-hint.d.ts

@@ -10,9 +10,16 @@ export declare class HotkeyHintController implements ReactiveController {
   private visible;
   /** Attaches to the host; getter arguments can read changing reactive properties. */
   constructor(host: ReactiveControllerHost, hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions));
-  /** Current visibility; combine with the action’s enabled state when rendering. */
+  /**
+   * Current visibility. True only while the hotkey can fire: some registration
+   * of it is enabled and in an active scope. A hotkey on an element counts only while focus is inside it.
+   */
   get value(): boolean;
-  /** Subscribes on connection and requests renders only when hint visibility changes. */
+  /**
+   * Subscribes on connection, then requests renders only when hint visibility
+   * changes. Reconnecting always requests one, since the hint may have changed
+   * while disconnected.
+   */
   hostConnected(): void;
   /** Re-evaluates getter arguments when host properties trigger an update. */
   hostUpdate(): void;

package/dist/controllers/hotkey-hint.js

@@ -1,5 +1,5 @@
 import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/controllers/hotkey-hint.ts
 /** Modifier hint controller. Getter arguments can read reactive host properties. */
@@ -16,20 +16,30 @@ var HotkeyHintController = class {
 		this.options = options;
 		host.addController(this);
 	}
-	/** Current visibility; combine with the action’s enabled state when rendering. */
+	/**
+	* Current visibility. True only while the hotkey can fire: some registration
+	* of it is enabled and in an active scope. A hotkey on an element counts only while focus is inside it.
+	*/
 	get value() {
 		return this.visible;
 	}
-	/** Subscribes on connection and requests renders only when hint visibility changes. */
+	/**
+	* Subscribes on connection, then requests renders only when hint visibility
+	* changes. Reconnecting always requests one, since the hint may have changed
+	* while disconnected.
+	*/
 	hostConnected() {
 		this.update();
+		this.host.requestUpdate();
 		const refresh = () => {
 			if (this.update()) this.host.requestUpdate();
 		};
 		const subscription = getKeyStateTracker().store.subscribe(refresh);
+		const registrations = getHotkeyManager().registrations.subscribe(refresh);
 		const unsubscribeAppHotkeys = subscribeAppHotkeys(refresh);
 		this.unsubscribe = () => {
 			subscription.unsubscribe();
+			registrations.unsubscribe();
 			unsubscribeAppHotkeys();
 		};
 	}
@@ -47,7 +57,7 @@ var HotkeyHintController = class {
 	update() {
 		const value = typeof this.hotkey === "function" ? this.hotkey() : this.hotkey;
 		const hotkey = isAppHotkey(value) ? resolveAppHotkey(value, getAppHotkeysStore()).hotkey : value;
-		const next = hotkey !== null && matchesHeldModifiers(hotkey, getKeyStateTracker().store.state.heldKeys, typeof this.options === "function" ? this.options() : this.options);
+		const next = hotkey !== null && matchesHeldModifiers(hotkey, getKeyStateTracker().store.state.heldKeys, typeof this.options === "function" ? this.options() : this.options) && getHotkeyManager().hasActiveRegistration(value);
 		const changed = next !== this.visible;
 		this.visible = next;
 		return changed;

package/dist/controllers/hotkey-scopes-state.d.ts

@@ -0,0 +1,40 @@
+import { HotkeyScopesState } from "@tanstack/hotkeys";
+import { ReactiveController, ReactiveControllerHost } from "lit";
+//#region src/controllers/hotkey-scopes-state.d.ts
+/**
+ * A Lit ReactiveController that reads the hotkey manager's scope state: the
+ * active scopes, the exclusive scope that owns the keyboard, and the scopes it
+ * allows or suspends. Triggers host updates when scopes activate or release.
+ *
+ * @example
+ * ```ts
+ * class KeyboardOwner extends LitElement {
+ *   private scopes = new HotkeyScopesStateController(this)
+ *
+ *   render() {
+ *     const { exclusive } = this.scopes.value
+ *     return exclusive ? html`<p>Shortcuts belong to ${exclusive}</p>` : nothing
+ *   }
+ * }
+ * ```
+ */
+export declare class HotkeyScopesStateController implements ReactiveController {
+  private _host;
+  /** The unsubscribe function to unsubscribe from the scopes store. */
+  private _unsubscribe;
+  /** The current scope state. */
+  get value(): HotkeyScopesState;
+  /**
+   * @param _host - The Lit component that owns this controller.
+   */
+  constructor(_host: ReactiveControllerHost);
+  /**
+   * Subscribes to the scopes store and updates the host when it changes.
+   * Connecting requests an update too, since scopes may have changed while
+   * disconnected.
+   */
+  hostConnected(): void;
+  /** Unsubscribes from the scopes store. */
+  hostDisconnected(): void;
+}
+//#endregion

package/dist/controllers/hotkey-scopes-state.js

@@ -0,0 +1,54 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+
+//#region src/controllers/hotkey-scopes-state.ts
+/**
+* A Lit ReactiveController that reads the hotkey manager's scope state: the
+* active scopes, the exclusive scope that owns the keyboard, and the scopes it
+* allows or suspends. Triggers host updates when scopes activate or release.
+*
+* @example
+* ```ts
+* class KeyboardOwner extends LitElement {
+*   private scopes = new HotkeyScopesStateController(this)
+*
+*   render() {
+*     const { exclusive } = this.scopes.value
+*     return exclusive ? html`<p>Shortcuts belong to ${exclusive}</p>` : nothing
+*   }
+* }
+* ```
+*/
+var HotkeyScopesStateController = class {
+	_host;
+	/** The unsubscribe function to unsubscribe from the scopes store. */
+	_unsubscribe;
+	/** The current scope state. */
+	get value() {
+		return getHotkeyManager().scopes.state;
+	}
+	/**
+	* @param _host - The Lit component that owns this controller.
+	*/
+	constructor(_host) {
+		this._host = _host;
+		this._host.addController(this);
+	}
+	/**
+	* Subscribes to the scopes store and updates the host when it changes.
+	* Connecting requests an update too, since scopes may have changed while
+	* disconnected.
+	*/
+	hostConnected() {
+		this._host.requestUpdate();
+		const subscription = getHotkeyManager().scopes.subscribe(() => this._host.requestUpdate());
+		this._unsubscribe = () => subscription.unsubscribe();
+	}
+	/** Unsubscribes from the scopes store. */
+	hostDisconnected() {
+		this._unsubscribe?.();
+		this._unsubscribe = void 0;
+	}
+};
+
+//#endregion
+export { HotkeyScopesStateController };

package/dist/controllers/index.d.ts

@@ -6,4 +6,5 @@ import { HotkeyRecorderController } from "./hotkey-recorder.js";
 import { HotkeyRegistrationsController } from "./hotkey-registrations.js";
 import { KeyHoldController } from "./key-hold.js";
 import { HotkeyHintController } from "./hotkey-hint.js";
-export { AppHotkeyControllerOptions, AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyControllerChordOptions, HotkeyControllerCommonOptions, HotkeyControllerOptions, HotkeyControllerOptionsFor, HotkeyControllerSequenceOptions, HotkeyControllerTarget, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, KeyHoldController };
+import { HotkeyScopesStateController } from "./hotkey-scopes-state.js";
+export { AppHotkeyControllerOptions, AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyControllerChordOptions, HotkeyControllerCommonOptions, HotkeyControllerOptions, HotkeyControllerOptionsFor, HotkeyControllerSequenceOptions, HotkeyControllerTarget, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, HotkeyScopesStateController, KeyHoldController };

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { HotkeyRecorderController } from "./controllers/hotkey-recorder.js";
 import { HotkeyRegistrationsController } from "./controllers/hotkey-registrations.js";
 import { KeyHoldController } from "./controllers/key-hold.js";
 import { HotkeyHintController } from "./controllers/hotkey-hint.js";
+import { HotkeyScopesStateController } from "./controllers/hotkey-scopes-state.js";
 import "./controllers/index.js";
 export * from "@tanstack/hotkeys";
-export { AppHotkeyControllerOptions, AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyControllerChordOptions, HotkeyControllerCommonOptions, HotkeyControllerOptions, HotkeyControllerOptionsFor, HotkeyControllerSequenceOptions, HotkeyControllerTarget, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, KeyHoldController, hotkey };
+export { AppHotkeyControllerOptions, AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyControllerChordOptions, HotkeyControllerCommonOptions, HotkeyControllerOptions, HotkeyControllerOptionsFor, HotkeyControllerSequenceOptions, HotkeyControllerTarget, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, HotkeyScopesStateController, KeyHoldController, hotkey };

package/dist/index.js

@@ -7,7 +7,8 @@ import { HotkeyRecorderController } from "./controllers/hotkey-recorder.js";
 import { HotkeyRegistrationsController } from "./controllers/hotkey-registrations.js";
 import { KeyHoldController } from "./controllers/key-hold.js";
 import { HotkeyHintController } from "./controllers/hotkey-hint.js";
+import { HotkeyScopesStateController } from "./controllers/hotkey-scopes-state.js";
 
 export * from "@tanstack/hotkeys"
 
-export { AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, KeyHoldController, hotkey };
+export { AppHotkeysController, HeldKeyCodesController, HeldKeysController, HotkeyController, HotkeyHintController, HotkeyRecorderController, HotkeyRegistrationsController, HotkeyScopesStateController, KeyHoldController, hotkey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/lit-hotkeys",
-  "version": "0.16.1",
+  "version": "0.18.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.18.0"
   },
   "devDependencies": {
     "lit": "^3.3.3"

package/skills/lit-hotkeys/SKILL.md

@@ -0,0 +1,94 @@
+---
+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, `meta`, and `status` (whether it's enabled and in an active scope).                                                                    |
+| `new HotkeyScopesStateController(host)`                  | Read `.value`, the active scopes and the exclusive scope that owns the keyboard.                                                                                                                  |
+| `new HotkeyHintController(host, hotkey, options?)`       | Read `.value`, 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. |
+| `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>
+    `
+  }
+}
+```