@atscript/ui 0.1.102 → 0.1.103

package/dist/index.cjs

@@ -948,6 +948,435 @@ 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).
+*/
+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/error-utils.ts
 /**
 * Framework-agnostic helpers for working with form-error maps keyed by
@@ -1636,6 +2065,7 @@ exports.ValueHelpClient = ValueHelpClient;
 exports.WF_ACTION_WITH_DATA = WF_ACTION_WITH_DATA;
 exports.asArray = asArray;
 exports.buildDescendantErrorCounts = buildDescendantErrorCounts;
+exports.buildFormDiff = buildFormDiff;
 exports.buildGridClasses = buildGridClasses;
 exports.buildUnionVariants = buildUnionVariants;
 exports.createFieldValidator = createFieldValidator;

package/dist/index.d.cts

@@ -484,6 +484,73 @@ declare function createFieldValidator(prop: TAtscriptAnnotatedType, opts?: TFiel
   context: unknown;
 }) => true | string;
 //#endregion
+//#region src/form/diff.d.ts
+/**
+ * One field that differs between baseline and current.
+ *
+ * - `kind: 'set'` — scalar / object / union / tuple field whose value changed
+ *   (including a clear-to-`null`). `before` / `after` are the whole values at
+ *   `path`.
+ * - `kind: 'array'` — array field whose membership or item content changed.
+ *   `before` / `after` are the whole arrays.
+ *
+ * NOTE: `before` / `after` hold live references into the supplied `baseline` /
+ * `current` containers — see {@link buildFormDiff} for the snapshot contract.
+ */
+interface FormFieldChange {
+  /** Dot-separated path relative to the form root (matches FormFieldDef.path). */
+  path: string;
+  kind: "set" | "array";
+  before: unknown;
+  after: unknown;
+}
+/** Options for {@link buildFormDiff}. */
+interface FormDiffOptions {
+  /**
+   * Optimistic-concurrency control. When `true` (default), a top-level
+   * `$cas: { [versionColumn]: baselineVersion }` sibling is auto-included in
+   * the patch whenever the form has a `@db.column.version` column AND the
+   * patch is non-empty AND a baseline version value exists. `false` suppresses
+   * it entirely.
+   *
+   * Independent of `$cas`, the `@db.column.version` column is ALWAYS excluded
+   * from the SET diff: it is server-managed, and a direct write to it is
+   * rejected by `@atscript/db` (`DbError('VERSION_COLUMN_WRITE')`). It is only
+   * ever round-tripped through `$cas`.
+   */
+  cas?: boolean;
+}
+/** Result of {@link buildFormDiff}. */
+interface FormDiffResult {
+  /** True when at least one field changed (revert-aware). */
+  isDirty: boolean;
+  /** Per-field changes (revert-aware — reverted fields are absent). */
+  changes: FormFieldChange[];
+  /**
+   * `@atscript/db` patch object — flat, keyed by field name. Empty `{}` when
+   * nothing changed. Carries a top-level `$cas` sibling when `opts.cas` is on
+   * and a version column exists.
+   */
+  patch: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+declare function buildFormDiff(def: FormDef, baseline: Record<string, unknown>, current: Record<string, unknown>, opts?: FormDiffOptions): FormDiffResult;
+//#endregion
 //#region src/form/error-utils.d.ts
 /**
  * Framework-agnostic helpers for working with form-error maps keyed by
@@ -912,4 +979,4 @@ declare function getFilterableColumns(def: TableDef): ColumnDef[];
 /** Find a column by path. */
 declare function getColumn(def: TableDef, path: string): ColumnDef | undefined;
 //#endregion
-export { type ClientFactory, type ColumnDef, type CurrencyDisplay, DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, type DecimalParts, EXPECT_MAX_LENGTH, type FieldMeta, type FieldResolver, type FormActionInfo, type FormArrayFieldDef, type FormDef, type FormFieldDef, type FormObjectFieldDef, type FormTupleFieldDef, type FormUnionFieldDef, type FormUnionVariant, type FormatDecimalOptions, type GridSpanArgs, type GridSpec, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, type MeasurementInfo, type MetaCacheEntry, type MetaResponse, type PaginationControl, type RelationInfo, type ResolvedValueHelp, type SearchIndexInfo, type SortControl, StaticFieldResolver, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TFieldValidatorOptions, type TFormAction, type TFormEntryOptions, type TFormValidatorCallOptions, type TFormValueResolver, type TResolveOptions, type TableActionsModel, type TableDef, type TableQueryState, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, type ValueHelpInfo, type ValueHelpResult, type ValueHelpSearchOptions, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };
+export { type ClientFactory, type ColumnDef, type CurrencyDisplay, DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, type DecimalParts, EXPECT_MAX_LENGTH, type FieldMeta, type FieldResolver, type FormActionInfo, type FormArrayFieldDef, type FormDef, type FormDiffOptions, type FormDiffResult, type FormFieldChange, type FormFieldDef, type FormObjectFieldDef, type FormTupleFieldDef, type FormUnionFieldDef, type FormUnionVariant, type FormatDecimalOptions, type GridSpanArgs, type GridSpec, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, type MeasurementInfo, type MetaCacheEntry, type MetaResponse, type PaginationControl, type RelationInfo, type ResolvedValueHelp, type SearchIndexInfo, type SortControl, StaticFieldResolver, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TFieldValidatorOptions, type TFormAction, type TFormEntryOptions, type TFormValidatorCallOptions, type TFormValueResolver, type TResolveOptions, type TableActionsModel, type TableDef, type TableQueryState, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, type ValueHelpInfo, type ValueHelpResult, type ValueHelpSearchOptions, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildFormDiff, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };

package/dist/index.d.mts

@@ -484,6 +484,73 @@ declare function createFieldValidator(prop: TAtscriptAnnotatedType, opts?: TFiel
   context: unknown;
 }) => true | string;
 //#endregion
