@tanstack/lit-hotkeys 0.17.0 → 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.17.0",
+  "version": "0.18.0",
   "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.18.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.                                                                                                                                                           |
+| `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`.