@x-tech-laboratories/x-libs 0.14.1 → 0.15.0

package/dist/web/react/shell.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from "react";
+import { type Route } from "../router.ts";
+import { type ThemeChoice } from "../theme.ts";
+export declare function use_route(): Route;
+export declare function ThemeButton({ choice }: {
+    choice: ThemeChoice;
+}): import("react").JSX.Element;
+export interface ShellSection {
+    id: string;
+    label: string;
+    href: string;
+}
+export interface SidebarWidth {
+    default_width: number;
+    min: number;
+    max: number;
+    storage_key?: string;
+    width?: number;
+    on_change?: (width: number, done: boolean) => void;
+}
+interface ShellProps {
+    brand: string;
+    brand_icon?: string;
+    sections?: ShellSection[];
+    active?: string;
+    sidebar?: ReactNode;
+    sidebar_width?: SidebarWidth;
+    theme: ThemeChoice;
+    user?: string | null;
+    logged_out?: boolean;
+    user_href?: string;
+    on_logout?: () => void;
+    brand_href?: string;
+    menu_open?: boolean;
+    on_menu_open_change?: (open: boolean) => void;
+    main_class?: string;
+    tools?: ReactNode;
+    sidebar_foot?: ReactNode;
+    status_bar?: ReactNode;
+    view_key?: string;
+    contained?: boolean;
+    brand_in_sidebar?: boolean;
+    children: ReactNode;
+}
+export declare function Shell({ brand, brand_icon, sections, active, sidebar: sidebar_content, sidebar_width, theme, user, logged_out: held_logged_out, user_href, on_logout, brand_href, tools, sidebar_foot, status_bar, view_key, menu_open: held_menu_open, on_menu_open_change, main_class, contained, brand_in_sidebar, children, }: ShellProps): import("react").JSX.Element;
+export {};

package/dist/web/react/shell.js

