@atscript/ui 0.1.103 → 0.1.104

package/dist/index.d.cts

@@ -29,7 +29,7 @@ declare const UI_FORM_SUFFIX_ICON: "ui.form.suffix.icon";
 declare const UI_TABLE_WIDTH: "ui.table.width";
 declare const UI_TABLE_COMPONENT: "ui.table.component";
 declare const UI_TABLE_SELECT_WITH: "ui.table.selectWith";
-declare const UI_TABLE_HIDDEN: "ui.table.hidden";
+declare const UI_TABLE_EXCLUDE: "ui.table.exclude";
 declare const UI_TABLE_ATTR: "ui.table.attr";
 declare const UI_TABLE_CLASSES: "ui.table.classes";
 declare const UI_TABLE_STYLES: "ui.table.styles";
@@ -442,6 +442,20 @@ declare function getByPath(obj: Record<string, unknown>, path: string): unknown;
  * Creates intermediate objects if they do not exist.
  */
 declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * 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`).
+ */
+declare function deleteByPath(obj: Record<string, unknown>, path: string): void;
 /** Value resolver function type — created once per form, reused across calls. */
 type TFormValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown;
 declare function createFormValueResolver(data?: Record<string, unknown>, context?: Record<string, unknown>): TFormValueResolver;
@@ -450,6 +464,28 @@ declare function createFormData<T extends TAtscriptAnnotatedType>(type: T, resol
 };
 declare function detectUnionVariant(value: unknown, variants: FormUnionVariant[]): number;
 //#endregion
+//#region src/form/clone.d.ts
+/**
+ * Optional per-value unwrap hook. Lets a framework caller strip a reactive
+ * proxy off every visited value before it is copied (e.g. Vue's `toRaw`). The
+ * core never needs it — it is `undefined` here and the value passes through.
+ */
+type CloneUnwrap = (value: unknown) => unknown;
+/**
+ * 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.
+ */
+declare function deepClone<T>(value: T, unwrap?: CloneUnwrap): T;
+//#endregion
 //#region src/form/validate.d.ts
 /** Per-call options for the form validator function. */
 interface TFormValidatorCallOptions {
@@ -550,6 +586,168 @@ interface FormDiffResult {
  * 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;
+/**
+ * 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.
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+//#endregion
+//#region src/form/dirty.d.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.
+ */
+declare function isPathDirty(changes: FormFieldChange[], path: string): boolean;
+/**
+ * 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.
+ */
+declare function collectDirtyPaths(changes: FormFieldChange[]): Set<string>;
+//#endregion
+//#region src/form/apply.d.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.
+ */
+declare function applyFormChanges(_def: FormDef, data: Record<string, unknown>, changes: FormFieldChange[]): Record<string, unknown>;
+//#endregion
+//#region src/form/rebase.d.ts
+/** Options for {@link buildFormRebase}. */
+interface FormRebaseOptions {
+  /**
+   * How to resolve a field changed on BOTH sides (local edit vs. upstream
+   * edit) to a different value:
+   * - `'ours'` (default) — keep the local edit, discard upstream's value.
+   * - `'theirs'` — take upstream's value, discard the local edit.
+   *
+   * A field changed on both sides to the SAME value is never a conflict.
+   */
+  conflict?: "ours" | "theirs";
+}
+/** Result of {@link buildFormRebase}. */
+interface FormRebaseResult {
+  /**
+   * The rebased WRAPPED form-data container (`{ value }`). Always a fresh deep
+   * clone of `upstream` with the local diff reapplied — never aliases any
+   * input container.
+   */
+  next: Record<string, unknown>;
+  /**
+   * Paths that were changed on both sides to different values (same-path
+   * conflicts), plus ancestor paths whose subtree upstream cleared while local
+   * still edited a leaf under it (ancestor-clear conflicts). De-duplicated.
+   */
+  conflicts: string[];
+  /**
+   * The diff of `next` against the NEW baseline (`upstream`) — i.e. exactly the
+   * changes that survive on top of upstream. Empty `[]` when the rebased form
+   * equals upstream (a fully clean / fully reverted rebase).
+   *
+   * The returned `reapplied` does NOT alias the returned `next`, so installing
+   * `next` as live form data never retroactively mutates the returned change set.
+   */
+  reapplied: FormFieldChange[];
+}
+/**
+ * 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.
+ */
+declare function buildFormRebase(def: FormDef, baseline: Record<string, unknown>, current: Record<string, unknown>, upstream: Record<string, unknown>, opts?: FormRebaseOptions, diffOptions?: FormDiffOptions): FormRebaseResult;
+//#endregion
+//#region src/form/union-detect.d.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.
+ */
+declare function unionVariantChanged(def: FormDef, before: Record<string, unknown>, after: Record<string, unknown>): boolean;
 //#endregion
 //#region src/form/error-utils.d.ts
 /**
@@ -819,6 +1017,11 @@ interface TableDef {
    * of re-walking the type.
    */
   flatMap: Map<string, TAtscriptAnnotatedType>;
+  /**
+   * Server-returnable field paths (from meta.fields) — the gate for
+   * @ui.table.selectWith targets, includes @ui.table.exclude fields.
+   */
+  fetchableFields: Set<string>;
   primaryKeys: string[];
   /** Preferred row identifier — see `MetaResponse.preferredId`. */
   preferredId: string[];
@@ -859,8 +1062,6 @@ interface ColumnDef {
    * for non-nullable columns since they can never match.
    */
   nullable: boolean;
-  /** Whether this column is visible by default. */
-  visible: boolean;
   /** Default column width from @ui.table.width. */
   width?: string;
   /** Maximum length constraint from @expect.maxLen — used to derive default column width. */
@@ -970,8 +1171,6 @@ declare function resetMetaCache(): void;
 declare function str(value: unknown): string;
 //#endregion
 //#region src/table/column-resolver.d.ts
-/** Get visible columns only, already sorted by order. */
-declare function getVisibleColumns(def: TableDef): ColumnDef[];
 /** Get sortable columns. */
 declare function getSortableColumns(def: TableDef): ColumnDef[];
 /** Get filterable columns. */
@@ -979,4 +1178,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 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 };
+export { type ClientFactory, type CloneUnwrap, 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 FormRebaseOptions, type FormRebaseResult, 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_EXCLUDE, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, 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, applyFormChanges, asArray, buildDescendantErrorCounts, buildFormDiff, buildFormRebase, buildGridClasses, buildUnionVariants, collectDirtyPaths, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, deepClone, deepEqual, defaultResolver, deleteByPath, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPathDirty, 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, unionVariantChanged, valueHelpDictPaths };

package/dist/index.d.mts

@@ -29,7 +29,7 @@ declare const UI_FORM_SUFFIX_ICON: "ui.form.suffix.icon";
 declare const UI_TABLE_WIDTH: "ui.table.width";
 declare const UI_TABLE_COMPONENT: "ui.table.component";
 declare const UI_TABLE_SELECT_WITH: "ui.table.selectWith";
-declare const UI_TABLE_HIDDEN: "ui.table.hidden";
+declare const UI_TABLE_EXCLUDE: "ui.table.exclude";
 declare const UI_TABLE_ATTR: "ui.table.attr";
 declare const UI_TABLE_CLASSES: "ui.table.classes";
 declare const UI_TABLE_STYLES: "ui.table.styles";
@@ -442,6 +442,20 @@ declare function getByPath(obj: Record<string, unknown>, path: string): unknown;
  * Creates intermediate objects if they do not exist.
  */
 declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * 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`).
+ */
+declare function deleteByPath(obj: Record<string, unknown>, path: string): void;
 /** Value resolver function type — created once per form, reused across calls. */
 type TFormValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown;
 declare function createFormValueResolver(data?: Record<string, unknown>, context?: Record<string, unknown>): TFormValueResolver;
@@ -450,6 +464,28 @@ declare function createFormData<T extends TAtscriptAnnotatedType>(type: T, resol
 };
 declare function detectUnionVariant(value: unknown, variants: FormUnionVariant[]): number;
 //#endregion
+//#region src/form/clone.d.ts
+/**
+ * Optional per-value unwrap hook. Lets a framework caller strip a reactive
+ * proxy off every visited value before it is copied (e.g. Vue's `toRaw`). The
+ * core never needs it — it is `undefined` here and the value passes through.
+ */
+type CloneUnwrap = (value: unknown) => unknown;
+/**
+ * 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.
+ */
+declare function deepClone<T>(value: T, unwrap?: CloneUnwrap): T;
+//#endregion
 //#region src/form/validate.d.ts
 /** Per-call options for the form validator function. */
 interface TFormValidatorCallOptions {
@@ -550,6 +586,168 @@ interface FormDiffResult {
  * 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;
+/**
+ * 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.
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+//#endregion
+//#region src/form/dirty.d.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.
+ */
+declare function isPathDirty(changes: FormFieldChange[], path: string): boolean;
+/**
+ * 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.
+ */
+declare function collectDirtyPaths(changes: FormFieldChange[]): Set<string>;
+//#endregion
+//#region src/form/apply.d.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.
+ */
+declare function applyFormChanges(_def: FormDef, data: Record<string, unknown>, changes: FormFieldChange[]): Record<string, unknown>;
+//#endregion
+//#region src/form/rebase.d.ts
+/** Options for {@link buildFormRebase}. */
+interface FormRebaseOptions {
+  /**
+   * How to resolve a field changed on BOTH sides (local edit vs. upstream
+   * edit) to a different value:
+   * - `'ours'` (default) — keep the local edit, discard upstream's value.
+   * - `'theirs'` — take upstream's value, discard the local edit.
+   *
+   * A field changed on both sides to the SAME value is never a conflict.
+   */
+  conflict?: "ours" | "theirs";
+}
+/** Result of {@link buildFormRebase}. */
+interface FormRebaseResult {
+  /**
+   * The rebased WRAPPED form-data container (`{ value }`). Always a fresh deep
+   * clone of `upstream` with the local diff reapplied — never aliases any
+   * input container.
+   */
+  next: Record<string, unknown>;
+  /**
+   * Paths that were changed on both sides to different values (same-path
+   * conflicts), plus ancestor paths whose subtree upstream cleared while local
+   * still edited a leaf under it (ancestor-clear conflicts). De-duplicated.
+   */
+  conflicts: string[];
+  /**
+   * The diff of `next` against the NEW baseline (`upstream`) — i.e. exactly the
+   * changes that survive on top of upstream. Empty `[]` when the rebased form
+   * equals upstream (a fully clean / fully reverted rebase).
+   *
+   * The returned `reapplied` does NOT alias the returned `next`, so installing
+   * `next` as live form data never retroactively mutates the returned change set.
+   */
+  reapplied: FormFieldChange[];
+}
+/**
+ * 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.
+ */
+declare function buildFormRebase(def: FormDef, baseline: Record<string, unknown>, current: Record<string, unknown>, upstream: Record<string, unknown>, opts?: FormRebaseOptions, diffOptions?: FormDiffOptions): FormRebaseResult;
+//#endregion
+//#region src/form/union-detect.d.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.
+ */
+declare function unionVariantChanged(def: FormDef, before: Record<string, unknown>, after: Record<string, unknown>): boolean;
 //#endregion
 //#region src/form/error-utils.d.ts
 /**
@@ -819,6 +1017,11 @@ interface TableDef {
    * of re-walking the type.
    */
   flatMap: Map<string, TAtscriptAnnotatedType>;
+  /**
+   * Server-returnable field paths (from meta.fields) — the gate for
+   * @ui.table.selectWith targets, includes @ui.table.exclude fields.
+   */
+  fetchableFields: Set<string>;
   primaryKeys: string[];
   /** Preferred row identifier — see `MetaResponse.preferredId`. */
   preferredId: string[];
@@ -859,8 +1062,6 @@ interface ColumnDef {
    * for non-nullable columns since they can never match.
    */
   nullable: boolean;
-  /** Whether this column is visible by default. */
-  visible: boolean;
   /** Default column width from @ui.table.width. */
   width?: string;
   /** Maximum length constraint from @expect.maxLen — used to derive default column width. */
@@ -970,8 +1171,6 @@ declare function resetMetaCache(): void;
 declare function str(value: unknown): string;
 //#endregion
 //#region src/table/column-resolver.d.ts
-/** Get visible columns only, already sorted by order. */
-declare function getVisibleColumns(def: TableDef): ColumnDef[];
 /** Get sortable columns. */
 declare function getSortableColumns(def: TableDef): ColumnDef[];
 /** Get filterable columns. */
@@ -979,4 +1178,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 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 };
+export { type ClientFactory, type CloneUnwrap, 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 FormRebaseOptions, type FormRebaseResult, 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_EXCLUDE, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, 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, applyFormChanges, asArray, buildDescendantErrorCounts, buildFormDiff, buildFormRebase, buildGridClasses, buildUnionVariants, collectDirtyPaths, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, deepClone, deepEqual, defaultResolver, deleteByPath, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDeclaredFormActions, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPathDirty, 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, unionVariantChanged, valueHelpDictPaths };