@atscript/ui 0.1.103 → 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. */
@@ -1351,6 +1412,10 @@ function stableKey(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;
@@ -1377,6 +1442,228 @@ function deepEqual(a, b) {
 	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
@@ -1861,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);
@@ -1877,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,
@@ -1893,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,
@@ -1966,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);
@@ -2050,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;
@@ -2063,17 +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;
@@ -2095,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;
@@ -2130,4 +2420,5 @@ exports.setDefaultValidatorPlugins = setDefaultValidatorPlugins;
 exports.setResolver = setResolver;
 exports.splitDecimalString = splitDecimalString;
 exports.str = str;
+exports.unionVariantChanged = unionVariantChanged;
 exports.valueHelpDictPaths = valueHelpDictPaths;