ngx-vest-forms 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-vest-forms",
-  "version": "2.1.0",
+  "version": "2.2.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

@@ -1,78 +1,99 @@
 import * as _angular_core from '@angular/core';
 import { Signal, AfterContentInit, OnDestroy, InputSignal, AfterViewInit, InjectionToken } from '@angular/core';
-import { NgModel, NgModelGroup, AsyncValidator, AbstractControl, ValidationErrors, NgForm, AsyncValidatorFn, FormsModule, ControlContainer, FormGroup } from '@angular/forms';
+import { ValidationErrors, NgModel, NgModelGroup, AsyncValidator, AbstractControl, NgForm, AsyncValidatorFn, FormsModule, ControlContainer, FormGroup } from '@angular/forms';
 import { Observable } from 'rxjs';
 import * as ngx_vest_forms from 'ngx-vest-forms';
 import { StaticSuite } from 'vest';
 
+/**
+ * Angular's ValidationErrors is `{ [key: string]: any }`.
+ * We extend it with Vest-specific structure for better type safety.
+ */
+type VestValidationErrors = {
+    /** Vest error messages array */
+    errors?: readonly string[];
+    /** Vest warning messages array */
+    warnings?: readonly string[];
+} & ValidationErrors;
+/**
+ * Form control status values as defined by Angular.
+ * @see AbstractControl.status
+ */
+type FormControlStatus = 'VALID' | 'INVALID' | 'PENDING' | 'DISABLED';
 /**
  * Represents the core state of an Angular form control.
- * Contains only the raw state properties directly from the Angular form system.
+ * Uses narrower types than Angular's defaults where possible.
  */
 type FormControlState = {
-    status: string | null | undefined;
-    isValid: boolean | null | undefined;
-    isInvalid: boolean | null | undefined;
-    isPending: boolean | null | undefined;
-    isDisabled: boolean | null | undefined;
-    isTouched: boolean | null | undefined;
-    isDirty: boolean | null | undefined;
-    isPristine: boolean | null | undefined;
-    errors: Record<string, unknown> | null | undefined;
+    readonly status: FormControlStatus | null;
+    readonly isValid: boolean;
+    readonly isInvalid: boolean;
+    readonly isPending: boolean;
+    readonly isDisabled: boolean;
+    readonly isTouched: boolean;
+    readonly isDirty: boolean;
+    readonly isPristine: boolean;
+    /** Errors from Angular validators or Vest validation */
+    readonly errors: VestValidationErrors | null;
 };
 declare class FormControlStateDirective {
     #private;
-    protected readonly contentNgModel: Signal<NgModel | undefined>;
-    protected readonly contentNgModelGroup: Signal<NgModelGroup | undefined>;
+    protected readonly contentNgModel: _angular_core.Signal<NgModel | undefined>;
+    protected readonly contentNgModelGroup: _angular_core.Signal<NgModelGroup | undefined>;
     constructor();
     /**
      * Main control state computed signal (merges robust touched/dirty)
      */
-    readonly controlState: Signal<FormControlState>;
+    readonly controlState: _angular_core.Signal<FormControlState>;
     /**
      * Extracts error messages from Angular/Vest errors (recursively flattens)
      */
-    readonly errorMessages: Signal<any[]>;
+    readonly errorMessages: _angular_core.Signal<string[]>;
     /**
      * ADVANCED: updateOn strategy (change/blur/submit) if available
      */
-    readonly updateOn: Signal<"change" | "blur" | "submit">;
+    readonly updateOn: _angular_core.Signal<"change" | "blur" | "submit">;
     /**
      * ADVANCED: Composite/derived signals for advanced error display logic
      */
-    readonly isValidTouched: Signal<boolean>;
-    readonly isInvalidTouched: Signal<boolean>;
-    readonly shouldShowErrors: Signal<boolean>;
+    readonly isValidTouched: _angular_core.Signal<boolean>;
+    readonly isInvalidTouched: _angular_core.Signal<boolean>;
+    readonly shouldShowErrors: _angular_core.Signal<boolean>;
     /**
-     * Extracts warning messages from Vest validation results (robust)
+     * Extracts warning messages from Vest validation results.
+     * Checks two sources:
+     * 1. control.errors.warnings (when errors exist alongside warnings)
+     * 2. FormDirective.fieldWarnings (for warnings-only scenarios)
+     * This dual-source approach allows warnings to be displayed without affecting field validity.
      */
-    readonly warningMessages: Signal<any[]>;
+    readonly warningMessages: _angular_core.Signal<string[]>;
     /**
      * Whether async validation is in progress
      */
-    readonly hasPendingValidation: Signal<boolean>;
+    readonly hasPendingValidation: _angular_core.Signal<boolean>;
     /**
      * Convenience signals for common state checks
      */
-    readonly isValid: Signal<boolean>;
-    readonly isInvalid: Signal<boolean>;
-    readonly isPending: Signal<boolean>;
-    readonly isTouched: Signal<boolean>;
-    readonly isDirty: Signal<boolean>;
-    readonly isPristine: Signal<boolean>;
-    readonly isDisabled: Signal<boolean>;
-    readonly hasErrors: Signal<boolean>;
+    readonly isValid: _angular_core.Signal<boolean>;
+    readonly isInvalid: _angular_core.Signal<boolean>;
+    readonly isPending: _angular_core.Signal<boolean>;
+    readonly isTouched: _angular_core.Signal<boolean>;
+    readonly isDirty: _angular_core.Signal<boolean>;
+    readonly isPristine: _angular_core.Signal<boolean>;
+    readonly isDisabled: _angular_core.Signal<boolean>;
+    readonly hasErrors: _angular_core.Signal<boolean>;
     /**
      * Whether this control has been validated at least once.
      * True after the first validation completes, even if the user hasn't touched the field.
      * This enables showing errors for validationConfig-triggered validations.
      */
-    readonly hasBeenValidated: Signal<boolean>;
+    readonly hasBeenValidated: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormControlStateDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormControlStateDirective, "[formControlState], [ngxControlState]", ["formControlState", "ngxControlState"], {}, {}, ["contentNgModel", "contentNgModelGroup"], never, true, never>;
 }
 
 type ScErrorDisplayMode = 'on-blur' | 'on-submit' | 'on-blur-or-submit';
