@dynamicforms/vue-forms 0.12.0 → 0.16.0

package/dist/index.d.ts

@@ -4,10 +4,16 @@ import { DefineComponent } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
 
+/**
+ * Thrown from a handler to end the run it is in. What the trigger answers with is the exception itself rather than
+ * `null`, so a caller can tell a run a handler ended from one that reached no handler at all - and the setters
+ * that ask a `*Changing*` handler read it as a refusal and write nothing.
+ */
 export declare class AbortEventHandlingException extends Error {
 }
 
 export declare class Action<T extends ActionValue = ActionValue, X extends object = {}> extends Field<T, X> {
+    get [Symbol.toStringTag](): string;
     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
@@ -47,18 +53,22 @@ export declare class Action<T extends ActionValue = ActionValue, X extends objec
 declare type ActionExecutor = (field: FieldBase, supr: FieldActionExecute, ...params: any[]) => any;
 
 /**
- * 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
+ * The actions one declaration has registered, in registration order. A trigger walks them from the end backwards
+ * and passes over the ones registered under another identifier, so the newest registration of an identifier is its
  * 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.
+ *
+ * The order is the whole index. An element carries a handful of actions, and a walk over that many is cheaper than
+ * a keyed lookup as well as smaller: measured over three actions, the walk is about twice as fast as `Map.get` and
+ * the two maps it replaces cost about 500 bytes per declaration.
  */
 export declare class ActionsMap {
-    /** every action registered here, in registration order across all identifiers */
-    private readonly registeredActions;
-    /** 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;
+    /**
+     * Every action registered here, in registration order. It is replaced rather than written when an action is
+     * dropped, so a run already walking it finishes on the array it started with and the removal takes effect from
+     * the next trigger.
+     */
+    private actions;
     /**
      * 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
@@ -66,11 +76,7 @@ export declare class ActionsMap {
      * 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.
-     */
+    /** Drops `action` and answers whether it was registered here. */
     unregister(action: FieldActionBase): boolean;
     /** True where something is registered under `identifier`. */
     willTrigger(identifier: symbol): boolean;
@@ -80,29 +86,35 @@ export declare class ActionsMap {
     trigger<T extends FieldActionBase>(ActionClass: (abstract new (...args: any[]) => T) & {
         classIdentifier: symbol;
     }, field: FieldBase, ...params: any[]): any;
-    /** Runs the eager actions of every identifier, each group on its own. */
+    /**
+     * Runs the eager actions of every identifier, each group on its own. A group is entered at its outermost eager
+     * action, which is the last one registered under that identifier.
+     */
     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 */
+    /** the validators registered here, in registration order */
     get validators(): Validator[];
-    clone(): 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.
+     * Tells every action here that it serves `owner`. A binding reads the map its declaration holds, so this is what
+     * announces the new element to the actions already in it - the way registering an action announces the elements
+     * it comes to serve.
      */
     bindTo(owner: FieldBase): void;
+    /** True where no eager action of `identifier` stands after `index`, which makes `index` the group's entry. */
+    private static outermostEager;
     /**
-     * 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.
+     * Enters a group at its outermost action. An abort ends the run and is answered with rather than raised: the
+     * exception is what the caller receives, so a run a handler ended is told apart from one that reached no handler
+     * and from one whose handler answered null.
      */
-    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;
+    /**
+     * Walks from `index` backwards to the first action of `identifier`, handing it a `supr` that continues at the one
+     * before it. The actions registered under other identifiers are passed over, so the array needs no grouping of
+     * its own; the closures exist for the length of the run and only as deep as the run actually goes.
+     */
+    private walk;
 }
 
 export declare interface ActionValue {
@@ -110,6 +122,12 @@ export declare interface ActionValue {
     icon?: string;
 }
 
+/**
+ * The values a field may hold: a fixed list, or a reference or a callback for a list that is filled in or replaced
+ * after the validator is built - the options a server answers with, or the ones another field's value leaves open.
+ */
+declare type AllowedValues<T> = T[] | Ref<T[]> | (() => T[]);
+
 /**
  * Depending on the useMarkdownInValidators setting, return either markdown or a plain string error message
  * @param mdErrorString markdown source to optionally be stripped
@@ -235,6 +253,9 @@ declare interface ContainerSlots<T = any> extends ElementSlots<T> {
     cachedValueVersion: number;
 }
 
+/** What a form element's visibility is when nothing sets it. It is a starting value, never a fallback for input. */
+export declare const defaultDisplayMode = DisplayMode.FULL;
+
 /**
  * DisplayMode enum provides an enumeration for supported ways of rendering a particular object in the DOM
  */
@@ -246,8 +267,22 @@ export declare enum DisplayMode {
 }
 
 export declare namespace DisplayMode {
+    /**
+     * Resolves a constant's name, case insensitive, to the constant it names. Anything else - a misspelled name, a
+     * value that is not a string - throws an `Error` naming it. A mode nobody defined is an error at the point it
+     * arrives, not a field that renders as `FULL` and is never questioned.
+     */
     export function fromString(mode: string): DisplayMode;
+    /**
+     * Resolves a DisplayMode number, or a constant's name (case insensitive), to a DisplayMode. A number that is
+     * none of the constants, a string that names none, and input that is neither a number nor a string all throw an
+     * `Error` naming the value. Ask `isDefined` where the answer is to be judged rather than raised.
+     */
     export function fromAny(mode: any): DisplayMode;
+    /**
+     * Answers whether the input is a DisplayMode: a number that is one of the constants, or a string naming one,
+     * case insensitive. This is the way to ask that does not throw; it answers `false` where `fromAny` raises.
+     */
     export function isDefined(mode: number | string): boolean;
 }
 
@@ -269,8 +304,8 @@ export declare namespace DisplayMode {
  * 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.
+ * What they do reach on an element is `_actions` once something is registered, `_fields` and the guarded view
+ * over it on a `Group`, and `_itemTemplate` on a `List`. All of them lead downwards only.
  */
 declare interface ElementSlots<T = any> {
     /** the value the element was given at construction; isChanged compares against it */
@@ -284,6 +319,8 @@ declare interface ElementSlots<T = any> {
     valueVersion: number;
     /** how many asynchronous validation runs are in flight on this element */
     validatingCount: number;
+    /** how many direct children answer `validating` with true; a child that starts or stops running moves it */
+    validatingChildren: 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 */
@@ -308,8 +345,6 @@ declare interface ElementSlots<T = any> {
     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);
     static get classIdentifier(): symbol;
@@ -329,6 +364,7 @@ export declare class ExecuteAction extends FieldActionBase {
 }
 
 export declare class Field<T = any, X extends object = {}> extends FieldBase<T, X> {
+    get [Symbol.toStringTag](): string;
     protected get state(): FieldSlots<T>;
     protected get raw(): FieldSlots<T>;
     /** the value slot itself, without the notifications the value setter carries around a write */
@@ -347,6 +383,12 @@ export declare class Field<T = any, X extends object = {}> extends FieldBase<T,
     protected init(params?: IFieldParams<T, X>): void;
     get value(): T;
     set value(newValue: T);
+    /**
+     * The container that holds this field. A `List` holds rows and a row is a `Group`, so a field is never a `List`'s
+     * child and the link is a `Group` wherever there is one: `field.parent?.fields.other` is the sibling lookup, and
+     * it is typed here.
+     */
+    get parent(): Group | undefined;
     get touched(): boolean;
     set touched(touched: boolean);
     bind(data?: T, overrides?: IBindParams<T, X>): this;
@@ -404,6 +446,19 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      */
     get __v_skip(): boolean;
     get __v_isReactive(): boolean;
+    /**
+     * Names the element's class, which is what a structural comparison of two elements answers on. An element keeps
+     * its state in private class fields, so a walk over own keys reaches none of it; lodash reads this tag through
+     * Object.prototype.toString before it compares anything, and a tag it does not know ends the comparison there.
+     * Two elements are therefore equal only where they are the same element. What they hold is compared as
+     * isEqual(a.value, b.value).
+     *
+     * It is an accessor on the prototype, so an element carries nothing for it, and `Object.prototype.toString`
+     * answers `[object Field]` rather than `[object Object]`. Each class states its own name as a literal: a
+     * minifier renames the class itself, so reading the constructor's name would report whatever the build called
+     * it.
+     */
+    get [Symbol.toStringTag](): string;
     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>;
@@ -499,16 +554,56 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      * 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.
+     * The two validation counters are the slots the element keeps: they count runs that are in flight, and a
+     * rollback cannot un-start one. Put back, the counts 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 */
+    /**
+     * True while an asynchronous validation is in flight on this element or on anything below it, so a form answers
+     * for the whole tree it holds. The answer is a pair of counters rather than a walk: the element's own runs, and
+     * how many of its children answer the same question with true. A child that starts running while it was idle,
+     * or stops while it was the last one running, moves its container's tally, and a tally that changes the
+     * container's own answer moves the one above it - the transition costs the nesting depth and the read costs
+     * nothing.
+     */
     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;
+    /**
+     * Records that a child started or stopped answering `validating` with true, and carries the transition further
+     * up where it changes this element's own answer.
+     */
+    protected childValidatingChanged(started: boolean): void;
+    /**
+     * True while an `Action.execute()` at or below this element has yet to settle. An `Action` answers for its own
+     * runs; a container answers for the actions below it; anything else answers false, because an element that is
+     * not an action has nothing to execute.
+     *
+     * It states one thing and `validating` states the other, so a form that gates a submit button on the tree being
+     * idle reads both.
+     */
+    get busy(): boolean;
+    /**
+     * The composed answer a container gives `busy`, memoised by Vue. An `Action` counts its executions in a counter
+     * of its own, which no container is told about, so the answer is composed over the members instead of tallied;
+     * the computed keeps the walk from repeating while nothing it read has moved, and a member that is itself a
+     * container answers from its own computed.
+     */
+    protected get busyRead(): boolean;
+    /** What busyRead computes. A container answers over its members; anything else executes nothing. */
+    protected composeBusy(): boolean;
+    /**
+     * Resolves once nothing at or below this element is running - no asynchronous validation, no `Action.execute()`
+     * that has yet to settle. It is what a submit path awaits instead of polling `validating` and `busy`, and it
+     * resolves at once where nothing is running to begin with.
+     *
+     * It answers for the moment it resolves and makes no promise about the one after: work started later leaves the
+     * element running again, so a caller that has to act on a settled tree reads what it needs immediately after
+     * awaiting rather than at its leisure.
+     */
+    settled(): Promise<void>;
     /**
      * 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
@@ -521,8 +616,17 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      * 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.
+     *
+     * A `List` holds rows and a row is a `Group`, so only a container can be a `List`'s child: `Field` narrows the
+     * type to `Group | undefined`, and the sibling lookup `field.parent?.fields.other` is typed on a field.
      */
-    get parent(): Group | undefined;
+    get parent(): Group | List | undefined;
+    /**
+     * The same link at the type the internals reach through. The protected members a container is told things
+     * through - childValidatingChanged, childValidityChanged - are declared here, and a union of two subclasses is
+     * not an instance of this class, which is what a protected access needs.
+     */
+    private get container();
     /** when member of a Group, fieldName specifies the name of this field. Written by the group, read-only after */
     get fieldName(): string | undefined;
     /**
@@ -560,13 +664,30 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
     /** 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.
+     * The map an element that was declared rather than bound registers its actions in, absent while it has registered
+     * none. A binding holds no map of its own: `boundActions` reads the one its declaration holds.
      */
     protected _actions?: ActionsMap;
+    /**
+     * The actions this element answers to, absent where nothing is registered. A binding holds the very map its
+     * declaration holds rather than a copy of it, so the slot is read directly: what a trigger costs is one property
+     * read, and a rule registered on a `List`'s item template reaches every row through the map they share - the
+     * rows built before the registration as much as the ones built after.
+     */
+    protected get boundActions(): ActionsMap | undefined;
+    /** Records that `binding` was made from this element, so a later registration can reach it. */
+    protected noteBinding(binding: FieldBase): void;
+    /**
+     * The bindings made from this element that are still alive, and this element itself. The dead references are
+     * dropped as they are found, which is what keeps the set from growing over the life of a long-lived declaration.
+     */
+    protected get boundElements(): FieldBase[];
+    /**
+     * The map registrations go into: the declaration's, since that is where behaviour lives. The map is made on the
+     * first registration and handed to every binding already made from the declaration, so all of them go on reading
+     * one map through a slot of their own.
+     */
     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
@@ -653,6 +774,12 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      * pass of its own.
      */
     protected get composesValue(): boolean;
+    /**
+     * Whether `child` composes its value from members of its own. It is what lets a container tell a nested
+     * container from a leaf without knowing the classes below it, the way `resetChild` reaches a reset it does not
+     * know the shape of.
+     */
+    protected childComposesValue(child: FieldBase): boolean;
     /**
      * 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
@@ -670,7 +797,7 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
     protected [TxSettleValidity](tx: Transaction): void;
     validate(revalidate?: boolean): void;
     get valid(): boolean;
-    get fullValue(): any;
+    get fullValue(): T;
     get isChanged(): boolean;
     /**
      * Brings a fresh element into the state a binding of `source` is in: it records what it was declared as, takes
@@ -725,6 +852,15 @@ declare interface FieldSlots<T = any> extends ElementSlots<T> {
     touched: boolean;
 }
 
+/**
+ * What Group.fullValue reads back. The indexed access reads each field's fullValue getter, so a nested group
+ * contributes its own full structure rather than the partial one its `value` builds, and the recursion carries
+ * the guarantee all the way down: every key is present and none of them is null.
+ */
+export declare type FieldsToFullValues<T extends GenericFieldsInterface> = {
+    [K in keyof T]: T[K]['fullValue'];
+};
+
 export declare type FieldsToValues<T extends GenericFieldsInterface> = {
     [K in keyof T]: T[K]['value'];
 };
@@ -732,6 +868,7 @@ export declare type FieldsToValues<T extends GenericFieldsInterface> = {
 declare namespace Form {
     export {
         DisplayMode,
+        defaultDisplayMode,
         transaction,
         TransactionControl,
         FieldActionBase,
@@ -758,7 +895,6 @@ declare namespace Form {
         MessagesWidget,
         Field,
         NullableField,
-        EmptyField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
         IFieldParams,
@@ -768,6 +904,7 @@ declare namespace Form {
         FieldBase,
         GenericFieldsInterface,
         FieldsToValues,
+        FieldsToFullValues,
         GroupValue,
         GroupValueInput,
         Group,
@@ -790,11 +927,7 @@ declare namespace Form {
         ValidationError,
         ValidationErrorText,
         ValidationErrorRenderContent,
-        RenderableValue,
-        ValidationFunctionResult,
-        ValidationFunction,
-        ValidatorBindingState,
-        Validator
+        RenderableValue
     }
 }
 export default Form;
@@ -803,26 +936,80 @@ export declare const forms: {
     install(app: any, options?: Partial<FormsConfig>): void;
 };
 
-declare interface FormsConfig {
+/**
+ * Global configuration for @dynamicforms/vue-forms.
+ *
+ * The configuration is module-global: `setConfig` and the plugin's `install` write the single record this module
+ * holds, so in a process running several Vue apps the configuration applied last is the one all of them read.
+ */
+export declare interface FormsConfig {
+    /** Whether the built-in validators phrase their error messages as `MdString` markdown instead of plain text. */
     useMarkdownInValidators: boolean;
 }
 
 export declare type GenericFieldsInterface = Record<string, FieldBase>;
 
+/** The current configuration. The object is the module's own record, and reading it again reports later writes. */
+export declare function getConfig(): FormsConfig;
+
 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>>;
+    get [Symbol.toStringTag](): string;
+    protected get state(): GroupSlots<GroupValue<T>>;
+    protected get raw(): GroupSlots<GroupValue<T>>;
     private readonly _fields;
     constructor(fields: T, params?: IFieldParams<GroupValueInput<T>, X>);
+    /**
+     * The name array is copied as well: a rollback puts back the set of members the group 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 object per version, and
      * a baseline holding that same object would report every value as its own original.
      */
     private static baseline;
-    private addField;
+    /**
+     * Takes `field` into this group under `fieldName`. The group ends up holding it exactly as it holds a field the
+     * constructor was given: the field carries the back-reference and the name, its verdict counts towards the
+     * group's, and a rule of the field's that names another member of the form reaches it here.
+     *
+     * The change is announced through the ordinary path, so a group whose value the new field adds to says so once
+     * the transaction closes, and its verdict is re-formed over the members it now holds. The baseline behind
+     * `isChanged` is not rewritten: a group that gains a field holds something its original value does not carry,
+     * and reports itself changed until `originalValue` is written.
+     *
+     * @throws Error where this group already holds a field under `fieldName`.
+     * @throws TypeError where `field` already belongs to a container - pass a `bind()` of it instead.
+     */
+    addField(fieldName: string, field: FieldBase): this;
+    /**
+     * Takes the field held under `fieldName` out of this group and hands it back, answering undefined where the
+     * group holds no field of that name. The field is released whole: the back-reference and the name are gone, its
+     * verdict and its runs in flight no longer count towards the group's, and it is free to be taken by another
+     * container. What it holds - its value, its errors, the change history behind `isChanged` - is its own to report.
+     *
+     * The change is announced through the ordinary path, so the group's value and verdict settle over the members it
+     * has left. The baseline behind `isChanged` is not rewritten, the same way it is not on `addField`.
+     */
+    removeField(fieldName: string): FieldBase | undefined;
+    /**
+     * Writes one entry of the member map. The map is typed by the fields interface, which names the members a group
+     * of that type holds and no others, so both here and in dropEntry it is reached as the plain record it is.
+     */
+    private static setEntry;
+    /** Drops one entry out of the member map. */
+    private static dropEntry;
     private static isValidFields;
     static createFromFormData(data: Record<string, any> | null): Group;
     field<K extends keyof T>(fieldName: K): T[K] | null;
+    /**
+     * The typed map of this group's members. What it hands out is a view over the map the group holds: reading it
+     * reaches the members themselves, and every write to it is refused - addField() and removeField() are what
+     * change the set. The view is built the first time something asks for it.
+     *
+     * Reading through it is a tracked read of the set of members, so a template rendering off `group.fields`
+     * re-renders when a field is added or removed; what a member itself holds is tracked by that member.
+     */
     get fields(): T;
     protected get members(): FieldBase[];
     get value(): GroupValue<T>;
@@ -841,7 +1028,7 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     protected resetTo(source: FieldBase, value: any): void;
     get touched(): boolean;
     set touched(touched: boolean);
-    get fullValue(): Record<string, any>;
+    get fullValue(): FieldsToFullValues<T>;
     /**
      * 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.
@@ -856,7 +1043,16 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     protected refreshPreviousValue(): void;
     get valid(): boolean;
     protected composeValid(): boolean;
+    get busy(): boolean;
+    protected composeBusy(): boolean;
     validate(revalidate?: boolean): void;
+    /**
+     * States that `res` was built from the members handed to it. A subclass whose constructor takes something other
+     * than `(fields, params)` - one that composes its own members and passes them to super - never sees them, and
+     * would answer with a binding carrying the declaration's data instead of the record's. That is a difference no
+     * reader would find, so it is refused here rather than returned.
+     */
+    private static assertTookFields;
     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
@@ -865,19 +1061,32 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     rebind(data: GroupValueInput<T>): this;
 }
 
-/** what Group.value reads back: the full field map, or null when no field serializes */
-export declare type GroupValue<T extends GenericFieldsInterface> = FieldsToValues<T> | null;
+/** what a Group holds beyond the container slots: the names of its members, in the order it took them */
+declare interface GroupSlots<T = any> extends ContainerSlots<T> {
+    /**
+     * The names the group holds its members under. The member map itself is a plain object beside the state, so
+     * this array is what a reader inside an effect depends on: a member added or removed re-runs the effect, and a
+     * rolled-back transaction puts the set back with the rest of the slots.
+     */
+    fieldNames: string[];
+}
+
+/**
+ * What Group.value reads back: the values of the fields that serialize, or null when none does. Every key is
+ * optional, because a field that is disabled is left out of the object the group builds.
+ */
+export declare type GroupValue<T extends GenericFieldsInterface> = Partial<FieldsToValues<T>> | null;
 
 /** 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.
+ * What bind() accepts beside the data it binds: the three members a binding takes over from the element it was
+ * bound from, and the extended properties. What is left out is left out because a binding cannot honour it -
+ * `validators` and `actions` are carried from the declaration rather than supplied, and `touched` and `errors`
+ * are what the binding establishes for itself as it validates.
  */
-export declare type IBindParams<T = any, X extends object = {}> = Partial<Omit<IFieldConstructorParams<T>, 'value'>> & Partial<NoInfer<X>>;
+export declare type IBindParams<T = any, X extends object = {}> = Partial<Pick<IFieldConstructorParams<T>, 'originalValue' | 'enabled' | 'visibility'>> & Partial<NoInfer<X>>;
 
 export declare interface IFieldConstructorActionsList {
     actions?: FieldActionBase[];
@@ -887,7 +1096,7 @@ export declare interface IFieldConstructorActionsList {
 /**
  * Parameters accepted by field constructors and by bind overrides.
  *
- * Only writable members are listed. valid, validating, fullValue and isChanged are getter-only, so assigning
+ * Only writable members are listed. valid, validating, busy, fullValue and isChanged are getter-only, so assigning
  * 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.
  */
@@ -915,7 +1124,7 @@ export declare type IFieldConstructorParams<T = any> = {
 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);
+    constructor(allowedValues: AllowedValues<T>, message?: RenderContentRef);
 }
 
 export declare function isCallableFunction(msg?: RenderContentRef): msg is RenderContentCallable;
@@ -927,11 +1136,12 @@ export declare function isCallableFunction(msg?: RenderContentRef): msg is Rende
  */
 export declare function isSimpleComponentDef(msg?: RenderContentRef): msg is SimpleComponentDef;
 
-declare class LengthInRange<T = any> extends Validator {
+declare class LengthInRange extends Validator {
     constructor(minLength: number, maxLength: number, message?: RenderContentRef);
 }
 
 export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<ListValue, X> {
+    get [Symbol.toStringTag](): string;
     protected get state(): ListSlots<T>;
     protected get raw(): ListSlots<T>;
     private _itemTemplate?;
@@ -949,9 +1159,13 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
      * own values, or an empty group when the list has no template.
      */
     private createPaddingItem;
+    /** Records that the set of rows changed, so `items` rebuilds the frozen array it hands out at the next read. */
+    private rowsChanged;
+    /** True where `next` is a different set of rows than `previous`: another count, or another row at a position. */
+    private static rowsDiffer;
     private setValueInternal;
     get value(): ListValue;
-    set value(newValue: Record<string, any>[]);
+    set value(newValue: ListValue);
     /**
      * 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.
@@ -974,8 +1188,31 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
     protected refreshPreviousValue(): void;
     get valid(): boolean;
     protected composeValid(): boolean;
+    get busy(): boolean;
+    protected composeBusy(): boolean;
     validate(revalidate?: boolean): void;
     protected get members(): FieldBase[];
+    /**
+     * How many rows this list holds. The read is tracked, so a template rendering off it re-renders as rows come and
+     * go.
+     */
+    /**
+     * Every row of this list, each one built from all of its fields. Where `value` states what the list serializes -
+     * rows composed of the fields that are enabled, and null where the list is empty - this states what the list
+     * holds: the disabled fields are in it too, and an empty list reads back as an empty array rather than as null.
+     */
+    get fullValue(): FieldsToFullValues<T>[];
+    get length(): number;
+    /**
+     * The rows this list holds, oldest position first. The array is a frozen copy: it states what the list held at
+     * the read and nothing writes back through it - `push`, `insert`, `remove` and `clear` are what change the set -
+     * so a caller may hold on to it. The rows in it are the live elements, so reading one reports what it holds now.
+     *
+     * The copy is built once per change of the set and handed to every reader until the next one: a write inside a
+     * row changes what the list serializes without changing which rows it holds, and the array a reader took stays
+     * the same one across such a write.
+     */
+    get items(): readonly Group<T>[];
     get(index: number): Group<T> | undefined;
     push(item: any): number;
     pop(): Group<T> | undefined;
@@ -1001,12 +1238,20 @@ export declare class ListItemRemovedAction extends FieldActionBase {
 /** 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;
+    /**
+     * Counts the changes to the set of rows. `items` rebuilds the frozen array it hands out when it moves, and
+     * only then: a write inside a row changes what the list serializes without changing which rows it holds.
+     */
+    rowsVersion: number;
+    /** the frozen array `items` last handed out, together with the rows version it was built from */
+    cachedItems: readonly Group<T>[] | null;
+    cachedItemsVersion: number;
 }
 
 /** 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;
 
-declare class MaxLength<T = any> extends Validator {
+declare class MaxLength extends Validator {
     constructor(maxLength: number, message?: RenderContentRef);
 }
 
@@ -1025,7 +1270,7 @@ export declare class MdString extends String {
 
 export declare const MessagesWidget: DefineComponent<Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
-declare class MinLength<T = any> extends Validator {
+declare class MinLength extends Validator {
     constructor(minLength: number, message?: RenderContentRef);
 }
 
@@ -1073,7 +1318,7 @@ export declare namespace Operator {
     export function isLogicOperator(operator: Operator): boolean;
 }
 
-declare class Pattern<T = any> extends Validator {
+declare class Pattern extends Validator {
     constructor(pattern: RegExp, message?: RenderContentRef);
 }
 
@@ -1102,10 +1347,23 @@ export declare type RenderContentNonCallable = string | MdString | SimpleCompone
  */
 export declare type RenderContentRef = RenderContent | Ref<RenderContent>;
 
-declare class Required_2<T = any> extends Validator {
-    constructor(message?: RenderContentRef);
+declare class Required_2 extends Validator {
+    constructor(options?: RequiredOptions);
+    constructor(message?: RenderContentRef, options?: RequiredOptions);
 }
 
+/** How the value is read before its length is taken. */
+declare interface RequiredOptions {
+    /**
+     * Whether a string is trimmed before it is measured, so that whitespace alone is no value. Defaults to true.
+     * Set it to false where the spaces are part of what the field holds.
+     */
+    trim?: boolean;
+}
+
+/** Writes the members `newConfig` names and leaves the rest as they stand. */
+export declare function setConfig(newConfig: Partial<FormsConfig>): void;
+
 /**
  * Interface for custom component content definition
  */
@@ -1119,6 +1377,21 @@ export declare class Statement {
     private readonly operand1;
     private readonly operator;
     private readonly operand2;
+    /**
+     * An operand is a nested `Statement`, a `FieldBase` whose value is compared, or a literal. `undefined` and a
+     * function are neither: they are what a misspelled field name and a field accessor handed over uncalled answer
+     * with, and a statement built from one compares nothing and never fires. The position names which of the two
+     * operands is at fault, so the error points at the place the name was written.
+     */
+    private static validateOperand;
+    /**
+     * `NOT` reads one operand, so it is stated with one. Every other operator compares two and takes both, and so
+     * does an operator held in a variable - `Operator.fromString()` answers with the type rather than with the
+     * constant, and the compiler cannot tell from it which of the two forms is meant.
+     *
+     * @throws TypeError where an operand the statement reads is undefined or a function.
+     */
+    constructor(operand1: OperandType, operator: Operator.NOT);
     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:
@@ -1145,6 +1418,8 @@ declare class Transaction {
     private readonly participants;
     /** what a rollback has to put back beyond the state slots, newest last */
     private readonly undo;
+    /** what the commit has to do once the change stands, in the order it was handed in */
+    private readonly settled;
     /** 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 */
@@ -1177,6 +1452,12 @@ declare class Transaction {
      * hands its own undo in here rather than making every snapshot carry the thing.
      */
     whenRolledBack(work: () => void): void;
+    /**
+     * Registers work that runs once the transaction has committed, and not at all where it is rolled back. It is
+     * how an operation defers a step that cannot be taken back - cancelling work in flight, for one - until the
+     * change it belongs to actually stands.
+     */
+    whenCommitted(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
@@ -1286,6 +1567,24 @@ declare interface TxStructuralEvent {
  * Base validation error class with component rendering capabilities
  */
 export declare class ValidationError {
+    code?: string | undefined;
+    /**
+     * Machine-readable identifier of what failed, in kebab-case. Every validator this library ships states one, so
+     * code that reacts to a particular failure does not have to match the message text, which is translated and
+     * configurable. It is optional: an error built by hand carries whatever its author gives it, or nothing.
+     */
+    constructor(code?: string | undefined);
+    /**
+     * True where `other` is an error of this class that renders exactly as this one does and reports the same code.
+     * Two runs of one validator over an unchanged value produce two instances of one message, and this is what lets
+     * the validator hand the field back the instance it already holds rather than a fresh one: an equal error is not
+     * a new error, and nothing re-renders over a verdict that did not move.
+     *
+     * The comparison is over what renders - the component, its bindings, its body and the classes - because that is
+     * what a reader of `field.errors` sees. A structural comparison of the errors themselves answers nothing useful:
+     * `ValidationErrorRenderContent` holds a Vue `computed`, and two of those are never structurally equal.
+     */
+    sameAs(other: ValidationError): boolean;
     get componentName(): string;
     get componentBindings(): {};
     get componentBody(): string;
@@ -1299,7 +1598,7 @@ export declare class ValidationErrorRenderContent extends ValidationError {
     classes: ClassTypes;
     private text;
     private textType;
-    constructor(text: RenderContentRef, classes?: ClassTypes);
+    constructor(text: RenderContentRef, classes?: ClassTypes, code?: string);
     get resolvedText(): RenderContentNonCallable;
     get getTextType(): "string" | "md" | "component";
     get componentName(): string;
@@ -1314,21 +1613,27 @@ export declare class ValidationErrorRenderContent extends ValidationError {
 export declare class ValidationErrorText extends ValidationError {
     text: string;
     classes: ClassTypes;
-    constructor(text: string, classes?: ClassTypes);
+    constructor(text: string, classes?: ClassTypes, code?: string);
     get componentName(): string;
     get componentBody(): string;
     get extraClasses(): ClassTypes;
 }
 
-export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: FieldBase<T>) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
+/**
+ * What a validator does with a value. `signal` aborts when the verdict this call would reach stops counting - a
+ * newer run over the same field, a field the validator was taken off once that removal stands, a transaction that
+ * was unwound - so an asynchronous check hands it to the work it commissions and stops paying for an answer nobody
+ * will read. A function that has nothing to cancel ignores it.
+ */
+declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: FieldBase<T>, signal: AbortSignal) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
 
-export declare type ValidationFunctionResult = ValidationError[] | null;
+declare type ValidationFunctionResult = ValidationError[] | null;
 
 /**
  * Validator is a specialized action that performs validation when a field's value changes.
  * It automatically adds/removes validation errors from the field's errors array.
  */
-export declare class Validator<T = any> extends ValueChangedAction {
+declare class Validator<T = any> extends ValueChangedAction {
     private readonly source;
     /**
      * Creates a new validator
@@ -1349,8 +1654,19 @@ export declare class Validator<T = any> extends ValueChangedAction {
      * 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.
+     *
+     * A run in flight over the field is cancelled once the removal stands, and not before: a transaction that
+     * unwinds puts the validator and its epoch back, and the run it never cancelled goes on to reach the verdict the
+     * field is then owed. Cancelling it as the removal is made would leave the field reporting itself valid over a
+     * value nothing checked, on the strength of a transaction that never happened.
      */
     unregisterFrom(field: FieldBase): void;
+    /**
+     * Cancels the asynchronous run in flight over `field`, where there is one. It is called once the field has
+     * stopped holding this validator: the field's validation epoch has moved on by then, so the run's verdict is
+     * already dropped and the signal it handed its check aborts with it.
+     */
+    protected abandonRun(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
@@ -1368,8 +1684,10 @@ export declare class Validator<T = any> extends ValueChangedAction {
 }
 
 /** What a validator remembers about one field it is registered on; a subclass widens it. */
-export declare interface ValidatorBindingState {
+declare interface ValidatorBindingState {
     run: number;
+    /** cancels the asynchronous run in flight over the field, absent while no run is waiting for its verdict */
+    abandon?: () => void;
 }
 
 export declare namespace Validators {
@@ -1377,7 +1695,9 @@ export declare namespace Validators {
         CompareTo,
         CompareToTarget,
         InAllowedValues,
+        AllowedValues,
         Required_2 as Required,
+        RequiredOptions,
         Pattern,
         ValidationFunctionResult,
         ValidationFunction,