@dynamicforms/vue-forms 0.13.0 → 0.16.1

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 {
@@ -241,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
  */
@@ -252,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;
 }
 
@@ -316,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;
@@ -337,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 */
@@ -355,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;
@@ -412,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>;
@@ -569,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;
     /**
@@ -608,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
@@ -637,6 +710,25 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      * different list whatever the items compare as - so the commit announces it without composing a comparison.
      */
     protected propagateValueChanged(force?: boolean): void;
+    /**
+     * The last step of a construction: it runs inside the transaction the construction is, with the parameters
+     * applied and the value in place, before the element records what it was built as.
+     *
+     * A subclass overrides it to complete what the element was built with. What it writes here is part of the
+     * construction rather than a change of it: the element announces no ValueChangedAction, and what the hook
+     * leaves is what its eager actions and its validators run over, once. An element whose parameters named no
+     * `originalValue` is baselined on the value the hook left and so starts unchanged; one that named a baseline is
+     * measured against it, as any element is. A `Field` writes
+     * `_value`, which reaches the slot on an element built `enabled: false` as well - the value setter, which a
+     * disabled field refuses, states a change, and this is not one.
+     *
+     * A container completes itself through its members, and a member carries a construction of its own: the write
+     * reaches it as any later one would, so the member announces it and reports itself changed. A member that is to
+     * start unchanged is baselined here as well - `this.fields.x.originalValue = this.fields.x.value`.
+     *
+     * `params` is the parameter object the constructor received, where it received one.
+     */
+    protected constructed(params?: object): void;
     /**
      * Re-reads the value that the next ValueChangedAction will report as the one it replaces. A leaf records what
      * it announced at every announcement, so its copy is always current and there is nothing to re-read; a
@@ -701,6 +793,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
@@ -789,6 +887,7 @@ export declare type FieldsToValues<T extends GenericFieldsInterface> = {
 declare namespace Form {
     export {
         DisplayMode,
+        defaultDisplayMode,
         transaction,
         TransactionControl,
         FieldActionBase,
@@ -815,7 +914,6 @@ declare namespace Form {
         MessagesWidget,
         Field,
         NullableField,
-        EmptyField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
         IFieldParams,
@@ -848,11 +946,7 @@ declare namespace Form {
         ValidationError,
         ValidationErrorText,
         ValidationErrorRenderContent,
-        RenderableValue,
-        ValidationFunctionResult,
-        ValidationFunction,
-        ValidatorBindingState,
-        Validator
+        RenderableValue
     }
 }
 export default Form;
@@ -878,6 +972,7 @@ export declare type GenericFieldsInterface = Record<string, FieldBase>;
 export declare function getConfig(): FormsConfig;
 
 export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<GroupValue<T>, X> {
+    get [Symbol.toStringTag](): string;
     protected get state(): GroupSlots<GroupValue<T>>;
     protected get raw(): GroupSlots<GroupValue<T>>;
     private readonly _fields;
@@ -970,6 +1065,13 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     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
@@ -998,12 +1100,12 @@ export declare type GroupValue<T extends GenericFieldsInterface> = Partial<Field
 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[];
@@ -1058,6 +1160,7 @@ declare class LengthInRange extends Validator {
 }
 
 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?;
@@ -1300,7 +1403,14 @@ export declare class Statement {
      * 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. */
+    /**
+     * `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:
@@ -1483,6 +1593,17 @@ export declare class ValidationError {
      * 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;
@@ -1523,15 +1644,15 @@ export declare class ValidationErrorText extends ValidationError {
  * 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>;
+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
@@ -1582,7 +1703,7 @@ 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;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.13.0",
+  "version": "0.16.1",
   "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",
+  "author": "Jure Erzno\u017enik",
   "files": [
     "dist/*"
   ],
@@ -61,23 +61,35 @@
     "vue": "^3.5.2"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/lodash-es": "^4.17.12",
     "@types/markdown-it-attrs": "^4.1.3",
-    "@types/node": "^24.5.2",
+    "@types/node": "^26.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "@vitejs/plugin-vue": "^6",
     "@vitest/coverage-v8": "^3",
     "@vue/test-utils": "^2.2.4",
     "@vue/tsconfig": "^0.7.0",
     "baseline-browser-mapping": "^2.8.31",
-    "eslint-config-velis": "^2.0.11",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-config-velis": "^3.0.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "eslint-plugin-vue": "^10.10.0",
     "jsdom": "^26.0.0",
     "markdown-it-attrs": "^4.3.1",
+    "prettier": "^3.9.6",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5",
     "vite": "^7",
     "vite-plugin-dts": "^4",
     "vite-plugin-eslint": "^1.8.1",
     "vitest": "^3",
+    "vue-eslint-parser": "^10.4.1",
     "vue-markdown-render": "^2.3.0",
     "vue-tsc": "^2"
   }

package/readme.md

@@ -38,6 +38,8 @@ mechanism applies at every level of a nested form.
 - **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
+- **Extended properties**: a field carries whatever your UI renders it with — a label, a hint, a width — declared
+  as a second type argument, checked by the compiler and read through `extra`
 - **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