@x-tech-laboratories/x-libs 0.4.0 → 0.6.0

package/README.md

@@ -6,7 +6,10 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 
 | Import                                   | What it holds                                                                 |
 | ---------------------------------------- | ----------------------------------------------------------------------------- |
-| `durations`                              | `parse_duration` for settings such as `"2h30m"`, `format_duration`, `format_age`. |
+| `durations`                              | `parse_duration` for settings such as `"2h30m"`, `format_duration` in months down to seconds, `format_age`. |
+| `dates`                                  | Local dates as `"2026-06-10"` or `"2026-06-10T09:30"`: reading, writing, adding days and months, overdue, and Yesterday/Today/Tomorrow labels. |
+| `electron/bridge`                        | `define_bridge`: one method table for the preload, the main process, and a web page's calls to its server. |
+| `electron/window`                        | `create_window`: links open in the browser, the background follows the system theme, and the size and place are remembered. |
 | `agent/commands`                         | `run_command` and `stream_command`: one shell command, in its own process group. |
 | `agent/long_runs`                        | `LongRuns`: commands that outlive the agent, their output and exit code kept on disk. |
 | `agent/keys`                             | Reads and makes OpenSSH ed25519 agent keys; signs and checks the login challenge. |
@@ -17,13 +20,16 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `server/agents/connection`, `agent`, `local`, `route` | One connected agent, the `Agent` interface, `LocalAgent`, and the Fastify route. |
 | `server/passwords`                       | scrypt hashes and the `name:hash` accounts file.                              |
 | `server/hash_password`                   | The `hash-password` command.                                                  |
-| `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder, formatters, hash router and theme choice. |
-| `web/states`, `web/tables`, `web/menus`, `web/split` | `LoginNeeded`; table sorting; menu items and on-screen placement; pane sizing. |
-| `web/preact/shell`                       | `Shell`: top bar, sidebar, theme button, toasts and dialogs; `use_route`.       |
-| `web/preact/layout`, `badges`, `states`  | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows; badges and chips; `use_resource` and its loading states. |
-| `web/preact/time`                        | `Age`: a time as how long ago, with the full stamp on hover. |
-| `web/preact/controls`, `table`           | Segmented choices, button groups, switches, search boxes, selects; sortable tables that turn into cards on phones, and a pager. |
-| `web/preact/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo; modal, confirm and text dialogs openable from anywhere; context menus and popovers; resize handles and splits. |
+| `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder, formatters, hash router and theme choice, kept in this browser or the app's settings. |
+| `web/states`, `web/tables`, `web/menus`, `web/split` | `LoginNeeded`; sorting by several columns, trees and column order; menu items, placement and keys; pane sizing. |
+| `web/tree`                               | Rows with `parent_id` and `position`: nesting, subtrees, and where a dropped or keyed row lands. |
+| `web/react/shell`                        | `Shell`: top bar, section links or the app's own sidebar, resizable, theme button, toasts, dialogs and menus; `use_route`. |
+| `web/react/layout`, `badges`, `states`   | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows; badges and chips; `use_resource` and its loading states. |
+| `web/react/time`                         | `Age`: a time as how long ago, with the full stamp on hover. |
+| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes, selects; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, and cards on phones; a pager. |
+| `web/react/shortcuts`                    | `use_shortcuts` for keys such as `"mod+z"`, quiet while typing or while a dialog or popover is open; `describe_keys` for help text. |
+| `web/react/tree`                         | `Tree`: nested rows that fold, walk with the arrow keys, and reorder by dragging or with Alt and the arrow keys. |
+| `web/react/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo that say how they closed; modal, confirm and text dialogs openable from anywhere; context menus and popovers worked by keyboard, openable from anywhere; resize handles and splits. |
 
 ```ts
 import { AgentHub } from "@x-tech-laboratories/x-libs/server/agents/hub";
@@ -38,13 +44,57 @@ which an app imports once:
 ```ts
 import "@x-tech-laboratories/halon/halon-tokens.css";
 import "@x-tech-laboratories/halon/halon.css";
