nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Domains/DomainCard.js

@@ -0,0 +1,182 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconArrowRight, iconChevronDown, iconChevronUp, iconLoader2, iconLock, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useImperativeHandle, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { chatTimeLabel } from "../../Helpers/ChatHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { domainCardContext, domainCardFailedText, domainCardFields, domainCardNoun, domainCardOf, domainCardRefusedText, domainCardShape, domainCardValueText, DomainCardRun, heldDomainCardShape, rememberDomainCardShape, } from "../../Helpers/DomainCards.js";
+import { useNumberLocale } from "../../Helpers/UserPreferences.js";
+import { ChatFailure } from "../Chats/ChatParts.js";
+import { Button } from "../Documents/Button.js";
+/** A record's card, read live from its module: see the notes at the top of this file. */
+export function DomainCard({ card: given, kind: givenKind, ...props }) {
+    const registered = domainCardOf(props.domain);
+    const card = given === undefined ? registered?.card : (given ?? undefined);
+    const kind = givenKind ?? registered?.info.label ?? chatDomainLabel(props.domain);
+    const { id } = props;
+    if (!card || id === null || id === undefined || id === "")
+        return _jsx(DomainLine, { kind: kind, label: props.label, className: props.className });
+    // A record of its own is a read of its own: another id starts from its placeholder, never from the last record.
+    return _jsx(LiveDomainCard, { ...props, id: id, card: card, kind: kind }, `${String(props.domain)}|${String(id)}|${String(props.viewer ?? "")}`);
+}
+/** One record's card read, for a page that draws it its own way: the snapshot, and `run.reload()` / `run.retry()`. */
+export function useDomainCard({ domain, id, card, viewer, label, kind, revision }) {
+    const context = useMemo(() => domainCardContext(domain, id, { ...(viewer !== null && viewer !== undefined && { viewer }), label, kind }), [domain, id, viewer, label, kind]);
+    const latest = useRef({ card, context });
+    latest.current = { card, context };
+    const run = useMemo(() => new DomainCardRun({ domainType: domain, id, viewer, lifetime: card.lifetime, load: signal => latest.current.card.load(id, signal, latest.current.context) }), 
+    // A new card definition for the same record keeps the run: `load` is read when it is called.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [domain, id, viewer]);
+    useEffect(() => {
+        run.start();
+        return () => run.stop();
+    }, [run]);
+    const snapshot = useSyncExternalStore(run.subscribe, run.getSnapshot, run.getSnapshot);
+    // A change seen after the card was drawn reads the record again; the revision it opened with does not.
+    const seen = useRef(revision);
+    useEffect(() => {
+        if (revision === seen.current)
+            return;
+        seen.current = revision;
+        run.reload();
+    }, [revision, run]);
+    const shown = useMemo(() => {
+        if (snapshot.data === undefined)
+            return {};
+        try {
+            return { params: card.view(snapshot.data, context) };
+        }
+        catch (error) {
+            console.error("A record's card could not be drawn from its answer:", error);
+            return { viewError: error };
+        }
+    }, [snapshot.data, card, context]);
+    useEffect(() => {
+        if (shown.params)
+            rememberDomainCardShape(domain, domainCardShape(shown.params));
+    }, [domain, shown.params]);
+    return { run, snapshot, context, ...shown };
+}
+function LiveDomainCard({ domain, id, label, revision, viewer, card, kind, headingLevel = 3, collapsible = true, defaultCollapsed = false, collapsed: heldCollapsed, onCollapsedChange, className, ref }) {
+    const state = useDomainCard({ domain, id, card, viewer, label, kind, revision });
+    const { run, snapshot, params, viewError, context } = state;
+    const [ownCollapsed, setOwnCollapsed] = useState(defaultCollapsed);
+    const collapsed = heldCollapsed ?? ownCollapsed;
+    const setCollapsed = (next) => {
+        setOwnCollapsed(next);
+        onCollapsedChange?.(next);
+    };
+    useImperativeHandle(ref, () => ({ reload: () => run.reload() }), [run]);
+    // Said aloud once, when a read again changes what is on screen or fails.
+    const [spoken, setSpoken] = useState("");
+    const noun = domainCardNoun(kind);
+    useEffect(() => {
+        if (snapshot.changedAt)
+            setSpoken(`The ${noun} was updated.`);
+    }, [snapshot.changedAt, noun]);
+    useEffect(() => {
+        if (snapshot.refreshFailed)
+            setSpoken(`The ${noun} could not be read again.`);
+    }, [snapshot.refreshFailed, noun]);
+    const live = (_jsx("span", { className: "nx-visually-hidden", "aria-live": "polite", children: spoken }));
+    if (snapshot.status === "refused") {
+        return (_jsxs("section", { className: cx("nx-domain-card", className), "data-state": "refused", "aria-label": kind ?? label ?? undefined, "aria-busy": snapshot.refreshing || undefined, children: [_jsx(DomainLine, { kind: kind, label: label }), _jsxs("p", { className: "nx-domain-card__notice", children: [_jsx(InlineIcon, { icon: iconLock }), domainCardRefusedText(kind)] }), live] }));
+    }
+    if (snapshot.status === "failed" || (viewError !== undefined && !params)) {
+        return (_jsxs("section", { className: cx("nx-domain-card", className), "data-state": "failed", "aria-label": kind ?? label ?? undefined, children: [_jsx(DomainLine, { kind: kind, label: label }), _jsx(ChatFailure, { message: domainCardFailedText(kind), onRetry: () => run.retry() }), live] }));
+    }
+    if (snapshot.status === "loading" || !params) {
+        return (_jsxs(_Fragment, { children: [_jsx(DomainCardHeld, { shape: heldDomainCardShape(domain, card), kind: kind, label: label, headingLevel: headingLevel, collapsible: collapsible, collapsed: collapsed, onCollapsedChange: setCollapsed, className: className }), live] }));
+    }
+    const status = snapshot.refreshing ? (_jsx("span", { className: "nx-domain-card__meta", title: "Reading again", children: _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) })) : snapshot.refreshFailed ? (_jsxs("span", { className: "nx-domain-card__meta nx-domain-card__meta--failed", children: ["Not up to date", _jsx("button", { type: "button", className: "nx-domain-card__retry", onClick: () => run.retry(), children: "Try again" })] })) : snapshot.changedAt ? (_jsx(DomainCardUpdated, { at: snapshot.changedAt })) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(DomainCardFrame, { params: params, kind: kind, headingLevel: headingLevel, status: status, busy: snapshot.refreshing, collapsible: collapsible, collapsed: collapsed, onCollapsedChange: setCollapsed, className: className, "data-state": "ready", children: card.extra && snapshot.data !== undefined ? card.extra(snapshot.data, context) : null }), live] }));
+}
+/** "Updated 2:45 PM": the record changed while its card was open. */
+function DomainCardUpdated({ at }) {
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const moment = new Date(at).toISOString();
+    return (_jsxs("span", { className: "nx-domain-card__meta", children: ["Updated ", _jsx("time", { dateTime: moment, children: chatTimeLabel(moment, { ...preferences, ...(zone && { timeZone: zone }) }) })] }));
+}
+/**
+ * A card drawn from params alone: the look every record's card shares. `DomainCard` draws it once a record is read; a
+ * page that already holds a record (a dashboard, a print preview) can draw it straight.
+ */
+export function DomainCardFrame({ params, kind, headingLevel = 3, status, busy = false, collapsible = false, collapsed: heldCollapsed, defaultCollapsed = false, onCollapsedChange, children, className, "data-state": dataState, }) {
+    const [ownCollapsed, setOwnCollapsed] = useState(defaultCollapsed);
+    const collapsed = collapsible && (heldCollapsed ?? ownCollapsed);
+    const titleId = useId();
+    const detailsId = useId();
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const locale = useNumberLocale();
+    const values = { preferences, timeZone: zone, locale, currency: params.currency };
+    const Heading = `h${headingLevel}`;
+    const fields = domainCardFields(params);
+    const figures = params.figures ?? [];
+    const lines = params.lines && params.lines.rows.length > 0 ? params.lines : null;
+    const extra = children === undefined || children === null || children === false ? null : children;
+    // Only what can fold has a fold button: the fields, the lines and what a kind adds; the figures always show.
+    const foldable = collapsible && (fields.length > 0 || lines !== null || extra !== null);
+    const toggle = () => {
+        const next = !collapsed;
+        setOwnCollapsed(next);
+        onCollapsedChange?.(next);
+    };
+    return (_jsxs("section", { className: cx("nx-domain-card", className), "aria-labelledby": titleId, "aria-busy": busy || undefined, "data-state": dataState, children: [_jsxs("div", { className: "nx-domain-card__head", children: [_jsxs(Heading, { className: "nx-domain-card__title", id: titleId, children: [kind && _jsx("span", { className: "nx-table__tag nx-table__tag--plain nx-domain-card__kind", children: kind }), kind && " ", _jsx("span", { children: params.title })] }), _jsxs("div", { className: "nx-domain-card__status", children: [status, params.state && (_jsx("span", { className: "nx-table__tag nx-domain-card__state", "data-tone": params.state.tone && params.state.tone !== "neutral" ? params.state.tone : undefined, children: params.state.label })), foldable && (_jsx(Button, { variant: "ghost", size: "sm", className: "nx-domain-card__toggle", icon: _jsx(InlineIcon, { icon: collapsed ? iconChevronDown : iconChevronUp }), "aria-expanded": !collapsed, "aria-controls": detailsId, "aria-label": `${collapsed ? "Show" : "Hide"} the details: ${params.title}`, title: collapsed ? "Show the details" : "Hide the details", onClick: toggle }))] }), (params.code || params.subtitle || params.link) && (_jsxs("div", { className: "nx-domain-card__subtitle", children: [_jsxs("span", { title: [params.code, params.subtitle].filter(Boolean).join(" · ") || undefined, children: [params.code && _jsx("span", { className: "nx-domain-card__code", children: params.code }), params.code && params.subtitle && " · ", params.subtitle] }), params.link && (_jsxs("a", { className: "nx-domain-card__link", href: params.link.href, target: params.link.target, rel: params.link.target === "_blank" ? "noopener" : undefined, children: [params.link.label, _jsx(InlineIcon, { icon: iconArrowRight })] }))] }))] }), _jsxs("div", { className: "nx-domain-card__body", hidden: collapsed && figures.length === 0, children: [figures.length > 0 && (_jsx("dl", { className: "nx-domain-card__figures", children: figures.map((figure, index) => (_jsxs("div", { className: "nx-domain-card__figure", "data-tone": figure.tone && figure.tone !== "neutral" ? figure.tone : undefined, children: [_jsx("dt", { children: figure.label }), _jsx("dd", { children: _jsx(DomainFigureValue, { figure: figure, values: values }) }), figure.hint && _jsx("dd", { className: "nx-domain-card__hint", children: figure.hint })] }, `${figure.label}-${index}`))) })), _jsxs("div", { className: "nx-domain-card__details", id: detailsId, hidden: collapsed || (fields.length === 0 && lines === null && extra === null), children: [fields.length > 0 && (_jsx("dl", { className: "nx-domain-card__fields", children: fields.map((field, index) => {
+                                    const text = domainCardValueText(field.value, field.kind, { ...values, currency: field.currency ?? values.currency });
+                                    return (_jsxs("div", { className: "nx-domain-card__field", "data-kind": field.kind ?? "text", "data-empty": text ? undefined : "", children: [_jsx("dt", { children: field.label }), _jsxs("dd", { children: [text || field.empty, field.note && _jsxs("span", { className: "nx-domain-card__note", children: [" \u00B7 ", field.note] })] })] }, `${field.label}-${index}`));
+                                }) })), lines && (_jsxs(_Fragment, { children: [_jsxs("table", { className: "nx-domain-card__lines", children: [_jsx("caption", { className: "nx-visually-hidden", children: lines.label ?? "Lines" }), _jsx("thead", { children: _jsx("tr", { children: lines.columns.map((column, index) => (_jsx("th", { scope: "col", "data-align": alignOf(column.kind, column.align), children: column.label }, `${column.label}-${index}`))) }) }), _jsx("tbody", { children: lines.rows.map((row, rowIndex) => (_jsx("tr", { children: lines.columns.map((column, index) => {
+                                                        const text = domainCardValueText(row[index], column.kind, values);
+                                                        // The first column keeps to one line, cut with "..." on a narrow card: its whole words on hover.
+                                                        return (_jsx("td", { "data-align": alignOf(column.kind, column.align), title: index === 0 && text ? text : undefined, children: text }, index));
+                                                    }) }, rowIndex))) })] }), (lines.more ?? 0) > 0 && _jsxs("p", { className: "nx-domain-card__more", children: ["and ", lines.more, " more"] })] })), extra] })] })] }));
+}
+const alignOf = (kind, align) => align ?? (kind === "number" || kind === "money" || kind === "days" ? "end" : "start");
+/** A figure's parts: the words before it (money's currency), the figure, the words after it (days, a unit). */
+function figureParts(figure, values) {
+    const { value } = figure;
+    if (value === null || value === undefined || value === "" || (typeof value === "number" && !Number.isFinite(value)))
+        return { shown: "-" };
+    if (figure.kind === "money") {
+        const currency = (figure.currency ?? values.currency ?? "").trim();
+        return { before: currency || undefined, shown: domainCardValueText(value, "money", { ...values, currency: null }) };
+    }
+    if (figure.kind === "days") {
+        // "14 days": the same helper as every other days value, its number large and its word small.
+        const text = domainCardValueText(value, "days", values);
+        const space = text.lastIndexOf(" ");
+        return space > 0 ? { shown: text.slice(0, space), after: text.slice(space + 1) } : { shown: text };
+    }
+    return { shown: typeof value === "string" ? value : domainCardValueText(value, "number", values), after: figure.unit };
+}
+/** A figure's value: large, its unit smaller beside it, a real space between them for a screen reader. */
+function DomainFigureValue({ figure, values }) {
+    const { before, shown, after } = figureParts(figure, values);
+    return (_jsxs(_Fragment, { children: [before && _jsx("span", { className: "nx-domain-card__unit", children: before }), before && " ", _jsx("span", { className: "nx-domain-card__value", children: shown }), after && " ", after && _jsx("span", { className: "nx-domain-card__unit", children: after })] }));
+}
+/** A bone on the line of the text it stands for. */
+const Bone = ({ width }) => _jsx("span", { className: "nx-table__bone nx-domain-card__bone", style: { width } });
+/**
+ * The card while it loads: the frame's own parts, each holding its line with a bone, in the shape of the kind's last
+ * card - so when the record lands the thread under it does not move. The record's words name it for a screen reader.
+ */
+function DomainCardHeld({ shape, kind, label, headingLevel, collapsible, collapsed, onCollapsedChange, className }) {
+    const titleId = useId();
+    const detailsId = useId();
+    const Heading = `h${headingLevel}`;
+    const details = shape.fields > 0 || shape.lines > 0;
+    const foldable = collapsible && details;
+    const folded = foldable && collapsed;
+    const columns = Math.max(shape.columns, 1);
+    return (_jsxs("section", { className: cx("nx-domain-card", className), "aria-labelledby": titleId, "aria-busy": "true", "data-state": "loading", children: [_jsxs("div", { className: "nx-domain-card__head", children: [_jsxs(Heading, { className: "nx-domain-card__title", id: titleId, children: [kind && _jsx("span", { className: "nx-table__tag nx-table__tag--plain nx-domain-card__kind", children: kind }), kind && " ", _jsxs("span", { children: [_jsx(Bone, { width: "8rem" }), _jsx("span", { className: "nx-visually-hidden", children: label ? `${label}, loading` : "Loading" })] })] }), _jsxs("div", { className: "nx-domain-card__status", children: [shape.state && _jsx("span", { className: "nx-table__tag nx-table__tag--plain nx-domain-card__bone-tag", "aria-hidden": "true" }), foldable && (_jsx(Button, { variant: "ghost", size: "sm", className: "nx-domain-card__toggle", icon: _jsx(InlineIcon, { icon: folded ? iconChevronDown : iconChevronUp }), "aria-expanded": !folded, "aria-controls": detailsId, "aria-label": `${folded ? "Show" : "Hide"} the details`, title: folded ? "Show the details" : "Hide the details", onClick: () => onCollapsedChange(!folded) }))] }), shape.subtitle && (_jsxs("div", { className: "nx-domain-card__subtitle", "aria-hidden": "true", children: [_jsx("span", { children: _jsx(Bone, { width: "10rem" }) }), shape.link && (_jsx("span", { className: "nx-domain-card__link", children: _jsx(Bone, { width: "7rem" }) }))] }))] }), _jsxs("div", { className: "nx-domain-card__body", hidden: folded && shape.figures === 0, "aria-hidden": "true", children: [shape.figures > 0 && (_jsx("dl", { className: "nx-domain-card__figures", children: Array.from({ length: shape.figures }, (_, index) => (_jsxs("div", { className: "nx-domain-card__figure", children: [_jsx("dt", { children: _jsx(Bone, { width: "3.5rem" }) }), _jsx("dd", { children: _jsx("span", { className: "nx-domain-card__value", children: _jsx(Bone, { width: "2.5rem" }) }) }), shape.hints.includes(index) && (_jsx("dd", { className: "nx-domain-card__hint", children: _jsx(Bone, { width: "5rem" }) }))] }, index))) })), _jsxs("div", { className: "nx-domain-card__details", id: detailsId, hidden: folded || !details, children: [shape.fields > 0 && (_jsx("dl", { className: "nx-domain-card__fields", children: Array.from({ length: shape.fields }, (_, index) => (_jsxs("div", { className: "nx-domain-card__field", children: [_jsx("dt", { children: _jsx(Bone, { width: "3.5rem" }) }), _jsx("dd", { children: _jsx(Bone, { width: "6rem" }) })] }, index))) })), shape.lines > 0 && (_jsxs(_Fragment, { children: [_jsxs("table", { className: "nx-domain-card__lines", children: [_jsx("thead", { children: _jsx("tr", { children: Array.from({ length: columns }, (_, index) => (_jsx("th", { children: _jsx(Bone, { width: "3rem" }) }, index))) }) }), _jsx("tbody", { children: Array.from({ length: shape.lines }, (_, row) => (_jsx("tr", { children: Array.from({ length: columns }, (_, index) => (_jsx("td", { children: _jsx(Bone, { width: index === 0 ? "7rem" : "2.5rem" }) }, index))) }, row))) })] }), shape.more && (_jsx("p", { className: "nx-domain-card__more", children: _jsx(Bone, { width: "5rem" }) }))] }))] })] })] }));
+}
+/** A record named by its kind and its words, with nothing read: a message about a kind with no card. */
+export function DomainLine({ kind, label, className }) {
+    if (!kind && !label)
+        return null;
+    return (_jsxs("p", { className: cx("nx-domain-line", className), children: [kind && _jsx("span", { className: "nx-table__tag nx-table__tag--plain", children: kind }), kind && label && " ", label && _jsx("span", { className: "nx-domain-line__label", children: label })] }));
+}

