@inklu/keys 1.0.0

package/dist/index-WDNLK0dX.d.ts

@@ -0,0 +1,93 @@
+import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-lCPeoWII.js";
+import { Hotkey } from "@tanstack/hotkeys";
+//#region src/bindings.d.ts
+/**
+ * Creates a sequence binding from ordered hotkey steps.
+ *
+ * @example
+ * ```ts
+ * keys: seq("G", "I")
+ * ```
+ */
+declare function seq(...steps: Array<Hotkey>): SequenceBinding;
+/** Validation result for a hotkey binding. */
+interface BindingValidation {
+  readonly valid: boolean;
+  readonly errors: ReadonlyArray<string>;
+  readonly warnings: ReadonlyArray<string>;
+}
+/** Validates a binding's syntax without logging warnings or errors. */
+declare function validateBinding(binding: Binding): BindingValidation;
+//#endregion
+//#region src/rebind.d.ts
+/** Hotkey capture mode: single `"chord"` or multi-step `"sequence"`. */
+type RebindMode = "chord" | "sequence";
+/** Current state of a rebinding session. */
+interface RebindState<Id extends string = string> {
+  /** Whether keys are actively being recorded. */
+  readonly recording: boolean;
+  /** Most recently captured binding. */
+  readonly binding: Binding | null;
+  /** Captured steps in the current sequence session. */
+  readonly steps: ReadonlyArray<Chord>;
+  /** Conflicting commands for the captured binding. */
+  readonly conflicts: ReadonlyArray<Conflict<Id>>;
+}
+/** Options for creating a rebinder. */
+interface RebindOptions<Id extends string = string> {
+  /** Capture mode. Defaults to `"chord"`. */
+  mode?: RebindMode;
+  /** Whether to apply the recorded binding to the keymap. Defaults to `true`. */
+  apply?: boolean;
+  /** Whether to append rather than replace existing bindings. Defaults to `false`. */
+  add?: boolean;
+  /** Prevent applying bindings that conflict with other commands. Defaults to `false`. */
+  rejectConflicts?: boolean;
+  /** Ignore key events from inputs while recording. Defaults to `true`. */
+  ignoreInputs?: boolean;
+  /** Inactivity timeout in milliseconds before a sequence commits. */
+  idleTimeout?: number;
+  /** Callback fired when a binding is recorded. */
+  onRecord?: (binding: Binding, conflicts: ReadonlyArray<Conflict<Id>>) => void;
+  /** Callback fired when recording is cancelled. */
+  onCancel?: () => void;
+  /** Callback fired when bindings are cleared. */
+  onClear?: () => void;
+}
+/** Controller instance for managing a rebinding session. */
+interface Rebinder<Id extends string = string> {
+  /** Begins capturing keys. */
+  start: () => void;
+  /** Stops capturing keys without recording. */
+  stop: () => void;
+  /** Stops capturing keys and reports cancellation. */
+  cancel: () => void;
+  /** Commits the currently captured sequence steps. */
+  commit: () => void;
+  /** Current rebinder state. */
+  readonly state: RebindState<Id>;
+  /** Subscribes to rebinder state changes. Returns an unsubscribe function. */
+  subscribe: (listener: () => void) => () => void;
+  /** Destroys the rebinder and cleans up listeners. */
+  destroy: () => void;
+}
+/**
+ * Creates a rebinder instance for capturing and remapping a command's keys.
+ *
+ * @example
+ * ```ts
+ * const rebinder = createRebinder(commands, "palette.open", {
+ *   onRecord: (binding, conflicts) => {
+ *     if (conflicts.length) console.warn("Conflict with", conflicts[0].id);
+ *   },
+ * });
+ * rebinder.start();
+ * ```
+ */
+declare function createRebinder<Id extends string>(registry: Commands<Id>, id: Id, options?: RebindOptions<Id>): Rebinder<Id>;
+//#endregion
+//#region src/scopes.d.ts
+/** Wildcard scope identifier for commands that remain active across exclusive scopes. */
+declare const ALWAYS_SCOPE = "*";
+//#endregion
+export { Rebinder as a, seq as c, RebindState as i, validateBinding as l, RebindMode as n, createRebinder as o, RebindOptions as r, BindingValidation as s, ALWAYS_SCOPE as t };

