@sincpro/web-framework 0.0.0-stage → 0.1.0

package/dist/react/context.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { metaStore } from "../core/metas.js";
+import { createContext, useContext, useMemo, useState } from "react";
+const FrameworkContext = createContext(null);
+export function FrameworkProvider({ transport, locale, metas: seed, children, }) {
+    // One store for the provider's life: a new seed object on a re-render must not forget what
+    // the screens already learned.
+    const [metas] = useState(() => metaStore(seed));
+    const value = useMemo(() => ({ transport, locale, metas }), [transport, locale, metas]);
+    return _jsx(FrameworkContext.Provider, { value: value, children: children });
+}
+export function useFramework() {
+    const value = useContext(FrameworkContext);
+    if (value === null)
+        throw new Error("useFramework outside a FrameworkProvider");
+    return value;
+}

package/dist/react/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The state of a list and a record and the gestures that drive them. It draws nothing — no
+ * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
+ * keeps it that way.
+ */
+export { FrameworkProvider, useFramework } from "./context.js";
+export { type CommandState, type Rehearsal, useCommand, } from "./useCommand.js";
+export { useHistory } from "./useHistory.js";
+export { type Listing, type ListingOptions, type Paging, useListing, } from "./useListing.js";
+export { type Lookup, useLookup } from "./useLookup.js";
+export { type Advice, type Editing, type RecordReading, type RecordState, useRecord, } from "./useRecord.js";
+export { useRelated } from "./useRelated.js";

package/dist/react/index.js

@@ -0,0 +1,12 @@
+/**
+ * The state of a list and a record and the gestures that drive them. It draws nothing — no
+ * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
+ * keeps it that way.
+ */
+export { FrameworkProvider, useFramework } from "./context.js";
+export { useCommand, } from "./useCommand.js";
+export { useHistory } from "./useHistory.js";
+export { useListing, } from "./useListing.js";
+export { useLookup } from "./useLookup.js";
+export { useRecord, } from "./useRecord.js";
+export { useRelated } from "./useRelated.js";

package/dist/react/useCommand.d.ts

@@ -0,0 +1,28 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import { type Entity } from "../core/entity.js";
+/**
+ * One Command of an entity: run it, or ask first what it would do.
+ *
+ * Context: sincpro_framework runs a Command dry when it carries `dry_run: true` (a
+ * `DryRunnable`): the handler's `preview` answers what it WOULD do — «provider odoo deletes
+ * env-42; its record and history stay» — and nothing is touched. That is the confirmation a
+ * destructive action deserves: not «are you sure?», but what is about to happen. forge's
+ * console had the backend for it and no screen that asked.
+ *
+ * One at a time: `busy` turns the button off, because a payment sent twice is two payments.
+ */
+export type Rehearsal = {
+    text: string;
+    data: Record<string, unknown>;
+};
+export type CommandState<R> = {
+    run: (id?: string, body?: AnyRecord) => Promise<R | undefined>;
+    /** The dry run: what it would do, nothing touched. */
+    rehearse: (id?: string, body?: AnyRecord) => Promise<Rehearsal | undefined>;
+    busy: boolean;
+    error: unknown;
+    /** The last dry run's answer, until `reset`. */
+    rehearsal: Rehearsal | null;
+    reset: () => void;
+};
+export declare function useCommand<T extends AnyRecord, R = unknown>(entity: Entity<T>, name: string): CommandState<R>;

package/dist/react/useCommand.js

@@ -0,0 +1,52 @@
+"use client";
+import { pathFor } from "../core/entity.js";
+import { useFramework } from "./context.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+export function useCommand(entity, name) {
+    const { transport } = useFramework();
+    const route = entity.commands[name];
+    if (route === undefined)
+        throw new Error(`${entity.key} declares no command "${name}"`);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [rehearsal, setRehearsal] = useState(null);
+    // A Command is never aborted once sent — the server may have done it — but its answer must
+    // not land on a screen that left.
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => void (mounted.current = false);
+    }, []);
+    const send = useCallback(async (id, body) => {
+        setBusy(true);
+        setError(null);
+        try {
+            return await transport.send(route.method, pathFor(route, id), body);
+        }
+        catch (failure) {
+            if (mounted.current)
+                setError(failure);
+            return undefined;
+        }
+        finally {
+            if (mounted.current)
+                setBusy(false);
+        }
+    }, [transport, route]);
+    return {
+        run: (id, body = {}) => send(id, body),
+        rehearse: async (id, body = {}) => {
+            const answer = await send(id, { ...body, dry_run: true });
+            if (answer !== undefined && mounted.current)
+                setRehearsal(answer);
+            return answer;
+        },
+        busy,
+        error,
+        rehearsal,
+        reset: () => {
+            setRehearsal(null);
+            setError(null);
+        },
+    };
+}

