@dynamicforms/vue-forms 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -110,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
@@ -269,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 */
@@ -284,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 */
@@ -499,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
@@ -670,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
@@ -725,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'];
 };
@@ -768,6 +825,7 @@ declare namespace Form {
         FieldBase,
         GenericFieldsInterface,
         FieldsToValues,
+        FieldsToFullValues,
         GroupValue,
         GroupValueInput,
         Group,
@@ -803,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>;
@@ -841,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.
@@ -856,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>;
     /**
@@ -865,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;
@@ -887,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.
  */
@@ -915,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;
@@ -927,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);
 }
 
@@ -949,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.
@@ -974,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;
@@ -1001,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);
 }
 
@@ -1025,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);
 }
 
@@ -1073,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);
 }
 
@@ -1102,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
  */
@@ -1119,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:
@@ -1145,6 +1327,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 +1361,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 +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;
@@ -1299,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;
@@ -1314,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;
 
@@ -1349,8 +1552,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
@@ -1370,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 {
@@ -1377,7 +1593,9 @@ export declare namespace Validators {
         CompareTo,
         CompareToTarget,
         InAllowedValues,
+        AllowedValues,
         Required_2 as Required,
+        RequiredOptions,
         Pattern,
         ValidationFunctionResult,
         ValidationFunction,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "A lightweight Vue.js library for form state management with built-in validation, conditional logic, nested structures, and a rich event system. UI-agnostic and TypeScript-first.",
   "author": "Jure Erznožnik",

package/readme.md

@@ -22,19 +22,25 @@ mechanism applies at every level of a nested form.
 
 ## Features
 
-- **UI-agnostic**: Works with any Vue UI components or your custom ones
+- **UI-agnostic**: a logic layer for form state, validation and dynamic behaviour. Any Vue components render it,
+  your own included
+- **Transactional**: every mutating operation is atomic — events are announced once, over the net change, and a
+  handler that throws leaves the form exactly as it was. `transaction()` makes several writes one operation, and
+  `tx.rollback()` withdraws one without an error
+- **Lists that scale**: a `List` is meant to hold thousands of rows. Writing one field of one row costs that row
+  and the depth it sits at, a `push()` costs one row, and reading `value` or `valid` again costs nothing
+- **Declared once, bound per record**: the `Group` handed to `new List(template)` is the declaration every row is
+  built from. One validator instance and one conditional rule serve every row, and each row answers for itself
 - **Reactive**: every member of a field, group or list is a tracked read — assign a property directly, with no
   `ref` to unwrap and no computed mirror to keep in sync
-- **Nested structures**: Support for complex data with nested fields and groups
-- **Event system**: Rich event handling for field changes, validation, and more
-- **Transactional**: every mutating operation is atomic — events are announced once, over the net change, and a
-  handler that throws leaves the form exactly as it was
-- **TypeScript support**: Full type definitions for excellent developer experience
+- **Nested structures**: fields, groups and lists compose recursively, at every level
+- **Event system**: every change travels through an action pipeline; a handler may pass it on, reshape it or stop it
+- **Validation**: built-in validators, custom synchronous and asynchronous rules, cross-field comparisons, and
+  errors that carry a `code` and render as text, markdown or a component of your own
+- **Conditional logic**: visibility, enablement and values declared as statements over other fields
+- **Display modes**: control field visibility with different display modes (Full, Hidden, Invisible, Suppress)
+- **TypeScript support**: full type definitions, and a group's value type inferred from the fields it holds
 - **Lightweight**: `vue` (^3.5.2) is the only peer dependency and `lodash-es` the only runtime one
-- **Field types**: Core field types (Field, Action, Group, List) to represent any data structure
-- **Validation**: Comprehensive validation system with built-in validators and extensible error handling
-- **Conditional logic**: Dynamic form behavior based on field values and conditions
-- **Display modes**: Control field visibility with different display modes (Full, Hidden, Invisible, Suppress)
 
 ## Installation
 
@@ -63,6 +69,10 @@ The import must be a named one — the default export is a namespace of the libr
 (`MdString`). Rendering those requires a globally registered `vue-markdown` component; set the option to `false` if you
 want plain text instead.
 
+The configuration is module-global rather than per app, and `getConfig()`, `setConfig()` and the `FormsConfig` type
+are exported beside the plugin, so the options can be read and written where there is no app to install a plugin
+on.
+
 ## Basic Usage Example
 
 Every form element is created with the constructor: `new Field({ ... })`, `new Action({ ... })`,
@@ -211,13 +221,22 @@ const validatedForm = new Group({
 ```
 
 Validators run eagerly — a field is validated the moment it is created, so a form built from empty required fields is
-invalid immediately. Use `field.touched` to decide when to show the errors in the UI.
-
-A validation function may return a `Promise`. `field.validating` is `true` while such a run is pending, and the
-verdict applied to the field is always the one belonging to the newest run, so a slow check cannot overwrite a faster
-one started after it. A validator message given as a `Ref` or `computed` is resolved when the message is rendered, so
-a translated message follows a locale switch without revalidating. `field.clearValidators()` drops the validators,
-empties the errors and cancels whatever validation is still in flight.
+invalid immediately. Use `field.touched` to decide when to show the errors in the UI. `Required` trims a string
+before it measures it, so a value of spaces alone is no value; `new Validators.Required({ trim: false })` keeps the
+spaces where they are part of what the field holds.
+
+Every error a built-in validator produces carries a `code` — `required`, `pattern`, `min-length`, … — so a program
+reacting to one particular failure need not match message text that is translated and configurable.
+
+A validation function may return a `Promise`. `field.validating` is `true` while such a run is pending — on the
+field and on every container above it, so a form answers for the whole tree — and the verdict applied to the field
+is always the one belonging to the newest run, so a slow check cannot overwrite a faster one started after it. The
+function receives an `AbortSignal` as its fourth argument, which aborts the moment the run's verdict stops
+counting, so the request behind it can be called off. `form.busy` is the same question with the `Action.execute()`
+runs below it included — what a submit button binds to. A validator message given as a `Ref` or `computed` is
+resolved when the message is rendered, so a translated message follows a locale switch without revalidating.
+`field.clearValidators()` drops the validators, empties the errors and cancels whatever validation is still in
+flight.
 
 ## Messages Widget Component
 
@@ -326,7 +345,8 @@ const contactsList = new List(contactTemplate);
 contactsList.push({ name: 'John Doe', email: 'john@example.com', phone: '123-456-7890' });
 contactsList.push({ name: 'Jane Doe', email: 'jane@example.com', phone: '987-654-3210' });
 
-// Access list items: get() returns undefined for an invalid index
+// Access list items: items hands out the rows, get() answers undefined for an invalid index
+console.log(contactsList.length);            // 2
 const firstContact = contactsList.get(0)!;
 console.log(firstContact.fields.name.value); // 'John Doe'
 
@@ -337,8 +357,9 @@ firstContact.fields.email.value = 'john.doe@example.com';
 contactsList.remove(1);
 ```
 
-Every list mutation is tracked, so a `v-for` over `contactsList.value` re-renders on `push()`, `insert()`,
-`remove()`, `pop()` and `clear()` without any extra wiring.
+Every list mutation is tracked, so a `v-for` over `contactsList.items` re-renders on `push()`, `insert()`,
+`remove()`, `pop()` and `clear()` without any extra wiring. `items` hands out a frozen array of the live rows,
+rebuilt once per change of the set.
 
 ## TypeScript Support
 
@@ -388,10 +409,11 @@ const email: string = userForm.fields.email.value;
 const age: number = userForm.fields.age.value;
 const darkMode: boolean = userForm.fields.preferences.fields.darkMode.value;
 
-// The serialized value is typed too, member by member
+// The serialized value is typed too, member by member. Every member is optional, because a disabled field is
+// left out of the object the group builds
 const values = userForm.value!;
-const emailFromValue: string = values.email;
-const prefs: { darkMode: boolean; notifications: boolean } | null = values.preferences;
+const emailFromValue: string | undefined = values.email;
+const prefs: { darkMode?: boolean; notifications?: boolean } | null | undefined = values.preferences;
 
 // Type safety prevents errors
 // userForm.fields.age.value = 'not a number'; // Error: Type 'string' is not assignable to type 'number'
@@ -443,8 +465,8 @@ For more detailed documentation and examples, check out the [documentation](http
 declarations, transactions, where validity comes from and how a `List` builds its rows.
 
 Upgrading an existing project? The
-[migration guide](https://docs.velis.si/dynamicforms/vue-forms/guide/migration) walks the journey from 0.6.1 to
-0.10.x, silent breaks first, and keeps a section per release for a project crossing one.
+[migration guide](https://docs.velis.si/dynamicforms/vue-forms/guide/migration) walks the journey from 0.6.1
+onwards, silent breaks first, and keeps a section per release for a project crossing one.
 
 ## Conclusion