@@ -0,0 +1,94 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The frame around every view: the top bar, the sidebar that slides in on phones and resizes on wide screens, the theme button, a status bar, and the toasts, dialogs and menus.
+import { useEffect, useRef, useState } from "react";
+import { current_route } from "../router.js";
+import { store_sizes, stored_sizes } from "../split.js";
+import { next_theme } from "../theme.js";
+import { Dialogs } from "./dialog.js";
+import { ContextMenus } from "./menus.js";
+import { ResizeHandle } from "./split.js";
+import { Toasts } from "./toasts.js";
+// ── Route ────────────────────────────────────────────────────────────────────
+// The hash route, read again whenever it changes.
+export function use_route() {
+    const [route, set_route] = useState(current_route);
+    useEffect(() => {
+        const changed = () => set_route(current_route());
+        window.addEventListener("hashchange", changed);
+        return () => window.removeEventListener("hashchange", changed);
+    }, []);
+    return route;
+}
+// ── Theme ────────────────────────────────────────────────────────────────────
+const theme_labels = { system: ["◐", "Theme: system"], light: ["☀", "Theme: light"], dark: ["☾", "Theme: dark"] };
+// Steps through system, light and dark, its glyph and label showing the current one.
+export function ThemeButton({ choice }) {
+    const [theme, set_theme] = useState(choice.get);
+    useEffect(() => choice.on_change(set_theme), []);
+    const [icon, text] = theme_labels[theme];
+    return (_jsx("button", { id: "theme", className: "icon", title: `${text} (click to change)`, "aria-label": `${text}, click to change`, onClick: () => choice.set(next_theme(choice.get())), children: icon }));
+}
+// The sidebar's width: the app's own, else the one kept in this browser, else the default.
+function use_sidebar_width(spec) {
+    const [kept, set_kept] = useState(() => spec?.storage_key ? stored_sizes(spec.storage_key, 1)?.[0] : undefined);
+    const width = spec ? Math.min(spec.max, Math.max(spec.min, spec.width ?? kept ?? spec.default_width)) : undefined;
+    const change = (next, done) => {
+        if (spec?.width === undefined)
+            set_kept(next);
+        if (done && spec?.storage_key)
+            store_sizes(spec.storage_key, [next]);
+        spec?.on_change?.(next, done);
+    };
+    return [width, change];
+}
+export function Shell({ brand, brand_icon, sections = [], active, sidebar: sidebar_content, sidebar_width, theme, user, logged_out: held_logged_out, user_href, on_logout, brand_href = "#/", tools, sidebar_foot, status_bar, view_key, menu_open: held_menu_open, on_menu_open_change, main_class, contained = false, brand_in_sidebar = false, children, }) {
+    const [own_menu_open, set_own_menu_open] = useState(false);
+    const menu_open = held_menu_open ?? own_menu_open;
+    const main = useRef(null);
+    const menu_button = useRef(null);
+    const sidebar = useRef(null);
+    const first_view = useRef(true);
+    const logged_out = held_logged_out ?? user === null;
+    const user_name = typeof user === "string" && user !== "" ? user : undefined;
+    const [width, change_width] = use_sidebar_width(sidebar_width);
+    // Every opening and closing of the phone menu goes through here, so an app that holds it hears each one.
+    function set_menu_open(open) {
+        if (open === menu_open)
+            return;
+        if (held_menu_open === undefined)
+            set_own_menu_open(open);
+        on_menu_open_change?.(open);
+    }
+    // The login page has no theme button, so the saved theme is set here.
+    useEffect(() => theme.apply(), []);
+    useEffect(() => {
+        document.body.classList.toggle("logged-out", logged_out);
+        document.body.classList.toggle("menu-open", menu_open);
+        document.body.classList.toggle("has-status-bar", status_bar !== undefined);
+        document.body.classList.toggle("contained", contained);
+    }, [logged_out, menu_open, status_bar !== undefined, contained]);
+    useEffect(() => {
+        if (menu_open)
+            sidebar.current?.querySelector("a[href], button:not(:disabled), input, select, textarea, [tabindex='0']")?.focus();
+        if (!menu_open)
+            return;
+        const escape = (event) => {
+            if (event.key !== "Escape")
+                return;
+            set_menu_open(false);
+            menu_button.current?.focus();
+        };
+        document.addEventListener("keydown", escape);
+        return () => document.removeEventListener("keydown", escape);
+    }, [menu_open]);
+    // A new view closes the menu and takes focus, which tells a screen reader the page changed, but not on the first load.
+    useEffect(() => {
+        set_menu_open(false);
+        if (!first_view.current)
+            main.current?.focus({ preventScroll: true });
+        first_view.current = false;
+        window.scrollTo(0, 0);
+        main.current?.scrollTo?.(0, 0);
+    }, [view_key]);
+    return (_jsxs(_Fragment, { children: [_jsx("a", { className: "skip", href: "#main", children: "Skip to content" }), _jsxs("header", { className: "topbar", children: [_jsx("button", { ref: menu_button, className: "icon menu-button", "aria-label": "Open the menu", "aria-expanded": menu_open, "aria-controls": "sidebar", onClick: () => set_menu_open(!menu_open), children: "\u2630" }), !(brand_in_sidebar && !logged_out) && _jsxs("a", { href: brand_href, className: "brand", children: [brand_icon && _jsx("img", { className: "brand-icon", src: brand_icon, alt: "" }), brand] }), !logged_out && tools, !logged_out && _jsx(ThemeButton, { choice: theme }), user_name !== undefined && (user_href ? _jsx("a", { className: "account-link", href: user_href, children: user_name }) : _jsx("span", { className: "user-name", children: user_name })), user_name !== undefined && on_logout && _jsx("button", { onClick: on_logout, children: "Log out" })] }), _jsxs("div", { className: "layout", style: width === undefined ? undefined : { "--sidebar-width": `${width}px` }, children: [_jsxs("nav", { ref: sidebar, id: "sidebar", className: "sidebar", "aria-label": "Main", children: [brand_in_sidebar && _jsxs("a", { href: brand_href, className: "sidebar-brand", children: [brand_icon && _jsx("img", { className: "brand-icon", src: brand_icon, alt: "" }), brand] }), sidebar_content !== undefined && sidebar_content !== null ? _jsx("div", { className: "sidebar-content", children: sidebar_content }) : sections.map((section) => (_jsx("a", { href: section.href, "data-section": section.id, className: section.id === active ? "active" : undefined, "aria-current": section.id === active ? "page" : undefined, children: section.label }, section.id))), sidebar_foot, sidebar_width && width !== undefined && (_jsx(ResizeHandle, { side: "left", size: width, min: sidebar_width.min, max: sidebar_width.max, default_size: sidebar_width.default_width, on_resize: (next) => change_width(next, false), on_resize_end: (next) => change_width(next, true), label: "Resize the sidebar", class_name: "sidebar-resize" }))] }), _jsx("div", { className: "scrim", hidden: !menu_open, onClick: () => set_menu_open(false) }), _jsx("main", { ref: main, id: "main", className: main_class, tabIndex: -1, children: children })] }), status_bar !== undefined && _jsx("footer", { className: "status-bar", children: status_bar }), _jsx(Toasts, {}), _jsx(Dialogs, {}), _jsx(ContextMenus, {})] }));
+}

