@inklu/keys 1.4.1 → 2.0.0

package/dist/react.d.mts

@@ -0,0 +1,82 @@
+import { A as HotkeySequence, C as Command, D as Conflict, E as CommandSource, F as SequenceBinding, I as SerializedBinding, M as KeymapStorage, N as Platform, O as ConflictKind, P as ScopeOptions, S as Chord, T as CommandDefinition, _ as bindingTokens, a as Commands, b as Binding, c as PendingSequence, d as createCommands, f as CommandKeymap, g as ariaKeyShortcuts, h as DisplayOptions, i as CommandId, j as KeymapPersistence, k as Hotkey, l as RunBlockReason, m as SerializedOverride, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as formatBinding, w as CommandContext, x as BindingInput, y as spokenBinding } from "./attributes-DotLr2MW.mjs";
+import { a as RebindState, c as BindingValidation, d as validateBinding, i as RebindOptions, l as isSingleKeyBinding, n as ALWAYS_SCOPE, o as Rebinder, r as RebindMode, s as createRebinder, t as matchCommands, u as seq } from "./index-BTgscYdI.mjs";
+//#region src/react/hooks.d.ts
+/**
+ * Mounts a commands registry for the lifecycle of the component.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useMountCommands(commands);
+ *   return <Shortcuts />;
+ * }
+ * ```
+ */
+export declare function useMountCommands<Id extends string>(registry: Commands<Id>): void;
+/** Returns all registered commands, re-rendering when the registry changes. */
+export declare function useCommands<Id extends string>(registry: Commands<Id>): ReadonlyArray<Command<Id>>;
+/** Returns a specific command snapshot by ID. */
+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"`.
+ */
+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.
+ *
+ * @example
+ * ```tsx
+ * useScope(commands, "dialog", isOpen, { exclusive: true });
+ * ```
+ */
+export declare function useScope<Id extends string>(registry: Commands<Id>, name: string, active?: boolean, options?: ScopeOptions): void;
+/** Registers a dynamic command for the lifecycle of the component. */
+export declare function useRegisterCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id> | (string & {}), definition: CommandDefinition<NoInfer<Id>>): void;
+/** State and actions for rebinding a command. */
+interface UseRebindResult<Id extends string = string> extends RebindState<Id> {
+  /** Active display string for the shortcut. */
+  display: string;
+  /** Display tokens for rendering `<kbd>` elements. */
+  tokens: ReadonlyArray<string>;
+  /** Whether the shortcut has been customized by the user. */
+  overridden: boolean;
+  start: () => void;
+  stop: () => void;
+  cancel: () => void;
+  commit: () => void;
+  clear: () => void;
+  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 { 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 ConflictKind, 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, type SerializedOverride, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, validateBinding };

package/dist/{react.js → react.mjs}

@@ -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-DWmUPZSL.js";
+import { observe } from "./attributes.mjs";
+import { a as ariaKeyShortcuts, c as spokenBinding, d as seq, f as toBindings, i as createRebinder, l as bindingSignature, n as createCommands, o as bindingTokens, p as validateBinding, r as ALWAYS_SCOPE, s as formatBinding, t as matchCommands, u as isSingleKeyBinding } from "./src-DgYjA1oS.mjs";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region src/react/hooks.ts
@@ -28,7 +28,8 @@ function useMountCommands(registry) {
 function useCommandList(registry) {
 	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
 	const getSnapshot = useCallback(() => registry.list(), [registry]);
-	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	const getServerSnapshot = useCallback(() => registry.serverList(), [registry]);
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 /** Returns all registered commands, re-rendering when the registry changes. */
 function useCommands(registry) {
@@ -37,19 +38,20 @@ function useCommands(registry) {
 /** Returns a specific command snapshot by ID. */
 function useCommand(registry, id) {
 	const commands = useCommandList(registry);
-	return useMemo(() => registry.get(id), [
-		registry,
-		commands,
-		id
-	]);
+	return useMemo(() => commands.find((command) => command.id === id), [commands, id]);
 }
-/** Returns display and accessibility shortcuts for a command. */
+/**
+* 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"`.
+*/
 function useShortcut(registry, id) {
 	const command = useCommand(registry, id);
 	return useMemo(() => ({
 		display: command?.display[0] ?? "",
 		tokens: command?.tokens[0] ?? EMPTY_TOKENS,
-		aria: command?.aria ?? ""
+		aria: command?.aria ?? "",
+		spoken: command?.spoken ?? ""
 	}), [command]);
 }
 /**
@@ -62,14 +64,19 @@ function useShortcut(registry, id) {
 */
 function useScope(registry, name, active = true, options = {}) {
 	const exclusive = options.exclusive === true;
+	const strict = options.strict === true;
 	useEffect(() => {
 		if (!active) return;
-		return registry.pushScope(name, { exclusive });
+		return registry.pushScope(name, {
+			exclusive,
+			strict
+		});
 	}, [
 		registry,
 		name,
 		active,
-		exclusive
+		exclusive,
+		strict
 	]);
 }
 /** Registers a dynamic command for the lifecycle of the component. */
@@ -95,6 +102,10 @@ function definitionSignature(definition) {
 		toBindings(definition.keys).map((binding) => bindingSignature(binding)).join("|"),
 		definition.scope ?? "",
 		definition.title,
+		definition.description ?? "",
+		definition.group ?? "",
+		(definition.keywords ?? []).join(","),
+		definition.hidden === true ? "1" : "0",
 		definition.enabled === false ? "0" : "1",
 		definition.preventDefault === false ? "0" : "1",
 		definition.ignoreInputs === void 0 ? "" : String(definition.ignoreInputs),
@@ -211,4 +222,4 @@ function usePendingSequences(registry) {
 	return useSyncExternalStore(subscribe, getSnapshot, getEmptyPending);
 }
 //#endregion
-export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, useCommand, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useRegisterCommand, useScope, useShortcut, validateBinding };
+export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, useCommand, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useRegisterCommand, useScope, useShortcut, validateBinding };