@tanstack/hotkeys 0.24.0 → 0.25.0

package/dist/validate.d.ts

@@ -1,14 +1,15 @@
 import { Hotkey } from "./hotkey.types.js";
-//#region src/validate.d.ts
 /** A hotkey to validate: a chord string, a sequence, or untyped input such as saved data. */
 export type ValidatableHotkey = Hotkey | (string & {}) | ReadonlyArray<string>;
 /**
  * Validates a hotkey and returns any warnings or errors.
- * Sequences are validated step by step, and messages name the failing step.
+ * Each issue has a `reason` code, so apps can write their own messages.
+ * Issues in a sequence carry the index of their `step`.
  *
  * Checks for:
  * - Valid syntax (modifier+...+key format)
  * - Known modifiers
+ * - A key that isn't a modifier
  * - Known keys
  *
  * @param hotkey - The hotkey string to validate
@@ -20,10 +21,10 @@ export type ValidatableHotkey = Hotkey | (string & {}) | ReadonlyArray<string>;
  * // { valid: true, warnings: [], errors: [] }
  *
  * validateHotkey('')
- * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+ * // { valid: false, warnings: [], errors: [{ reason: 'empty' }] }
  *
  * validateHotkey(['G', 'Foo+H'])
- * // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
+ * // { valid: false, warnings: [], errors: [{ reason: 'unknown-modifier', part: 'Foo', step: 1 }] }
  * ```
  */
 export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationResult;
@@ -37,7 +38,7 @@ export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationRes
  * @example
  * ```ts
  * assertValidHotkey('Mod+S') // OK
- * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+ * assertValidHotkey('') // Throws Error: [hotkeys] Invalid hotkey '': empty
  * ```
  */
 export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
@@ -51,24 +52,43 @@ export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
  * @example
  * ```ts
  * checkHotkey('Control+escape')
- * // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
+ * // Console: [hotkeys] Hotkey 'Control+escape' may never fire: unknown-key 'escape'
  * // Returns: true
  *
  * checkHotkey('Ctl+K')
- * // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+ * // Console: [hotkeys] Invalid hotkey 'Ctl+K': unknown-modifier 'Ctl'
  * // Returns: false
  * ```
  */
 export declare function checkHotkey(hotkey: ValidatableHotkey): boolean;
+/**
+ * Why a hotkey is invalid or may never fire:
+ *
+ * - `'empty'`: the hotkey or sequence is empty.
+ * - `'empty-part'`: a part between `+` signs is empty or whitespace.
+ * - `'unknown-modifier'`: a modifier isn't one the library knows, such as `Ctl`.
+ * - `'invalid-physical-key'`: a bracketed key isn't a `KeyboardEvent.code`.
+ * - `'modifier-only'`: the key is a modifier, such as `Shift` or `[ShiftLeft]`.
+ * - `'unknown-key'` (warning): the key isn't written like a known key name.
+ *   Key names are case-sensitive, so `escape` never matches `Escape`.
+ */
+export type HotkeyIssueReason = 'empty' | 'empty-part' | 'unknown-modifier' | 'invalid-physical-key' | 'modifier-only' | 'unknown-key';
+/** One problem found by `validateHotkey`. */
+export interface HotkeyIssue {
+  reason: HotkeyIssueReason;
+  /** The part of the chord with the problem, such as `'Ctl'` in `'Ctl+K'`. */
+  part?: string;
+  /** For a sequence, the index of the step with the problem. */
+  step?: number;
+}
 /**
  * Result of validating a hotkey string.
  */
 export interface ValidationResult {
   /** Whether the hotkey is valid (can still have warnings) */
   valid: boolean;
-  /** Warning messages about potential issues */
-  warnings: Array<string>;
-  /** Error messages about invalid syntax */
-  errors: Array<string>;
-}
-//#endregion
+  /** Problems that may stop the hotkey from firing, such as an unknown key */
+  warnings: Array<HotkeyIssue>;
+  /** Problems that stop the hotkey from registering */
+  errors: Array<HotkeyIssue>;
+}

package/dist/validate.js

