@tanstack/hotkeys 0.17.0 → 0.18.0

package/dist/_event-target.js

@@ -17,6 +17,17 @@ function getTargetDocument(target) {
 	return target.ownerDocument;
 }
 /**
+* Whether key presses reach a listener on `target` right now. Document and
+* window listeners receive every key press in their document. An element
+* receives them only while focus is inside it, including inside a shadow
+* root it contains.
+*/
+function targetHasFocus(target) {
+	if (isWindow(target) || target.nodeType === 9) return true;
+	const active = target.getRootNode().activeElement;
+	return !!active && target.contains(active);
+}
+/**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
 * This includes:
@@ -191,4 +202,4 @@ function isEventForTarget(event, target) {
 }
 
 //#endregion
-export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent };
+export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };

package/dist/app-hotkeys.js

@@ -227,13 +227,12 @@ var AppHotkeysStore = class {
 			if (list) list.push(registration);
 			else byId.set(id, [registration]);
 		}
-		const manager = getHotkeyManager();
 		return Object.values(this.store.state.appHotkeys).map((appHotkey) => {
 			const registered = byId.get(appHotkey.id) ?? [];
-			const enabled = registered.filter((r) => r.options.enabled !== false);
+			const has = (status) => registered.some((r) => r.status === status);
 			return {
 				appHotkey,
-				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : enabled.length === 0 ? "disabled" : enabled.some((r) => manager.isScopeActive(r.options.scope)) ? "active" : "suspended",
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : has("active") ? "active" : has("suspended") ? "suspended" : "disabled",
 				isCustom: isCustomHotkey(appHotkey, this.#platform),
 				registrations: registered
 			};

package/dist/hotkey-manager.d.ts

@@ -1,5 +1,5 @@
 import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
-import { AppHotkeysStore } from "./app-hotkeys.js";
+import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
 /** An element, document, or window that hotkeys can listen on. */