package/dist/web/react/shortcuts.d.ts

@@ -0,0 +1,23 @@
+export interface Shortcut {
+    keys: string;
+    when?: "always" | "outside_fields";
+    over_overlays?: boolean;
+    keep_default?: boolean;
+    run: (event: KeyboardEvent) => void;
+}
+interface KeyCombination {
+    key: string;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean | "any";
+}
+export declare function is_apple_platform(): boolean;
+export declare function parse_keys(keys: string, apple?: boolean): KeyCombination;
+export declare function matches_keys(keys: string, event: KeyboardEvent, apple?: boolean): boolean;
+export declare function describe_keys(keys: string, apple?: boolean): string;
+export declare function is_typing(target: EventTarget | null): boolean;
+export declare function is_overlay_open(document: Document): boolean;
+export declare function is_shortcut_allowed(shortcut: Shortcut, event: KeyboardEvent): boolean;
+export declare function use_shortcuts(shortcuts: Shortcut[]): void;
+export {};

package/dist/web/react/shortcuts.js

@@ -0,0 +1,95 @@
+// Keyboard shortcuts for a page: "mod+z" style bindings that stay quiet while text is typed or a dialog or popover is open.
+import { useEffect, useRef } from "react";
+// ── Parsing ──────────────────────────────────────────────────────────────────
+const KEY_ALIASES = {
+    esc: "escape", return: "enter", space: " ", spacebar: " ", del: "delete",
+    up: "arrowup", down: "arrowdown", left: "arrowleft", right: "arrowright",
+    plus: "+", cmd: "meta", command: "meta", control: "ctrl", option: "alt",
+};
+export function is_apple_platform() {
+    return typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+// A punctuation key such as "?" needs Shift on some layouts and not others, so Shift is ignored unless named.
+export function parse_keys(keys, apple = is_apple_platform()) {
+    const parts = keys.toLowerCase().split(/\+(?!$)/).map((part) => KEY_ALIASES[part] ?? part);
+    const key = parts.at(-1) ?? "";
+    const modifiers = new Set(parts.slice(0, -1).map((part) => part === "mod" ? (apple ? "meta" : "ctrl") : part));
+    const is_letter_or_named = /^[a-z0-9]$/.test(key) || key.length > 1;
+    return {
+        key,
+        ctrl: modifiers.has("ctrl"),
+        meta: modifiers.has("meta"),
+        alt: modifiers.has("alt"),
+        shift: modifiers.has("shift") || (is_letter_or_named ? false : "any"),
+    };
+}
+// Letters and digits also match by their physical key, so Alt+A still matches on a Mac where it types "å".
+export function matches_keys(keys, event, apple = is_apple_platform()) {
+    const combination = parse_keys(keys, apple);
+    if (event.ctrlKey !== combination.ctrl || event.metaKey !== combination.meta || event.altKey !== combination.alt)
+        return false;
+    if (combination.shift !== "any" && event.shiftKey !== combination.shift)
+        return false;
+    if (event.key.toLowerCase() === combination.key)
+        return true;
+    return /^[a-z]$/.test(combination.key) ? event.code === `Key${combination.key.toUpperCase()}` : /^[0-9]$/.test(combination.key) && event.code === `Digit${combination.key}`;
+}
+// ── Help text ────────────────────────────────────────────────────────────────
+const KEY_NAMES = {
+    " ": "Space", escape: "Esc", arrowup: "↑", arrowdown: "↓", arrowleft: "←", arrowright: "→",
+    enter: "Enter", delete: "Delete", backspace: "Backspace", tab: "Tab", home: "Home", end: "End",
+    pageup: "Page Up", pagedown: "Page Down",
+};
+// The keys as a person reads them: "Ctrl+Shift+Z" elsewhere, "⌘⇧Z" on Apple devices.
+export function describe_keys(keys, apple = is_apple_platform()) {
+    const combination = parse_keys(keys, apple);
+    const key = KEY_NAMES[combination.key] ?? (combination.key.length === 1 ? combination.key.toUpperCase() : capitalised(combination.key));
+    const shift = combination.shift === true;
+    if (apple)
+        return [combination.ctrl && "⌃", combination.alt && "⌥", shift && "⇧", combination.meta && "⌘", key].filter(Boolean).join("");
+    return [combination.ctrl && "Ctrl", combination.alt && "Alt", shift && "Shift", combination.meta && "Meta", key].filter(Boolean).join("+");
+}
+function capitalised(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+// ── Guards ───────────────────────────────────────────────────────────────────
+// Text fields, selects and editable regions keep their keys for typing.
+export function is_typing(target) {
+    if (!(target instanceof Element))
+        return false;
+    if (target instanceof HTMLElement && target.isContentEditable)
+        return true;
+    return target.closest("input, textarea, select, [contenteditable]:not([contenteditable='false'])") !== null;
+}
+// An open dialog or popover takes the keyboard, so page shortcuts wait until it closes.
+export function is_overlay_open(document) {
+    return document.querySelector("dialog[open], [popover]:popover-open") !== null;
+}
+// Whether the shortcut should fire for the event, before its keys are compared.
+export function is_shortcut_allowed(shortcut, event) {
+    if (event.isComposing)
+        return false;
+    if ((shortcut.when ?? "outside_fields") === "outside_fields" && is_typing(event.target))
+        return false;
+    return shortcut.over_overlays === true || !is_overlay_open(document);
+}
+// ── Hook ─────────────────────────────────────────────────────────────────────
+// Listens on the window while the component is shown; the first shortcut that matches runs, and the list may change on every render.
+export function use_shortcuts(shortcuts) {
+    const latest = useRef(shortcuts);
+    latest.current = shortcuts;
+    useEffect(() => {
+        function on_key(event) {
+            if (event.defaultPrevented)
+                return;
+            const shortcut = latest.current.find((each) => matches_keys(each.keys, event) && is_shortcut_allowed(each, event));
+            if (!shortcut)
+                return;
+            if (!shortcut.keep_default)
+                event.preventDefault();
+            shortcut.run(event);
+        }
+        window.addEventListener("keydown", on_key);
+        return () => window.removeEventListener("keydown", on_key);
+    }, []);
+}

package/dist/web/react/split.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type Axis, type PaneSpec } from "../split.ts";
+export type { PaneSpec } from "../split.ts";
+interface ResizeHandleProps {
+    side: "left" | "right" | "top" | "bottom";
+    size: number;
+    min: number;
+    max: number;
+    default_size: number;
+    on_resize: (size: number) => void;
+    on_resize_end: (size: number) => void;
+    label: string;
+    class_name?: string;
+}
+export declare function ResizeHandle({ side, size, min, max, default_size, on_resize, on_resize_end, label, class_name }: ResizeHandleProps): import("react").JSX.Element;
+interface SplitProps {
+    storage_key: string;
+    axis?: Axis;
+    specs: PaneSpec[];
+    preferred?: (number | undefined)[];
+    panes: ReactNode[];
+}
+export declare function Split({ storage_key, axis, specs, preferred, panes }: SplitProps): import("react").JSX.Element;

package/dist/web/react/split.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// React resize handles: one on a panel's edge, and a split whose panes share a container and remember their sizes.
+import { Fragment, useEffect, useRef, useState } from "react";
+import { distribute, fit, follow_drag, key_step, resize_at, store_sizes, stored_sizes } from "../split.js";
+// A thin bar on a panel's inner edge: drag it or press the arrow keys to resize, double-click it to reset.
+export function ResizeHandle({ side, size, min, max, default_size, on_resize, on_resize_end, label, class_name }) {
+    const axis = side === "left" || side === "right" ? "horizontal" : "vertical";
+    const direction = side === "left" || side === "top" ? 1 : -1;
+    const clamp = (value) => Math.round(Math.min(max, Math.max(min, value)));
+    function start_drag(event) {
+        const start_size = size;
+        let latest = size;
+        follow_drag(event.currentTarget, event.nativeEvent, axis, (moved) => {
+            latest = clamp(start_size + direction * moved);
+            on_resize(latest);
+        }, () => on_resize_end(latest));
+    }
+    function nudge(event) {
+        const step = key_step(event.nativeEvent, axis);
+        if (step === null)
+            return;
+        event.preventDefault();
+        on_resize_end(clamp(size + direction * step));
+    }
+    return (_jsx("div", { className: ["resize-handle", axis === "vertical" && "vertical", class_name].filter(Boolean).join(" "), role: "separator", "aria-orientation": axis === "horizontal" ? "vertical" : "horizontal", "aria-label": label, "aria-valuenow": size, "aria-valuemin": min, "aria-valuemax": max, tabIndex: 0, onPointerDown: start_drag, onDoubleClick: () => on_resize_end(default_size), onKeyDown: nudge }));
+}
+// Panes side by side or stacked, with a handle between each two; double-clicking a handle restores the first sizes.
+export function Split({ storage_key, axis = "horizontal", specs, preferred, panes }) {
+    const container = useRef(null);
+    const [sizes, set_sizes] = useState([]);
+    const latest = useRef(sizes);
+    latest.current = sizes;
+    // The length the panes share: the container's less the handles between them.
+    function extent() {
+        const element = container.current;
+        if (!element)
+            return 0;
+        const along = (child) => axis === "horizontal" ? child.offsetWidth : child.offsetHeight;
+        const handles = [...element.querySelectorAll(":scope > .resize-handle")].reduce((sum, handle) => sum + along(handle), 0);
+        return (axis === "horizontal" ? element.clientWidth : element.clientHeight) - handles;
+    }
+    function first_sizes(total) {
+        const saved = stored_sizes(storage_key, specs.length);
+        return saved ? fit(saved, total, specs) : distribute(total, specs, preferred);
+    }
+    function change(next, keep) {
+        set_sizes(next);
+        if (keep)
+            store_sizes(storage_key, next);
+    }
+    useEffect(() => {
+        const total = extent();
+        if (total > 0)
+            set_sizes(first_sizes(total));
+        // Sizing straight from the observer would resize what it watches, so the change waits for the next frame.
+        let queued = 0;
+        const observer = new ResizeObserver(() => {
+            if (queued)
+                return;
+            queued = requestAnimationFrame(() => {
+                queued = 0;
+                const length = extent();
+                if (length <= 0)
+                    return;
+                set_sizes(latest.current.length === specs.length ? fit(latest.current, length, specs) : first_sizes(length));
+            });
+        });
+        observer.observe(container.current);
+        return () => {
+            if (queued)
+                cancelAnimationFrame(queued);
+            observer.disconnect();
+        };
+    }, []);
+    function start_drag(index, event) {
+        const before = [...latest.current];
+        let moved_to = before;
+        follow_drag(event.currentTarget, event.nativeEvent, axis, (moved) => {
+            moved_to = resize_at(before, index, moved, specs);
+            change(moved_to, false);
+        }, () => store_sizes(storage_key, moved_to));
+    }
+    function nudge(index, event) {
+        const step = key_step(event.nativeEvent, axis);
+        if (step === null)
+            return;
+        event.preventDefault();
+        change(resize_at(sizes, index, step, specs), true);
+    }
+    const template = sizes.length === specs.length
+        ? sizes.flatMap((size, index) => index === 0 ? [`${size}px`] : ["auto", `${size}px`]).join(" ")
+        : specs.map(() => "1fr").join(" auto ");
+    return (_jsx("div", { ref: container, className: `split ${axis}`, style: axis === "horizontal" ? { gridTemplateColumns: template } : { gridTemplateRows: template }, children: panes.map((pane, index) => (_jsxs(Fragment, { children: [index > 0 && (_jsx("div", { className: axis === "horizontal" ? "resize-handle" : "resize-handle vertical", role: "separator", tabIndex: 0, "aria-orientation": axis === "horizontal" ? "vertical" : "horizontal", "aria-label": "Resize panes", "aria-valuenow": sizes[index - 1] ?? 0, onPointerDown: (event) => start_drag(index - 1, event), onKeyDown: (event) => nudge(index - 1, event), onDoubleClick: () => change(distribute(extent(), specs, preferred), true) })), _jsx("div", { className: "split-pane", children: pane })] }, index))) }));
+}

package/dist/web/react/states.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from "react";
+import type { Watch } from "../watch.ts";
+export declare function Skeleton({ lines }: {
+    lines?: number;
+}): import("react").JSX.Element;
+export declare function Empty({ title, hint }: {
+    title: string;
+    hint?: ReactNode;
+}): import("react").JSX.Element;
+export declare function Failure({ error, retry }: {
+    error: unknown;
+    retry: () => void;
+}): import("react").JSX.Element;
+export type ResourceStatus = "idle" | "loading" | "loaded" | "failed";
+export interface Resource<Data> {
+    data: Data | null;
+    error: unknown;
+    loading: boolean;
+    status: ResourceStatus;
+    reload: (quiet?: boolean) => Promise<void>;
+}
+export interface ResourceOptions {
+    refresh_in_milliseconds?: number;
+    enabled?: boolean;
+    watch?: Watch;
+}
+export declare function use_resource<Data>(work: () => Promise<Data>, dependencies: unknown[], options?: ResourceOptions): Resource<Data>;
+interface LoadedProps<Data> {
+    resource: Resource<Data>;
+    lines?: number;
+    idle?: ReactNode;
+    empty?: ReactNode;
+    children: (data: Data) => ReactNode;
+}
+export declare function Loaded<Data>({ resource, lines, idle, empty, children }: LoadedProps<Data>): import("react").JSX.Element;
+export {};

package/dist/web/react/states.js

@@ -0,0 +1,64 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// What a part of the page shows while it loads, when it has nothing, and when loading failed, and the hook that loads it.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { describe_error } from "../errors.js";
+import { pass_login_needed } from "../states.js";
+// ── States ───────────────────────────────────────────────────────────────────
+export function Skeleton({ lines = 3 }) {
+    return (_jsx("div", { className: "skeleton", "aria-busy": "true", "aria-label": "Loading", children: Array.from({ length: lines }, (_, index) => _jsx("div", { className: "skeleton-line", style: { width: `${90 - index * 15}%` } }, index)) }));
+}
+export function Empty({ title, hint }) {
+    return (_jsxs("div", { className: "empty", children: [_jsx("p", { className: "empty-title", children: title }), hint && _jsx("p", { className: "muted", children: hint })] }));
+}
+export function Failure({ error, retry }) {
+    return (_jsxs("div", { className: "failure", role: "alert", children: [_jsxs("p", { children: ["Could not load this: ", describe_error(error)] }), _jsx("button", { onClick: retry, children: "Retry" })] }));
+}
+// Loads what the work fetches whenever the dependencies change, passing a lapsed login on to the page.
+export function use_resource(work, dependencies, options = {}) {
+    const enabled = options.enabled ?? true;
+    const [state, set_state] = useState({ data: null, error: null, status: enabled ? "loading" : "idle" });
+    const latest_work = useRef(work);
+    latest_work.current = work;
+    const generation = useRef(0);
+    const reload = useCallback((quiet = false) => {
+        const mine = ++generation.current;
+        if (!quiet)
+            set_state({ data: null, error: null, status: "loading" });
+        return latest_work.current().then((data) => { if (mine === generation.current)
+            set_state({ data, error: null, status: "loaded" }); }, (error) => {
+            if (pass_login_needed(error) || mine !== generation.current)
+                return;
+            set_state((before) => quiet && before.data !== null ? before : { data: null, error, status: "failed" });
+        });
+    }, []);
+    useEffect(() => {
+        if (enabled)
+            return void reload();
+        // Turning off drops the load under way and what it showed.
+        generation.current += 1;
+        set_state((before) => before.status === "idle" ? before : { data: null, error: null, status: "idle" });
+    }, [enabled, ...dependencies]);
+    useEffect(() => {
+        if (!options.refresh_in_milliseconds || !enabled)
+            return;
+        const timer = setInterval(() => { if (document.visibilityState === "visible")
+            void reload(true); }, options.refresh_in_milliseconds);
+        return () => clearInterval(timer);
+    }, [options.refresh_in_milliseconds, enabled]);
+    useEffect(() => {
+        if (!options.watch || !enabled)
+            return;
+        return options.watch.subscribe(() => void reload(true));
+    }, [options.watch, enabled]);
+    return { ...state, loading: state.status === "loading", reload };
+}
+// Shows a skeleton while the resource first loads, an error with Retry if that fails, and what children build from it after, going by its status so a null result still shows.
+export function Loaded({ resource, lines, idle = null, empty, children }) {
+    if (resource.status === "loaded")
+        return _jsx(_Fragment, { children: resource.data === null && empty !== undefined ? empty : children(resource.data) });
+    if (resource.status === "idle")
+        return _jsx(_Fragment, { children: idle });
+    if (resource.status === "failed")
+        return _jsx(Failure, { error: resource.error, retry: () => void resource.reload() });
+    return _jsx(Skeleton, { lines: lines });
+}

package/dist/web/react/store.d.ts

@@ -0,0 +1,4 @@
+import type { Store } from "../store.ts";
+export type { Store, StoreOptions } from "../store.ts";
+export { create_store } from "../store.ts";
+export declare function use_store<Value>(store: Store<Value>): Value;

package/dist/web/react/store.js

@@ -0,0 +1,7 @@
+// Reads a store's value and redraws the component when it changes.
+import { use_watch } from "./watch.js";
+export { create_store } from "../store.js";
+export function use_store(store) {
+    use_watch(store.watch);
+    return store.get();
+}

package/dist/web/react/suggestions.d.ts

@@ -0,0 +1,23 @@
+import { type FocusEvent, type KeyboardEvent, type ReactNode } from "react";
+export interface FieldProps<Field extends HTMLElement> {
+    "aria-autocomplete": "list";
+    "aria-expanded": boolean;
+    "aria-controls": string;
+    "aria-activedescendant": string | undefined;
+    onKeyDown: (event: KeyboardEvent<Field>) => void;
+    onBlur: (event: FocusEvent<Field>) => void;
+}
+interface SuggestionsProps<Item, Field extends HTMLElement> {
+    value: string;
+    source: (value: string) => Item[] | Promise<Item[]>;
+    key_of: (item: Item) => string;
+    render: (item: Item) => ReactNode;
+    detail?: (item: Item) => ReactNode;
+    on_take: (item: Item) => void;
+    label: string;
+    on_key_down?: (event: KeyboardEvent<Field>) => void;
+    on_blur?: (event: FocusEvent<Field>) => void;
+    children: (field: FieldProps<Field>) => ReactNode;
+}
+export declare function Suggestions<Item, Field extends HTMLElement>({ value, source, key_of, render, detail, on_take, label, on_key_down, on_blur, children }: SuggestionsProps<Item, Field>): import("react").JSX.Element;
+export {};

package/dist/web/react/suggestions.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Completions listed under a text field as it is typed into, such as slash commands: arrow keys choose, Tab or Enter take, Escape dismisses.
+import { useEffect, useId, useRef, useState } from "react";
+export function Suggestions({ value, source, key_of, render, detail, on_take, label, on_key_down, on_blur, children }) {
+    const list_id = useId();
+    const [items, set_items] = useState([]);
+    const [index, set_index] = useState(0);
+    const latest_value = useRef(value);
+    latest_value.current = value;
+    useEffect(() => {
+        let stale = false;
+        Promise.resolve(source(value)).then((found) => {
+            if (stale || latest_value.current !== value)
+                return;
+            set_items(found);
+            set_index(0);
+        });
+        return () => { stale = true; };
+    }, [value]);
+    function take(choice) {
+        const item = items[choice];
+        if (item === undefined)
+            return;
+        set_items([]);
+        on_take(item);
+    }
+    function key_down(event) {
+        if (items.length > 0 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                set_index((index + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length);
+                return;
+            }
+            if (event.key === "Tab" || event.key === "Enter") {
+                event.preventDefault();
+                take(index);
+                return;
+            }
+            if (event.key === "Escape") {
+                event.preventDefault();
+                set_items([]);
+                return;
+            }
+        }
+        on_key_down?.(event);
+    }
+    const option_id = (position) => `${list_id}-${position}`;
+    const field = {
+        "aria-autocomplete": "list",
+        "aria-expanded": items.length > 0,
+        "aria-controls": list_id,
+        "aria-activedescendant": items.length > 0 ? option_id(index) : undefined,
+        onKeyDown: key_down,
+        onBlur: (event) => { set_items([]); on_blur?.(event); },
+    };
+    return (_jsxs("div", { className: "suggest-wrap", children: [children(field), items.length > 0 && (_jsx("ul", { id: list_id, className: "suggestions menu", role: "listbox", "aria-label": label, children: items.map((item, position) => (_jsxs("li", { id: option_id(position), role: "option", className: "menu-item", "aria-selected": position === index, onMouseDown: (event) => { event.preventDefault(); take(position); }, children: [_jsx("span", { className: "suggestion-main", children: render(item) }), detail && _jsx("span", { className: "suggestion-detail muted small", children: detail(item) })] }, key_of(item)))) }))] }));
+}