react-cheminfo 0.10.0 → 0.12.0

package/lib/hooks/ui/documentListNavigation.js

@@ -0,0 +1,41 @@
+import { isInteractiveTarget, isTextEntryTarget } from "./keyTargets.js";
+import { handleListNavigationKey } from "./listNavigation.js";
+/**
+ * Move a list's selection from a key heard on the whole document.
+ *
+ * A key already handled, a key pressed with a modifier, and a key aimed at a
+ * text field are left to the page. `ArrowUp` and `ArrowDown` move the
+ * selection as {@link handleListNavigationKey} does, and `Enter` activates the
+ * selected entry when the list asks for it.
+ * @param event - The native keyboard event.
+ * @param options - See {@link DocumentListNavigationOptions}.
+ * @returns Whether the selection moved; an activation does not move it.
+ */
+export function handleDocumentListKey(event, options) {
+    const { enabled = true, pageKeys = false, onActivate, ignoreKey } = options;
+    if (!enabled || event.defaultPrevented === true)
+        return false;
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
+        return false;
+    }
+    if (isTextEntryTarget(event.target))
+        return false;
+    if (ignoreKey?.(event) === true)
+        return false;
+    if (event.key === 'Enter') {
+        const { selectedIndex, length } = options;
+        if (onActivate === undefined || isInteractiveTarget(event.target)) {
+            return false;
+        }
+        if (selectedIndex < 0 || selectedIndex >= length)
+            return false;
+        event.preventDefault();
+        onActivate(selectedIndex);
+        return false;
+    }
+    if (!pageKeys && event.key !== 'ArrowUp' && event.key !== 'ArrowDown') {
+        return false;
+    }
+    return handleListNavigationKey(event, options);
+}
+//# sourceMappingURL=documentListNavigation.js.map

package/lib/hooks/ui/documentListNavigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentListNavigation.js","sourceRoot":"","sources":["../../../src/hooks/ui/documentListNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAKzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AA4C9D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA2B,EAC3B,OAAsC;IAEtC,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAG,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC5E,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,gBAAgB,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,SAAS,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAE9C,IAAI,KAAK,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QAC1B,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC1C,IAAI,UAAU,KAAK,SAAS,IAAI,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,aAAa,GAAG,CAAC,IAAI,aAAa,IAAI,MAAM;YAAE,OAAO,KAAK,CAAC;QAC/D,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,UAAU,CAAC,aAAa,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,WAAW,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,uBAAuB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC"}

package/lib/hooks/ui/elementTarget.d.ts

@@ -0,0 +1,14 @@
+import type { RefObject } from 'react';
+/**
+ * The element a hook works on: a ref holding it, or the element itself. Pass
+ * the element — kept in state through a callback ref — when it mounts after
+ * the component does, so the hook sees it arrive.
+ */
+export type ElementTarget = RefObject<Element | null> | Element | null;
+/**
+ * The element a target currently names.
+ * @param target - A ref or an element.
+ * @returns The element, or `null` while there is none.
+ */
+export declare function resolveElementTarget(target: ElementTarget): Element | null;
+//# sourceMappingURL=elementTarget.d.ts.map

package/lib/hooks/ui/elementTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementTarget.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/elementTarget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI,CAG1E"}

package/lib/hooks/ui/elementTarget.js

@@ -0,0 +1,11 @@
+/**
+ * The element a target currently names.
+ * @param target - A ref or an element.
+ * @returns The element, or `null` while there is none.
+ */
+export function resolveElementTarget(target) {
+    if (target === null)
+        return null;
+    return 'current' in target ? target.current : target;
+}
+//# sourceMappingURL=elementTarget.js.map

package/lib/hooks/ui/elementTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementTarget.js","sourceRoot":"","sources":["../../../src/hooks/ui/elementTarget.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AACvD,CAAC"}

package/lib/hooks/ui/index.d.ts