@@ -41,9 +41,14 @@ export interface HotkeyOptions {
   platform?: 'mac' | 'windows' | 'linux';
   /**
    * Prevent the default browser action when the hotkey matches. For a
-   * sequence, every step that advances it does. Defaults to true
+   * sequence, every step that advances it does. Defaults to true.
+   *
+   * `'always'` also prevents it while a chord can't fire because it is
+   * disabled or its scope is inactive or suspended, unless another hotkey
+   * handles the key. It never stops propagation for such a chord. Sequences
+   * treat `'always'` as `true`.
    */
-  preventDefault?: boolean;
+  preventDefault?: boolean | 'always';
   /**
    * Stop event propagation when the hotkey matches. For a sequence, only the
    * last step does, so earlier steps reach other listeners. Defaults to true
@@ -118,8 +123,18 @@ export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySeque
 }
 /** A registered hotkey in the HotkeyManager. */
 export type HotkeyRegistration = HotkeyChordRegistration | HotkeySequenceRegistration;
+/**
+ * Whether a registration is on. Focus isn't checked: a registration on an
+ * element also needs focus inside that element to fire.
+ * - `'active'`: enabled, and its scope is active
+ * - `'suspended'`: enabled, but its scope is inactive or suspended by an exclusive scope
+ * - `'disabled'`: registered with `enabled: false`
+ */
+export type HotkeyRegistrationStatus = 'active' | 'suspended' | 'disabled';
 interface RegistrationViewBase {
   id: string;
+  /** Whether the registration is enabled and in an active scope. */
+  status: HotkeyRegistrationStatus;
   target: Target;
   triggerCount: number;
   hasFired: boolean;
@@ -372,6 +387,17 @@ export declare class HotkeyManager {
    * @returns True if a matching registration exists
    */
   isRegistered(hotkey: RegisterableHotkey, target?: Target): boolean;
+  /**
+   * Checks whether a hotkey can fire now: at least one registration is
+   * enabled, in an active scope, and listening where key presses go. A
+   * registration on `document` or `window` always is; one on an element is
+   * only while focus is inside that element. An app hotkey matches
+   * registrations by id, so custom hotkeys apply.
+   *
+   * @param hotkey - A chord, sequence, or app hotkey
+   * @returns True if a registration that can fire exists
+   */
+  hasActiveRegistration(hotkey: RegisterableHotkey | AppHotkey): boolean;
   /**
    * Destroys the manager and removes all listeners.
    */

package/dist/hotkey-manager.js

@@ -5,7 +5,7 @@ import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
@@ -13,10 +13,16 @@ import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConfl
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
+/** Whether a registration can fire now. Without a manager, scopes don't apply. */
+function getRegistrationStatus(options, manager) {
+	if (options.enabled === false) return "disabled";
+	return manager?.isScopeActive(options.scope) === false ? "suspended" : "active";
+}
 /** Creates a public view from an internal registration, stripping the callback. */
 function toHotkeyRegistrationView(reg) {
 	const base = {
 		id: reg.id,
+		status: getRegistrationStatus(reg.options, managerRef.current),
 		target: reg.target,
 		triggerCount: reg.triggerCount,
 		hasFired: reg.hasFired
@@ -270,7 +276,20 @@ var HotkeyManager = class HotkeyManager {
 	}
 	/** Whether a registration can fire now: enabled, in an active scope. */
 	#isLive(registration) {
-		return registration.options.enabled !== false && this.isScopeActive(registration.options.scope);
+		return getRegistrationStatus(registration.options, this) === "active";
+	}
+	/**
+	* Whether a hotkey that can fire would handle this key on any listener the
+	* event reaches, including other targets and phases. A sequence counts when
+	* the key matches its next step or its first step.
+	*/
+	#handledByLiveHotkey(event, eventType) {
+		const path = event.composedPath();
+		for (const registration of this.registrations.state.values()) {
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target, registration.target)) continue;
+			if ((registration.kind === "chord" ? [registration.parsedChord] : [registration.parsedSequence[registration.currentIndex], registration.parsedSequence[0]]).some((step) => matchKeyboardEvent(event, step, registration.options.platform).matched)) return true;
+		}
+		return false;
 	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
@@ -455,14 +474,20 @@ var HotkeyManager = class HotkeyManager {
 		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
+		let reserved = false;
 		for (const registration of registrations) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const live = this.#isLive(registration);
+			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
-			if (result.matched) {
-				matches.set(registration.id, result);
-				bestScore = Math.max(bestScore, result.score);
+			if (!result.matched) continue;
+			if (!live) {
+				reserved = true;
+				continue;
 			}
+			matches.set(registration.id, result);
+			bestScore = Math.max(bestScore, result.score);
 		}
+		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) event.preventDefault();
 		let bestRank = -1;
 		for (const registration of registrations) if (matches.get(registration.id)?.score === bestScore) bestRank = Math.max(bestRank, this.#scopeRank(registration.options.scope));
 		for (const snapshot of registrations) {
@@ -679,6 +704,21 @@ var HotkeyManager = class HotkeyManager {
 		return false;
 	}
 	/**
+	* Checks whether a hotkey can fire now: at least one registration is
+	* enabled, in an active scope, and listening where key presses go. A
+	* registration on `document` or `window` always is; one on an element is
+	* only while focus is inside that element. An app hotkey matches
+	* registrations by id, so custom hotkeys apply.
+	*
+	* @param hotkey - A chord, sequence, or app hotkey
+	* @returns True if a registration that can fire exists
+	*/
+	hasActiveRegistration(hotkey) {
+		const id = typeof hotkey === "object" && "~appHotkey" in hotkey ? hotkey.id : void 0;
+		for (const registration of this.registrations.state.values()) if (this.#isLive(registration) && targetHasFocus(registration.target) && (id === void 0 ? areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) : registration.options.appHotkeyId === id)) return true;
+		return false;
+	}
+	/**
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
 import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
-import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
@@ -13,4 +13,4 @@ import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
-export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/hotkeys-core/SKILL.md

@@ -56,7 +56,7 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 
 ## Pitfalls
 
-- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. To skip the action, keep the hotkey enabled and return early from the callback.
+- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. Add `preventDefault: 'always'` to keep the action blocked while the hotkey can't fire, whether it's disabled or its scope is off. Skip it for hotkeys turned off to give the key back to the browser, such as `Mod+C`, `Mod+Z`, `Tab`, or single keys behind a user's off switch. Don't keep the hotkey enabled and return early from the callback; the hotkey would also stay `active` in app hotkey lists and show its hint.
 - **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
 - **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
 - **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.

package/skills/hotkeys-core/references/scopes.md

@@ -9,3 +9,5 @@
 - A hotkey's `scope` option, or an app hotkey's declared `scope`, overrides the provider's.
 - Scopes follow the component tree, not the DOM, so a portaled dialog keeps its scope.
 - The hotkey that opens an exclusive dialog is suspended with the rest of the page. To close the dialog with the same keys, register that hotkey inside the dialog too.
+- To show which scope owns the keyboard, use the adapter's scope state API, such as `useHotkeyScopesState()` in React. Don't subscribe to `manager.scopes` by hand.
+- To list only hotkeys that are on, filter the adapter's registrations by `status === 'active'`. `'suspended'` means the hotkey's scope is inactive or suspended, and `'disabled'` means `enabled: false`.