@inklu/keys 2.1.0 → 3.0.0

package/dist/react.d.mts

@@ -1,5 +1,5 @@
-import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as KeymapPersistence, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictKind, g as KeyCapture, h as Json, i as CommandContext, k as Platform, l as Commands, m as DisplayOptions, n as BindingInput, o as CommandHandler, p as ConflictOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as KeymapStorage, w as SerializedBinding, x as RunOptions, y as PendingSequence } from "./types-QEXldPnL.mjs";
-import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spokenBinding, g as validateBinding, h as seq, i as RebindMode, l as ariaKeyShortcuts, m as isSingleKeyBinding, n as CommandId, o as RebindState, p as BindingValidation, r as createCommands, s as Rebinder, t as matchCommands, u as bindingTokens } from "./index-3d9f54ln.mjs";
+import { C as Chord, S as SerializedKeymap, T as Platform, _ as RunBlockReason, a as CommandDefinition, b as SequenceBinding, c as CommandSource, d as Conflict, f as ConflictOptions, g as PlatformBindings, h as KeymapStore, i as CommandContext, l as Commands, m as KeyCapture, n as BindingInput, o as CommandHandler, p as Json, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as RunOptions, w as Key, x as SerializedBinding, y as ScopeOptions } from "./types-BxMI3b4a.mjs";
+import { a as Rebinder, c as importKeymap, d as bindingTokens, f as formatBinding, i as RebindState, l as webStorage, m as seq, n as createCommands, o as createRebinder, p as isSingleKeyBinding, r as RebindOptions, s as exportKeymap, t as CommandId, u as ariaKeyShortcuts } from "./index-BnB38jCF.mjs";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.
@@ -13,26 +13,27 @@ import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spoke
  * ```
  */
 export declare function useMountCommands<Id extends string>(registry: Commands<Id>): void;
-/** Returns all registered commands, re-rendering when the registry changes. */
+/**
+ * Returns all registered commands, re-rendering when the registry changes.
+ * Hydrates against `serverList()`, so a subtree that hydrates late still
+ * matches the server's HTML.
+ */
 export declare function useCommands<Id extends string>(registry: Commands<Id>): ReadonlyArray<Command<Id>>;
-/** Returns a specific command snapshot by ID. */
+/** Returns one command's snapshot, re-rendering only when that command changes. */
 export declare function useCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>): Command<Id> | undefined;
 /**
- * Returns display and accessibility shortcuts for a command's primary
- * binding: `tokens` for `<kbd>` elements, `aria` for `aria-keyshortcuts`
- * (chords only), and `spoken` for screen-reader text such as `"G then I"`.
+ * Returns a command's primary binding for people: `display` to read,
+ * `tokens` for `<kbd>` elements, and `aria` for `aria-keyshortcuts` (chords only).
  */
 export declare function useShortcut<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>): {
   display: string;
   tokens: ReadonlyArray<string>;
   aria: string;
-  spoken: string;
 };
 /**
  * Activates a scope for the lifecycle of the component. Scopes rank in the
- * order they are pushed, which here is the order React runs effects in: a
- * surface opened later ranks higher, but of a parent and a child opening in
- * the same render the child is pushed first.
+ * order React runs effects in: of a parent and a child opening in the same
+ * render, the child is pushed first.
  *
  * @example
  * ```tsx
@@ -41,12 +42,10 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
  */
 export declare function useScope<Id extends string>(registry: Commands<Id>, name: string, active?: boolean, options?: ScopeOptions): void;
 /**
- * Attaches what a command does for the lifecycle of the component, so the
- * behaviour lives where its state does. The latest `run` is always the one
- * called. While `enabled` is `false` the component steps back: the command
- * falls to the handler attached before it, or cannot run if there is none.
- * The handler attached last wins, and React attaches a parent's after its
- * children's when they mount together.
+ * Attaches what a command does for the lifecycle of the component. The latest
+ * `run` is always the one called, and the handler attached last wins. While
+ * `enabled` is `false` the command falls to the handler attached before it,
+ * or cannot run if there is none.
  *
  * @example
  * ```tsx
@@ -64,35 +63,14 @@ interface UseRebindResult<Id extends string = string> extends RebindState<Id> {
   /** Whether the shortcut has been customized by the user. */
   overridden: boolean;
   start: () => void;
-  stop: () => void;
   cancel: () => void;
   commit: () => void;
+  /** Unbinds the command. */
   clear: () => void;
+  /** Restores the default shortcut. */
   reset: () => void;
 }
 /** Hook for recording and configuring a command's keybindings. */
 export declare function useRebind<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>, options?: RebindOptions<Id>): UseRebindResult<Id>;
-/** Returns an array of keys currently held down. */
-export declare function useHeldKeys(): ReadonlyArray<string>;
-/**
- * Checks whether a specific key is currently held down.
- *
- * @example
- * ```tsx
- * const shift = useKeyHold("Shift");
- * ```
- */
-export declare function useKeyHold(key: string): boolean;
-/** Returns a map of held key identifiers to physical event codes. */
-export declare function useHeldKeyCodes(): Readonly<Record<string, string>>;
-/**
- * Returns currently active partially-typed sequences.
- *
- * @example
- * ```tsx
- * const pending = usePendingSequences(commands);
- * ```
- */
-export declare function usePendingSequences<Id extends string>(registry: Commands<Id>): ReadonlyArray<PendingSequence<Id>>;
 //#endregion
