@svgrid/enterprise 3.1.21 → 3.1.23

package/dist/review/model.svelte.js

@@ -0,0 +1,883 @@
+import { nudgeEnterprise } from '../license.js';
+import { clusterProposals } from './cluster.js';
+import { sameValue } from './equal.js';
+import { FLASH_BG, pendingFormats, CONFLICT_BG, CONFLICT_ICON } from './formats.js';
+import { hasPending, stripPending, trackPendingSource, withPending } from './pending-filter.js';
+import { registerCardMarks } from './card-marks.svelte.js';
+import { registerRichCellMarks } from './rich-cells.js';
+import { fill, reviewMessages } from './messages.js';
+import { showValue } from './cluster.js';
+import { wrapColumns } from './ghost.js';
+const STATUSES = new Set(['pending', 'accepted', 'rejected', 'stale', 'conflict']);
+const SOURCE_KINDS = new Set(['agent', 'ai', 'import', 'bulk', 'sync', 'rule', 'user']);
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+/**
+ * An export, checked before it is trusted: it may come from another person,
+ * another session or an agent. A wrong shape throws; a malformed proposal is
+ * dropped and counted.
+ */
+function checkExport(json) {
+    const root = json;
+    if (!root || typeof root !== 'object' || root.v !== 1 || !Array.isArray(root.sets)) {
+        throw new Error('[svgrid review] not a change review export (expected { v: 1, sets: [...] })');
+    }
+    let dropped = 0;
+    const sets = [];
+    for (const raw of root.sets) {
+        const set = raw;
+        const src = set?.source;
+        if (!set || !isStr(set.id) || !Array.isArray(set.proposals) || !src || !isStr(src.id) || !SOURCE_KINDS.has(src.kind)) {
+            throw new Error('[svgrid review] a set in the export has no id, source or proposals');
+        }
+        const source = { kind: src.kind, id: src.id, label: typeof src.label === 'string' ? src.label : src.id };
+        const proposals = [];
+        for (const p of set.proposals) {
+            const rowId = typeof p?.rowId === 'number' ? String(p.rowId) : p?.rowId;
+            if (!p || !isStr(p.id) || !isStr(rowId) || !isStr(p.field) || !STATUSES.has(p.status)) {
+                dropped++;
+                continue;
+            }
+            proposals.push({
+                id: p.id, op: 'update', rowId, field: p.field, before: p.before, after: p.after, source,
+                reason: typeof p.reason === 'string' ? p.reason : undefined,
+                confidence: typeof p.confidence === 'number' && p.confidence >= 0 && p.confidence <= 1 ? p.confidence : undefined,
+                createdAt: typeof p.createdAt === 'number' ? p.createdAt : Date.now(),
+                status: p.status,
+                note: typeof p.note === 'string' ? p.note : undefined,
+                decidedBy: typeof p.decidedBy === 'string' ? p.decidedBy : undefined,
+                decidedAt: typeof p.decidedAt === 'number' ? p.decidedAt : undefined,
+            });
+        }
+        sets.push({ id: set.id, title: typeof set.title === 'string' ? set.title : source.label, source, createdAt: typeof set.createdAt === 'number' ? set.createdAt : Date.now(), proposals });
+    }
+    return { sets, dropped };
+}
+let uid = 0;
+const nextId = (prefix) => `${prefix}${Date.now().toString(36)}-${(uid++).toString(36)}`;
+const SEP = '\u0000';
+const cellKey = (rowId, field) => rowId + SEP + field;
+export function createReview(opts) {
+    if (!opts.setRows && !opts.server)
+        throw new Error('[svgrid review] pass setRows (client data) or server (server row model)');
+    if (opts.server && !opts.onCommit)
+        throw new Error('[svgrid review] onCommit is required with a server row model');
+    const msg = reviewMessages(opts.messages);
+    // Without a key: watermark and a one-time nudge. The review still runs.
+    nudgeEnterprise('Change review');
+    // Proposed values beside rich cells (selects, ratings): registered by the
+    // first review, so grids in apps without one keep the plain fast path.
+    registerRichCellMarks();
+    const all = new Map();
+    const sets = new Map();
+    /** Live proposals (pending or in conflict) per cell. */
+    const byCell = new Map();
+    const inFlight = new Set();
+    /** Decision order for the log: timestamps tie within one millisecond. */
+    const decidedOrder = new Map();
+    let lastError = $state(null);
+    function failed(error, during) {
+        lastError = { error, during, at: Date.now() };
+        opts.onError?.(error, during);
+    }
+    let decisionSeq = 0;
+    const stamp = (p) => decidedOrder.set(p.id, ++decisionSeq);
+    let version = $state(0);
+    // "Only rows with changes": our node ANDed onto the advanced filter. Put on
+    // again after every change so the grid filters with the new pending set.
+    const filterToken = nextId('rv-');
+    let pendingOnly = $state(false);
+    let filterNonce = 0;
+    let pendingRows = null;
+    const pendingSource = { hasPendingRow: (rowId) => hasPendingRow(rowId) };
+    function hasPendingRow(rowId) {
+        if (pendingRows?.v !== version) {
+            const ids = new Set();
+            for (const p of all.values())
+                if (p.status === 'pending' || p.status === 'conflict')
+                    ids.add(p.rowId);
+            pendingRows = { v: version, ids };
+        }
+        return pendingRows.ids.has(rowId);
+    }
+    function applyPendingFilter() {
+        const api = getApi();
+        if (!api)
+            return;
+        const current = api.getAdvancedFilter();
+        // The user's own filter tools may have dropped the node: then the toggle is off.
+        if (filterNonce > 0 && !hasPending(current)) {
+            pendingOnly = false;
+            return;
+        }
+        api.setAdvancedFilter(withPending(current, filterToken, ++filterNonce));
+    }
+    const bump = () => {
+        version += 1;
+        if (pendingOnly)
+            applyPendingFilter();
+    };
+    /**
+     * Show only rows with a pending or conflicting proposal, on top of the
+     * user's own filters; off takes our condition back out and leaves theirs.
+     * Rows leave the view as their proposals are decided.
+     */
+    function showPendingOnly(on) {
+        const api = getApi();
+        if (!api)
+            return;
+        if (on) {
+            trackPendingSource(filterToken, pendingSource);
+            filterNonce = 0;
+            pendingOnly = true;
+            api.setAdvancedFilter(withPending(api.getAdvancedFilter(), filterToken, ++filterNonce));
+        }
+        else {
+            pendingOnly = false;
+            api.setAdvancedFilter(stripPending(api.getAdvancedFilter()));
+        }
+    }
+    const getApi = () => (typeof opts.api === 'function' ? opts.api() : opts.api) ?? null;
+    function rowIdFn(api) {
+        const fn = api.getOption('getRowId');
+        if (!fn)
+            throw new Error('[svgrid review] the grid needs a getRowId prop: proposals are keyed by row id, and positions move on sort and filter');
+        return fn;
+    }
+    function indexRows(api) {
+        const id = rowIdFn(api);
+        const map = new Map();
+        api.getData().forEach((row, i) => map.set(String(id(row, i)), i));
+        return map;
+    }
+    // ---- adding -------------------------------------------------------------
+    function add(input) {
+        const linked = getApi();
+        if (linked)
+            linkCards(linked);
+        const setId = input.id ?? nextId('cs-');
+        const createdAt = Date.now();
+        const ids = [];
+        for (const raw of input.proposals) {
+            if (sameValue(raw.before, raw.after))
+                continue;
+            const p = {
+                ...raw,
+                rowId: String(raw.rowId),
+                id: raw.id ?? nextId('pr-'),
+                op: 'update',
+                source: input.source,
+                // A merged proposal keeps when it was made.
+                createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : createdAt,
+                status: 'pending',
+            };
+            const key = cellKey(p.rowId, p.field);
+            const live = byCell.get(key) ?? new Set();
+            for (const otherId of [...live]) {
+                const other = all.get(otherId);
+                // Being accepted right now: leave it be. If it lands, the stale check
+                // catches this one.
+                if (inFlight.has(otherId))
+                    continue;
+                if (other.source.id === p.source.id && other.status === 'pending') {
+                    // A newer proposal from the same producer replaces the older one
+                    // and keeps what the cell held when the first was made.
+                    p.before = other.before;
+                    live.delete(otherId);
+                    all.delete(otherId);
+                    for (const set of sets.values()) {
+                        const at = set.ids.indexOf(otherId);
+                        if (at >= 0)
+                            set.ids.splice(at, 1);
+                    }
+                }
+                else {
+                    other.status = 'conflict';
+                    other.note = msg.noteConflict;
+                    p.status = 'conflict';
+                    p.note = other.note;
+                }
+            }
+            if (p.status === 'pending' && sameValue(p.before, p.after))
+                continue;
+            live.add(p.id);
+            byCell.set(key, live);
+            all.set(p.id, p);
+            ids.push(p.id);
+        }
+        sets.set(setId, { id: setId, title: input.title ?? input.source.label, source: input.source, createdAt, ids });
+        bump();
+        return { id: setId, title: input.title ?? input.source.label, source: input.source, createdAt, proposals: ids.map((i) => all.get(i)) };
+    }
+    const leaveCell = (p) => {
+        const live = byCell.get(cellKey(p.rowId, p.field));
+        live?.delete(p.id);
+        if (live && !live.size)
+            byCell.delete(cellKey(p.rowId, p.field));
+    };
+    const enterCell = (p) => {
+        const key = cellKey(p.rowId, p.field);
+        byCell.set(key, (byCell.get(key) ?? new Set()).add(p.id));
+    };
+    // ---- reading ------------------------------------------------------------
+    let groupCache = null;
+    function fieldLabels() {
+        const api = getApi();
+        const cols = api?.getColumns() ?? [];
+        const map = new Map(cols.map((c) => [c.field ?? c.id, c.header || c.id]));
+        return (f) => map.get(f) ?? f;
+    }
+    const list = (status) => {
+        void version;
+        const out = [...all.values()];
+        return status ? out.filter((p) => p.status === status) : out;
+    };
+    function groups() {
+        const v = version;
+        if (groupCache?.v === v)
+            return groupCache.groups;
+        const g = clusterProposals(list('pending'), { fieldLabel: fieldLabels(), ...opts.cluster, messages: { ...opts.messages, ...opts.cluster?.messages } });
+        groupCache = { v, groups: g };
+        return g;
+    }
+    function pendingFor(rowId, field) {
+        void version;
+        for (const id of byCell.get(cellKey(rowId, field)) ?? []) {
+            const p = all.get(id);
+            if (p?.status === 'pending')
+                return p;
+        }
+        return undefined;
+    }
+    // ---- deciding -----------------------------------------------------------
+    const outcome = () => ({ accepted: [], rejected: [], stale: [], skipped: [], committedStale: [] });
+    /** Drop proposals whose cell no longer holds `before`. */
+    function freshOnly(ps, out, api) {
+        if (!api)
+            return ps;
+        const data = api.getData();
+        const index = indexRows(api);
+        return ps.filter((p) => {
+            const i = index.get(p.rowId);
+            if (i === undefined) {
+                // A server row model only holds the loaded rows; the backend decides there.
+                if (opts.server)
+                    return true;
+                markStale(p, msg.noteRowGone, out);
+                return false;
+            }
+            const current = data[i][p.field];
+            if (sameValue(current, p.before))
+                return true;
+            markStale(p, msg.noteCellChanged, out);
+            return false;
+        });
+    }
+    function markStale(p, note, out) {
+        p.status = 'stale';
+        p.note = note;
+        p.decidedAt = Date.now();
+        stamp(p);
+        leaveCell(p);
+        out.stale.push(p.id);
+    }
+    /** Write `value` per (rowId, field) into a copy of the grid's current data. */
+    function writeValues(api, writes, beforeSet) {
+        const data = api.getData();
+        const index = indexRows(api);
+        const next = data.slice();
+        const copied = new Set();
+        for (const [rowId, field, value] of writes) {
+            const i = index.get(rowId);
+            if (i === undefined)
+                continue;
+            if (!copied.has(i)) {
+                next[i] = { ...next[i] };
+                copied.add(i);
+            }
+            ;
+            next[i][field] = value;
+        }
+        if (!copied.size)
+            return;
+        beforeSet?.(next);
+        opts.setRows(next);
+    }
+    function currentValue(api, index, p) {
+        const i = index.get(p.rowId);
+        return i === undefined ? undefined : api.getData()[i][p.field];
+    }
+    /**
+     * What an open editor could write back over. A cell editor is committed
+     * first (`stopEditing`), so its value lands and the stale check sees it. A
+     * full-row draft has no public commit, so its row is left alone.
+     */
+    function editedRow(api) {
+        if (!api)
+            return null;
+        api.stopEditing(false);
+        if (!api.getOption('fullRowEditing'))
+            return null;
+        const active = api.getActiveCell();
+        return active ? api.getRowId(active.rowIndex) : null;
+    }
+    async function accept(ids) {
+        const out = outcome();
+        const api = getApi();
+        if (!api && !opts.server) {
+            for (const id of ids) {
+                const p = all.get(id);
+                if (p?.status !== 'pending')
+                    continue;
+                p.note = msg.noteGridNotReady;
+                out.skipped.push(id);
+            }
+            bump();
+            return out;
+        }
+        const busyRow = editedRow(api);
+        let take = [];
+        for (const id of ids) {
+            const p = all.get(id);
+            if (!p || p.status !== 'pending')
+                continue;
+            if (inFlight.has(id) || (busyRow !== null && p.rowId === busyRow)) {
+                if (!inFlight.has(id))
+                    p.note = msg.noteRowEditing;
+                out.skipped.push(id);
+                continue;
+            }
+            take.push(p);
+        }
+        take = freshOnly(take, out, api);
+        if (!take.length) {
+            bump();
+            return out;
+        }
+        for (const p of take)
+            inFlight.add(p.id);
+        try {
+            if (opts.onCommit)
+                await opts.onCommit(take.map((p) => ({ ...p })));
+        }
+        catch (error) {
+            for (const p of take)
+                inFlight.delete(p.id);
+            bump();
+            return { ...out, error };
+        }
+        for (const p of take)
+            inFlight.delete(p.id);
+        // The await let other writes in: check again before writing. What
+        // onCommit already saved but cannot be written now is told apart.
+        if (!opts.server) {
+            const saved = take.filter((p) => p.status === 'pending');
+            const late = outcome();
+            take = freshOnly(saved, late, api);
+            for (const id of late.stale) {
+                const p = all.get(id);
+                if (opts.onCommit) {
+                    p.note = msg.noteSavedStale;
+                    out.committedStale.push(id);
+                }
+                else
+                    out.stale.push(id);
+            }
+        }
+        if (!take.length) {
+            bump();
+            return out;
+        }
+        if (opts.setRows && api)
+            writeValues(api, take.map((p) => [p.rowId, p.field, p.after]), (next) => opts.onApply?.(take, 'accept', next));
+        else {
+            opts.server?.refresh();
+            opts.onApply?.(take, 'accept');
+        }
+        const at = Date.now();
+        for (const p of take) {
+            p.status = 'accepted';
+            p.note = undefined;
+            p.decidedBy = opts.user;
+            p.decidedAt = at;
+            stamp(p);
+            leaveCell(p);
+            out.accepted.push(p.id);
+        }
+        recordUndo(api, take, 'accepted');
+        decided('accept', take);
+        bump();
+        return out;
+    }
+    function decided(action, ps, of) {
+        if (ps.length)
+            opts.onDecision?.({ action, of, proposals: ps.map((p) => ({ ...p })), by: opts.user, at: Date.now() });
+    }
+    function reject(ids) {
+        const out = outcome();
+        const at = Date.now();
+        const taken = [];
+        // What each proposal was before, so an undo puts a conflict back as one.
+        const was = new Map();
+        for (const id of ids) {
+            const p = all.get(id);
+            if (!p || (p.status !== 'pending' && p.status !== 'conflict') || inFlight.has(id))
+                continue;
+            was.set(p.id, p.status);
+            p.status = 'rejected';
+            p.decidedBy = opts.user;
+            p.decidedAt = at;
+            stamp(p);
+            leaveCell(p);
+            taken.push(p);
+            out.rejected.push(id);
+        }
+        if (taken.length)
+            recordUndo(getApi(), taken, 'rejected', was);
+        decided('reject', taken);
+        bump();
+        return out;
+    }
+    /**
+     * One Ctrl+Z for the whole decision, by row id, so it works with paging and
+     * filters on. Undoing an accept writes `before` back only where the cell
+     * still holds `after`; anything edited since is left as it is. With
+     * `onCommit`, the reversed values are saved first and written once that
+     * resolves, the way an accept is.
+     */
+    function recordUndo(api, ps, kind, was) {
+        if (!api)
+            return;
+        const prior = new Map(ps.map((p) => [p.id, { decidedBy: p.decidedBy, decidedAt: p.decidedAt }]));
+        const undecided = (p) => was?.get(p.id) ?? 'pending';
+        const flip = (undo, which) => {
+            for (const p of which) {
+                if (undo) {
+                    p.status = undecided(p);
+                    p.decidedBy = undefined;
+                    p.decidedAt = undefined;
+                    // A proposal dropped since (clear, load) stays out of the cell index.
+                    if (all.get(p.id) === p)
+                        enterCell(p);
+                }
+                else {
+                    p.status = kind;
+                    Object.assign(p, prior.get(p.id));
+                    leaveCell(p);
+                }
+            }
+            decided(undo ? 'undo' : 'redo', which, kind === 'accepted' ? 'accept' : 'reject');
+            bump();
+        };
+        const move = (undo) => {
+            const live = ps.filter((p) => (undo ? p.status === kind : p.status === undecided(p)));
+            if (kind === 'rejected')
+                return flip(undo, live);
+            const from = undo ? 'after' : 'before';
+            const to = undo ? 'before' : 'after';
+            const how = undo ? 'undo' : 'redo';
+            if (opts.server) {
+                const inverse = live.map((p) => ({ ...p, before: p[from], after: p[to] }));
+                Promise.resolve(opts.onCommit(inverse)).then(() => {
+                    opts.server.refresh();
+                    flip(undo, live);
+                    opts.onApply?.(live, how);
+                }, (error) => failed(error, how));
+                return;
+            }
+            // One row index per pass (rebuilt after an async save), not one per proposal.
+            const holdsIn = () => {
+                const index = indexRows(api);
+                return (p) => sameValue(currentValue(api, index, p), p[from]);
+            };
+            const write = (ok) => {
+                if (!ok.length)
+                    return;
+                writeValues(api, ok.map((p) => [p.rowId, p.field, p[to]]), (next) => opts.onApply?.(ok, how, next));
+                flip(undo, ok);
+            };
+            const ok = live.filter(holdsIn());
+            if (!opts.onCommit)
+                return write(ok);
+            // The backend holds the accepted values: save the reverse there first.
+            Promise.resolve(opts.onCommit(ok.map((p) => ({ ...p, before: p[from], after: p[to] })))).then(() => write(ok.filter(holdsIn())), (error) => failed(error, how));
+        };
+        api.getCommandContext().recordUndo(() => move(true), () => move(false));
+    }
+    function groupIds(key, shownIds) {
+        const g = groups().find((x) => x.key === key);
+        if (!g)
+            return [];
+        const members = new Set(g.ids);
+        return shownIds.filter((id) => members.has(id));
+    }
+    /**
+     * Keep one of a cell's conflicting proposals (it becomes pending) and reject
+     * the rest, as one undo step that puts all of them back in conflict.
+     */
+    function resolveConflict(keepId) {
+        const keep = all.get(keepId);
+        if (!keep || keep.status !== 'conflict')
+            return;
+        const rivals = [...(byCell.get(cellKey(keep.rowId, keep.field)) ?? [])]
+            .filter((id) => id !== keepId && !inFlight.has(id))
+            .map((id) => all.get(id))
+            .filter((p) => p?.status === 'conflict');
+        const note = keep.note;
+        const apply = (resolved) => {
+            const at = Date.now();
+            for (const r of rivals) {
+                if (resolved) {
+                    r.status = 'rejected';
+                    r.decidedBy = opts.user;
+                    r.decidedAt = at;
+                    stamp(r);
+                    leaveCell(r);
+                }
+                else {
+                    r.status = 'conflict';
+                    r.decidedBy = undefined;
+                    r.decidedAt = undefined;
+                    if (all.get(r.id) === r)
+                        enterCell(r);
+                }
+            }
+            keep.status = resolved ? 'pending' : 'conflict';
+            keep.note = resolved ? undefined : note;
+            bump();
+        };
+        apply(true);
+        decided('reject', rivals);
+        getApi()?.getCommandContext().recordUndo(() => apply(false), () => apply(true));
+    }
+    // ---- serialising --------------------------------------------------------
+    /**
+     * Every set with its proposals and their status, as plain JSON. Pass
+     * `setIds` to export only some, to hand them to someone else to decide.
+     */
+    function toJSON(opts = {}) {
+        const only = opts.setIds ? new Set(opts.setIds) : null;
+        return {
+            v: 1,
+            sets: [...sets.values()].filter((set) => !only || only.has(set.id)).map(({ ids, ...meta }) => ({
+                ...meta,
+                proposals: ids.map((i) => all.get(i)).filter((p) => !!p).map((p) => ({ ...p })),
+            })),
+        };
+    }
+    /**
+     * Replace everything with an export. The export is checked first: a wrong
+     * shape throws and leaves the review as it was; a malformed proposal is
+     * dropped. Returns how many were dropped.
+     */
+    function load(json) {
+        const { sets: valid, dropped } = checkExport(json);
+        clear();
+        for (const set of valid) {
+            sets.set(set.id, { id: set.id, title: set.title, source: set.source, createdAt: set.createdAt, ids: set.proposals.map((p) => p.id) });
+            for (const p of set.proposals) {
+                all.set(p.id, { ...p });
+                if (p.status === 'pending' || p.status === 'conflict')
+                    enterCell(p);
+            }
+        }
+        bump();
+        return { dropped };
+    }
+    /**
+     * Add the sets of an export to this review, keeping what is here: an
+     * approver's page merges what the author exported. A set already present is
+     * skipped. Pending proposals go through the same rules as `add` (a cell
+     * with a live proposal from another source becomes a conflict); decided ones
+     * are kept as history.
+     */
+    function merge(json) {
+        const { sets: valid, dropped } = checkExport(json);
+        for (const set of valid) {
+            if (sets.has(set.id))
+                continue;
+            const live = set.proposals.filter((p) => p.status === 'pending' || p.status === 'conflict');
+            const history = set.proposals.filter((p) => !live.includes(p) && !all.has(p.id));
+            add({ id: set.id, title: set.title, source: set.source, proposals: live.filter((p) => !all.has(p.id)) });
+            sets.get(set.id).createdAt = set.createdAt;
+            for (const p of history)
+                all.set(p.id, { ...p });
+            sets.get(set.id).ids.push(...history.map((p) => p.id));
+        }
+        bump();
+        return { dropped };
+    }
+    // ---- history ------------------------------------------------------------
+    /** Every decided proposal (accepted, rejected or stale), oldest decision first. */
+    function log() {
+        void version;
+        return [...all.values()]
+            .filter((p) => p.status === 'accepted' || p.status === 'rejected' || p.status === 'stale')
+            .sort((a, b) => (a.decidedAt ?? 0) - (b.decidedAt ?? 0) || (decidedOrder.get(a.id) ?? 0) - (decidedOrder.get(b.id) ?? 0))
+            .map((p) => ({ ...p }));
+    }
+    /**
+     * Propose undoing what a set wrote, after the fact: a new set with each
+     * accepted proposal reversed (`after` back to `before`). It is reviewed and
+     * accepted like any other set, so the stale check keeps a later edit.
+     * Returns null when nothing of the set was accepted.
+     */
+    function revertSet(setId) {
+        const set = sets.get(setId);
+        if (!set)
+            return null;
+        const accepted = set.ids.map((id) => all.get(id)).filter((p) => p?.status === 'accepted');
+        if (!accepted.length)
+            return null;
+        return add({
+            source: { kind: 'user', id: `revert:${setId}`, label: `Revert: ${set.title}` },
+            title: `Revert: ${set.title}`,
+            proposals: accepted.map((p) => ({ rowId: p.rowId, field: p.field, before: p.after, after: p.before, reason: `reverts ${p.source.label}` })),
+        });
+    }
+    /** The sets in this review, newest last, without their proposals. */
+    function sets_() {
+        void version;
+        return [...sets.values()].map(({ ids, ...meta }) => ({ ...meta, count: ids.length }));
+    }
+    function clear() {
+        all.clear();
+        sets.clear();
+        byCell.clear();
+        bump();
+    }
+    // ---- grid display -------------------------------------------------------
+    /** A card's mark (board, gallery): how many proposals its row has and what they set. */
+    let liveByRow = null;
+    function cardMark(rowId) {
+        if (liveByRow?.v !== version) {
+            const rows = new Map();
+            for (const p of all.values()) {
+                if (p.status !== 'pending' && p.status !== 'conflict')
+                    continue;
+                const list = rows.get(p.rowId);
+                if (list)
+                    list.push(p);
+                else
+                    rows.set(p.rowId, [p]);
+            }
+            liveByRow = { v: version, rows };
+        }
+        const ps = liveByRow.rows.get(rowId);
+        if (!ps)
+            return null;
+        const labels = fieldLabels();
+        return {
+            count: ps.length,
+            label: fill(msg.cardProposed, { count: ps.length }),
+            text: ps.map((p) => `${labels(p.field)} → ${showValue(p.after, msg.empty)}`).join(', '),
+        };
+    }
+    /** Whether a row object is in the grid's data (cached per data array). */
+    let owned = null;
+    function owns(row) {
+        const data = getApi()?.getData();
+        if (!data || !row || typeof row !== 'object')
+            return false;
+        if (owned?.data !== data)
+            owned = { data, rows: new WeakSet(data.filter((r) => !!r && typeof r === 'object')) };
+        return owned.rows.has(row);
+    }
+    let marksFor = null;
+    /** Register for the board and gallery cards of the grid, once its getRowId is known. */
+    function linkCards(api) {
+        const fn = api.getOption('getRowId');
+        if (fn && fn !== marksFor) {
+            marksFor = fn;
+            registerCardMarks(fn, {
+                cardMark,
+                owns,
+                cellProposal: (rowId, field) => {
+                    const p = pendingFor(rowId, field);
+                    return p ? { after: p.after, source: p.source.label, reason: p.reason, proposes: msg.proposes, empty: msg.empty } : null;
+                },
+            });
+        }
+    }
+    /** The row "Show in grid" just landed on; it flashes for a moment so the eye finds it. */
+    let flashRow = $state(null);
+    let flashTimer;
+    function flash(rowId) {
+        flashRow = rowId;
+        clearTimeout(flashTimer);
+        flashTimer = setTimeout(() => (flashRow = null), 1600);
+    }
+    const formats = $derived.by(() => {
+        void version;
+        const api = getApi();
+        if (!api || !api.getOption('getRowId'))
+            return [];
+        linkCards(api);
+        const idOf = rowIdFn(api);
+        const cols = api.getColumns();
+        const out = pendingFormats(list('pending'), idOf, cols);
+        // After the pending tint, so a disputed cell reads as disputed.
+        out.push(...pendingFormats(list('conflict'), idOf, cols, { background: CONFLICT_BG, icon: CONFLICT_ICON }));
+        const lit = flashRow;
+        // Last, so it wins over the pending tint; every column of the row.
+        if (lit !== null)
+            out.push({ type: 'rule', when: ({ row }) => String(idOf(row, 0)) === lit, background: FLASH_BG });
+        return out;
+    });
+    /** Pending-field set as a string, so `columns()` rebuilds only when it changes. */
+    const pendingFields = $derived.by(() => {
+        void version;
+        return [...new Set(list('pending').map((p) => p.field))].sort().join(SEP);
+    });
+    /** The first non-blank value of `field`, so a boolean column is never wrapped. */
+    function sampleValue(field) {
+        for (const row of getApi()?.getData() ?? []) {
+            const v = row[field];
+            if (v != null && v !== '')
+                return v;
+        }
+        return undefined;
+    }
+    let columnsCache = null;
+    function columns(cols) {
+        // The grid reads its columns in every view (table, board, gallery), so cards link here too.
+        const linked = getApi();
+        if (linked)
+            linkCards(linked);
+        const fields = pendingFields;
+        if (columnsCache && columnsCache.input === cols && columnsCache.fields === fields)
+            return columnsCache.output;
+        const output = wrapColumns(cols, new Set(fields ? fields.split(SEP) : []), review, sampleValue);
+        columnsCache = { input: cols, fields, output };
+        return output;
+    }
+    // ---- navigation ---------------------------------------------------------
+    /**
+     * Show the next proposal of `ids` after `fromId`, on whatever page it is:
+     * with client paging the grid moves to its page (`api.getRowPosition`),
+     * then scrolls to it. Does not move the active cell. With grouping, where
+     * pages are counted in groups, it stays on the current page. Returns the id
+     * shown and how many of `ids` cannot be shown (filtered out, or on another
+     * page of a grouped grid).
+     */
+    function reveal(ids, fromId) {
+        const api = getApi();
+        if (!api)
+            return { id: null, hidden: ids.length };
+        const proposals = ids.map((i) => all.get(i)).filter((p) => !!p);
+        const grouped = (api.getState().grouping?.length ?? 0) > 0;
+        // The grid pages with `pageable`, or the older `showPagination`.
+        const paged = !!(api.getOption('pageable') ?? api.getOption('showPagination')) && !api.getOption('externalPagination');
+        let reachable;
+        if (grouped) {
+            const idFn = rowIdFn(api);
+            const onPage = new Set(api.getDisplayedRows().map((r, i) => String(idFn(r, i))));
+            reachable = proposals.filter((p) => onPage.has(p.rowId)).map((p) => ({ p, position: -1 }));
+        }
+        else {
+            reachable = proposals
+                .map((p) => ({ p, position: api.getRowPosition(p.rowId) }))
+                .filter((x) => x.position !== null);
+        }
+        const hidden = proposals.length - reachable.length;
+        if (!reachable.length)
+            return { id: null, hidden };
+        const start = fromId ? reachable.findIndex((x) => x.p.id === fromId) + 1 : 0;
+        const target = reachable[start % reachable.length];
+        if (!grouped) {
+            let index = target.position;
+            if (paged) {
+                const { pageIndex, pageSize } = api.getPageInfo();
+                const page = Math.floor(index / pageSize);
+                if (page !== pageIndex)
+                    api.setPage(page);
+                index -= page * pageSize;
+            }
+            api.scrollToRow(index);
+            flash(target.p.rowId);
+            return { id: target.p.id, hidden };
+        }
+        // The display index counts group banners, which getDisplayedRows skips:
+        // walk the display rows until the id matches.
+        const limit = api.getDisplayedRows().length * 2 + 64;
+        for (let i = 0; i < limit; i++) {
+            if (api.getRowId(i) === target.p.rowId) {
+                api.scrollToRow(i);
+                flash(target.p.rowId);
+                break;
+            }
+        }
+        return { id: target.p.id, hidden };
+    }
+    // Row index for labels, rebuilt when the grid's data array changes.
+    let labelIndex = null;
+    function rowLabel(p) {
+        const api = getApi();
+        if (!api || !api.getOption('getRowId'))
+            return null;
+        const data = api.getData();
+        if (labelIndex?.data !== data)
+            labelIndex = { data, map: indexRows(api) };
+        const i = labelIndex.map.get(p.rowId);
+        if (i === undefined)
+            return null;
+        const row = data[i];
+        if (opts.rowLabel)
+            return opts.rowLabel(row) || null;
+        for (const c of api.getColumns()) {
+            if (!c.visible || !c.field)
+                continue;
+            const v = row[c.field];
+            if (typeof v === 'string' && v.trim())
+                return c.field === p.field ? null : v.trim();
+        }
+        return null;
+    }
+    const review = {
+        get version() {
+            return version;
+        },
+        /** The wording in effect: English with `messages` laid over it. */
+        messages: msg,
+        /** The last undo or redo whose save failed, or null. */
+        get lastError() {
+            return lastError;
+        },
+        add,
+        get: (id) => {
+            void version;
+            return all.get(id);
+        },
+        proposals: () => list(),
+        /** What names the proposal's row (`rowLabel`), or null. */
+        rowLabel,
+        /** A field's column header, as the group labels show it. */
+        fieldLabel: (field) => fieldLabels()(field),
+        pending: () => list('pending'),
+        conflicts: () => list('conflict'),
+        groups,
+        pendingFor,
+        accept,
+        reject,
+        acceptGroup: (key, shownIds) => accept(groupIds(key, shownIds)),
+        rejectGroup: (key, shownIds) => reject(groupIds(key, shownIds)),
+        resolveConflict,
+        get formats() {
+            return formats;
+        },
+        columns,
+        reveal,
+        showPendingOnly,
+        /** On while our condition is in the grid's advanced filter (the grid's own Clear takes it out too). */
+        get pendingOnly() {
+            return pendingOnly && hasPending(getApi()?.getAdvancedFilter() ?? null);
+        },
+        toJSON,
+        load,
+        merge,
+        log,
+        revertSet,
+        sets: sets_,
+        clear,
+    };
+    return review;
+}