@@ -1,13 +1,15 @@
-import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { isKeyNameShape, isModifierCode, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
-//#region src/validate.ts
+// src/validate.ts
 /**
 * Validates a hotkey and returns any warnings or errors.
-* Sequences are validated step by step, and messages name the failing step.
+* Each issue has a `reason` code, so apps can write their own messages.
+* Issues in a sequence carry the index of their `step`.
 *
 * Checks for:
 * - Valid syntax (modifier+...+key format)
 * - Known modifiers
+* - A key that isn't a modifier
 * - Known keys
 *
 * @param hotkey - The hotkey string to validate
@@ -19,55 +21,71 @@ import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "
 * // { valid: true, warnings: [], errors: [] }
 *
 * validateHotkey('')
-* // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+* // { valid: false, warnings: [], errors: [{ reason: 'empty' }] }
 *
 * validateHotkey(['G', 'Foo+H'])
-* // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
+* // { valid: false, warnings: [], errors: [{ reason: 'unknown-modifier', part: 'Foo', step: 1 }] }
 * ```
 */
 function validateHotkey(hotkey) {
 	if (typeof hotkey !== "string") {
-		if (hotkey.length === 0) return {
-			valid: false,
-			warnings: [],
-			errors: ["Sequence cannot be empty"]
-		};
+		if (hotkey.length === 0) return invalid("empty");
 		if (hotkey.length === 1) return validateChord(hotkey[0]);
 		const results = hotkey.map(validateChord);
-		const prefixed = (key) => results.flatMap((result, i) => result[key].map((message) => `Step ${i + 1}: ${message}`));
+		const withStep = (key) => results.flatMap((result, step) => result[key].map((issue) => ({
+			...issue,
+			step
+		})));
 		return {
 			valid: results.every((result) => result.valid),
-			warnings: prefixed("warnings"),
-			errors: prefixed("errors")
+			warnings: withStep("warnings"),
+			errors: withStep("errors")
 		};
 	}
 	return validateChord(hotkey);
 }
-function validateChord(hotkey) {
-	const warnings = [];
-	const errors = [];
-	if (!hotkey || hotkey.trim() === "") return {
+function invalid(reason) {
+	return {
 		valid: false,
 		warnings: [],
-		errors: ["Hotkey cannot be empty"]
+		errors: [{ reason }]
 	};
+}
+function validateChord(hotkey) {
+	const warnings = [];
+	const errors = [];
+	if (!hotkey || hotkey.trim() === "") return invalid("empty");
 	const parts = splitChordParts(hotkey).map((p) => p.trim());
-	if (parts.length === 0 || parts.some((p) => p === "")) return {
-		valid: false,
-		warnings: [],
-		errors: ["Invalid hotkey format: empty parts detected"]
-	};
+	if (parts.length === 0 || parts.some((p) => p === "")) return invalid("empty-part");
 	const modifierParts = parts.slice(0, -1);
 	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 (physicalCodeOf(keyPart) === void 0 && !isKeyNameShape(keyPart)) warnings.push(`Unknown key: '${keyPart}'. Key names are case-sensitive, such as 'Escape' and 'F1'.`);
+	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push({
+		reason: "unknown-modifier",
+		part: modifier
+	});
+	const code = physicalCodeOf(keyPart);
+	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && code === void 0) errors.push({
+		reason: "invalid-physical-key",
+		part: keyPart
+	});
+	if (code !== void 0 ? isModifierCode(code) : modifierAlias(keyPart)) errors.push({
+		reason: "modifier-only",
+		part: keyPart
+	});
+	if (code === void 0 && !isKeyNameShape(keyPart)) warnings.push({
+		reason: "unknown-key",
+		part: keyPart
+	});
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
+/** Lists issues for a console message, such as `unknown-modifier 'Ctl'`. */
+function describeIssues(issues) {
+	return issues.map(({ reason, part, step }) => (step === void 0 ? "" : `step ${step + 1} `) + reason + (part === void 0 ? "" : ` '${part}'`)).join(", ");
+}
 /**
 * Validates a hotkey and throws an error if invalid.
 * Useful for development-time validation.
@@ -78,12 +96,12 @@ function validateChord(hotkey) {
 * @example
 * ```ts
 * assertValidHotkey('Mod+S') // OK
-* assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+* assertValidHotkey('') // Throws Error: [hotkeys] Invalid hotkey '': empty
 * ```
 */
 function assertValidHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (!result.valid) throw new Error(`Invalid hotkey '${String(hotkey)}': ${result.errors.join(", ")}`);
+	if (!result.valid) throw new Error(`[hotkeys] Invalid hotkey '${String(hotkey)}': ${describeIssues(result.errors)}`);
 }
 /**
 * Validates a hotkey and logs errors and warnings to the console.
@@ -95,22 +113,21 @@ function assertValidHotkey(hotkey) {
 * @example
 * ```ts
 * checkHotkey('Control+escape')
-* // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
+* // Console: [hotkeys] Hotkey 'Control+escape' may never fire: unknown-key 'escape'
 * // Returns: true
 *
 * checkHotkey('Ctl+K')
-* // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+* // Console: [hotkeys] Invalid hotkey 'Ctl+K': unknown-modifier 'Ctl'
 * // Returns: false
 * ```
 */
 function checkHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	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("; "));
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+		if (result.errors.length > 0) console.error(`[hotkeys] Invalid hotkey '${String(hotkey)}': ${describeIssues(result.errors)}`);
+		if (result.warnings.length > 0) console.warn(`[hotkeys] Hotkey '${String(hotkey)}' may never fire: ${describeIssues(result.warnings)}`);
 	}
 	return result.valid;
 }
 
-//#endregion
 export { assertValidHotkey, checkHotkey, validateHotkey };

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

@@ -1,5 +1,4 @@
 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>;
@@ -19,5 +18,4 @@ declare class Store<T, TActions extends StoreActionMap = never> {
   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

@@ -1,4 +1,3 @@
-//#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;
@@ -7,5 +6,4 @@ type Observer<T> = {
 interface Subscription {
   unsubscribe: () => void;
 }
-//#endregion
 export { Observer, Subscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -47,9 +47,9 @@
   },
   "scripts": {
     "clean": "premove ./build ./dist",
-    "lint": "eslint ./src",
-    "lint:fix": "eslint ./src --fix",
-    "test:eslint": "eslint ./src",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint ./src --fix",
+    "test:oxlint": "oxlint ./src",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc",

package/skills/app-hotkeys/SKILL.md

@@ -52,7 +52,7 @@ Augment `Register` in the adapter module you import from, such as `declare modul
 
 - **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'`.
 - **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.
+- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are silently dropped, 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`.
 - **Declare scopes on app hotkeys that share keys.** An app hotkey without a scope, or in `'global'`, conflicts with every other app hotkey on the same keys, so rebinding is rejected.
 - **Conflict checks treat physical and logical bindings as different.** A recorded `Mod+[KeyP]` doesn't conflict with a declared `Mod+P`, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as `Mod+[KeyP]`, makes them comparable.

package/skills/hotkeys-core/SKILL.md

@@ -59,7 +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`.
+- **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`. Its errors and warnings are reason codes such as `{ reason: 'unknown-key', part: 'escape' }`, not text, so map them to your own messages. A modifier-only hotkey, or one with an unknown modifier such as `Ctl+K`, registers nothing.
 - **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.