@dynamicforms/vue-forms 0.6.1 → 0.12.0

package/dist/index.d.ts

@@ -7,27 +7,102 @@ import { Ref } from 'vue';
 export declare class AbortEventHandlingException extends Error {
 }
 
-export declare class Action<T extends ActionValue = ActionValue> extends Field<T> {
-    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
+export declare class Action<T extends ActionValue = ActionValue, X extends object = {}> extends Field<T, X> {
+    protected init(params?: IFieldParams<T, X>): void;
+    /**
+     * A copy of the value this action holds, carrying one member rewritten. A member handed undefined is dropped
+     * from the copy rather than written into it: an own key holding undefined is invisible to a reader and to
+     * JSON, but lodash isEqual compares own-key sets, so writing one would leave the action permanently changed
+     * against a baseline that never carried the key.
+     */
+    private valueWith;
     get icon(): string | undefined;
     set icon(newValue: string | undefined);
     get label(): string | undefined;
+    /**
+     * The two setters hand the value setter a new object rather than writing into the one the action holds, so each
+     * is an ordinary value change: the handlers fire, isChanged answers over it, and a disabled action refuses it.
+     * The new object is built only for a member that differs from the one held - the value setter compares by
+     * identity and every copy is a new object, so without the comparison here a write of the value already held
+     * would announce a change and invalidate the value cache of every container above.
+     */
     set label(newValue: string | undefined);
-    execute(params: any): void;
+    /** the counter behind `busy`, allocated for this action the first time it is asked for */
+    private get busyRuns();
+    /** true from the moment execute() is called until the handler it ran has settled, however it settles */
+    get busy(): boolean;
+    /**
+     * Runs the ExecuteAction chain registered on this action and answers what the chain returned. `busy` stands for
+     * the length of the run: the chain is entered synchronously, and the flag is cleared once the value it produced
+     * has settled - a handler that returns a promise holds it for as long as that promise takes, and one that
+     * rejects clears it as it rejects.
+     *
+     * The answer is a promise whatever the handler returns, so a handler that throws rejects it rather than throwing
+     * out of this call: a caller that does not await the answer and does not attach a catch handler leaves that
+     * rejection unhandled.
+     */
+    execute(params?: any): Promise<any>;
 }
 
 declare type ActionExecutor = (field: FieldBase, supr: FieldActionExecute, ...params: any[]) => any;
 
-export declare class ActionsMap extends Map<symbol, FieldActionExecute> {
-    private readonly eagerActions;
+/**
+ * The actions one element has registered, grouped by the identifier they are triggered under. Within a group the
+ * actions stand in registration order and are run from the end backwards, so the newest registration is the
+ * outermost handler and reaches the ones before it through the `supr` it is handed. A handler that does not call
+ * `supr` ends the run there, and one that calls it may transform what it answers with.
+ */
+export declare class ActionsMap {
+    /** every action registered here, in registration order across all identifiers */
     private readonly registeredActions;
-    register(action: FieldActionBase): void;
+    /** the actions of one identifier, in registration order */
+    private readonly chains;
+    /** the eager actions of one identifier, in registration order; a subsequence of the chain under that identifier */
+    private readonly eagerChains;
+    /**
+     * Registers `action`. It becomes the outermost handler of its identifier, or - where `before` is given and is
+     * registered here under the same identifier - takes that action's place in the order, so `before` wraps it and
+     * reaches it through `supr`. That is what lets an action be added to a chain someone else built and still sit
+     * inside a handler already there.
+     */
+    register(action: FieldActionBase, before?: FieldActionBase): void;
+    /**
+     * Drops `action` from this map and answers whether it was in it. The lists it stood in are replaced rather than
+     * written, so a run already walking one finishes on the list it started with and the removal takes effect from
+     * the next trigger.
+     */
+    unregister(action: FieldActionBase): boolean;
+    /** True where something is registered under `identifier`. */
+    willTrigger(identifier: symbol): boolean;
+    /** True where any eager action is registered, whatever identifier it stands under. */
+    get hasEager(): boolean;
+    /** Runs the actions registered under `ActionClass` and answers with what the outermost of them returned. */
     trigger<T extends FieldActionBase>(ActionClass: (abstract new (...args: any[]) => T) & {
         classIdentifier: symbol;
     }, field: FieldBase, ...params: any[]): any;
-    triggerEager(field: FieldBase, ...params: any[]): any;
+    /** Runs the eager actions of every identifier, each group on its own. */
+    triggerEager(field: FieldBase, ...params: any[]): void;
+    /** Runs the eager actions registered under `identifier` and nothing else. */
+    triggerEagerFor(identifier: symbol, field: FieldBase, ...params: any[]): any;
+    /** the validators registered in this map, in registration order */
+    get validators(): Validator[];
     clone(): ActionsMap;
-    cloneWithoutValidators(): ActionsMap;
+    /**
+     * Tells every action in this map that it serves `owner`. A copied map holds the instances the original holds, so
+     * the element that took the copy on is announced to them here, the way registering an action announces the
+     * element it was registered on.
+     */
+    bindTo(owner: FieldBase): void;
+    /**
+     * Walks `chain` from the end backwards, handing each action a `supr` that continues at the one before it. The
+     * closures exist for the length of the run and only as deep as the run actually goes, so a chain nobody walks to
+     * the bottom costs nothing for the part left unreached.
+     */
+    private step;
+    /** Walks a chain, answering null where there is none. An abort ends the run and is not an error to the caller. */
+    private run;
+    private insert;
+    private remove;
 }
 
 export declare interface ActionValue {
@@ -47,13 +122,55 @@ export declare type ClassType = string | string[] | Record<string, boolean>;
 export declare type ClassTypes = ClassType | ClassType[];
 
 declare class CompareTo<T = any> extends Validator {
-    private otherField;
     private isValidComparison;
-    private unregistered;
-    constructor(otherField: FieldBase, isValidComparison: (myValue: T, otherValue: T) => boolean, message: RenderContentRef);
-    unregister(): void;
+    private readonly otherField;
+    /**
+     * The fields this validator is registered on. Registration reaches one element at a time - the rows of a list
+     * take the validator on one by one, as they are built from the item template that carries it - so this is what
+     * says which of the fields a declaration stands for actually carry the rule, and a field that never took it on
+     * is left alone by a change of the compared field.
+     */
+    private readonly registrations;
+    /**
+     * The fields this validator has installed its listener on. A binding of such a field carries the listener too -
+     * a binding takes on the actions of the field it was bound from - so the field it was bound from is what is
+     * asked about as well, and a list of a thousand rows installs one listener rather than a thousand.
+     */
+    private readonly listening;
+    /**
+     * What the fields this validator was registered on were declared as. One entry stands for every binding of such a
+     * field, so a change of a compared field finds the fields of the record that change happened in without a list
+     * of a thousand rows being held here.
+     */
+    private readonly declarations;
+    constructor(otherField: CompareToTarget, isValidComparison: (myValue: T, otherValue: T) => boolean, message: RenderContentRef);
+    /** The field `field` is compared against, within the record `field` belongs to. */
+    private resolve;
+    /**
+     * Makes a change of `other` re-run this comparison. The listener re-runs it over the fields of the record the
+     * change happened in rather than over the field that installed it, so the listener a row inherits with the field
+     * it was bound from serves that row; and it re-runs this one validator, not the chain around it.
+     */
+    private listenOn;
+    boundToBinding(binding: FieldBase): void;
+    private comparisonState;
+    protected newBindingState(): CompareToBindingState<T>;
+    unregisterFrom(binding: FieldBase): void;
 }
 
+/** What the validator remembers about one field it validates. */
+declare interface CompareToBindingState<T> extends ValidatorBindingState {
+    oldValue: T;
+}
+
+/**
+ * How the field to compare against is named. A field names it directly, a string names it by the name its
+ * container holds it under, and a callback works it out from the field being validated. All three answer for the
+ * record the validation is running over: handed the field of a `List`'s item template, a row compares against that
+ * row's field.
+ */
+declare type CompareToTarget = FieldBase | string | ((field: FieldBase) => FieldBase | null | undefined);
+
 export declare class ConditionalEnabledAction extends ConditionalStatementAction {
     constructor(statement: Statement);
 }
@@ -61,12 +178,44 @@ export declare class ConditionalEnabledAction extends ConditionalStatementAction
 declare type ConditionalExecutorFn = (field: FieldBase, currentResult: boolean, previousResult: boolean | undefined) => void;
 
 export declare class ConditionalStatementAction extends ValueChangedAction {
-    private lastResult;
-    private readonly boundFields;
+    private readonly statement;
+    private readonly conditionalExecutor;
+    /**
+     * What the elements this action was registered on were declared as. It holds declarations rather than the
+     * elements themselves, so one entry stands for every row of a list, and the element a result is applied to is
+     * the one that declaration names within the record the change happened in.
+     */
+    private readonly declarations;
+    /**
+     * The elements this action was registered on. Registration reaches one element at a time - the rows of a list
+     * take the action on one by one, as they are built from the item template that carries it - so this is what
+     * says which of the elements a declaration stands for the action actually drives.
+     */
+    private readonly registrations;
     constructor(statement: Statement, executorFn: ConditionalExecutorFn);
     static get classIdentifier(): symbol;
     get eager(): boolean;
-    boundToField(field: FieldBase): void;
+    boundToBinding(binding: FieldBase): void;
+    unregisterFrom(binding: FieldBase): void;
+    /**
+     * The elements of `scope` this action controls: what each declaration it serves names within that record, and of
+     * those the ones that took the action on. A row of a list that never took it on is not one this action drives.
+     */
+    private targetsIn;
+    /**
+     * Re-evaluates the statement over one record and applies the result where it changed. The result is recorded
+     * before the executor runs, because an executor that writes a value re-enters through that value's eager pass
+     * and what it has to find there is the result being applied. It answers whether the record held anything for
+     * this action to drive, which is how a caller learns that the record is not assembled yet.
+     */
+    private applyIn;
+    /**
+     * Re-evaluates the records a change of `source` speaks for. A field of the record the targets live in speaks for
+     * that record alone, which is what keeps one row of a list from answering for another; a field above them - a
+     * form field every row reads - speaks for every record below it, and for the record the action was declared in
+     * where the change reaches none.
+     */
+    private applyFrom;
 }
 
 export declare class ConditionalValueAction<T> extends ConditionalStatementAction {
@@ -77,6 +226,15 @@ export declare class ConditionalVisibilityAction extends ConditionalStatementAct
     constructor(statement: Statement);
 }
 
+/**
+ * What a container holds beyond the common slots: the object the value getter last built, together with the
+ * version of the tree it was built from.
+ */
+declare interface ContainerSlots<T = any> extends ElementSlots<T> {
+    cachedValue: T;
+    cachedValueVersion: number;
+}
+
 /**
  * DisplayMode enum provides an enumeration for supported ways of rendering a particular object in the DOM
  */
@@ -93,7 +251,64 @@ export declare namespace DisplayMode {
     export function isDefined(mode: number | string): boolean;
 }
 
-export declare const EmptyField: Field<string>;
+/**
+ * The mutable state of one element, held in an object of its own beside the element rather than in the element's
+ * own properties.
+ *
+ * An element reaches it through two views of that one object, both in private class fields of `FieldBase`:
+ * `this.state` is `reactive(slots)` and `this.raw` is the object itself. A slot read through `state` inside a
+ * render effect or a computed subscribes that effect to the slot, and a write to the slot re-runs it. The
+ * bookkeeping an element does for itself goes through `raw`, which neither records a read nor announces a write.
+ * The value cache of a container goes through `raw` in particular: its getter writes the cache while it runs, and
+ * a tracked write there costs the reading effect one extra evaluation, and one extra render on mount, for a value
+ * it has already built.
+ *
+ * Being private class fields is what puts the two views out of reach of everything outside `FieldBase`: a private
+ * field is absent from `Object.keys`, `JSON.stringify`, `Object.getOwnPropertySymbols` and lodash `getAllKeys` by
+ * construction, and needs no per-instance property definition to be. Both `JSON.stringify` and lodash `isEqual`
+ * walk their way down a structure over own keys, enumerable symbols included, and the `parent` slot is in the
+ * state: reachable, it would take either walker back into the container the element came from.
+ *
+ * What they do reach on an element is `_actions` once something is registered, `_fields` on a `Group` and
+ * `_itemTemplate` on a `List`. All three lead downwards only.
+ */
+declare interface ElementSlots<T = any> {
+    /** the value the element was given at construction; isChanged compares against it */
+    originalValue: T;
+    /** the value the last ValueChangedAction reported; the next transaction measures its net change against it */
+    announcedValue: T;
+    errors: ValidationError[];
+    visibility: DisplayMode;
+    enabled: boolean;
+    /** counts the writes that changed the value of the element or of anything below it */
+    valueVersion: number;
+    /** how many asynchronous validation runs are in flight on this element */
+    validatingCount: number;
+    /** the container that holds this element, absent while none does; takeChild writes it, releaseChild clears it */
+    parent: FieldBase | undefined;
+    /** the name the containing Group holds this element under; a List row carries none */
+    fieldName: string | undefined;
+    /** generation of the validators attached to the element; clearValidators() raises it */
+    validationEpoch: number;
+    /**
+     * The extended properties the element carries, typed by the element's own X parameter. A write replaces the
+     * object rather than writing into it, so an effect that read the slot re-runs on the write, and the object a
+     * transaction captured is the one a rollback puts back.
+     */
+    extra: object;
+    /**
+     * The element this one was bound from, absent on an element that was declared rather than bound. It is what lets
+     * an action shared by every binding work out which binding of a second element it means: `declaration` is the
+     * canonical one, so a binding of a binding names the element the whole family was declared as.
+     */
+    declaration: FieldBase | undefined;
+    /** the verdict the last commit announced, which is what a change of validity is measured against */
+    valid: boolean;
+    /** number of direct children whose last announced verdict was invalid */
+    invalidChildren: number;
+}
+
+export declare const EmptyField: Field<string, {}>;
 
 export declare class EnabledChangedAction extends FieldActionBase {
     constructor(executorFn: (field: FieldBase, supr: FieldActionExecute, newValue: boolean, oldValue: boolean) => void);
@@ -113,10 +328,13 @@ export declare class ExecuteAction extends FieldActionBase {
     execute(field: FieldBase, supr: FieldActionExecute, params: any): any;
 }
 
-export declare class Field<T = any> extends FieldBase<T> {
-    protected _value: T;
-    protected _touched: boolean;
-    constructor(params?: Partial<IFieldConstructorParams<T>>);
+export declare class Field<T = any, X extends object = {}> extends FieldBase<T, X> {
+    protected get state(): FieldSlots<T>;
+    protected get raw(): FieldSlots<T>;
+    /** the value slot itself, without the notifications the value setter carries around a write */
+    protected get _value(): T;
+    protected set _value(newValue: T);
+    constructor(params?: IFieldParams<T, X>);
     /**
      * Applies the constructor parameters. It is a hook so that a subclass needing different parameter handling
      * overrides one method instead of redeclaring the constructor - Action does exactly that.
@@ -126,81 +344,343 @@ export declare class Field<T = any> extends FieldBase<T> {
      * subclass initializes read as undefined inside it, and anything it writes to such a member is overwritten
      * the moment the initializer runs.
      */
-    protected init(params?: Partial<IFieldConstructorParams<T>>): void;
+    protected init(params?: IFieldParams<T, X>): void;
     get value(): T;
     set value(newValue: T);
     get touched(): boolean;
     set touched(touched: boolean);
-    clone(overrides?: Partial<IFieldConstructorParams<T>>): this;
+    bind(data?: T, overrides?: IBindParams<T, X>): this;
 }
 
 export declare abstract class FieldActionBase {
     static get classIdentifier(): symbol;
     get classIdentifier(): symbol;
     private readonly executorFn;
+    /**
+     * What this action remembers about one of the elements it serves. An action instance is shared - a `List` row
+     * carries the instances the item template carries - so anything an action holds about the element it last ran
+     * over belongs to that element rather than to the action: a verdict, a sequence number, a listener it installed.
+     * The keys are weak, so what an action remembers about a row is released with the row.
+     */
+    private readonly states;
     constructor(executorFn: ActionExecutor);
+    /**
+     * This action's state for `key`, created by `init` the first time it is asked for. The key is the element the
+     * action is running over, or the record that element belongs to where what is remembered is a fact about the
+     * whole record.
+     */
+    protected state<S>(key: object, init: () => S): S;
     execute(field: FieldBase, supr: FieldActionExecute, ...params: any[]): any;
     get eager(): boolean;
-    boundToField(field: FieldBase): void;
-    unregister(): void;
+    /**
+     * Announces that this action now serves `binding`. It runs once per element the action is registered on, the
+     * copies of that element included: a copy takes on the instances it was copied from and each is told about the
+     * copy as it does.
+     */
+    boundToBinding(binding: FieldBase): void;
+    /**
+     * Announces that `binding` no longer holds this action, and takes back what running it left there. It names one
+     * element rather than the action as a whole, because the instance goes on serving every other element it was
+     * registered on. It runs inside the operation that drops the registration, so an operation that unwinds puts the
+     * registration and what this took back both back.
+     */
+    unregisterFrom(binding: FieldBase): void;
 }
 
 export declare type FieldActionExecute<T = any> = (field: FieldBase<T>, ...params: any[]) => any;
 
-export declare abstract class FieldBase<T = any> {
+export declare abstract class FieldBase<T = any, X extends object = {}> {
+    #private;
     /**
-     * A field is a Vue reactive proxy from construction onwards: the base constructor returns the proxy, and a
-     * derived class's `this` is whatever super() returned, so every subclass constructor, field initializer and
-     * method sees the proxy. Consequence: plain `field.property = value` is tracked, with no wrapper in between.
+     * Vue's getTargetType answers INVALID for an object that carries __v_skip, so reactive() hands an element back
+     * unwrapped and no element is ever behind a proxy of its own. isReactive() reads the second flag, and it stays
+     * true because what carries an element's reactivity - its state - is a reactive object.
+     *
+     * Two consequences for a consumer, both silent. watch(field, cb) with a bare element as the source registers
+     * no dependency, because the deep traversal Vue starts for a reactive source stops on __v_skip; the supported
+     * form is watch(() => field.value, cb). And readonly(field) hands the element straight back, so the value it
+     * returns is the element itself and a write through it reaches the field; what a caller hands out instead is
+     * the value, which is frozen, or a computed over it.
      */
-    constructor();
+    get __v_skip(): boolean;
+    get __v_isReactive(): boolean;
+    constructor(slots: ElementSlots<T>);
+    /** the tracked view of this element's state; a subclass narrows the return type to its own slots */
+    protected get state(): ElementSlots<T>;
+    /** the untracked view of this element's state; a subclass narrows the return type to its own slots */
+    protected get raw(): ElementSlots<T>;
     abstract get value(): T;
     abstract set value(newValue: T);
     abstract get touched(): boolean;
     abstract set touched(touched: boolean);
-    abstract clone(overrides?: Partial<IFieldConstructorParams<T>>): FieldBase<T>;
-    originalValue: T;
-    private validatingCount;
+    /**
+     * A new element of this one's class over `data`: same class, same registered actions, same extended properties,
+     * and the change history starting over. It is how a declaration is put to work over a record - every row a
+     * `List` builds is its item template bound to that row's data - and the element it is called on is what the new
+     * one answers `declaration` with.
+     *
+     * `data` of `undefined` is no data supplied and the new element carries what this one holds; an explicit `null`
+     * is data and clears. `overrides` states the rest: `originalValue` is read by key presence, `enabled` and
+     * `visibility` fall back to this element's, and extended properties it names are written over the ones carried
+     * over. The new element is detached - no `parent`, no `fieldName` - so it is free to be taken by a container.
+     */
+    abstract bind(data?: T, overrides?: IBindParams<T, X>): FieldBase<T, X>;
+    /**
+     * Exchanges the data this element holds for `data`, in place. The element is the same instance afterwards - its
+     * identity, its actions, its extended properties and its place in whatever container holds it all stand - and it
+     * ends up in the state `bind(data)` would have produced: the values are written, the change history starts over
+     * and the validators run. It is what recycles one element across records, which is what a virtualised renderer
+     * does with the rows it keeps.
+     *
+     * The element makes no statement of its own about the exchange: no `ValueChangedAction` fires for it, the way
+     * none fires for an element that was just built. Its members do announce theirs, and a verdict that moves is
+     * announced as always - a rebound element that is invalid says so to the container holding it. A change an
+     * open transaction is already owed an announcement for stands: the commit reports the pair measured from
+     * where the element was when the transaction opened.
+     *
+     * The data is measured against the element's `declaration`, so a key a record leaves out is taken from the
+     * declaration rather than left as the previous record had it.
+     */
+    rebind(data: T): this;
+    /** contains original field value as was provided at creation */
+    get originalValue(): T;
+    set originalValue(newValue: T);
+    /**
+     * The extended properties this element carries: what a consumer attached to it beyond the members the class
+     * declares, such as the label, hint or css class a UI layer binds to the input it renders the element with.
+     * The read is tracked, so a template rendering off `field.extra.label` re-renders when the property is written.
+     *
+     * Every property is optional here, whatever `X` states: a parameter object need not carry one and
+     * setExtendedValues writes as few as a caller likes, so a property `X` declares as required is present only
+     * once something has written it.
+     *
+     * The object is frozen and setExtendedValues is the way to change it: it is the object a transaction captured,
+     * and one written in place would leave a rollback with nothing to put back.
+     */
+    get extra(): Readonly<Partial<X>>;
+    /**
+     * Writes extended properties. The values given are merged over the ones the element carries, so a write of one
+     * property leaves the others standing, and the merged set replaces the object the element held.
+     */
+    setExtendedValues(values: Partial<X>): void;
+    /**
+     * The extended properties a parameter object carries: every key the element does not answer for itself. A key
+     * the element answers for at the time the parameters are applied - `value`, `enabled`, an accessor a subclass
+     * adds - is the element's own; a key that only Object.prototype answers for is nobody's declaration and counts
+     * as extended, and `validators` and `actions` are neither, since they state what to register on the element.
+     *
+     * A member a subclass declares as a class field is not among the keys the element answers for: class fields are
+     * defined on the instance after the base constructor returns, and the parameters are applied inside it. A
+     * subclass that wants a parameter of its own name assigned to it declares that member as an accessor.
+     */
+    protected extendedOf(params: object): Partial<X>;
+    /**
+     * Applies a parameter object: the members the element answers for are assigned to the element and the rest
+     * become its extended properties. Assigning a getter-only member throws a TypeError, which is what a caller
+     * naming `valid` or `parent` past the type system gets.
+     */
+    protected assignParams(params: object): void;
+    /**
+     * Takes this element into the record of the open transaction, where one is open. A write of a single slot that
+     * announces nothing calls it instead of opening a transaction of its own: on its own such a write is already
+     * atomic, and inside a transaction it has to be part of what a rollback puts back.
+     */
+    protected touchState(): void;
+    /**
+     * Records the whole of this element's mutable state, so that a rolled-back transaction can put it back exactly
+     * as it found it. The errors array is copied because a validator writes into the array it is handed rather than
+     * replacing it, and a subclass copies whatever else it holds by reference the same way.
+     *
+     * What is not in the snapshot is the action map, which no write touches: an operation that replaces it hands
+     * the transaction its own undo instead, so this stays the one shape every element captures.
+     */
+    protected [TxCapture](): TxSnapshot;
+    /**
+     * Puts a captured state back. It writes through the tracked view, so an effect that ran on the state the
+     * transaction produced runs again on the state it is being returned to, and only for the slots that differ.
+     *
+     * validatingCount is the one slot the element keeps: it counts runs that are in flight, and a rollback cannot
+     * un-start one. Put back, the count would no longer match the endValidating calls still to come.
+     */
+    protected [TxRestore](snapshot: TxSnapshot): void;
     /** true while at least one asynchronous validator is still running for this field */
     get validating(): boolean;
     /** announces the start of one asynchronous validation run; validators pair it with endValidating */
     beginValidating(): void;
     /** announces the end of one asynchronous validation run */
     endValidating(): void;
-    protected _valid: boolean;
-    errors: ValidationError[];
-    parent?: Group;
-    fieldName?: string;
-    protected actions: ActionsMap;
-    private _visibility;
+    /**
+     * List of errors. The array handed out is the one the element holds, and a validator writes into it in place,
+     * so a transaction that is open takes the element into its record here: a rollback that put back everything
+     * except the errors would leave a state the form never held.
+     */
+    get errors(): ValidationError[];
+    set errors(newValue: ValidationError[]);
+    /**
+     * The container that holds this element: the Group it is a member of, or the List whose row it is, and
+     * undefined while no container holds it. The container writes it; everyone else reads it. The read is tracked,
+     * so an effect rendering off the link - `v-if="field.parent"` - re-runs when a container takes the element or
+     * releases it.
+     */
+    get parent(): Group | undefined;
+    /** when member of a Group, fieldName specifies the name of this field. Written by the group, read-only after */
+    get fieldName(): string | undefined;
+    /**
+     * The element this one was declared as: itself for an element built from parameters, and the element it was
+     * bound from for a binding - transitively, so a binding of a binding names the same one. Every row a `List`
+     * builds from an item template is a binding of it, so a row's member and the template's member it stands for
+     * answer with the same element, and an action registered on the template can tell the two apart.
+     */
+    get declaration(): FieldBase;
+    /** The elements this one holds: a Group's members, a List's rows, none for a leaf. */
+    protected get members(): FieldBase[];
+    /**
+     * Every element in this element's subtree, this element included, that was declared as `declaration`. It answers
+     * the question a shared action asks when the record it changed in is not the record its targets live in - a form
+     * field that every row of a list reacts to - and it costs the subtree, so it is the path taken only when the
+     * cheaper one, resolving within a single record, does not apply.
+     */
+    bindingsOf(declaration: FieldBase): FieldBase[];
+    /** set while an eager pass over this element is waiting for the record the element belongs to */
+    protected _recordPending?: boolean;
+    /**
+     * States that an eager pass over this element reached an element it needs and did not find it, because the
+     * record this element belongs to was not assembled at the time: a `List` row is built member by member and its
+     * members are bound before any of them holds the row, so a validator comparing two of them runs before the
+     * row exists. The container that finishes the record runs the pass again, and a pass that still reaches
+     * nothing says so again, so the next container above answers for it.
+     */
+    markRecordIncomplete(): void;
+    /**
+     * Runs the eager passes outstanding in `element`'s subtree, now that the record it belongs to is assembled. A
+     * container calls it where it has just made a record complete: a Group that has written its members, and a
+     * List that has taken a row, which is what gives the row's fields the form above it.
+     */
+    protected completeRecords(element?: FieldBase): void;
+    /** Runs this element's eager actions over the value it holds and re-forms the verdict they reach. */
+    private rerunEagerActions;
+    /**
+     * The map this element registers its actions in, absent while it has registered none. Code that only triggers
+     * reads this slot rather than `actions`, so an element with nothing registered stays free of a map: `actions`
+     * allocates one for whoever asks, and a trigger over an empty map does nothing anyway.
+     */
+    protected _actions?: ActionsMap;
+    protected get actions(): ActionsMap;
+    protected set actions(newValue: ActionsMap);
+    /**
+     * Counts the writes that have changed the value of this element or of anything below it. A container reads it
+     * before answering from its value cache, and the read is an ordinary tracked one, so an effect that took a
+     * cached value still re-runs when a descendant is written.
+     */
+    protected get valueVersion(): number;
+    /**
+     * Marks the value of this element and of every ancestor as superseded. It walks the parent chain, so it costs
+     * the nesting depth: an ancestor rebuilds its value the next time one is asked of it, instead of being walked
+     * here for a reader that may never come. The walk also brings each element into the open transaction, so a
+     * rollback puts the versions back and no reader is left holding a cache the tree no longer supports.
+     */
+    protected bumpValueVersion(): void;
+    /**
+     * States that this element's value changed and that every container above it therefore holds a different value
+     * too. Nothing is announced here: the transaction works out at commit which of the elements enrolled actually
+     * ends up holding a different value, and announces those once each.
+     *
+     * `force` states that the caller already knows this element's value changed - one item more or fewer is a
+     * different list whatever the items compare as - so the commit announces it without composing a comparison.
+     */
+    protected propagateValueChanged(force?: boolean): void;
+    /**
+     * Re-reads the value that the next ValueChangedAction will report as the one it replaces. A leaf records what
+     * it announced at every announcement, so its copy is always current and there is nothing to re-read; a
+     * container that skipped composing a value nobody was listening for overrides this.
+     */
+    protected refreshPreviousValue(): void;
+    /**
+     * The verdict validate() records and announces: this element's own errors plus the tally of children that
+     * reported themselves invalid, so a container forms it without walking its members. `valid` is the read path
+     * and answers over the live errors arrays instead; the two differ only for an error written into a member
+     * without a validate() call, which is the documented cost of pushing errors by hand.
+     */
+    protected get countedValid(): boolean;
+    /**
+     * Makes this element the container of `child`: it installs the back-reference, records the name a Group holds
+     * the child under, and takes the child into the invalid tally. An element belongs to one container at a time,
+     * so a child that already carries the link is refused; releaseChild() takes the link away again, and an element
+     * released that way can be handed on. The child's state is unreachable from outside FieldBase, so a container
+     * writes the two slots through here rather than on the child.
+     */
+    protected takeChild(child: FieldBase, fieldName?: string): void;
+    /** Takes a child into this element's invalid tally; a container calls it once the child's parent link exists. */
+    protected adoptChild(child: FieldBase): void;
+    /**
+     * Drops a child out of this element's invalid tally and takes its back-reference away. An element keeps no link
+     * to a container that no longer holds it: it would go on moving that container's tally, and the link is what
+     * stands in the way of the element being taken by another container.
+     */
+    protected releaseChild(child: FieldBase): void;
+    /**
+     * Brings this element to the state a fresh binding of `source` carrying `value` would be in: `value` is written
+     * where the caller supplied one and `source`'s own value where it did not, the change history - originalValue,
+     * touched - starts over and the errors are dropped and re-established by the validators. A container that reuses
+     * an element at a position it already holds calls it, so the element is indistinguishable from one built for
+     * that position.
+     */
+    protected resetTo(source: FieldBase, value: any): void;
+    /** Resets a member. It is what lets a container reach the reset of a child whose class it does not know. */
+    protected resetChild(child: FieldBase, source: FieldBase, value: any): void;
+    /**
+     * Records a child's new verdict in this element's tally. The child reports it as it settles, and the commit
+     * settles the deepest element first, so the tally a container reads when its own turn comes is finished.
+     */
+    protected childValidityChanged(nowValid: boolean): void;
+    /**
+     * The composed verdict a container answers `valid` with, memoised by Vue. The walk over the members is what
+     * makes an error pushed into one of them visible without a validate() call, and the computed keeps that walk
+     * from repeating while nothing it read has moved.
+     */
+    protected get validRead(): boolean;
+    /** What validRead computes. A leaf answers over its own errors; a container adds its members. */
+    protected composeValid(): boolean;
     get visibility(): DisplayMode;
     set visibility(newValue: DisplayMode);
-    private _enabled;
     get enabled(): boolean;
     set enabled(newValue: boolean);
     /**
-     * While true, validate() on this field does nothing at all: it neither recomputes _valid nor emits
-     * ValidChangedAction, and nothing climbs to the parent. A container that walks its members one by one - assigning
-     * them a value, or revalidating them - sets it for the duration of the walk, so a member's upward climb cannot
-     * announce the verdict of a half-applied value or of a half-revalidated set, and clears it in a finally block
-     * followed by its own validate(). That call recomputes over the finished state and emits the net transition, so
-     * the deferral cannot swallow a real change.
+     * True for an element whose value is composed of its members'. The commit builds such a value only where
+     * something receives it, compares it by content rather than by identity, and runs the element's own validators
+     * with the announcement: a container's validators read the composed value, which exists only once the members
+     * have been written. A leaf's validators have run at the write instead, so its announcement carries no eager
+     * pass of its own.
      */
-    protected suppressValidation: boolean;
+    protected get composesValue(): boolean;
     /**
-     * While true, a validity change is still recomputed and still announced on this field, but it is not passed up to
-     * the parent: the climb is only remembered and carried out by flushParentValidityClimb(). A setter that notifies
-     * the parent of the new value itself holds it over the notifying region, so the parent forms its verdict once,
-     * over the finished value, instead of once over the value being replaced and once over the value replacing it.
+     * Announces what this element's value became over the transaction. The pair carried is (value now, value at the
+     * last announcement), so a value that went A -> B -> A within the transaction says nothing, and the events an
+     * operation states rather than an element's state - an item added, an item removed - are emitted first, in the
+     * order the operations happened.
      */
-    protected suppressParentValidityClimb: boolean;
-    private parentValidityClimbPending;
-    /** Carries out the climb that a validity change made while suppressParentValidityClimb was held, if there was one. */
-    protected flushParentValidityClimb(): void;
+    protected [TxAnnounceValue](tx: Transaction, dirty: boolean, force: boolean, structural?: TxStructuralEvent[]): void;
+    /**
+     * Forms the verdict this element ends the transaction with and announces a transition of it. The container is
+     * told first, so a handler reads a tally that already includes this verdict, and it is enrolled in the same
+     * transaction: its own verdict is composed of its members', so a member that moves without a value change - an
+     * asynchronous validator, an error pushed in by hand - is what makes the container re-form its own. The
+     * transaction settles the deepest element first, so a container is reached only once its members have decided.
+     */
+    protected [TxSettleValidity](tx: Transaction): void;
     validate(revalidate?: boolean): void;
     get valid(): boolean;
     get fullValue(): any;
     get isChanged(): boolean;
+    /**
+     * Brings a fresh element into the state a binding of `source` is in: it records what it was declared as, takes
+     * on the extended properties and the actions `source` carries, and runs the eager ones over the value it was
+     * built with. The extended properties `overrides` states are written over the ones `source` carries, and they
+     * are in place before the eager pass, so an action reading one sees what the binding ends up carrying. The
+     * actions are the very instances `source` holds - what a binding takes on is data, not behaviour - and each is
+     * told about this element as it is taken on, so an action serving several bindings knows all of them.
+     */
+    protected boundFrom(source: FieldBase<any, X>, newValue: any, oldValue: any, overrides?: object): void;
     /**
      * Registers the actions a constructor received in its parameters: registration without the eager trigger,
      * because a constructor ends with a single this.actions.triggerEager(...) over the finished value, and an
@@ -208,10 +688,28 @@ export declare abstract class FieldBase<T = any> {
      */
     protected registerInitialActions(actions: FieldActionBase[]): void;
     registerAction(action: FieldActionBase): this;
+    /**
+     * Registers `action` so that `before` wraps it: `before` reaches it through the `supr` it is handed, instead of
+     * ending the run there. It is how an action is added to a chain someone else built and still sits inside a
+     * handler already registered, which registration order alone cannot arrange. `before` has to be registered on
+     * this element under the same identifier.
+     */
+    registerActionBefore(action: FieldActionBase, before: FieldActionBase): this;
+    /**
+     * Drops `action` from this element and answers whether it held it. The instance goes on serving every other
+     * element it was registered on: what is dropped is this element's registration, not the action. A validator
+     * withdraws the errors it put on this element as it goes, so the verdict the element reports is the one the
+     * validators it still holds reach.
+     */
+    unregisterAction(action: FieldActionBase): boolean;
+    /**
+     * Records that `action` is now registered on this element, and that a rollback has to take that back. The
+     * registration is not one of the state slots the snapshot covers, so it hands its own undo in.
+     */
+    private registered;
     triggerAction<T2 extends FieldActionBase>(actionClass: (abstract new (...args: any[]) => T2) & {
         classIdentifier: symbol;
     }, ...params: any[]): any;
-    private _validationEpoch;
     /**
      * Generation counter of the validators attached to this field. A Validator reads it when a run starts and drops
      * a result whose epoch no longer matches, so a validation still in flight when clearValidators() is called
@@ -221,6 +719,12 @@ export declare abstract class FieldBase<T = any> {
     clearValidators(): void;
 }
 
+/** what a Field holds beyond the common slots: the value itself, and whether it has been touched */
+declare interface FieldSlots<T = any> extends ElementSlots<T> {
+    value: T;
+    touched: boolean;
+}
+
 export declare type FieldsToValues<T extends GenericFieldsInterface> = {
     [K in keyof T]: T[K]['value'];
 };
@@ -228,6 +732,8 @@ export declare type FieldsToValues<T extends GenericFieldsInterface> = {
 declare namespace Form {
     export {
         DisplayMode,
+        transaction,
+        TransactionControl,
         FieldActionBase,
         ActionsMap,
         EnabledChangedAction,
@@ -255,6 +761,8 @@ declare namespace Form {
         EmptyField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
+        IFieldParams,
+        IBindParams,
         AbortEventHandlingException,
         FieldActionExecute,
         FieldBase,
@@ -285,6 +793,7 @@ declare namespace Form {
         RenderableValue,
         ValidationFunctionResult,
         ValidationFunction,
+        ValidatorBindingState,
         Validator
     }
 }
@@ -300,33 +809,60 @@ declare interface FormsConfig {
 
 export declare type GenericFieldsInterface = Record<string, FieldBase>;
 
-export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<GroupValue<T>> {
+export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<GroupValue<T>, X> {
+    protected get state(): ContainerSlots<GroupValue<T>>;
+    protected get raw(): ContainerSlots<GroupValue<T>>;
     private readonly _fields;
-    private _value;
-    private suppressNotifyValueChanged;
-    constructor(fields: T, params?: Partial<IFieldConstructorParams<GroupValueInput<T>>>);
+    constructor(fields: T, params?: IFieldParams<GroupValueInput<T>, X>);
+    /**
+     * The copy of a built value that serves as a baseline. The value getter hands out one object per version, and
+     * a baseline holding that same object would report every value as its own original.
+     */
+    private static baseline;
     private addField;
     private static isValidFields;
     static createFromFormData(data: Record<string, any> | null): Group;
     field<K extends keyof T>(fieldName: K): T[K] | null;
     get fields(): T;
+    protected get members(): FieldBase[];
     get value(): GroupValue<T>;
     /**
-     * Writes the members that the given value carries, without letting any single member announce the state in
-     * between: the group's own value notification and its own validation are both held back for the duration, so
-     * neither a ValueChangedAction nor a ValidChangedAction reports a verdict over a half-applied value. The
-     * caller decides what to announce once the whole value is in place. Both flags are restored to what they were,
-     * so a caller that is itself holding the group back stays in charge.
+     * Writes the members that the given value carries. The members are written one by one and the group says
+     * nothing in between: the transaction the assignment runs in measures the group's own value and its own verdict
+     * once, over the finished set, and announces each at most once.
      */
     private assignMembers;
     set value(newValue: GroupValueInput<T>);
+    /**
+     * Members are reset one by one rather than assigned as a whole value: the value setter writes only the keys the
+     * value carries, while a member the value leaves out has to end up holding what the template gives it. `source`
+     * supplies that per member, so a group reset from the template it was bound from matches a fresh binding of it.
+     */
+    protected resetTo(source: FieldBase, value: any): void;
     get touched(): boolean;
     set touched(touched: boolean);
     get fullValue(): Record<string, any>;
+    /**
+     * Records that a member changed its value, so that the transaction in progress works out at commit what this
+     * group's own value became and announces it once. A mutation method calls it itself; you rarely need to.
+     */
     notifyValueChanged(): void;
+    protected get composesValue(): boolean;
+    /**
+     * A group with nothing listening for its value does not compose one at all, so the copy it holds is from before
+     * the changes nobody received. A registration that adds a listener brings it up to date here, and what the
+     * listener is then told about is the change that follows it.
+     */
+    protected refreshPreviousValue(): void;
     get valid(): boolean;
+    protected composeValid(): boolean;
     validate(revalidate?: boolean): void;
-    clone(overrides?: Partial<IFieldConstructorParams<GroupValueInput<T>>>): Group<T>;
+    bind(data?: GroupValueInput<T>, overrides?: IBindParams<GroupValueInput<T>, X>): Group<T, X>;
+    /**
+     * A record need not name every member: a key it leaves out is taken from the declaration, the same way a member
+     * the constructor is given no value for takes the one it was declared with.
+     */
+    rebind(data: GroupValueInput<T>): this;
 }
 
 /** what Group.value reads back: the full field map, or null when no field serializes */
@@ -335,17 +871,25 @@ export declare type GroupValue<T extends GenericFieldsInterface> = FieldsToValue
 /** what Group.value and the Group constructor accept: keys left out are simply not assigned */
 export declare type GroupValueInput<T extends GenericFieldsInterface> = Partial<FieldsToValues<T>> | null;
 
+/**
+ * What bind() accepts beside the data it binds: everything a constructor takes except the value, which the data
+ * argument states. Of the members named here, bind() reads `originalValue`, `enabled` and `visibility`;
+ * `validators` and `actions` state what to register and are carried by the binding from its declaration, and the
+ * rest are the element's to establish.
+ */
+export declare type IBindParams<T = any, X extends object = {}> = Partial<Omit<IFieldConstructorParams<T>, 'value'>> & Partial<NoInfer<X>>;
+
 export declare interface IFieldConstructorActionsList {
     actions?: FieldActionBase[];
     validators?: FieldActionBase[];
 }
 
 /**
- * Parameters accepted by field constructors and by clone overrides.
+ * Parameters accepted by field constructors and by bind overrides.
  *
  * Only writable members are listed. valid, validating, fullValue and isChanged are getter-only, so assigning
- * them throws a TypeError. parent and fieldName are set by the container: until a Group or List installs them
- * as non-configurable accessors, assigning them is silently accepted, which is why the type rejects them.
+ * them throws a TypeError. So are parent and fieldName: a container writes the slots behind them when it takes
+ * an element, and nobody else can, which is why the type rejects them.
  */
 export declare type IFieldConstructorParams<T = any> = {
     value: T;
@@ -356,6 +900,20 @@ export declare type IFieldConstructorParams<T = any> = {
     errors: ValidationError[];
 } & IFieldConstructorActionsList;
 
+/**
+ * What an element's constructor accepts: the parameters the element answers for itself, together with the
+ * extended properties its X parameter declares.
+ *
+ * X is left out of inference, so an element built without a type argument carries no extended properties and a
+ * parameter object naming one is rejected as an excess property. A caller that wants them states them:
+ * `new Field<string, { label: string }>({ value: 'a', label: 'Name' })`.
+ *
+ * The two halves are made partial separately. `Partial<A & X>` is a mapped type over an intersection, which is
+ * what T is inferred through, and inference through it answers with one constituent of a union rather than the
+ * union: `new Field({ value: someStringOrNumber })` would be a Field<string>.
+ */
+export declare type IFieldParams<T = any, X extends object = {}> = Partial<IFieldConstructorParams<T>> & Partial<NoInfer<X>>;
+
 declare class InAllowedValues<T = any> extends Validator {
     constructor(allowedValues: T[], message?: RenderContentRef);
 }
@@ -373,31 +931,58 @@ declare class LengthInRange<T = any> extends Validator {
     constructor(minLength: number, maxLength: number, message?: RenderContentRef);
 }
 
-export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface> extends FieldBase<ListValue> {
-    private _value;
+export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<ListValue, X> {
+    protected get state(): ListSlots<T>;
+    protected get raw(): ListSlots<T>;
     private _itemTemplate?;
-    private _previousValue;
-    constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams<ListValue>>);
+    constructor(itemTemplate?: Group<T>, params?: IFieldParams<ListValue, X>);
+    /** The row array is copied as well: a rollback puts back the set the list held, not the array it went on to hold. */
+    protected [TxCapture](): TxSnapshot;
+    /**
+     * The copy of a built value that serves as a baseline. The value getter hands out one array per version, and a
+     * baseline holding that same array would report every value as its own original.
+     */
+    private static baseline;
     private processSetValueItem;
     /**
-     * Builds the item that fills a gap left by an insert beyond the end of the list: a copy of the item template with
-     * the template's own values, or an empty group when the list has no template.
+     * Builds the item that fills a gap left by an insert beyond the end of the list: the item template bound to its
+     * own values, or an empty group when the list has no template.
      */
     private createPaddingItem;
     private setValueInternal;
     get value(): ListValue;
     set value(newValue: Record<string, any>[]);
+    /**
+     * The rows are taken from `source` where the caller supplied no value of its own, so a list nested in a row that
+     * a whole-list assignment reuses ends up holding what the template gives it rather than what it held before.
+     */
+    protected resetTo(source: FieldBase, value: any): void;
     get touched(): boolean;
     set touched(touched: boolean);
-    clone(overrides?: Partial<IFieldConstructorParams<ListValue>>): List<T>;
+    bind(data?: ListValue, overrides?: IBindParams<ListValue, X>): List<T, X>;
+    /**
+     * Records that a row changed its value, so that the transaction in progress works out at commit what this
+     * list's own value became and announces it once. The mutation methods call it themselves; you rarely need to.
+     */
     notifyValueChanged(): void;
+    protected get composesValue(): boolean;
+    /**
+     * A list with nothing listening for its value does not compose one at all, so the copy it holds is from before
+     * the changes nobody received. A registration that adds a listener brings it up to date here, and what the
+     * listener is then told about is the change that follows it.
+     */
+    protected refreshPreviousValue(): void;
     get valid(): boolean;
+    protected composeValid(): boolean;
     validate(revalidate?: boolean): void;
+    protected get members(): FieldBase[];
     get(index: number): Group<T> | undefined;
     push(item: any): number;
     pop(): Group<T> | undefined;
     remove(index: number): Group<T> | undefined;
     insert(item: any, index: number): number;
+    /** Drops every row this list holds out of its tally, so a row that changes its verdict later is not counted. */
+    private releaseRows;
     clear(): void;
 }
 
@@ -413,6 +998,11 @@ export declare class ListItemRemovedAction extends FieldActionBase {
     execute(field: FieldBase, supr: FieldActionExecute, item: any, index: number): void;
 }
 
+/** what a List holds beyond the container slots: the rows themselves */
+declare interface ListSlots<T extends GenericFieldsInterface = GenericFieldsInterface> extends ContainerSlots<ListValue> {
+    rows: Group<T>[] | null;
+}
+
 /** what List.value reads back: one plain object per item, or null when the list is empty */
 export declare type ListValue = Record<string, any>[] | null;
 
@@ -530,9 +1120,20 @@ export declare class Statement {
     private readonly operator;
     private readonly operand2;
     constructor(operand1: OperandType, operator: Operator, operand2: OperandType);
+    /**
+     * The value an operand contributes. A field operand names a field of the record the statement is evaluated in:
+     * the same statement over a `List` reads row 3's field while row 3 is the record, and a field belonging to no
+     * record of the statement's own - a form field above the list - is read where it stands. A record that does not
+     * hold the field yet contributes undefined, which is what a half-built row answers with.
+     */
+    private static valueOf;
     get operand1Value(): any;
     get operand2Value(): any;
-    evaluate(): boolean;
+    /**
+     * The result of the statement, over the record `scope` belongs to where one is given and over the fields the
+     * statement was built from where it is not.
+     */
+    evaluate(scope?: FieldBase): boolean;
     /**
      * Recursively collects all fields used in this statement and its nested statements
      * @returns A set of all fields used in this statement
@@ -540,6 +1141,147 @@ export declare class Statement {
     collectFields(): Set<FieldBase>;
 }
 
+declare class Transaction {
+    private readonly participants;
+    /** what a rollback has to put back beyond the state slots, newest last */
+    private readonly undo;
+    /** true once the transaction has been unwound, which is what tells a run started inside it to say nothing */
+    private unwound;
+    /** the depth the announcement in progress is working at, -1 while none is */
+    private passDepth;
+    /** set while a pass is running and an element it has already passed the depth of gets enrolled */
+    private restartPass;
+    /** true for a transaction that was rolled back rather than committed */
+    get rolledBack(): boolean;
+    private participant;
+    /**
+     * Records the state of an element the first time the transaction modifies it. The whole of the mutable state
+     * goes into the snapshot rather than the part being written: a rollback that restored some of it would leave
+     * the element in a state the form never held.
+     */
+    touch(element: FieldBase): void;
+    /** Enrols an element as one whose value the commit has to announce. `force` skips the comparison. */
+    markValueChanged(element: FieldBase, force: boolean): void;
+    /** Enrols an element as one whose verdict the commit has to re-form. */
+    markValidityDirty(element: FieldBase): void;
+    /**
+     * Queues an event that states an operation rather than a state. Added and removed items have no net over a
+     * transaction, so they are neither compared nor coalesced: the commit emits them in the order they happened.
+     */
+    recordStructural(element: FieldBase, event: TxStructuralEvent): void;
+    /** True where the commit still owes this element a value announcement. */
+    willAnnounceValue(element: FieldBase): boolean;
+    /**
+     * Registers what a rollback has to put back beyond the element's state slots. The snapshot covers the slots,
+     * which is everything an ordinary write touches; an operation that replaces something else the element carries
+     * hands its own undo in here rather than making every snapshot carry the thing.
+     */
+    whenRolledBack(work: () => void): void;
+    /**
+     * Notes that an element at or below the depth the pass in progress is working at has been enrolled. The pass
+     * then gives up the rest of its batch and is started again over what is now owed, so the newcomer is reached
+     * before the containers above it: an element a handler writes must still be announced before the container
+     * whose composed value carries that write. The depth is only measured while a pass is running - outside one
+     * there is nothing the answer would change.
+     */
+    private noteDepth;
+    /**
+     * Puts every element the transaction modified back as it found it. Nothing is announced: from an observer's
+     * point of view the transaction never happened. What a rollback cannot take back are side effects - a handler
+     * that called a server during the transaction already did.
+     */
+    rollback(): void;
+    /**
+     * Announces what the transaction did. Values first and verdicts after, because a container's validators run
+     * with its value announcement and the verdict they reach is what the validity pass then reports. Both passes
+     * run deepest first - field, then row, then list - which is the order the change travelled in.
+     *
+     * A handler may write while the commit runs; its writes join this transaction, so both passes repeat until
+     * nothing is left dirty.
+     */
+    commit(): void;
+    /**
+     * The dirty participants a pass has to visit, one bucket per nesting depth; ties keep the order they were
+     * enrolled in. A nesting depth is a small integer, so the elements go into buckets rather than through a
+     * comparison sort: a whole-list assignment enrols one participant per field, and ordering those by comparison
+     * would cost more than the announcement it orders.
+     */
+    private buckets;
+    /**
+     * Runs one pass over the dirty participants, deepest bucket first; the caller repeats it until it answers
+     * false. The buckets are taken once, and the pass gives up as soon as a handler enrols an element at or below
+     * the depth being drained: that element is not in the bucket being walked, and going on would reach the
+     * containers above it first. The caller's next pass takes fresh buckets and finds it at its own depth.
+     */
+    private pass;
+    private announceValues;
+    private settleValidity;
+}
+
+/**
+ * Runs `fn` as one atomic change. The writes it makes land in the elements as they are made and the events they
+ * produce are announced once, at the end, over the net result.
+ *
+ * A call made while a transaction is already open joins it: nothing is committed until the outermost call
+ * returns. A throw out of `fn` rolls the whole transaction back and rethrows, and `tx.rollback()` rolls it back
+ * without an error, in which case the call answers undefined.
+ *
+ * The handle `fn` receives is usable only for the duration of that call; calling it afterwards throws a TypeError.
+ *
+ * @throws TypeError immediately if `fn` returns a thenable - a transaction cannot cross an await.
+ */
+export declare function transaction<R>(fn: (tx: TransactionControl) => R): R | undefined;
+
+export declare interface TransactionControl {
+    /**
+     * Undoes everything the transaction has done and ends it, announcing nothing. It unwinds from the point of
+     * the call, so nothing after it runs. There are no savepoints: a nested call rolls back the whole transaction
+     * it joined, not its own part of it.
+     *
+     * @throws TypeError where the transaction the handle belongs to has already closed.
+     */
+    rollback(): never;
+}
+
+declare const TxAnnounceValue: unique symbol;
+
+/**
+ * The protocol a transaction drives its participants through. The four members are symbol-keyed so that they
+ * carry no name a consumer could reach or collide with, and they live on the prototype, so no walker over an
+ * element's own keys sees them either.
+ */
+declare const TxCapture: unique symbol;
+
+declare const TxRestore: unique symbol;
+
+declare const TxSettleValidity: unique symbol;
+
+/**
+ * A transaction is the unit an observer sees a change in. Every mutating operation runs inside one: where the
+ * caller opens none, the operation is the transaction, so a single write is atomic without anything having to be
+ * remembered at the call site.
+ *
+ * Writes land in the element straight away and only the announcement waits. At commit the net transitions are
+ * measured against the state the elements last announced and each is announced once, so a value that goes A -> B
+ * -> A within one transaction says nothing. Validators run while the transaction is open, because the verdict
+ * they reach is what the commit announces; every other action fires at commit.
+ *
+ * A transaction may not cross an await: transaction() throws when the callback returns a thenable. Two
+ * overlapping transactions therefore cannot exist, and an asynchronous validator settling later opens one of its
+ * own at that moment.
+ */
+/** the slots of one element as they stood when the transaction first modified it */
+declare type TxSnapshot = Record<string, any>;
+
+/** a ListItemAddedAction or ListItemRemovedAction waiting for the commit that will emit it */
+declare interface TxStructuralEvent {
+    actionClass: (abstract new (...args: any[]) => FieldActionBase) & {
+        classIdentifier: symbol;
+    };
+    item: any;
+    index: number;
+}
+
 /**
  * Base validation error class with component rendering capabilities
  */
@@ -588,13 +1330,6 @@ export declare type ValidationFunctionResult = ValidationError[] | null;
  */
 export declare class Validator<T = any> extends ValueChangedAction {
     private readonly source;
-    /**
-     * Sequence number of the newest run of this validator, per field. Every execution takes the next number, and a
-     * result is applied only while its number is still the newest one, so a slow run cannot overwrite the verdict of
-     * a faster one that started after it. The key is the field because one validator instance may be registered on
-     * several fields, each with a sequence of its own.
-     */
-    private readonly runs;
     /**
      * Creates a new validator
      * @param validationFn Function that validates the field value and returns errors or null
@@ -610,18 +1345,43 @@ export declare class Validator<T = any> extends ValueChangedAction {
     private claim;
     static get classIdentifier(): symbol;
     get eager(): boolean;
+    /**
+     * Takes this validator off `field`: the errors it put there are withdrawn and the verdict is re-formed over what
+     * the validators the field still holds have to say. Withdrawing them is what keeps a field from staying invalid
+     * on an error no validator is left to take back.
+     */
+    unregisterFrom(field: FieldBase): void;
+    /**
+     * What this validator remembers about one of the fields it validates. One instance may be registered on several
+     * fields - every row of a list carries the instances the item template carries - so each field has a record of
+     * its own. A subclass that remembers more widens the record by overriding `newBindingState`.
+     */
+    protected bindingState(field: FieldBase<any>): ValidatorBindingState;
+    /**
+     * The record a field starts with. `run` is the sequence number of the newest run over that field: every
+     * execution takes the next one and a result is applied only while its number is still the newest, so a slow run
+     * cannot overwrite the verdict of a faster one that started after it.
+     */
+    protected newBindingState(): ValidatorBindingState;
     protected replacePlaceholdersFunction(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;
     protected replacePlaceholders(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;
 }
 
+/** What a validator remembers about one field it is registered on; a subclass widens it. */
+export declare interface ValidatorBindingState {
+    run: number;
+}
+
 export declare namespace Validators {
     export {
         CompareTo,
+        CompareToTarget,
         InAllowedValues,
         Required_2 as Required,
         Pattern,
         ValidationFunctionResult,
         ValidationFunction,
+        ValidatorBindingState,
         Validator,
         MinValue,
         MaxValue,