ngx-vest-forms 1.3.0 → 1.4.0

package/fesm2022/ngx-vest-forms.mjs

@@ -1,9 +1,322 @@
 import * as i0 from '@angular/core';
-import { input, Directive, isDevMode, inject, DestroyRef, effect, ChangeDetectorRef, signal, computed, ContentChild, ChangeDetectionStrategy, Component, Optional } from '@angular/core';
-import { FormGroup, FormArray, NG_ASYNC_VALIDATORS, NgForm, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, NgModelGroup, NgModel, ControlContainer, FormsModule } from '@angular/forms';
-import { Subject, of, ReplaySubject, debounceTime, take, switchMap, Observable, takeUntil, filter, map, distinctUntilChanged, startWith, tap, finalize, mergeWith } from 'rxjs';
+import { contentChild, inject, Injector, computed, signal, effect, afterEveryRender, Directive, InjectionToken, input, ChangeDetectionStrategy, Component, isDevMode, DestroyRef, Optional } from '@angular/core';
+import { NgModel, NgModelGroup, NgForm, FormGroup, FormArray, NG_ASYNC_VALIDATORS, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, ControlContainer, FormsModule } from '@angular/forms';
+import { Subject, of, ReplaySubject, debounceTime, take, switchMap, Observable, takeUntil, filter, map, distinctUntilChanged, startWith, tap, finalize, catchError, from } from 'rxjs';
 import { outputFromObservable, takeUntilDestroyed } from '@angular/core/rxjs-interop';
 