-import { DataTable } from "@x-tech-laboratories/x-libs/web/preact/table";
-import { toast } from "@x-tech-laboratories/x-libs/web/preact/toasts";
+import { DataTable } from "@x-tech-laboratories/x-libs/web/react/table";
+import { toast } from "@x-tech-laboratories/x-libs/web/react/toasts";
 ```
 
-The widgets are Preact components, so a page renders with Preact; `Shell` holds the toasts and dialogs that `toast` and
-`confirm_dialog` open from anywhere. A request whose session has lapsed throws `LoginNeeded` from `web/states`, and
-`use_resource` passes it on as an unhandled rejection, which the page's login listens for.
+The widgets are React components, so a page renders with React through `createRoot` from `react-dom/client`; `Shell`
+holds the toasts, dialogs and menus that `toast`, `confirm_dialog` and `open_context_menu` open from anywhere. `DataTable`
+is drawn on `@tanstack/react-table` with Halon's markup; its sorting, column order, widths, hidden columns and open rows
+are props with change callbacks, so the app keeps them in its own settings, and a column's filter is the app's own
+content in a popover X-Libs opens from the column's funnel. A request whose session has lapsed
+throws `LoginNeeded` from `web/states`, and `use_resource` passes it on as an unhandled rejection, which the page's
+login listens for.
+
+## Shortcuts and trees
+
+```tsx
+import { use_shortcuts } from "@x-tech-laboratories/x-libs/web/react/shortcuts";
+import { Tree } from "@x-tech-laboratories/x-libs/web/react/tree";
+
+use_shortcuts([
+  { keys: "mod+z", run: undo },
+  { keys: "escape", run: clear_picks },
+]);
+
+<Tree items={tags} label="Tags" render_item={(tag) => tag.name} collapsed={collapsed} on_collapsed_change={set_collapsed}
+  on_move={(tag, { parent_id, position }) => move_tag(tag.id, parent_id, position)} />
+```
+
+A shortcut stays quiet in text fields unless it has `when: "always"`, and while a dialog or popover is open unless it
+has `over_overlays: true`. The tree builds Halon's `.tree` markup; a row dropped onto its top or bottom quarter lands
+beside it, and onto its middle inside it.
+
+## Electron apps
+
+The bridge and window helpers describe the few parts of Electron they use, so the app passes Electron's own objects in
+and X-Libs does not depend on Electron.
+
+```ts
+// shared
+export const notes_bridge = define_bridge<NotesApi>("x_notes", ["list_notes", "add_note"]);
+// preload
+notes_bridge.expose(contextBridge, ipcRenderer);
+// main
+notes_bridge.handle(ipcMain, { list_notes, add_note });
+create_window(BrowserWindow, {
+  title: "X-Notes", file: join(__dirname, "../renderer/index.html"), dev_url: process.env.ELECTRON_RENDERER_URL,
+  preload: join(__dirname, "../preload/index.mjs"), default_size: { width: 1100, height: 700 },
+  state_file: join(app.getPath("userData"), "window.json"), native_theme: nativeTheme, shell,
+});
+// web page
+window.x_notes = notes_bridge.web_rpc((method, args) => post_json(`api/${method}`, args));
+```
 
 ## The app and its tasks
 

package/dist/dates.d.ts

@@ -0,0 +1,9 @@
+export declare function has_time(local_date: string): boolean;
+export declare function parse_local(local_date: string): Date;
+export declare function format_local(date: Date, with_time: boolean): string;
+export declare function start_of_day(date: Date): Date;
+export declare function days_between(first: Date, second: Date): number;
+export declare function add_days(date: Date, days: number): Date;
+export declare function add_months(date: Date, months: number): Date;
+export declare function is_overdue(local_date: string, now?: Date): boolean;
+export declare function relative_day_label(local_date: string, now?: Date, locale?: string): string;

package/dist/dates.js

@@ -0,0 +1,60 @@
+// Local calendar dates written as "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM", read and written in the device's own time zone.
+const DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+// ── Text and dates ───────────────────────────────────────────────────────────
+export function has_time(local_date) {
+    return local_date.includes("T");
+}
+// A date without a time stands for midnight at the start of its day.
+export function parse_local(local_date) {
+    const [day = "", time = "00:00"] = local_date.split("T");
+    const [year = 0, month = 1, day_of_month = 1] = day.split("-").map(Number);
+    const [hours = 0, minutes = 0] = time.split(":").map(Number);
+    return new Date(year, month - 1, day_of_month, hours, minutes);
+}
+export function format_local(date, with_time) {
+    const pad = (number) => String(number).padStart(2, "0");
+    const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    return with_time ? `${day}T${pad(date.getHours())}:${pad(date.getMinutes())}` : day;
+}
+// ── Arithmetic ───────────────────────────────────────────────────────────────
+export function start_of_day(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+// Whole calendar days from the first date to the second, so a clock change in between still counts as one day.
+export function days_between(first, second) {
+    return Math.round((start_of_day(second).getTime() - start_of_day(first).getTime()) / DAY_IN_MILLISECONDS);
+}
+export function add_days(date, days) {
+    const moved = new Date(date);
+    moved.setDate(moved.getDate() + days);
+    return moved;
+}
+// A day past the end of the target month falls back to its last day, so Jan 31 plus a month is Feb 28.
+export function add_months(date, months) {
+    const last_day = new Date(date.getFullYear(), date.getMonth() + months + 1, 0).getDate();
+    return new Date(date.getFullYear(), date.getMonth() + months, Math.min(date.getDate(), last_day), date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+}
+// ── Labels ───────────────────────────────────────────────────────────────────
+// A date without a time is overdue only once its day has passed.
+export function is_overdue(local_date, now = new Date()) {
+    const date = parse_local(local_date);
+    return has_time(local_date) ? date < now : date < start_of_day(now);
+}
+// Yesterday, Today or Tomorrow in the reader's language, else a short date with the year only when it is not this year, then the time if there is one.
+export function relative_day_label(local_date, now = new Date(), locale) {
+    const date = parse_local(local_date);
+    const day_offset = days_between(now, date);
+    const day_label = Math.abs(day_offset) <= 1
+        ? capitalised(new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(day_offset, "day"), locale)
+        : date.toLocaleDateString(locale, {
+            month: "short",
+            day: "numeric",
+            year: date.getFullYear() === now.getFullYear() ? undefined : "numeric",
+        });
+    if (!has_time(local_date))
+        return day_label;
+    return `${day_label} ${date.toLocaleTimeString(locale, { hour: "numeric", minute: "2-digit" })}`;
+}
+function capitalised(text, locale) {
+    return text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
+}

package/dist/durations.d.ts

@@ -1,3 +1,10 @@
+declare const unit_names: readonly [readonly ["months", 2592000], readonly ["weeks", 604800], readonly ["days", 86400], readonly ["hours", 3600], readonly ["minutes", 60], readonly ["seconds", 1]];
+export type DurationUnit = (typeof unit_names)[number][0];
+export interface DurationWording {
+    separator?: string;
+    largest_unit?: DurationUnit;
+}
 export declare function parse_duration(value: unknown, key: string): number;
-export declare function format_duration(seconds: number): string;
+export declare function format_duration(seconds: number, wording?: DurationWording): string;
 export declare function format_age(seconds: number): string;
+export {};

package/dist/durations.js

@@ -1,6 +1,7 @@
 // Reads durations such as "2h30m" from settings and writes them back in words, for the server and the agent alike.
 import parse from "parse-duration";
-const unit_names = [["weeks", 604800], ["days", 86400], ["hours", 3600], ["minutes", 60], ["seconds", 1]];
+// A month counts as 30 days.
+const unit_names = [["months", 2592000], ["weeks", 604800], ["days", 86400], ["hours", 3600], ["minutes", 60], ["seconds", 1]];
 const words = new Intl.DurationFormat("en", { style: "long" });
 // A duration in whole seconds; `key` names the setting in the error.
 export function parse_duration(value, key) {
@@ -14,13 +15,14 @@ export function parse_duration(value, key) {
     }
     return Math.floor(seconds);
 }
-// The two largest whole units, such as "1 day, 2 hours".
-export function format_duration(seconds) {
+// The two largest whole units, such as "1 day, 2 hours" or, with a space between, "1 week 2 days".
+export function format_duration(seconds, wording = {}) {
     if (seconds < 1)
         return "0 seconds";
+    const first_unit = unit_names.findIndex(([name]) => name === (wording.largest_unit ?? "months"));
     const parts = {};
     let remaining = Math.floor(seconds);
-    for (const [name, size] of unit_names) {
+    for (const [name, size] of unit_names.slice(first_unit)) {
         if (Object.keys(parts).length === 2)
             break;
         if (remaining < size)
@@ -28,7 +30,9 @@ export function format_duration(seconds) {
         parts[name] = Math.floor(remaining / size);
         remaining %= size;
     }
-    return words.format(parts);
+    if (wording.separator === undefined)
+        return words.format(parts);
+    return Object.entries(parts).map(([name, count]) => words.format({ [name]: count })).join(wording.separator);
 }
 export function format_age(seconds) {
     return seconds < 0 ? "never" : `${format_duration(seconds)} ago`;

package/dist/electron/bridge.d.ts

@@ -0,0 +1,30 @@
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;
+    removeHandler(channel: string): void;
+}
+export interface IpcRendererLike {
+    invoke(channel: string, ...args: unknown[]): Promise<unknown>;
+}
+export interface ContextBridgeLike {
+    exposeInMainWorld(api_key: string, api: unknown): void;
+}
+type AnyMethod = (...args: never[]) => unknown;
+export type Client<Methods extends Record<keyof Methods, AnyMethod>> = {
+    [Name in keyof Methods]: (...args: Parameters<Methods[Name]>) => Promise<Awaited<ReturnType<Methods[Name]>>>;
+};
+export type Implementation<Methods extends Record<keyof Methods, AnyMethod>> = {
+    [Name in keyof Methods]: (...args: Parameters<Methods[Name]>) => ReturnType<Methods[Name]> | Promise<Awaited<ReturnType<Methods[Name]>>>;
+};
+export type CallRemote = (method: string, args: unknown[]) => Promise<unknown>;
+export interface Bridge<Methods extends Record<keyof Methods, AnyMethod>> {
+    api_name: string;
+    method_names: readonly (keyof Methods & string)[];
+    channel: (method: keyof Methods & string) => string;
+    expose: (context_bridge: ContextBridgeLike, ipc_renderer: IpcRendererLike) => void;
+    ipc_client: (ipc_renderer: IpcRendererLike) => Client<Methods>;
+    handle: (ipc_main: IpcMainLike, implementation: Implementation<Methods>) => () => void;
+    web_rpc: (call_remote: CallRemote) => Client<Methods>;
+    dispatch: (implementation: Implementation<Methods>, method: string, args: unknown[]) => Promise<unknown>;
+}
+export declare function define_bridge<Methods extends Record<keyof Methods, AnyMethod>>(api_name: string, method_names: readonly (keyof Methods & string)[]): Bridge<Methods>;
+export {};

package/dist/electron/bridge.js

@@ -0,0 +1,32 @@
+// One table of method names serves the Electron preload, the main process and a web page's calls to its server alike.
+export function define_bridge(api_name, method_names) {
+    const channel = (method) => `${api_name}:${method}`;
+    const is_method = (method) => method_names.includes(method);
+    function client_through(call) {
+        return Object.fromEntries(method_names.map((method) => [method, (...args) => call(method, args)]));
+    }
+    async function dispatch(implementation, method, args) {
+        if (!is_method(method))
+            throw new Error(`${api_name} has no method ${method}`);
+        const answer = implementation[method];
+        return answer.apply(implementation, args);
+    }
+    return {
+        api_name,
+        method_names,
+        channel,
+        dispatch,
+        ipc_client: (ipc_renderer) => client_through((method, args) => ipc_renderer.invoke(channel(method), ...args)),
+        expose: (context_bridge, ipc_renderer) => {
+            context_bridge.exposeInMainWorld(api_name, client_through((method, args) => ipc_renderer.invoke(channel(method), ...args)));
+        },
+        handle: (ipc_main, implementation) => {
+            for (const method of method_names) {
+                ipc_main.handle(channel(method), (_event, ...args) => dispatch(implementation, method, args));
+            }
+            return () => { for (const method of method_names)
+                ipc_main.removeHandler(channel(method)); };
+        },
+        web_rpc: client_through,
+    };
+}

package/dist/electron/window.d.ts

@@ -0,0 +1,85 @@
+export interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BrowserWindowOptionsLike {
+    title: string;
+    icon?: string;
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+    minWidth?: number;
+    minHeight?: number;
+    show: boolean;
+    backgroundColor: string;
+    webPreferences: {
+        preload?: string;
+        sandbox: boolean;
+        contextIsolation: boolean;
+        nodeIntegration: boolean;
+    };
+}
+export interface BrowserWindowLike {
+    webContents: {
+        setWindowOpenHandler(handler: (details: {
+            url: string;
+        }) => {
+            action: "deny";
+        }): void;
+    };
+    on(event: string, listener: () => void): unknown;
+    once(event: string, listener: () => void): unknown;
+    show(): void;
+    maximize(): void;
+    isMaximized(): boolean;
+    getNormalBounds(): Rectangle;
+    setBackgroundColor(color: string): void;
+    loadURL(url: string): Promise<void>;
+    loadFile(path: string): Promise<void>;
+}
+export interface NativeThemeLike {
+    shouldUseDarkColors: boolean;
+    on(event: "updated", listener: () => void): unknown;
+    removeListener(event: "updated", listener: () => void): unknown;
+}
+export interface ShellLike {
+    openExternal(url: string): Promise<void>;
+}
+export interface ScreenLike {
+    getAllDisplays(): {
+        workArea: Rectangle;
+    }[];
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface WindowOptions {
+    title: string;
+    icon?: string;
+    preload?: string;
+    dev_url?: string;
+    file: string;
+    default_size: Size;
+    min_size?: Size;
+    state_file?: string;
+    native_theme: NativeThemeLike;
+    shell: ShellLike;
+    screen?: ScreenLike;
+    background?: {
+        light: string;
+        dark: string;
+    };
+    sandbox?: boolean;
+    save_delay_ms?: number;
+}
+export interface WindowState {
+    bounds: Rectangle;
+    is_maximized: boolean;
+}
+export declare function read_window_state(state_file: string): WindowState | null;
+export declare function write_window_state(state_file: string, state: WindowState): void;
+export declare function create_window<Window extends BrowserWindowLike>(BrowserWindow: new (options: BrowserWindowOptionsLike) => Window, options: WindowOptions): Window;

package/dist/electron/window.js

@@ -0,0 +1,85 @@
+// An Electron app's main window: links open in the browser, the background follows the system theme, and its size and place are remembered.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const DEFAULT_BACKGROUND = { light: "#f5f6f8", dark: "#0f1115" };
+const DEFAULT_SAVE_DELAY_MS = 500;
+// ── State file ───────────────────────────────────────────────────────────────
+// A missing, unreadable or malformed file reads as no saved state.
+export function read_window_state(state_file) {
+    try {
+        const state = JSON.parse(readFileSync(state_file, "utf8"));
+        const bounds = state.bounds;
+        const is_whole = (value) => Number.isInteger(value);
+        if (!bounds || ![bounds.x, bounds.y, bounds.width, bounds.height].every(is_whole) || bounds.width <= 0 || bounds.height <= 0)
+            return null;
+        return { bounds, is_maximized: state.is_maximized === true };
+    }
+    catch {
+        return null;
+    }
+}
+// Writes beside the file and renames over it, so a crash mid-write never leaves half a file.
+export function write_window_state(state_file, state) {
+    mkdirSync(dirname(state_file), { recursive: true });
+    const temporary_file = `${state_file}.tmp`;
+    writeFileSync(temporary_file, JSON.stringify(state));
+    renameSync(temporary_file, state_file);
+}
+function overlaps(first, second) {
+    return first.x < second.x + second.width && second.x < first.x + first.width && first.y < second.y + second.height && second.y < first.y + first.height;
+}
+// ── Window ───────────────────────────────────────────────────────────────────
+export function create_window(BrowserWindow, options) {
+    const background = options.background ?? DEFAULT_BACKGROUND;
+    const background_color = () => options.native_theme.shouldUseDarkColors ? background.dark : background.light;
+    const saved = options.state_file ? read_window_state(options.state_file) : null;
+    const on_a_screen = saved && (!options.screen || options.screen.getAllDisplays().some((display) => overlaps(saved.bounds, display.workArea)));
+    const size = saved?.bounds ?? options.default_size;
+    const window = new BrowserWindow({
+        title: options.title,
+        icon: options.icon,
+        ...(on_a_screen ? { x: saved.bounds.x, y: saved.bounds.y } : {}),
+        width: size.width,
+        height: size.height,
+        minWidth: options.min_size?.width,
+        minHeight: options.min_size?.height,
+        show: false,
+        backgroundColor: background_color(),
+        webPreferences: { preload: options.preload, sandbox: options.sandbox ?? false, contextIsolation: true, nodeIntegration: false },
+    });
+    window.once("ready-to-show", () => {
+        if (saved?.is_maximized)
+            window.maximize();
+        window.show();
+    });
+    window.webContents.setWindowOpenHandler(({ url }) => {
+        void options.shell.openExternal(url);
+        return { action: "deny" };
+    });
+    const follow_theme = () => window.setBackgroundColor(background_color());
+    options.native_theme.on("updated", follow_theme);
+    window.on("closed", () => options.native_theme.removeListener("updated", follow_theme));
+    if (options.state_file)
+        remember_state(window, options.state_file, options.save_delay_ms ?? DEFAULT_SAVE_DELAY_MS);
+    if (options.dev_url)
+        void window.loadURL(options.dev_url);
+    else
+        void window.loadFile(options.file);
+    return window;
+}
+// Saves a moment after the last move or resize, and at once when the window closes.
+function remember_state(window, state_file, save_delay_ms) {
+    let timer;
+    const save_now = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        write_window_state(state_file, { bounds: window.getNormalBounds(), is_maximized: window.isMaximized() });
+    };
+    const save_soon = () => {
+        clearTimeout(timer);
+        timer = setTimeout(save_now, save_delay_ms);
+    };
+    for (const event of ["resize", "move", "maximize", "unmaximize"])
+        window.on(event, save_soon);
+    window.on("close", save_now);
+}

package/dist/web/menus.d.ts

@@ -6,8 +6,12 @@ export interface MenuItem {
     danger?: boolean;
     separator_before?: boolean;
     checked?: boolean;
+    radio?: boolean;
+    keep_open?: boolean;
 }
 export declare function on_screen_position(x: number, y: number, width: number, height: number, room_width?: number, room_height?: number): {
     left: number;
     top: number;
 };
+export declare function item_after_key(key: string, current: number, count: number): number | null;
+export declare function item_starting_with(labels: readonly string[], typed: string, current: number): number | null;

package/dist/web/menus.js

@@ -1,4 +1,4 @@
-// What a menu item holds, and where a menu opened at a point goes so it stays on screen.
+// What a menu item holds, where a menu opened at a point goes so it stays on screen, and which item a key moves to.
 const edge_gap = 4;
 // Flipped to the point's other side near an edge, or pushed back from the edge when neither side has room.
 export function on_screen_position(x, y, width, height, room_width = window.innerWidth, room_height = window.innerHeight) {
@@ -11,3 +11,30 @@ export function on_screen_position(x, y, width, height, room_width = window.inne
     };
     return { left: place(x, width, room_width), top: place(y, height, room_height) };
 }
+// ── Keys ─────────────────────────────────────────────────────────────────────
+// The item an arrow, Home or End key moves to from the current one, wrapping round, or null for any other key.
+export function item_after_key(key, current, count) {
+    if (count === 0)
+        return null;
+    switch (key) {
+        case "ArrowDown": return current < 0 ? 0 : (current + 1) % count;
+        case "ArrowUp": return current < 0 ? count - 1 : (current - 1 + count) % count;
+        case "Home": return 0;
+        case "End": return count - 1;
+        default: return null;
+    }
+}
+// The first item after the current one whose label starts with the typed text, or null when none does.
+export function item_starting_with(labels, typed, current) {
+    const wanted = typed.toLocaleLowerCase();
+    // A repeated first letter steps on through the items that start with it.
+    const repeated = wanted.length > 1 && [...wanted].every((letter) => letter === wanted[0]);
+    const prefix = repeated ? wanted[0] : wanted;
+    const start = repeated || wanted.length === 1 ? current + 1 : Math.max(current, 0);
+    for (let offset = 0; offset < labels.length; offset += 1) {
+        const index = (start + offset) % labels.length;
+        if (labels[index].trim().toLocaleLowerCase().startsWith(prefix))
+            return index;
+    }
+    return null;
+}

package/dist/web/{preact → react}/badges.d.ts

@@ -1,26 +1,26 @@
-import type { ComponentChildren } from "preact";
+import type { ReactNode } from "react";
 export type Tone = "good" | "warn" | "bad" | "info" | "none";
 export declare function Badge({ tone, title, children }: {
     tone?: Tone;
     title?: string;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function StateBadge<State extends string>({ labels, state, title }: {
     labels: Record<State, [text: string, tone: Tone]>;
     state: State;
     title?: string;
-}): import("preact").JSX.Element;
+}): import("react").JSX.Element;
 export declare function Chip({ title, on_click, class_name, children }: {
     title?: string;
     on_click?: () => void;
     class_name?: string;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function Chips({ inline, children }: {
     inline?: boolean;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function Verdict({ ok, label }: {
     ok: boolean | null | undefined;
     label: string;
-}): import("preact").JSX.Element;
+}): import("react").JSX.Element;

package/dist/web/{preact → react}/badges.js

@@ -1,7 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // ── Badges ───────────────────────────────────────────────────────────────────
 export function Badge({ tone = "none", title, children }) {
-    return _jsx("span", { class: `badge tone-${tone}`, title: title, children: children });
+    return _jsx("span", { className: `badge tone-${tone}`, title: title, children: children });
 }
 // A badge for one of a fixed set of states, each named by its text and tone.
 export function StateBadge({ labels, state, title }) {
@@ -13,16 +13,16 @@ export function StateBadge({ labels, state, title }) {
 export function Chip({ title, on_click, class_name, children }) {
     const chip_class = class_name ? `chip ${class_name}` : "chip";
     return on_click
-        ? _jsx("button", { type: "button", class: chip_class, title: title, onClick: on_click, children: children })
-        : _jsx("span", { class: chip_class, title: title, children: children });
+        ? _jsx("button", { type: "button", className: chip_class, title: title, onClick: on_click, children: children })
+        : _jsx("span", { className: chip_class, title: title, children: children });
 }
 // A row of chips or badges, with less space between them when they sit inside a line of text.
 export function Chips({ inline = false, children }) {
-    return _jsx("span", { class: inline ? "chips inline-chips" : "chips", children: children });
+    return _jsx("span", { className: inline ? "chips inline-chips" : "chips", children: children });
 }
 // ── Verdicts ─────────────────────────────────────────────────────────────────
 // A pass, fail or not-yet verdict, such as "checks: pass".
 export function Verdict({ ok, label }) {
     const known = ok !== null && ok !== undefined;
-    return _jsxs("span", { class: `verdict tone-${known ? (ok ? "good" : "bad") : "none"}`, children: [label, ": ", known ? (ok ? "pass" : "fail") : "no verdict"] });
+    return _jsxs("span", { className: `verdict tone-${known ? (ok ? "good" : "bad") : "none"}`, children: [label, ": ", known ? (ok ? "pass" : "fail") : "no verdict"] });
 }

package/dist/web/{preact → react}/controls.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentChildren } from "preact";
+import { type ReactNode } from "react";
 interface SegmentedProps<Value extends string> {
     label: string;
     choices: {
@@ -9,29 +9,29 @@ interface SegmentedProps<Value extends string> {
     on_change: (value: Value) => void;
     class_name?: string;
 }
-export declare function Segmented<Value extends string>({ label, choices, value, on_change, class_name }: SegmentedProps<Value>): import("preact").JSX.Element;
+export declare function Segmented<Value extends string>({ label, choices, value, on_change, class_name }: SegmentedProps<Value>): import("react").JSX.Element;
 export declare function ButtonGroup({ label, children }: {
     label: string;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 interface SwitchProps {
     label: string;
     checked: boolean;
     on_change: (on: boolean) => Promise<boolean | void> | boolean | void;
     disabled?: boolean;
 }
-export declare function Switch({ label, checked, on_change, disabled }: SwitchProps): import("preact").JSX.Element;
+export declare function Switch({ label, checked, on_change, disabled }: SwitchProps): import("react").JSX.Element;
 interface SearchBoxProps {
     label: string;
     value: string;
     on_input: (value: string) => void;
 }
-export declare function SearchBox({ label, value, on_input }: SearchBoxProps): import("preact").JSX.Element;
+export declare function SearchBox({ label, value, on_input }: SearchBoxProps): import("react").JSX.Element;
 interface SelectProps<Value extends string> {
     label: string;
     options: [value: Value, text: string][];
     value: Value;
     on_change: (value: Value) => void;
 }
-export declare function Select<Value extends string>({ label, options, value, on_change }: SelectProps<Value>): import("preact").JSX.Element;
+export declare function Select<Value extends string>({ label, options, value, on_change }: SelectProps<Value>): import("react").JSX.Element;
 export {};