-export { type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapPersistence, type KeymapStorage, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };
+export { type Binding, type BindingInput, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type Json, type Key, type KeyCapture, type KeymapStore, type Platform, type PlatformBindings, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, seq, webStorage };

package/dist/react.mjs

@@ -1,81 +1,8 @@
 "use client";
-import { a as bindingTokens, c as isSingleKeyBinding, d as isModifierKey, f as keyName, i as ariaKeyShortcuts, l as seq, n as createCommands, o as formatBinding, r as createRebinder, s as spokenBinding, t as matchCommands, u as validateBinding } from "./src-B76YvObL.mjs";
+import { a as webStorage, c as formatBinding, i as importKeymap, l as isSingleKeyBinding, n as createRebinder, o as ariaKeyShortcuts, r as exportKeymap, s as bindingTokens, t as createCommands, u as seq } from "./src-CGKvYKjd.mjs";
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
-//#region src/held.ts
-/** Which keys are down right now. Listens only while something is subscribed. */
-const NONE = {
-	keys: [],
-	codes: {}
-};
-/** Held keys by physical key, so two keys producing one character stay apart. */
-const down = /* @__PURE__ */ new Map();
-const listeners = /* @__PURE__ */ new Set();
-let state = NONE;
-const identify = (event) => event.code || `key:${keyName(event.key)}`;
-function publish() {
-	const entries = [...down.values()];
-	state = entries.length === 0 ? NONE : {
-		keys: [...new Set(entries.map((entry) => entry.key))],
-		codes: Object.fromEntries(entries.map((entry) => [entry.key, entry.code]))
-	};
-	for (const listener of listeners) listener();
-}
-function onKeyDown(event) {
-	if (!event.key || down.has(identify(event))) return;
-	down.set(identify(event), {
-		key: keyName(event.key),
-		code: event.code
-	});
-	publish();
-}
-function onKeyUp(event) {
-	down.delete(identify(event));
-	if (event.key === "Meta") {
-		for (const [identity, entry] of down) if (!isModifierKey(entry.key)) down.delete(identity);
-	}
-	publish();
-}
-/** Leaving the window swallows the keyups, so nothing is held any more. */
-function onBlur() {
-	if (down.size === 0) return;
-	down.clear();
-	publish();
-}
-/** The keys held right now. Empty unless something is subscribed. */
-function heldKeys() {
-	return state;
-}
-/** Whether `key` is held, by the name `KeyboardEvent.key` gives it. */
-function isHeld(key) {
-	return state.keys.includes(keyName(key));
-}
-/** Watches held keys until the returned function is called. */
-function subscribeHeldKeys(listener) {
-	listeners.add(listener);
-	if (listeners.size === 1) {
-		document.addEventListener("keydown", onKeyDown, true);
-		document.addEventListener("keyup", onKeyUp, true);
-		window.addEventListener("blur", onBlur);
-	}
-	return () => {
-		listeners.delete(listener);
-		if (listeners.size > 0) return;
-		document.removeEventListener("keydown", onKeyDown, true);
-		document.removeEventListener("keyup", onKeyUp, true);
-		window.removeEventListener("blur", onBlur);
-		down.clear();
-		state = NONE;
-	};
-}
-//#endregion
 //#region src/react/hooks.ts
 const EMPTY_TOKENS = [];