+type NgxWarningDisplayMode = 'on-touch' | 'on-validated-or-touch';
 declare class FormErrorDisplayDirective {
     #private;
     /**
@@ -80,31 +101,36 @@ declare class FormErrorDisplayDirective {
      * Works seamlessly with hostDirectives in Angular 19+.
      */
     readonly errorDisplayMode: _angular_core.InputSignal<ScErrorDisplayMode>;
-    readonly controlState: _angular_core.Signal<FormControlState>;
-    readonly errorMessages: _angular_core.Signal<any[]>;
-    readonly warningMessages: _angular_core.Signal<any[]>;
-    readonly hasPendingValidation: _angular_core.Signal<boolean>;
-    readonly isTouched: _angular_core.Signal<boolean>;
-    readonly isDirty: _angular_core.Signal<boolean>;
-    readonly isValid: _angular_core.Signal<boolean>;
-    readonly isInvalid: _angular_core.Signal<boolean>;
-    readonly hasBeenValidated: _angular_core.Signal<boolean>;
+    /**
+     * Input signal for warning display mode.
+     * Controls whether warnings are shown only after touch or also after validation.
+     */
+    readonly warningDisplayMode: _angular_core.InputSignal<NgxWarningDisplayMode>;
+    readonly controlState: Signal<FormControlState>;
+    readonly errorMessages: Signal<string[]>;
+    readonly warningMessages: Signal<string[]>;
+    readonly hasPendingValidation: Signal<boolean>;
+    readonly isTouched: Signal<boolean>;
+    readonly isDirty: Signal<boolean>;
+    readonly isValid: Signal<boolean>;
+    readonly isInvalid: Signal<boolean>;
+    readonly hasBeenValidated: Signal<boolean>;
     /**
      * Expose updateOn and formSubmitted as public signals for advanced consumers.
      * updateOn: The ngModelOptions.updateOn value for the control (change/blur/submit)
      * formSubmitted: true after the form is submitted (if NgForm is present)
      */
-    readonly updateOn: _angular_core.Signal<"change" | "blur" | "submit">;
+    readonly updateOn: Signal<"change" | "blur" | "submit">;
     /**
      * Signal that tracks NgForm.submitted state reactively.
      *
-     * Uses toSignal() to convert ngSubmit events + statusChanges into a reactive signal.
+     * Uses a trigger signal pattern for cleaner reactive tracking:
      * - ngSubmit: fires when form is submitted (sets NgForm.submitted = true)
      * - statusChanges: fires after resetForm() (which sets NgForm.submitted = false)
      *
      * This ensures proper sync with both submit and reset operations.
      */
-    readonly formSubmitted: _angular_core.Signal<boolean>;
+    readonly formSubmitted: Signal<boolean>;
     constructor();
     /**
      * Determines if errors should be shown based on the specified display mode
@@ -119,22 +145,22 @@ declare class FormErrorDisplayDirective {
      * (e.g., confirmPassword validated when password changes). We check hasBeenValidated to show
      * errors in these scenarios, providing better UX and proper ARIA attributes.
      */
-    readonly shouldShowErrors: _angular_core.Signal<boolean>;
+    readonly shouldShowErrors: Signal<boolean>;
     /**
      * Errors to display (filtered for pending state)
      */
-    readonly errors: _angular_core.Signal<any[]>;
+    readonly errors: Signal<string[]>;
     /**
      * Warnings to display (filtered for pending state)
      */
-    readonly warnings: _angular_core.Signal<any[]>;
+    readonly warnings: Signal<string[]>;
     /**
      * Whether the control is currently being validated (pending)
      * Excludes pristine+untouched controls to prevent "Validating..." on initial load
      */
-    readonly isPending: _angular_core.Signal<boolean>;
+    readonly isPending: Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormErrorDisplayDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormErrorDisplayDirective, "[formErrorDisplay], [ngxErrorDisplay]", ["formErrorDisplay", "ngxErrorDisplay"], { "errorDisplayMode": { "alias": "errorDisplayMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof FormControlStateDirective; inputs: {}; outputs: {}; }]>;
+    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: {}; }]>;
 }
 
 /**
@@ -169,25 +195,37 @@ declare class FormErrorDisplayDirective {
  * - Unique IDs for error/warning/pending regions
  * - `aria-describedby` linking errors to form controls
  * - `aria-invalid="true"` when errors are shown
- * - `role="status"` with `aria-live="polite"` for non-interruptive announcements
+ * - Uses `role="status"` with `aria-live="polite"` for non-disruptive announcements
  * - Debounced pending state to prevent flashing for quick validations
  *
+ * ### WCAG 2.2 AA - Error Severity Levels
+ * This component uses `role="status"` for **field-level** validation messages:
+ * - **Errors**: Non-disruptive announcement (user can continue filling other fields)
+ * - **Warnings**: Informational only, doesn't block submission
+ * - **Pending**: Status update while async validation runs
+ *
+ * For **form-level blocking errors** (e.g., submission failed), implement a separate
+ * error summary component with `role="alert"` and `aria-live="assertive"`.
+ *
  * @see {@link FormErrorDisplayDirective} for custom wrapper implementation
  *
- *   Blocking Errors (form-level):
+ *   Form-Level Blocking Errors:
  *   - For post-submit validation errors that block submission, implement a separate
  *     form-level error summary with role="alert" and aria-live="assertive"
- *   - Example:
+ *   - This component uses role="status" for field-level errors (non-disruptive)
+ *   - Example for form-level errors:
  *     ```html
  *     <!-- Keep in DOM; update text content on submit -->
  *     <div id="form-errors" role="alert" aria-live="assertive" aria-atomic="true"></div>
  *     ```
- *   - This provides immediate, reliable announcements for blocking errors while keeping
- *     inline field errors non-disruptive. Follows WCAG ARIA19/ARIA22 guidance.
+ *   - This separation provides immediate announcements for blocking form errors while
+ *     keeping inline field errors non-disruptive. Follows WCAG ARIA21/ARIA22 guidance.
  *
  * Error & Warning Display Behavior:
- *   - The error display mode can be configured globally using the SC_ERROR_DISPLAY_MODE_TOKEN injection token (import from core), or per instance using the `errorDisplayMode` input on FormErrorDisplayDirective (which this component uses as a hostDirective).
+ *   - The error display mode can be configured globally using the NGX_ERROR_DISPLAY_MODE_TOKEN injection token, or per instance using the `errorDisplayMode` input on FormErrorDisplayDirective (which this component uses as a hostDirective).
  *   - Possible values: 'on-blur' | 'on-submit' | 'on-blur-or-submit' (default: 'on-blur-or-submit')
+ *   - The warning display mode can be configured globally using NGX_WARNING_DISPLAY_MODE_TOKEN, or per instance using the `warningDisplayMode` input on FormErrorDisplayDirective.
+ *   - Possible values: 'on-touch' | 'on-validated-or-touch' (default: 'on-validated-or-touch')
  *
  * Example (per instance):
  *   <div ngxControlWrapper>
@@ -208,10 +246,10 @@ declare class FormErrorDisplayDirective {
  *
  * Example (global config):
  *   import { provide } from '@angular/core';
- *   import { SC_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
+ *   import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
  *   @Component({
  *     providers: [
- *       provide(SC_ERROR_DISPLAY_MODE_TOKEN, { useValue: 'submit' })
+ *       provide(NGX_ERROR_DISPLAY_MODE_TOKEN, { useValue: 'submit' })
  *     ]
  *   })
  *   export class MyComponent {}
@@ -256,6 +294,22 @@ declare class ControlWrapperComponent implements AfterContentInit, OnDestroy {
      */
     private readonly pendingState;
     protected readonly showPendingMessage: _angular_core.Signal<boolean>;