@@ -1,7 +1,22 @@
+export type { ActivationKeyEvent } from './activationKey.ts';
+export { isActivationKey, onActivateKey } from './activationKey.ts';
+export type { AsyncState } from './asyncState.ts';
+export type { DocumentListKeyEvent, DocumentListNavigationOptions, } from './documentListNavigation.ts';
+export type { ElementTarget } from './elementTarget.ts';
+export type { ListNavigationHandlerOptions, ListNavigationKeyEvent, ListNavigationOptions, } from './listNavigation.ts';
+export { handleListNavigationKey } from './listNavigation.ts';
+export type { PollingOptions, PollingSnapshot } from './pollingController.ts';
+export type { ActiveHeadingOptions } from './useActiveHeading.ts';
+export { useActiveHeading } from './useActiveHeading.ts';
+export { useAsync } from './useAsync.ts';
 export { useContainerSize } from './useContainerSize.ts';
 export { useDebouncedValue } from './useDebouncedValue.ts';
+export type { DocumentListNavigationHookOptions } from './useDocumentListNavigation.ts';
+export { useDocumentListNavigation } from './useDocumentListNavigation.ts';
 export type { ListKeyboardNavigationOptions } from './useListKeyboardNavigation.ts';
 export { useListKeyboardNavigation } from './useListKeyboardNavigation.ts';
+export type { PollingState, UsePollingOptions } from './usePolling.ts';
+export { usePolling } from './usePolling.ts';
 export type { ElementSize } from './useResizeObserver.ts';
 export { useResizeObserver } from './useResizeObserver.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/hooks/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EACV,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,4BAA4B,EAC5B,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/lib/hooks/ui/index.js

@@ -1,5 +1,11 @@
+export { isActivationKey, onActivateKey } from "./activationKey.js";
+export { handleListNavigationKey } from "./listNavigation.js";
+export { useActiveHeading } from "./useActiveHeading.js";
+export { useAsync } from "./useAsync.js";
 export { useContainerSize } from "./useContainerSize.js";
 export { useDebouncedValue } from "./useDebouncedValue.js";
+export { useDocumentListNavigation } from "./useDocumentListNavigation.js";
 export { useListKeyboardNavigation } from "./useListKeyboardNavigation.js";
+export { usePolling } from "./usePolling.js";
 export { useResizeObserver } from "./useResizeObserver.js";
 //# sourceMappingURL=index.js.map

package/lib/hooks/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/ui/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAYpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/lib/hooks/ui/keyTargets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a key event is aimed at somewhere the visitor types: a text field, a
+ * select, an editable region or anything carrying `role="textbox"`. A keyboard
+ * shortcut listening above it leaves such a key alone.
+ * @param target - The `target` of the keyboard event.
+ * @returns True when the key belongs to the field.
+ */
+export declare function isTextEntryTarget(target: EventTarget | null | undefined): boolean;
+/**
+ * Whether a key event is aimed at a control that answers `Enter` or the space
+ * bar by itself: a button, a link, a summary, or an element with the role of
+ * one. A handler further up leaves the activation to it.
+ * @param target - The `target` of the keyboard event.
+ * @returns True when the control acts on the key itself.
+ */
+export declare function isInteractiveTarget(target: EventTarget | null | undefined): boolean;
+//# sourceMappingURL=keyTargets.d.ts.map

package/lib/hooks/ui/keyTargets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyTargets.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/keyTargets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAWT;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAWT"}

package/lib/hooks/ui/keyTargets.js