+//#region src/form/diff.d.ts
+/**
+ * One field that differs between baseline and current.
+ *
+ * - `kind: 'set'` — scalar / object / union / tuple field whose value changed
+ *   (including a clear-to-`null`). `before` / `after` are the whole values at
+ *   `path`.
+ * - `kind: 'array'` — array field whose membership or item content changed.
+ *   `before` / `after` are the whole arrays.
+ *
+ * NOTE: `before` / `after` hold live references into the supplied `baseline` /
+ * `current` containers — see {@link buildFormDiff} for the snapshot contract.
+ */
+interface FormFieldChange {
+  /** Dot-separated path relative to the form root (matches FormFieldDef.path). */
+  path: string;
+  kind: "set" | "array";
+  before: unknown;
+  after: unknown;
+}
+/** Options for {@link buildFormDiff}. */
+interface FormDiffOptions {
+  /**
+   * Optimistic-concurrency control. When `true` (default), a top-level
+   * `$cas: { [versionColumn]: baselineVersion }` sibling is auto-included in
+   * the patch whenever the form has a `@db.column.version` column AND the
+   * patch is non-empty AND a baseline version value exists. `false` suppresses
+   * it entirely.
+   *
+   * Independent of `$cas`, the `@db.column.version` column is ALWAYS excluded
+   * from the SET diff: it is server-managed, and a direct write to it is
+   * rejected by `@atscript/db` (`DbError('VERSION_COLUMN_WRITE')`). It is only
+   * ever round-tripped through `$cas`.
+   */
+  cas?: boolean;
+}
+/** Result of {@link buildFormDiff}. */
+interface FormDiffResult {
+  /** True when at least one field changed (revert-aware). */
+  isDirty: boolean;
+  /** Per-field changes (revert-aware — reverted fields are absent). */
+  changes: FormFieldChange[];
+  /**
+   * `@atscript/db` patch object — flat, keyed by field name. Empty `{}` when
+   * nothing changed. Carries a top-level `$cas` sibling when `opts.cas` is on
+   * and a version column exists.
+   */
+  patch: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+declare function buildFormDiff(def: FormDef, baseline: Record<string, unknown>, current: Record<string, unknown>, opts?: FormDiffOptions): FormDiffResult;
+//#endregion
 //#region src/form/error-utils.d.ts
 /**
  * Framework-agnostic helpers for working with form-error maps keyed by
@@ -912,4 +979,4 @@ declare function getFilterableColumns(def: TableDef): ColumnDef[];
 /** Find a column by path. */
 declare function getColumn(def: TableDef, path: string): ColumnDef | undefined;
 //#endregion
-export { type ClientFactory, type ColumnDef, type CurrencyDisplay, DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, type DecimalParts, EXPECT_MAX_LENGTH, type FieldMeta, type FieldResolver, type FormActionInfo, type FormArrayFieldDef, type FormDef, type FormFieldDef, type FormObjectFieldDef, type FormTupleFieldDef, type FormUnionFieldDef, type FormUnionVariant, type FormatDecimalOptions, type GridSpanArgs, type GridSpec, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, type MeasurementInfo, type MetaCacheEntry, type MetaResponse, type PaginationControl, type RelationInfo, type ResolvedValueHelp, type SearchIndexInfo, type SortControl, StaticFieldResolver, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TFieldValidatorOptions, type TFormAction, type TFormEntryOptions, type TFormValidatorCallOptions, type TFormValueResolver, type TResolveOptions, type TableActionsModel, type TableDef, type TableQueryState, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, type ValueHelpInfo, type ValueHelpResult, type ValueHelpSearchOptions, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };
+export { type ClientFactory, type ColumnDef, type CurrencyDisplay, DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, type DecimalParts, EXPECT_MAX_LENGTH, type FieldMeta, type FieldResolver, type FormActionInfo, type FormArrayFieldDef, type FormDef, type FormDiffOptions, type FormDiffResult, type FormFieldChange, type FormFieldDef, type FormObjectFieldDef, type FormTupleFieldDef, type FormUnionFieldDef, type FormUnionVariant, type FormatDecimalOptions, type GridSpanArgs, type GridSpec, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, type MeasurementInfo, type MetaCacheEntry, type MetaResponse, type PaginationControl, type RelationInfo, type ResolvedValueHelp, type SearchIndexInfo, type SortControl, StaticFieldResolver, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TFieldValidatorOptions, type TFormAction, type TFormEntryOptions, type TFormValidatorCallOptions, type TFormValueResolver, type TResolveOptions, type TableActionsModel, type TableDef, type TableQueryState, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, type ValueHelpInfo, type ValueHelpResult, type ValueHelpSearchOptions, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildFormDiff, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };

package/dist/index.mjs

@@ -947,6 +947,435 @@ 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).
+*/
+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/error-utils.ts
 /**
 * Framework-agnostic helpers for working with form-error maps keyed by
@@ -1553,4 +1982,4 @@ function getColumn(def, path) {
 	return def.columns.find((c) => c.path === path);
 }
 //#endregion
-export { DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, EXPECT_MAX_LENGTH, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, StaticFieldResolver, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };
+export { DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, EXPECT_MAX_LENGTH, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, StaticFieldResolver, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_SELECT_WITH, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildFormDiff, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/ui",
-  "version": "0.1.102",
+  "version": "0.1.103",
   "description": "Framework-agnostic runtime for form and table definitions from atscript annotated types",
   "keywords": [
     "annotations",