+function getInitialFormControlState() {
+    return {
+        status: 'INVALID',
+        isValid: false,
+        isInvalid: true,
+        isPending: false,
+        isDisabled: false,
+        isTouched: false,
+        isDirty: false,
+        isPristine: true,
+        errors: null,
+    };
+}
+class FormControlStateDirective {
+    #hostNgModel;
+    #hostNgModelGroup;
+    #injector;
+    /**
+     * Computed signal for the active control (NgModel or NgModelGroup)
+     */
+    #activeControl;
+    /**
+     * Internal signal for robust touched/dirty tracking (syncs after every render)
+     */
+    #interactionState;
+    /**
+     * Internal signal for control state (updated reactively)
+     */
+    #controlStateSignal;
+    constructor() {
+        this.contentNgModel = contentChild(NgModel, ...(ngDevMode ? [{ debugName: "contentNgModel" }] : []));
+        this.contentNgModelGroup = contentChild(NgModelGroup, ...(ngDevMode ? [{ debugName: "contentNgModelGroup" }] : []));
+        this.#hostNgModel = inject(NgModel, {
+            self: true,
+            optional: true,
+        });
+        this.#hostNgModelGroup = inject(NgModelGroup, {
+            self: true,
+            optional: true,
+        });
+        this.#injector = inject(Injector);
+        /**
+         * Computed signal for the active control (NgModel or NgModelGroup)
+         */
+        this.#activeControl = computed(() => {
+            return (this.#hostNgModel ||
+                this.#hostNgModelGroup ||
+                this.contentNgModel() ||
+                this.contentNgModelGroup() ||
+                null);
+        }, ...(ngDevMode ? [{ debugName: "#activeControl" }] : []));
+        /**
+         * Internal signal for robust touched/dirty tracking (syncs after every render)
+         */
+        this.#interactionState = signal({
+            isTouched: false,
+            isDirty: false,
+        }, ...(ngDevMode ? [{ debugName: "#interactionState" }] : []));
+        /**
+         * Internal signal for control state (updated reactively)
+         */
+        this.#controlStateSignal = signal(getInitialFormControlState(), ...(ngDevMode ? [{ debugName: "#controlStateSignal" }] : []));
+        /**
+         * Main control state computed signal (merges robust touched/dirty)
+         */
+        this.controlState = computed(() => this.#controlStateSignal(), ...(ngDevMode ? [{ debugName: "controlState" }] : []));
+        /**
+         * Extracts error messages from Angular/Vest errors (recursively flattens)
+         */
+        this.errorMessages = computed(() => {
+            const state = this.controlState();
+            if (!state?.errors)
+                return [];
+            // Vest errors are stored in the 'errors' property as an array
+            const vestErrors = state.errors['errors'];
+            if (Array.isArray(vestErrors)) {
+                return vestErrors;
+            }
+            // Fallback to flattened Angular error keys
+            return this.#flattenAngularErrors(state.errors);
+        }, ...(ngDevMode ? [{ debugName: "errorMessages" }] : []));
+        /**
+         * ADVANCED: updateOn strategy (change/blur/submit) if available
+         */
+        this.updateOn = computed(() => {
+            const ngModel = this.contentNgModel() || this.#hostNgModel;
+            // Angular's NgModel.options?.updateOn
+            return ngModel?.options?.updateOn ?? 'change';
+        }, ...(ngDevMode ? [{ debugName: "updateOn" }] : []));
+        /**
+         * ADVANCED: Composite/derived signals for advanced error display logic
+         */
+        this.isValidTouched = computed(() => this.isValid() && this.isTouched(), ...(ngDevMode ? [{ debugName: "isValidTouched" }] : []));
+        this.isInvalidTouched = computed(() => this.isInvalid() && this.isTouched(), ...(ngDevMode ? [{ debugName: "isInvalidTouched" }] : []));
+        this.shouldShowErrors = computed(() => this.isInvalid() && this.isTouched() && !this.isPending(), ...(ngDevMode ? [{ debugName: "shouldShowErrors" }] : []));
+        /**
+         * Extracts warning messages from Vest validation results (robust)
+         */
+        this.warningMessages = computed(() => {
+            const state = this.controlState();
+            if (!state?.errors)
+                return [];
+            const warnings = state.errors['warnings'];
+            if (Array.isArray(warnings)) {
+                return warnings;
+            }
+            // Optionally, flatten nested warnings if needed in future
+            return [];
+        }, ...(ngDevMode ? [{ debugName: "warningMessages" }] : []));
+        /**
+         * Whether async validation is in progress
+         */
+        this.hasPendingValidation = computed(() => !!this.controlState().isPending, ...(ngDevMode ? [{ debugName: "hasPendingValidation" }] : []));
+        /**
+         * Convenience signals for common state checks
+         */
+        this.isValid = computed(() => this.controlState().isValid || false, ...(ngDevMode ? [{ debugName: "isValid" }] : []));
+        this.isInvalid = computed(() => this.controlState().isInvalid || false, ...(ngDevMode ? [{ debugName: "isInvalid" }] : []));
+        this.isPending = computed(() => this.controlState().isPending || false, ...(ngDevMode ? [{ debugName: "isPending" }] : []));
+        this.isTouched = computed(() => this.controlState().isTouched || false, ...(ngDevMode ? [{ debugName: "isTouched" }] : []));
+        this.isDirty = computed(() => this.controlState().isDirty || false, ...(ngDevMode ? [{ debugName: "isDirty" }] : []));
+        this.isPristine = computed(() => this.controlState().isPristine || false, ...(ngDevMode ? [{ debugName: "isPristine" }] : []));
+        this.isDisabled = computed(() => this.controlState().isDisabled || false, ...(ngDevMode ? [{ debugName: "isDisabled" }] : []));
+        this.hasErrors = computed(() => this.errorMessages().length > 0, ...(ngDevMode ? [{ debugName: "hasErrors" }] : []));
+        // Update control state reactively
+        effect(() => {
+            const control = this.#activeControl();
+            const interaction = this.#interactionState();
+            if (!control) {
+                this.#controlStateSignal.set(getInitialFormControlState());
+                return;
+            }
+            // Listen to control changes
+            const sub = control.control?.statusChanges?.subscribe(() => {
+                const { status, valid, invalid, pending, disabled, pristine, errors } = control;
+                this.#controlStateSignal.set({
+                    status,
+                    isValid: valid,
+                    isInvalid: invalid,
+                    isPending: pending,
+                    isDisabled: disabled,
+                    isTouched: interaction.isTouched,
+                    isDirty: interaction.isDirty,
+                    isPristine: pristine,
+                    errors,
+                });
+            });
+            // Initial update
+            const { status, valid, invalid, pending, disabled, pristine, errors } = control;
+            this.#controlStateSignal.set({
+                status,
+                isValid: valid,
+                isInvalid: invalid,
+                isPending: pending,
+                isDisabled: disabled,
+                isTouched: interaction.isTouched,
+                isDirty: interaction.isDirty,
+                isPristine: pristine,
+                errors,
+            });
+            return () => sub?.unsubscribe();
+        });
+        // Robustly sync touched/dirty after every render (Angular 18+ best practice)
+        afterEveryRender(() => {
+            const control = this.#activeControl();
+            if (control) {
+                const current = this.#interactionState();
+                const newTouched = control.touched ?? false;
+                const newDirty = control.dirty ?? false;
+                if (newTouched !== current.isTouched ||
+                    newDirty !== current.isDirty) {
+                    this.#interactionState.set({
+                        isTouched: newTouched,
+                        isDirty: newDirty,
+                    });
+                }
+            }
+        }, { injector: this.#injector });
+    }
+    /**
+     * Recursively flattens Angular error objects into an array of error keys.
+     */
+    #flattenAngularErrors(errors) {
+        const result = [];
+        for (const key of Object.keys(errors)) {
+            const value = errors[key];
+            if (typeof value === 'object' && value !== null) {
+                result.push(...this.#flattenAngularErrors(value));
+            }
+            else {
+                result.push(key);
+            }
+        }
+        return result;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormControlStateDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.2.0", version: "20.3.1", type: FormControlStateDirective, isStandalone: true, selector: "[formControlState]", queries: [{ propertyName: "contentNgModel", first: true, predicate: NgModel, descendants: true, isSignal: true }, { propertyName: "contentNgModelGroup", first: true, predicate: NgModelGroup, descendants: true, isSignal: true }], exportAs: ["formControlState"], ngImport: i0 }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormControlStateDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[formControlState]',
+                    exportAs: 'formControlState',
+                }]
+        }], ctorParameters: () => [] });
+
+const SC_ERROR_DISPLAY_MODE_TOKEN = new InjectionToken('SC_ERROR_DISPLAY_MODE_TOKEN', {
+    providedIn: 'root',
+    factory: () => 'on-blur-or-submit',
+});
+
+const SC_ERROR_DISPLAY_MODE_DEFAULT = 'on-blur-or-submit';
+class FormErrorDisplayDirective {
+    #formControlState;
+    // Optionally inject NgForm for form submission tracking
+    #ngForm;
+    constructor() {
+        this.#formControlState = inject(FormControlStateDirective);
+        // Optionally inject NgForm for form submission tracking
+        this.#ngForm = inject(NgForm, { optional: true });
+        // Use DI token for global default, fallback to hardcoded default
+        this.errorDisplayMode = input(inject(SC_ERROR_DISPLAY_MODE_TOKEN, { optional: true }) ??
+            SC_ERROR_DISPLAY_MODE_DEFAULT, ...(ngDevMode ? [{ debugName: "errorDisplayMode" }] : []));
+        // Expose state signals from FormControlStateDirective
+        this.controlState = this.#formControlState.controlState;
+        this.errorMessages = this.#formControlState.errorMessages;
+        this.warningMessages = this.#formControlState.warningMessages;
+        this.hasPendingValidation = this.#formControlState.hasPendingValidation;
+        this.isTouched = this.#formControlState.isTouched;
+        this.isDirty = this.#formControlState.isDirty;
+        this.isValid = this.#formControlState.isValid;
+        this.isInvalid = this.#formControlState.isInvalid;
+        /**
+         * 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)
+         */
+        this.updateOn = this.#formControlState.updateOn;
+        // formSubmitted signal is already public
+        // Signal for form submission state (true after submit)
+        this.formSubmitted = signal(false, ...(ngDevMode ? [{ debugName: "formSubmitted" }] : []));
+        /**
+         * Determines if errors should be shown based on the specified display mode
+         * and the control's state (touched/submitted).
+         */
+        this.shouldShowErrors = computed(() => {
+            const mode = this.errorDisplayMode();
+            const isTouched = this.isTouched();
+            const hasErrors = this.errorMessages().length > 0;
+            const updateOn = this.updateOn();
+            const formSubmitted = this.formSubmitted();
+            // Always only show errors after submit if updateOn is 'submit'
+            if (updateOn === 'submit') {
+                return !!(formSubmitted && hasErrors);
+            }
+            // on-blur: show errors after blur (touch)
+            if (mode === 'on-blur') {
+                return !!(isTouched && hasErrors);
+            }
+            // on-submit: show errors after submit
+            if (mode === 'on-submit') {
+                return !!(formSubmitted && hasErrors);
+            }
+            // on-blur-or-submit: show errors after blur (touch) or submit
+            return !!((isTouched || formSubmitted) && hasErrors);
+        }, ...(ngDevMode ? [{ debugName: "shouldShowErrors" }] : []));
+        /**
+         * Errors to display (filtered for pending state)
+         */
+        this.errors = computed(() => {
+            if (this.hasPendingValidation())
+                return [];
+            return this.errorMessages();
+        }, ...(ngDevMode ? [{ debugName: "errors" }] : []));
+        /**
+         * Warnings to display (filtered for pending state)
+         */
+        this.warnings = computed(() => {
+            if (this.hasPendingValidation())
+                return [];
+            return this.warningMessages();
+        }, ...(ngDevMode ? [{ debugName: "warnings" }] : []));
+        /**
+         * Whether the control is currently being validated (pending)
+         */
+        this.isPending = computed(() => this.hasPendingValidation(), ...(ngDevMode ? [{ debugName: "isPending" }] : []));
+        // Listen for form submit event if NgForm is present
+        if (this.#ngForm?.ngSubmit) {
+            this.#ngForm.ngSubmit.subscribe(() => {
+                this.formSubmitted.set(true);
+            });
+        }
+        // Warn about problematic combinations of updateOn and errorDisplayMode
+        effect(() => {
+            const mode = this.errorDisplayMode();
+            const updateOn = this.updateOn();
+            if (updateOn === 'submit' && mode === 'on-blur') {
+                console.warn('[ngx-vest-forms] Potential UX issue: errorDisplayMode is "on-blur" but updateOn is "submit". Errors will only show after form submission, not after blur.');
+            }
+        });
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormErrorDisplayDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "20.3.1", type: FormErrorDisplayDirective, isStandalone: true, selector: "[formErrorDisplay]", inputs: { errorDisplayMode: { classPropertyName: "errorDisplayMode", publicName: "errorDisplayMode", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["formErrorDisplay"], hostDirectives: [{ directive: FormControlStateDirective }], ngImport: i0 }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormErrorDisplayDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[formErrorDisplay]',
+                    exportAs: 'formErrorDisplay',
+                    hostDirectives: [FormControlStateDirective],
+                }]
+        }], ctorParameters: () => [] });
+
 const ROOT_FORM = 'rootForm';
 /**
  * Debounce time in milliseconds for validation config dependency triggering.
@@ -258,7 +571,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
             type: Directive,
             args: [{
                     selector: 'form[validateRootForm][formValue][suite]',
-                    standalone: true,
                     providers: [
                         {
                             provide: NG_ASYNC_VALIDATORS,
@@ -269,6 +581,72 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
                 }]
         }] });
 
+/**
+ * Accessible ScControlWrapper
+ *
+ * Usage:
+ *   - Wrap any form element with `sc-control-wrapper` or `[scControlWrapper]` (or `[sc-control-wrapper]` for legacy) that contains an `ngModel` or `ngModelGroup`.
+ *   - Errors and warnings are shown when the control is invalid and touched, after form submit, or both, depending on the error display mode.
+ *   - Pending state is shown with a spinner and aria-busy when async validation is running.
+ *   - No manual error/warning/pending signal management is needed in your form components.
+ *
+ * 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).
+ *   - Possible values: 'on-blur' | 'on-submit' | 'on-blur-or-submit' (default: 'on-blur-or-submit')
+ *
+ * Example (per instance):
+ *   <div ngxControlWrapper>
+ *     <label>
+ *       <span>First name</span>
+ *       <input type="text" name="firstName" [ngModel]="formValue().firstName" />
+ *     </label>
+ *   </div>
+ *   /// To customize errorDisplayMode for this instance, use the errorDisplayMode input.
+ *
+ * Example (with warnings and pending):
+ *   <sc-control-wrapper>
+ *     <input name="username" ngModel />
+ *   </sc-control-wrapper>
+ *   /// If async validation is running, a spinner and 'Validating…' will be shown.
+ *   /// If Vest warnings are present, they will be shown below errors.
+ *
+ * Example (global config):
+ *   import { provide } from '@angular/core';
+ *   import { SC_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
+ *   @Component({
+ *     providers: [
+ *       provide(SC_ERROR_DISPLAY_MODE_TOKEN, { useValue: 'submit' })
+ *     ]
+ *   })
+ *   export class MyComponent {}
+ *
+ * Best Practices:
+ *   - Use for every input or group in your forms.
+ *   - Do not manually display errors for individual fields; rely on this wrapper.
+ */
+class ControlWrapperComponent {
+    constructor() {
+        this.errorDisplay = inject(FormErrorDisplayDirective, {
+            self: true,
+        });
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: ControlWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.1", type: ControlWrapperComponent, isStandalone: true, selector: "sc-control-wrapper, [scControlWrapper], [sc-control-wrapper]", host: { properties: { "class.sc-control-wrapper--invalid": "errorDisplay.shouldShowErrors()", "attr.aria-busy": "errorDisplay.isPending() ? 'true' : null" }, classAttribute: "sc-control-wrapper" }, hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0, template: "<div class=\"ngx-control-wrapper\">\n  <div class=\"sc-control-wrapper__content\">\n    <ng-content />\n  </div>\n\n  @if (errorDisplay.shouldShowErrors()) {\n    <div class=\"text-sm text-red-600\" role=\"alert\" aria-live=\"polite\">\n      <ul>\n        @for (error of errorDisplay.errors(); track error) {\n          <li>{{ error.message || error }}</li>\n        }\n      </ul>\n    </div>\n  }\n  @if (errorDisplay.warnings().length > 0) {\n    <div class=\"text-sm text-yellow-700\" role=\"status\" aria-live=\"polite\">\n      <ul>\n        @for (warn of errorDisplay.warnings(); track warn) {\n          <li>{{ warn }}</li>\n        }\n      </ul>\n    </div>\n  }\n  @if (errorDisplay.isPending()) {\n    <div class=\"flex items-center gap-1 text-xs text-gray-500\" aria-busy=\"true\">\n      <span\n        class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      ></span>\n      Validating\u2026\n    </div>\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: ControlWrapperComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'sc-control-wrapper, [scControlWrapper], [sc-control-wrapper]', changeDetection: ChangeDetectionStrategy.OnPush, host: {
+                        class: 'sc-control-wrapper',
+                        '[class.sc-control-wrapper--invalid]': 'errorDisplay.shouldShowErrors()',
+                        '[attr.aria-busy]': "errorDisplay.isPending() ? 'true' : null",
+                    }, hostDirectives: [
+                        {
+                            directive: FormErrorDisplayDirective,
+                            inputs: ['errorDisplayMode'],
+                        },
+                    ], template: "<div class=\"ngx-control-wrapper\">\n  <div class=\"sc-control-wrapper__content\">\n    <ng-content />\n  </div>\n\n  @if (errorDisplay.shouldShowErrors()) {\n    <div class=\"text-sm text-red-600\" role=\"alert\" aria-live=\"polite\">\n      <ul>\n        @for (error of errorDisplay.errors(); track error) {\n          <li>{{ error.message || error }}</li>\n        }\n      </ul>\n    </div>\n  }\n  @if (errorDisplay.warnings().length > 0) {\n    <div class=\"text-sm text-yellow-700\" role=\"status\" aria-live=\"polite\">\n      <ul>\n        @for (warn of errorDisplay.warnings(); track warn) {\n          <li>{{ warn }}</li>\n        }\n      </ul>\n    </div>\n  }\n  @if (errorDisplay.isPending()) {\n    <div class=\"flex items-center gap-1 text-xs text-gray-500\" aria-busy=\"true\">\n      <span\n        class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      ></span>\n      Validating\u2026\n    </div>\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"] }]
+        }] });
+
 /**
  * Type guard to check if a value is a primitive type.
  *
@@ -538,6 +916,16 @@ function validateFormValue(formValue, shape, path = '') {
 }
 
 class FormDirective {
+    /**
+     * Returns the current form state: validity and errors.
+     * Used by templates and tests as vestForm.formState().valid/errors
+     */
+    formState() {
+        return {
+            valid: this.ngForm.form.valid,
+            errors: getAllFormErrors(this.ngForm.form),
+        };
+    }
     constructor() {
         this.ngForm = inject(NgForm, { self: true, optional: false });
         this.destroyRef = inject(DestroyRef);
@@ -613,17 +1001,21 @@ class FormDirective {
         /**
          * Used to debounce formValues to make sure vest isn't triggered all the time
          */
+        // Async validator cache for debouncing and single-flight per field
         this.formValueCache = {};
         this.validationInProgress = new Set();
         /**
          * Trigger shape validations if the form gets updated
          * This is how we can throw run-time errors
          */
-        this.formValueChange.subscribe((v) => {
-            if (this.formShape()) {
-                validateShape(v, this.formShape());
-            }
-        });
+        if (isDevMode()) {
+            effect(() => {
+                const v = this.formValue();
+                if (v && this.formShape()) {
+                    validateShape(v, this.formShape());
+                }
+            });
+        }
         /**
          * Mark all the fields as touched when the form is submitted
          */
@@ -749,35 +1141,109 @@ class FormDirective {
      * @param validationOptions
      * @returns an asynchronous validator function
      */
+    /**
+     * Improved async validator: composable, debounced, robust error handling.
+     * Compatible with v2 pattern, non-breaking.
+     */
     createAsyncValidator(field, validationOptions) {
-        if (!this.suite()) {
-            return () => of(null);
-        }
         return (value) => {
-            if (!this.formValue()) {
+            const suite = this.suite();
+            const formValue = this.formValue();
+            if (!suite || !formValue) {
                 return of(null);
             }
-            const mod = cloneDeep(this.formValue());
-            set(mod, field, value); // Update the property with path
+            const candidate = cloneDeep(formValue);
+            set(candidate, field, value);
             if (!this.formValueCache[field]) {
-                this.formValueCache[field] = {
-                    sub$$: new ReplaySubject(1), // Keep track of the last model
-                };
-                this.formValueCache[field].debounced = this.formValueCache[field].sub$$.pipe(debounceTime(validationOptions.debounceTime));
+                this.formValueCache[field] = new ReplaySubject(1);
             }
-            // Next the latest model in the cache for a certain field
-            this.formValueCache[field].sub$$.next(mod);
-            return this.formValueCache[field].debounced.pipe(
-            // When debounced, take the latest value and perform the asynchronous vest validation
-            take(1), switchMap(() => {
+            const subject = this.formValueCache[field];
+            subject.next(candidate);
+            const debounceMs = validationOptions?.debounceTime ?? 0;
+            return subject.pipe(debounceTime(debounceMs), take(1), switchMap((model) => {
+                if (isDevMode()) {
+                    console.debug('[ngx-vest-forms] Running suite for field', field, 'with model', model);
+                }
                 return new Observable((observer) => {
-                    this.suite()(mod, field).done((result) => {
-                        const errors = result.getErrors()[field];
-                        observer.next(errors ? { error: errors[0], errors } : null);
+                    const emitResult = (vestResult) => {
+                        const pushResult = () => {
+                            try {
+                                let errors;
+                                if (typeof vestResult?.getErrors === 'function') {
+                                    const direct = vestResult.getErrors(field);
+                                    if (Array.isArray(direct)) {
+                                        errors = direct;
+                                    }
+                                    else {
+                                        const bag = vestResult.getErrors();
+                                        errors = bag?.[field];
+                                    }
+                                }
+                                if (isDevMode()) {
+                                    console.debug('[ngx-vest-forms] Final result errors for field', field, errors);
+                                }
+                                if (Array.isArray(errors) && errors.length > 0) {
+                                    observer.next({ error: errors[0], errors });
+                                }
+                                else {
+                                    observer.next(null);
+                                }
+                            }
+                            catch (error) {
+                                observer.next({
+                                    vestInternalError: error instanceof Error
+                                        ? error.message
+                                        : 'Unknown validation error',
+                                });
+                            }
+                            finally {
+                                observer.complete();
+                            }
+                        };
+                        if (typeof queueMicrotask === 'function') {
+                            queueMicrotask(pushResult);
+                        }
+                        else {
+                            setTimeout(pushResult, 0);
+                        }
+                    };
+                    let suiteResult;
+                    try {
+                        suiteResult = suite(model, field);
+                    }
+                    catch (error) {
+                        observer.next({
+                            vestInternalError: error instanceof Error
+                                ? error.message
+                                : 'Unknown validation error',
+                        });
                         observer.complete();
-                    });
+                        return;
+                    }
+                    if (isDevMode()) {
+                        console.debug('[ngx-vest-forms] Suite returned', suiteResult);
+                    }
+                    const doneFn = suiteResult?.done;
+                    if (typeof doneFn === 'function') {
+                        try {
+                            doneFn.call(suiteResult, emitResult);
+                        }
+                        catch (error) {
+                            observer.next({
+                                vestInternalError: error instanceof Error
+                                    ? error.message
+                                    : 'Unknown validation error',
+                            });
+                            observer.complete();
+                        }
+                    }
+                    else {
+                        emitResult(suiteResult);
+                    }
                 });
-            }), takeUntilDestroyed(this.destroyRef));
+            }), catchError((err) => of({
+                vestInternalError: err?.message || 'Unknown validation error',
+            })), takeUntilDestroyed(this.destroyRef));
         };
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
@@ -788,80 +1254,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
             args: [{
                     selector: 'form[scVestForm]',
                     exportAs: 'scVestForm',
-                    standalone: true,
                 }]
         }], ctorParameters: () => [] });
 
-class ControlWrapperComponent {
-    constructor() {
-        this.ngModelGroup = inject(NgModelGroup, {
-            optional: true,
-            self: true,
-        });
-        this.destroy$$ = new Subject();
-        this.cdRef = inject(ChangeDetectorRef);
-        this.formDirective = inject(FormDirective);
-        // Signal-based state management
-        this.controlState = signal({ touched: false, pending: false, errors: undefined }, ...(ngDevMode ? [{ debugName: "controlState" }] : []));
-        // Computed signal for invalid state
-        this.invalid = computed(() => {
-            const state = this.controlState();
-            return state.touched && state.errors && state.errors.length > 0;
-        }, ...(ngDevMode ? [{ debugName: "invalid" }] : []));
-        // Computed signal for errors with pending state handling
-        this.errors = computed(() => {
-            const state = this.controlState();
-            if (state.pending) {
-                return this.previousError;
-            }
-            else {
-                this.previousError = state.errors;
-            }
-            return state.errors;
-        }, ...(ngDevMode ? [{ debugName: "errors" }] : []));
-    }
-    get control() {
-        return this.ngModelGroup
-            ? this.ngModelGroup.control
-            : this.ngModel?.control;
-    }
-    ngOnDestroy() {
-        this.destroy$$.next();
-    }
-    ngAfterViewInit() {
-        // Wait until the form is idle
-        // Then, listen to all events of the ngModelGroup or ngModel
-        // and update our signal-based state
-        this.formDirective.idle$
-            .pipe(switchMap(() => this.ngModelGroup?.control?.events || of(null)), mergeWith(this.control?.events || of(null)), takeUntil(this.destroy$$))
-            .subscribe(() => {
-            this.updateControlState();
-            this.cdRef.markForCheck();
-        });
-    }
-    updateControlState() {
-        const control = this.control;
-        if (control) {
-            this.controlState.set({
-                touched: control.touched,
-                pending: control.pending,
-                errors: control.errors?.['errors'],
-            });
-        }
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: ControlWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.1", type: ControlWrapperComponent, isStandalone: true, selector: "[sc-control-wrapper]", host: { properties: { "class.sc-control-wrapper--invalid": "invalid()" } }, queries: [{ propertyName: "ngModel", first: true, predicate: NgModel, descendants: true }], ngImport: i0, template: "<div class=\"sc-control-wrapper\">\n  <div class=\"sc-control-wrapper__content\">\n    <ng-content></ng-content>\n  </div>\n  <div class=\"sc-control-wrapper__errors\">\n    <ul [hidden]=\"!invalid()\">\n      @for (error of errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  </div>\n</div>\n", styles: [":host{display:block;position:relative}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: ControlWrapperComponent, decorators: [{
-            type: Component,
-            args: [{ selector: '[sc-control-wrapper]', changeDetection: ChangeDetectionStrategy.OnPush, host: {
-                        '[class.sc-control-wrapper--invalid]': 'invalid()',
-                    }, template: "<div class=\"sc-control-wrapper\">\n  <div class=\"sc-control-wrapper__content\">\n    <ng-content></ng-content>\n  </div>\n  <div class=\"sc-control-wrapper__errors\">\n    <ul [hidden]=\"!invalid()\">\n      @for (error of errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  </div>\n</div>\n", styles: [":host{display:block;position:relative}\n"] }]
-        }], propDecorators: { ngModel: [{
-                type: ContentChild,
-                args: [NgModel]
-            }] } });
-
 /**
  * Hooks into the ngModel selector and triggers an asynchronous validation for a form model
  * It will use a vest suite behind the scenes
@@ -869,12 +1264,57 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
 class FormModelDirective {
     constructor() {
         this.validationOptions = input({ debounceTime: 0 }, ...(ngDevMode ? [{ debugName: "validationOptions" }] : []));
-        this.formDirective = inject(FormDirective);
+        /**
+         * Reference to the form that needs to be validated
+         * Injected optionally so that using ngModel outside of an ngxVestForm
+         * does not crash the application. In that case, validation becomes a no-op.
+         */
+        this.formDirective = inject(FormDirective, {
+            optional: true,
+        });
     }
     validate(control) {
-        const { ngForm, suite, formValue } = this.formDirective;
+        // Null check for control
+        if (!control) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Validate called with null control in FormModelDirective.');
+            }
+            return of(null);
+        }
+        // Null check for form context
+        const context = this.formDirective;
+        if (!context) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] ngModel used outside of ngxVestForm; skipping validation.');
+            }
+            return of(null);
+        }
+        const { ngForm } = context;
         const field = getFormControlField(ngForm.control, control);
