@dynamicforms/vue-forms 0.6.0 → 0.6.1

package/dist/index.d.cts

@@ -178,14 +178,46 @@ export declare abstract class FieldBase<T = any> {
     private _enabled;
     get enabled(): boolean;
     set enabled(newValue: boolean);
+    /**
+     * While true, validate() on this field does nothing at all: it neither recomputes _valid nor emits
+     * ValidChangedAction, and nothing climbs to the parent. A container that walks its members one by one - assigning
+     * them a value, or revalidating them - sets it for the duration of the walk, so a member's upward climb cannot
+     * announce the verdict of a half-applied value or of a half-revalidated set, and clears it in a finally block
+     * followed by its own validate(). That call recomputes over the finished state and emits the net transition, so
+     * the deferral cannot swallow a real change.
+     */
+    protected suppressValidation: boolean;
+    /**
+     * While true, a validity change is still recomputed and still announced on this field, but it is not passed up to
+     * the parent: the climb is only remembered and carried out by flushParentValidityClimb(). A setter that notifies
+     * the parent of the new value itself holds it over the notifying region, so the parent forms its verdict once,
+     * over the finished value, instead of once over the value being replaced and once over the value replacing it.
+     */
+    protected suppressParentValidityClimb: boolean;
+    private parentValidityClimbPending;
+    /** Carries out the climb that a validity change made while suppressParentValidityClimb was held, if there was one. */
+    protected flushParentValidityClimb(): void;
     validate(revalidate?: boolean): void;
     get valid(): boolean;
     get fullValue(): any;
     get isChanged(): boolean;
+    /**
+     * Registers the actions a constructor received in its parameters: registration without the eager trigger,
+     * because a constructor ends with a single this.actions.triggerEager(...) over the finished value, and an
+     * eager action registered here would otherwise also run once per registration, over a half-built field.
+     */
+    protected registerInitialActions(actions: FieldActionBase[]): void;
     registerAction(action: FieldActionBase): this;
     triggerAction<T2 extends FieldActionBase>(actionClass: (abstract new (...args: any[]) => T2) & {
         classIdentifier: symbol;
     }, ...params: any[]): any;
+    private _validationEpoch;
+    /**
+     * Generation counter of the validators attached to this field. A Validator reads it when a run starts and drops
+     * a result whose epoch no longer matches, so a validation still in flight when clearValidators() is called
+     * cannot push an error onto a field that no longer has the validator that produced it.
+     */
+    get validationEpoch(): number;
     clearValidators(): void;
 }
 
@@ -279,6 +311,14 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     field<K extends keyof T>(fieldName: K): T[K] | null;
     get fields(): T;
     get value(): GroupValue<T>;
+    /**
+     * Writes the members that the given value carries, without letting any single member announce the state in
+     * between: the group's own value notification and its own validation are both held back for the duration, so
+     * neither a ValueChangedAction nor a ValidChangedAction reports a verdict over a half-applied value. The
+     * caller decides what to announce once the whole value is in place. Both flags are restored to what they were,
+     * so a caller that is itself holding the group back stays in charge.
+     */
+    private assignMembers;
     set value(newValue: GroupValueInput<T>);
     get touched(): boolean;
     set touched(touched: boolean);
@@ -339,6 +379,11 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
     private _previousValue;
     constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams<ListValue>>);
     private processSetValueItem;
+    /**
+     * Builds the item that fills a gap left by an insert beyond the end of the list: a copy of the item template with
+     * the template's own values, or an empty group when the list has no template.
+     */
+    private createPaddingItem;
     private setValueInternal;
     get value(): ListValue;
     set value(newValue: Record<string, any>[]);