@@ -0,0 +1,59 @@
+/**
+ * Whether a key event is aimed at somewhere the visitor types: a text field, a
+ * select, an editable region or anything carrying `role="textbox"`. A keyboard
+ * shortcut listening above it leaves such a key alone.
+ * @param target - The `target` of the keyboard event.
+ * @returns True when the key belongs to the field.
+ */
+export function isTextEntryTarget(target) {
+    const element = asElementLike(target);
+    if (element === null)
+        return false;
+    if (element.isContentEditable === true)
+        return true;
+    if (typeof element.tagName === 'string' &&
+        TEXT_ENTRY_TAGS.has(element.tagName)) {
+        return true;
+    }
+    return roleOf(element) === 'textbox';
+}
+/**
+ * Whether a key event is aimed at a control that answers `Enter` or the space
+ * bar by itself: a button, a link, a summary, or an element with the role of
+ * one. A handler further up leaves the activation to it.
+ * @param target - The `target` of the keyboard event.
+ * @returns True when the control acts on the key itself.
+ */
+export function isInteractiveTarget(target) {
+    const element = asElementLike(target);
+    if (element === null)
+        return false;
+    if (typeof element.tagName === 'string' &&
+        INTERACTIVE_TAGS.has(element.tagName)) {
+        return true;
+    }
+    const role = roleOf(element);
+    return role !== null && INTERACTIVE_ROLES.has(role);
+}
+const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+const INTERACTIVE_TAGS = new Set(['BUTTON', 'A', 'SUMMARY']);
+const INTERACTIVE_ROLES = new Set([
+    'button',
+    'checkbox',
+    'link',
+    'menuitem',
+    'switch',
+    'tab',
+]);
+function asElementLike(target) {
+    if (typeof target !== 'object' || target === null)
+        return null;
+    return target;
+}
+function roleOf(element) {
+    if (typeof element.getAttribute !== 'function')
+        return null;
+    const role = element.getAttribute('role');
+    return typeof role === 'string' ? role : null;
+}
+//# sourceMappingURL=keyTargets.js.map

package/lib/hooks/ui/keyTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyTargets.js","sourceRoot":"","sources":["../../../src/hooks/ui/keyTargets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAsC;IAEtC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,OAAO,CAAC,iBAAiB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpD,IACE,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACnC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,EACpC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAsC;IAEtC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IACE,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACnC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,EACrC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AACjE,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;AAC7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,QAAQ;IACR,UAAU;IACV,MAAM;IACN,UAAU;IACV,QAAQ;IACR,KAAK;CACN,CAAC,CAAC;AAQH,SAAS,aAAa,CACpB,MAAsC;IAEtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,MAAqB,CAAC;AAC/B,CAAC;AAED,SAAS,MAAM,CAAC,OAAoB;IAClC,IAAI,OAAO,OAAO,CAAC,YAAY,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/lib/hooks/ui/listNavigation.d.ts

