ngx-vest-forms 2.2.0 → 2.3.0

package/README.md

@@ -116,7 +116,8 @@ That's all you need. The directive automatically creates controls, wires validat
 - **Unidirectional state with signals** — Models are `NgxDeepPartial<T>` so values build up incrementally
 - **Type-safe with runtime shape validation** — Automatic control creation and validation wiring (dev mode checks)
 - **Vest.js validations** — Sync/async, conditional, composable patterns with `only(field)` optimization
-- **Error display modes** — Control when errors show: `on-blur`, `on-submit`, or `on-blur-or-submit` (default)
+- **Error display modes** — Control when errors show: `on-blur`, `on-submit`, `on-blur-or-submit` (default), `on-dirty`, or `always`
+- **Warning display modes** — Control when warnings show: `on-touch`, `on-validated-or-touch` (default), `on-dirty`, or `always`
 - **Form state tracking** — Access touched, dirty, valid/invalid states for individual fields or entire form
 - **Error display helpers** — `ngx-control-wrapper` component (recommended) plus directive building blocks for custom wrappers:
   - `ngx-form-group-wrapper` component (recommended for `ngModelGroup` containers)
@@ -125,23 +126,60 @@ That's all you need. The directive automatically creates controls, wires validat
 - **Cross-field dependencies** — `validationConfig` for field-to-field triggers, `ROOT_FORM` for form-level rules
 - **Utilities** — Field paths, field clearing, validation config builder
 
-### Error Display Modes
+### Error & Warning Display Modes
 