-        return this.formDirective.createAsyncValidator(field, this.validationOptions())(control.getRawValue());
+        if (!field) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Could not determine field name for validation in FormModelDirective (skipping).');
+            }
+            return of(null);
+        }
+        const asyncValidator = context.createAsyncValidator(field, this.validationOptions());
+        // Pass the control value to the validator
+        const validationResult = asyncValidator(control.value);
+        if (validationResult instanceof Observable) {
+            return validationResult;
+        }
+        else if (validationResult instanceof Promise) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Async validator returned a Promise. Converting to Observable.');
+            }
+            return from(validationResult);
+        }
+        else {
+            if (isDevMode()) {
+                console.error('[ngx-vest-forms] Async validator returned an unexpected type:', validationResult);
+            }
+            return of(null);
+        }
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormModelDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
     static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "20.3.1", type: FormModelDirective, isStandalone: true, selector: "[ngModel]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
@@ -889,7 +1329,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
             type: Directive,
             args: [{
                     selector: '[ngModel]',
-                    standalone: true,
                     providers: [
                         {
                             provide: NG_ASYNC_VALIDATORS,
@@ -907,12 +1346,49 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
 class FormModelGroupDirective {
     constructor() {
         this.validationOptions = input({ debounceTime: 0 }, ...(ngDevMode ? [{ debugName: "validationOptions" }] : []));
-        this.formDirective = inject(FormDirective);
+        this.formDirective = inject(FormDirective, { optional: true });
     }
     validate(control) {
-        const { ngForm } = this.formDirective;
+        // Null check for control
+        if (!control) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Validate called with null control in FormModelGroupDirective.');
+            }
+            return of(null);
+        }
+        // Null check for form context
+        const context = this.formDirective;
+        if (!context) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] ngModelGroup used outside of ngxVestForm; skipping validation.');
+            }
+            return of(null);
+        }
+        const { ngForm } = context;
         const field = getFormGroupField(ngForm.control, control);
-        return this.formDirective.createAsyncValidator(field, this.validationOptions())(control.value);
+        if (!field) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Could not determine field name for validation in FormModelGroupDirective (skipping).');
+            }
+            return of(null);
+        }
+        const asyncValidator = context.createAsyncValidator(field, this.validationOptions());
+        const validationResult = asyncValidator(control.value);
+        if (validationResult instanceof Observable) {
+            return validationResult;
+        }
+        else if (validationResult instanceof Promise) {
+            if (isDevMode()) {
+                console.debug('[ngx-vest-forms] Async validator returned a Promise. Converting to Observable.');
+            }
+            return from(validationResult);
+        }
+        else {
+            if (isDevMode()) {
+                console.error('[ngx-vest-forms] Async validator returned an unexpected type:', validationResult);
+            }
+            return of(null);
+        }
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: FormModelGroupDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
     static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "20.3.1", type: FormModelGroupDirective, isStandalone: true, selector: "[ngModelGroup]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
@@ -927,7 +1403,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImpor
             type: Directive,
             args: [{
                     selector: '[ngModelGroup]',
-                    standalone: true,
                     providers: [
                         {
                             provide: NG_ASYNC_VALIDATORS,
@@ -1207,13 +1682,9 @@ function keepFieldsWhen(currentState, conditions) {
     return result;
 }
 
-/*
- * Public API Surface of ngx-vest-forms
- */
-
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { ControlWrapperComponent, FormDirective, FormModelDirective, FormModelGroupDirective, ROOT_FORM, ShapeMismatchError, VALIDATION_CONFIG_DEBOUNCE_TIME, ValidateRootFormDirective, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeValuesAndRawValues, set, shallowEqual, validateShape, vestForms, vestFormsViewProviders };
+export { ControlWrapperComponent, FormControlStateDirective, FormDirective, FormErrorDisplayDirective, FormModelDirective, FormModelGroupDirective, ROOT_FORM, ShapeMismatchError, VALIDATION_CONFIG_DEBOUNCE_TIME, ValidateRootFormDirective, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeValuesAndRawValues, set, shallowEqual, validateShape, vestForms, vestFormsViewProviders };
 //# sourceMappingURL=ngx-vest-forms.mjs.map