@tanstack/hotkeys 0.19.0 → 0.21.0

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.19.0",
+  "version": "0.21.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/app-hotkeys/SKILL.md

@@ -46,12 +46,11 @@ export const appHotkeys = defineAppHotkeys({
 })
 ```
 
-Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup.
+Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup. Pass saved data that loads later to `store.setOptions({ customHotkeys })` on the returned store; providers apply a changed `customHotkeys` prop themselves. `undefined` leaves custom hotkeys unchanged while data loads; `null` clears them, such as on sign-out.
 
 ## Pitfalls
 
 - **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.
-- **The provider reads `customHotkeys` once.** When saved shortcuts load asynchronously, render the provider after they arrive, or key it by user. Change shortcuts afterwards through the adapter's custom hotkeys API, not by updating the prop.
 - **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
 - **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are dropped with a warning, so renaming an id discards users' customizations.
 - **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.

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.