@tanstack/lit-hotkeys 0.17.0 → 0.18.1

package/dist/controllers/_server.js

@@ -0,0 +1,12 @@
+//#region src/controllers/_server.ts
+/**
+* Whether the code runs on a server. With `@lit-labs/ssr`'s
+* `connectedCallback: true` option, the server calls `hostConnected` and never
+* calls `hostDisconnected`, so controllers must not subscribe there.
+*/
+function isServer() {
+	return typeof document === "undefined";
+}
+
+//#endregion
+export { isServer };

package/dist/controllers/app-hotkeys.js

@@ -1,4 +1,5 @@
 import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
+import { isServer } from "./_server.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 
 //#region src/controllers/app-hotkeys.ts
@@ -66,6 +67,7 @@ var AppHotkeysController = class {
 		return requireStore().findConflicts(id, hotkey);
 	}
 	hostConnected() {
+		if (isServer()) return;
 		const update = () => this._host.requestUpdate();
 		const unsubscribeAppHotkeys = subscribeAppHotkeys(update);
 		const registrations = getHotkeyManager().registrations.subscribe(update);

package/dist/controllers/held-key-codes.js

@@ -1,3 +1,4 @@
+import { isServer } from "./_server.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 
 //#region src/controllers/held-key-codes.ts
@@ -45,6 +46,7 @@ var HeldKeyCodesController = class {
 		const tracker = getKeyStateTracker();
 		this._value = tracker.store.state.heldCodes;
 		this._host.requestUpdate();
+		if (isServer()) return;
 		const subscription = tracker.store.subscribe(() => {
 			const { heldCodes } = tracker.store.state;
 			this._value = heldCodes;

package/dist/controllers/held-keys.js

@@ -1,3 +1,4 @@
+import { isServer } from "./_server.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 
 //#region src/controllers/held-keys.ts
@@ -41,6 +42,7 @@ var HeldKeysController = class {
 	}
 	/** Subscribes to the tracker store and updates the internal state when changes occur. */
 	hostConnected() {
+		if (isServer()) return;
 		const tracker = getKeyStateTracker();
 		const subscription = tracker.store.subscribe(() => {
 			const { heldKeys } = tracker.store.state;

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,6 @@
 import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
-import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
+import { isServer } from "./_server.js";
+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 +17,31 @@ 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();
+		if (isServer()) return;
 		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 +59,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-recorder.js

@@ -1,3 +1,4 @@
+import { isServer } from "./_server.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 
 //#region src/controllers/hotkey-recorder.ts
@@ -75,6 +76,7 @@ var HotkeyRecorderController = class {
 	}
 	/** Subscribes to the recorder store and updates the internal state when changes occur. */
 	hostConnected() {
+		if (isServer()) return;
 		const subscription = this._recorder.store.subscribe(() => {
 			const { isRecording, recordedHotkey, steps } = this._recorder.store.state;
 			if (isRecording !== this._isRecording || recordedHotkey !== this._recordedHotkey || steps !== this._steps) {

package/dist/controllers/hotkey-registrations.js

@@ -1,3 +1,4 @@
+import { isServer } from "./_server.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 
 //#region src/controllers/hotkey-registrations.ts
@@ -36,12 +37,13 @@ var HotkeyRegistrationsController = class {
 	hostConnected() {
 		const manager = getHotkeyManager();
 		const read = () => Array.from(manager.registrations.state.values()).map(toHotkeyRegistrationView);
+		this._hotkeys = read();
+		if (isServer()) return;
 		const subscription = manager.registrations.subscribe(() => {
 			this._hotkeys = read();
 			this._host.requestUpdate();
 		});
 		this._unsubscribe = () => subscription.unsubscribe();
-		this._hotkeys = read();
 	}
 	hostDisconnected() {
 		this._unsubscribe?.();

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,56 @@
+import { isServer } from "./_server.js";
+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();
+		if (isServer()) return;
+		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/hotkey.js

@@ -1,4 +1,5 @@
 import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
+import { isServer } from "./_server.js";
 import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
 
 //#region src/controllers/hotkey.ts
@@ -42,6 +43,7 @@ var HotkeyController = class {
 	}
 	/** Registers when connected and a target is available. */
 	hostConnected() {
+		if (isServer()) return;
 		this._connected = true;
 		this._unsubscribe = subscribeAppHotkeys(() => this._sync());
 		this._sync();

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/controllers/key-hold.d.ts

@@ -5,7 +5,9 @@ import { ReactiveController, ReactiveControllerHost } from "lit";
  * A Lit ReactiveController that tracks whether a specific key is currently held.
  *
  * Subscribes to the global KeyStateTracker and triggers host updates
- * when the held state of the specified key changes.
+ * when the held state of the specified key changes. Pass a getter to track a
+ * key that changes, such as a reactive property; it is read again on each
+ * host update.
  *
  * @example
  * ```ts
@@ -50,10 +52,14 @@ export declare class KeyHoldController implements ReactiveController {
   get value(): boolean;
   /**
    * @param _host - The Lit component that owns this controller.
-   * @param _key - The key to track (e.g. 'Shift', 'Control', 'A').
+   * @param _key - The key to track (e.g. 'Shift', 'Control', 'A'), or a getter.
    */
-  constructor(_host: ReactiveControllerHost, _key: IndividualKey);
+  constructor(_host: ReactiveControllerHost, _key: IndividualKey | (() => IndividualKey));
   hostConnected(): void;
+  /** Re-reads a getter key when host properties trigger an update. */
+  hostUpdate(): void;
   hostDisconnected(): void;
+  /** Recomputes the held state and reports whether it changed. */
+  private _refresh;
 }
 //#endregion

package/dist/controllers/key-hold.js

@@ -1,3 +1,4 @@
+import { isServer } from "./_server.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 
 //#region src/controllers/key-hold.ts
@@ -5,7 +6,9 @@ import { getKeyStateTracker } from "@tanstack/hotkeys";
 * A Lit ReactiveController that tracks whether a specific key is currently held.
 *
 * Subscribes to the global KeyStateTracker and triggers host updates
-* when the held state of the specified key changes.
+* when the held state of the specified key changes. Pass a getter to track a
+* key that changes, such as a reactive property; it is read again on each
+* host update.
 *
 * @example
 * ```ts
@@ -52,7 +55,7 @@ var KeyHoldController = class {
 	}
 	/**
 	* @param _host - The Lit component that owns this controller.
-	* @param _key - The key to track (e.g. 'Shift', 'Control', 'A').
+	* @param _key - The key to track (e.g. 'Shift', 'Control', 'A'), or a getter.
 	*/
 	constructor(_host, _key) {
 		this._host = _host;
@@ -60,22 +63,30 @@ var KeyHoldController = class {
 		this._host.addController(this);
 	}
 	hostConnected() {
-		const tracker = getKeyStateTracker();
-		const normalizedKey = this._key.toLowerCase();
-		const subscription = tracker.store.subscribe(() => {
-			const isHeld = tracker.store.state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey);
-			if (isHeld !== this._value) {
-				this._value = isHeld;
-				this._host.requestUpdate();
-			}
+		if (this._refresh()) this._host.requestUpdate();
+		if (isServer()) return;
+		const subscription = getKeyStateTracker().store.subscribe(() => {
+			if (this._refresh()) this._host.requestUpdate();
 		});
 		this._unsubscribe = () => subscription.unsubscribe();
 	}
+	/** Re-reads a getter key when host properties trigger an update. */
+	hostUpdate() {
+		this._refresh();
+	}
 	hostDisconnected() {
 		this._unsubscribe?.();
 		this._unsubscribe = void 0;
 		this._value = false;
 	}
+	/** Recomputes the held state and reports whether it changed. */
+	_refresh() {
+		const key = (typeof this._key === "function" ? this._key() : this._key).toLowerCase();
+		const next = getKeyStateTracker().store.state.heldKeys.some((heldKey) => heldKey.toLowerCase() === key);
+		const changed = next !== this._value;
+		this._value = next;
+		return changed;
+	}
 };
 
 //#endregion

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.17.0",
+  "version": "0.18.1",
   "description": "Lit adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.17.0"
+    "@tanstack/hotkeys": "0.19.0"
   },
   "devDependencies": {
     "lit": "^3.3.3"

package/skills/lit-hotkeys/SKILL.md

@@ -63,19 +63,20 @@ export class MyEditor extends LitElement {
 
 ## 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`.                                                                                       |
+| 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. Pass a getter, such as `() => this.key`, for a key that changes.                                                                                          |
+| `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`.