@tanstack/hotkeys 0.18.0 → 0.20.0

package/dist/key-state-tracker.js

@@ -1,5 +1,5 @@
 import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
-import { Store } from "@tanstack/store";
+import { createStore } from "./_store.js";
 
 //#region src/key-state-tracker.ts
 /**
@@ -51,7 +51,7 @@ var KeyStateTracker = class KeyStateTracker {
 	* The TanStack Store instance containing the tracker state.
 	* Use this to subscribe to state changes or access current state.
 	*/
-	store = new Store(getDefaultKeyStateTrackerState());
+	store = createStore(getDefaultKeyStateTrackerState());
 	#heldEntries = /* @__PURE__ */ new Map();
 	/** Window listeners as `[type, listener, capture]`, removed together on destroy. */
 	#listeners = [];

package/dist/validate.d.ts

@@ -42,8 +42,8 @@ export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationRes
  */
 export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
 /**
- * Validates a hotkey and logs warnings to the console.
- * Useful for development-time feedback.
+ * Validates a hotkey and logs errors and warnings to the console.
+ * Useful for development-time feedback. Logs nothing in production builds.
  *
  * @param hotkey - The hotkey string to validate
  * @returns True if the hotkey is valid (may still have warnings)

package/dist/validate.js

@@ -1,5 +1,4 @@
-import { ALL_KEYS, normalizeKeyName } from "./constants.js";
-import { modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
@@ -62,17 +61,13 @@ function validateChord(hotkey) {
 	const keyPart = parts[parts.length - 1];
 	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push(`Unknown modifier: '${modifier}'`);
 	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && physicalCodeOf(keyPart) === void 0) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
-	if (!isKnownKey(normalizeKeyName(keyPart))) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	if (physicalCodeOf(keyPart) === void 0 && !isKeyNameShape(keyPart)) warnings.push(`Unknown key: '${keyPart}'. Key names are case-sensitive, such as 'Escape' and 'F1'.`);
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
-/** Physical codes, single characters, and named keys are known. */
-function isKnownKey(key) {
-	return physicalCodeOf(key) !== void 0 || Array.from(key).length === 1 || ALL_KEYS.has(key);
-}
 /**
 * Validates a hotkey and throws an error if invalid.
 * Useful for development-time validation.
@@ -91,8 +86,8 @@ function assertValidHotkey(hotkey) {
 	if (!result.valid) throw new Error(`Invalid hotkey '${String(hotkey)}': ${result.errors.join(", ")}`);
 }
 /**
-* Validates a hotkey and logs warnings to the console.
-* Useful for development-time feedback.
+* Validates a hotkey and logs errors and warnings to the console.
+* Useful for development-time feedback. Logs nothing in production builds.
 *
 * @param hotkey - The hotkey string to validate
 * @returns True if the hotkey is valid (may still have warnings)
@@ -106,8 +101,10 @@ function assertValidHotkey(hotkey) {
 */
 function checkHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
-	if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
+	if (process.env.NODE_ENV !== "production") {
+		if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
+		if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
+	}
 	return result.valid;
 }
 

package/dist/vendor/@tanstack/store/dist/store.d.ts

@@ -0,0 +1,23 @@
+import { Observer, Subscription } from "./types.js";
+//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/store.d.ts
+//#region src/store.d.ts
+type StoreAction = (...args: Array<any>) => any;
+type StoreActionMap = Record<string, StoreAction>;
+type StoreActionsFactory<T, TActions extends StoreActionMap> = (store: {
+  setState: Store<T>['setState'];
+  get: Store<T>['get'];
+}) => TActions;
+type NonFunction<T> = T extends ((...args: Array<any>) => any) ? never : T;
+declare class Store<T, TActions extends StoreActionMap = never> {
+  private atom;
+  readonly actions: TActions;
+  constructor(getValue: (prev?: NoInfer<T>) => T);
+  constructor(initialValue: T);
+  constructor(initialValue: NonFunction<T>, actionsFactory: StoreActionsFactory<T, TActions>);
+  setState(updater: (prev: T) => T): void;
+  get state(): T;
+  get(): T;
+  subscribe(observerOrFn: Observer<T> | ((value: T) => void)): Subscription;
+}
+//#endregion
+export { Store, StoreAction, StoreActionMap, StoreActionsFactory };

package/dist/vendor/@tanstack/store/dist/types.d.ts

@@ -0,0 +1,11 @@
+//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/types.d.ts
+type Observer<T> = {
+  next?: (value: T) => void;
+  error?: (err: unknown) => void;
+  complete?: () => void;
+};
+interface Subscription {
+  unsubscribe: () => void;
+}
+//#endregion
+export { Observer, Subscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -39,9 +39,12 @@
     "dist",
     "skills"
   ],
-  "dependencies": {
+  "devDependencies": {
     "@tanstack/store": "^0.11.2"
   },
+  "inlinedDependencies": {
+    "@tanstack/store": "0.11.2"
+  },
   "scripts": {
     "clean": "premove ./build ./dist",
     "lint": "eslint ./src",

package/skills/hotkeys-core/SKILL.md

@@ -33,7 +33,7 @@ The library owns the keyboard. Register every shortcut with your framework adapt
 | Instead of                                                            | Use                                                                                                                                           |
 | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | A `keydown` listener that checks `event.key`, `metaKey`, or `ctrlKey` | A registered hotkey such as `'Mod+S'`. Inside a widget's own key handler, `matchesKeyboardEvent(event, 'Mod+Enter')`.                         |
-| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, and `formatForDisplay(hotkey)` for labels                                                                                |
+| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, `formatForDisplay(hotkey)` for labels, or `formatForDisplay({ key })` for held keys                                      |
 | Skipping events from text fields, calling `preventDefault`            | The defaults: single keys and Shift/Alt chords are skipped while typing, `Mod` chords and `Escape` still fire, and matched keys are prevented |
 | A shortcut registry, service, context, or wrapper hook                | The adapter API, called where each action lives. For one list of every shortcut, load `@tanstack/hotkeys#app-hotkeys`.                        |
 | A "shortcuts enabled" flag or topmost-dialog tracking                 | Scopes, with `exclusive` for dialogs                                                                                                          |
@@ -59,6 +59,7 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 - **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.
+- **Key names are case-sensitive.** Write `Escape`, `ArrowUp`, `F1`, and `+` as the types spell them; `escape`, `Esc`, `f1`, and `Plus` never match. Only letters match in any case. Hotkeys from plain JavaScript or saved data skip the types, so check them with `validateHotkey`.
 - **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`.
 - **Each open exclusive scope needs its own name.** A reusable dialog with a fixed scope name breaks when one dialog opens another: both share one scope and both handle `Escape`. Build the name per instance.
 - **A chord on a sequence's first key runs every time the sequence starts.** With `G` and `['G', 'G']`, the first `G` runs the chord. Later keys belong to the sequence. To show "waiting for the next key", read `matchedStepCount` from the adapter's registrations list.