@@ -1,5 +1,3 @@
-/** The default number of entries `PageUp` and `PageDown` move by. */
-export declare const DEFAULT_PAGE_STEP = 10;
 /** How a list stands when a key reaches it. */
 export interface ListNavigationOptions {
     /** Number of entries currently displayed. */
@@ -49,6 +47,7 @@ export declare function nextSelectedIndex(key: string, options: ListNavigationOp
  * move, so the page never scrolls out from under the last entry.
  * @param event - The keyboard event, synthetic or native.
  * @param options - See {@link ListNavigationHandlerOptions}.
+ * @returns Whether the selection moved, i.e. whether `onSelect` was called.
  */
-export declare function handleListNavigationKey(event: ListNavigationKeyEvent, options: ListNavigationHandlerOptions): void;
+export declare function handleListNavigationKey(event: ListNavigationKeyEvent, options: ListNavigationHandlerOptions): boolean;
 //# sourceMappingURL=listNavigation.d.ts.map

package/lib/hooks/ui/listNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listNavigation.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/listNavigation.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA6B,SAAQ,qBAAqB;IACzE,4DAA4D;IAC5D,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,GAC7B,MAAM,GAAG,IAAI,CAmCf;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,IAAI,CAMN"}
+{"version":3,"file":"listNavigation.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/listNavigation.ts"],"names":[],"mappings":"AAKA,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA6B,SAAQ,qBAAqB;IACzE,4DAA4D;IAC5D,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,GAC7B,MAAM,GAAG,IAAI,CAmCf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAQT"}

package/lib/hooks/ui/listNavigation.js

@@ -1,5 +1,6 @@
+import { isTextEntryTarget } from "./keyTargets.js";
 /** The default number of entries `PageUp` and `PageDown` move by. */
-export const DEFAULT_PAGE_STEP = 10;
+const DEFAULT_PAGE_STEP = 10;
 /**
  * The entry a navigation key selects.
  *
@@ -54,24 +55,18 @@ export function nextSelectedIndex(key, options) {
  * move, so the page never scrolls out from under the last entry.
  * @param event - The keyboard event, synthetic or native.
  * @param options - See {@link ListNavigationHandlerOptions}.
+ * @returns Whether the selection moved, i.e. whether `onSelect` was called.
  */
 export function handleListNavigationKey(event, options) {
     if (isTextEntryTarget(event.target))
-        return;
+        return false;
     const next = nextSelectedIndex(event.key, options);
     if (next === null)
-        return;
+        return false;
     event.preventDefault();
-    if (next !== options.selectedIndex)
-        options.onSelect(next);
-}
-const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
-function isTextEntryTarget(target) {
-    if (target === null || target === undefined)
+    if (next === options.selectedIndex)
         return false;
-    const element = target;
-    if (element.isContentEditable === true)
-        return true;
-    return (typeof element.tagName === 'string' && TEXT_ENTRY_TAGS.has(element.tagName));
+    options.onSelect(next);
+    return true;
 }
 //# sourceMappingURL=listNavigation.js.map

package/lib/hooks/ui/listNavigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"listNavigation.js","sourceRoot":"","sources":["../../../src/hooks/ui/listNavigation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"listNavigation.js","sourceRoot":"","sources":["../../../src/hooks/ui/listNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,qEAAqE;AACrE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAgC7B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,OAA8B;IAE9B,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,IAAI,GACR,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;QACxE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACtB,CAAC,CAAC,iBAAiB,CAAC;IACxB,MAAM,OAAO,GACX,aAAa,IAAI,CAAC,IAAI,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpE,IAAI,MAAc,CAAC;IACnB,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,WAAW;YACd,MAAM,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;YAC1C,MAAM;QACR,KAAK,SAAS;YACZ,MAAM,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;YACnD,MAAM;QACR,KAAK,UAAU;YACb,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;YACrC,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;YACxD,MAAM;QACR,KAAK,MAAM;YACT,MAAM,GAAG,CAAC,CAAC;YACX,MAAM;QACR,KAAK,KAAK;YACR,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC;YACpB,MAAM;QACR;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA6B,EAC7B,OAAqC;IAErC,IAAI,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,KAAK,CAAC,cAAc,EAAE,CAAC;IACvB,IAAI,IAAI,KAAK,OAAO,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/hooks/ui/pollingController.d.ts

@@ -0,0 +1,63 @@
+/** How a backend is asked again and again until it is done. */
+export interface PollingOptions<TValue> {
+    /**
+     * Milliseconds between the end of one poll and the start of the next, or a
+     * function of the latest answer — short while a job runs, long while idle.
+     */
+    interval: number | ((value: TValue) => number);
+    /**
+     * Milliseconds before a failed poll is tried again.
+     * @default the interval when it is a number, otherwise 10 000
+     */
+    retryInterval?: number;
+    /**
+     * Whether an answer is final, which stops the polling.
+     * @default undefined — the polling never stops by itself
+     */
+    isDone?: (value: TValue) => boolean;
+    /**
+     * Whether nothing is asked while the tab is hidden. The next poll then runs
+     * as soon as the tab is shown again.
+     * @default true
+     */
+    pauseWhenHidden?: boolean;
+}
+/** What the polling has learned so far. */
+export interface PollingSnapshot<TValue> {
+    /** The latest answer, kept through a failed poll. */
+    value: TValue | undefined;
+    /** Why the latest poll failed, or `undefined` when it answered. */
+    error: Error | undefined;
+    /** Whether an answer was final and the polling stopped. */
+    done: boolean;
+}
+/** The snapshot before anything was asked. */
+export declare const POLLING_IDLE: PollingSnapshot<never>;
+/** What one run of the polling is started from. */
+export interface PollingRun<TValue> {
+    /** Asks the backend once. */
+    fetcher: () => Promise<TValue>;
+    /** Whether the polling runs at all. */
+    enabled: boolean;
+}
+/**
+ * Whether the polling now describes another run than before, so what the
+ * previous run learned — the answer of another job, a `done` that no longer
+ * holds — must be forgotten rather than shown until the first new answer.
+ * @param previous - The run the snapshot on screen came from.
+ * @param next - The run asked for now.
+ * @returns True when the fetcher changed or the polling was switched.
+ */
+export declare function isNewPollingRun<TValue>(previous: PollingRun<TValue>, next: PollingRun<TValue>): boolean;
+/**
+ * Poll `fetcher` until an answer is final, one request at a time.
+ *
+ * The next poll is scheduled once the previous one settled, so requests never
+ * stack and a slow backend is not asked faster than it answers.
+ * @param fetcher - Asks the backend once.
+ * @param options - See {@link PollingOptions}.
+ * @param onUpdate - Receives every new snapshot.
+ * @returns Stops the polling; an answer still in flight is then ignored.
+ */
+export declare function startPolling<TValue>(fetcher: () => Promise<TValue>, options: PollingOptions<TValue>, onUpdate: (snapshot: PollingSnapshot<TValue>) => void): () => void;
+//# sourceMappingURL=pollingController.d.ts.map

package/lib/hooks/ui/pollingController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollingController.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/pollingController.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC/C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe,CAAC,MAAM;IACrC,qDAAqD;IACrD,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mEAAmE;IACnE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,2DAA2D;IAC3D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,8CAA8C;AAC9C,eAAO,MAAM,YAAY,EAAE,eAAe,CAAC,KAAK,CAI/C,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,UAAU,CAAC,MAAM;IAChC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EACpC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,GACvB,OAAO,CAET;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EACjC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC9B,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,IAAI,GACpD,MAAM,IAAI,CAuDZ"}

package/lib/hooks/ui/pollingController.js

@@ -0,0 +1,86 @@
+import { toError } from "../../error/core/toError.js";
+/** The snapshot before anything was asked. */
+export const POLLING_IDLE = {
+    value: undefined,
+    error: undefined,
+    done: false,
+};
+/**
+ * Whether the polling now describes another run than before, so what the
+ * previous run learned — the answer of another job, a `done` that no longer
+ * holds — must be forgotten rather than shown until the first new answer.
+ * @param previous - The run the snapshot on screen came from.
+ * @param next - The run asked for now.
+ * @returns True when the fetcher changed or the polling was switched.
+ */
+export function isNewPollingRun(previous, next) {
+    return previous.fetcher !== next.fetcher || previous.enabled !== next.enabled;
+}
+const DEFAULT_RETRY_INTERVAL = 10_000;
+/**
+ * Poll `fetcher` until an answer is final, one request at a time.
+ *
+ * The next poll is scheduled once the previous one settled, so requests never
+ * stack and a slow backend is not asked faster than it answers.
+ * @param fetcher - Asks the backend once.
+ * @param options - See {@link PollingOptions}.
+ * @param onUpdate - Receives every new snapshot.
+ * @returns Stops the polling; an answer still in flight is then ignored.
+ */
+export function startPolling(fetcher, options, onUpdate) {
+    const { interval, isDone, pauseWhenHidden = true } = options;
+    const retryInterval = options.retryInterval ??
+        (typeof interval === 'number' ? interval : DEFAULT_RETRY_INTERVAL);
+    const document = pauseWhenHidden
+        ? globalThis.document
+        : undefined;
+    let stopped = false;
+    let waitingForVisible = false;
+    let timer;
+    let snapshot = POLLING_IDLE;
+    function publish(next) {
+        snapshot = next;
+        onUpdate(next);
+    }
+    async function poll() {
+        timer = undefined;
+        if (stopped)
+            return;
+        if (document?.visibilityState === 'hidden') {
+            waitingForVisible = true;
+            return;
+        }
+        try {
+            const value = await fetcher();
+            if (stopped)
+                return;
+            const done = isDone?.(value) ?? false;
+            publish({ value, error: undefined, done });
+            if (done)
+                return;
+            const delay = typeof interval === 'number' ? interval : interval(value);
+            timer = setTimeout(() => void poll(), delay);
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            publish({ ...snapshot, error: toError(error) });
+            timer = setTimeout(() => void poll(), retryInterval);
+        }
+    }
+    function onVisibilityChange() {
+        if (!waitingForVisible || document?.visibilityState === 'hidden')
+            return;
+        waitingForVisible = false;
+        void poll();
+    }
+    document?.addEventListener('visibilitychange', onVisibilityChange);
+    void poll();
+    return () => {
+        stopped = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        document?.removeEventListener('visibilitychange', onVisibilityChange);
+    };
+}
+//# sourceMappingURL=pollingController.js.map

package/lib/hooks/ui/pollingController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollingController.js","sourceRoot":"","sources":["../../../src/hooks/ui/pollingController.ts"],"names":[],"mappings":"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"}

package/lib/hooks/ui/useActiveHeading.d.ts

@@ -0,0 +1,29 @@
+import type { ElementTarget } from './elementTarget.ts';
+/** How the headings of an article are found and read. */
+export interface ActiveHeadingOptions {
+    /**
+     * Selects the headings inside the container; each needs an `id`.
+     * @default 'h2[id], h3[id], h4[id]'
+     */
+    selector?: string;
+    /**
+     * Distance from the top of the viewport, in CSS pixels, a heading must pass
+     * to count as the one being read — usually the height of a sticky header.
+     * @default 96
+     */
+    readingLine?: number;
+}
+/**
+ * The id of the heading the reader is under, for the table of contents beside
+ * a long article.
+ *
+ * Measured once the container is there, then again on any scroll — of the page
+ * or of a panel holding the article — and on resize, at most once a frame. The
+ * headings are looked up at every measure, so content inserted later is found.
+ * @param container - Ref holding the article, or the article itself. Pass the
+ * element when it mounts later than the component.
+ * @param options - See {@link ActiveHeadingOptions}.
+ * @returns The heading's id, or `null` while there is no heading.
+ */
+export declare function useActiveHeading(container: ElementTarget, options?: ActiveHeadingOptions): string | null;
+//# sourceMappingURL=useActiveHeading.d.ts.map

package/lib/hooks/ui/useActiveHeading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActiveHeading.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/useActiveHeading.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,oBAAyB,GACjC,MAAM,GAAG,IAAI,CAkCf"}

package/lib/hooks/ui/useActiveHeading.js

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react';
+import { activeHeadingIndex } from "./activeHeading.js";
+import { resolveElementTarget } from "./elementTarget.js";
+/**
+ * The id of the heading the reader is under, for the table of contents beside
+ * a long article.
+ *
+ * Measured once the container is there, then again on any scroll — of the page
+ * or of a panel holding the article — and on resize, at most once a frame. The
+ * headings are looked up at every measure, so content inserted later is found.
+ * @param container - Ref holding the article, or the article itself. Pass the
+ * element when it mounts later than the component.
+ * @param options - See {@link ActiveHeadingOptions}.
+ * @returns The heading's id, or `null` while there is no heading.
+ */
+export function useActiveHeading(container, options = {}) {
+    const { selector = HEADING_SELECTOR, readingLine = 96 } = options;
+    const [activeId, setActiveId] = useState(null);
+    useEffect(() => {
+        const document = globalThis.document;
+        if (document === undefined)
+            return;
+        let frame = 0;
+        function measure() {
+            frame = 0;
+            const element = resolveElementTarget(container);
+            if (element === null)
+                return;
+            const headings = element.querySelectorAll(selector);
+            const index = activeHeadingIndex(headings, readingLine);
+            setActiveId(index === -1 ? null : headings[index].id);
+        }
+        function schedule() {
+            frame ||= requestAnimationFrame(measure);
+        }
+        schedule();
+        const listening = { capture: true, passive: true };
+        document.addEventListener('scroll', schedule, listening);
+        globalThis.addEventListener('resize', schedule, { passive: true });
+        return () => {
+            document.removeEventListener('scroll', schedule, listening);
+            globalThis.removeEventListener('resize', schedule);
+            if (frame !== 0)
+                cancelAnimationFrame(frame);
+        };
+    }, [container, selector, readingLine]);
+    return activeId;
+}
+const HEADING_SELECTOR = 'h2[id], h3[id], h4[id]';
+//# sourceMappingURL=useActiveHeading.js.map

package/lib/hooks/ui/useActiveHeading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActiveHeading.js","sourceRoot":"","sources":["../../../src/hooks/ui/useActiveHeading.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAiB1D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAwB,EACxB,UAAgC,EAAE;IAElC,MAAM,EAAE,QAAQ,GAAG,gBAAgB,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAE9D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAgC,CAAC;QAC7D,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO;QACnC,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,SAAS,OAAO;YACd,KAAK,GAAG,CAAC,CAAC;YACV,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;YAChD,IAAI,OAAO,KAAK,IAAI;gBAAE,OAAO;YAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YACpD,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YACxD,WAAW,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,QAAQ,CAAC,KAAK,CAAa,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;QAED,SAAS,QAAQ;YACf,KAAK,KAAK,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;QAED,QAAQ,EAAE,CAAC;QACX,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnD,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QACzD,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;YAC5D,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACnD,IAAI,KAAK,KAAK,CAAC;gBAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC/C,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IAEvC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,gBAAgB,GAAG,wBAAwB,CAAC"}

package/lib/hooks/ui/useAsync.d.ts

@@ -0,0 +1,19 @@
+import type { AsyncState } from './asyncState.ts';
+/**
+ * Run an async task and follow where it stands, as a discriminated union.
+ *
+ * The task runs on mount and again whenever it or `refreshKey` changes. A
+ * re-run does not flip the state back to `loading`: what is on screen stays
+ * until the new answer arrives, and a refresh that fails keeps it rather than
+ * replacing it with an error. An answer that arrives after the component
+ * unmounted, or after a newer run started, is ignored.
+ *
+ * The task is a dependency, so pass a stable function — declared at module
+ * scope, or wrapped in `useCallback` over the values it reads.
+ * @param task - The async function to run.
+ * @param refreshKey - Changing it runs the task again; only its identity
+ * matters. Defaults to `undefined`.
+ * @returns Where the latest run stands.
+ */
+export declare function useAsync<TData>(task: () => Promise<TData>, refreshKey?: unknown): AsyncState<TData>;
+//# sourceMappingURL=useAsync.d.ts.map

package/lib/hooks/ui/useAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsync.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/useAsync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EAC1B,UAAU,CAAC,EAAE,OAAO,GACnB,UAAU,CAAC,KAAK,CAAC,CAmBnB"}

package/lib/hooks/ui/useAsync.js

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react';
+import { ASYNC_LOADING, asyncFailed, asyncSucceeded } from "./asyncState.js";
+/**
+ * Run an async task and follow where it stands, as a discriminated union.
+ *
+ * The task runs on mount and again whenever it or `refreshKey` changes. A
+ * re-run does not flip the state back to `loading`: what is on screen stays
+ * until the new answer arrives, and a refresh that fails keeps it rather than
+ * replacing it with an error. An answer that arrives after the component
+ * unmounted, or after a newer run started, is ignored.
+ *
+ * The task is a dependency, so pass a stable function — declared at module
+ * scope, or wrapped in `useCallback` over the values it reads.
+ * @param task - The async function to run.
+ * @param refreshKey - Changing it runs the task again; only its identity
+ * matters. Defaults to `undefined`.
+ * @returns Where the latest run stands.
+ */
+export function useAsync(task, refreshKey) {
+    const [state, setState] = useState(ASYNC_LOADING);
+    useEffect(() => {
+        let cancelled = false;
+        task().then((data) => {
+            if (!cancelled)
+                setState(asyncSucceeded(data));
+        }, (error) => {
+            if (!cancelled)
+                setState((previous) => asyncFailed(previous, error));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [task, refreshKey]);
+    return state;
+}
+//# sourceMappingURL=useAsync.js.map

package/lib/hooks/ui/useAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsync.js","sourceRoot":"","sources":["../../../src/hooks/ui/useAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG5C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CACtB,IAA0B,EAC1B,UAAoB;IAEpB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAoB,aAAa,CAAC,CAAC;IAErE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;YACP,IAAI,CAAC,SAAS;gBAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,CAAC,SAAS;gBAAE,QAAQ,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QACvE,CAAC,CACF,CAAC;QACF,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAEvB,OAAO,KAAK,CAAC;AACf,CAAC"}