package/dist/react/useHistory.d.ts

@@ -0,0 +1,5 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import { type HistoryEntry } from "../core/history.js";
+import { type DependencyList } from "react";
+export declare function useHistory<T extends AnyRecord>(entity: Entity<T>, id: string, deps?: DependencyList): HistoryEntry[] | undefined;

package/dist/react/useHistory.js

@@ -0,0 +1,41 @@
+"use client";
+import { historyOf } from "../core/history.js";
+import { useFramework } from "./context.js";
+import { useEffect, useState } from "react";
+/**
+ * A record's business events, newest first — what `Record.Activity` draws.
+ *
+ * Context: the history of a record is a criteria over its context's events — `entity_type`
+ * and `entity_id` — so it is read like any list, with the same transport. `undefined` while it
+ * is not read, or when it cannot be: an empty history says «nothing happened», which is a
+ * different claim from «you may not see it». Pass the record among `deps` so a write that
+ * reloads it reads its new facts too.
+ *
+ * Named after sincpro_framework's `history_of`; web-ui's `useActivity` is something else (the
+ * panel's open state).
+ */
+const SHOWN = 100;
+export function useHistory(entity, id, deps = []) {
+    const { transport, locale } = useFramework();
+    const [entries, setEntries] = useState(undefined);
+    const history = entity.history;
+    useEffect(() => {
+        if (history === undefined)
+            return;
+        const aborter = new AbortController();
+        const criteria = {
+            where: {
+                all: [
+                    { field: "entity_type", operator: "=", value: history.type },
+                    { field: "entity_id", operator: "=", value: id },
+                ],
+            },
+            order: [{ field: "created_at", descending: true }],
+            pagination: { limit: SHOWN },
+        };
+        transport.list(history.route, criteria, aborter.signal).then((page) => aborter.signal.aborted || setEntries(historyOf(page.rows, page.meta, locale)), () => aborter.signal.aborted || setEntries(undefined));
+        return () => aborter.abort();
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- the caller names what reloads it
+    }, [transport, history, id, locale, ...deps]);
+    return entries;
+}

package/dist/react/useListing.d.ts

@@ -0,0 +1,75 @@
+import { type AnyRecord, type Count, type Criteria, type Dropped, type Expression, type Meta, type ReadingStatus, type Sort } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+/**
+ * N records of an entity, live: what a list draws and the gestures that drive it.
+ *
+ * Context: `useReading` from `@sincpro/criteria-react` already owns the hard rules — the
+ * definition asked for once, the stale answer dropped, the cursor never seen. What a screen
+ * still wrote by hand around it (forge's `listState`, `More`, the search box, the order) is
+ * the same on every list, so it lives here. Three things narrow the reading, and they AND:
+ *
+ *     search(text)   the entity's own search template (`meta.search`), as the server fills it
+ *     filter(where)  what a search bar or a criteria builder put — any depth of all/any/negate
+ *     orderBy(sort)  the order, asked of the SERVER: a page sorted locally lies about page two
+ *
+ * All three refine the same reading instead of starting another. It holds state and draws
+ * nothing: `EntityList` draws it, and a screen that needs another shape draws it itself.
+ */
+export type Listing<T> = {
+    entity: Entity<T & AnyRecord>;
+    rows: T[];
+    meta: Meta | null;
+    count: Count | null;
+    dropped: Dropped[];
+    status: ReadingStatus;
+    error: unknown;
+    hasMore: boolean;
+    locale: string | undefined;
+    more: () => void;
+    reload: () => void;
+    /** What was typed in the search box. */
+    text: string;
+    /** Debounced: a request per pause, not per keystroke. */
+    search: (text: string) => void;
+    /** What the search bar put; `undefined` is nothing. */
+    where: Expression<T> | undefined;
+    filter: (where: Expression<T> | undefined) => void;
+    /** The order the server was asked for; `null` is the entity's own default. */
+    order: Sort | null;
+    orderBy: (order: Sort | null) => void;
+    /** How the set is walked: a page at a time, or «load more» up to a ceiling. */
+    paging: Paging;
+    /** Where the page on screen is — `pages` mode. `from`/`to` count from 1. */
+    page: {
+        index: number;
+        size: number;
+        from: number;
+        to: number;
+        hasPrev: boolean;
+        hasNext: boolean;
+    };
+    next: () => void;
+    prev: () => void;
+    /** `more` mode reached its ceiling: refine the search instead of loading on. */
+    capped: boolean;
+};
+/**
+ * - `pages`: one page on screen at a time, walked by the server's own cursor (keyset — no
+ *   `offset`, so page 4 000 costs what page 1 costs). The DOM holds one page: a set of millions
+ *   never freezes the screen. The default.
+ * - `more`: «load more» appends — natural for short sets, a feed — up to `maxRows`; past it the
+ *   list asks to narrow the search instead of growing the page until it freezes.
+ */
+export type Paging = "pages" | "more";
+export type ListingOptions<T> = {
+    /** The route's own parameters: `{ tenant_id: "acme" }` → `/projects?tenant_id=acme`. */
+    params?: Readonly<Record<string, string>>;
+    /** What this list always asks — a scope. Search, filter and order AND it. */
+    criteria?: Criteria<T>;
+    paging?: Paging;
+    /** Rows per page (or per «load more»). 50 by default; the server's own default too. */
+    pageSize?: number;
+    /** `more` mode: the most rows ever on screen. 500 by default. */
+    maxRows?: number;
+};
+export declare function useListing<T extends AnyRecord>(entity: Entity<T>, options?: ListingOptions<T>): Listing<T>;

package/dist/react/useListing.js

