@inklu/keys 1.2.1 → 1.3.0

package/dist/{attributes-DbxlLdrb.d.ts → attributes-O6bXNKT9.d.ts}

@@ -12,6 +12,10 @@ type Binding = Chord | SequenceBinding;
 type BindingInput = Binding | ReadonlyArray<Binding>;
 /** JSON-serializable form of a binding. */
 type SerializedBinding = string | Array<string>;
+/** An arbitrary JSON-compatible value, e.g. from `JSON.parse` or persisted storage. */
+type Json = string | number | boolean | null | ReadonlyArray<Json> | {
+  readonly [key: string]: Json;
+};
 /** Trigger source for a command. */
 type CommandSource = "keyboard" | "api" | "dom";
 /** Context passed to a command's `run` handler. */
@@ -138,7 +142,7 @@ interface CommandKeymap<Id extends string = string> {
   /** Exports user overrides as JSON-serializable data. */
   export(): SerializedKeymap;
   /** Imports user overrides, replacing current overrides and saving to storage. */
-  import(data: unknown): void;
+  import(data: Json): void;
 }
 //#endregion
 //#region src/registry.d.ts
@@ -182,7 +186,7 @@ interface CommandsOptions<Id extends string = string> {
    */
   onRun?: (context: CommandContext) => void;
   /** Error handler called when a command execution fails. Defaults to `console.error`. */
-  onError?: (error: unknown, context: CommandContext) => void;
+  onError?: (error: Error, context: CommandContext) => void;
 }
 /** Options passed when manually running a command. */
 interface RunOptions {

package/dist/attributes.d.ts

@@ -1,2 +1,2 @@
-import { n as observe, t as ObserveOptions } from "./attributes-DbxlLdrb.js";
+import { n as observe, t as ObserveOptions } from "./attributes-O6bXNKT9.js";
 export { ObserveOptions, observe };

package/dist/attributes.js

@@ -5,7 +5,7 @@ const KEYS_ATTRIBUTE = "data-command-keys";
 * Wires a commands registry to DOM data attributes. Returns a cleanup function.
 */
 function observe(registry, options = {}) {
-	if (typeof document === "undefined") return () => {};
+	if (!("document" in globalThis)) return () => {};
 	const root = options.root ?? document;
 	const onClick = (event) => {
 		const target = event.target;
@@ -45,7 +45,7 @@ function observe(registry, options = {}) {
 		paintWithin(root);
 	});
 	let observer;
-	if (typeof MutationObserver !== "undefined") {
+	if ("MutationObserver" in globalThis) {
 		observer = new MutationObserver((mutations) => {
 			for (const mutation of mutations) {
 				if (mutation.type === "attributes" && mutation.target instanceof Element) {

package/dist/{index-D4UoKAQU.d.ts → index-nIJJ9qsY.d.ts}

@@ -1,4 +1,4 @@
-import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-DbxlLdrb.js";
+import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-O6bXNKT9.js";
 import { Hotkey } from "@tanstack/hotkeys";
 //#region src/bindings.d.ts
 /**

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-O6bXNKT9.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-nIJJ9qsY.js";
 export { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/index.js

@@ -1,3 +1,3 @@
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-DifrdRcK.js";
 export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-O6bXNKT9.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-nIJJ9qsY.js";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.

package/dist/react.js

@@ -1,6 +1,6 @@
 "use client";
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-DifrdRcK.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region src/react/hooks.ts

package/dist/{src-DyFUgmho.js → src-DifrdRcK.js}

@@ -1,6 +1,10 @@
 import { HotkeyRecorder, HotkeySequenceRecorder, detectPlatform, formatForDisplay, getHotkeyManager, getSequenceManager, normalizeHotkey, validateHotkey } from "@tanstack/hotkeys";
 //#region src/bindings.ts
 /** Comparing, validating and serializing hotkey bindings. */
+/** Type guard narrowing a JSON value to a string. */
+function isJsonString(value) {
+	return typeof value === "string";
+}
 /**
 * Creates a sequence binding from ordered hotkey steps.
 *
@@ -50,7 +54,7 @@ function serializeBinding(binding) {
 }
 /** Deserializes a stored value into a valid binding, or `null` if invalid. */
 function deserializeBinding(value) {
-	if (typeof value === "string") {
+	if (isJsonString(value)) {
 		const trimmed = value.trim();
 		return trimmed && isBindingValid(trimmed) ? trimmed : null;
 	}
@@ -396,6 +400,10 @@ var Binder = class {
 //#region src/keymap.ts
 /** Keymap managing default bindings and user overrides. */
 const DEFAULT_STORAGE_KEY = "inklu.keys";
+/** Type guard narrowing a JSON value to a plain object (excludes arrays and `null`). */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 var Keymap = class {
 	#defaults = /* @__PURE__ */ new Map();
 	#overrides = /* @__PURE__ */ new Map();
@@ -445,9 +453,7 @@ var Keymap = class {
 	}
 	/** Exports user overrides as a serialized keymap object. */
 	export() {
-		const data = {};
-		for (const [id, bindings] of this.#overrides) data[id] = bindings.map(serializeBinding);
-		return data;
+		return Object.fromEntries(Array.from(this.#overrides, ([id, bindings]) => [id, bindings.map(serializeBinding)]));
 	}
 	/** Imports serialized user overrides and saves to storage. */
 	import(data) {
@@ -473,7 +479,7 @@ var Keymap = class {
 		};
 	}
 	#read(data) {
-		if (typeof data !== "object" || data === null) return;
+		if (!isJsonObject(data)) return;
 		this.#overrides.clear();
 		for (const [id, value] of Object.entries(data)) {
 			if (!Array.isArray(value)) continue;
@@ -638,7 +644,7 @@ var CommandRegistry = class {
 		try {
 			return definition.when() === false ? "guarded" : null;
 		} catch (error) {
-			this.#reportError(error, {
+			this.#reportError(toError(error), {
 				id,
 				source: "api",
 				commands: this
@@ -898,13 +904,13 @@ var CommandRegistry = class {
 		if (this.#options.onRun) try {
 			this.#options.onRun(full);
 		} catch (error) {
-			this.#reportError(error, full);
+			this.#reportError(toError(error), full);
 		}
 		try {
 			const result = definition.run(full);
-			if (result instanceof Promise) result.catch((error) => this.#reportError(error, full));
+			if (result instanceof Promise) result.catch((cause) => this.#reportError(toError(cause), full));
 		} catch (error) {
-			this.#reportError(error, full);
+			this.#reportError(toError(error), full);
 		}
 	}
 	#reportError(error, context) {
@@ -1014,7 +1020,11 @@ var CommandRegistry = class {
 	}
 };
 function describeBinding(binding) {
-	return typeof binding === "string" ? `"${binding}"` : `"${binding.sequence.join(" ")}"`;
+	return isSequence(binding) ? `"${binding.sequence.join(" ")}"` : `"${binding}"`;
+}
+/** Normalizes an arbitrary thrown value into a real `Error` at the catch boundary. */
+function toError(cause) {
+	return cause instanceof Error ? cause : new Error(String(cause));
 }
 function isDevelopment() {
 	const environment = globalThis.process?.env?.NODE_ENV;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
   "keywords": [
     "keyboard",