@@ -543,11 +588,26 @@ export declare type ValidationFunctionResult = ValidationError[] | null;
  */
 export declare class Validator<T = any> extends ValueChangedAction {
     private readonly source;
+    /**
+     * Sequence number of the newest run of this validator, per field. Every execution takes the next number, and a
+     * result is applied only while its number is still the newest one, so a slow run cannot overwrite the verdict of
+     * a faster one that started after it. The key is the field because one validator instance may be registered on
+     * several fields, each with a sequence of its own.
+     */
+    private readonly runs;
     /**
      * Creates a new validator
      * @param validationFn Function that validates the field value and returns errors or null
      */
     constructor(validationFn: ValidationFunction<T>);
+    /**
+     * Returns the error instance this validator owns and may later withdraw: the argument itself when it carries no
+     * ownership stamp or already carries this validator's, a copy of it when it belongs to another validator. The
+     * stamp is not configurable, so an instance one validator owns can never be reassigned to another; the copy is
+     * what makes an error instance shareable between validators, and it keeps the prototype and every own property,
+     * including the non-enumerable ones, so it renders exactly like the instance it was made from.
+     */
+    private claim;
     static get classIdentifier(): symbol;
     get eager(): boolean;
     protected replacePlaceholdersFunction(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;

package/dist/index.d.ts

@@ -178,14 +178,46 @@ export declare abstract class FieldBase<T = any> {
     private _enabled;
     get enabled(): boolean;
     set enabled(newValue: boolean);
+    /**
+     * While true, validate() on this field does nothing at all: it neither recomputes _valid nor emits
+     * ValidChangedAction, and nothing climbs to the parent. A container that walks its members one by one - assigning
+     * them a value, or revalidating them - sets it for the duration of the walk, so a member's upward climb cannot
+     * announce the verdict of a half-applied value or of a half-revalidated set, and clears it in a finally block
+     * followed by its own validate(). That call recomputes over the finished state and emits the net transition, so
+     * the deferral cannot swallow a real change.
+     */
+    protected suppressValidation: boolean;
+    /**
+     * While true, a validity change is still recomputed and still announced on this field, but it is not passed up to
+     * the parent: the climb is only remembered and carried out by flushParentValidityClimb(). A setter that notifies
+     * the parent of the new value itself holds it over the notifying region, so the parent forms its verdict once,
+     * over the finished value, instead of once over the value being replaced and once over the value replacing it.
+     */
+    protected suppressParentValidityClimb: boolean;
+    private parentValidityClimbPending;
+    /** Carries out the climb that a validity change made while suppressParentValidityClimb was held, if there was one. */
+    protected flushParentValidityClimb(): void;
     validate(revalidate?: boolean): void;
     get valid(): boolean;
     get fullValue(): any;
     get isChanged(): boolean;
+    /**
+     * Registers the actions a constructor received in its parameters: registration without the eager trigger,
+     * because a constructor ends with a single this.actions.triggerEager(...) over the finished value, and an
+     * eager action registered here would otherwise also run once per registration, over a half-built field.
+     */
+    protected registerInitialActions(actions: FieldActionBase[]): void;
     registerAction(action: FieldActionBase): this;
     triggerAction<T2 extends FieldActionBase>(actionClass: (abstract new (...args: any[]) => T2) & {
         classIdentifier: symbol;
     }, ...params: any[]): any;
+    private _validationEpoch;
+    /**
+     * Generation counter of the validators attached to this field. A Validator reads it when a run starts and drops
+     * a result whose epoch no longer matches, so a validation still in flight when clearValidators() is called
+     * cannot push an error onto a field that no longer has the validator that produced it.
+     */
+    get validationEpoch(): number;
     clearValidators(): void;
 }
 
@@ -279,6 +311,14 @@ export declare class Group<T extends GenericFieldsInterface = GenericFieldsInter
     field<K extends keyof T>(fieldName: K): T[K] | null;
     get fields(): T;
     get value(): GroupValue<T>;
+    /**
+     * Writes the members that the given value carries, without letting any single member announce the state in
+     * between: the group's own value notification and its own validation are both held back for the duration, so
+     * neither a ValueChangedAction nor a ValidChangedAction reports a verdict over a half-applied value. The
+     * caller decides what to announce once the whole value is in place. Both flags are restored to what they were,
+     * so a caller that is itself holding the group back stays in charge.
+     */
+    private assignMembers;
     set value(newValue: GroupValueInput<T>);
     get touched(): boolean;
     set touched(touched: boolean);
@@ -339,6 +379,11 @@ export declare class List<T extends GenericFieldsInterface = GenericFieldsInterf
     private _previousValue;
     constructor(itemTemplate?: Group<T>, params?: Partial<IFieldConstructorParams<ListValue>>);
     private processSetValueItem;
+    /**
+     * Builds the item that fills a gap left by an insert beyond the end of the list: a copy of the item template with
+     * the template's own values, or an empty group when the list has no template.
+     */
+    private createPaddingItem;
     private setValueInternal;
     get value(): ListValue;
     set value(newValue: Record<string, any>[]);
@@ -543,11 +588,26 @@ export declare type ValidationFunctionResult = ValidationError[] | null;
  */
 export declare class Validator<T = any> extends ValueChangedAction {
     private readonly source;
+    /**
+     * Sequence number of the newest run of this validator, per field. Every execution takes the next number, and a
+     * result is applied only while its number is still the newest one, so a slow run cannot overwrite the verdict of
+     * a faster one that started after it. The key is the field because one validator instance may be registered on
+     * several fields, each with a sequence of its own.
+     */
+    private readonly runs;
     /**
      * Creates a new validator
      * @param validationFn Function that validates the field value and returns errors or null
      */
     constructor(validationFn: ValidationFunction<T>);
+    /**
+     * Returns the error instance this validator owns and may later withdraw: the argument itself when it carries no
+     * ownership stamp or already carries this validator's, a copy of it when it belongs to another validator. The
+     * stamp is not configurable, so an instance one validator owns can never be reassigned to another; the copy is
+     * what makes an error instance shareable between validators, and it keeps the prototype and every own property,
+     * including the non-enumerable ones, so it renders exactly like the instance it was made from.
+     */
+    private claim;
     static get classIdentifier(): symbol;
     get eager(): boolean;
     protected replacePlaceholdersFunction(text: RenderContentRef, replace: Record<string, any>): RenderContentRef;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.6.0",
+  "version": "0.6.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",
@@ -29,6 +29,7 @@
   ],
   "scripts": {
     "build": "vite build && node -e \"require('fs').copyFileSync('dist/index.d.ts', 'dist/index.d.cts')\"",
+    "prepack": "npm run build",
     "test": "vitest run --coverage",
     "lint": "eslint src --fix && vue-tsc --noEmit",
     "lint:ci": "eslint src && vue-tsc --noEmit",
@@ -52,13 +53,19 @@
   "homepage": "https://docs.velis.si/dynamicforms/vue-forms",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velis74/dynamicforms-vue-forms.git"
+    "url": "git+https://github.com/dynamicforms/vue-forms.git"
   },
   "bugs": {
-    "url": "https://github.com/velis74/dynamicforms-vue-forms/issues"
+    "url": "https://github.com/dynamicforms/vue-forms/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "lodash-es": "^4.17.21"
   },
   "peerDependencies": {
-    "lodash-es": "^4.17.12",
     "vue": "^3.4"
   },
   "devDependencies": {

package/readme.md

@@ -18,7 +18,7 @@ mechanism applies at every level of a nested form.
 - **Fields that react to each other**: Conditional visibility, enablement and values are declared as statements over other fields, and an action pipeline lets a handler intercept, transform or abort an event.
 - **Reactive & Type-Safe**: Fields, groups and lists are Vue reactive objects, and a group's value type is inferred from the fields it holds, nested structures included.
 - **Structural serialization**: A group's value is the shape of its fields, and `Group.createFromFormData()` turns a plain object back into a form.
-- **Lightweight**: Depends on Vue and lodash-es, and nothing else.
+- **Lightweight**: `vue` (^3.4) is the only peer dependency, and `lodash` and `lodash-es` — one per build — the only runtime ones.
 
 ## Features
 
@@ -28,7 +28,8 @@ mechanism applies at every level of a nested form.
 - **Nested structures**: Support for complex data with nested fields and groups
 - **Event system**: Rich event handling for field changes, validation, and more
 - **TypeScript support**: Full type definitions for excellent developer experience
-- **Lightweight**: depends only on `vue` (^3.4) and `lodash-es` (^4.17)
+- **Lightweight**: `vue` (^3.4) is the only peer dependency; the runtime dependencies are `lodash` and `lodash-es`,
+  one for each of the two builds
 - **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
@@ -40,6 +41,11 @@ mechanism applies at every level of a nested form.
 npm install @dynamicforms/vue-forms
 ```
 
+The package ships two builds of the same source: an ESM build that imports `lodash-es` and a CJS/UMD build that
+requires `lodash`. Both lodash packages are declared as dependencies and install with the package, so an `import` and
+a `require()` both resolve without further setup. Node 18 or newer is required, and `vue` (^3.4) is the only peer
+dependency. Type definitions ship for both entry points; the stylesheet is `@dynamicforms/vue-forms/style.css`.
+
 ## Setup
 
 The library ships a Vue plugin for its global options:
@@ -185,6 +191,12 @@ 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.
+
 ## Messages Widget Component
 
 The library includes a `messages-widget` Vue component for displaying validation errors and messages: