@atscript/ui 0.1.102 → 0.1.104

package/dist/index.cjs

@@ -30,7 +30,7 @@ const UI_FORM_SUFFIX_ICON = "ui.form.suffix.icon";
 const UI_TABLE_WIDTH = "ui.table.width";
 const UI_TABLE_COMPONENT = "ui.table.component";
 const UI_TABLE_SELECT_WITH = "ui.table.selectWith";
-const UI_TABLE_HIDDEN = "ui.table.hidden";
+const UI_TABLE_EXCLUDE = "ui.table.exclude";
 const UI_TABLE_ATTR = "ui.table.attr";
 const UI_TABLE_CLASSES = "ui.table.classes";
 const UI_TABLE_STYLES = "ui.table.styles";
@@ -811,6 +811,35 @@ function setByPath(obj, path, value) {
 	}
 	current[last] = value;
 }
+/**
+* Deletes the own key at a dot-separated path (form-data wrapper aware — derefs
+* `obj.value` first). Walks to the parent WITHOUT vivifying intermediate nodes:
+* if any ancestor is missing, the call is a no-op (nothing to delete).
+*
+* Unlike `setByPath(obj, path, undefined)`, this leaves NO own key behind — the
+* leaf reads as absent (`'k' in parent === false`), which keeps `deepEqual`
+* structural comparisons in sync (a present `undefined` own-key and an absent
+* key are NOT structurally equal under the own-key walk). Used by
+* {@link applyFormChanges} to apply a clear-to-`undefined` change as a delete.
+*
+* Empty path clears the root domain value (`obj.value = undefined`).
+*/
+function deleteByPath(obj, path) {
+	if (!path) {
+		obj.value = void 0;
+		return;
+	}
+	const keys = path.split(".");
+	const last = keys.pop();
+	if (last === void 0) return;
+	let current = obj.value;
+	for (const key of keys) {
+		if (current === null || current === void 0 || typeof current !== "object") return;
+		current = current[key];
+	}
+	if (current === null || current === void 0 || typeof current !== "object") return;
+	delete current[last];
+}
 function parseStaticDefault(raw, prop) {
 	if (typeof raw !== "string") return raw;
 	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
@@ -884,8 +913,11 @@ function detectUnionVariant(value, variants) {
 	const disc = getVariantsDiscriminator(variants);
 	if (disc && value !== null && typeof value === "object") {
 		const tag = value[disc.propertyName];
-		const idx = disc.indexMapping[String(tag)];
-		if (idx !== void 0) return idx;
+		const key = String(tag);
+		if (Object.prototype.hasOwnProperty.call(disc.indexMapping, key)) {
+			const idx = disc.indexMapping[key];
+			if (idx !== void 0) return idx;
+		}
 	}
 	for (let i = 0; i < variants.length; i++) try {
 		if (getVariantValidator(variants[i]).validate(value, true)) return i;
@@ -893,6 +925,35 @@ function detectUnionVariant(value, variants) {
 	return 0;
 }
 //#endregion
+//#region src/form/clone.ts
+/**
+* Structural deep clone of plain JSON-ish data (objects / arrays / primitives /
+* `Date`). Walks OWN-ENUMERABLE keys only (matches the own-key discipline in
+* `diff.ts` — never copies an accidental prototype) and copies leaves by value.
+*
+* `structuredClone` is deliberately NOT used: it throws on functions and on Vue
+* reactive proxies. The optional `unwrap` hook lets a framework caller
+* de-proxy each value first (vue-form passes `toRaw`); the core omits it.
+*
+* The SINGLE deep-clone primitive for the form engine — used by
+* `applyFormChanges`, `buildFormRebase`, and vue-form's baseline snapshot. Do
+* not reimplement structural cloning elsewhere.
+*/
+function deepClone(value, unwrap) {
+	const v = unwrap ? unwrap(value) : value;
+	if (v === null || typeof v !== "object") return v;
+	if (v instanceof Date) return new Date(v.getTime());
+	if (Array.isArray(v)) {
+		const out = [];
+		for (let i = 0; i < v.length; i++) out.push(deepClone(v[i], unwrap));
+		return out;
+	}
+	const src = v;
+	const out = {};
+	for (const k of Object.keys(src)) out[k] = deepClone(src[k], unwrap);
+	return out;
+}
+//#endregion
 //#region src/form/validate.ts
 let defaultValidatorPlugins = [];
 /** Replace the default validator plugins applied to every form/field validator. */
@@ -948,6 +1009,661 @@ function createFieldValidator(prop, opts) {
 	};
 }
 //#endregion
+//#region src/form/diff.ts
+/**
+* Diffs a form's `current` data against its `baseline` snapshot, producing both
+* a changed-fields list and an `@atscript/db` patch object.
+*
+* Both `baseline` and `current` are the WRAPPED form-data container
+* (`{ value: domainData }`) so this reuses {@link getByPath}.
+*
+* Revert-aware: a value edited back to its baseline produces no change and no
+* patch entry.
+*
+* Snapshot contract: the result is NOT a deep copy. `$insert` items, `$replace`
+* arrays, scalar leaf values, and `changes[].before/after` all hold live
+* references into `baseline` / `current`. Callers that keep editing the form
+* after building the patch must snapshot first (e.g. build the patch at submit
+* time on a frozen clone). This is the common Vue v-model flow.
+*/
+function buildFormDiff(def, baseline, current, opts) {
+	const changes = [];
+	const patch = {};
+	const versionColumn = findVersionColumn(def);
+	diffFields(def.fields, "", baseline, current, changes, patch, versionColumn, def.flatMap);
+	if ((opts?.cas ?? true) && versionColumn && Object.keys(patch).length > 0) {
+		const baselineVersion = getByPath(baseline, versionColumn);
+		if (typeof baselineVersion === "number" && Number.isInteger(baselineVersion)) patch.$cas = { [versionColumn]: baselineVersion };
+	}
+	return {
+		isDirty: changes.length > 0,
+		changes,
+		patch
+	};
+}
+/**
+* Diffs a list of sibling fields. `prefix` is the dot-path of the parent
+* context relative to the form root (used only for the change list `path`);
+* patch entries are written into the local `patch` object so callers can place
+* the whole sub-object as a nested partial.
+*
+* `versionColumn` is the top-level `@db.column.version` field name (or
+* undefined). When set, the matching top-level field is skipped entirely — it
+* is server-managed and may only be round-tripped via `$cas`.
+*
+* `inlineFlatMap` is the form's `flatMap`, supplied only at the top-level walk.
+* It lets {@link diffScalarField} read `@db.patch.strategy` off the object
+* ancestors of an INLINED leaf (a dotted-path leaf with no `FormObjectFieldDef`
+* node — `createFormDef` dissolves unlabelled objects into dot-paths). At a
+* default (replace) ancestor the whole sub-object must be emitted. It is
+* intentionally NOT propagated into `diffObjectField` recursion, where the
+* strategy decision is already made per structured object.
+*/
+function diffFields(fields, prefix, baseline, current, changes, patch, versionColumn, inlineFlatMap) {
+	for (const field of fields) {
+		if (field.path === "" && fields.length === 1) {
+			diffLeafRoot(field, baseline, current, changes, patch);
+			continue;
+		}
+		if (field.phantom) continue;
+		if (versionColumn !== void 0 && !prefix && field.path === versionColumn) continue;
+		const fullPath = prefix ? `${prefix}.${field.path}` : field.path;
+		if (isArrayField(field)) {
+			diffArrayField(field, fullPath, baseline, current, changes, patch);
+			continue;
+		}
+		if (isObjectField(field)) {
+			diffObjectField(field, fullPath, baseline, current, changes, patch);
+			continue;
+		}
+		diffScalarField(field, fullPath, baseline, current, changes, patch, inlineFlatMap);
+	}
+}
+/** Single-leaf root form (non-object root). Whole value is the patch. */
+function diffLeafRoot(field, baseline, current, changes, patch) {
+	const before = getByPath(baseline, "");
+	const after = getByPath(current, "");
+	if (deepEqual(before, after)) return;
+	if (isArrayField(field)) {
+		const arrayPatch = diffArray(field, before, after);
+		if (arrayPatch === void 0) return;
+		changes.push({
+			path: "",
+			kind: "array",
+			before,
+			after
+		});
+		patch.value = arrayPatch;
+	} else {
+		changes.push({
+			path: "",
+			kind: "set",
+			before,
+			after
+		});
+		patch.value = after === void 0 ? null : after;
+	}
+}
+/** Scalar / union / tuple / ref field — whole-value compare; clear → null. */
+function diffScalarField(field, fullPath, baseline, current, changes, patch, inlineFlatMap) {
+	const before = getByPath(baseline, fullPath);
+	const after = getByPath(current, fullPath);
+	if (deepEqual(before, after)) return;
+	changes.push({
+		path: fullPath,
+		kind: "set",
+		before,
+		after
+	});
+	if (inlineFlatMap && field.path.includes(".")) {
+		const cutoff = inlinedReplaceCutoff(field.path, inlineFlatMap);
+		if (cutoff !== void 0) {
+			const prefixLen = fullPath.length - field.path.length;
+			const sub = getByPath(current, prefixLen > 0 ? fullPath.slice(0, prefixLen) + cutoff : cutoff);
+			setPatchLeaf(patch, cutoff, sub === void 0 ? null : sub);
+			return;
+		}
+	}
+	setPatchLeaf(patch, field.path, after === void 0 ? null : after);
+}
+/**
+* For a dotted INLINED leaf path, returns the path of the shallowest object
+* ancestor whose `@db.patch.strategy` is the default (`replace`), or undefined
+* when every ancestor is `merge` (then the leaf partial is correct). At a
+* replace ancestor the whole sub-object must be present in the patch.
+*
+* Walks ancestor segments (`a`, `a.b`, … but not the leaf itself); the first
+* one that is an object AND not merge is the cutoff. merge does NOT propagate,
+* so a default-replace level below a merge level still cuts off there.
+*/
+function inlinedReplaceCutoff(leafPath, flatMap) {
+	const segs = leafPath.split(".");
+	let acc = "";
+	for (let i = 0; i < segs.length - 1; i++) {
+		acc = acc ? `${acc}.${segs[i]}` : segs[i];
+		const prop = flatMap.get(acc);
+		if (!prop || prop.type.kind !== "object") continue;
+		if (getFieldMeta(prop, "db.patch.strategy") !== "merge") return acc;
+	}
+}
+/**
+* Inlined-or-structured object field — recurse, emit a nested partial OR the
+* whole sub-object depending on the field's `@db.patch.strategy`.
+*
+* atscript-db's DEFAULT nested-object patch strategy is `replace` (strict —
+* every required child must be present, else 400; omitted optionals are
+* null-filled). A changed-leaves-only partial is a valid patch ONLY when the
+* object field carries `@db.patch.strategy 'merge'`. For the default (replace)
+* case we therefore emit the WHOLE current sub-object so the validator passes
+* and no optional leaf is silently nulled. `merge` does NOT propagate, so a
+* descendant object without its own `merge` again emits its full sub-object
+* (handled by recursion — `diffFields` re-enters this function per child).
+*
+* Wholesale-clear: if the sub-object was a defined object in `baseline` but is
+* now undefined/null, emit `field: null` (object removed) instead of a partial
+* of nulled leaves.
+*/
+function diffObjectField(field, fullPath, baseline, current, changes, patch) {
+	const beforeObj = getByPath(baseline, fullPath);
+	const afterObj = getByPath(current, fullPath);
+	const nested = {};
+	diffFields(field.objectDef.fields, fullPath, baseline, current, changes, nested, void 0, field.objectDef.flatMap);
+	if ((afterObj === void 0 || afterObj === null) && isPlainObject(beforeObj)) {
+		setPatchLeaf(patch, field.path, null);
+		return;
+	}
+	if (Object.keys(nested).length === 0) return;
+	if (getFieldMeta(field.prop, "db.patch.strategy") === "merge") setPatchLeaf(patch, field.path, nested);
+	else setPatchLeaf(patch, field.path, afterObj === void 0 ? null : afterObj);
+}
+/** Array field — keyed → $update/$insert/$remove; unkeyed → $replace. */
+function diffArrayField(field, fullPath, baseline, current, changes, patch) {
+	const before = getByPath(baseline, fullPath);
+	const after = getByPath(current, fullPath);
+	if (deepEqual(before, after)) return;
+	const arrayPatch = diffArray(field, before, after);
+	if (arrayPatch === void 0) return;
+	changes.push({
+		path: fullPath,
+		kind: "array",
+		before,
+		after
+	});
+	setPatchLeaf(patch, field.path, arrayPatch);
+}
+/**
+* Produces a `TArrayPatch` value for one array field, or `undefined` when no
+* real op results (the caller then skips the field entirely).
+*
+* - Keyed arrays (item object has `@expect.array.key`): emit `$update`
+*   (key + changed leaves), `$insert` (wholly-new items, whole), `$remove`
+*   (key only). Reorder-only (same key membership, same content, different
+*   order) → `$replace` (key-ops can't express a pure reorder).
+*   Ambiguous keys (duplicate or missing key values) → `$replace` (the only
+*   faithful op when key identity is unreliable).
+* - Unkeyed object arrays / primitive arrays: `$replace` with the whole array.
+*   Primitive arrays with `@expect.array.uniqueItems` use by-value
+*   `$insert` / `$remove` (set semantics).
+*
+* Deliberate `$insert`-not-`$upsert`: wholly-new keyed items use `$insert`
+* (pure append) rather than `$upsert`. This is safe because `$insert` is only
+* ever used for keys ABSENT from baseline; existing keys go through `$update`.
+* `$upsert` would dedupe-by-key, which we don't need given that invariant.
+*/
+function diffArray(field, before, after) {
+	const beforeArr = Array.isArray(before) ? before : [];
+	const afterArr = Array.isArray(after) ? after : [];
+	const keyProps = getArrayKeyProps(field.itemType);
+	if (keyProps.length > 0) return diffKeyedArray(beforeArr, afterArr, keyProps);
+	if (getFieldMeta(field.prop, "expect.array.uniqueItems") !== void 0 && isPrimitiveItem(field)) {
+		const setPatch = diffUniqueArray(beforeArr, afterArr);
+		if (setPatch) return setPatch;
+	}
+	return { $replace: afterArr };
+}
+/**
+* Keyed array diff. Reorder-only (same membership) falls back to $replace.
+*
+* Returns `undefined` when no $update/$insert/$remove op is produced (so the
+* caller skips the field rather than emitting a malformed empty `{}`).
+*
+* Ambiguity fallback: if either side has DUPLICATE key buckets, or ANY element
+* is missing all of its key values, key identity is unreliable — fall back to
+* `{ $replace: after }`, the only faithful op (last-write-wins collapse would
+* silently drop items, and a key-less `$update` is unmatchable by the DB).
+*/
+function diffKeyedArray(before, after, keyProps) {
+	if (hasKeylessItem(before, keyProps) || hasKeylessItem(after, keyProps)) return { $replace: after };
+	const beforeByKey = /* @__PURE__ */ new Map();
+	for (const el of before) if (isPlainObject(el)) beforeByKey.set(keyOf(el, keyProps), el);
+	const afterByKey = /* @__PURE__ */ new Map();
+	for (const el of after) if (isPlainObject(el)) afterByKey.set(keyOf(el, keyProps), el);
+	if (beforeByKey.size !== before.length || afterByKey.size !== after.length) return { $replace: after };
+	if (beforeByKey.size === afterByKey.size) {
+		let sameMembershipAndContent = true;
+		for (const [k, el] of afterByKey) {
+			const prev = beforeByKey.get(k);
+			if (prev === void 0 || !deepEqual(prev, el)) {
+				sameMembershipAndContent = false;
+				break;
+			}
+		}
+		if (sameMembershipAndContent) return { $replace: after };
+	}
+	const $insert = [];
+	const $update = [];
+	const $remove = [];
+	for (const [k, el] of afterByKey) {
+		const prev = beforeByKey.get(k);
+		if (prev === void 0) {
+			$insert.push(el);
+			continue;
+		}
+		if (!deepEqual(prev, el)) {
+			const partial = buildKeyedUpdate(prev, el, keyProps);
+			if (partial) $update.push(partial);
+		}
+	}
+	for (const [k, el] of beforeByKey) if (!afterByKey.has(k)) $remove.push(pickKeys(el, keyProps));
+	return arrayOps({
+		$update,
+		$insert,
+		$remove
+	});
+}
+/** Builds a `$update` partial: key fields + changed leaves only. */
+function buildKeyedUpdate(prev, next, keyProps) {
+	const partial = {};
+	for (const k of keyProps) partial[k] = next[k];
+	let changed = false;
+	const allKeys = new Set([...Object.keys(prev), ...Object.keys(next)]);
+	for (const k of allKeys) {
+		if (keyProps.includes(k)) continue;
+		const a = prev[k];
+		const b = next[k];
+		if (!deepEqual(a, b)) {
+			partial[k] = b === void 0 ? null : b;
+			changed = true;
+		}
+	}
+	return changed ? partial : void 0;
+}
+/** Primitive uniqueItems set diff. Returns undefined if neither side differs. */
+function diffUniqueArray(before, after) {
+	const beforeSet = new Set(before.map((v) => stableKey(v)));
+	const afterSet = new Set(after.map((v) => stableKey(v)));
+	const $insert = [];
+	const $remove = [];
+	const seenInsert = /* @__PURE__ */ new Set();
+	const seenRemove = /* @__PURE__ */ new Set();
+	for (const v of after) {
+		const k = stableKey(v);
+		if (!beforeSet.has(k) && !seenInsert.has(k)) {
+			$insert.push(v);
+			seenInsert.add(k);
+		}
+	}
+	for (const v of before) {
+		const k = stableKey(v);
+		if (!afterSet.has(k) && !seenRemove.has(k)) {
+			$remove.push(v);
+			seenRemove.add(k);
+		}
+	}
+	return arrayOps({
+		$insert,
+		$remove
+	});
+}
+/**
+* Assembles a `TArrayPatch` from named op-arrays, dropping empty ones. Returns
+* `undefined` when no op carries any item, so the caller skips the field rather
+* than emitting a malformed empty `{}`.
+*/
+function arrayOps(ops) {
+	const result = {};
+	for (const k in ops) if (ops[k].length > 0) result[k] = ops[k];
+	return Object.keys(result).length > 0 ? result : void 0;
+}
+/** Reads `@expect.array.key` props from an array item's object type. */
+function getArrayKeyProps(itemType) {
+	if (itemType.type.kind !== "object") return [];
+	const props = itemType.type.props;
+	const keys = [];
+	for (const [name, prop] of props.entries()) if (getFieldMeta(prop, "expect.array.key") !== void 0) keys.push(name);
+	return keys;
+}
+/** True when the array's item type is a primitive (designType, kind === ''). */
+function isPrimitiveItem(field) {
+	return field.itemType.type.kind === "";
+}
+/** Finds the form's `@db.column.version` column name, if any (top-level only). */
+function findVersionColumn(def) {
+	for (const [path, prop] of def.flatMap.entries()) {
+		if (!path || path.includes(".")) continue;
+		if (getFieldMeta(prop, "db.column.version") !== void 0) return path;
+	}
+}
+/** True when any element lacks ALL of its key values (un-keyable identity). */
+function hasKeylessItem(arr, keyProps) {
+	for (const el of arr) {
+		if (!isPlainObject(el)) return true;
+		let hasAnyKey = false;
+		for (const k of keyProps) {
+			const v = el[k];
+			if (v !== void 0 && v !== null) {
+				hasAnyKey = true;
+				break;
+			}
+		}
+		if (!hasAnyKey) return true;
+	}
+	return false;
+}
+/** Composite key string for a keyed-array element. */
+function keyOf(el, keyProps) {
+	if (keyProps.length === 1) return stableKey(el[keyProps[0]]);
+	return keyProps.map((k) => stableKey(el[k])).join(" ");
+}
+/** Picks only the key fields from an element (for $remove). */
+function pickKeys(el, keyProps) {
+	const out = {};
+	for (const k of keyProps) out[k] = el[k];
+	return out;
+}
+/** Writes a value into a (possibly dotted) leaf path on a local patch object. */
+function setPatchLeaf(patch, path, value) {
+	if (!path.includes(".")) {
+		patch[path] = value;
+		return;
+	}
+	const keys = path.split(".");
+	const last = keys.pop();
+	let cur = patch;
+	for (const k of keys) {
+		let next = cur[k];
+		if (next === void 0 || next === null || typeof next !== "object") {
+			next = {};
+			cur[k] = next;
+		}
+		cur = next;
+	}
+	cur[last] = value;
+}
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* Stable string key for primitives / values (used for set membership).
+*
+* Key equality is TYPE-STRICT: a number `1` and a string `'1'` produce
+* distinct keys, so a keyed-array item whose key changes JS representation
+* between baseline and current is treated as a remove + insert. Callers that
+* round-trip keys with loose typing should normalise the key type first.
+*/
+function stableKey(v) {
+	if (typeof v === "string") return `s:${v}`;
+	if (typeof v === "number" || typeof v === "boolean") return `p:${String(v)}`;
+	if (v === null) return "null";
+	if (v === void 0) return "undef";
+	return `j:${JSON.stringify(v)}`;
+}
+/**
+* Structural deep equality (order-sensitive for arrays). `NaN` equals `NaN`
+* (revert-aware for NaN scalars) while `0` / `-0` stay equal (matches DB
+* intent — `===` treats them equal, only NaN is special-cased).
+*
+* The single comparator shared across the form engine: diff, conflict
+* detection ({@link buildFormRebase}), and apply all route through this — never
+* reimplement equality elsewhere.
+*/
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number") return Number.isNaN(a) && Number.isNaN(b);
+	if (a === null || b === null || a === void 0 || b === void 0) return false;
+	if (typeof a !== "object" || typeof b !== "object") return false;
+	const aIsArr = Array.isArray(a);
+	const bIsArr = Array.isArray(b);
+	if (aIsArr !== bIsArr) return false;
+	if (aIsArr && bIsArr) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	const ao = a;
+	const bo = b;
+	const aKeys = Object.keys(ao);
+	const bKeys = Object.keys(bo);
+	if (aKeys.length !== bKeys.length) return false;
+	for (const k of aKeys) {
+		if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
+		if (!deepEqual(ao[k], bo[k])) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/form/dirty.ts
+/**
+* True when the field at dot-path `path` is dirty given a {@link FormFieldChange}
+* list (as produced by {@link buildFormDiff}).
+*
+* The change list is leaf-grained for scalars/objects but WHOLE-ARRAY for arrays,
+* so a field at `path` is dirty iff some change path equals `path` OR starts with
+* `path + "."`:
+*
+* - scalar / leaf field (incl. nested `address.city`) → exact match.
+* - object / section container → no entry at its own path, only its leaves →
+*   matched by the PREFIX branch.
+* - whole-array field → one entry at the array root → exact match.
+* - a field rendered for an array-ITEM leaf (e.g. `items.0.qty`) → NOT detectable:
+*   the array diff emits a single whole-array change at the array root, never
+*   per-item leaf paths, so this correctly returns false (the array container
+*   lights up instead). This is a known, documented limitation.
+*
+* The prefix uses `path + "."` so field `item` never matches a change at `items`
+* (no false positives).
+*
+* Empty `path` `''` is the wrapped form root — every change is nested under it,
+* so it is considered dirty iff there are ANY changes.
+*/
+function isPathDirty(changes, path) {
+	if (path === "") return changes.length > 0;
+	const prefix = `${path}.`;
+	for (const change of changes) if (change.path === path || change.path.startsWith(prefix)) return true;
+	return false;
+}
+/**
+* Precomputes the set of ALL dirty paths from a {@link FormFieldChange} list so
+* that membership is an O(1) `Set.has(path)` instead of {@link isPathDirty}'s
+* per-call O(changes) prefix scan. Callers that probe many fields against the
+* same change list (e.g. a form rendering one field per leaf) build this once
+* and query it per field.
+*
+* For each change path `C` it adds `C` AND every dot-prefix ancestor of `C`
+* (so `'address.city'` adds both `'address.city'` and `'address'`), matching
+* `isPathDirty`'s "exact OR `path + '.'` prefix" predicate — an ancestor
+* container is dirty exactly when some change is nested under it. The wrapped
+* root `''` is added iff there are ANY changes, mirroring `isPathDirty('')`.
+*
+* INVARIANT (locked, tested): for EVERY path `P`,
+* `collectDirtyPaths(changes).has(P) === isPathDirty(changes, P)`. This is a
+* precompute of the SAME predicate, not a second one — keep them in lockstep.
+*/
+function collectDirtyPaths(changes) {
+	const dirty = /* @__PURE__ */ new Set();
+	if (changes.length === 0) return dirty;
+	dirty.add("");
+	for (const change of changes) {
+		const path = change.path;
+		dirty.add(path);
+		let dot = path.indexOf(".");
+		while (dot !== -1) {
+			dirty.add(path.slice(0, dot));
+			dot = path.indexOf(".", dot + 1);
+		}
+	}
+	return dirty;
+}
+//#endregion
+//#region src/form/apply.ts
+/**
+* Applies a {@link FormFieldChange} list onto a WRAPPED form-data container
+* (`{ value: domainData }`), mutating it in place and returning the same
+* reference. The inverse direction of {@link buildFormDiff}: where the diff
+* READS `(baseline, current)` into changes, this WRITES changes onto data.
+*
+* IMPORTANT: pass a CLONE, never the live fetched row — every write mutates
+* `data` directly. Callers that need the original intact should
+* `deepClone(data)` first (see {@link deepClone}).
+*
+* Per-change semantics (the single place the apply rules live, so
+* {@link buildFormRebase} stays consistent):
+*
+* - `kind: 'set'`:
+*   - `change.after === undefined` → DELETE the own key at `change.path` (walk
+*     to parent, `delete`). A cleared field must read as ABSENT, not as a
+*     present `undefined` own-key — otherwise a re-diff sees a structural
+*     mismatch where the form intends "no value". `setByPath(…, undefined)`
+*     leaves an own key behind, so we use {@link deleteByPath} instead.
+*   - otherwise → `setByPath(data, change.path, change.after)`.
+* - `kind: 'array'`: whole-array set via `setByPath(data, change.path,
+*   change.after)` (LOCKED Option A — no per-element merge; the diff already
+*   carried the full after-array).
+*
+* The `def` is currently unused by the apply walk (paths fully describe the
+* write target) but is part of the signature for parity with
+* `buildFormDiff`/`buildFormRebase`, so the rebase engine threads one `def`
+* uniformly through diff + apply.
+*/
+function applyFormChanges(_def, data, changes) {
+	for (const change of changes) if (change.kind === "set" && change.after === void 0) deleteByPath(data, change.path);
+	else setByPath(data, change.path, change.after);
+	return data;
+}
+//#endregion
+//#region src/form/rebase.ts
+/**
+* Pure 3-way rebase for a change-tracked form. Given the current baseline `B0`,
+* the live form `C`, and a fresh upstream `U`, produces the form rewritten as
+* `U` + the local diff (`C` vs `B0`) reapplied on top:
+*
+* - Fields the user never touched adopt upstream's value.
+* - Local edits survive (reapplied onto the upstream clone).
+* - Fields changed on BOTH sides to different values are conflicts, resolved by
+*   `opts.conflict` (`'ours'` keeps local, `'theirs'` takes upstream).
+*
+* All inputs are WRAPPED form-data containers (`{ value: domainData }`). The
+* result `next` is a fresh container; no input is mutated.
+*
+* `diffOptions` are forwarded to BOTH internal `buildFormDiff` passes so the
+* same field exclusions apply (notably the `@db.column.version` column and the
+* `$cas` policy) on the local and upstream sides — keep them identical to the
+* options the caller uses for its own change tracking.
+*/
+function buildFormRebase(def, baseline, current, upstream, opts, diffOptions) {
+	const conflictMode = opts?.conflict ?? "ours";
+	const local = buildFormDiff(def, baseline, current, diffOptions).changes;
+	const upstreamChanges = buildFormDiff(def, baseline, upstream, diffOptions).changes;
+	const upstreamByPath = /* @__PURE__ */ new Map();
+	for (const uc of upstreamChanges) upstreamByPath.set(uc.path, uc);
+	const next = deepClone(upstream);
+	const conflicts = [];
+	for (const lc of local) {
+		const clearedAncestor = findClearedAncestor(lc.path, baseline, upstream);
+		if (clearedAncestor !== void 0) {
+			conflicts.push(clearedAncestor);
+			if (conflictMode === "ours") setByPath(next, clearedAncestor, deepClone(getByPath(current, clearedAncestor)));
+			continue;
+		}
+		const uc = upstreamByPath.get(lc.path);
+		if (uc !== void 0) {
+			if (deepEqual(lc.after, uc.after)) continue;
+			conflicts.push(lc.path);
+			if (conflictMode === "ours") reapply(def, next, lc);
+			continue;
+		}
+		reapply(def, next, lc);
+	}
+	const reapplied = buildFormDiff(def, upstream, deepClone(next), diffOptions).changes;
+	return {
+		next,
+		conflicts: [...new Set(conflicts)],
+		reapplied
+	};
+}
+/**
+* Reapplies a single local change onto `next`, DEEP-CLONING its `after` value
+* first. `lc.after` is a LIVE reference into `current` (buildFormDiff holds live
+* refs), so for a `kind:'array'` or whole-object/union `set` change a raw apply
+* would make `next.value`'s node `===` `current.value`'s node — violating the
+* `FormRebaseResult.next` contract ("never aliases any input container"). The
+* ancestor-clear branch already deep-clones before writing; this keeps the two
+* leaf-reapply sites consistent.
+*/
+function reapply(def, next, lc) {
+	applyFormChanges(def, next, [{
+		...lc,
+		after: deepClone(lc.after)
+	}]);
+}
+/**
+* Returns the SHALLOWEST strict ancestor of `leafPath` that was an object/array
+* in `baseline` but is `null`/`undefined` in `upstream` (upstream cleared the
+* subtree), or `undefined` when no ancestor was cleared. The leaf path itself is
+* never considered an ancestor.
+*/
+function findClearedAncestor(leafPath, baseline, upstream) {
+	if (!leafPath.includes(".")) return void 0;
+	const segs = leafPath.split(".");
+	let acc = "";
+	for (let i = 0; i < segs.length - 1; i++) {
+		acc = acc ? `${acc}.${segs[i]}` : segs[i];
+		const base = getByPath(baseline, acc);
+		if (typeof base !== "object" || base === null) continue;
+		const up = getByPath(upstream, acc);
+		if (up === null || up === void 0) return acc;
+	}
+}
+//#endregion
+//#region src/form/union-detect.ts
+/**
+* True when ANY union field in the form resolves to a DIFFERENT discriminated
+* variant between two wrapped data containers. A variant picker typically
+* detects its variant index once at setup and keys the variant subtree on it,
+* so a rebase that lands a different variant (via conflict OR an upstream-only
+* switch) needs a remount to re-detect. This walks union + nested-object fields
+* and compares `detectUnionVariant` at each union path.
+*
+* Scope note (pragmatic): walks standalone + nested-OBJECT union fields. Unions
+* nested INSIDE array items are not walked — an array renderer that keeps a
+* stable per-item key across in-place value mutations would not remount an
+* existing row's picker on an upstream-driven variant flip, but that collision
+* (a 3-way rebase landing a different union variant inside an unchanged array
+* row) is a rare edge. TODO: extend to array-item unions if a real consumer
+* hits a stuck picker inside an array row.
+*/
+function unionVariantChanged(def, before, after) {
+	return walkUnionFields(def.fields, "", before, after);
+}
+function walkUnionFields(fields, prefix, before, after) {
+	for (const field of fields) {
+		if (field.phantom) continue;
+		const fullPath = field.path ? prefix ? `${prefix}.${field.path}` : field.path : prefix;
+		if (isUnionField(field)) {
+			const variants = field.unionVariants;
+			if (variants.length > 1) {
+				if (detectUnionVariant(getByPath(before, fullPath), variants) !== detectUnionVariant(getByPath(after, fullPath), variants)) return true;
+			}
+			continue;
+		}
+		if (isObjectField(field)) {
+			const objectDef = field.objectDef;
+			if (walkUnionFields(objectDef.fields, fullPath, before, after)) return true;
+		}
+	}
+	return false;
+}
+//#endregion
 //#region src/form/error-utils.ts
 /**
 * Framework-agnostic helpers for working with form-error maps keyed by
@@ -1432,6 +2148,7 @@ function createTableDef(meta, preDeserializedType) {
 			const kind = prop.type.kind;
 			if (path.includes(".") || kind === "object" || kind === "array") continue;
 		}
+		if (getFieldMeta(prop, "ui.table.exclude") !== void 0) continue;
 		const fieldMeta = meta.fields[path];
 		const options = extractLiteralOptions(prop);
 		const valueHelpInfo = extractValueHelp(prop);
@@ -1448,7 +2165,6 @@ function createTableDef(meta, preDeserializedType) {
 			sortable: fieldMeta?.sortable ?? false,
 			filterable: fieldMeta?.filterable ?? false,
 			nullable: prop.optional === true,
-			visible: getFieldMeta(prop, UI_TABLE_HIDDEN) === void 0,
 			width: getFieldMeta(prop, UI_TABLE_WIDTH),
 			maxLen: maxLengthMeta?.length,
 			order: getFieldMeta(prop, "ui.table.order") ?? Infinity,
@@ -1464,6 +2180,7 @@ function createTableDef(meta, preDeserializedType) {
 		type,
 		columns,
 		flatMap,
+		fetchableFields: new Set(Object.keys(meta.fields)),
 		primaryKeys: meta.primaryKeys,
 		preferredId: meta.preferredId ?? meta.primaryKeys,
 		versionColumn: meta.versionColumn,
@@ -1537,10 +2254,6 @@ function str(value) {
 }
 //#endregion
 //#region src/table/column-resolver.ts
-/** Get visible columns only, already sorted by order. */
-function getVisibleColumns(def) {
-	return def.columns.filter((c) => c.visible);
-}
 /** Get sortable columns. */
 function getSortableColumns(def) {
 	return def.columns.filter((c) => c.sortable);
@@ -1621,11 +2334,11 @@ exports.UI_FORM_VALIDATE = UI_FORM_VALIDATE;
 exports.UI_TABLE_ATTR = UI_TABLE_ATTR;
 exports.UI_TABLE_CLASSES = UI_TABLE_CLASSES;
 exports.UI_TABLE_COMPONENT = UI_TABLE_COMPONENT;
+exports.UI_TABLE_EXCLUDE = UI_TABLE_EXCLUDE;
 exports.UI_TABLE_FN_ATTR = UI_TABLE_FN_ATTR;
 exports.UI_TABLE_FN_CLASSES = UI_TABLE_FN_CLASSES;
 exports.UI_TABLE_FN_PREFIX = UI_TABLE_FN_PREFIX;
 exports.UI_TABLE_FN_STYLES = UI_TABLE_FN_STYLES;
-exports.UI_TABLE_HIDDEN = UI_TABLE_HIDDEN;
 exports.UI_TABLE_ORDER = UI_TABLE_ORDER;
 exports.UI_TABLE_SELECT_WITH = UI_TABLE_SELECT_WITH;
 exports.UI_TABLE_STYLES = UI_TABLE_STYLES;
@@ -1634,16 +2347,23 @@ exports.UI_TABLE_WIDTH = UI_TABLE_WIDTH;
 exports.UI_TYPE = UI_TYPE;
 exports.ValueHelpClient = ValueHelpClient;
 exports.WF_ACTION_WITH_DATA = WF_ACTION_WITH_DATA;
+exports.applyFormChanges = applyFormChanges;
 exports.asArray = asArray;
 exports.buildDescendantErrorCounts = buildDescendantErrorCounts;
+exports.buildFormDiff = buildFormDiff;
+exports.buildFormRebase = buildFormRebase;
 exports.buildGridClasses = buildGridClasses;
 exports.buildUnionVariants = buildUnionVariants;
+exports.collectDirtyPaths = collectDirtyPaths;
 exports.createFieldValidator = createFieldValidator;
 exports.createFormData = createFormData;
 exports.createFormDef = createFormDef;
 exports.createFormValueResolver = createFormValueResolver;
 exports.createTableDef = createTableDef;
+exports.deepClone = deepClone;
+exports.deepEqual = deepEqual;
 exports.defaultResolver = defaultResolver;
+exports.deleteByPath = deleteByPath;
 exports.detectUnionVariant = detectUnionVariant;
 exports.enforceScale = enforceScale;
 exports.extractLiteralOptions = extractLiteralOptions;
@@ -1665,11 +2385,11 @@ exports.getMetaEntry = getMetaEntry;
 exports.getResolver = getResolver;
 exports.getSortableColumns = getSortableColumns;
 exports.getThousandsSeparator = getThousandsSeparator;
-exports.getVisibleColumns = getVisibleColumns;
 exports.groupInteger = groupInteger;
 exports.hasComputedAnnotations = hasComputedAnnotations;
 exports.isArrayField = isArrayField;
 exports.isObjectField = isObjectField;
+exports.isPathDirty = isPathDirty;
 exports.isPureLiteralUnion = isPureLiteralUnion;
 exports.isTupleField = isTupleField;
 exports.isUnionField = isUnionField;
@@ -1700,4 +2420,5 @@ exports.setDefaultValidatorPlugins = setDefaultValidatorPlugins;
 exports.setResolver = setResolver;
 exports.splitDecimalString = splitDecimalString;
 exports.str = str;
+exports.unionVariantChanged = unionVariantChanged;
 exports.valueHelpDictPaths = valueHelpDictPaths;