package/dist/index.d.ts

@@ -0,0 +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-lCPeoWII.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-WDNLK0dX.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

@@ -0,0 +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-B305icXC.js";
+export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/react.d.ts

@@ -0,0 +1,77 @@
+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-lCPeoWII.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-WDNLK0dX.js";
+//#region src/react/hooks.d.ts
+/**
+ * Mounts a commands registry for the lifecycle of the component.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useMountCommands(commands);
+ *   return <Shortcuts />;
+ * }
+ * ```
+ */
+declare function useMountCommands<Id extends string>(registry: Commands<Id>): void;
+/** Returns all registered commands, re-rendering when the registry changes. */
+declare function useCommands<Id extends string>(registry: Commands<Id>): ReadonlyArray<Command<Id>>;
+/** Returns a specific command snapshot by ID. */
+declare function useCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>): Command<Id> | undefined;
+/** Returns display and accessibility shortcuts for a command. */
+declare function useShortcut<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>): {
+  display: string;
+  tokens: ReadonlyArray<string>;
+  aria: string;
+};
+/**
+ * Activates a scope for the lifecycle of the component.
+ *
+ * @example
+ * ```tsx
+ * useScope(commands, "dialog", isOpen, { exclusive: true });
+ * ```
+ */
+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. */
+declare function useRegisterCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id> | (string & {}), definition: CommandDefinition): 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. */
+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. */
+declare function useHeldKeys(): ReadonlyArray<string>;
+/**
+ * Checks whether a specific key is currently held down.
+ *
+ * @example
+ * ```tsx
+ * const shift = useKeyHold("Shift");
+ * ```
+ */
+declare function useKeyHold(key: string): boolean;
+/** Returns a map of held key identifiers to physical event codes. */
+declare function useHeldKeyCodes(): Readonly<Record<string, string>>;
+/**
+ * Returns currently active partially-typed sequences.
+ *
+ * @example
+ * ```tsx
+ * const pending = usePendingSequences(commands);
+ * ```
+ */
+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 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 UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, useCommand, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useRegisterCommand, useScope, useShortcut, validateBinding };

package/dist/react.js

