ngx-vest-forms 2.2.0 → 2.3.1

package/package.json

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

@@ -92,8 +92,23 @@ declare class FormControlStateDirective {
     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';
+/**
+ * Error display modes for form controls.
+ * - 'on-blur': Show errors after field is touched/blurred
+ * - 'on-submit': Show errors after form submission
+ * - 'on-blur-or-submit': Show errors after blur or form submission (default)
+ * - 'on-dirty': Show errors as soon as the field value changes
+ * - 'always': Show errors immediately, even on pristine fields
+ */
+type ScErrorDisplayMode = 'on-blur' | 'on-submit' | 'on-blur-or-submit' | 'on-dirty' | 'always';
+/**
+ * Warning display modes for form controls.
+ * - 'on-touch': Show warnings after field is touched/blurred
+ * - 'on-validated-or-touch': Show warnings after validation runs or field is touched (default)
+ * - 'on-dirty': Show warnings as soon as the field value changes
+ * - 'always': Show warnings immediately, even on pristine fields
+ */
+type NgxWarningDisplayMode = 'on-touch' | 'on-validated-or-touch' | 'on-dirty' | 'always';
 declare class FormErrorDisplayDirective {
     #private;
     /**
@@ -159,6 +174,19 @@ declare class FormErrorDisplayDirective {
      * Excludes pristine+untouched controls to prevent "Validating..." on initial load
      */
     readonly isPending: Signal<boolean>;
+    /**
+     * Determines if warnings should be shown based on the specified display mode
+     * and the control's state (touched/validated/dirty).
+     *
+     * 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` for `on-validated-or-touch` mode 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 show.
+     */
+    readonly shouldShowWarnings: 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; }; "warningDisplayMode": { "alias": "warningDisplayMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof FormControlStateDirective; inputs: {}; outputs: {}; }]>;
 }
@@ -184,6 +212,8 @@ declare class FormErrorDisplayDirective {
  * - `'on-blur-or-submit'` (default): Show errors after blur OR form submit
  * - `'on-blur'`: Show errors only after blur
  * - `'on-submit'`: Show errors only after form submit
+ * - `'on-dirty'`: Show errors as soon as the field value changes
+ * - `'always'`: Show errors immediately, even on pristine fields
  *
  * ```html
  * <ngx-control-wrapper [errorDisplayMode]="'on-submit'">
@@ -191,6 +221,19 @@ declare class FormErrorDisplayDirective {
  * </ngx-control-wrapper>
  * ```
  *
+ * ### Warning Display Modes
+ * Control when warnings appear using the `warningDisplayMode` input:
+ * - `'on-validated-or-touch'` (default): Show warnings after validation runs or touch
+ * - `'on-touch'`: Show warnings only after touch/blur
+ * - `'on-dirty'`: Show warnings as soon as the field value changes
+ * - `'always'`: Show warnings immediately, even on pristine fields
+ *
+ * ```html
+ * <ngx-control-wrapper [warningDisplayMode]="'on-dirty'">
+ *   <input name="email" [ngModel]="formValue().email" />
+ * </ngx-control-wrapper>
+ * ```
+ *
  * ### Accessibility Features (Automatic)
  * - Unique IDs for error/warning/pending regions
  * - `aria-describedby` linking errors to form controls
@@ -223,9 +266,9 @@ declare class FormErrorDisplayDirective {
  *
  * Error & Warning Display Behavior:
  *   - 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')
+ *   - Possible error display values: 'on-blur' | 'on-submit' | 'on-blur-or-submit' | 'on-dirty' | 'always' (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')
+ *   - Possible warning display values: 'on-touch' | 'on-validated-or-touch' | 'on-dirty' | 'always' (default: 'on-validated-or-touch')
  *
  * Example (per instance):
  *   <div ngxControlWrapper>
@@ -296,18 +339,10 @@ declare class ControlWrapperComponent implements AfterContentInit, OnDestroy {
     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.
+     * Delegates to FormErrorDisplayDirective's centralized shouldShowWarnings signal.
      *
-     * 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.
+     * This ensures consistent warning display behavior across all form components
+     * and supports the new 'on-dirty' and 'always' display modes.
      */
     protected readonly shouldShowWarnings: _angular_core.Signal<boolean>;
     /**
@@ -2374,12 +2409,21 @@ declare function fastDeepEqual(obj1: unknown, obj2: unknown, maxDepth?: number):
 declare const SC_ERROR_DISPLAY_MODE_TOKEN: InjectionToken<ScErrorDisplayMode>;
 /**
  * Injection token for configuring the default error display mode.
- * Values: 'on-blur' | 'on-submit' | 'on-blur-or-submit' (default)
+ * Values:
+ * - 'on-blur': Show errors after field is touched/blurred
+ * - 'on-submit': Show errors after form submission
+ * - 'on-blur-or-submit': Show errors after blur or form submission (default)
+ * - 'on-dirty': Show errors as soon as the field value changes
+ * - 'always': Show errors immediately, even on pristine fields
  */
 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)
+ * Values:
+ * - 'on-touch': Show warnings after field is touched/blurred
+ * - 'on-validated-or-touch': Show warnings after validation runs or field is touched (default)
+ * - 'on-dirty': Show warnings as soon as the field value changes
+ * - 'always': Show warnings immediately, even on pristine fields
  */
 declare const NGX_WARNING_DISPLAY_MODE_TOKEN: InjectionToken<NgxWarningDisplayMode>;