@@ -0,0 +1,121 @@
+"use client";
+import { merge, resource, resumingFrom, searchOver, } from "@sincpro/criteria";
+import { useReading } from "@sincpro/criteria-react";
+import { useFramework } from "./context.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+/** How long typing has to pause before the search goes out. */
+const TYPING_PAUSE = 200;
+function routeOf(list, params) {
+    const query = new URLSearchParams(Object.entries(params ?? {}).filter(([, value]) => value !== "")).toString();
+    if (query === "")
+        return list;
+    return `${list}${list.includes("?") ? "&" : "?"}${query}`;
+}
+export function useListing(entity, options = {}) {
+    const { transport, locale, metas } = useFramework();
+    const route = routeOf(entity.list, options.params);
+    const source = useMemo(() => resource((criteria, signal) => transport.list(route, criteria, signal)), [transport, route]);
+    // Decided once, at mount: a definition already known means the server is not asked for it
+    // again. Deciding it later would change the criteria and restart the reading.
+    const [preloaded] = useState(() => metas.get(entity.key));
+    const paging = options.paging ?? "pages";
+    const size = options.pageSize ?? options.criteria?.pagination?.limit ?? 50;
+    const maxRows = options.maxRows ?? 500;
+    const asked = {
+        ...options.criteria,
+        pagination: { ...options.criteria?.pagination, limit: size },
+    };
+    const base = preloaded ? { ...asked, meta: false } : asked;
+    const reading = useReading(source, base);
+    // `pages` mode: the cursor that opens each page walked so far — page 0 opens with none.
+    const [cursors, setCursors] = useState([null]);
+    // The definition is kept across refinements: a refine in flight must not blank the columns.
+    const known = useRef(preloaded ?? null);
+    if (reading.meta && reading.meta !== known.current) {
+        known.current = reading.meta;
+        metas.set(entity.key, reading.meta);
+    }
+    const meta = reading.meta ?? known.current;
+    const [narrowing, setNarrowing] = useState({
+        text: "",
+        where: undefined,
+        order: null,
+    });
+    const typing = useRef(null);
+    useEffect(() => () => void (typing.current && clearTimeout(typing.current)), []);
+    const narrowed = (next) => {
+        let criteria = base;
+        const found = searchOver(meta, next.text);
+        if (found !== undefined)
+            criteria = merge(criteria, { where: found });
+        if (next.where !== undefined)
+            criteria = merge(criteria, { where: next.where });
+        if (next.order !== null)
+            criteria = merge(criteria, { order: [next.order] });
+        return criteria;
+    };
+    const refine = useCallback((next) => {
+        // Another question starts on its first page: a cursor belongs to one order and one filter.
+        setCursors([null]);
+        void reading.refine(narrowed(next));
+    }, 
+    // `base` is the caller's literal: its identity changes every render, its content does not.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [reading.refine, meta]);
+    const index = cursors.length - 1;
+    const turn = (to) => {
+        setCursors(to);
+        void reading.refine(resumingFrom(narrowed(narrowing), to[to.length - 1] ?? null));
+    };
+    const capped = paging === "more" && reading.rows.length >= maxRows;
+    const narrow = (change, debounce) => {
+        const next = { ...narrowing, ...change };
+        setNarrowing(next);
+        if (typing.current)
+            clearTimeout(typing.current);
+        if (debounce)
+            typing.current = setTimeout(() => refine(next), TYPING_PAUSE);
+        else
+            refine(next);
+    };
+    return {
+        entity,
+        rows: reading.rows,
+        meta,
+        count: reading.count,
+        dropped: reading.dropped,
+        status: reading.status,
+        error: reading.error,
+        hasMore: paging === "more" && reading.hasMore && !capped,
+        locale,
+        more: () => {
+            if (paging === "more" && !capped)
+                void reading.more();
+        },
+        reload: () => void reading.reload(),
+        text: narrowing.text,
+        search: (text) => narrow({ text }, true),
+        where: narrowing.where,
+        filter: (where) => narrow({ where }, false),
+        order: narrowing.order,
+        orderBy: (order) => narrow({ order }, false),
+        paging,
+        page: {
+            index,
+            size,
+            from: reading.rows.length === 0 ? 0 : index * size + 1,
+            to: index * size + reading.rows.length,
+            hasPrev: paging === "pages" && index > 0,
+            hasNext: paging === "pages" && reading.cursor !== null,
+        },
+        next: () => {
+            if (paging === "pages" && reading.cursor !== null)
+                turn([...cursors, reading.cursor]);
+        },
+        prev: () => {
+            if (paging === "pages" && index > 0)
+                turn(cursors.slice(0, -1));
+        },
+        capped,
+    };
+}

package/dist/react/useLookup.d.ts

@@ -0,0 +1,22 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import { type LookupOption } from "../core/lookup.js";
+/**
+ * The records of an entity as choices — the literal search of a many2one.
+ *
+ * Context: it is a listing like any other — the entity's own search template fills with what
+ * is typed, debounced, asked of the server — whose rows are read as choices (`lookupOf`). One
+ * page at a time: a select over ten thousand customers loads the first page and the next on
+ * demand, never the table.
+ */
+export type Lookup = {
+    options: LookupOption[];
+    text: string;
+    search: (text: string) => void;
+    loading: boolean;
+    hasMore: boolean;
+    more: () => void;
+};
+export declare function useLookup<T extends AnyRecord>(entity: Entity<T>, options?: {
+    pageSize?: number;
+}): Lookup;

package/dist/react/useLookup.js

@@ -0,0 +1,15 @@
+"use client";
+import { lookupOf } from "../core/lookup.js";
+import { useListing } from "./useListing.js";
+export function useLookup(entity, options = {}) {
+    // «More», not pages: a choice list grows downwards, and its ceiling keeps it light.
+    const listing = useListing(entity, { paging: "more", pageSize: options.pageSize ?? 50 });
+    return {
+        options: lookupOf(listing.meta, listing.rows),
+        text: listing.text,
+        search: listing.search,
+        loading: listing.status === "loading",
+        hasMore: listing.hasMore,
+        more: listing.more,
+    };
+}

package/dist/react/useRecord.d.ts

@@ -0,0 +1,74 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+import { type FieldState } from "../core/edit.js";
+import { type Entity } from "../core/entity.js";
+import { type Draft } from "../core/transport.js";
+/**
+ * ONE record of an entity, with the definition of its model — read, and edited.
+ *
+ * Context: forge's console wrote the reading as `useAnswer` and never edited at all, though its
+ * backend had an update route: editing by hand (dirty state, save, discard, conflicts) cost more
+ * than the screen was worth. Here it is the same object:
+ *
+ *   - **reading** — the record and its meta travel together (sincpro_framework's
+ *     `ResponseRecord`); an answer that arrives after the view moved on is dropped.
+ *   - **editing** — `set` keeps what is typed apart from the record; each field's state comes
+ *     from the model's hints evaluated over what is on screen (`fieldStateOf`), refined by the
+ *     server's `Preview` when the entity has one (computed values, states, advice).
+ *   - **saving** — only what changed travels, with the version that was read: if someone saved
+ *     in between, the server answers 409 and the screen says so instead of overwriting.
+ *   - **drafts** — an edit kept between requests (sincpro_framework's `Drafts`) comes back with
+ *     the record and is shown as restored; `keep()` stores the current one.
+ */
+export type RecordState<T> = {
+    status: "loading";
+    record: null;
+    meta: Meta | null;
+    error: null;
+} | {
+    status: "ready";
+    record: T;
+    meta: Meta | null;
+    error: null;
+} | {
+    status: "failed";
+    record: null;
+    meta: Meta | null;
+    error: unknown;
+};
+export type Advice = {
+    field?: string;
+    text: string;
+};
+export type Editing = {
+    /** The record as on screen: what was read, what the server computed, what was typed. */
+    values: AnyRecord;
+    changed: AnyRecord;
+    dirty: boolean;
+    set: (name: string, value: unknown) => void;
+    state: (name: string) => FieldState;
+    /** The server's word on fields that did not validate, by field. */
+    errors: Record<string, string>;
+    advice: Advice[];
+    /** Required, visible, editable and empty: what blocks a save. */
+    missing: string[];
+    saving: boolean;
+    /** The last save's refusal, when it was not a conflict. */
+    failure: unknown;
+    /** Someone saved after this was read: nothing was overwritten. */
+    conflict: boolean;
+    /** The values came back from a kept draft. */
+    restored: boolean;
+    /** The draft this caller keeps on the server, when there is one. */
+    draft: Draft | null;
+    save: () => Promise<boolean>;
+    discard: () => void;
+    /** Store the current edit as a draft — only when the entity declares where. */
+    keep?: () => Promise<void>;
+};
+export type RecordReading<T> = RecordState<T> & {
+    entity: Entity<T & AnyRecord>;
+    locale: string | undefined;
+    reload: () => void;
+    edit: Editing;
+};
+export declare function useRecord<T extends AnyRecord>(entity: Entity<T>, id: string): RecordReading<T>;

package/dist/react/useRecord.js

@@ -0,0 +1,176 @@
+"use client";
+import { changesOf, errorsByField, fieldStateOf, missingOf, } from "../core/edit.js";
+import { pathFor } from "../core/entity.js";
+import { TransportError } from "../core/transport.js";
+import { useFramework } from "./context.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+/** How long typing has to pause before the server is asked what the record becomes. */
+const PREVIEW_PAUSE = 300;
+export function useRecord(entity, id) {
+    const { transport, locale, metas } = useFramework();
+    const [state, setState] = useState({
+        status: "loading",
+        record: null,
+        meta: null,
+        error: null,
+    });
+    const [round, setRound] = useState(0);
+    const [typed, setTyped] = useState({});
+    const [computed, setComputed] = useState({});
+    const [fromServer, setFromServer] = useState({});
+    const [advice, setAdvice] = useState([]);
+    const [saving, setSaving] = useState(false);
+    const [failure, setFailure] = useState(null);
+    const [conflict, setConflict] = useState(false);
+    const [draft, setDraft] = useState(null);
+    const pause = useRef(null);
+    // The preview in flight. A newer one cancels it, and so do a save, a discard and leaving:
+    // an answer about values that are no longer on screen must never land on them.
+    const asking = useRef(null);
+    const mounted = useRef(true);
+    const cancelPreview = () => {
+        if (pause.current)
+            clearTimeout(pause.current);
+        asking.current?.abort();
+        asking.current = null;
+    };
+    const forget = () => {
+        cancelPreview();
+        setTyped({});
+        setComputed({});
+        setFromServer({});
+        setAdvice([]);
+        setFailure(null);
+        setConflict(false);
+    };
+    useEffect(() => {
+        const aborter = new AbortController();
+        setState((now) => ({ status: "loading", record: null, meta: now.meta, error: null }));
+        transport.one(entity.one(id), aborter.signal).then((answer) => {
+            if (answer.meta)
+                metas.set(entity.key, answer.meta);
+            if (aborter.signal.aborted)
+                return;
+            forget();
+            setDraft(answer.draft);
+            if (answer.draft)
+                setTyped(answer.draft.values);
+            setState({
+                status: "ready",
+                record: answer.record,
+                meta: answer.meta ?? metas.get(entity.key) ?? null,
+                error: null,
+            });
+        }, (error) => {
+            if (!aborter.signal.aborted)
+                setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
+        });
+        return () => aborter.abort();
+        // `forget` only resets this hook's own state; listing it would reload the record on every
+        // render. What reloads it is the transport, the entity, the id or an explicit `reload()`.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [transport, metas, entity, id, round]);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            cancelPreview();
+        };
+    }, []);
+    const reload = useCallback(() => setRound((n) => n + 1), []);
+    const record = useMemo(() => (state.record ?? {}), [state.record]);
+    const values = useMemo(() => ({ ...record, ...computed, ...typed }), [record, computed, typed]);
+    const changed = useMemo(() => changesOf(record, typed), [record, typed]);
+    const version = record["version"];
+    const ask = (next, name) => {
+        const preview = entity.preview;
+        if (preview === undefined)
+            return;
+        cancelPreview();
+        pause.current = setTimeout(() => {
+            const aborter = new AbortController();
+            asking.current = aborter;
+            transport
+                .send(preview.method, pathFor(preview, id), { id, values: changesOf(record, next), changed: [name] }, aborter.signal)
+                .then((answer) => {
+                if (aborter.signal.aborted || !mounted.current)
+                    return;
+                setComputed(answer.values ?? {});
+                setFromServer(answer.fields ?? {});
+                setAdvice(answer.advice ?? []);
+            }, () => undefined);
+        }, PREVIEW_PAUSE);
+    };
+    const refused = (error) => {
+        if (error instanceof TransportError && error.problem?.kind === "conflict")
+            setConflict(true);
+        else
+            setFailure(error);
+    };
+    const edit = {
+        values,
+        changed,
+        dirty: Object.keys(changed).length > 0,
+        set: (name, value) => {
+            const next = { ...typed, [name]: value };
+            setTyped(next);
+            ask(next, name);
+        },
+        state: (name) => fieldStateOf(state.meta, name, values, fromServer),
+        errors: failure instanceof TransportError ? errorsByField(failure.problem?.errors) : {},
+        advice,
+        missing: missingOf(state.meta, values, fromServer),
+        saving,
+        failure,
+        conflict,
+        restored: draft !== null && Object.keys(changed).length > 0,
+        draft,
+        save: async () => {
+            const route = entity.save;
+            if (route === undefined)
+                throw new Error(`${entity.key} declares no save route`);
+            cancelPreview();
+            setSaving(true);
+            setFailure(null);
+            try {
+                await transport.send(route.method, pathFor(route, id), {
+                    ...changed,
+                    ...(version === undefined ? {} : { version }),
+                });
+                setDraft(null);
+                reload();
+                return true;
+            }
+            catch (error) {
+                // A write is never aborted — the server may have done it — but an answer that comes
+                // back after the screen left lands nowhere.
+                if (mounted.current)
+                    refused(error);
+                return false;
+            }
+            finally {
+                if (mounted.current)
+                    setSaving(false);
+            }
+        },
+        discard: forget,
+        ...(entity.draft === undefined
+            ? {}
+            : {
+                keep: async () => {
+                    const route = entity.draft;
+                    try {
+                        const kept = await transport.send(route.method, pathFor(route, id), {
+                            values: changed,
+                            expected: draft?.version ?? 0,
+                        });
+                        setDraft(kept);
+                    }
+                    catch (error) {
+                        refused(error);
+                    }
+                },
+            }),
+    };
+    return { ...state, entity, locale, reload, edit };
+}