@svgrid/enterprise 3.1.22 → 3.1.23

package/dist/review/cluster.js

@@ -0,0 +1,377 @@
+/**
+ * Proposal clustering: put every pending proposal in exactly one group, by
+ * the transformation it applies, so a reviewer looks at a few groups instead
+ * of thousands of cells. Deterministic and pure; no model is asked.
+ *
+ * Detectors run in a fixed order and the first that matches wins. The rule
+ * detectors go first because they prove their claim for every member:
+ *
+ *   1. whitespace       `after` is `before` trimmed / with spaces collapsed
+ *   2. case             same letters, different case
+ *   3. format           same characters apart from punctuation, the same
+ *                       unambiguous date, or text that parses to the number
+ *   4. scale            `after / before` is the same number, 5+ members
+ *
+ * Then the judgment detectors, where a person has to look:
+ *
+ *   5. same-mapping     non-blank `before` values that each map to the same
+ *                       `after` at least twice: one group per target, read
+ *                       as a mapping table ("usa", "U.S." -> "United States")
+ *   6. fill-empty       blank `before`, split by `after`; singletons pooled
+ *   7. constant-target  many different `before`, one `after`, 3+ members
+ *   8. unpatterned      the rest, per field
+ *
+ * A group is keyed by source, field, kind and param, so two producers never
+ * share a group and neither do two fields.
+ */
+import { isBlank } from './equal.js';
+import { fill, reviewMessages } from './messages.js';
+const RULE_KINDS = new Set(['whitespace', 'case', 'format', 'scale']);
+const SEP = '\u0001';
+export function clusterProposals(proposals, opts = {}) {
+    const fieldLabel = opts.fieldLabel ?? ((f) => f);
+    const msg = reviewMessages(opts.messages);
+    const minScale = opts.minScale ?? 5;
+    const low = opts.lowConfidence ?? 0.6;
+    const order = new Map();
+    proposals.forEach((p, i) => order.set(p.id, i));
+    const buckets = new Map();
+    const put = (p, kind, param) => {
+        const key = [p.source.id, p.field, kind, param].join(SEP);
+        let b = buckets.get(key);
+        if (!b)
+            buckets.set(key, (b = { kind, param, field: p.field, sourceId: p.source.id, members: [] }));
+        b.members.push(p);
+    };
+    const cell = (p) => p.source.id + SEP + p.field;
+    // 1-3: provable per proposal.
+    let rest = [];
+    for (const p of proposals) {
+        const r = ruleOf(p.before, p.after);
+        if (r)
+            put(p, r.kind, r.param);
+        else
+            rest.push(p);
+    }
+    // 4: scale, only once enough members share a ratio.
+    rest = bucketPass(rest, (p) => {
+        const r = ratioOf(p.before, p.after);
+        return r == null ? null : cell(p) + SEP + r;
+    }, (members) => members.length >= minScale, (p, k) => put(p, 'scale', k.slice(k.lastIndexOf(SEP) + 1)));
+    // 5: non-blank pairs seen at least twice, one group per target value.
+    rest = bucketPass(rest, (p) => (isBlank(p.before) ? null : cell(p) + SEP + keyOf(p.before) + SEP + keyOf(p.after)), (members) => members.length >= 2, (p) => put(p, 'same-mapping', keyOf(p.after)));
+    // 6: blank before, split by the value proposed; singletons go to one pooled group.
+    rest = bucketPass(rest, (p) => (isBlank(p.before) ? cell(p) + SEP + keyOf(p.after) : null), () => true, (p, _k, members) => put(p, 'fill-empty', members.length >= 2 ? keyOf(p.after) : '*'));
+    // 7: one target from at least three proposals.
+    rest = bucketPass(rest, (p) => cell(p) + SEP + keyOf(p.after), (members) => members.length >= 3, (p) => put(p, 'constant-target', keyOf(p.after)));
+    // 8: everything else, per field.
+    for (const p of rest)
+        put(p, 'unpatterned', '');
+    const groups = [];
+    for (const [key, b] of buckets) {
+        const members = b.members.sort((x, y) => order.get(x.id) - order.get(y.id));
+        const confs = members.map((m) => m.confidence).filter((c) => typeof c === 'number');
+        groups.push({
+            key,
+            kind: b.kind,
+            rule: RULE_KINDS.has(b.kind),
+            param: b.param,
+            label: labelOf(b.kind, b.param, fieldLabel(b.field), members, msg),
+            field: b.field,
+            sourceId: b.sourceId,
+            ids: members.map((m) => m.id),
+            count: members.length,
+            minConfidence: confs.length ? Math.min(...confs) : undefined,
+            avgConfidence: confs.length ? confs.reduce((s, c) => s + c, 0) / confs.length : undefined,
+            sample: sampleOf(members, low),
+            beforeDistribution: b.kind === 'constant-target' || b.kind === 'same-mapping' ? distributionOf(members) : undefined,
+        });
+    }
+    return groups.sort((a, b) => rankOf(a, low) - rankOf(b, low) || b.count - a.count || (a.key < b.key ? -1 : 1));
+}
+/**
+ * Bucket `items` by `keyFn`. Members of buckets that pass `keep` are handed
+ * to `take`; everything else (no key, or a bucket that failed) is returned,
+ * in the original order.
+ */
+function bucketPass(items, keyFn, keep, take) {
+    const byKey = new Map();
+    const keys = items.map((p) => {
+        const k = keyFn(p);
+        if (k != null) {
+            const list = byKey.get(k);
+            if (list)
+                list.push(p);
+            else
+                byKey.set(k, [p]);
+        }
+        return k;
+    });
+    const out = [];
+    items.forEach((p, i) => {
+        const k = keys[i];
+        const members = k == null ? null : byKey.get(k);
+        if (members && keep(members))
+            take(p, k, members);
+        else
+            out.push(p);
+    });
+    return out;
+}
+// ---- rule detectors -------------------------------------------------------
+function ruleOf(before, after) {
+    if (typeof before === 'string' && typeof after === 'number') {
+        const n = parseLooseNumber(before);
+        return n !== null && n === after ? { kind: 'format', param: 'to-number' } : null;
+    }
+    const dayB = dayOf(before);
+    const dayA = dayOf(after);
+    // The same day at a different time is a different value, not a new format.
+    if (dayB && dayA && dayB === dayA && timeOf(before) === timeOf(after) && !(before instanceof Date && after instanceof Date)) {
+        return { kind: 'format', param: 'date:' + (after instanceof Date ? 'Date' : shapeOf(String(after))) };
+    }
+    if (typeof before !== 'string' || typeof after !== 'string' || before === after)
+        return null;
+    if (before.trim() === after || before.replace(/\s+/g, ' ').trim() === after)
+        return { kind: 'whitespace', param: '' };
+    if (before.toLowerCase() === after.toLowerCase())
+        return { kind: 'case', param: caseOf(after) };
+    // Punctuation can carry meaning in a number: "3.5" -> "35" keeps every
+    // digit and is still a different value. Text that reads as a number on
+    // either side only counts as reformatting when both read as the same one.
+    const nB = parseLooseNumber(before);
+    const nA = parseLooseNumber(after);
+    if ((nB !== null || nA !== null) && nB !== nA)
+        return null;
+    const coreB = alnum(before);
+    // Punctuation between digits can be part of a number ("$1,234.56" ->
+    // "$123,456", "12.5%" -> "1.25%"): every run of digits has to stay as it was.
+    if (coreB.length > 0 && coreB === alnum(after) && digitRuns(before) === digitRuns(after)) {
+        const digits = coreB.replace(/\D/g, '').length;
+        return digits * 2 >= coreB.length
+            ? { kind: 'format', param: 'shape:' + shapeOf(after) }
+            : { kind: 'format', param: 'punct:' + JSON.stringify(punctDiff(before, after)) };
+    }
+    return null;
+}
+function ratioOf(before, after) {
+    if (typeof before !== 'number' || typeof after !== 'number')
+        return null;
+    if (!Number.isFinite(before) || !Number.isFinite(after) || before === 0 || before === after)
+        return null;
+    return String(Number((after / before).toPrecision(10)));
+}
+const alnum = (s) => s.replace(/[^\p{L}\p{N}]/gu, '');
+const digitRuns = (s) => (s.match(/\d+/g) ?? []).join(',');
+/** The time of day a date value carries, as HH:MM:SS; midnight when it carries none. */
+function timeOf(v) {
+    if (v instanceof Date)
+        return [v.getHours(), v.getMinutes(), v.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+    const m = typeof v === 'string' ? /[T ](\d{1,2}):(\d{2})(?::(\d{2}))?/.exec(v) : null;
+    return m ? [m[1], m[2], m[3] ?? '00'].map((n) => n.padStart(2, '0')).join(':') : '00:00:00';
+}
+const shapeOf = (s) => s.replace(/\p{N}/gu, '9').replace(/\p{Lu}/gu, 'A').replace(/\p{Ll}/gu, 'a');
+function caseOf(s) {
+    if (s === s.toUpperCase())
+        return 'upper';
+    if (s === s.toLowerCase())
+        return 'lower';
+    const words = s.split(/\s+/).filter(Boolean);
+    const title = words.every((w) => {
+        const head = w.charAt(0);
+        return head === head.toUpperCase() && w.slice(1) === w.slice(1).toLowerCase();
+    });
+    return title ? 'title' : 'mixed';
+}
+/** The punctuation removed and added, each sorted and unique. */
+function punctDiff(before, after) {
+    const count = (s) => {
+        const m = new Map();
+        for (const ch of s.replace(/[\p{L}\p{N}]/gu, ''))
+            m.set(ch, (m.get(ch) ?? 0) + 1);
+        return m;
+    };
+    const b = count(before);
+    const a = count(after);
+    const removed = [...b].filter(([ch, n]) => n > (a.get(ch) ?? 0)).map(([ch]) => ch).sort().join('');
+    const added = [...a].filter(([ch, n]) => n > (b.get(ch) ?? 0)).map(([ch]) => ch).sort().join('');
+    return [removed, added];
+}
+/**
+ * A number written as text, or null. Commas count only as thousands
+ * separators ("1,200"), so "1,5" (a decimal comma) is not read as 15.
+ */
+function parseLooseNumber(s) {
+    const t = s.trim();
+    if (!/^[-+]?(\d{1,3}(,\d{3})+|\d+)?(\.\d+)?$/.test(t) || !/\d/.test(t))
+        return null;
+    return Number(t.replace(/,/g, ''));
+}
+/**
+ * A calendar day as YYYY-MM-DD, or null when the value is not a date or its
+ * day and month cannot be told apart (03/05/2024 could be either).
+ */
+function dayOf(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? null : ymd(v.getFullYear(), v.getMonth() + 1, v.getDate());
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim();
+    let m = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T ][\d:.]+Z?)?$/.exec(s);
+    if (m)
+        return valid(+m[1], +m[2], +m[3]);
+    m = /^(\d{1,2})[/.-](\d{1,2})[/.-](\d{4})$/.exec(s);
+    if (!m)
+        return null;
+    const a = +m[1];
+    const b = +m[2];
+    const y = +m[3];
+    if (a === b)
+        return valid(y, a, b);
+    if (a > 12 && b <= 12)
+        return valid(y, b, a);
+    if (b > 12 && a <= 12)
+        return valid(y, a, b);
+    return null;
+}
+function valid(y, mo, d) {
+    if (mo < 1 || mo > 12 || d < 1 || d > 31)
+        return null;
+    return ymd(y, mo, d);
+}
+const ymd = (y, m, d) => `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+// ---- grouping helpers -----------------------------------------------------
+/** A key that tells values apart by type as well as content. */
+export function keyOf(v) {
+    if (v instanceof Date)
+        return 'd:' + v.getTime();
+    if (isBlank(v))
+        return 'blank';
+    if (typeof v === 'string')
+        return 's:' + v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return typeof v.valueOf() + ':' + String(v);
+    try {
+        return 'j:' + JSON.stringify(v);
+    }
+    catch {
+        return 'o:' + String(v);
+    }
+}
+/**
+ * What to look at first: every member below the low-confidence line (up to
+ * ten), at least the two least confident, then members spread evenly across
+ * the group until there are five.
+ */
+function sampleOf(members, low) {
+    if (members.length <= 5)
+        return members.map((m) => m.id);
+    const byConfidence = members
+        .filter((m) => typeof m.confidence === 'number')
+        .sort((x, y) => x.confidence - y.confidence);
+    const unsure = byConfidence.filter((m) => m.confidence < low).slice(0, 10);
+    const picked = unsure.length >= 2 ? unsure : byConfidence.slice(0, 2);
+    const rest = members.filter((m) => !picked.includes(m));
+    const need = Math.max(0, 5 - picked.length);
+    for (let i = 0; i < need; i++)
+        picked.push(rest[Math.round((i * (rest.length - 1)) / Math.max(1, need - 1))]);
+    return [...new Set(picked.map((m) => m.id))];
+}
+function distributionOf(members) {
+    const counts = new Map();
+    for (const m of members) {
+        const k = keyOf(m.before);
+        const e = counts.get(k);
+        if (e)
+            e.count++;
+        else
+            counts.set(k, { value: m.before, count: 1 });
+    }
+    const sorted = [...counts.values()].sort((a, b) => b.count - a.count);
+    const top = sorted.slice(0, 5);
+    const other = sorted.slice(5).reduce((s, e) => s + e.count, 0);
+    if (other > 0)
+        top.push({ value: undefined, count: other, other: true });
+    return top;
+}
+function rankOf(g, low) {
+    if (g.kind === 'unpatterned')
+        return 0;
+    if (g.kind === 'constant-target')
+        return 1;
+    if (!g.rule && g.minConfidence !== undefined && g.minConfidence < low)
+        return 2;
+    return g.rule ? 4 : 3;
+}
+// ---- labels ---------------------------------------------------------------
+/**
+ * Spaces a reader cannot see, drawn as `·`: leading and trailing ones and runs
+ * of two or more. A trim proposal otherwise reads "Acme -> Acme".
+ */
+export function visibleSpaces(s) {
+    return s.replace(/^\s+|\s+$/g, (m) => '·'.repeat(m.length)).replace(/ {2,}/g, (m) => '·'.repeat(m.length));
+}
+/**
+ * A value as a group label shows it: short, `(empty)` for blank, spaces
+ * visible. A string is quoted only where the quotes tell something: around
+ * spaces at its ends, or when it reads as a number, a boolean or the blank mark.
+ */
+export function showValue(v, empty = '(empty)') {
+    if (isBlank(v))
+        return empty;
+    if (v instanceof Date)
+        return v.toISOString().slice(0, 10);
+    const s = typeof v === 'string' ? v : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    const short = s.length > 40 ? s.slice(0, 39) + '...' : s;
+    if (typeof v !== 'string')
+        return short;
+    const quote = /^\s|\s$/.test(s) || /^-?[\d.,]+$|^(true|false)$/i.test(s) || s === empty;
+    return quote ? `"${visibleSpaces(short)}"` : visibleSpaces(short);
+}
+function labelOf(kind, param, field, members, m) {
+    const first = members[0];
+    const show = (v) => showValue(v, m.empty);
+    switch (kind) {
+        case 'whitespace':
+            return fill(m.labelWhitespace, { field });
+        case 'case': {
+            const name = { upper: m.caseUpper, lower: m.caseLower, title: m.caseTitle }[param] ?? m.caseMixed;
+            return fill(m.labelCase, { field, case: name });
+        }
+        case 'format': {
+            if (param === 'to-number')
+                return fill(m.labelToNumber, { field });
+            if (param.startsWith('date:'))
+                return fill(m.labelDates, { field, shape: param === 'date:Date' ? m.datesAsDates : param.slice(5) });
+            if (param.startsWith('shape:'))
+                return fill(m.labelShape, { field, shape: param.slice(6) });
+            const [removed, added] = JSON.parse(param.slice(6));
+            const chars = (cs) => [...cs].map((c) => (c === ' ' ? m.punctSpaces : `"${c}"`)).join(' ');
+            const parts = [];
+            if (removed)
+                parts.push(fill(m.punctRemove, { chars: chars(removed) }));
+            if (added)
+                parts.push(fill(m.punctAdd, { chars: chars(added) }));
+            const change = parts.join(', ');
+            return fill(m.labelPunct, { field, change: change.charAt(0).toUpperCase() + change.slice(1) });
+        }
+        case 'scale': {
+            const r = Number(param);
+            const inv = 1 / r;
+            if (Math.abs(r) < 1 && Math.abs(inv - Math.round(inv)) < 1e-9)
+                return fill(m.labelDivide, { field, n: Math.round(inv) });
+            return fill(m.labelMultiply, { field, n: param });
+        }
+        case 'same-mapping': {
+            const froms = new Set(members.map((p) => keyOf(p.before))).size;
+            const from = froms === 1 ? show(first.before) : fill(m.mappingValues, { count: froms });
+            return fill(m.labelMapping, { field, from, to: show(first.after) });
+        }
+        case 'fill-empty':
+            return param === '*' ? fill(m.labelFillVarious, { field }) : fill(m.labelFill, { field, value: show(first.after) });
+        case 'constant-target':
+            return fill(m.labelConstant, { field, value: show(first.after) });
+        case 'unpatterned':
+            return fill(m.labelUnpatterned, { field });
+    }
+}

package/dist/review/equal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Value equality for change review: is a cell still what a proposal saw, and
+ * is a proposal a no-op. `Object.is` for primitives, Dates by time, arrays
+ * and plain objects by structure. Blank (null, undefined, '') equals blank,
+ * the same rule Base sync uses (`fields/base-sync.ts`), so a cell cleared to
+ * '' does not make a proposal made against `null` look stale.
+ */
+export declare const isBlank: (v: unknown) => boolean;
+export declare function sameValue(a: unknown, b: unknown): boolean;

package/dist/review/equal.js

@@ -0,0 +1,35 @@
+/**
+ * Value equality for change review: is a cell still what a proposal saw, and
+ * is a proposal a no-op. `Object.is` for primitives, Dates by time, arrays
+ * and plain objects by structure. Blank (null, undefined, '') equals blank,
+ * the same rule Base sync uses (`fields/base-sync.ts`), so a cell cleared to
+ * '' does not make a proposal made against `null` look stale.
+ */
+export const isBlank = (v) => v == null || v === '';
+export function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (isBlank(a) && isBlank(b))
+        return true;
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => sameValue(v, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ka = Object.keys(a);
+        if (ka.length !== Object.keys(b).length)
+            return false;
+        return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && sameValue(a[k], b[k]));
+    }
+    return false;
+}
+function isPlainObject(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}

package/dist/review/formats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The tint on cells with a pending proposal, as `conditionalFormats` rules:
+ * one rule per field, scoped to that field's columns, matching rows by id.
+ * Costs the free grid nothing; the app concatenates these with its own
+ * formats, as `BaseTableView.svelte` does for remote changes.
+ */
+import type { ConditionalFormat } from '@svgrid/grid';
+import type { Proposal } from './types.js';
+/**
+ * Theme it with `--sg-review-pending-bg`. The default is a light amber wash
+ * from `--sg-warning`, kept apart from the accent, which themes use for
+ * selection and focus.
+ */
+export declare const PENDING_BG = "var(--sg-review-pending-bg, color-mix(in srgb, var(--sg-warning, #d97706) 13%, transparent))";
+/** The row "Show in grid" lands on, for a moment: a stronger wash of the same amber. */
+export declare const FLASH_BG = "var(--sg-review-flash-bg, color-mix(in srgb, var(--sg-warning, #d97706) 32%, transparent))";
+/** Drawn before the value, so a pending cell is never marked by colour alone. */
+export declare const PENDING_ICON = "\u2022";
+/**
+ * A cell two sources disagree on: a red wash (`--sg-review-conflict-bg`) and
+ * a "!" before the value, so the grid shows where the panel's conflicts are.
+ */
+export declare const CONFLICT_BG = "var(--sg-review-conflict-bg, color-mix(in srgb, var(--sg-danger, #dc2626) 12%, transparent))";
+export declare const CONFLICT_ICON = "!";
+export declare function pendingFormats<TData>(pending: ReadonlyArray<Proposal>, rowId: (row: TData, index: number) => string, columns: ReadonlyArray<{
+    id: string;
+    field?: string;
+}>, look?: {
+    background: string;
+    icon: string;
+}): ConditionalFormat<any>[];

package/dist/review/formats.js

@@ -0,0 +1,37 @@
+/**
+ * Theme it with `--sg-review-pending-bg`. The default is a light amber wash
+ * from `--sg-warning`, kept apart from the accent, which themes use for
+ * selection and focus.
+ */
+export const PENDING_BG = 'var(--sg-review-pending-bg, color-mix(in srgb, var(--sg-warning, #d97706) 13%, transparent))';
+/** The row "Show in grid" lands on, for a moment: a stronger wash of the same amber. */
+export const FLASH_BG = 'var(--sg-review-flash-bg, color-mix(in srgb, var(--sg-warning, #d97706) 32%, transparent))';
+/** Drawn before the value, so a pending cell is never marked by colour alone. */
+export const PENDING_ICON = '•';
+/**
+ * A cell two sources disagree on: a red wash (`--sg-review-conflict-bg`) and
+ * a "!" before the value, so the grid shows where the panel's conflicts are.
+ */
+export const CONFLICT_BG = 'var(--sg-review-conflict-bg, color-mix(in srgb, var(--sg-danger, #dc2626) 12%, transparent))';
+export const CONFLICT_ICON = '!';
+export function pendingFormats(pending, rowId, columns, look = { background: PENDING_BG, icon: PENDING_ICON }) {
+    const rowsByField = new Map();
+    for (const p of pending) {
+        let ids = rowsByField.get(p.field);
+        if (!ids)
+            rowsByField.set(p.field, (ids = new Set()));
+        ids.add(p.rowId);
+    }
+    const out = [];
+    for (const [field, ids] of rowsByField) {
+        const cols = columns.filter((c) => (c.field ?? c.id) === field).map((c) => c.id);
+        out.push({
+            type: 'rule',
+            columns: cols.length ? cols : [field],
+            when: ({ row }) => ids.has(String(rowId(row, 0))),
+            background: look.background,
+            icon: look.icon,
+        });
+    }
+    return out;
+}

package/dist/review/ghost.d.ts

@@ -0,0 +1,17 @@
+import { type ReviewMessages } from './messages.js';
+import type { Proposal } from './types.js';
+type Ghostable = {
+    pendingFor(rowId: string, field: string): Proposal | undefined;
+    messages?: ReviewMessages;
+};
+/**
+ * Whether wrapping this column's `cell` keeps the rest of its cells as they
+ * were. `columns` is every leaf column, which a field type's fill may read.
+ */
+export declare function canGhost(raw: any, sample?: unknown, columns?: ReadonlyArray<any>): boolean;
+/**
+ * Wrap the `cell` of every ghostable column whose field has a pending
+ * proposal. Returns the same array when nothing needs wrapping.
+ */
+export declare function wrapColumns<C extends ReadonlyArray<any>>(cols: C, fields: ReadonlySet<string>, review: Ghostable, sample?: (field: string) => unknown): C;
+export {};

package/dist/review/ghost.js

@@ -0,0 +1,104 @@
+/**
+ * The proposed value drawn in its cell, then the current value struck
+ * through.
+ *
+ * Done by wrapping a column's `cell` template, which needs no free-grid seam.
+ * But setting `cell` turns off the grid's own drawing for the whole column:
+ * field types, checkboxes, list/chips, sparklines and booleans
+ * (`SvGrid.svelte`, every branch gated on `cell == null`). So only columns
+ * that already have a `cell`, or draw plain text, are wrapped. The rest keep
+ * the tint and the glyph from `formats.ts`.
+ *
+ * A field type (`@svgrid/enterprise/fields`, SvGrid Base) counts as plain
+ * text when its type draws no cell of its own (single line text, email,
+ * number...): the check runs on the column as the fields module fills it in,
+ * the way the grid will see it.
+ */
+import { formatValueForExport, getGridExtension, renderComponent } from '@svgrid/grid';
+import { visibleSpaces } from './cluster.js';
+import { isBlank } from './equal.js';
+import { fill } from './messages.js';
+import GhostCell from './GhostCell.svelte';
+/**
+ * Whether wrapping this column's `cell` keeps the rest of its cells as they
+ * were. `columns` is every leaf column, which a field type's fill may read.
+ */
+export function canGhost(raw, sample, columns = []) {
+    if (!raw || raw.columns?.length)
+        return false;
+    const ext = getGridExtension();
+    // The grid draws a field type's own cell when the module has one for it;
+    // otherwise the column draws as an ordinary one.
+    if (raw.fieldType && raw.cell == null && ext?.cell && ext.hasCell?.(raw) !== false)
+        return false;
+    const def = raw.fieldType && ext?.column ? ext.column(raw, columns) : raw;
+    const field = def.field ?? def.id;
+    if (!field || def.sparkline)
+        return false;
+    if (raw.cell != null)
+        return true;
+    if (def.editorType === 'checkbox' || def.editorType === 'list' || def.editorType === 'chips')
+        return false;
+    if (def.cellDataType === 'boolean' || typeof sample === 'boolean')
+        return false;
+    return true;
+}
+/**
+ * Wrap the `cell` of every ghostable column whose field has a pending
+ * proposal. Returns the same array when nothing needs wrapping.
+ */
+export function wrapColumns(cols, fields, review, sample = () => undefined) {
+    if (!fields.size)
+        return cols;
+    const leaves = leafColumns(cols);
+    let changed = false;
+    const out = cols.map((def) => {
+        if (def?.columns?.length) {
+            const inner = wrapColumns(def.columns, fields, review, sample);
+            if (inner === def.columns)
+                return def;
+            changed = true;
+            return { ...def, columns: inner };
+        }
+        const field = def?.field ?? def?.id;
+        if (!fields.has(field) || !canGhost(def, sample(field), leaves))
+            return def;
+        changed = true;
+        const original = def.cell;
+        return {
+            ...def,
+            // Grids published before the core refreshed `columnDef` on a soft
+            // cache hit (`getAllColumns` in core.ts) kept a reused column's old
+            // `cell`, and the peer range admits them. A fresh `fieldProps` object
+            // makes those rebuild the column (same id, so no state resets). A field
+            // type reads its settings from it; the copy holds the same ones.
+            fieldProps: { ...def.fieldProps },
+            cell: (ctx) => {
+                const own = typeof original === 'function' ? original(ctx) : original;
+                const p = review.pendingFor(String(ctx.row.id), field);
+                if (!p)
+                    return own;
+                // The column as the grid holds it: a field type's format is filled in after this wrap.
+                const format = ctx.column?.columnDef?.format ?? def.format;
+                const after = formatValueForExport(p.after, format);
+                const m = review.messages;
+                return renderComponent(GhostCell, {
+                    own,
+                    before: ctx.getValue(),
+                    after,
+                    empty: m?.empty ?? '(empty)',
+                    // The current value too: a narrow cell may have no room to show it struck.
+                    title: fill(m?.proposes ?? '{source} proposes {value}', { source: p.source.label, value: after || (m?.empty ?? '(empty)') }) + (p.reason ? ` - ${p.reason}` : '')
+                        + (isBlank(ctx.getValue()) ? '' : '\n' + fill(m?.nowValue ?? 'Now: {value}', { value: formatValueForExport(ctx.getValue(), format) })),
+                    beforeText: typeof ctx.getValue() === 'string' && !format
+                        ? visibleSpaces(ctx.getValue())
+                        : formatValueForExport(ctx.getValue(), format),
+                });
+            },
+        };
+    });
+    return changed ? out : cols;
+}
+function leafColumns(cols) {
+    return cols.flatMap((c) => (c?.columns?.length ? leafColumns(c.columns) : [c]));
+}

package/dist/review/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @svgrid/enterprise/review - change review. Writes nobody typed (AI helper
+ * results, agent edits, imports, syncs) arrive as proposals held apart from
+ * the data, grouped by the transformation they apply, and are accepted or
+ * rejected a group at a time. Accepted values are written to the app's data,
+ * a cell that changed since the proposal was made is never overwritten, and
+ * every decision is one Ctrl+Z.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { SvGrid } from '@svgrid/grid'
+ *   import { createReview, reviewSmartFill, SvReviewPanel } from '@svgrid/enterprise/review'
+ *
+ *   let rows = $state(initialRows)
+ *   let api = $state()
+ *   const review = createReview({ api: () => api, setRows: (next) => (rows = next) })
+ * </script>
+ *
+ * <SvGrid data={rows} columns={review.columns(columns)} getRowId={(r) => r.id}
+ *   conditionalFormats={review.formats} onApiReady={(a) => (api = a)} />
+ * <SvReviewPanel {review} />
+ * ```
+ *
+ * Adds nothing to `@svgrid/grid`: the tint is `conditionalFormats`, the
+ * proposed value is a wrapped `cell`, the undo step is the public command
+ * context.
+ */
+export { createReview } from './model.svelte.js';
+export type { Review, ReviewOptions, ReviewOutcome, ReviewGridApi, ReviewJSON, ReviewDecision, AddInput } from './model.svelte.js';
+export { createGridTools, registerWebMcpTools } from './agent.js';
+export type { GridTool, GridToolsOptions } from './agent.js';
+export { clusterProposals, showValue } from './cluster.js';
+export type { ClusterOptions } from './cluster.js';
+export { sameValue, isBlank } from './equal.js';
+export { REVIEW_MESSAGES } from './messages.js';
+export type { ReviewMessages } from './messages.js';
+export { pendingFormats, PENDING_BG, PENDING_ICON, CONFLICT_BG, CONFLICT_ICON } from './formats.js';
+export { canGhost } from './ghost.js';
+export { fromSmartFill, fromClassify, fromRows, fromStaged, reviewSmartFill, reviewClassify, blankTargets } from './adapters.js';
+export type { AdapterResult } from './adapters.js';
+export type { Proposal, ProposalInput, ProposalSource, ProposalStatus, ChangeSet, GroupKind, ProposalGroup } from './types.js';
+export { default as SvReviewPanel } from './SvReviewPanel.svelte';