@@ -0,0 +1,214 @@
+"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-B305icXC.js";
+import { getKeyStateTracker } from "@tanstack/hotkeys";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+//#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.
+*
+* @example
+* ```tsx
+* function App() {
+*   useMountCommands(commands);
+*   return <Shortcuts />;
+* }
+* ```
+*/
+function useMountCommands(registry) {
+	useEffect(() => registry.mount(), [registry]);
+}
+function useCommandList(registry) {
+	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
+	const getSnapshot = useCallback(() => registry.list(), [registry]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** Returns all registered commands, re-rendering when the registry changes. */
+function useCommands(registry) {
+	return useCommandList(registry);
+}
+/** Returns a specific command snapshot by ID. */
+function useCommand(registry, id) {
+	const commands = useCommandList(registry);
+	return useMemo(() => registry.get(id), [
+		registry,
+		commands,
+		id
+	]);
+}
+/** Returns display and accessibility shortcuts for a command. */
+function useShortcut(registry, id) {
+	const command = useCommand(registry, id);
+	return useMemo(() => ({
+		display: command?.display[0] ?? "",
+		tokens: command?.tokens[0] ?? EMPTY_TOKENS,
+		aria: command?.aria ?? ""
+	}), [command]);
+}
+/**
+* Activates a scope for the lifecycle of the component.
+*
+* @example
+* ```tsx
+* useScope(commands, "dialog", isOpen, { exclusive: true });
+* ```
+*/
+function useScope(registry, name, active = true, options = {}) {
+	const exclusive = options.exclusive === true;
+	useEffect(() => {
+		if (!active) return;
+		return registry.pushScope(name, { exclusive });
+	}, [
+		registry,
+		name,
+		active,
+		exclusive
+	]);
+}
+/** Registers a dynamic command for the lifecycle of the component. */
+function useRegisterCommand(registry, id, definition) {
+	const latest = useRef(definition);
+	latest.current = definition;
+	const signature = useMemo(() => definitionSignature(definition), [definition]);
+	useEffect(() => {
+		const handle = registry.add(id, {
+			...latest.current,
+			run: (context) => latest.current.run(context),
+			when: () => latest.current.when?.() !== false
+		});
+		return () => handle.dispose();
+	}, [
+		registry,
+		id,
+		signature
+	]);
+}
+function definitionSignature(definition) {
+	return [
+		toBindings(definition.keys).map((binding) => bindingSignature(binding)).join("|"),
+		definition.scope ?? "",
+		definition.title,
+		definition.enabled === false ? "0" : "1",
+		definition.preventDefault === false ? "0" : "1",
+		definition.ignoreInputs === void 0 ? "" : String(definition.ignoreInputs),
+		definition.requireReset === true ? "1" : "0",
+		definition.sequenceTimeout === void 0 ? "" : String(definition.sequenceTimeout)
+	].join(" ");
+}
+const IDLE_REBIND = {
+	recording: false,
+	binding: null,
+	steps: [],
+	conflicts: []
+};
+/** Hook for recording and configuring a command's keybindings. */
+function useRebind(registry, id, options = {}) {
+	const latest = useRef(options);
+	latest.current = options;
+	const command = useCommand(registry, id);
+	const [rebinder, setRebinder] = useState(null);
+	const [state, setState] = useState(IDLE_REBIND);
+	const mode = options.mode ?? "chord";
+	const idleTimeout = options.idleTimeout;
+	useEffect(() => {
+		const instance = createRebinder(registry, id, {
+			mode,
+			idleTimeout,
+			get apply() {
+				return latest.current.apply;
+			},
+			get add() {
+				return latest.current.add;
+			},
+			get rejectConflicts() {
+				return latest.current.rejectConflicts;
+			},
+			get ignoreInputs() {
+				return latest.current.ignoreInputs;
+			},
+			onRecord: (binding, conflicts) => latest.current.onRecord?.(binding, conflicts),
+			onCancel: () => latest.current.onCancel?.(),
+			onClear: () => latest.current.onClear?.()
+		});
+		const unsubscribe = instance.subscribe(() => setState(instance.state));
+		setRebinder(instance);
+		return () => {
+			unsubscribe();
+			instance.destroy();
+			setRebinder(null);
+			setState(IDLE_REBIND);
+		};
+	}, [
+		registry,
+		id,
+		mode,
+		idleTimeout
+	]);
+	return useMemo(() => ({
+		...state,
+		display: command?.display[0] ?? "",
+		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),
+		reset: () => registry.keymap.reset(id)
+	}), [
+		state,
+		command,
+		rebinder,
+		registry,
+		id
+	]);
+}
+function useKeyState() {
+	return useCallback((onChange) => {
+		const subscription = getKeyStateTracker().store.subscribe(onChange);
+		return () => subscription.unsubscribe();
+	}, []);
+}
+/** Returns an array of keys currently held down. */
+function useHeldKeys() {
+	return useSyncExternalStore(useKeyState(), () => getKeyStateTracker().store.state.heldKeys, getEmptyTokens);
+}
+/**
+* Checks whether a specific key is currently held down.
+*
+* @example
+* ```tsx
+* const shift = useKeyHold("Shift");
+* ```
+*/
+function useKeyHold(key) {
+	const subscribe = useKeyState();
+	const getSnapshot = useCallback(() => getKeyStateTracker().isKeyHeld(key), [key]);
+	return useSyncExternalStore(subscribe, getSnapshot, getFalse);
+}
+/** Returns a map of held key identifiers to physical event codes. */
+function useHeldKeyCodes() {
+	return useSyncExternalStore(useKeyState(), () => getKeyStateTracker().store.state.heldCodes, 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 { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, useCommand, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useRegisterCommand, useScope, useShortcut, validateBinding };