nexus-shared 3.2.0 → 4.0.0

package/dist/Components/Viewers/RecordCards.d.ts

@@ -0,0 +1,16 @@
+import type { RecordCardsProps } from "../../Interfaces/RecordInterfaces.ts";
+/**
+ * A record's page of cards, declared by params: the `sources` it reads, a `hero`, and its `cards` (fields, items, or its
+ * own). See `RecordCardsProps` and the interfaces it names.
+ *
+ * @example
+ * <RecordCards
+ *   sources={{ profile: ACCOUNT_API.profile, emails: ACCOUNT_API.emails }}
+ *   hero={{ title: p => p.fullName, lines: p => [`@${p.username}`] }}
+ *   cards={[
+ *     { id: "personal", title: "Personal details", fields: [FULL_NAME, DATE_OF_BIRTH], edit: { submit: { url: ACCOUNT_API.saveProfile } } },
+ *     { id: "emails", source: "emails", title: "Emails", items: "items", itemKey: "id", item: e => ({ title: e.address }), add: { ... } },
+ *   ]}
+ * />
+ */
+export declare function RecordCards(props: RecordCardsProps): import("react").JSX.Element;

package/dist/Components/Viewers/RecordCards.js

@@ -0,0 +1,509 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconPencil, iconPlus, iconRefresh, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { getPermissions, permissionsVersion, subscribePermissions } from "../../Helpers/Permissions.js";
+import { recordActionName, recordActionState, recordBusyKeys, recordCardKind, recordCount, recordField, recordFieldHeld, recordHeldLines, recordFieldInputs, recordFieldWide, recordItemKey, recordItems, recordLimit, recordLimitReason, RecordSources, recordSessionEnded, recordValueView, recordWrite, } from "../../Helpers/RecordCards.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { Button } from "../Documents/Button.js";
+import { ProfilePicture } from "../Forms/CrudWorkspace.js";
+import { openRecordFlow, runRecordConfirm } from "../Forms/RecordFlows.js";
+import { useReadOnlyNotice } from "../Inputs/ReadOnlyNotice.js";
+import { toast } from "../Layouts/Toaster.js";
+import { MarkdownView } from "./MarkdownView.js";
+import { RichTextView } from "./RichTextView.js";
+/*
+ * A record's page of cards: a hero across the top, then cards of fields, cards of items and the page's own cards, each
+ * drawn from one of the sources the page reads. Nothing on the page saves: a card's Edit, a list's Add and an item's
+ * icon actions open popups (RecordFlows.tsx), and their answers are written into the source at once, so every card on
+ * it shows the change. Loading draws the cards as they will be, held; a source that fails says so in each of its cards,
+ * with Try again; read-only draws no buttons; an ended session leaves the page's own words and its way back in.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const shown = (node) => node !== undefined && node !== null && node !== false && node !== "";
+/** Reads a source: its own function, else a GET of its endpoint or URL, without the client's toasts. */
+const readSource = (read, signal) => (typeof read === "function" ? read(signal) : browserApi.get(read, { signal, toast: false }));
+/** One placeholder line while a source loads: the table's bone. */
+/** How long after the page opens a link to a card is still followed again once the cards have their records. */
+const FOLLOW_WITHIN_MS = 5000;
+/** Tells one mounted page from another: a popup belongs to the page that opened it, never to the next one drawn. */
+let pages = 0;
+const Bone = ({ width = "60%" }) => _jsx("span", { className: "nx-table__bone nx-record__bone", style: { width }, "aria-hidden": "true" });
+/**
+ * A record's page of cards, declared by params: the `sources` it reads, a `hero`, and its `cards` (fields, items, or its
+ * own). See `RecordCardsProps` and the interfaces it names.
+ *
+ * @example
+ * <RecordCards
+ *   sources={{ profile: ACCOUNT_API.profile, emails: ACCOUNT_API.emails }}
+ *   hero={{ title: p => p.fullName, lines: p => [`@${p.username}`] }}
+ *   cards={[
+ *     { id: "personal", title: "Personal details", fields: [FULL_NAME, DATE_OF_BIRTH], edit: { submit: { url: ACCOUNT_API.saveProfile } } },
+ *     { id: "emails", source: "emails", title: "Emails", items: "items", itemKey: "id", item: e => ({ title: e.address }), add: { ... } },
+ *   ]}
+ * />
+ */
+export function RecordCards(props) {
+    const { hero, cards, readOnly = false, headingLevel = 2, className } = props;
+    const latest = useRef(props);
+    latest.current = props;
+    const popups = useRef(new Set());
+    const endRef = useRef(() => false);
+    const [store] = useState(() => new RecordSources(props.sources, async (read, signal) => {
+        const answer = await readSource(read, signal);
+        if (!answer.ok)
+            endRef.current(answer);
+        return answer;
+    }));
+    const states = useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
+    useSyncExternalStore(subscribePermissions, permissionsVersion, permissionsVersion);
+    const permissions = getPermissions();
+    const can = permissions.ready ? permissions.can.bind(permissions) : () => false;
+    const preferences = useDatePreferences();
+    const [busy, setBusy] = useState({});
+    // Each mounted page keys its popups apart: a page drawn afresh (another visit, a new `key`) never brings back a popup
+    // bound to the page before it, whose data is gone.
+    const [page] = useState(() => ++pages);
+    useEffect(() => {
+        store.start();
+        return () => store.stop();
+    }, [store]);
+    // The page's popups go with it: their answers would be written into data no card shows any more.
+    useEffect(() => {
+        const open = popups.current;
+        return () => {
+            const closing = [...open];
+            open.clear();
+            for (const popup of closing)
+                popup.close();
+        };
+    }, []);
+    // A link to a card (`/dashboard/profile#emails`) is followed while the cards are held; the cards above it may grow as
+    // their records come (a list longer than its held rows) and push it away. Once every source has answered, the card
+    // the address names is brought back into view - once, and only while the person has not moved on: a wheel, a touch,
+    // a key or a press since the page opened (or more than a few seconds gone) leaves the page where they are.
+    const followed = useRef(false);
+    const movedOn = useRef(false);
+    useEffect(() => {
+        const moved = () => {
+            movedOn.current = true;
+        };
+        const events = ["wheel", "touchstart", "keydown", "pointerdown"];
+        for (const name of events)
+            window.addEventListener(name, moved, { capture: true, passive: true });
+        const late = window.setTimeout(moved, FOLLOW_WITHIN_MS);
+        return () => {
+            window.clearTimeout(late);
+            for (const name of events)
+                window.removeEventListener(name, moved, { capture: true });
+        };
+    }, []);
+    const settled = Object.values(states).every(state => state.status !== "loading");
+    useEffect(() => {
+        if (!settled || followed.current)
+            return;
+        followed.current = true;
+        if (movedOn.current)
+            return;
+        let id = "";
+        try {
+            id = decodeURIComponent(window.location.hash.slice(1));
+        }
+        catch {
+            return;
+        }
+        if (!id)
+            return;
+        const target = document.getElementById(id);
+        if (!target?.closest(".nx-record"))
+            return;
+        // Already where the link put it (its top in view): left as it is.
+        const top = target.getBoundingClientRect().top;
+        if (top >= 0 && top < window.innerHeight / 2)
+            return;
+        target.scrollIntoView({ block: "start" });
+    }, [settled]);
+    /** An answer that ended the session, when the page says what to do then: the page's words, its popups closed. */
+    const ended = useCallback((answer) => {
+        const { signedOut, isSessionEnded = recordSessionEnded } = latest.current;
+        if (!signedOut || answer.ok || answer.aborted || !isSessionEnded(answer))
+            return false;
+        if (store.ended)
+            return true;
+        store.end(answer);
+        const closing = [...popups.current];
+        popups.current.clear();
+        for (const popup of closing)
+            popup.close();
+        // A closing popup hands the focus back to what opened it, which went with the cards: Sign in again takes it.
+        void Promise.all(closing.map(popup => popup.closed)).then(() => {
+            const active = document.activeElement;
+            if (!active || active === document.body)
+                document.getElementById(`${latest.current.name ?? "record"}-sign-in`)?.focus();
+        });
+        signedOut.onEnded?.(answer);
+        return true;
+    }, [store]);
+    endRef.current = ended;
+    const sourceOf = useCallback((card) => card.source ?? store.names[0] ?? "", [store]);
+    /** Reads a source again for a step: its data, or null - said in a toast while the cards still show the data. */
+    const reload = useCallback(async (source) => {
+        const answer = await store.read(source);
+        if (answer.ok)
+            return store.get(source).data;
+        if (!answer.aborted && !store.ended && store.get(source).status === "ready")
+            toast.error(`Not read again: ${answer.message ?? "the server did not answer."}`, "The page shows what was read before.");
+        return null;
+    }, [store]);
+    /** Puts the focus back in a card when what held it went away: the item's first button, the card's, or its title. */
+    const focusHome = useCallback((cardId, itemKey) => {
+        const root = document.getElementById(cardId);
+        if (!root)
+            return;
+        const row = itemKey !== undefined ? root.querySelector(`[data-key="${CSS.escape(itemKey)}"]`) : null;
+        const target = row?.querySelector("button") ?? root.querySelector(".nx-record-card__actions button, .nx-record-card__body button") ?? root.querySelector(".nx-record-card__title");
+        target?.focus({ preventScroll: true });
+    }, []);
+    const contextOf = useCallback((card, item) => {
+        const source = sourceOf(card);
+        const state = store.get(source);
+        const now = item && card.itemKey ? recordItems(state.data, card.items).find(one => recordItemKey(one, card.itemKey) === item.key) : undefined;
+        return {
+            data: state.data,
+            item: item ? (now ?? item.value) : undefined,
+            readOnly: latest.current.readOnly === true || card.readOnly === true,
+            reload: () => reload(source),
+            write: data => store.write(source, data),
+            run: (actionId, target) => {
+                const action = card.itemActions?.find(one => one.id === actionId);
+                if (action && card.itemKey)
+                    runItemRef.current(card, action, target);
+            },
+            // A popup of the page's own: its values sent as they are (or merged over the item), its answer written as said.
+            open: flow => {
+                const named = flow.label ?? (typeof flow.title === "string" ? flow.title : "open");
+                const label = item ? (card.itemLabel?.(item.value) ?? item.key) : undefined;
+                openFlowRef.current(card, { id: `open-${named}`, label: named }, flow, item ? "item" : "add", item && label !== undefined ? { ...item, label } : undefined);
+            },
+        };
+    }, [store, sourceOf, reload]);
+    const hostOf = useCallback((card, item) => ({
+        context: () => contextOf(card, item),
+        subscribe: store.subscribe,
+        snapshot: store.snapshot,
+        write: async ({ writes, result, values, fallback }) => {
+            const source = sourceOf(card);
+            const context = contextOf(card, item);
+            const outcome = recordWrite({ writes, result, data: store.get(source).data, values, fallback, items: card.items, itemKey: card.itemKey, item: context.item });
+            if (outcome.kind === "write")
+                store.write(source, outcome.data);
+            else if (outcome.kind === "reload")
+                await reload(source);
+        },
+        ended,
+        track: popup => {
+            popups.current.add(popup);
+            void popup.closed.then(() => {
+                popups.current.delete(popup);
+                const active = document.activeElement;
+                if (!active || active === document.body)
+                    focusHome(card.id, item?.key);
+            });
+        },
+    }), [store, contextOf, sourceOf, reload, ended, focusHome]);
+    const name = props.name ?? "record";
+    const openFlow = useCallback((card, action, flow, kind, item) => {
+        openRecordFlow({
+            flow,
+            host: hostOf(card, item),
+            key: `${name}:${page}:${card.id}:${action.id}${item ? `:${item.key}` : ""}`,
+            title: kind === "item" ? action.label : (card.title ?? action.label),
+            description: item?.label ?? (kind === "add" ? action.label : undefined),
+            kind,
+            inputs: kind === "edit" && card.fields ? recordFieldInputs({ fields: card.fields }) : undefined,
+        });
+    }, [hostOf, name, page]);
+    const openFlowRef = useRef(openFlow);
+    openFlowRef.current = openFlow;
+    /**
+     * A question, then the call: the item (or the card) busy meanwhile. The question hands the focus back to the button,
+     * which the answer may take away (a Remove takes its row): the focus then comes home, once the change is drawn.
+     */
+    const confirmThen = useCallback((card, confirm, busyKey, item) => {
+        void runRecordConfirm(confirm, hostOf(card, item), on => setBusy(now => ({ ...now, [card.id]: recordBusyKeys(now[card.id], busyKey, on) }))).then(() => window.requestAnimationFrame(() => {
+            const active = document.activeElement;
+            if (!active || active === document.body)
+                focusHome(card.id, item?.key);
+        }));
+    }, [hostOf, focusHome]);
+    const runCard = useCallback((card, action, kind) => {
+        if (action.flow)
+            openFlow(card, action, action.flow, kind);
+        else if (action.confirm)
+            confirmThen(card, action.confirm, "card");
+        else
+            action.onSelect?.(contextOf(card));
+    }, [openFlow, confirmThen, contextOf]);
+    const runItem = useCallback((card, action, value) => {
+        const key = recordItemKey(value, card.itemKey);
+        const label = card.itemLabel?.(value) ?? itemTitle(card, value, store.get(sourceOf(card)).data, key);
+        const item = { key, value, label };
+        const actionLabel = typeof action.label === "function" ? action.label(value, store.get(sourceOf(card)).data) : action.label;
+        if (action.flow)
+            openFlow(card, { id: action.id, label: actionLabel }, action.flow, "item", item);
+        else if (action.confirm)
+            confirmThen(card, action.confirm, key, item);
+        else
+            action.onSelect?.(contextOf(card, item));
+    }, [store, sourceOf, openFlow, confirmThen, contextOf]);
+    const runItemRef = useRef(runItem);
+    runItemRef.current = runItem;
+    const retry = useCallback((source, cardId) => {
+        const had = document.getElementById(cardId)?.contains(document.activeElement) ?? false;
+        void store.read(source).then(() => {
+            if (had && (!document.activeElement || document.activeElement === document.body))
+                focusHome(cardId);
+        });
+    }, [store, focusHome]);
+    const endedAnswer = store.ended;
+    const { signedOut } = props;
+    if (endedAnswer && signedOut) {
+        const Heading = headingLevel === 3 ? "h3" : "h2";
+        const message = typeof signedOut.message === "function" ? signedOut.message(endedAnswer) : (signedOut.message ?? endedAnswer.message ?? "Your session has ended. Sign in again.");
+        return (_jsx("div", { className: cx("nx-record", className), children: _jsxs("section", { className: "nx-record-card nx-record-card--wide", "aria-labelledby": `${name}-ended`, children: [_jsx("header", { className: "nx-record-card__head", children: _jsx("div", { className: "nx-record-card__text", children: _jsx(Heading, { id: `${name}-ended`, className: "nx-record-card__title", children: signedOut.title ?? "Your session has ended" }) }) }), _jsxs("div", { className: "nx-record-card__body", children: [_jsx("p", { role: "alert", className: "nx-record-card__message", children: message }), _jsx(Button, { id: `${name}-sign-in`, variant: "primary", autoFocus: true, onClick: signedOut.onSignIn, children: signedOut.label ?? "Sign in again" })] })] }) }));
+    }
+    const runtime = {
+        store,
+        readOnly,
+        level: headingLevel,
+        can,
+        preferences,
+        busy,
+        sourceOf,
+        loudFor: loudParts(hero ? [{ id: `${name}-hero`, source: sourceOf(hero) }, ...cards.map(card => ({ id: card.id, source: sourceOf(card) }))] : cards.map(card => ({ id: card.id, source: sourceOf(card) })), states),
+        retry,
+        runCard,
+        runItem,
+        contextOf,
+    };
+    return (_jsxs("div", { className: cx("nx-record", className), role: props["aria-label"] ? "region" : undefined, "aria-label": props["aria-label"], children: [hero && _jsx(RecordHero, { hero: hero, id: `${name}-hero`, state: states[sourceOf(hero)] ?? store.get(sourceOf(hero)), runtime: runtime }), _jsx("div", { className: "nx-record__cards", children: cards.map(card => (_jsx(RecordCardView, { card: card, state: states[sourceOf(card)] ?? store.get(sourceOf(card)), runtime: runtime }, card.id))) })] }));
+}
+/** The first part (in the page's order) that shows each failed source: it alone says the failure aloud. */
+function loudParts(parts, states) {
+    const loud = new Map();
+    for (const part of parts)
+        if (states[part.source]?.status === "failed" && !loud.has(part.source))
+            loud.set(part.source, part.id);
+    return loud;
+}
+/** An item's name for a screen reader and a popup's line: its title when that is text, else its key. */
+function itemTitle(card, item, data, key) {
+    const title = card.item(item, data).title;
+    return typeof title === "string" || typeof title === "number" ? String(title) : key;
+}
+/** The failure of a source, in a card: the server's words and Try again. The first part to show it says it aloud. */
+function Failed({ state, source, cardId, runtime }) {
+    const loud = runtime.loudFor.get(source) === cardId;
+    return (_jsxs("div", { className: "nx-form-load-failed nx-record__failed", role: loud ? "alert" : undefined, children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsxs("p", { children: [_jsx("strong", { children: "This could not be read." }), " ", state.answer.message ?? "The server did not answer."] }), _jsx("div", { className: "nx-form-load-failed__actions", children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => runtime.retry(source, cardId), children: "Try again" }) })] }));
+}
+/** The marks after a name: the table's tags, each with its tone. */
+function Marks({ marks, className }) {
+    if (!marks?.length)
+        return null;
+    return (_jsx("span", { className: className, children: marks.map((mark, index) => (_jsx("span", { className: "nx-table__tag", "data-tone": mark.tone, children: mark.label }, index))) }));
+}
+/**
+ * The buttons of a card's heading, the hero's, or an item's right side, with the note a held one says when pressed (the
+ * read-only fields' and the table's held Add's): one note for the whole part, saying the pressed button's reason.
+ */
+function useHeldNote(rootRef) {
+    const [reason, setReason] = useState("");
+    const notice = useReadOnlyNotice(true, rootRef, reason, { anchor: target => target.closest(".nx-btn"), typing: false, lock: "label" });
+    return {
+        note: notice.notice,
+        onKeyDown: (event) => notice.onKeyDown(event),
+        say: (target, why) => {
+            setReason(why);
+            notice.show(target);
+        },
+    };
+}
+/** The text a card's title says, for a button named after it: its text, or the heading's own words once drawn. */
+const titleText = (title) => (typeof title === "string" || typeof title === "number" ? String(title).trim() || null : null);
+/**
+ * A heading's buttons: Edit or Add first, then the card's own; held ones say why when pressed. Each is named with its
+ * card to a screen reader ("Edit: Personal details"), as an item's icons are with their item: three Edits on a page are
+ * three different buttons.
+ */
+function HeaderActions({ actions, card, runtime, say, busy }) {
+    const visible = actions.filter(entry => entry.state.kind !== "hidden");
+    if (!visible.length)
+        return null;
+    const of = titleText(card.title);
+    return (_jsx("div", { className: "nx-record-card__actions", children: visible.map(({ action, kind, state }) => {
+            const held = state.kind === "held" ? state.reason : null;
+            return (_jsx(Button, { size: "sm", icon: action.icon, hoverTone: action.tone === "danger" ? "danger" : undefined, "data-action": action.id, "data-held": held !== null || undefined, "aria-label": of ? recordActionName(action.label, of) : undefined, "aria-disabled": held !== null || busy || undefined, title: held ?? undefined, onClick: event => {
+                    if (held !== null)
+                        return say(event.currentTarget, held);
+                    if (!busy)
+                        runtime.runCard(card, action, kind);
+                }, children: action.label }, action.id));
+        }) }));
+}
+/** The card across the top: the picture that opens the pictures window, the name, its lines and marks. */
+function RecordHero({ hero, id, state, runtime }) {
+    const rootRef = useRef(null);
+    const held = useHeldNote(rootRef);
+    const data = state.data ?? {};
+    const loading = state.status === "loading";
+    const source = runtime.sourceOf(hero);
+    const Heading = runtime.level === 3 ? "h3" : "h2";
+    const title = hero.title(data);
+    const picture = hero.picture?.(data);
+    const lines = hero.lines?.(data) ?? [];
+    const card = { id, source: hero.source, title };
+    const actions = (hero.actions ?? []).map(action => ({
+        action,
+        kind: "edit",
+        // While the record is read its rules are not asked: each is held (or not drawn yet, `loading: "hidden"`).
+        state: state.status === "failed" ? { kind: "hidden" } : recordActionState(action, state.status === "ready" ? [data] : null, { readOnly: runtime.readOnly, can: runtime.can }),
+    }));
+    return (_jsxs("section", { ref: rootRef, id: id, className: "nx-record-hero", "aria-labelledby": `${id}-title`, "aria-busy": loading || undefined, onKeyDown: held.onKeyDown, children: [shown(picture) && (_jsx("div", { className: "nx-record-hero__picture", children: _jsx(ProfilePicture, { picture: picture, title: title, size: "var(--nx-record-hero-picture)", readOnly: runtime.readOnly }) })), _jsxs("div", { className: "nx-record-hero__text", children: [_jsx(Heading, { id: `${id}-title`, className: "nx-record-hero__title", children: shown(title) ? title : _jsx(Bone, { width: "12rem" }) }), lines.map((line, index) => shown(line) ? (_jsx("p", { className: "nx-record-hero__line", children: line }, index)) : loading ? (_jsx("p", { className: "nx-record-hero__line", "aria-hidden": "true", children: "\u00A0" }, index)) : null), state.status === "failed" ? (_jsx(Failed, { state: state, source: source, cardId: id, runtime: runtime })) : loading && hero.marks && !hero.marks(data).length ? (_jsx("span", { className: "nx-record-hero__marks", "aria-hidden": "true", children: _jsx("span", { className: "nx-table__tag nx-table__tag--plain nx-record__bone-tag", children: "\u00A0" }) })) : (_jsx(Marks, { marks: hero.marks?.(data), className: "nx-record-hero__marks" }))] }), _jsx(HeaderActions, { actions: actions, card: card, runtime: runtime, say: held.say, busy: false }), held.note] }));
+}
+/** One card: its heading (icon, title, count, sentence, buttons) and its body (fields, items, or its own). */
+function RecordCardView({ card, state, runtime }) {
+    const rootRef = useRef(null);
+    const held = useHeldNote(rootRef);
+    const kind = recordCardKind(card);
+    const source = runtime.sourceOf(card);
+    const data = state.data;
+    const ready = state.status === "ready";
+    if (ready && card.hidden?.(data))
+        return null;
+    const readOnly = runtime.readOnly || card.readOnly === true;
+    const busy = runtime.busy[card.id] ?? [];
+    const Heading = runtime.level === 3 ? "h3" : "h2";
+    const titleId = `${card.id}-title`;
+    const description = typeof card.description === "function" ? (ready ? card.description(data) : null) : card.description;
+    // The heading's buttons: Edit or Add first, then the card's own. Held while the source loads; none once it failed.
+    const items = kind === "items" ? card : null;
+    const list = items && ready ? recordItems(data, items.items) : [];
+    const limit = items && ready ? recordLimit(data, items.limit) : null;
+    // The rules typed on the data are asked once it is read; until then each button is held, saying so.
+    const stateOf = (action, extra) => {
+        if (state.status === "failed")
+            return { kind: "hidden" };
+        const own = recordActionState(action, ready ? [data] : null, { readOnly, can: runtime.can });
+        if (own.kind !== "ready")
+            return own;
+        return extra ? { kind: "held", reason: extra } : own;
+    };
+    const header = [];
+    if (kind === "fields") {
+        const edit = card.edit;
+        if (edit) {
+            const action = { id: "edit", label: edit.label ?? "Edit", icon: edit.icon ?? _jsx(InlineIcon, { icon: iconPencil }), flow: edit };
+            header.push({ action, kind: "edit", state: stateOf(action) });
+        }
+    }
+    if (items?.add) {
+        const add = items.add;
+        const action = { id: "add", label: add.label ?? "Add", icon: add.icon ?? _jsx(InlineIcon, { icon: iconPlus }), flow: add };
+        const full = limit !== null && list.length >= limit ? recordLimitReason(limit, items.limitReason) : null;
+        header.push({ action, kind: "add", state: stateOf(action, full) });
+    }
+    for (const action of card.actions ?? [])
+        header.push({ action, kind: "edit", state: stateOf(action) });
+    let body;
+    if (state.status === "failed")
+        body = _jsx(Failed, { state: state, source: source, cardId: card.id, runtime: runtime });
+    else if (kind === "fields")
+        body = _jsx(FieldsBody, { card: card, data: data, loading: !ready, preferences: runtime.preferences });
+    else if (kind === "items")
+        body = _jsx(ItemsBody, { card: items, data: data, loading: !ready, runtime: runtime, readOnly: readOnly, busy: busy, say: held.say });
+    else if (!ready)
+        body = _jsx(HeldLines, {});
+    else
+        body = card.render(runtime.contextOf(card));
+    return (_jsxs("section", { ref: rootRef, id: card.id, className: cx("nx-record-card", `nx-record-card--${kind}`, card.wide && "nx-record-card--wide"), "aria-labelledby": titleId, "aria-busy": state.status === "loading" || busy.length > 0 || undefined, "data-state": state.status, onKeyDown: held.onKeyDown, children: [_jsxs("header", { className: "nx-record-card__head", children: [card.icon && (_jsx("span", { className: "nx-record-card__icon", "aria-hidden": "true", children: card.icon })), _jsxs("div", { className: "nx-record-card__main", children: [_jsxs("div", { className: "nx-record-card__text", children: [_jsxs(Heading, { id: titleId, className: "nx-record-card__title", tabIndex: -1, children: [card.title, items && limit !== null && _jsx("span", { className: "nx-record-card__count", children: recordCount(list.length, limit) })] }), shown(description) && _jsx("p", { className: "nx-record-card__lead", children: description })] }), _jsx(HeaderActions, { actions: header, card: card, runtime: runtime, say: held.say, busy: busy.length > 0 })] })] }), _jsx("div", { className: "nx-record-card__body", children: body }), held.note] }));
+}
+/** Two held lines of text, for a card of the page's own while its source loads: each a line box, as a paragraph's are. */
+const HeldLines = () => (_jsxs("div", { className: "nx-record__held", "aria-hidden": "true", children: [_jsx("span", { className: "nx-record__held-line", children: _jsx(Bone, { width: "80%" }) }), _jsx("span", { className: "nx-record__held-line", children: _jsx(Bone, { width: "55%" }) })] }));
+/** A fields card's body: label over value, from the inputs its Edit uses. */
+function FieldsBody({ card, data, loading, preferences }) {
+    const fields = card.fields.map(recordField);
+    return (_jsx("dl", { className: "nx-record-fields", children: fields.map(field => {
+            if (!loading && field.hidden?.(data))
+                return null;
+            const label = field.label ?? field.input.label ?? field.input.name;
+            return (_jsxs("div", { className: cx("nx-record-field", recordFieldWide(field) && "nx-record-field--wide"), children: [_jsx("dt", { className: "nx-record-field__label", children: label }), _jsx("dd", { className: "nx-record-field__value", children: loading ? _jsx(HeldValue, { field: field }) : _jsx(FieldValue, { field: field, data: data, empty: card.empty ?? "Not said", preferences: preferences }) })] }, field.input.name));
+        }) }));
+}
+/** A value held while its source loads, as tall as it will be: two lines for long text, a chip's height for chips. */
+function HeldValue({ field }) {
+    const held = recordFieldHeld(field);
+    // Each bone on a line of its own, as the text will be (`heldLines`; long text 2); a chip as the chips will be.
+    if (held === "lines" || field.heldLines !== undefined) {
+        const lines = recordHeldLines(field);
+        return (_jsx(_Fragment, { children: Array.from({ length: lines }, (_, index) => (_jsx("span", { className: "nx-record__held-line", children: _jsx(Bone, { width: index === lines - 1 && lines > 1 ? "55%" : "85%" }) }, index))) }));
+    }
+    if (held === "chips")
+        return (_jsx("ul", { className: "nx-record-chips", "aria-hidden": "true", children: _jsx("li", { className: "nx-table__tag nx-table__tag--plain nx-record__bone-tag", children: "\u00A0" }) }));
+    return _jsx(Bone, { width: "60%" });
+}
+/** One value as its input draws it: a choice by its label, a date in the person's format, chips, lines, Markdown. */
+function FieldValue({ field, data, empty, preferences }) {
+    const value = isRecord(data) ? data[field.input.name] : undefined;
+    const none = _jsx("span", { className: "nx-record-field__empty", children: empty });
+    if (field.show) {
+        const own = field.show(value, data);
+        return shown(own) ? _jsx(_Fragment, { children: own }) : none;
+    }
+    const view = recordValueView(field.input, value, { look: field.look, preferences });
+    switch (view.kind) {
+        case "empty":
+            return none;
+        case "text":
+            return _jsx(_Fragment, { children: view.text });
+        case "lines":
+            return _jsx("span", { className: "nx-record-field__lines", children: view.text });
+        case "chips":
+            return (_jsx("ul", { className: "nx-record-chips", children: view.items.map((item, index) => (_jsx("li", { className: "nx-table__tag nx-table__tag--plain", children: item }, `${index}:${item}`))) }));
+        case "markdown":
+            return _jsx(MarkdownView, { value: view.text });
+        case "rich":
+            return _jsx(RichTextView, { value: view.html });
+    }
+}
+/** An items card's body: the rows, each with its picture or icon, its name and marks, lines, and icon actions. */
+function ItemsBody({ card, data, loading, runtime, readOnly, busy, say, }) {
+    if (loading) {
+        return (_jsx("ul", { className: "nx-record-items", "aria-hidden": "true", children: Array.from({ length: card.heldRows ?? 2 }, (_, index) => (_jsxs("li", { className: "nx-record-item", children: [_jsx("span", { className: "nx-record-item__media nx-record-item__media--held" }), _jsxs("span", { className: "nx-record-item__text", children: [_jsx("span", { className: "nx-record-item__title nx-record__held-line", children: _jsx(Bone, { width: "45%" }) }), Array.from({ length: recordHeldLines({ heldLines: card.heldRowLines ?? 1 }) }, (_, line) => (_jsx("span", { className: "nx-record-item__line nx-record__held-line", children: _jsx(Bone, { width: line ? "40%" : "30%" }) }, line)))] })] }, index))) }));
+    }
+    const items = recordItems(data, card.items);
+    if (!items.length)
+        return _jsx("p", { className: "nx-record-card__empty", children: card.empty ?? "Nothing here yet." });
+    return (_jsx("ul", { className: "nx-record-items", children: items.map(item => {
+            const key = recordItemKey(item, card.itemKey);
+            const view = card.item(item, data);
+            const label = card.itemLabel?.(item) ?? itemTitle(card, item, data, key);
+            const working = busy.includes(key) || busy.includes("card");
+            const actions = (card.itemActions ?? [])
+                .map(action => ({ action, state: recordActionState(action, [item, data], { readOnly, can: runtime.can }) }))
+                .filter(entry => entry.state.kind !== "hidden");
+            const media = view.picture ?? view.icon;
+            return (_jsxs("li", { className: "nx-record-item", "data-key": key, "aria-busy": working || undefined, children: [shown(media) && _jsx("span", { className: cx("nx-record-item__media", !view.picture && "nx-record-item__media--icon"), children: media }), _jsxs("div", { className: "nx-record-item__text", children: [_jsxs("p", { className: "nx-record-item__title", children: [_jsx("span", { className: "nx-record-item__name", children: view.title }), _jsx(Marks, { marks: view.marks, className: "nx-record-item__marks" })] }), (view.lines ?? []).filter(shown).map((line, index) => (_jsx("p", { className: "nx-record-item__line", children: line }, index)))] }), actions.length > 0 && (_jsx("div", { className: "nx-record-item__actions", children: actions.map(({ action, state }) => {
+                            const name = typeof action.label === "function" ? action.label(item, data) : action.label;
+                            const held = state.kind === "held" ? state.reason : null;
+                            return (_jsx(Button, { variant: "ghost", size: "sm", icon: action.icon, hoverTone: action.tone === "danger" ? "danger" : undefined, "aria-label": recordActionName(name, label), title: held ? `${name}. ${held}` : name, "data-action": action.id, "data-held": held !== null || undefined, "aria-disabled": held !== null || working || undefined, onClick: event => {
+                                    if (held !== null)
+                                        return say(event.currentTarget, held);
+                                    if (!working)
+                                        runtime.runItem(card, action, item);
+                                } }, action.id));
+                        }) }))] }, key));
+        }) }));
+}

package/dist/Helpers/BusyHooks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether to say that something is still under way: `true` only once `busy` has lasted 400ms, and then for at least
+ * 300ms, however soon `busy` ends. A status line that reads it says "Loading…" for a slow read and nothing for a quick
+ * one. A Crud's details footer and `DocumentFrame` use it.
+ */
+export declare function useSlowBusy(busy: boolean): boolean;

package/dist/Helpers/BusyHooks.js

@@ -0,0 +1,39 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A read that ends sooner than this says nothing: most backends answer sooner, and a word shown for a frame or two is
+ * the flicker this avoids. Longer than a popup's 160ms fade, so the word never lands on a half-faded popup.
+ */
+const SLOW_DELAY = 400;
+/** Once the word shows, it stays at least this long, so a read that ends just after the delay does not blink it. */
+const SLOW_HOLD = 300;
+/**
+ * Whether to say that something is still under way: `true` only once `busy` has lasted 400ms, and then for at least
+ * 300ms, however soon `busy` ends. A status line that reads it says "Loading…" for a slow read and nothing for a quick
+ * one. A Crud's details footer and `DocumentFrame` use it.
+ */
+export function useSlowBusy(busy) {
+    const [said, setSaid] = useState(false);
+    const since = useRef(0);
+    useEffect(() => {
+        if (busy) {
+            if (said)
+                return;
+            const timer = window.setTimeout(() => {
+                since.current = performance.now();
+                setSaid(true);
+            }, SLOW_DELAY);
+            return () => window.clearTimeout(timer);
+        }
+        if (!said)
+            return;
+        const left = since.current + SLOW_HOLD - performance.now();
+        if (left <= 0) {
+            setSaid(false);
+            return;
+        }
+        const timer = window.setTimeout(() => setSaid(false), left);
+        return () => window.clearTimeout(timer);
+    }, [busy, said]);
+    return said;
+}

package/dist/Helpers/CrudBackend.d.ts

@@ -105,10 +105,19 @@ export declare abstract class CrudBackend {
     answeredRow<TRow extends TableRow>(result: unknown): Partial<TRow> | null;
     /**
      * The key an answer gives in place of the record: `Create` answering the new record's id. `null` when the answer
-     * is the record itself, or says nothing. With a key the new record goes straight into the list, and where there is
-     * a `details` endpoint it is read back on its own - one small request, never the whole list again.
+     * is the record itself, or says nothing. With a key the new record goes straight into the list, finished by `savedRow`;
+     * only a record whose list still cannot be told is read back on its own through `details` - never the whole list again.
      */
     answeredKey(result: unknown): TableKey | null;
+    /**
+     * A record a save wrote - what the form sent, under what the answer said - with the fields only the server keeps
+     * filled in as this backend writes them, so nothing has to be read back: a status, the times, the marks. `before` is
+     * the record as the page holds it now (an edit; `undefined` for a new one): an edit's form carries its own copy of those
+     * fields from when it opened, which a flag or a mark made since has left behind. Default: the record as it is - and a
+     * record whose list still cannot be told from it (`listMembership`) is read back once through `details`, where there is
+     * one.
+     */
+    savedRow<TRow extends TableRow>(action: "create" | "edit", record: TRow, before?: TRow): TRow;
     /**
      * Whether a record belongs in a list, read from the record itself. It is what lets one answer be written into the
      * lists that are **not** on screen: a flagged record joins the flagged list, a trashed one leaves the active list
@@ -176,6 +185,15 @@ export declare class NexusCrudBackend extends CrudBackend {
     answeredRow<TRow extends TableRow>(result: unknown): Partial<TRow> | null;
     /** `Create` and `Update` answer the record's id: a token when ids are encrypted, the number as text when not. */
     answeredKey(result: unknown): TableKey | null;
+    /**
+     * What a Nexus save leaves to the server, written as the server writes it, so nothing is read back (the owner,
+     * 2026-10-10: "the creationTime, recordStatus we will provide fake or just right now"). A new record lacking them is
+     * Active (every Create writes `NEXUS_ACTIVE_STATUS`), has no marks, was added now and never changed; what its answer
+     * said stays. An Update writes none of the status, the marks and the time added, so an edited record has the ones the
+     * page holds (`before`) - over its form's older copies - and was changed now. Times are UTC ISO strings, as a date-time
+     * column reads them.
+     */
+    savedRow<TRow extends TableRow>(action: "create" | "edit", record: TRow, before?: TRow): TRow;
     /**
      * The bands the owner settled on: under 40 is live, 25–29 of that is flagged, 40–59 is the trash, and 60 and up is
      * deleted. A row without a `recordStatus` says nothing, and the lists it cannot answer for load again.