+    /**
+     * Whether to display warnings.
+     * Warnings are shown when:
+     * 1. The field has been touched (user has interacted with it)
+     * 2. The field has warnings to display
+     * 3. The field is not currently pending validation
+     *
+     * NOTE: Unlike errors, warnings can exist on VALID fields (warnings-only scenario).
+     * We don't require isInvalid() because Vest warn() tests don't affect field validity.
+     *
+     * UX Note: We include `hasBeenValidated` here to support cross-field validation.
+     * If Field A triggers validation on Field B (via validationConfig), Field B should
+     * show warnings if it has them, even if the user hasn't touched Field B yet.
+     * Unlike errors (which block submission), warnings are informational and safe to safe to show.
+     */
+    protected readonly shouldShowWarnings: _angular_core.Signal<boolean>;
     /**
      * Computed signal that builds aria-describedby string based on visible regions
      */
@@ -278,7 +332,7 @@ declare class ControlWrapperComponent implements AfterContentInit, OnDestroy {
      */
     private updateFormControls;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ControlWrapperComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ControlWrapperComponent, "ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]", never, { "ariaAssociationMode": { "alias": "ariaAssociationMode"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; }; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ControlWrapperComponent, "ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]", never, { "ariaAssociationMode": { "alias": "ariaAssociationMode"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof FormErrorDisplayDirective; inputs: { "errorDisplayMode": "errorDisplayMode"; "warningDisplayMode": "warningDisplayMode"; }; outputs: {}; }]>;
 }
 
 /**
@@ -326,7 +380,6 @@ declare class FormGroupWrapperComponent {
 declare class FormErrorControlDirective implements AfterContentInit, OnDestroy {
     protected readonly errorDisplay: FormErrorDisplayDirective;
     private readonly elementRef;
-    private readonly destroyRef;
     /**
      * Controls how this directive applies ARIA attributes to descendant controls.
      *
@@ -890,6 +943,13 @@ declare class FormDirective<T extends Record<string, unknown>> {
     private readonly destroyRef;
     private readonly cdr;
     private readonly configDebounceTime;
+    /**
+     * Public signal storing field warnings keyed by field path.
+     * This allows warnings to be stored and displayed without affecting field validity.
+     * Angular's control.errors !== null marks a field as invalid, so we store warnings
+     * separately when they exist without errors.
+     */
+    readonly fieldWarnings: _angular_core.WritableSignal<Map<string, readonly string[]>>;
     /**
      * Computed signal for form state with validity and errors.
      * Used by templates and tests as vestForm.formState().valid/errors
@@ -938,7 +998,7 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * that is not PENDING
      * We need this to assure that the form is in 'idle' state
      */
-    readonly idle$: Observable<"INVALID" | "VALID" | "DISABLED">;
+    readonly idle$: Observable<"VALID" | "INVALID" | "DISABLED">;
     /**
      * Triggered as soon as the form value changes
      * It also contains the disabled values (raw values)
@@ -950,6 +1010,9 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * Emits an object with all the errors of the form
      * every time a form control or form groups changes its status to valid or invalid
      *
+     * For submit events, waits for async validation (including ROOT_FORM) to complete
+     * before emitting errors. This ensures ROOT_FORM errors are included in the output.
+     *
      * Cleanup is handled automatically by the directive when it's destroyed.
      */
     readonly errorsChange: _angular_core.OutputRef<Record<string, any>>;
@@ -2314,6 +2377,11 @@ declare const SC_ERROR_DISPLAY_MODE_TOKEN: InjectionToken<ScErrorDisplayMode>;
  * Values: 'on-blur' | 'on-submit' | 'on-blur-or-submit' (default)
  */
 declare const NGX_ERROR_DISPLAY_MODE_TOKEN: InjectionToken<ScErrorDisplayMode>;
+/**
+ * Injection token for configuring the default warning display mode.
+ * Values: 'on-touch' | 'on-validated-or-touch' (default)
+ */
+declare const NGX_WARNING_DISPLAY_MODE_TOKEN: InjectionToken<NgxWarningDisplayMode>;
 
 /**
  * Injection token for configurable validation config debounce timing.
@@ -2361,5 +2429,5 @@ declare const NGX_ERROR_DISPLAY_MODE_TOKEN: InjectionToken<ScErrorDisplayMode>;
  */
 declare const NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN: InjectionToken<number>;
 
-export { ControlWrapperComponent, FormControlStateDirective, FormDirective, FormErrorControlDirective, FormErrorDisplayDirective, FormGroupWrapperComponent, FormModelDirective, FormModelGroupDirective, NGX_ERROR_DISPLAY_MODE_TOKEN, NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, NgxVestForms, ROOT_FORM, ROOT_FORM as ROOT_FORM_CONSTANT, SC_ERROR_DISPLAY_MODE_TOKEN, ValidateRootFormDirective, ValidationConfigBuilder, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, createDebouncedPendingState, createEmptyFormState, createValidationConfig, deepArrayToObject, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeValuesAndRawValues, objectToArray, parseFieldPath, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
-export type { DebouncedPendingStateOptions, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxFieldKey, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };
+export { ControlWrapperComponent, FormControlStateDirective, FormDirective, FormErrorControlDirective, FormErrorDisplayDirective, FormGroupWrapperComponent, FormModelDirective, FormModelGroupDirective, NGX_ERROR_DISPLAY_MODE_TOKEN, NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, NGX_WARNING_DISPLAY_MODE_TOKEN, NgxVestForms, ROOT_FORM, ROOT_FORM as ROOT_FORM_CONSTANT, SC_ERROR_DISPLAY_MODE_TOKEN, ValidateRootFormDirective, ValidationConfigBuilder, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, createDebouncedPendingState, createEmptyFormState, createValidationConfig, deepArrayToObject, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeValuesAndRawValues, objectToArray, parseFieldPath, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
+export type { DebouncedPendingStateOptions, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxFieldKey, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, NgxWarningDisplayMode, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };