@inklu/keys 2.1.0 → 2.2.0

package/dist/react.mjs

@@ -1,53 +1,39 @@
 "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 importKeymap, c as bindingTokens, d as isSingleKeyBinding, f as seq, i as exportKeymap, l as formatBinding, m as keyName, n as createCommands, o as webStorage, p as isModifierKey, r as createRebinder, s as ariaKeyShortcuts, t as matchCommands, u as spokenBinding } from "./src-TaZw4V61.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: {}
-};
+const NONE = [];
 /** 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;
+let held = 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]))
-	};
+	held = down.size === 0 ? NONE : [...new Set(down.values())];
 	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
-	});
+	down.set(identify(event), keyName(event.key));
 	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);
+		for (const [identity, key] of down) if (!isModifierKey(key)) down.delete(identity);
 	}
 	publish();
 }
-/** Leaving the window swallows the keyups, so nothing is held any more. */
-function onBlur() {
+/** Leaving the window or hiding the page swallows the keyups, so nothing is held any more. */
+function onLeave() {
 	if (down.size === 0) return;
 	down.clear();
 	publish();
 }
-/** The keys held right now. Empty unless something is subscribed. */
+/** The keys held right now, by name. 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));
+	return held;
 }
 /** Watches held keys until the returned function is called. */
 function subscribeHeldKeys(listener) {
@@ -55,27 +41,26 @@ function subscribeHeldKeys(listener) {
 	if (listeners.size === 1) {
 		document.addEventListener("keydown", onKeyDown, true);
 		document.addEventListener("keyup", onKeyUp, true);
-		window.addEventListener("blur", onBlur);
+		document.addEventListener("visibilitychange", onLeave);
+		window.addEventListener("blur", onLeave);
 	}
 	return () => {
 		listeners.delete(listener);
 		if (listeners.size > 0) return;
 		document.removeEventListener("keydown", onKeyDown, true);
 		document.removeEventListener("keyup", onKeyUp, true);
-		window.removeEventListener("blur", onBlur);
+		document.removeEventListener("visibilitychange", onLeave);
+		window.removeEventListener("blur", onLeave);
 		down.clear();
-		state = NONE;
+		held = 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,20 +75,23 @@ 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
@@ -121,9 +109,8 @@ function useShortcut(registry, id) {
 }
 /**
 * 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 +130,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
@@ -221,38 +206,15 @@ function useRebind(registry, id, options = {}) {
 		id
 	]);
 }
-/** Returns an array of keys currently held down. */
+/** Returns the keys held down right now, by the name `KeyboardEvent.key` gives each. */
 function useHeldKeys() {
-	return useSyncExternalStore(subscribeHeldKeys, () => heldKeys().keys, getEmptyTokens);
+	return useSyncExternalStore(subscribeHeldKeys, heldKeys, 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);
-* ```
-*/
+/** Returns the half-typed sequences, for a hint such as "G …". */
 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, matchCommands, seq, spokenBinding, useCommand, useCommandHandler, useCommands, useHeldKeys, useMountCommands, usePendingSequences, useRebind, useScope, useShortcut, webStorage };