package/dist/Components/Forms/ApiForm.js

@@ -39,6 +39,10 @@ export function ApiForm(props) {
     const latest = useRef(props);
     latest.current = props;
     const answerRef = useRef(null);
+    // What the save that answered sent: the values and the body made of them, for `onSuccess`.
+    const sentRef = useRef(null);
+    // The body the question before a save showed (`confirm`), and the submit it is for.
+    const keptRef = useRef(null);
     const [load, setLoad] = useState(() => (loadValue ? { state: "loading" } : { state: "done" }));
     const [attempt, setAttempt] = useState(0);
     useEffect(() => {
@@ -59,11 +63,25 @@ export function ApiForm(props) {
         });
         return () => controller.abort();
     }, [store, attempt]);
+    /**
+     * With `confirm`, the body is made once, before the question, so the question shows exactly what is sent: kept with
+     * the submit it was made for, and sent by that submit alone. Without `confirm` nothing calls this.
+     */
+    async function makeBody(values, context) {
+        keptRef.current = null;
+        const { transform } = latest.current;
+        const body = transform ? await transform(values, context) : values;
+        keptRef.current = { context, body };
+        return body;
+    }
     async function send(values, context) {
         // No `readResponse` means the client's own reader: the app's (`configureApi({ read })`), else the built-in one.
         const { api, transform, readResponse } = latest.current;
         answerRef.current = null;
-        const body = transform ? await transform(values, context) : values;
+        sentRef.current = null;
+        const kept = keptRef.current;
+        keptRef.current = null;
+        const body = kept && kept.context === context ? kept.body : transform ? await transform(values, context) : values;
         let answer;
         if (typeof api === "function")
             answer = await toApiResult(await api(body, context), readResponse ?? getApiReader() ?? readApiResponse);
@@ -76,6 +94,7 @@ export function ApiForm(props) {
         }
         if (answer.ok) {
             answerRef.current = answer;
+            sentRef.current = { values, body };
             return { ok: true };
         }
         latest.current.onError?.(answer, values);
@@ -91,10 +110,12 @@ export function ApiForm(props) {
         const endpoint = isApiEndpoint(api) ? api : undefined;
         if (successMessage !== false)
             toast.success(successMessage ?? answer?.message ?? messages.success(endpoint?.action ?? "save", endpoint?.subject));
-        onSuccess?.(answer?.result, values, store);
+        onSuccess?.(answer?.result, values, store, sentRef.current ?? { values, body: values });
     }
     if (load.state === "failed") {
         return (_jsxs("div", { className: cx("nx-form-load-failed", rest.className), style: rest.style, role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsxs("p", { children: [_jsx("strong", { children: "Could not load the values." }), " ", load.message] }), _jsxs("div", { className: "nx-form-load-failed__actions", children: [rest.onCancel && (_jsx(Button, { size: "sm", onClick: rest.onCancel, children: rest.cancelLabel ?? "Cancel" })), _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => setAttempt(count => count + 1), children: "Retry" })] })] }));
     }