-const EMPTY_CODES = {};
-const EMPTY_PENDING = [];
-const getEmptyTokens = () => EMPTY_TOKENS;
-const getEmptyCodes = () => EMPTY_CODES;
-const getEmptyPending = () => EMPTY_PENDING;
-const getFalse = () => false;
 /**
 * Mounts a commands registry for the lifecycle of the component.
 *
@@ -90,40 +17,40 @@ const getFalse = () => false;
 function useMountCommands(registry) {
 	useEffect(() => registry.mount(), [registry]);
 }
-function useCommandList(registry) {
+/**
+* Returns all registered commands, re-rendering when the registry changes.
+* Hydrates against `serverList()`, so a subtree that hydrates late still
+* matches the server's HTML.
+*/
+function useCommands(registry) {
 	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
 	const getSnapshot = useCallback(() => registry.list(), [registry]);
 	const getServerSnapshot = useCallback(() => registry.serverList(), [registry]);
 	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
-/** Returns all registered commands, re-rendering when the registry changes. */
-function useCommands(registry) {
-	return useCommandList(registry);
-}
-/** Returns a specific command snapshot by ID. */
+/** Returns one command's snapshot, re-rendering only when that command changes. */
 function useCommand(registry, id) {
-	const commands = useCommandList(registry);
-	return useMemo(() => commands.find((command) => command.id === id), [commands, id]);
+	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
+	const getSnapshot = useCallback(() => registry.get(id), [registry, id]);
+	const getServerSnapshot = useCallback(() => registry.serverList().find((command) => command.id === id), [registry, id]);
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 /**
-* Returns display and accessibility shortcuts for a command's primary
-* binding: `tokens` for `<kbd>` elements, `aria` for `aria-keyshortcuts`
-* (chords only), and `spoken` for screen-reader text such as `"G then I"`.
+* Returns a command's primary binding for people: `display` to read,
+* `tokens` for `<kbd>` elements, and `aria` for `aria-keyshortcuts` (chords only).
 */
 function useShortcut(registry, id) {
 	const command = useCommand(registry, id);
 	return useMemo(() => ({
 		display: command?.display[0] ?? "",
 		tokens: command?.tokens[0] ?? EMPTY_TOKENS,
-		aria: command?.aria ?? "",
-		spoken: command?.spoken ?? ""
+		aria: command?.aria ?? ""
 	}), [command]);
 }
 /**
 * Activates a scope for the lifecycle of the component. Scopes rank in the
-* order they are pushed, which here is the order React runs effects in: a
-* surface opened later ranks higher, but of a parent and a child opening in
-* the same render the child is pushed first.
+* order React runs effects in: of a parent and a child opening in the same
+* render, the child is pushed first.
 *
 * @example
 * ```tsx
@@ -143,12 +70,10 @@ function useScope(registry, name, active = true, options = {}) {
 	]);
 }
 /**
-* Attaches what a command does for the lifecycle of the component, so the
-* behaviour lives where its state does. The latest `run` is always the one
-* called. While `enabled` is `false` the component steps back: the command
-* falls to the handler attached before it, or cannot run if there is none.
-* The handler attached last wins, and React attaches a parent's after its
-* children's when they mount together.
+* Attaches what a command does for the lifecycle of the component. The latest
+* `run` is always the one called, and the handler attached last wins. While
+* `enabled` is `false` the command falls to the handler attached before it,
+* or cannot run if there is none.
 *
 * @example
 * ```tsx
@@ -172,31 +97,21 @@ function useCommandHandler(registry, id, run, enabled = true) {
 function useRebind(registry, id, options = {}) {
 	const latest = useRef(options);
 	latest.current = options;
-	const mode = options.mode ?? "chord";
+	const sequence = options.sequence === true;
 	const rebinder = useMemo(() => createRebinder(registry, id, {
-		mode,
+		sequence,
 		get apply() {
 			return latest.current.apply;
 		},
-		get add() {
-			return latest.current.add;
-		},
 		get rejectConflicts() {
 			return latest.current.rejectConflicts;
 		},
-		get ignoreInputs() {
-			return latest.current.ignoreInputs;
-		},
-		get idleTimeout() {
-			return latest.current.idleTimeout;
-		},
 		onRecord: (binding, conflicts) => latest.current.onRecord?.(binding, conflicts),
-		onCancel: () => latest.current.onCancel?.(),
-		onClear: () => latest.current.onClear?.()
+		onCancel: () => latest.current.onCancel?.()
 	}), [
 		registry,
 		id,
-		mode
+		sequence
 	]);
 	useEffect(() => rebinder.destroy, [rebinder]);
 	const getState = useCallback(() => rebinder.state, [rebinder]);
@@ -208,7 +123,6 @@ function useRebind(registry, id, options = {}) {
 		tokens: command?.tokens[0] ?? EMPTY_TOKENS,
 		overridden: command?.overridden ?? false,
 		start: rebinder.start,
-		stop: rebinder.stop,
 		cancel: rebinder.cancel,
 		commit: rebinder.commit,
 		clear: () => registry.keymap.set(id, null),
@@ -221,38 +135,5 @@ function useRebind(registry, id, options = {}) {
 		id
 	]);
 }
-/** Returns an array of keys currently held down. */
-function useHeldKeys() {
-	return useSyncExternalStore(subscribeHeldKeys, () => heldKeys().keys, getEmptyTokens);
-}
-/**
-* Checks whether a specific key is currently held down.
-*
-* @example
-* ```tsx
-* const shift = useKeyHold("Shift");
-* ```
-*/
-function useKeyHold(key) {
-	const getSnapshot = useCallback(() => isHeld(key), [key]);
-	return useSyncExternalStore(subscribeHeldKeys, getSnapshot, getFalse);
-}
-/** Returns a map of held key identifiers to physical event codes. */
-function useHeldKeyCodes() {
-	return useSyncExternalStore(subscribeHeldKeys, () => heldKeys().codes, getEmptyCodes);
-}
-/**
-* Returns currently active partially-typed sequences.
-*
-* @example
-* ```tsx
-* const pending = usePendingSequences(commands);
-* ```
-*/
-function usePendingSequences(registry) {
-	const subscribe = useCallback((onChange) => registry.subscribePending(onChange), [registry]);
-	const getSnapshot = useCallback(() => registry.pending(), [registry]);
-	return useSyncExternalStore(subscribe, getSnapshot, getEmptyPending);
-}
 //#endregion
-export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, useCommand, useCommandHandler, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useScope, useShortcut, validateBinding };
+export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, seq, useCommand, useCommandHandler, useCommands, useMountCommands, useRebind, useScope, useShortcut, webStorage };