ngx-vest-forms 2.3.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-vest-forms",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "license": "MIT",
   "author": "Brecht Billiet, Arjen Althoff",
   "description": "Opinionated template-driven forms library for Angular with Vest.js integration",

package/types/ngx-vest-forms.d.ts

@@ -191,8 +191,10 @@ declare class FormErrorDisplayDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormErrorDisplayDirective, "[formErrorDisplay], [ngxErrorDisplay]", ["formErrorDisplay", "ngxErrorDisplay"], { "errorDisplayMode": { "alias": "errorDisplayMode"; "required": false; "isSignal": true; }; "warningDisplayMode": { "alias": "warningDisplayMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof FormControlStateDirective; inputs: {}; outputs: {}; }]>;
 }
 
+type AriaAssociationMode = 'all-controls' | 'single-control' | 'none';
+
 /**
- * Accessible form control wrapper with WCAG 2.2 AA compliance.
+ * Accessible form control wrapper built with WCAG 2.2 AA considerations.
  *
  * Wrap form fields to automatically display validation errors, warnings, and pending states
  * with proper accessibility attributes.
@@ -283,7 +285,7 @@ declare class FormErrorDisplayDirective {
  *   <ngx-control-wrapper>
  *     <input name="username" ngModel />
  *   </ngx-control-wrapper>
- *   /// If async validation is running for >200ms, a spinner and 'Validating…' will be shown.
+ *   /// If async validation is running for >500ms, a spinner and 'Validating…' will be shown.
  *   /// Once shown, the validation message stays visible for minimum 500ms to prevent flashing.
  *   /// If Vest warnings are present, they will be shown below errors.
  *
@@ -292,13 +294,14 @@ declare class FormErrorDisplayDirective {
  *   import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
  *   @Component({
  *     providers: [
- *       provide(NGX_ERROR_DISPLAY_MODE_TOKEN, { useValue: 'submit' })
+ *       provide(NGX_ERROR_DISPLAY_MODE_TOKEN, { useValue: 'on-submit' })
  *     ]
  *   })
  *   export class MyComponent {}
  *
  * Best Practices:
- *   - Use for every input or group in your forms.
+ *   - Use for single-control wrappers.
+ *   - For multi-control/group containers, prefer `ngx-form-group-wrapper`.
  *   - Do not manually display errors for individual fields; rely on this wrapper.
  *   - Validate with tools like Accessibility Insights and real screen reader testing.
  *
@@ -323,7 +326,7 @@ declare class ControlWrapperComponent implements AfterContentInit, OnDestroy {
      *   across multiple child controls.
      * - This does not affect whether messages render; it only affects ARIA wiring.
      */
-    readonly ariaAssociationMode: _angular_core.InputSignal<"all-controls" | "single-control" | "none">;
+    readonly ariaAssociationMode: _angular_core.InputSignal<AriaAssociationMode>;
     protected readonly uniqueId: string;
     protected readonly errorId: string;
     protected readonly warningId: string;
@@ -357,7 +360,6 @@ declare class ControlWrapperComponent implements AfterContentInit, OnDestroy {
      * hint/help text associations.
      */
     private readonly wrapperOwnedDescribedByIds;
-    private mergeAriaDescribedBy;
     constructor();
     ngAfterContentInit(): void;
     ngOnDestroy(): void;
@@ -400,7 +402,7 @@ declare class FormGroupWrapperComponent {
      */
     readonly describedByIds: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormGroupWrapperComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FormGroupWrapperComponent, "ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper], [ngx-form-group-wrapper], [sc-form-group-wrapper]", ["formGroupWrapper", "ngxFormGroupWrapper"], { "pendingDebounce": { "alias": "pendingDebounce"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; }; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FormGroupWrapperComponent, "ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper]", ["ngxFormGroupWrapper"], { "pendingDebounce": { "alias": "pendingDebounce"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; "warningDisplayMode": "warningDisplayMode"; }; outputs: {}; }]>;
 }
 
 /**
@@ -422,7 +424,7 @@ declare class FormErrorControlDirective implements AfterContentInit, OnDestroy {
      * - `single-control`: apply ARIA attributes only when exactly one control is found.
      * - `none`: do not mutate descendant controls.
      */
-    readonly ariaAssociationMode: _angular_core.InputSignal<"all-controls" | "single-control" | "none">;
+    readonly ariaAssociationMode: _angular_core.InputSignal<AriaAssociationMode>;
     /**
      * Unique ID prefix for this instance.
      * Use these IDs to render message regions and to support aria-describedby.
@@ -441,13 +443,12 @@ declare class FormErrorControlDirective implements AfterContentInit, OnDestroy {
      */
     readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     private readonly ownedDescribedByIds;
-    private mergeAriaDescribedBy;
     constructor();
     ngAfterContentInit(): void;
     ngOnDestroy(): void;
     private updateFormControls;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormErrorControlDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormErrorControlDirective, "[formErrorControl], [ngxErrorControl]", ["formErrorControl", "ngxErrorControl"], { "ariaAssociationMode": { "alias": "ariaAssociationMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormErrorControlDirective, "[formErrorControl], [ngxErrorControl]", ["formErrorControl", "ngxErrorControl"], { "ariaAssociationMode": { "alias": "ariaAssociationMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; "warningDisplayMode": "warningDisplayMode"; }; outputs: {}; }]>;
 }
 
 /**
@@ -461,22 +462,37 @@ type ValidationOptions = {
 };
 
 /**
- * Hooks into the ngModelGroup selector and triggers an asynchronous validation for a form group
- * It will use a vest suite behind the scenes
+ * Hooks into `ngModelGroup`/`ngxModelGroup` and runs async group-level validation
+ * through the parent `FormDirective` Vest suite bridge.
  */
 declare class FormModelGroupDirective implements AsyncValidator {
+    /**
+     * Per-group async validation options.
+     *
+     * Defaults to no debounce (`{ debounceTime: 0 }`).
+     */
     validationOptions: _angular_core.InputSignal<ValidationOptions>;
     private readonly formDirective;
+    /**
+     * Runs async validation for the current model-group control.
+     *
+     * Returns `null` (fail-open) when used outside an `ngxVestForm` context.
+     */
     validate(control: AbstractControl): Observable<ValidationErrors | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormModelGroupDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormModelGroupDirective, "[ngModelGroup],[ngxModelGroup]", never, { "validationOptions": { "alias": "validationOptions"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * Hooks into the ngModel selector and triggers an asynchronous validation for a form model
- * It will use a vest suite behind the scenes
+ * Hooks into `ngModel`/`ngxModel` and runs async field-level validation
+ * through the parent `FormDirective` Vest suite bridge.
  */
 declare class FormModelDirective implements AsyncValidator {
+    /**
+     * Per-control async validation options.
+     *
+     * Defaults to no debounce (`{ debounceTime: 0 }`).
+     */
     validationOptions: _angular_core.InputSignal<ValidationOptions>;
     /**
      * Reference to the form that needs to be validated
@@ -484,6 +500,11 @@ declare class FormModelDirective implements AsyncValidator {
      * does not crash the application. In that case, validation becomes a no-op.
      */
     private readonly formDirective;
+    /**
+     * Runs field-level async validation for this control.
+     *
+     * Returns `null` (fail-open) when used outside an `ngxVestForm` context.
+     */
     validate(control: AbstractControl): Observable<ValidationErrors | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormModelDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormModelDirective, "[ngModel],[ngxModel]", never, { "validationOptions": { "alias": "validationOptions"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
@@ -883,6 +904,7 @@ type NgxFieldKey<T> = Extract<keyof T, string> | (string & {});
  * @see {@link https://vestjs.dev/docs/writing_your_suite | Vest Documentation}
  * @see {@link NgxFieldKey} For typed field name hints with arbitrary string support
  */
+/** @internal Do not use outside ngx-vest-forms. The `any` is architecturally required. */
 type NgxSuiteCallback<T> = {
     bivarianceHack(model: T, field?: any): void;
 }['bivarianceHack'];
@@ -924,6 +946,7 @@ type NgxVestSuite<T = unknown> = StaticSuite<string, string, NgxSuiteCallback<T>
  * @see {@link NgxVestSuite} For the base suite type (accepts any string field)
  * @see {@link FormFieldName} For the field name type with autocomplete
  */
+/** @internal Do not use outside ngx-vest-forms. */
 type NgxTypedSuiteCallback<T> = {
     bivarianceHack(model: T, field?: FormFieldName<T>): void;
 }['bivarianceHack'];
@@ -985,6 +1008,16 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * separately when they exist without errors.
      */
     readonly fieldWarnings: _angular_core.WritableSignal<Map<string, readonly string[]>>;
+    /**
+     * Computed signal that returns field paths for all touched (or submitted) leaf controls.
+     * Updates reactively when controls are touched (blur) or when form status changes.
+     *
+     * This enables consumers to determine which fields the user has interacted with,
+     * useful for filtering errors/warnings to match the form's visible validation state.
+     *
+     * @publicApi
+     */
+    readonly touchedFieldPaths: _angular_core.Signal<string[]>;
     /**
      * Computed signal for form state with validity and errors.
      * Used by templates and tests as vestForm.formState().valid/errors
@@ -1050,7 +1083,7 @@ declare class FormDirective<T extends Record<string, unknown>> {
      *
      * Cleanup is handled automatically by the directive when it's destroyed.
      */
-    readonly errorsChange: _angular_core.OutputRef<Record<string, any>>;
+    readonly errorsChange: _angular_core.OutputRef<Record<string, string[]>>;
     /**
      * Triggered as soon as the form becomes dirty
      *
@@ -1176,6 +1209,11 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * ```
      */
     markAllAsTouched(): void;
+    /**
+     * Host handler: called whenever any descendant field loses focus.
+     * Used to make touched-path tracking react immediately on blur/tab.
+     */
+    onFormFocusOut(): void;
     /**
      * Resets the form to a pristine, untouched state with optional new values.
      *
@@ -1229,15 +1267,15 @@ declare class FormDirective<T extends Record<string, unknown>> {
      */
     resetForm(value?: T | null): void;
     /**
-     * This will feed the formValueCache, debounce it till the next tick
-     * and create an asynchronous validator that runs a vest suite
-     * @param field
-     * @param validationOptions
-     * @returns an asynchronous validator function
-     */
-    /**
-     * V2 async validator pattern: uses timer() + switchMap for proper re-validation.
-     * Each invocation builds a fresh one-shot observable, ensuring progressive validation.
+     * Creates a one-shot async validator function for a specific field path.
+     *
+     * The returned validator:
+     * - snapshots the current form model,
+     * - injects the candidate control value at `field`,
+     * - runs the Vest suite with debouncing,
+     * - maps Vest errors/warnings into Angular `ValidationErrors | null`.
+     *
+     * Warnings are stored in `fieldWarnings` to keep warnings non-blocking when no errors exist.
      */
     createAsyncValidator(field: string, validationOptions: ValidationOptions): AsyncValidatorFn;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormDirective<any>, never>;
@@ -1601,7 +1639,7 @@ declare class ValidationConfigBuilder<T> {
      * /// Result: { password: ['confirmPassword', 'securityScore'] }
      * ```
      */
-    whenChanged<K extends FieldPath<T>>(trigger: K, revalidate: FieldPath<T> | Array<FieldPath<T>>): this;
+    whenChanged<K extends FieldPath<T>>(trigger: K, revalidate: FieldPath<T> | ReadonlyArray<FieldPath<T>>): this;
     /**
      * Add bidirectional dependency: when either field changes, revalidate the other.
      *
@@ -1710,7 +1748,7 @@ declare class ValidationConfigBuilder<T> {
      * builder.group(['street', 'city', 'state', 'zipCode']);
      * ```
      */
-    group<K extends FieldPath<T>>(fields: K[]): this;
+    group<K extends FieldPath<T>>(fields: readonly K[]): this;
     /**
      * Merge with an existing validation configuration.
      *
@@ -1858,12 +1896,15 @@ declare function createValidationConfig<T>(): ValidationConfigBuilder<T>;
  * Does not recurse into nested arrays or objects.
  * Uses reduce() for optimal single-pass conversion.
  */
-declare function arrayToObject<T>(array: T[]): Record<number, T>;
+type DeepArrayToObject<T> = T extends ReadonlyArray<infer U> ? Record<number, DeepArrayToObject<U>> : T extends object ? {
+    [K in keyof T]: DeepArrayToObject<T[K]>;
+} : T;
+declare function arrayToObject<T>(array: readonly T[]): Record<number, T>;
 /**
  * Recursively converts arrays to objects with numeric keys, including nested arrays in objects.
  * Useful for template-driven forms that require object structure for nested arrays.
  */
-declare function deepArrayToObject<T>(array: T[]): Record<number, unknown>;
+declare function deepArrayToObject<T>(array: readonly T[]): Record<number, DeepArrayToObject<T>>;
 /**
  * Converts selected numeric-keyed object properties back to arrays.
  * Only properties listed in keys will be converted; others remain untouched.
@@ -1874,7 +1915,7 @@ declare function deepArrayToObject<T>(array: T[]): Record<number, unknown>;
  * Note: Conversion is explicit (by key) but will cascade inside converted branches
  * so nested numeric objects representing arrays become real arrays recursively.
  */
-declare function objectToArray(object: unknown, keys: string[]): unknown;
+declare function objectToArray<const K extends readonly string[]>(object: unknown, keys: K): unknown;
 
 /**
  * Utility functions for managing form field state in dynamic forms.
@@ -1916,7 +1957,7 @@ declare function objectToArray(object: unknown, keys: string[]): unknown;
  * Uses `Object.entries()` for efficient field clearing without mutation.
  * Only processes fields that need to be cleared, preserving other field values.
  *
- * @template T - The form model type, must extend Record<string, any>
+ * @template T - The form model type, must extend Record<string, unknown>
  * @param currentState - The current form state object
  * @param conditions - Object mapping field names to boolean conditions (true = clear field)
  * @returns New state object with specified fields cleared (set to undefined)
@@ -1967,7 +2008,7 @@ declare function objectToArray(object: unknown, keys: string[]): unknown;
  * ```
  *
  */
-declare function clearFieldsWhen<T extends Record<string, unknown>>(currentState: T, conditions: Partial<Record<keyof T, boolean>>): T;
+declare function clearFieldsWhen<T extends Record<string, unknown>>(currentState: T, conditions: Readonly<Partial<Record<keyof T, boolean>>>): T;
 /**
  * Clears multiple fields from form state unconditionally.
  *
@@ -1980,7 +2021,7 @@ declare function clearFieldsWhen<T extends Record<string, unknown>>(currentState
  * **Note:** Unlike `clearFieldsWhen`, this function always clears the specified fields
  * regardless of conditions. Use this when you want unconditional field removal.
  *
- * @template T - The form model type, must extend Record<string, any>
+ * @template T - The form model type, must extend Record<string, unknown>
  * @param currentState - The current form state object
  * @param fieldsToClear - Array of field names to clear (set to undefined)
  * @returns New state object with specified fields cleared
@@ -2004,7 +2045,7 @@ declare function clearFieldsWhen<T extends Record<string, unknown>>(currentState
  * }
  * ```
  */
-declare function clearFields<T extends Record<string, unknown>>(currentState: T, fieldsToClear: Array<keyof T>): T;
+declare function clearFields<T extends Record<string, unknown>>(currentState: T, fieldsToClear: ReadonlyArray<keyof T>): T;
 /**
  * Creates a clean form state containing only fields that meet specified conditions.
  *
@@ -2019,7 +2060,7 @@ declare function clearFields<T extends Record<string, unknown>>(currentState: T,
  *
  * **Returns:** `Partial<T>` because the result may not contain all original fields.
  *
- * @template T - The form model type, must extend Record<string, any>
+ * @template T - The form model type, must extend Record<string, unknown>
  * @param currentState - The current form state object
  * @param conditions - Object mapping field names to boolean conditions (true = keep field)
  * @returns New state object containing only fields where condition is true
@@ -2054,26 +2095,8 @@ declare function clearFields<T extends Record<string, unknown>>(currentState: T,
  *
  * @since 1.0.0
  */
-declare function keepFieldsWhen<T extends Record<string, unknown>>(currentState: T, conditions: Partial<Record<keyof T, boolean>>): Partial<T>;
+declare function keepFieldsWhen<T extends Record<string, unknown>>(currentState: T, conditions: Readonly<Partial<Record<keyof T, boolean>>>): Partial<T>;
 
-/**
- * Utilities for working with field paths in dot/bracket notation and Standard Schema path arrays.
- *
- * These utilities help convert between:
- * - **Dot/bracket notation**: `'addresses[0].street'` (used in Angular forms and Vest)
- * - **Standard Schema paths**: `['addresses', 0, 'street']` (used in schema validation)
- *
- * @example
- * ```typescript
- * // Parse string path to array
- * parseFieldPath('user.addresses[0].street')
- * // Returns: ['user', 'addresses', 0, 'street']
- *
- * // Stringify array path to string
- * stringifyFieldPath(['user', 'addresses', 0, 'street'])
- * // Returns: 'user.addresses[0].street'
- * ```
- */
 /**
  * @internal
  * Internal utility for parsing field path strings.
@@ -2170,8 +2193,11 @@ declare function getFormGroupField(rootForm: FormGroup, control: AbstractControl
  * to include disabled field values in form submissions. Use Angular's `getRawValue()`
  * method on your form if you need to access disabled field values.
  *
- * This RxJS operator merges the value of the form with the raw value.
+ * This utility merges the value of the form with the raw value.
  * By doing this we can assure that we don't lose values of disabled form fields
+ *
+ * Security: Unsafe prototype-related keys (`__proto__`, `prototype`, `constructor`)
+ * are skipped during recursive merge.
  * @param form
  */
 declare function mergeValuesAndRawValues<T>(form: FormGroup): T;
@@ -2186,16 +2212,23 @@ declare function mergeValuesAndRawValues<T>(form: FormGroup): T;
  */
 declare function cloneDeep<T>(object: T): T;
 /**
- * Sets a value in an object in the correct path
- * @param obj
- * @param path
- * @param value
+ * Sets a value in an object at the provided field path.
+ *
+ * Supports dot and bracket notation via `parseFieldPath()`.
+ * Examples: `user.profile.name`, `addresses[0].street`.
+ *
+ * Security: If any path segment matches an unsafe prototype-related key
+ * (`__proto__`, `prototype`, `constructor`), the write is ignored.
+ *
+ * @param obj - Target object to mutate.
+ * @param path - Dot/bracket field path.
+ * @param value - Value to assign at the resolved path.
  */
-declare function setValueAtPath(obj: object, path: string, value: any): void;
+declare function setValueAtPath(obj: object, path: string, value: unknown): void;
 /**
  * @deprecated Use {@link setValueAtPath} instead
  */
-declare function set(obj: object, path: string, value: any): void;
+declare function set(obj: object, path: string, value: unknown): void;
 /**
  * @internal
  * Internal utility for collecting all form errors by field path.
@@ -2207,7 +2240,7 @@ declare function set(obj: object, path: string, value: any): void;
  * Traverses the form and returns the errors by path
  * @param form
  */
-declare function getAllFormErrors(form?: AbstractControl): Record<string, any>;
+declare function getAllFormErrors(form?: AbstractControl): Record<string, string[]>;
 
 /**
  * Options for configuring debounced pending state behavior.