-    return _jsx(SubmitForm, { ...rest, form: store, loading: Boolean(rest.loading) || load.state === "loading", onSubmit: send, onSaved: saved });
+    // `makeBody` is the package's own hand-over to its SubmitForm, not a prop of SubmitForm's.
+    const internals = { makeBody };
+    return _jsx(SubmitForm, { ...rest, ...internals, form: store, loading: Boolean(rest.loading) || load.state === "loading", onSubmit: send, onSaved: saved });
 }

package/dist/Components/Forms/Crud.d.ts

@@ -1,5 +1,5 @@
 import type { CrudProps } from "../../Interfaces/CrudInterfaces.ts";
-import type { FormValues } from "../../Interfaces/FormInterfaces.ts";
+import { type FormValues } from "../../Interfaces/FormInterfaces.ts";
 /**
  * A CRUD page in one component: a data table of a controller's records with its lists, Add and Edit popups, details,
  * and actions on one record or many, each shown only when its endpoint exists and the user may call it.
@@ -14,4 +14,4 @@ import type { FormValues } from "../../Interfaces/FormInterfaces.ts";
  *   paging="server"
  * />
  */
-export declare function Crud<TRow extends FormValues = FormValues>(props: CrudProps<TRow>): import("react").JSX.Element;
+export declare function Crud<TRow extends FormValues = FormValues>(given: CrudProps<TRow>): import("react").JSX.Element;