-Control when validation errors are shown to users with three built-in modes:
+Control when validation errors and warnings are shown to users with multiple built-in modes:
+
+#### Error Display Modes
 
 ```typescript
 // Global configuration via DI token
 import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
 
 providers: [
-  { provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-blur-or-submit' }
+  { provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-dirty' }
 ]
 
 // Recommended: Use ngx-control-wrapper component
 <ngx-control-wrapper [errorDisplayMode]="'on-blur'">
   <input name="email" [ngModel]="formValue().email" />
 </ngx-control-wrapper>
+```
+
+| Mode                  | Behavior                                             |
+| --------------------- | ---------------------------------------------------- |
+| `'on-blur-or-submit'` | Show after blur OR form submit (default)             |
+| `'on-blur'`           | Show only after blur/touch                           |
+| `'on-submit'`         | Show only after form submission                      |
+| `'on-dirty'`          | Show as soon as value changes (or after blur/submit) |
+| `'always'`            | Show immediately, even on pristine fields            |
+
+#### Warning Display Modes
+
+```typescript
+// Global configuration via DI token
+import { NGX_WARNING_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
+
+providers: [
+  { provide: NGX_WARNING_DISPLAY_MODE_TOKEN, useValue: 'always' }
+]
 
+// Per-instance configuration
+<ngx-control-wrapper [warningDisplayMode]="'on-dirty'">
+  <input name="username" [ngModel]="formValue().username" />
+</ngx-control-wrapper>
+```
+
+| Mode                      | Behavior                                             |
+| ------------------------- | ---------------------------------------------------- |
+| `'on-validated-or-touch'` | Show after validation runs or touch (default)        |
+| `'on-touch'`              | Show only after blur/touch                           |
+| `'on-dirty'`              | Show as soon as value changes (or after blur/submit) |
+| `'always'`                | Show immediately, even on pristine fields            |
+
+#### Group-Safe Mode Example
+
+```html
 // Group-safe mode (use this on an ngModelGroup container)
 <ngx-form-group-wrapper ngModelGroup="address">
   <ngx-control-wrapper>
@@ -175,14 +213,6 @@ For `ngModelGroup` containers, prefer using `<ngx-form-group-wrapper>` (group-sa
 > **Styling note**: `ngx-control-wrapper` uses Tailwind CSS utility classes for default styling.
 > If your project doesn't use Tailwind, see the [component docs](./projects/ngx-vest-forms/src/lib/components/control-wrapper/README.md#styling-dependency-tailwind-css) for alternatives.
 
-**Available modes:**
-
-- **`on-blur-or-submit`** (default) — Show errors after field is touched OR form is submitted
-- **`on-blur`** — Show errors only after field loses focus (touched)
-- **`on-submit`** — Show errors only after form submission
-
-**Tip**: Use `on-blur-or-submit` for best UX — users get immediate feedback on touched fields while preventing overwhelming errors on pristine forms.
-
 📖 **[Complete Guide: Custom Control Wrappers](./docs/CUSTOM-CONTROL-WRAPPERS.md)**
 
 ### Form State
@@ -212,14 +242,14 @@ Access complete form and field state through the `FormErrorDisplayDirective` or
 - `isValid()` / `isInvalid()` — Validation state
 - `isPending()` — Async validation in progress
 - `errorMessages()` / `warningMessages()` — Current validation messages
-- `shouldShowErrors()` — Computed based on display mode and state
+- `shouldShowErrors()` / `shouldShowWarnings()` — Computed based on display mode and state
 
 **Warnings behavior:**
 
 - Warnings are **non-blocking** and do not make a field invalid.
-- Warnings are stored separately from `control.errors` and are cleared on `resetForm()`.
-- Warnings may appear after `validationConfig` triggers validation, even if the field
-- was not touched yet. Use `NGX_WARNING_DISPLAY_MODE_TOKEN` to require touch-only display.
+- They are stored separately from `control.errors` and are cleared on `resetForm()`.
+- These messages may appear after `validationConfig` triggers validation, even if the field was not touched yet.
+- Use `NGX_WARNING_DISPLAY_MODE_TOKEN` to control when warnings display (see [Warning Display Modes](#warning-display-modes)).
 
 **Tip**: For async validations, use `createDebouncedPendingState()` to prevent "Validating..." messages from flashing when validation completes quickly (< 200ms).
 

package/fesm2022/ngx-vest-forms.mjs

@@ -13,7 +13,12 @@ const SC_ERROR_DISPLAY_MODE_TOKEN = new InjectionToken('SC_ERROR_DISPLAY_MODE_TO
 });
 /**
  * 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
  */
 const NGX_ERROR_DISPLAY_MODE_TOKEN = new InjectionToken('NGX_ERROR_DISPLAY_MODE_TOKEN', {
     providedIn: 'root',
@@ -21,7 +26,11 @@ const NGX_ERROR_DISPLAY_MODE_TOKEN = new InjectionToken('NGX_ERROR_DISPLAY_MODE_
 });
 /**
  * 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
  */
 const NGX_WARNING_DISPLAY_MODE_TOKEN = new InjectionToken('NGX_WARNING_DISPLAY_MODE_TOKEN', {
     providedIn: 'root',
@@ -1966,6 +1975,7 @@ class FormErrorDisplayDirective {
         this.shouldShowErrors = computed(() => {
             const mode = this.errorDisplayMode();
             const isTouched = this.isTouched();
+            const isDirty = this.isDirty();
             const isInvalid = this.isInvalid();
             const hasErrors = this.errorMessages().length > 0;
             const updateOn = this.updateOn();
@@ -1977,16 +1987,25 @@ class FormErrorDisplayDirective {
             if (updateOn === 'submit') {
                 return !!(formSubmitted && hasErrorState);
             }
-            // on-blur: show errors after blur (touch)
-            if (mode === 'on-blur') {
-                return !!(isTouched && hasErrorState);
+            // Handle the new display modes
+            switch (mode) {
+                case 'always':
+                    // Always show errors immediately, even on pristine fields
+                    return hasErrorState;
+                case 'on-dirty':
+                    // Show when value has changed, OR when touched/submitted (for backwards compat)
+                    return !!(isDirty || isTouched || formSubmitted) && hasErrorState;
+                case 'on-blur':
+                    // Show after touch (blur) or form submission (traditional behavior, not dirty-based)
+                    return !!(isTouched || formSubmitted) && hasErrorState;
+                case 'on-submit':
+                    // Show only after form submission
+                    return !!(formSubmitted && hasErrorState);
+                case 'on-blur-or-submit':
+                default:
+                    // Show after blur (touch) OR submit (default behavior)
+                    return !!((isTouched || formSubmitted) && hasErrorState);
             }
-            // on-submit: show errors after submit
-            if (mode === 'on-submit') {
-                return !!(formSubmitted && hasErrorState);
-            }
-            // on-blur-or-submit: show errors after blur (touch) OR submit
-            return !!((isTouched || formSubmitted) && hasErrorState);
         }, ...(ngDevMode ? [{ debugName: "shouldShowErrors" }] : []));
         /**
          * Errors to display (filtered for pending state)
@@ -2017,6 +2036,47 @@ class FormErrorDisplayDirective {
             }
             return this.hasPendingValidation();
         }, ...(ngDevMode ? [{ debugName: "isPending" }] : []));
+        /**
+         * 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.
+         */
+        this.shouldShowWarnings = computed(() => {
+            const mode = this.warningDisplayMode();
+            const isTouched = this.isTouched();
+            const isDirty = this.isDirty();
+            const hasBeenValidated = this.hasBeenValidated();
+            const hasWarnings = this.warningMessages().length > 0;
+            const isPending = this.hasPendingValidation();
+            const formSubmitted = this.formSubmitted();
+            // No warnings to show or still pending
+            if (!hasWarnings || isPending) {
+                return false;
+            }
+            // Handle the warning display modes
+            switch (mode) {
+                case 'always':
+                    // Always show warnings immediately, even on pristine fields
+                    return true;
+                case 'on-dirty':
+                    // Show when value has changed, OR when touched/submitted (for backwards compat)
+                    return isDirty || isTouched || formSubmitted;
+                case 'on-touch':
+                    // Show after touch (blur) or form submission (traditional behavior, not dirty-based)
+                    return isTouched || formSubmitted;
+                case 'on-validated-or-touch':
+                default:
+                    // Show after validation runs or after touch/submit (default behavior)
+                    return hasBeenValidated || isTouched || formSubmitted;
+            }
+        }, ...(ngDevMode ? [{ debugName: "shouldShowWarnings" }] : []));
         // Warn about problematic combinations of updateOn and errorDisplayMode
         effect(() => {
             const mode = this.errorDisplayMode();
@@ -2161,6 +2221,8 @@ let nextUniqueId$2 = 0;
  * - `'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'">
@@ -2168,6 +2230,19 @@ let nextUniqueId$2 = 0;
  * </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
@@ -2200,9 +2275,9 @@ let nextUniqueId$2 = 0;
  *
  * 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>
@@ -2296,28 +2371,12 @@ class ControlWrapperComponent {
         this.showPendingMessage = this.pendingState.showPendingMessage;
         /**
          * 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.
          */
-        this.shouldShowWarnings = computed(() => {
-            const isTouched = this.errorDisplay.isTouched();
-            const hasBeenValidated = this.errorDisplay.hasBeenValidated();
-            const isPending = this.errorDisplay.isPending();
-            const hasWarnings = this.errorDisplay.warnings().length > 0;
-            const mode = this.errorDisplay.warningDisplayMode();
-            const shouldShowAfterInteraction = mode === 'on-touch' ? isTouched : isTouched || hasBeenValidated;
-            return shouldShowAfterInteraction && hasWarnings && !isPending;
-        }, ...(ngDevMode ? [{ debugName: "shouldShowWarnings" }] : []));
+        this.shouldShowWarnings = this.errorDisplay.shouldShowWarnings;
         /**
          * Computed signal that builds aria-describedby string based on visible regions
          */