@dynamicforms/vue-forms 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -46,27 +46,44 @@ export declare class Action<T extends ActionValue = ActionValue, X extends objec
 
 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;
     /**
-     * True when triggering this action would run something: a handler registered under the identifier, or - on the
-     * value change identifier, which trigger() answers with an eager pass as well - any eager action at all. A
-     * caller that has to build the parameters before it can trigger asks this first and skips building them when
-     * there is nothing to receive them.
+     * 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;
-    /**
-     * Runs the chain registered under one identifier and nothing else. A caller that has already run the eager
-     * pass - a transaction runs it at the write, so that the validators have decided before it commits - reaches
-     * the handlers through here, so the eager actions are not run a second time at the announcement.
-     */
-    triggerChain(identifier: 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;
@@ -77,11 +94,15 @@ export declare class ActionsMap extends Map<symbol, FieldActionExecute> {
      */
     bindTo(owner: FieldBase): void;
     /**
-     * A copy of this map carrying everything but the validators. It only leaves them out: releasing what a
-     * validator installed elsewhere is the caller's to do, and only once the transaction that dropped them has
-     * committed, because a rollback puts this map back with its validators in it.
+     * 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.
      */
-    cloneWithoutValidators(): ActionsMap;
+    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 {
@@ -89,6 +110,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
@@ -175,6 +202,7 @@ export declare class ConditionalStatementAction extends ValueChangedAction {
     static get classIdentifier(): symbol;
     get eager(): boolean;
     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.
@@ -247,8 +275,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 */
@@ -262,6 +290,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 */
@@ -357,8 +387,10 @@ export declare abstract class FieldActionBase {
      */
     boundToBinding(binding: FieldBase): void;
     /**
-     * Announces that `binding` no longer holds this action. It names one element rather than the action as a whole,
-     * because the instance goes on serving every other element it was registered on.
+     * 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;
 }
@@ -475,16 +507,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
@@ -646,7 +718,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
@@ -664,6 +736,25 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      */
     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;
@@ -682,6 +773,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'];
 };
@@ -725,6 +825,7 @@ declare namespace Form {
         FieldBase,
         GenericFieldsInterface,
         FieldsToValues,
+        FieldsToFullValues,
         GroupValue,
         GroupValueInput,
         Group,
@@ -760,26 +861,79 @@ 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>>;
+    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>;
@@ -798,7 +952,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.
@@ -813,6 +967,8 @@ 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;
     bind(data?: GroupValueInput<T>, overrides?: IBindParams<GroupValueInput<T>, X>): Group<T, X>;
     /**
@@ -822,8 +978,21 @@ 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;
@@ -844,7 +1013,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.
  */
@@ -872,7 +1041,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;
@@ -884,7 +1053,7 @@ 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);
 }
 
@@ -906,9 +1075,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.
@@ -931,8 +1104,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;
@@ -958,12 +1154,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);
 }
 
@@ -982,7 +1186,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);
 }
 
@@ -1030,7 +1234,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);
 }
 
@@ -1059,10 +1263,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
  */
@@ -1076,6 +1293,14 @@ 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;
+    /** @throws TypeError where an operand the statement reads is undefined or a function. */
     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:
@@ -1100,10 +1325,10 @@ export declare class Statement {
 
 declare class Transaction {
     private readonly participants;
-    /** work that stands only where the transaction commits; a rollback simply never does it */
-    private readonly deferred;
     /** 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 */
@@ -1130,18 +1355,18 @@ declare class Transaction {
     recordStructural(element: FieldBase, event: TxStructuralEvent): void;
     /** True where the commit still owes this element a value announcement. */
     willAnnounceValue(element: FieldBase): boolean;
-    /**
-     * Registers work the commit does once everything has been announced. It is for what a rollback could not take
-     * back: releasing a listener, dropping a registration. Held until the commit, it is simply never done where the
-     * transaction unwinds instead.
-     */
-    whenCommitted(work: () => void): void;
     /**
      * 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;
+    /**
+     * 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
@@ -1251,6 +1476,13 @@ 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);
     get componentName(): string;
     get componentBindings(): {};
     get componentBody(): string;
@@ -1264,7 +1496,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;
@@ -1279,13 +1511,19 @@ 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.
+ */
+export declare type ValidationFunction<T = any> = (newValue: T, oldValue: T, field: FieldBase<T>, signal: AbortSignal) => ValidationFunctionResult | Promise<ValidationFunctionResult>;
 
 export declare type ValidationFunctionResult = ValidationError[] | null;
 
@@ -1310,6 +1548,23 @@ 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.
+     *
+     * 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
@@ -1329,6 +1584,8 @@ 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 {
     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 {
@@ -1336,7 +1593,9 @@ export declare namespace Validators {
         CompareTo,
         CompareToTarget,
         InAllowedValues,
+        AllowedValues,
         Required_2 as Required,
+        RequiredOptions,
         Pattern,
         ValidationFunctionResult,
         ValidationFunction,