ngx-vest-forms 2.1.0 → 2.2.0

package/fesm2022/ngx-vest-forms.mjs

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, contentChild, inject, Injector, computed, signal, effect, afterEveryRender, Directive, input, ElementRef, DestroyRef, ChangeDetectionStrategy, Component, isDevMode, ChangeDetectorRef, linkedSignal, untracked, booleanAttribute, Optional } from '@angular/core';
-import { NgModel, NgModelGroup, NgForm, FormGroup, FormArray, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, NG_ASYNC_VALIDATORS, ControlContainer, FormsModule } from '@angular/forms';
+import { InjectionToken, isDevMode, inject, DestroyRef, ChangeDetectorRef, signal, linkedSignal, computed, input, effect, untracked, Directive, contentChild, Injector, afterEveryRender, ElementRef, ChangeDetectionStrategy, Component, booleanAttribute, Optional } from '@angular/core';
+import { FormGroup, FormArray, NgForm, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, NgModel, NgModelGroup, NG_ASYNC_VALIDATORS, ControlContainer, FormsModule } from '@angular/forms';
 import { toSignal, outputFromObservable, takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
-import { merge, of, startWith, map, filter, distinctUntilChanged, timer, switchMap, Observable, catchError, take, EMPTY, debounceTime, tap, race, from } from 'rxjs';
+import { startWith, filter, map, distinctUntilChanged, merge, switchMap, take, of, timer, Observable, catchError, EMPTY, debounceTime, tap, race, from } from 'rxjs';
 
 /**
  * @deprecated Use NGX_ERROR_DISPLAY_MODE_TOKEN instead
@@ -19,1010 +19,303 @@ const NGX_ERROR_DISPLAY_MODE_TOKEN = new InjectionToken('NGX_ERROR_DISPLAY_MODE_
     providedIn: 'root',
     factory: () => 'on-blur-or-submit',
 });
-
-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;
-    /**
-     * Track whether this control has been validated at least once.
-     * This is separate from touched - a field can be validated via validationConfig
-     * without being touched by the user. This flag enables showing errors for
-     * validationConfig-triggered validations even before user interaction.
-     */
-    #hasBeenValidated;
-    /**
-     * Track the previous status to detect actual status changes (not just status emissions).
-     * This helps distinguish between initial control creation and actual re-validation.
-     */
-    #previousStatus;
-    /**
-     * 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" }] : []));
-        /**
-         * Track whether this control has been validated at least once.
-         * This is separate from touched - a field can be validated via validationConfig
-         * without being touched by the user. This flag enables showing errors for
-         * validationConfig-triggered validations even before user interaction.
-         */
-        this.#hasBeenValidated = signal(false, ...(ngDevMode ? [{ debugName: "#hasBeenValidated" }] : []));
-        /**
-         * Track the previous status to detect actual status changes (not just status emissions).
-         * This helps distinguish between initial control creation and actual re-validation.
-         */
-        this.#previousStatus = undefined;
-        /**
-         * 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" }] : []));
-        /**
-         * 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.
-         */
-        this.hasBeenValidated = computed(() => this.#hasBeenValidated(), ...(ngDevMode ? [{ debugName: "hasBeenValidated" }] : []));
-        // 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, touched, dirty, } = control;
-                // Mark as validated when any of the following conditions are met:
-                // 1. The control has been touched (user blurred the field).
-                // 2. The control's status has actually changed (not the first status emission),
-                //    AND the new status is not 'PENDING' (validation completed),
-                //    AND the control has been interacted with (dirty).
-                //
-                // This ensures hasBeenValidated is true for:
-                //   - User blur events (touched becomes true)
-                //   - User-triggered validations (dirty)
-                //   - ValidationConfig-triggered validations that result in the control becoming touched
-                // But NOT for initial page load validations.
-                //
-                // Accessibility: The logic is structured for clarity and maintainability.
-                // IMPORTANT: Read touched/dirty directly from control, not from signal,
-                // to avoid race conditions with afterEveryRender sync.
-                if (touched || // Control was blurred (most common case)
-                    (this.#previousStatus !== undefined && // Not the first status emission
-                        this.#previousStatus !== status && // Status actually changed
-                        status &&
-                        status !== 'PENDING' &&
-                        dirty) // Or control value changed (typed)
-                ) {
-                    this.#hasBeenValidated.set(true);
-                }
-                // Track current status for next iteration
-                this.#previousStatus = status;
-                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;
-            // Set initial previous status
-            this.#previousStatus = status;
-            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,
-                    });
-                    // Mark as validated when control becomes touched (e.g., user blurred the field)
-                    // This handles the case where blur doesn't trigger statusChanges (field already invalid)
-                    if (newTouched && !current.isTouched) {
-                        this.#hasBeenValidated.set(true);
-                    }
-                }
-            }
-        }, { 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: "21.1.0", ngImport: i0, type: FormControlStateDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.2.0", version: "21.1.0", type: FormControlStateDirective, isStandalone: true, selector: "[formControlState], [ngxControlState]", queries: [{ propertyName: "contentNgModel", first: true, predicate: NgModel, descendants: true, isSignal: true }, { propertyName: "contentNgModelGroup", first: true, predicate: NgModelGroup, descendants: true, isSignal: true }], exportAs: ["formControlState", "ngxControlState"], ngImport: i0 }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormControlStateDirective, decorators: [{
-            type: Directive,
-            args: [{
-                    selector: '[formControlState], [ngxControlState]',
-                    exportAs: 'formControlState, ngxControlState',
-                }]
-        }], ctorParameters: () => [], propDecorators: { contentNgModel: [{ type: i0.ContentChild, args: [i0.forwardRef(() => NgModel), { isSignal: true }] }], contentNgModelGroup: [{ type: i0.ContentChild, args: [i0.forwardRef(() => NgModelGroup), { isSignal: true }] }] } });
-
-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 });
-        /**
-         * Input signal for error display mode.
-         * Works seamlessly with hostDirectives in Angular 19+.
-         */
-        this.errorDisplayMode = input(inject(NGX_ERROR_DISPLAY_MODE_TOKEN, { optional: true }) ??
-            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;
-        this.hasBeenValidated = this.#formControlState.hasBeenValidated;
-        /**
-         * 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;
-        /**
-         * Signal that tracks NgForm.submitted state reactively.
-         *
-         * Uses toSignal() to convert ngSubmit events + statusChanges into a reactive signal.
-         * - 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.
-         */
-        this.formSubmitted = this.#ngForm
-            ? toSignal(merge(this.#ngForm.ngSubmit, this.#ngForm.statusChanges ?? of()).pipe(startWith(null), map(() => this.#ngForm?.submitted ?? false)), { initialValue: this.#ngForm.submitted })
-            : toSignal(of(false), { initialValue: false });
-        /**
-         * Determines if errors should be shown based on the specified display mode
-         * and the control's state (touched/submitted/validated).
-         *
-         * Note: We check both hasErrors (extracted error messages) AND isInvalid (Angular's validation state)
-         * because in some cases (like conditional validations via validationConfig), the control is marked
-         * as invalid by Angular before error messages are extracted from Vest. This ensures aria-invalid
-         * is set correctly even during the validation propagation delay.
-         *
-         * For validationConfig-triggered validations: A field can be validated without being touched
-         * (e.g., confirmPassword validated when password changes). We check hasBeenValidated to show
-         * errors in these scenarios, providing better UX and proper ARIA attributes.
-         */
-        this.shouldShowErrors = computed(() => {
-            const mode = this.errorDisplayMode();
-            const isTouched = this.isTouched();
-            const isInvalid = this.isInvalid();
-            const hasErrors = this.errorMessages().length > 0;
-            const updateOn = this.updateOn();
-            const formSubmitted = this.formSubmitted();
-            // Consider errors present if either we have error messages OR the control is invalid
-            // This handles the race condition where Angular marks control invalid before Vest errors propagate
-            const hasErrorState = hasErrors || isInvalid;
-            // Always only show errors after submit if updateOn is 'submit'
-            if (updateOn === 'submit') {
-                return !!(formSubmitted && hasErrorState);
-            }
-            // on-blur: show errors after blur (touch)
-            if (mode === 'on-blur') {
-                return !!(isTouched && 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)
-         */
-        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)
-         * Excludes pristine+untouched controls to prevent "Validating..." on initial load
-         */
-        this.isPending = computed(() => {
-            // Don't show pending state for pristine untouched controls
-            // This prevents "Validating..." message appearing on initial page load
-            const state = this.#formControlState.controlState();
-            if (state.isPristine && !state.isTouched) {
-                return false;
-            }
-            return this.hasPendingValidation();
-        }, ...(ngDevMode ? [{ debugName: "isPending" }] : []));
-        // 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: "21.1.0", ngImport: i0, type: FormErrorDisplayDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: FormErrorDisplayDirective, isStandalone: true, selector: "[formErrorDisplay], [ngxErrorDisplay]", inputs: { errorDisplayMode: { classPropertyName: "errorDisplayMode", publicName: "errorDisplayMode", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["formErrorDisplay", "ngxErrorDisplay"], hostDirectives: [{ directive: FormControlStateDirective }], ngImport: i0 }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormErrorDisplayDirective, decorators: [{
-            type: Directive,
-            args: [{
-                    selector: '[formErrorDisplay], [ngxErrorDisplay]',
-                    exportAs: 'formErrorDisplay, ngxErrorDisplay',
-                    hostDirectives: [FormControlStateDirective],
-                }]
-        }], ctorParameters: () => [], propDecorators: { errorDisplayMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "errorDisplayMode", required: false }] }] } });
-
-/**
- * Creates a debounced pending state signal that prevents flashing validation messages.
- *
- * This utility helps implement a better UX for async validations by:
- * 1. Delaying the display of "Validating..." messages until validation takes longer than `showAfter`ms (default: 200ms)
- * 2. Keeping the message visible for at least `minimumDisplay`ms (default: 500ms) once shown to prevent flickering
- *
- * @example
- * ```typescript
- * @Component({
- *   template: `
- *     @if (showPendingMessage()) {
- *       <div role="status" aria-live="polite">Validating…</div>
- *     }
- *   `
- * })
- * export class CustomControlWrapperComponent {
- *   protected readonly errorDisplay = inject(FormErrorDisplayDirective, { self: true });
- *
- *   // Create debounced pending state
- *   private readonly pendingState = createDebouncedPendingState(
- *     this.errorDisplay.isPending,
- *     { showAfter: 200, minimumDisplay: 500 }
- *   );
- *
- *   protected readonly showPendingMessage = this.pendingState.showPendingMessage;
- * }
- * ```
- *
- * @param isPending - Signal indicating whether async validation is currently pending
- * @param options - Configuration options for debouncing behavior
- * @returns Object containing the debounced showPendingMessage signal and cleanup function
- */
-function createDebouncedPendingState(isPending, options = {}) {
-    const { showAfter = 200, minimumDisplay = 500 } = options;
-    // Create writable signal for debounced state
-    const showPendingMessageSignal = signal(false, ...(ngDevMode ? [{ debugName: "showPendingMessageSignal" }] : []));
-    // Track timeouts
-    let pendingTimeout = null;
-    let minimumDisplayTimeout = null;
-    // Cleanup function
-    const cleanup = () => {
-        if (pendingTimeout) {
-            clearTimeout(pendingTimeout);
-            pendingTimeout = null;
-        }
-        if (minimumDisplayTimeout) {
-            clearTimeout(minimumDisplayTimeout);
-            minimumDisplayTimeout = null;
-        }
-    };
-    // Effect to manage debounced pending message display
-    effect((onCleanup) => {
-        const pending = isPending();
-        if (pending) {
-            // Clear any existing minimum display timeout
-            if (minimumDisplayTimeout) {
-                clearTimeout(minimumDisplayTimeout);
-                minimumDisplayTimeout = null;
-            }
-            // Start delay timer before showing pending message
-            pendingTimeout = setTimeout(() => {
-                showPendingMessageSignal.set(true);
-                pendingTimeout = null;
-            }, showAfter);
-            onCleanup(() => {
-                if (pendingTimeout) {
-                    clearTimeout(pendingTimeout);
-                    pendingTimeout = null;
-                }
-            });
-        }
-        else {
-            // Validation completed
-            if (pendingTimeout) {
-                // Validation completed before delay - don't show message
-                clearTimeout(pendingTimeout);
-                pendingTimeout = null;
-            }
-            else if (showPendingMessageSignal()) {
-                // Message was shown - keep it visible for minimum duration
-                minimumDisplayTimeout = setTimeout(() => {
-                    showPendingMessageSignal.set(false);
-                    minimumDisplayTimeout = null;
-                }, minimumDisplay);
-                onCleanup(() => {
-                    if (minimumDisplayTimeout) {
-                        clearTimeout(minimumDisplayTimeout);
-                        minimumDisplayTimeout = null;
-                    }
-                });
-            }
-        }
-    });
-    return {
-        showPendingMessage: showPendingMessageSignal.asReadonly(),
-        cleanup,
-    };
-}
-
-// Counter for unique IDs
-let nextUniqueId$2 = 0;
-/**
- * Accessible form control wrapper with WCAG 2.2 AA compliance.
- *
- * Wrap form fields to automatically display validation errors, warnings, and pending states
- * with proper accessibility attributes.
- *
- * @usageNotes
- *
- * ### Basic Usage
- * ```html
- * <ngx-control-wrapper>
- *   <label for="email">Email</label>
- *   <input id="email" name="email" [ngModel]="formValue().email" />
- * </ngx-control-wrapper>
- * ```
- *
- * ### Error Display Modes
- * Control when errors appear using the `errorDisplayMode` input:
- * - `'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
- *
- * ```html
- * <ngx-control-wrapper [errorDisplayMode]="'on-submit'">
- *   <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
- * - `aria-invalid="true"` when errors are shown
- * - `role="status"` with `aria-live="polite"` for non-interruptive announcements
- * - Debounced pending state to prevent flashing for quick validations
- *
- * @see {@link FormErrorDisplayDirective} for custom wrapper implementation
- *
- *   Blocking Errors (form-level):
- *   - For post-submit validation errors that block submission, implement a separate
- *     form-level error summary with role="alert" and aria-live="assertive"
- *   - Example:
- *     ```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.
- *
- * 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):
- *   <ngx-control-wrapper>
- *     <input name="username" ngModel />
- *   </ngx-control-wrapper>
- *   /// If async validation is running for >200ms, 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.
- *
- * 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.
- *   - Validate with tools like Accessibility Insights and real screen reader testing.
- *
- * @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA19 - ARIA19: Using ARIA role=alert
- * @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22 - ARIA22: Using role=status
- */
-class ControlWrapperComponent {
-    mergeAriaDescribedBy(existing, wrapperActiveIds) {
-        const existingTokens = (existing ?? '')
-            .split(/\s+/)
-            .map((t) => t.trim())
-            .filter(Boolean);
-        // Remove any previous wrapper-owned IDs from the existing list.
-        const existingWithoutWrapper = existingTokens.filter((t) => !this.wrapperOwnedDescribedByIds.includes(t));
-        // Append current wrapper IDs, preserving existing order and uniqueness.
-        const merged = [...existingWithoutWrapper];
-        for (const id of wrapperActiveIds) {
-            if (!merged.includes(id)) {
-                merged.push(id);
-            }
-        }
-        return merged.length > 0 ? merged.join(' ') : null;
-    }
-    constructor() {
-        this.errorDisplay = inject(FormErrorDisplayDirective, {
-            self: true,
-        });
-        this.elementRef = inject(ElementRef);
-        this.destroyRef = inject(DestroyRef);
-        /**
-         * Controls how this wrapper applies ARIA attributes to descendant controls.
-         *
-         * - `all-controls` (default, backwards compatible): apply `aria-describedby` / `aria-invalid`
-         *   to all `input/select/textarea` elements inside the wrapper.
-         * - `single-control`: apply ARIA attributes only when exactly one control is found.
-         *   (Useful for wrappers that sometimes contain helper buttons/controls.)
-         * - `none`: do not mutate descendant controls at all (group-safe mode).
-         *
-         * Notes:
-         * - Use `none` when wrapping a container (e.g. `NgModelGroup`) to avoid stamping ARIA
-         *   across multiple child controls.
-         * - This does not affect whether messages render; it only affects ARIA wiring.
-         */
-        this.ariaAssociationMode = input('all-controls', ...(ngDevMode ? [{ debugName: "ariaAssociationMode" }] : []));
-        // Generate unique IDs for ARIA associations
-        this.uniqueId = `ngx-control-wrapper-${nextUniqueId$2++}`;
-        this.errorId = `${this.uniqueId}-error`;
-        this.warningId = `${this.uniqueId}-warning`;
-        this.pendingId = `${this.uniqueId}-pending`;
-        // Track form controls found in the wrapper
-        this.formControls = signal([], ...(ngDevMode ? [{ debugName: "formControls" }] : []));
-        // Signals when content is initialized so effects can safely touch the DOM.
-        this.contentInitialized = signal(false, ...(ngDevMode ? [{ debugName: "contentInitialized" }] : []));
-        // MutationObserver to detect dynamically added/removed controls
-        this.mutationObserver = null;
-        /**
-         * Debounced pending state to prevent flashing for quick async validations.
-         * Uses createDebouncedPendingState utility with 500ms delay and 500ms minimum display.
-         */
-        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, { showAfter: 500, minimumDisplay: 500 });
-        this.showPendingMessage = this.pendingState.showPendingMessage;
-        /**
-         * Computed signal that builds aria-describedby string based on visible regions
-         */
-        this.ariaDescribedBy = computed(() => {
-            const ids = [];
-            if (this.errorDisplay.shouldShowErrors()) {
-                ids.push(this.errorId);
-            }
-            if (this.errorDisplay.warnings().length > 0) {
-                ids.push(this.warningId);
-            }
-            if (this.showPendingMessage()) {
-                ids.push(this.pendingId);
-            }
-            return ids.length > 0 ? ids.join(' ') : null;
-        }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
-        /**
-         * IDs managed by this wrapper when composing aria-describedby.
-         *
-         * We remove only these from the consumer-provided aria-describedby tokens and then
-         * append the currently-relevant wrapper IDs. This prevents clobbering app-provided
-         * hint/help text associations.
-         */
-        this.wrapperOwnedDescribedByIds = [
-            this.errorId,
-            this.warningId,
-            this.pendingId,
-        ];
-        // Effect to update aria-describedby and aria-invalid on form controls
-        effect(() => {
-            if (!this.contentInitialized())
-                return;
-            const mode = this.ariaAssociationMode();
-            if (mode === 'none') {
-                return;
-            }
-            const describedBy = this.ariaDescribedBy();
-            const wrapperActiveIds = describedBy
-                ? describedBy.split(/\s+/).filter(Boolean)
-                : [];
-            const shouldShowErrors = this.errorDisplay.shouldShowErrors();
-            const targets = (() => {
-                const controls = this.formControls();
-                if (mode === 'single-control') {
-                    return controls.length === 1 ? controls : [];
-                }
-                return controls;
-            })();
-            targets.forEach((control) => {
-                // Update aria-describedby (merge, don't overwrite)
-                const nextDescribedBy = this.mergeAriaDescribedBy(control.getAttribute('aria-describedby'), wrapperActiveIds);
-                if (nextDescribedBy) {
-                    control.setAttribute('aria-describedby', nextDescribedBy);
-                }
-                else {
-                    control.removeAttribute('aria-describedby');
-                }
-                // Update aria-invalid
-                if (shouldShowErrors) {
-                    control.setAttribute('aria-invalid', 'true');
-                }
-                else {
-                    control.removeAttribute('aria-invalid');
-                }
-            });
-        });
-        // Clean up MutationObserver when component is destroyed
-        this.destroyRef.onDestroy(() => {
-            this.mutationObserver?.disconnect();
-            this.mutationObserver = null;
-        });
-        // Effect to enable/disable DOM observation based on ariaAssociationMode.
-        // This keeps the wrapper cheap in group-safe mode.
-        effect(() => {
-            if (!this.contentInitialized())
-                return;
-            const mode = this.ariaAssociationMode();
-            if (mode === 'none') {
-                this.mutationObserver?.disconnect();
-                this.mutationObserver = null;
-                if (this.formControls().length > 0) {
-                    this.formControls.set([]);
-                }
-                return;
-            }
-            // Ensure controls list is up to date.
-            this.updateFormControls();
-            // Ensure MutationObserver is installed (dynamic @if/@for support).
-            if (!this.mutationObserver) {
-                this.mutationObserver = new MutationObserver(() => {
-                    this.updateFormControls();
-                });
-                this.mutationObserver.observe(this.elementRef.nativeElement, {
-                    childList: true,
-                    subtree: true,
-                });
-            }
-        });
-    }
-    ngAfterContentInit() {
-        this.contentInitialized.set(true);
-        // ARIA wiring + observer setup is managed by effects so that the wrapper can
-        // opt out (ariaAssociationMode="none").
-    }
-    ngOnDestroy() {
-        this.mutationObserver?.disconnect();
-        this.mutationObserver = null;
-    }
-    /**
-     * Query and update the list of form controls within this wrapper.
-     * Called on init and whenever the DOM structure changes.
-     */
-    updateFormControls() {
-        const controls = this.elementRef.nativeElement.querySelectorAll('input, select, textarea');
-        this.formControls.set(Array.from(controls));
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: ControlWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.0", type: ControlWrapperComponent, isStandalone: true, selector: "ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]", inputs: { ariaAssociationMode: { classPropertyName: "ariaAssociationMode", publicName: "ariaAssociationMode", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class.ngx-control-wrapper--invalid": "errorDisplay.shouldShowErrors()", "attr.aria-busy": "errorDisplay.isPending() ? 'true' : null" }, classAttribute: "ngx-control-wrapper sc-control-wrapper" }, hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0, template: "<div class=\"ngx-control-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Live regions are kept stable in the DOM to improve announcement reliability.\n  We update the inner content instead of relying on node mount/unmount.\n-->\n<div\n  [id]=\"errorId\"\n  class=\"text-sm text-red-600\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.shouldShowErrors()) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error.message || error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div\n  [id]=\"warningId\"\n  class=\"text-sm text-yellow-700\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!-- Pending state is also stable; content appears only after the debounce delay -->\n<div\n  [id]=\"pendingId\"\n  class=\"absolute top-0 right-0 flex items-center gap-1 text-xs text-gray-500\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (showPendingMessage()) {\n    <span\n      class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      aria-hidden=\"true\"\n    ></span>\n    Validating\u2026\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+/**
+ * Injection token for configuring the default warning display mode.
+ * Values: 'on-touch' | 'on-validated-or-touch' (default)
+ */
+const NGX_WARNING_DISPLAY_MODE_TOKEN = new InjectionToken('NGX_WARNING_DISPLAY_MODE_TOKEN', {
+    providedIn: 'root',
+    factory: () => 'on-validated-or-touch',
+});
+
+const NGX_VEST_FORMS_ERRORS = {
+    EXTRA_PROPERTY: {
+        code: 'NGX-001',
+        message: (path) => `Shape mismatch: Property '${path}' is present in the form value but not defined in the form shape.`,
+    },
+    TYPE_MISMATCH: {
+        code: 'NGX-002',
+        message: (path, expected, actual) => `Type mismatch at '${path}': Expected '${expected}' but got '${actual}'.`,
+    },
+    CONTROL_NOT_FOUND: {
+        code: 'NGX-003',
+        message: (path) => `Control not found: Could not find form control at path '${path}'. Check your [ngModel] name attributes.`,
+    },
+};
+function logWarning(error, ...args) {
+    console.warn(`[${error.code}] ${error.message(...args)}\nCheck your [formShape] input and the initial [formValue].`);
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: ControlWrapperComponent, decorators: [{
-            type: Component,
-            args: [{ selector: 'ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]', changeDetection: ChangeDetectionStrategy.OnPush, host: {
-                        class: 'ngx-control-wrapper sc-control-wrapper',
-                        '[class.ngx-control-wrapper--invalid]': 'errorDisplay.shouldShowErrors()',
-                        '[attr.aria-busy]': "errorDisplay.isPending() ? 'true' : null",
-                    }, hostDirectives: [
-                        {
-                            directive: FormErrorDisplayDirective,
-                            inputs: ['errorDisplayMode'],
-                        },
-                    ], template: "<div class=\"ngx-control-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Live regions are kept stable in the DOM to improve announcement reliability.\n  We update the inner content instead of relying on node mount/unmount.\n-->\n<div\n  [id]=\"errorId\"\n  class=\"text-sm text-red-600\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.shouldShowErrors()) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error.message || error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div\n  [id]=\"warningId\"\n  class=\"text-sm text-yellow-700\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!-- Pending state is also stable; content appears only after the debounce delay -->\n<div\n  [id]=\"pendingId\"\n  class=\"absolute top-0 right-0 flex items-center gap-1 text-xs text-gray-500\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (showPendingMessage()) {\n    <span\n      class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      aria-hidden=\"true\"\n    ></span>\n    Validating\u2026\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { ariaAssociationMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaAssociationMode", required: false }] }] } });
 
-let nextUniqueId$1 = 0;
 /**
- * Group-safe wrapper for `NgModelGroup` containers.
+ * Injection token for configurable validation config debounce timing.
  *
- * This component renders group-level errors/warnings/pending UI, but intentionally
- * does **not** stamp `aria-describedby` / `aria-invalid` onto descendant controls.
+ * This token allows you to configure the debounce time for validation config
+ * dependencies at the application, route, or component level.
  *
- * Use this when you want a wrapper around a container that has multiple inputs.
- * For single inputs, prefer `<ngx-control-wrapper>`.
+ * @example
+ * ```typescript
+ * /// Global configuration
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     {
+ *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
+ *       useValue: 200
+ *     }
+ *   ]
+ * };
+ *
+ * /// Per-route configuration
+ * {
+ *   path: 'checkout',
+ *   component: CheckoutComponent,
+ *   providers: [
+ *     {
+ *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
+ *       useValue: 50
+ *     }
+ *   ]
+ * }
+ *
+ * /// Per-component override
+ * @Component({
+ *   providers: [
+ *     {
+ *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
+ *       useValue: 0 // for testing
+ *     }
+ *   ]
+ * })
+ * export class TestFormComponent {}
+ * ```
+ *
+ * @default 100ms - Maintains backward compatibility with existing behavior
  */
-class FormGroupWrapperComponent {
-    constructor() {
-        this.errorDisplay = inject(FormErrorDisplayDirective, {
-            self: true,
-        });
-        /**
-         * Controls the debounce behavior for the pending message.
-         * Defaults are conservative to avoid flashing.
-         */
-        this.pendingDebounce = input({
-            showAfter: 500,
-            minimumDisplay: 500,
-        }, ...(ngDevMode ? [{ debugName: "pendingDebounce" }] : []));
-        this.uniqueId = `ngx-form-group-wrapper-${nextUniqueId$1++}`;
-        this.errorId = `${this.uniqueId}-error`;
-        this.warningId = `${this.uniqueId}-warning`;
-        this.pendingId = `${this.uniqueId}-pending`;
-        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, this.pendingDebounce());
-        this.showPendingMessage = this.pendingState.showPendingMessage;
-        /**
-         * Helpful if consumers want to wire aria-describedby manually (e.g. fieldset/legend pattern).
-         */
-        this.describedByIds = computed(() => {
-            const ids = [];
-            if (this.errorDisplay.shouldShowErrors()) {
-                ids.push(this.errorId);
-            }
-            if (this.errorDisplay.warnings().length > 0) {
-                ids.push(this.warningId);
-            }
-            if (this.showPendingMessage()) {
-                ids.push(this.pendingId);
-            }
-            return ids.length > 0 ? ids.join(' ') : null;
-        }, ...(ngDevMode ? [{ debugName: "describedByIds" }] : []));
+const NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN = new InjectionToken('NgxValidationConfigDebounceTime', {
+    providedIn: 'root',
+    factory: () => 100,
+});
+
+/**
+ * Type guard to check if a value is a primitive type.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a primitive (string, number, boolean, null, undefined, symbol, bigint)
+ */
+function isPrimitive$1(value) {
+    return (value === null || (typeof value !== 'object' && typeof value !== 'function'));
+}
+/**
+ * @internal
+ * Internal utility for shallow equality checks.
+ *
+ * **Not intended for external use.** This function is used internally by the library
+ * for performance-critical operations. Consider using your own comparison logic or
+ * a library like lodash if you need shallow equality checks in your application.
+ *
+ * Optimized shallow equality check for objects.
+ *
+ * **Why this custom implementation is preferred:**
+ * - **Performance**: Direct property comparison is significantly faster than JSON.stringify
+ * - **Type Safety**: Handles null/undefined values correctly without serialization issues
+ * - **Accuracy**: Doesn't suffer from JSON.stringify limitations (undefined values, functions, symbols)
+ * - **Memory Efficient**: No temporary string creation or object serialization overhead
+ *
+ * **Use Cases:**
+ * - Form value change detection where only top-level properties matter
+ * - Quick object comparison in performance-critical code paths
+ * - Validation triggers where deep comparison is unnecessary
+ *
+ * **Performance Comparison:**
+ * ```typescript
+ * /// ❌ Slow: JSON.stringify approach
+ * JSON.stringify(obj1) === JSON.stringify(obj2)
+ *
+ * /// ✅ Fast: Direct property comparison
+ * shallowEqual(obj1, obj2)
+ * ```
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @returns true if objects are shallowly equal (same keys and same values by reference)
+ */
+function shallowEqual(obj1, obj2) {
+    if (obj1 === obj2) {
+        return true;
+    }
+    if (obj1 == null || obj2 == null) {
+        return obj1 === obj2;
+    }
+    if (typeof obj1 !== 'object' || typeof obj2 !== 'object') {
+        return obj1 === obj2;
+    }
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    for (const key of keys1) {
+        if (!Object.hasOwn(obj2, key) ||
+            obj1[key] !==
+                obj2[key]) {
+            return false;
+        }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormGroupWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.0", type: FormGroupWrapperComponent, isStandalone: true, selector: "ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper], [ngx-form-group-wrapper], [sc-form-group-wrapper]", inputs: { pendingDebounce: { classPropertyName: "pendingDebounce", publicName: "pendingDebounce", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class.ngx-form-group-wrapper--invalid": "errorDisplay.shouldShowErrors()", "attr.aria-busy": "errorDisplay.isPending() ? 'true' : null" }, classAttribute: "ngx-form-group-wrapper sc-form-group-wrapper" }, exportAs: ["formGroupWrapper", "ngxFormGroupWrapper"], hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0, template: "<div class=\"ngx-form-group-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Keep regions stable in the DOM so IDs are always valid targets.\n  This wrapper does NOT modify descendant controls.\n-->\n<div [id]=\"errorId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.shouldShowErrors() && errorDisplay.errors().length > 0) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"warningId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"pendingId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (showPendingMessage()) {\n    <span aria-hidden=\"true\">Validating\u2026</span>\n  }\n</div>\n", styles: [":host{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+    return true;
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormGroupWrapperComponent, decorators: [{
-            type: Component,
-            args: [{ selector: 'ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper], [ngx-form-group-wrapper], [sc-form-group-wrapper]', exportAs: 'formGroupWrapper, ngxFormGroupWrapper', changeDetection: ChangeDetectionStrategy.OnPush, host: {
-                        class: 'ngx-form-group-wrapper sc-form-group-wrapper',
-                        '[class.ngx-form-group-wrapper--invalid]': 'errorDisplay.shouldShowErrors()',
-                        '[attr.aria-busy]': "errorDisplay.isPending() ? 'true' : null",
-                    }, hostDirectives: [
-                        {
-                            directive: FormErrorDisplayDirective,
-                            inputs: ['errorDisplayMode'],
-                        },
-                    ], template: "<div class=\"ngx-form-group-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Keep regions stable in the DOM so IDs are always valid targets.\n  This wrapper does NOT modify descendant controls.\n-->\n<div [id]=\"errorId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.shouldShowErrors() && errorDisplay.errors().length > 0) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"warningId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"pendingId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (showPendingMessage()) {\n    <span aria-hidden=\"true\">Validating\u2026</span>\n  }\n</div>\n", styles: [":host{display:block}\n"] }]
-        }], propDecorators: { pendingDebounce: [{ type: i0.Input, args: [{ isSignal: true, alias: "pendingDebounce", required: false }] }] } });
-
-let nextUniqueId = 0;
 /**
- * Wires a control container to its error/warning/pending regions.
+ * @internal
+ * Internal utility for deep equality checks.
  *
- * This directive is intended for custom wrappers/components.
- * It composes `FormErrorDisplayDirective` (and thus `FormControlStateDirective`)
- * and applies `aria-invalid` / `aria-describedby` to descendant controls.
+ * **Not intended for external use.** This function is used internally by the library
+ * for form value comparison and change detection. Consider using your own comparison
+ * logic or a library like lodash if you need deep equality checks in your application.
  *
- * It does not render any UI; you can use the generated IDs to render messages.
+ * Fast deep equality check optimized for form values and Angular applications.
+ *
+ * **Why this custom implementation is preferred over alternatives:**
+ *
+ * **vs JSON.stringify():**
+ * - **10-100x faster**: Direct comparison without string serialization overhead
+ * - **Accurate**: Handles Date objects, RegExp, undefined values, and functions correctly
+ * - **Memory efficient**: No temporary string creation or garbage collection pressure
+ * - **Preserves semantics**: Maintains type information during comparison
+ *
+ * **vs structuredClone():**
+ * - **Wrong purpose**: structuredClone creates copies, not comparisons
+ * - **Performance**: Would require cloning both objects just to compare them
+ * - **Memory waste**: Creates unnecessary deep copies, doubling memory usage
+ * - **Still incomplete**: Even after cloning, you'd still need a comparison function
+ *
+ * **vs External libraries (lodash.isEqual, etc.):**
+ * - **Bundle size**: Zero dependencies, smaller application bundles
+ * - **Form-specific**: Optimized for common Angular form data patterns
+ * - **Type safety**: Full TypeScript integration with strict typing
+ * - **Performance**: Tailored algorithms for form value comparison use cases
+ *
+ * **Supported Data Types:**
+ * - Primitives (string, number, boolean, null, undefined, symbol, bigint)
+ * - Arrays (with recursive deep comparison)
+ * - Plain objects (with recursive deep comparison)
+ * - Date objects (by timestamp comparison)
+ * - RegExp objects (by source and flags comparison)
+ * - Set objects (by size and value membership)
+ * - Map objects (by size and key-value pairs)
+ *
+ * **Safety Features:**
+ * - **Circular reference protection**: MaxDepth parameter prevents infinite recursion
+ * - **Type coercion prevention**: Strict type checking before comparison
+ * - **Null safety**: Proper handling of null and undefined values
+ *
+ * **Performance Characteristics:**
+ * ```typescript
+ * /// Performance comparison on typical form objects:
+ * /// JSON.stringify:    ~100ms for complex nested forms
+ * /// fastDeepEqual:     ~1-5ms for the same objects
+ * ///
+ * /// Memory usage:
+ * /// JSON.stringify:    Creates temporary strings (high GC pressure)
+ * /// fastDeepEqual:     Zero allocations during comparison
+ * ```
+ *
+ * **Typical Usage in Forms:**
+ * ```typescript
+ * /// Detect when form values actually change
+ * distinctUntilChanged(fastDeepEqual)
+ *
+ * /// Prevent unnecessary re-renders
+ * if (!fastDeepEqual(oldFormValue, newFormValue)) {
+ *   updateUI();
+ * }
+ * ```
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @param maxDepth - Maximum recursion depth to prevent infinite loops (default: 10)
+ * @returns true if objects are deeply equal by value
  */
-class FormErrorControlDirective {
-    mergeAriaDescribedBy(existing, activeIds) {
-        const existingTokens = (existing ?? '')
-            .split(/\s+/)
-            .map((t) => t.trim())
-            .filter(Boolean);
-        const existingWithoutOwned = existingTokens.filter((t) => !this.ownedDescribedByIds.includes(t));
-        const merged = [...existingWithoutOwned];
-        for (const id of activeIds) {
-            if (!merged.includes(id)) {
-                merged.push(id);
+function fastDeepEqual(obj1, obj2, maxDepth = 10) {
+    if (maxDepth <= 0) {
+        // Fallback to shallow comparison at max depth to prevent infinite recursion
+        return obj1 === obj2;
+    }
+    if (obj1 === obj2) {
+        return true;
+    }
+    if (obj1 == null || obj2 == null) {
+        return obj1 === obj2;
+    }
+    if (typeof obj1 !== typeof obj2) {
+        return false;
+    }
+    if (isPrimitive$1(obj1) || isPrimitive$1(obj2)) {
+        return obj1 === obj2;
+    }
+    // Handle arrays early for performance (common in forms)
+    if (Array.isArray(obj1) !== Array.isArray(obj2)) {
+        return false;
+    }
+    if (Array.isArray(obj1)) {
+        // We know obj2 is also an array here
+        const arr2 = obj2;
+        if (obj1.length !== arr2.length) {
+            return false;
+        }
+        for (let i = 0; i < obj1.length; i++) {
+            if (!fastDeepEqual(obj1[i], arr2[i], maxDepth - 1)) {
+                return false;
             }
         }
-        return merged.length > 0 ? merged.join(' ') : null;
+        return true;
     }
-    constructor() {
-        this.errorDisplay = inject(FormErrorDisplayDirective, {
-            self: true,
-        });
-        this.elementRef = inject((ElementRef));
-        this.destroyRef = inject(DestroyRef);
-        /**
-         * Controls how this directive applies ARIA attributes to descendant controls.
-         *
-         * - `all-controls` (default): apply ARIA attributes to all input/select/textarea descendants.
-         * - `single-control`: apply ARIA attributes only when exactly one control is found.
-         * - `none`: do not mutate descendant controls.
-         */
-        this.ariaAssociationMode = input('all-controls', ...(ngDevMode ? [{ debugName: "ariaAssociationMode" }] : []));
-        /**
-         * Unique ID prefix for this instance.
-         * Use these IDs to render message regions and to support aria-describedby.
-         */
-        this.uniqueId = `ngx-error-control-${nextUniqueId++}`;
-        this.errorId = `${this.uniqueId}-error`;
-        this.warningId = `${this.uniqueId}-warning`;
-        this.pendingId = `${this.uniqueId}-pending`;
-        this.formControls = signal([], ...(ngDevMode ? [{ debugName: "formControls" }] : []));
-        this.contentInitialized = signal(false, ...(ngDevMode ? [{ debugName: "contentInitialized" }] : []));
-        this.mutationObserver = null;
-        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, { showAfter: 500, minimumDisplay: 500 });
-        this.showPendingMessage = this.pendingState.showPendingMessage;
-        /**
-         * aria-describedby value representing the *currently relevant* message regions.
-         */
-        this.ariaDescribedBy = computed(() => {
-            const ids = [];
-            if (this.errorDisplay.shouldShowErrors()) {
-                ids.push(this.errorId);
-            }
-            if (this.errorDisplay.warnings().length > 0) {
-                ids.push(this.warningId);
-            }
-            if (this.showPendingMessage()) {
-                ids.push(this.pendingId);
-            }
-            return ids.length > 0 ? ids.join(' ') : null;
-        }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
-        this.ownedDescribedByIds = [
-            this.errorId,
-            this.warningId,
-            this.pendingId,
-        ];
-        effect(() => {
-            if (!this.contentInitialized())
-                return;
-            const mode = this.ariaAssociationMode();
-            if (mode === 'none')
-                return;
-            const describedBy = this.ariaDescribedBy();
-            const activeIds = describedBy
-                ? describedBy.split(/\s+/).filter(Boolean)
-                : [];
-            const shouldShowErrors = this.errorDisplay.shouldShowErrors();
-            const targets = (() => {
-                const controls = this.formControls();
-                if (mode === 'single-control') {
-                    return controls.length === 1 ? controls : [];
-                }
-                return controls;
-            })();
-            for (const control of targets) {
-                const nextDescribedBy = this.mergeAriaDescribedBy(control.getAttribute('aria-describedby'), activeIds);
-                if (nextDescribedBy) {
-                    control.setAttribute('aria-describedby', nextDescribedBy);
-                }
-                else {
-                    control.removeAttribute('aria-describedby');
-                }
-                if (shouldShowErrors) {
-                    control.setAttribute('aria-invalid', 'true');
-                }
-                else {
-                    control.removeAttribute('aria-invalid');
-                }
-            }
-        });
-        effect(() => {
-            if (!this.contentInitialized())
-                return;
-            const mode = this.ariaAssociationMode();
-            if (mode === 'none') {
-                this.mutationObserver?.disconnect();
-                this.mutationObserver = null;
-                if (this.formControls().length > 0) {
-                    this.formControls.set([]);
-                }
-                return;
-            }
-            this.updateFormControls();
-            if (!this.mutationObserver) {
-                this.mutationObserver = new MutationObserver(() => {
-                    this.updateFormControls();
-                });
-                this.mutationObserver.observe(this.elementRef.nativeElement, {
-                    childList: true,
-                    subtree: true,
-                });
+    // Handle Date objects
+    if (obj1 instanceof Date) {
+        return obj2 instanceof Date && obj1.getTime() === obj2.getTime();
+    }
+    // Handle RegExp objects
+    if (obj1 instanceof RegExp) {
+        return (obj2 instanceof RegExp &&
+            obj1.source === obj2.source &&
+            obj1.flags === obj2.flags);
+    }
+    // Handle Set objects (common in forms)
+    if (obj1 instanceof Set) {
+        if (!(obj2 instanceof Set) || obj1.size !== obj2.size) {
+            return false;
+        }
+        for (const value of obj1) {
+            if (!obj2.has(value)) {
+                return false;
             }
-        });
-        this.destroyRef.onDestroy(() => {
-            this.mutationObserver?.disconnect();
-            this.mutationObserver = null;
-        });
+        }
+        return true;
     }
-    ngAfterContentInit() {
-        this.contentInitialized.set(true);
+    // Handle Map objects (common in forms)
+    if (obj1 instanceof Map) {
+        if (!(obj2 instanceof Map) || obj1.size !== obj2.size) {
+            return false;
+        }
+        for (const [key, value] of obj1) {
+            if (!obj2.has(key) ||
+                !fastDeepEqual(value, obj2.get(key), maxDepth - 1)) {
+                return false;
+            }
+        }
+        return true;
     }
-    ngOnDestroy() {
-        this.mutationObserver?.disconnect();
-        this.mutationObserver = null;
+    // Handle plain objects
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) {
+        return false;
     }
-    updateFormControls() {
-        const controls = this.elementRef.nativeElement.querySelectorAll('input, select, textarea');
-        this.formControls.set(Array.from(controls));
+    for (const key of keys1) {
+        if (!Object.hasOwn(obj2, key) ||
+            !fastDeepEqual(obj1[key], obj2[key], maxDepth - 1)) {
+            return false;
+        }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormErrorControlDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: FormErrorControlDirective, isStandalone: true, selector: "[formErrorControl], [ngxErrorControl]", inputs: { ariaAssociationMode: { classPropertyName: "ariaAssociationMode", publicName: "ariaAssociationMode", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["formErrorControl", "ngxErrorControl"], hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0 }); }
+    return true;
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormErrorControlDirective, decorators: [{
-            type: Directive,
-            args: [{
-                    selector: '[formErrorControl], [ngxErrorControl]',
-                    exportAs: 'formErrorControl, ngxErrorControl',
-                    hostDirectives: [
-                        {
-                            directive: FormErrorDisplayDirective,
-                            inputs: ['errorDisplayMode'],
-                        },
-                    ],
-                }]
-        }], ctorParameters: () => [], propDecorators: { ariaAssociationMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaAssociationMode", required: false }] }] } });
 
 const ROOT_FORM = 'rootForm';
 
@@ -1268,7 +561,7 @@ function mergeValuesAndRawValues(form) {
     mergeRecursive(value, rawValue);
     return value;
 }
-function isPrimitive$1(value) {
+function isPrimitive(value) {
     return (value === null || (typeof value !== 'object' && typeof value !== 'function'));
 }
 /**
@@ -1282,7 +575,7 @@ function isPrimitive$1(value) {
  */
 function cloneDeep(object) {
     // Handle primitives (null, undefined, boolean, string, number, function)
-    if (isPrimitive$1(object)) {
+    if (isPrimitive(object)) {
         return object;
     }
     // Handle Date
@@ -1411,1069 +704,1980 @@ function getAllFormErrors(form) {
     return errors;
 }
 
-const NGX_VEST_FORMS_ERRORS = {
-    EXTRA_PROPERTY: {
-        code: 'NGX-001',
-        message: (path) => `Shape mismatch: Property '${path}' is present in the form value but not defined in the form shape.`,
-    },
-    TYPE_MISMATCH: {
-        code: 'NGX-002',
-        message: (path, expected, actual) => `Type mismatch at '${path}': Expected '${expected}' but got '${actual}'.`,
-    },
-    CONTROL_NOT_FOUND: {
-        code: 'NGX-003',
-        message: (path) => `Control not found: Could not find form control at path '${path}'. Check your [ngModel] name attributes.`,
-    },
-};
-function logWarning(error, ...args) {
-    console.warn(`[${error.code}] ${error.message(...args)}\nCheck your [formShape] input and the initial [formValue].`);
-}
-
 /**
- * Injection token for configurable validation config debounce timing.
- *
- * This token allows you to configure the debounce time for validation config
- * dependencies at the application, route, or component level.
- *
- * @example
- * ```typescript
- * /// Global configuration
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     {
- *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
- *       useValue: 200
- *     }
- *   ]
- * };
+ * Validates a form value against a shape to catch typos in `name` or `ngModelGroup` attributes.
  *
- * /// Per-route configuration
- * {
- *   path: 'checkout',
- *   component: CheckoutComponent,
- *   providers: [
- *     {
- *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
- *       useValue: 50
- *     }
- *   ]
- * }
+ * **What it checks:**
+ * - Extra properties: Keys in formValue that don't exist in shape (likely typos)
+ * - Type mismatches: When formValue has an object but shape expects a primitive
  *
- * /// Per-component override
- * @Component({
- *   providers: [
- *     {
- *       provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN,
- *       useValue: 0 // for testing
- *     }
- *   ]
- * })
- * export class TestFormComponent {}
- * ```
+ * **What it does NOT check:**
+ * - Missing properties: Keys in shape that don't exist in formValue
+ *   (forms build incrementally with `NgxDeepPartial`, and `@if` conditionally renders fields)
  *
- * @default 100ms - Maintains backward compatibility with existing behavior
- */
-const NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN = new InjectionToken('NgxValidationConfigDebounceTime', {
-    providedIn: 'root',
-    factory: () => 100,
-});
-
-/**
- * Type guard to check if a value is a primitive type.
+ * Only runs in development mode.
  *
- * @param value - The value to check
- * @returns true if the value is a primitive (string, number, boolean, null, undefined, symbol, bigint)
+ * @param formVal - The current form value
+ * @param shape - The expected shape (created with `NgxDeepRequired<T>`)
  */
-function isPrimitive(value) {
-    return (value === null || (typeof value !== 'object' && typeof value !== 'function'));
+function validateShape(formVal, shape) {
+    if (isDevMode()) {
+        validateFormValueAgainstShape(formVal, shape);
+    }
 }
 /**
- * @internal
- * Internal utility for shallow equality checks.
- *
- * **Not intended for external use.** This function is used internally by the library
- * for performance-critical operations. Consider using your own comparison logic or
- * a library like lodash if you need shallow equality checks in your application.
- *
- * Optimized shallow equality check for objects.
- *
- * **Why this custom implementation is preferred:**
- * - **Performance**: Direct property comparison is significantly faster than JSON.stringify
- * - **Type Safety**: Handles null/undefined values correctly without serialization issues
- * - **Accuracy**: Doesn't suffer from JSON.stringify limitations (undefined values, functions, symbols)
- * - **Memory Efficient**: No temporary string creation or object serialization overhead
- *
- * **Use Cases:**
- * - Form value change detection where only top-level properties matter
- * - Quick object comparison in performance-critical code paths
- * - Validation triggers where deep comparison is unnecessary
- *
- * **Performance Comparison:**
- * ```typescript
- * /// ❌ Slow: JSON.stringify approach
- * JSON.stringify(obj1) === JSON.stringify(obj2)
- *
- * /// ✅ Fast: Direct property comparison
- * shallowEqual(obj1, obj2)
- * ```
- *
- * @param obj1 - First object to compare
- * @param obj2 - Second object to compare
- * @returns true if objects are shallowly equal (same keys and same values by reference)
+ * Recursively validates form value keys against the shape.
+ * Reports warnings for extra properties and type mismatches.
  */
-function shallowEqual(obj1, obj2) {
-    if (obj1 === obj2) {
-        return true;
-    }
-    if (obj1 == null || obj2 == null) {
-        return obj1 === obj2;
-    }
-    if (typeof obj1 !== 'object' || typeof obj2 !== 'object') {
-        return obj1 === obj2;
-    }
-    const keys1 = Object.keys(obj1);
-    const keys2 = Object.keys(obj2);
-    if (keys1.length !== keys2.length) {
-        return false;
-    }
-    for (const key of keys1) {
-        if (!Object.hasOwn(obj2, key) ||
-            obj1[key] !==
-                obj2[key]) {
-            return false;
+function validateFormValueAgainstShape(formValue, shape, path = '') {
+    for (const key of Object.keys(formValue)) {
+        const value = formValue[key];
+        const fieldPath = path ? `${path}.${key}` : key;
+        // Skip null/undefined values (valid during form initialization)
+        if (value == null) {
+            continue;
+        }
+        // For array items (numeric keys > 0), compare against the first item in shape
+        // since we only define one example item in the shape for arrays
+        const isNumericKey = !isNaN(parseFloat(key));
+        const shapeKey = isNumericKey && parseFloat(key) > 0 ? '0' : key;
+        const shapeValue = shape?.[shapeKey];
+        // Skip Date fields receiving empty strings (common in date picker libraries)
+        if (shapeValue instanceof Date && value === '') {
+            continue;
+        }
+        // Handle object values (recurse into nested objects)
+        if (typeof value === 'object') {
+            // Type mismatch: formValue has object, but shape expects primitive
+            if (!isNumericKey &&
+                (typeof shapeValue !== 'object' || shapeValue === null)) {
+                logWarning(NGX_VEST_FORMS_ERRORS.TYPE_MISMATCH, fieldPath, 'primitive', 'object');
+            }
+            // Recurse into nested object
+            validateFormValueAgainstShape(value, shapeValue ?? {}, fieldPath);
+            continue;
+        }
+        // Extra property: key exists in formValue but not in shape (likely a typo)
+        if (!isNumericKey && shape && !(shapeKey in shape)) {
+            logWarning(NGX_VEST_FORMS_ERRORS.EXTRA_PROPERTY, fieldPath);
         }
     }
-    return true;
 }
+
 /**
- * @internal
- * Internal utility for deep equality checks.
- *
- * **Not intended for external use.** This function is used internally by the library
- * for form value comparison and change detection. Consider using your own comparison
- * logic or a library like lodash if you need deep equality checks in your application.
- *
- * Fast deep equality check optimized for form values and Angular applications.
- *
- * **Why this custom implementation is preferred over alternatives:**
- *
- * **vs JSON.stringify():**
- * - **10-100x faster**: Direct comparison without string serialization overhead
- * - **Accurate**: Handles Date objects, RegExp, undefined values, and functions correctly
- * - **Memory efficient**: No temporary string creation or garbage collection pressure
- * - **Preserves semantics**: Maintains type information during comparison
- *
- * **vs structuredClone():**
- * - **Wrong purpose**: structuredClone creates copies, not comparisons
- * - **Performance**: Would require cloning both objects just to compare them
- * - **Memory waste**: Creates unnecessary deep copies, doubling memory usage
- * - **Still incomplete**: Even after cloning, you'd still need a comparison function
- *
- * **vs External libraries (lodash.isEqual, etc.):**
- * - **Bundle size**: Zero dependencies, smaller application bundles
- * - **Form-specific**: Optimized for common Angular form data patterns
- * - **Type safety**: Full TypeScript integration with strict typing
- * - **Performance**: Tailored algorithms for form value comparison use cases
+ * Duration (in milliseconds) to keep fields marked as "in-progress" after validation.
+ * This prevents immediate re-triggering of bidirectional validations.
+ * Increased from 100ms to 500ms to give validators enough time to complete and propagate.
+ */
+const VALIDATION_IN_PROGRESS_TIMEOUT_MS = 500;
+/**
+ * Main form directive for ngx-vest-forms that bridges Angular template-driven forms with Vest.js validation.
  *
- * **Supported Data Types:**
- * - Primitives (string, number, boolean, null, undefined, symbol, bigint)
- * - Arrays (with recursive deep comparison)
- * - Plain objects (with recursive deep comparison)
- * - Date objects (by timestamp comparison)
- * - RegExp objects (by source and flags comparison)
- * - Set objects (by size and value membership)
- * - Map objects (by size and key-value pairs)
+ * This directive provides:
+ * - **Unidirectional data flow**: Use `[ngModel]` (not `[(ngModel)]`) with `(formValueChange)` for predictable state updates
+ * - **Vest.js integration**: Automatic async validators from Vest suites with field-level optimization
+ * - **Validation dependencies**: Configure cross-field validation triggers via `validationConfig`
+ * - **Form state**: Access validity, errors, and values through the `formState` signal
  *
- * **Safety Features:**
- * - **Circular reference protection**: MaxDepth parameter prevents infinite recursion
- * - **Type coercion prevention**: Strict type checking before comparison
- * - **Null safety**: Proper handling of null and undefined values
+ * @usageNotes
  *
- * **Performance Characteristics:**
- * ```typescript
- * /// Performance comparison on typical form objects:
- * /// JSON.stringify:    ~100ms for complex nested forms
- * /// fastDeepEqual:     ~1-5ms for the same objects
- * ///
- * /// Memory usage:
- * /// JSON.stringify:    Creates temporary strings (high GC pressure)
- * /// fastDeepEqual:     Zero allocations during comparison
+ * ### Basic Usage
+ * ```html
+ * <form ngxVestForm [suite]="validationSuite" (formValueChange)="formValue.set($event)">
+ *   <input name="email" [ngModel]="formValue().email" />
+ * </form>
  * ```
  *
- * **Typical Usage in Forms:**
+ * ### With Validation Dependencies
+ * ```html
+ * <form ngxVestForm [suite]="suite" [validationConfig]="validationConfig">
+ *   <input name="password" [ngModel]="formValue().password" />
+ *   <input name="confirmPassword" [ngModel]="formValue().confirmPassword" />
+ * </form>
+ * ```
  * ```typescript
- * /// Detect when form values actually change
- * distinctUntilChanged(fastDeepEqual)
+ * validationConfig = { 'password': ['confirmPassword'] };
+ * ```
  *
- * /// Prevent unnecessary re-renders
- * if (!fastDeepEqual(oldFormValue, newFormValue)) {
- *   updateUI();
- * }
+ * ### Accessing Form State
+ * ```typescript
+ * vestForm = viewChild.required('vestForm', { read: FormDirective });
+ * isValid = computed(() => this.vestForm().formState().valid);
  * ```
  *
- * @param obj1 - First object to compare
- * @param obj2 - Second object to compare
- * @param maxDepth - Maximum recursion depth to prevent infinite loops (default: 10)
- * @returns true if objects are deeply equal by value
+ * @see {@link https://github.com/ngx-vest-forms/ngx-vest-forms} for full documentation
+ * @publicApi
  */
-function fastDeepEqual(obj1, obj2, maxDepth = 10) {
-    if (maxDepth <= 0) {
-        // Fallback to shallow comparison at max depth to prevent infinite recursion
-        return obj1 === obj2;
+class FormDirective {
+    // Track last linked value to prevent unnecessary updates
+    #lastLinkedValue;
+    #lastSyncedFormValue;
+    #lastSyncedModelValue;
+    // Internal signal tracking form value changes via statusChanges
+    #value;
+    /**
+     * LinkedSignal that computes form values from Angular form state.
+     * This eliminates timing issues with the previous dual-effect pattern.
+     */
+    #formValueSignal;
+    /**
+     * Track the Angular form status as a signal for advanced status flags
+     */
+    #statusSignal;
+    constructor() {
+        this.ngForm = inject(NgForm, { self: true });
+        this.destroyRef = inject(DestroyRef);
+        this.cdr = inject(ChangeDetectorRef);
+        this.configDebounceTime = inject(NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN);
+        /**
+         * 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.
+         */
+        this.fieldWarnings = signal(new Map(), ...(ngDevMode ? [{ debugName: "fieldWarnings" }] : []));
+        // Track last linked value to prevent unnecessary updates
+        this.#lastLinkedValue = null;
+        this.#lastSyncedFormValue = null;
+        this.#lastSyncedModelValue = null;
+        // Internal signal tracking form value changes via statusChanges
+        this.#value = toSignal(this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status)), { initialValue: this.ngForm.form.status });
+        /**
+         * LinkedSignal that computes form values from Angular form state.
+         * This eliminates timing issues with the previous dual-effect pattern.
+         */
+        this.#formValueSignal = linkedSignal(() => {
+            // Track form value changes
+            this.#value();
+            const raw = mergeValuesAndRawValues(this.ngForm.form);
+            if (Object.keys(this.ngForm.form.controls).length > 0) {
+                this.#lastLinkedValue = raw;
+                return raw;
+            }
+            else if (this.#lastLinkedValue !== null) {
+                return this.#lastLinkedValue;
+            }
+            return null;
+        }, ...(ngDevMode ? [{ debugName: "#formValueSignal" }] : []));
+        /**
+         * Track the Angular form status as a signal for advanced status flags
+         */
+        this.#statusSignal = toSignal(this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status)), { initialValue: this.ngForm.form.status });
+        /**
+         * Computed signal for form state with validity and errors.
+         * Used by templates and tests as vestForm.formState().valid/errors
+         *
+         * Uses custom equality function to prevent unnecessary recalculations
+         * when form status changes but actual values/errors remain the same.
+         */
+        this.formState = computed(() => {
+            // Tie to status signal to ensure recomputation on validation changes
+            this.#statusSignal();
+            return {
+                valid: this.ngForm.form.valid,
+                errors: getAllFormErrors(this.ngForm.form),
+                value: this.#formValueSignal(),
+            };
+        }, { ...(ngDevMode ? { debugName: "formState" } : {}), equal: (a, b) => {
+                // Fast path: reference equality
+                if (a === b)
+                    return true;
+                // Null/undefined check
+                if (!a || !b)
+                    return false;
+                // Deep equality check for form state properties
+                return (a.valid === b.valid &&
+                    fastDeepEqual(a.errors, b.errors) &&
+                    fastDeepEqual(a.value, b.value));
+            } });
+        /**
+         * The value of the form, this is needed for the validation part.
+         * Using input() here because two-way binding is provided via formValueChange output.
+         * In the minimal core directive (form-core.directive.ts), this would be model() instead.
+         */
+        this.formValue = input(null, ...(ngDevMode ? [{ debugName: "formValue" }] : []));
+        /**
+         * Static vest suite that will be used to feed our angular validators.
+         * Accepts both NgxVestSuite and NgxTypedVestSuite through compatible type signatures.
+         * NgxTypedVestSuite<T> is assignable to NgxVestSuite<T> due to bivariance and
+         * FormFieldName<T> (string literal union) being assignable to string.
+         */
+        this.suite = input(null, ...(ngDevMode ? [{ debugName: "suite" }] : []));
+        /**
+         * The shape of our form model. This is a deep required version of the form model
+         * The goal is to add default values to the shape so when the template-driven form
+         * contains values that shouldn't be there (typo's) that the developer gets run-time
+         * errors in dev mode
+         */
+        this.formShape = input(null, ...(ngDevMode ? [{ debugName: "formShape" }] : []));
+        /**
+         * Updates the validation config which is a dynamic object that will be used to
+         * trigger validations on the dependant fields
+         * Eg: ```typescript
+         * validationConfig = {
+         *     'passwords.password': ['passwords.confirmPassword']
+         * }
+         * ```
+         *
+         * This will trigger the updateValueAndValidity on passwords.confirmPassword every time the passwords.password gets a new value
+         *
+         * @param v
+         */
+        this.validationConfig = input(null, ...(ngDevMode ? [{ debugName: "validationConfig" }] : []));
+        this.pending$ = this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v === 'PENDING'), distinctUntilChanged());
+        /**
+         * Emits every time the form status changes in a state
+         * that is not PENDING
+         * We need this to assure that the form is in 'idle' state
+         */
+        this.idle$ = this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v !== 'PENDING'), distinctUntilChanged());
+        /**
+         * Triggered as soon as the form value changes
+         * It also contains the disabled values (raw values)
+         *
+         * Cleanup is handled automatically by the directive when it's destroyed.
+         */
+        this.formValueChange = outputFromObservable(this.ngForm.form.events.pipe(filter((v) => v instanceof ValueChangeEvent), map((v) => v.value), distinctUntilChanged((prev, curr) => {
+            // Use efficient deep equality instead of JSON.stringify for better performance
+            return fastDeepEqual(prev, curr);
+        }), map(() => mergeValuesAndRawValues(this.ngForm.form)), takeUntilDestroyed(this.destroyRef)));
+        /**
+         * 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.
+         */
+        this.errorsChange = outputFromObservable(merge(
+        // Status change events (non-PENDING) - emit immediately
+        this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v !== 'PENDING')), 
+        // Submit events - wait for async validation to complete before emitting
+        this.ngForm.ngSubmit.pipe(switchMap(() => {
+            // If form is PENDING (async validation in progress), wait for it to complete
+            if (this.ngForm.form.status === 'PENDING') {
+                return this.ngForm.form.statusChanges.pipe(filter((status) => status !== 'PENDING'), take(1));
+            }
+            // Form not pending, emit immediately
+            return of(this.ngForm.form.status);
+        }))).pipe(map(() => getAllFormErrors(this.ngForm.form)), takeUntilDestroyed(this.destroyRef)));
+        /**
+         * Triggered as soon as the form becomes dirty
+         *
+         * Cleanup is handled automatically by the directive when it's destroyed.
+         */
+        this.dirtyChange = outputFromObservable(this.ngForm.form.events.pipe(filter((v) => v instanceof PristineChangeEvent), map((v) => !v.pristine), startWith(this.ngForm.form.dirty), distinctUntilChanged(), takeUntilDestroyed(this.destroyRef)));
+        /**
+         * Fired when the status of the root form changes.
+         */
+        this.statusChanges$ = this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status), distinctUntilChanged());
+        /**
+         * Triggered When the form becomes valid but waits until the form is idle
+         *
+         * Cleanup is handled automatically by the directive when it's destroyed.
+         */
+        this.validChange = outputFromObservable(this.statusChanges$.pipe(filter((e) => e === 'VALID' || e === 'INVALID'), map((v) => v === 'VALID'), distinctUntilChanged(), takeUntilDestroyed(this.destroyRef)));
+        /**
+         * Track validation in progress to prevent circular triggering (Issue #19)
+         */
+        this.validationInProgress = new Set();
+        this.destroyRef.onDestroy(() => {
+            this.fieldWarnings.set(new Map());
+        });
+        /**
+         * Trigger shape validations if the form gets updated
+         * This is how we can throw run-time errors
+         */
+        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
+         */
+        this.ngForm.ngSubmit
+            .pipe(takeUntilDestroyed(this.destroyRef))
+            .subscribe(() => {
+            this.ngForm.form.markAllAsTouched();
+        });
+        /**
+         * Single bidirectional synchronization effect using linkedSignal.
+         * Uses proper deep comparison and change tracking for correct sync direction.
+         * Note: formValue is read-only input(), so we emit changes via formValueChange output.
+         */
+        effect(() => {
+            const formValue = this.#formValueSignal();
+            const modelValue = this.formValue();
+            // Skip if either is null
+            if (!formValue && !modelValue)
+                return;
+            // Compute change flags first
+            const formChanged = !fastDeepEqual(formValue, this.#lastSyncedFormValue);
+            const modelChanged = !fastDeepEqual(modelValue, this.#lastSyncedModelValue);
+            // Early return if nothing changed
+            if (!formChanged && !modelChanged) {
+                return;
+            }
+            if (formChanged && !modelChanged) {
+                // Form was modified by user -> form wins
+                // Note: We can't call this.formValue.set() since it's an input()
+                // The formValueChange output will emit the new value
+                // Use untracked() to avoid infinite loops - we're updating tracking state here
+                untracked(() => {
+                    this.#lastSyncedFormValue = formValue;
+                    this.#lastSyncedModelValue = formValue;
+                });
+            }
+            else if (modelChanged && !formChanged) {
+                // Model was modified programmatically -> model wins
+                // Use untracked() to avoid infinite loops - we're updating tracking state here
+                untracked(() => {
+                    // Update form controls with new model values
+                    if (modelValue) {
+                        // IMPORTANT: Use root patchValue instead of per-key setValue.
+                        // - Supports nested objects (ngModelGroup) without throwing when partial objects are provided.
+                        // - patchValue ignores missing controls/keys, which is compatible with DeepPartial form models.
+                        // - emitEvent:false prevents feedback loops; validation still updates internally.
+                        this.ngForm.form.patchValue(modelValue, { emitEvent: false });
+                    }
+                    this.#lastSyncedFormValue = modelValue;
+                    this.#lastSyncedModelValue = modelValue;
+                });
+            }
+            else if (formChanged && modelChanged) {
+                // Both form and model changed simultaneously
+                // Check if they changed to the same value (synchronized change) or different values (conflict)
+                const valuesEqual = fastDeepEqual(formValue, modelValue);
+                if (valuesEqual) {
+                    // Both changed to the same value - this is a synchronized change, not a conflict
+                    // Just update tracking to acknowledge the change
+                    untracked(() => {
+                        this.#lastSyncedFormValue = formValue;
+                        this.#lastSyncedModelValue = formValue;
+                    });
+                }
+                else {
+                    // Both changed to different values - this is a true conflict
+                    // This is an edge case that should rarely happen in practice.
+                    // We intentionally do nothing here to avoid breaking the Angular event flow.
+                    // The form will continue with its current values, and validation will run normally.
+                    // The next change (either form or model) will trigger proper synchronization.
+                }
+            }
+        });
+        // Set up validation config reactively
+        this.#setupValidationConfig();
     }
-    if (obj1 === obj2) {
-        return true;
+    /**
+     * Manually trigger form validation update.
+     *
+     * This is useful when form structure changes but no control values change,
+     * which means validation state might be stale. This method forces a re-evaluation
+     * of all form validators and updates the form validity state.
+     *
+     * **IMPORTANT: This method validates ALL form fields by design.**
+     * This is intentional for structure changes as conditional validators may now
+     * apply to different fields, requiring a complete validation refresh.
+     *
+     * **CRITICAL: This method does NOT mark fields as touched or show errors.**
+     * It only re-runs validation logic. To show all errors (e.g., on submit),
+     * use `markAllAsTouched()` instead or in combination.
+     *
+     * **When to use each:**
+     * - `triggerFormValidation()` - Re-run validation when structure changes
+     * - `markAllAsTouched()` - Show all errors to user (e.g., on submit)
+     * - Both together - Rare, only if structure changed AND you want to show errors
+     *
+     * **Note on form submission:**
+     * When using the default error display mode (`on-blur-or-submit`), you typically
+     * don't need to call this method on submit. The form directive automatically marks
+     * all fields as touched on `ngSubmit`, and errors will display automatically.
+     * Only use this method when form structure changes without value changes.
+     *
+     * **Use Cases:**
+     * - Conditionally showing/hiding form controls based on other field values
+     * - Adding or removing form controls dynamically
+     * - Switching between different form layouts where validation requirements change
+     * - Any scenario where form structure changes but no ValueChangeEvent is triggered
+     *
+     * **Example:**
+     * When switching from a form with required input fields to one with only informational content,
+     * the form should become valid, but this won't happen automatically
+     * when no value changes occur (e.g., switching from input fields to informational content).
+     *
+     * **Performance Note:**
+     * This method calls `updateValueAndValidity({ emitEvent: true })` on the root form,
+     * which validates all form controls. For large forms, consider if more granular
+     * validation updates are possible.
+     *
+     * @example
+     * ```typescript
+     * /// After changing form structure
+     * onProcedureTypeChange(newType: string) {
+     *   this.procedureType.set(newType);
+     *   /// Structure changed but no control values changed
+     *   this.formDirective.triggerFormValidation();
+     * }
+     *
+     * /// For submit with multiple forms (show all errors)
+     * submitAll() {
+     *   // Mark all as touched to show errors
+     *   this.form1Ref().markAllAsTouched();
+     *   this.form2Ref().markAllAsTouched();
+     *   // Only needed if structure changed without value changes
+     *   // this.form1Ref().triggerFormValidation();
+     *   // this.form2Ref().triggerFormValidation();
+     * }
+     * ```
+     */
+    triggerFormValidation(path) {
+        if (path) {
+            const control = this.ngForm.form.get(path);
+            if (control) {
+                control.updateValueAndValidity({ emitEvent: true });
+            }
+            else if (isDevMode()) {
+                logWarning(NGX_VEST_FORMS_ERRORS.CONTROL_NOT_FOUND, path);
+            }
+        }
+        else {
+            // Update all form controls validity which will trigger all form events
+            this.ngForm.form.updateValueAndValidity({ emitEvent: true });
+        }
     }
-    if (obj1 == null || obj2 == null) {
-        return obj1 === obj2;
+    /**
+     * Convenience method to mark all form controls as touched.
+     *
+     * This is useful for showing all validation errors at once, typically when
+     * the user clicks a submit button. When a field is marked as touched,
+     * the error display logic (based on `errorDisplayMode`) will show its errors.
+     *
+     * **Note on automatic behavior:**
+     * When using the default error display mode (`on-blur-or-submit`), you typically
+     * don't need to call this method manually for regular form submissions. The form
+     * directive automatically marks all fields as touched on `ngSubmit`, so errors
+     * will display automatically when the user submits the form.
+     *
+     * **When to use this method:**
+     * - Multiple forms with a single submit button (forms without their own submit)
+     * - Programmatic form submission without triggering `ngSubmit`
+     * - Custom validation flows outside the normal submit process
+     *
+     * **Note:** This method only marks fields as touched—it does NOT re-run validation.
+     * If you also need to re-run validation (e.g., after structure changes), call
+     * `triggerFormValidation()` as well.
+     *
+     * @example
+     * ```typescript
+     * /// Standard form submission - NO need to call markAllAsTouched()
+     * /// The directive handles this automatically on ngSubmit
+     * <form ngxVestForm (ngSubmit)="save()">
+     *   <button type="submit">Submit</button>
+     * </form>
+     *
+     * /// Multiple forms with one submit button
+     * submitAll() {
+     *   this.form1().markAllAsTouched();
+     *   this.form2().markAllAsTouched();
+     *   if (this.form1().formState().valid && this.form2().formState().valid) {
+     *     /// Submit all forms
+     *   }
+     * }
+     * ```
+     */
+    markAllAsTouched() {
+        this.ngForm.form.markAllAsTouched();
     }
-    if (typeof obj1 !== typeof obj2) {
-        return false;
+    /**
+     * Resets the form to a pristine, untouched state with optional new values.
+     *
+     * This method properly resets the form by:
+     * 1. Resetting Angular's underlying NgForm with the provided value
+     * 2. Clearing the bidirectional sync tracking state
+     * 3. Forcing a form validity update to clear any stale validation errors
+     *
+     * **Why this method exists:**
+     * When using the pattern `formValue.set({})` to reset a form, there can be a timing
+     * issue where the form controls in the DOM still hold their old values while the
+     * signal has already been updated. This creates a conflict in the bidirectional
+     * sync logic, requiring workarounds like calling `formValue.set({})` twice with
+     * a setTimeout. This method provides a proper solution by:
+     * - Calling Angular's `NgForm.resetForm()` which properly clears all controls
+     * - Clearing the internal sync tracking state to avoid stale comparisons
+     * - Triggering a form validity update to ensure validation state is current
+     *
+     * **Usage:**
+     * Instead of the double-set workaround:
+     * ```typescript
+     * // ❌ Old workaround (avoid)
+     * reset(): void {
+     *   this.formValue.set({});
+     *   setTimeout(() => this.formValue.set({}), 0);
+     * }
+     *
+     * // ✅ Preferred approach
+     * vestForm = viewChild.required('vestForm', { read: FormDirective });
+     * reset(): void {
+     *   this.formValue.set({});
+     *   this.vestForm().resetForm();
+     * }
+     * ```
+     *
+     * **With new values:**
+     * ```typescript
+     * // Reset and set new initial values
+     * resetWithDefaults(): void {
+     *   const defaults = { firstName: '', lastName: '', age: 18 };
+     *   this.formValue.set(defaults);
+     *   this.vestForm().resetForm(defaults);
+     * }
+     * ```
+     *
+     * @param value - Optional new value to reset the form to. If not provided,
+     *                resets to empty/default values.
+     *
+     * @see {@link markAllAsTouched} for showing validation errors
+     * @see {@link triggerFormValidation} for re-running validation without reset
+     */
+    resetForm(value) {
+        // Reset Angular's form to clear all controls and mark as pristine/untouched
+        this.ngForm.resetForm(value ?? undefined);
+        // Clear any stored warnings to avoid stale messages after reset
+        this.fieldWarnings.set(new Map());
+        // Clear the bidirectional sync tracking state so the next formValue change
+        // is treated as a model change (not a conflict with stale form values)
+        this.#lastSyncedFormValue = null;
+        this.#lastSyncedModelValue = null;
+        this.#lastLinkedValue = null;
+        // Force change detection to ensure DOM updates are reflected
+        // Note: This is still needed even with signals because we're modifying NgForm
+        // (reactive forms), not signals. The formValue signal updates happen in the
+        // consumer component. detectChanges() ensures NgForm's reset is reflected in
+        // the DOM before we update validity.
+        this.cdr.detectChanges();
+        // Trigger validation update to clear any stale errors
+        // Now synchronous since detectChanges() has flushed DOM updates
+        this.ngForm.form.updateValueAndValidity({ emitEvent: true });
     }
-    if (isPrimitive(obj1) || isPrimitive(obj2)) {
-        return obj1 === obj2;
+    /**
+     * 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.
+     */
+    createAsyncValidator(field, validationOptions) {
+        const suite = this.suite();
+        if (!suite)
+            return () => of(null);
+        return (control) => {
+            const model = mergeValuesAndRawValues(this.ngForm.form);
+            // Targeted snapshot with candidate value injected at path
+            // mergeValuesAndRawValues already returns a deep clone (via structuredClone),
+            // so we can modify it directly without affecting the form state.
+            const snapshot = model;
+            setValueAtPath(snapshot, field, control.value);
+            // Use timer() instead of ReplaySubject for proper debouncing
+            return timer(validationOptions.debounceTime ?? 0).pipe(map(() => snapshot), switchMap((snap) => new Observable((observer) => {
+                try {
+                    // Cast to NgxVestSuite to accept string field parameter
+                    // Both NgxVestSuite and NgxTypedVestSuite work with string at runtime
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    suite(snap, field).done((result) => {
+                        const errors = result.getErrors()[field];
+                        const warnings = result.getWarnings()[field];
+                        // Store warnings in the fieldWarnings signal for access by control wrappers.
+                        // This is necessary because Angular marks a field as invalid when control.errors !== null.
+                        // By storing warnings separately, fields can remain valid while still displaying warnings.
+                        this.fieldWarnings.update((map) => {
+                            const newMap = new Map(map);
+                            if (warnings?.length) {
+                                newMap.set(field, warnings);
+                            }
+                            else {
+                                newMap.delete(field);
+                            }
+                            return newMap;
+                        });
+                        // Build the validation result:
+                        // - Errors exist → return { errors, warnings? } (field invalid, Angular shows ng-invalid)
+                        // - Only warnings → return null (field valid, warnings accessed via fieldWarnings signal)
+                        // - Neither → return null (field valid)
+                        //
+                        // When errors exist, we also include warnings in control.errors for backwards compatibility
+                        // with code that reads warnings from control.errors.warnings.
+                        const out = errors?.length
+                            ? {
+                                errors,
+                                ...(warnings?.length && { warnings }),
+                            }
+                            : null;
+                        // CRITICAL: Ensure DOM validity classes update for OnPush components.
+                        //
+                        // Angular's template-driven forms update `ng-valid`/`ng-invalid` host classes
+                        // during change detection. When async validation completes, there may be no
+                        // follow-up change detection pass for OnPush hosts, leaving the DOM in a stale
+                        // visual state (even though the control status has updated).
+                        //
+                        // We schedule a detectChanges() on the next microtask to avoid calling it
+                        // synchronously inside Angular's own validation pipeline.
+                        queueMicrotask(() => {
+                            try {
+                                this.cdr.detectChanges();
+                            }
+                            catch {
+                                // Fallback: mark for check when immediate detectChanges isn't safe.
+                                // This keeps behavior resilient in edge cases.
+                                this.cdr.markForCheck();
+                            }
+                        });
+                        observer.next(out);
+                        observer.complete();
+                    });
+                }
+                catch {
+                    observer.next({ vestInternalError: 'Validation failed' });
+                    observer.complete();
+                }
+            })), catchError(() => of({ vestInternalError: 'Validation failed' })), take(1));
+        };
     }
-    // Handle arrays early for performance (common in forms)
-    if (Array.isArray(obj1) !== Array.isArray(obj2)) {
-        return false;
+    /**
+     * Set up validation config reactively using v2 pattern with toObservable + switchMap.
+     * This provides automatic cleanup when config changes.
+     */
+    #setupValidationConfig() {
+        const form = this.ngForm.form;
+        toObservable(this.validationConfig)
+            .pipe(distinctUntilChanged(), switchMap((config) => {
+            // Cast to the expected type for the helper method
+            const typedConfig = config;
+            return this.#createValidationStreams(form, typedConfig);
+        }), takeUntilDestroyed(this.destroyRef))
+            .subscribe();
     }
-    if (Array.isArray(obj1)) {
-        // We know obj2 is also an array here
-        const arr2 = obj2;
-        if (obj1.length !== arr2.length) {
-            return false;
-        }
-        for (let i = 0; i < obj1.length; i++) {
-            if (!fastDeepEqual(obj1[i], arr2[i], maxDepth - 1)) {
-                return false;
-            }
+    /**
+     * Creates validation streams for the provided configuration.
+     * Returns EMPTY if config is null/undefined, otherwise merges all trigger field streams.
+     *
+     * @param form - The NgForm instance
+     * @param config - The validation configuration mapping trigger fields to dependent fields
+     * @returns Observable that emits when any trigger field changes and dependent fields need validation
+     */
+    #createValidationStreams(form, config) {
+        if (!config) {
+            this.validationInProgress.clear();
+            return EMPTY;
         }
-        return true;
-    }
-    // Handle Date objects
-    if (obj1 instanceof Date) {
-        return obj2 instanceof Date && obj1.getTime() === obj2.getTime();
-    }
-    // Handle RegExp objects
-    if (obj1 instanceof RegExp) {
-        return (obj2 instanceof RegExp &&
-            obj1.source === obj2.source &&
-            obj1.flags === obj2.flags);
+        const streams = Object.keys(config).map((triggerField) => {
+            const dependents = config[triggerField] || [];
+            return this.#createTriggerStream(form, triggerField, dependents);
+        });
+        return streams.length > 0 ? merge(...streams) : EMPTY;
     }
-    // Handle Set objects (common in forms)
-    if (obj1 instanceof Set) {
-        if (!(obj2 instanceof Set) || obj1.size !== obj2.size) {
-            return false;
-        }
-        for (const value of obj1) {
-            if (!obj2.has(value)) {
-                return false;
-            }
-        }
-        return true;
+    /**
+     * Creates a stream for a single trigger field that revalidates its dependent fields.
+     *
+     * This method handles:
+     * 1. Waiting for the trigger control to exist in the form (for @if scenarios)
+     * 2. Listening to value changes with debouncing
+     * 3. Waiting for form to be idle before triggering dependents
+     * 4. Waiting for all dependent controls to exist
+     * 5. Updating dependent field validity with loop prevention
+     * 6. Touch state propagation from trigger to dependents
+     *
+     * @param form - The NgForm instance
+     * @param triggerField - Field path that triggers validation (e.g., 'password')
+     * @param dependents - Array of dependent field paths to revalidate (e.g., ['confirmPassword'])
+     * @returns Observable that completes after dependent fields are validated
+     */
+    #createTriggerStream(form, triggerField, dependents) {
+        // Wait for trigger control to exist, then stop listening (take(1) prevents feedback loops)
+        const triggerControl$ = form.statusChanges.pipe(startWith(form.status), map(() => form.get(triggerField)), filter((c) => !!c), 
+        // CRITICAL: take(1) to stop listening after control is found
+        // Without this, the pipeline continues to listen to statusChanges,
+        // creating a feedback loop where validation triggers re-trigger the pipeline
+        take(1));
+        return triggerControl$.pipe(switchMap((control) => {
+            return control.valueChanges.pipe(
+            // CRITICAL: Filter out changes when this field is being validated by another field's config
+            // This prevents circular triggers in bidirectional validationConfig
+            filter(() => !this.validationInProgress.has(triggerField)), debounceTime(this.configDebounceTime), switchMap(() => {
+                return this.#waitForFormIdle(form, control);
+            }), switchMap(() => this.#waitForDependentControls(form, dependents, control)), tap(() => this.#updateDependentFields(form, control, triggerField, dependents)));
+        }));
     }
-    // Handle Map objects (common in forms)
-    if (obj1 instanceof Map) {
-        if (!(obj2 instanceof Map) || obj1.size !== obj2.size) {
-            return false;
-        }
-        for (const [key, value] of obj1) {
-            if (!obj2.has(key) ||
-                !fastDeepEqual(value, obj2.get(key), maxDepth - 1)) {
-                return false;
-            }
+    /**
+     * Waits for the form to reach a non-PENDING state before proceeding.
+     * This prevents validation race conditions where dependent field validation
+     * triggers while the trigger field's validation is still running.
+     *
+     * If the form stays PENDING for longer than 2 seconds (e.g., slow async validators),
+     * proceeds anyway to prevent blocking the validation pipeline.
+     *
+     * @param form - The NgForm instance
+     * @param control - The trigger control to pass through
+     * @returns Observable that emits the control once form is idle or timeout
+     */
+    #waitForFormIdle(form, control) {
+        // If form is already non-PENDING, return immediately
+        if (form.status !== 'PENDING') {
+            return of(control);
         }
-        return true;
-    }
-    // Handle plain objects
-    const keys1 = Object.keys(obj1);
-    const keys2 = Object.keys(obj2);
-    if (keys1.length !== keys2.length) {
-        return false;
+        // Form is PENDING, wait for it to become idle
+        const idle$ = form.statusChanges.pipe(filter((s) => s !== 'PENDING'), take(1));
+        const timeout$ = timer(2000);
+        return race(idle$, timeout$).pipe(map(() => control));
     }
-    for (const key of keys1) {
-        if (!Object.hasOwn(obj2, key) ||
-            !fastDeepEqual(obj1[key], obj2[key], maxDepth - 1)) {
-            return false;
+    /**
+     * Waits for all dependent controls to exist in the form.
+     * This handles @if scenarios where controls are conditionally rendered.
+     *
+     * @param form - The NgForm instance
+     * @param dependents - Array of dependent field paths
+     * @param control - The trigger control to pass through
+     * @returns Observable that emits the control once all dependents exist
+     */
+    #waitForDependentControls(form, dependents, control) {
+        const allDependentsExist = dependents.every((depField) => !!form.get(depField));
+        if (allDependentsExist) {
+            return of(control);
         }
+        // Wait for dependent controls to be added to the form
+        return form.statusChanges.pipe(startWith(form.status), filter(() => dependents.every((depField) => !!form.get(depField))), take(1), map(() => control));
     }
-    return true;
-}
-
-/**
- * Validates a form value against a shape to catch typos in `name` or `ngModelGroup` attributes.
- *
- * **What it checks:**
- * - Extra properties: Keys in formValue that don't exist in shape (likely typos)
- * - Type mismatches: When formValue has an object but shape expects a primitive
- *
- * **What it does NOT check:**
- * - Missing properties: Keys in shape that don't exist in formValue
- *   (forms build incrementally with `NgxDeepPartial`, and `@if` conditionally renders fields)
- *
- * Only runs in development mode.
- *
- * @param formVal - The current form value
- * @param shape - The expected shape (created with `NgxDeepRequired<T>`)
- */
-function validateShape(formVal, shape) {
-    if (isDevMode()) {
-        validateFormValueAgainstShape(formVal, shape);
-    }
-}
-/**
- * Recursively validates form value keys against the shape.
- * Reports warnings for extra properties and type mismatches.
- */
-function validateFormValueAgainstShape(formValue, shape, path = '') {
-    for (const key of Object.keys(formValue)) {
-        const value = formValue[key];
-        const fieldPath = path ? `${path}.${key}` : key;
-        // Skip null/undefined values (valid during form initialization)
-        if (value == null) {
-            continue;
-        }
-        // For array items (numeric keys > 0), compare against the first item in shape
-        // since we only define one example item in the shape for arrays
-        const isNumericKey = !isNaN(parseFloat(key));
-        const shapeKey = isNumericKey && parseFloat(key) > 0 ? '0' : key;
-        const shapeValue = shape?.[shapeKey];
-        // Skip Date fields receiving empty strings (common in date picker libraries)
-        if (shapeValue instanceof Date && value === '') {
-            continue;
-        }
-        // Handle object values (recurse into nested objects)
-        if (typeof value === 'object') {
-            // Type mismatch: formValue has object, but shape expects primitive
-            if (!isNumericKey &&
-                (typeof shapeValue !== 'object' || shapeValue === null)) {
-                logWarning(NGX_VEST_FORMS_ERRORS.TYPE_MISMATCH, fieldPath, 'primitive', 'object');
+    /**
+     * Updates validation for all dependent fields.
+     *
+     * Handles:
+     * - Touch state propagation (mark dependents touched when trigger is touched)
+     * - Loop prevention via validationInProgress set
+     * - Silent validation (emitEvent: false) to prevent feedback loops
+     *
+     * @param form - The NgForm instance
+     * @param control - The trigger control
+     * @param triggerField - Field path of the trigger
+     * @param dependents - Array of dependent field paths to update
+     */
+    #updateDependentFields(form, control, triggerField, dependents) {
+        // Mark trigger field as in-progress to prevent it from being re-triggered
+        this.validationInProgress.add(triggerField);
+        for (const depField of dependents) {
+            const dependentControl = form.get(depField);
+            if (!dependentControl) {
+                continue;
+            }
+            // Only validate if not already in progress (prevents bidirectional loops)
+            if (!this.validationInProgress.has(depField)) {
+                // CRITICAL: Mark the dependent field as in-progress BEFORE calling updateValueAndValidity
+                // This prevents the dependent field's valueChanges from triggering its own validationConfig
+                this.validationInProgress.add(depField);
+                // Propagate touch state BEFORE validation to avoid duplicate class updates
+                // markAsTouched() triggers change detection, so we do it once before updateValueAndValidity
+                if (control.touched && !dependentControl.touched) {
+                    dependentControl.markAsTouched({ onlySelf: true });
+                }
+                // emitEvent: true is REQUIRED for async validators to actually run
+                // The validationInProgress Set prevents infinite loops:
+                // 1. Field A changes → triggers validation on dependent field B
+                // 2. B is added to validationInProgress Set
+                // 3. B's statusChanges emits → #handleValueChange checks validationInProgress
+                // 4. Since B is in validationInProgress, its validationConfig is not triggered
+                // 5. After 500ms timeout, B is removed from validationInProgress
+                // This way:
+                // - Async validators CAN run (emitEvent: true)
+                // - BUT circular triggers are prevented (validationInProgress check)
+                dependentControl.updateValueAndValidity({
+                    onlySelf: true,
+                    emitEvent: true, // Changed from false - REQUIRED for validators to run!
+                });
+                // CRITICAL: Force immediate change detection for OnPush components
+                // updateValueAndValidity updates the control's status, but doesn't automatically
+                // trigger change detection. Components using OnPush won't see the ng-invalid class
+                // update in the DOM without this. Using detectChanges() instead of markForCheck()
+                // to force immediate synchronous update rather than waiting for next CD cycle.
+                this.cdr.detectChanges();
             }
-            // Recurse into nested object
-            validateFormValueAgainstShape(value, shapeValue ?? {}, fieldPath);
-            continue;
-        }
-        // Extra property: key exists in formValue but not in shape (likely a typo)
-        if (!isNumericKey && shape && !(shapeKey in shape)) {
-            logWarning(NGX_VEST_FORMS_ERRORS.EXTRA_PROPERTY, fieldPath);
         }
+        // Keep fields marked as in-progress for a short time to prevent immediate re-triggering
+        // Use setTimeout to ensure async validators have time to complete before allowing new triggers
+        setTimeout(() => {
+            this.validationInProgress.delete(triggerField);
+            for (const depField of dependents) {
+                this.validationInProgress.delete(depField);
+            }
+        }, VALIDATION_IN_PROGRESS_TIMEOUT_MS);
     }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: FormDirective, isStandalone: true, selector: "form[scVestForm], form[ngxVestForm]", inputs: { formValue: { classPropertyName: "formValue", publicName: "formValue", isSignal: true, isRequired: false, transformFunction: null }, suite: { classPropertyName: "suite", publicName: "suite", isSignal: true, isRequired: false, transformFunction: null }, formShape: { classPropertyName: "formShape", publicName: "formShape", isSignal: true, isRequired: false, transformFunction: null }, validationConfig: { classPropertyName: "validationConfig", publicName: "validationConfig", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { formValueChange: "formValueChange", errorsChange: "errorsChange", dirtyChange: "dirtyChange", validChange: "validChange" }, exportAs: ["scVestForm", "ngxVestForm"], ngImport: i0 }); }
 }
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: 'form[scVestForm], form[ngxVestForm]',
+                    exportAs: 'scVestForm, ngxVestForm',
+                }]
+        }], ctorParameters: () => [], propDecorators: { formValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "formValue", required: false }] }], suite: [{ type: i0.Input, args: [{ isSignal: true, alias: "suite", required: false }] }], formShape: [{ type: i0.Input, args: [{ isSignal: true, alias: "formShape", required: false }] }], validationConfig: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationConfig", required: false }] }], formValueChange: [{ type: i0.Output, args: ["formValueChange"] }], errorsChange: [{ type: i0.Output, args: ["errorsChange"] }], dirtyChange: [{ type: i0.Output, args: ["dirtyChange"] }], validChange: [{ type: i0.Output, args: ["validChange"] }] } });
 
-/**
- * Main form directive for ngx-vest-forms that bridges Angular template-driven forms with Vest.js validation.
- *
- * This directive provides:
- * - **Unidirectional data flow**: Use `[ngModel]` (not `[(ngModel)]`) with `(formValueChange)` for predictable state updates
- * - **Vest.js integration**: Automatic async validators from Vest suites with field-level optimization
- * - **Validation dependencies**: Configure cross-field validation triggers via `validationConfig`
- * - **Form state**: Access validity, errors, and values through the `formState` signal
- *
- * @usageNotes
- *
- * ### Basic Usage
- * ```html
- * <form ngxVestForm [suite]="validationSuite" (formValueChange)="formValue.set($event)">
- *   <input name="email" [ngModel]="formValue().email" />
- * </form>
- * ```
- *
- * ### With Validation Dependencies
- * ```html
- * <form ngxVestForm [suite]="suite" [validationConfig]="validationConfig">
- *   <input name="password" [ngModel]="formValue().password" />
- *   <input name="confirmPassword" [ngModel]="formValue().confirmPassword" />
- * </form>
- * ```
- * ```typescript
- * validationConfig = { 'password': ['confirmPassword'] };
- * ```
- *
- * ### Accessing Form State
- * ```typescript
- * vestForm = viewChild.required('vestForm', { read: FormDirective });
- * isValid = computed(() => this.vestForm().formState().valid);
- * ```
- *
- * @see {@link https://github.com/ngx-vest-forms/ngx-vest-forms} for full documentation
- * @publicApi
- */
-class FormDirective {
-    // Track last linked value to prevent unnecessary updates
-    #lastLinkedValue;
-    #lastSyncedFormValue;
-    #lastSyncedModelValue;
-    // Internal signal tracking form value changes via statusChanges
-    #value;
+const INITIAL_FORM_CONTROL_STATE = {
+    status: 'INVALID',
+    isValid: false,
+    isInvalid: true,
+    isPending: false,
+    isDisabled: false,
+    isTouched: false,
+    isDirty: false,
+    isPristine: true,
+    errors: null,
+};
+class FormControlStateDirective {
+    #hostNgModel;
+    #hostNgModelGroup;
+    #injector;
     /**
-     * LinkedSignal that computes form values from Angular form state.
-     * This eliminates timing issues with the previous dual-effect pattern.
+     * Reference to the parent FormDirective for accessing field warnings.
+     * Optional to support usage outside of ngxVestForm context.
      */
-    #formValueSignal;
+    #formDirective;
+    /**
+     * Computed signal for the active control (NgModel or NgModelGroup)
+     */
+    #activeControl;
+    /**
+     * Consolidated internal signal for interaction state tracking.
+     * Combines touched, dirty, and hasBeenValidated into a single signal
+     * to reduce signal overhead and simplify state updates.
+     */
+    #interactionState;
+    /**
+     * Track the previous status to detect actual status changes (not just status emissions).
+     * This helps distinguish between initial control creation and actual re-validation.
+     */
+    #previousStatus;
+    /**
+     * 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);
+        /**
+         * Reference to the parent FormDirective for accessing field warnings.
+         * Optional to support usage outside of ngxVestForm context.
+         */
+        this.#formDirective = inject(FormDirective, { optional: true });
+        /**
+         * Computed signal for the active control (NgModel or NgModelGroup)
+         */
+        this.#activeControl = computed(() => this.#hostNgModel ||
+            this.#hostNgModelGroup ||
+            this.contentNgModel() ||
+            this.contentNgModelGroup() ||
+            null, ...(ngDevMode ? [{ debugName: "#activeControl" }] : []));
+        /**
+         * Consolidated internal signal for interaction state tracking.
+         * Combines touched, dirty, and hasBeenValidated into a single signal
+         * to reduce signal overhead and simplify state updates.
+         */
+        this.#interactionState = signal({
+            isTouched: false,
+            isDirty: false,
+            hasBeenValidated: false,
+        }, ...(ngDevMode ? [{ debugName: "#interactionState" }] : []));
+        /**
+         * Track the previous status to detect actual status changes (not just status emissions).
+         * This helps distinguish between initial control creation and actual re-validation.
+         */
+        this.#previousStatus = null;
+        /**
+         * Internal signal for control state (updated reactively)
+         */
+        this.#controlStateSignal = signal(INITIAL_FORM_CONTROL_STATE, ...(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 { errors } = this.controlState();
+            if (!errors)
+                return [];
+            // Vest errors are stored in the 'errors' property as an array
+            const vestErrors = errors.errors;
+            if (vestErrors) {
+                return vestErrors
+                    .map((error) => normalizeErrorMessage(error))
+                    .filter((error) => Boolean(error));
+            }
+            // Fallback to flattened Angular error keys, excluding 'warnings' key
+            // to prevent warnings from appearing in the error list
+            const errorsWithoutWarnings = { ...errors };
+            delete errorsWithoutWarnings['warnings'];
+            return this.#flattenAngularErrors(errorsWithoutWarnings);
+        }, ...(ngDevMode ? [{ debugName: "errorMessages" }] : []));
+        /**
+         * ADVANCED: updateOn strategy (change/blur/submit) if available
+         */
+        this.updateOn = computed(() => {
+            const ngModel = this.contentNgModel() || this.#hostNgModel;
+            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.
+         * 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.
+         */
+        this.warningMessages = computed(() => {
+            // Source 1: warnings from control.errors (when field has errors)
+            const { errors } = this.controlState();
+            // Always read fieldWarnings signal to ensure reactive tracking
+            // This must be read unconditionally for proper signal dependency tracking
+            const fieldWarnings = this.#formDirective?.fieldWarnings();
+            const activeControl = this.#activeControl();
+            // If we have warnings in control.errors, use those (errors+warnings case)
+            if (errors?.warnings) {
+                return [...errors.warnings];
+            }
+            // Source 2: warnings from FormDirective (for warnings-only scenarios)
+            // When a field only has warnings (no errors), they're stored in fieldWarnings
+            // to keep the field valid while still allowing warnings to be displayed.
+            if (fieldWarnings && activeControl) {
+                // Get the field path from the control's path property
+                // NgModel.path returns an array like ['passwords', 'password'] which needs to be joined
+                const path = activeControl.path;
+                if (path?.length) {
+                    const fieldPath = path.join('.');
+                    const warnings = fieldWarnings.get(fieldPath);
+                    if (warnings) {
+                        return [...warnings];
+                    }
+                }
+            }
+            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, ...(ngDevMode ? [{ debugName: "isValid" }] : []));
+        this.isInvalid = computed(() => this.controlState().isInvalid, ...(ngDevMode ? [{ debugName: "isInvalid" }] : []));
+        this.isPending = computed(() => this.controlState().isPending, ...(ngDevMode ? [{ debugName: "isPending" }] : []));
+        this.isTouched = computed(() => this.controlState().isTouched, ...(ngDevMode ? [{ debugName: "isTouched" }] : []));
+        this.isDirty = computed(() => this.controlState().isDirty, ...(ngDevMode ? [{ debugName: "isDirty" }] : []));
+        this.isPristine = computed(() => this.controlState().isPristine, ...(ngDevMode ? [{ debugName: "isPristine" }] : []));
+        this.isDisabled = computed(() => this.controlState().isDisabled, ...(ngDevMode ? [{ debugName: "isDisabled" }] : []));
+        this.hasErrors = computed(() => this.errorMessages().length > 0, ...(ngDevMode ? [{ debugName: "hasErrors" }] : []));
+        /**
+         * 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.
+         */
+        this.hasBeenValidated = computed(() => this.#interactionState().hasBeenValidated, ...(ngDevMode ? [{ debugName: "hasBeenValidated" }] : []));
+        // Update control state reactively with proper cleanup
+        effect((onCleanup) => {
+            const control = this.#activeControl();
+            const interaction = this.#interactionState();
+            if (!control) {
+                this.#controlStateSignal.set(INITIAL_FORM_CONTROL_STATE);
+                return;
+            }
+            // Listen to control changes
+            const sub = control.control?.statusChanges?.subscribe(() => {
+                const { status, valid, invalid, pending, disabled, pristine, errors, touched, dirty, } = control;
+                const currentStatus = status;
+                // Mark as validated when any of the following conditions are met:
+                // 1. The control has been touched (user blurred the field).
+                // 2. The control's status has actually changed (not the first status emission),
+                //    AND the new status is not 'PENDING' (validation completed),
+                //    AND the control has been interacted with (dirty).
+                //
+                // This ensures hasBeenValidated is true for:
+                //   - User blur events (touched becomes true)
+                //   - User-triggered validations (dirty)
+                //   - ValidationConfig-triggered validations that result in the control becoming touched
+                // But NOT for initial page load validations.
+                //
+                // Accessibility: The logic is structured for clarity and maintainability.
+                // IMPORTANT: Read touched/dirty directly from control, not from signal,
+                // to avoid race conditions with afterEveryRender sync.
+                if (touched || // Control was blurred (most common case)
+                    (this.#previousStatus !== null && // Not the first status emission
+                        this.#previousStatus !== currentStatus && // Status actually changed
+                        currentStatus !== null &&
+                        currentStatus !== 'PENDING' &&
+                        dirty) // Or control value changed (typed)
+                ) {
+                    this.#interactionState.update((state) => ({
+                        ...state,
+                        hasBeenValidated: true,
+                    }));
+                }
+                // Track current status for next iteration
+                this.#previousStatus = currentStatus;
+                this.#controlStateSignal.set({
+                    status: currentStatus,
+                    isValid: valid ?? false,
+                    isInvalid: invalid ?? false,
+                    isPending: pending ?? false,
+                    isDisabled: disabled ?? false,
+                    isTouched: interaction.isTouched,
+                    isDirty: interaction.isDirty,
+                    isPristine: pristine ?? true,
+                    errors: errors,
+                });
+            });
+            // Initial update
+            const { status, valid, invalid, pending, disabled, pristine, errors } = control;
+            const initialStatus = status;
+            this.#previousStatus = initialStatus;
+            this.#controlStateSignal.set({
+                status: initialStatus,
+                isValid: valid ?? false,
+                isInvalid: invalid ?? false,
+                isPending: pending ?? false,
+                isDisabled: disabled ?? false,
+                isTouched: interaction.isTouched,
+                isDirty: interaction.isDirty,
+                isPristine: pristine ?? true,
+                errors: errors,
+            });
+            // Proper cleanup using onCleanup callback (Angular 21 best practice)
+            onCleanup(() => sub?.unsubscribe());
+        });
+        // Robustly sync touched/dirty/pending after every render (Angular 18+ best practice)
+        // This handles cases where statusChanges events are missed or delayed
+        afterEveryRender(() => {
+            const control = this.#activeControl();
+            if (control) {
+                const currentInteraction = this.#interactionState();
+                const currentState = this.#controlStateSignal();
+                const newTouched = control.touched ?? false;
+                const newDirty = control.dirty ?? false;
+                // Sync interaction state (touched/dirty)
+                if (newTouched !== currentInteraction.isTouched ||
+                    newDirty !== currentInteraction.isDirty) {
+                    // Mark as validated when control becomes touched (e.g., user blurred the field)
+                    // This handles the case where blur doesn't trigger statusChanges (field already invalid)
+                    const shouldMarkValidated = newTouched && !currentInteraction.isTouched;
+                    this.#interactionState.update((state) => ({
+                        ...state,
+                        isTouched: newTouched,
+                        isDirty: newDirty,
+                        hasBeenValidated: shouldMarkValidated
+                            ? true
+                            : state.hasBeenValidated,
+                    }));
+                }
+                // Sync pending state only when it transitions from true to false
+                // This fixes "Validating..." being stuck when statusChanges misses the transition
+                // We only sync when pending goes false to avoid interfering with async validation in progress
+                const controlPending = control.pending ?? false;
+                if (currentState.isPending && !controlPending) {
+                    // Pending changed from true to false - update the full state
+                    const newStatus = control.status;
+                    this.#controlStateSignal.set({
+                        status: newStatus,
+                        isPending: false,
+                        isValid: control.valid ?? false,
+                        isInvalid: control.invalid ?? false,
+                        isPristine: control.pristine ?? true,
+                        isDisabled: control.disabled ?? false,
+                        isTouched: newTouched,
+                        isDirty: newDirty,
+                        errors: control.errors,
+                    });
+                }
+            }
+        }, { injector: this.#injector });
+    }
+    /**
+     * Recursively flattens Angular error objects into an array of error messages.
+     * Handles string values, objects with a message property, and nested structures.
+     */
+    #flattenAngularErrors(errors) {
+        const result = [];
+        for (const key of Object.keys(errors)) {
+            const value = errors[key];
+            if (typeof value === 'string') {
+                // String values: push the value itself, not the key
+                result.push(value);
+            }
+            else if (isErrorWithMessage(value)) {
+                // Objects with a 'message' property: extract the message
+                result.push(value.message);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                // Nested objects/arrays: recursively flatten
+                result.push(...this.#flattenAngularErrors(value));
+            }
+            else {
+                // Fallback: push the key for primitive types (backward compatibility)
+                result.push(key);
+            }
+        }
+        return result;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormControlStateDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.2.0", version: "21.1.1", type: FormControlStateDirective, isStandalone: true, selector: "[formControlState], [ngxControlState]", queries: [{ propertyName: "contentNgModel", first: true, predicate: NgModel, descendants: true, isSignal: true }, { propertyName: "contentNgModelGroup", first: true, predicate: NgModelGroup, descendants: true, isSignal: true }], exportAs: ["formControlState", "ngxControlState"], ngImport: i0 }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormControlStateDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[formControlState], [ngxControlState]',
+                    exportAs: 'formControlState, ngxControlState',
+                }]
+        }], ctorParameters: () => [], propDecorators: { contentNgModel: [{ type: i0.ContentChild, args: [i0.forwardRef(() => NgModel), { isSignal: true }] }], contentNgModelGroup: [{ type: i0.ContentChild, args: [i0.forwardRef(() => NgModelGroup), { isSignal: true }] }] } });
+/**
+ * Type guard for objects with a message property
+ */
+function isErrorWithMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'message' in value &&
+        typeof value.message === 'string');
+}
+function normalizeErrorMessage(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (isErrorWithMessage(value)) {
+        return value.message;
+    }
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+
+const SC_ERROR_DISPLAY_MODE_DEFAULT = 'on-blur-or-submit';
+const SC_WARNING_DISPLAY_MODE_DEFAULT = 'on-validated-or-touch';
+class FormErrorDisplayDirective {
+    #formControlState;
+    // Optionally inject NgForm for form submission tracking
+    #ngForm;
     /**
-     * Track the Angular form status as a signal for advanced status flags
+     * Internal trigger signal that updates whenever form submit or status changes.
+     * Used to ensure reactive tracking for the formSubmitted computed signal.
      */
-    #statusSignal;
+    #formEventTrigger;
     constructor() {
-        this.ngForm = inject(NgForm, { self: true });
-        this.destroyRef = inject(DestroyRef);
-        this.cdr = inject(ChangeDetectorRef);
-        this.configDebounceTime = inject(NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN);
-        // Track last linked value to prevent unnecessary updates
-        this.#lastLinkedValue = null;
-        this.#lastSyncedFormValue = null;
-        this.#lastSyncedModelValue = null;
-        // Internal signal tracking form value changes via statusChanges
-        this.#value = toSignal(this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status)), { initialValue: this.ngForm.form.status });
-        /**
-         * LinkedSignal that computes form values from Angular form state.
-         * This eliminates timing issues with the previous dual-effect pattern.
-         */
-        this.#formValueSignal = linkedSignal(() => {
-            // Track form value changes
-            this.#value();
-            const raw = mergeValuesAndRawValues(this.ngForm.form);
-            if (Object.keys(this.ngForm.form.controls).length > 0) {
-                this.#lastLinkedValue = raw;
-                return raw;
-            }
-            else if (this.#lastLinkedValue !== null) {
-                return this.#lastLinkedValue;
-            }
-            return null;
-        }, ...(ngDevMode ? [{ debugName: "#formValueSignal" }] : []));
-        /**
-         * Track the Angular form status as a signal for advanced status flags
-         */
-        this.#statusSignal = toSignal(this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status)), { initialValue: this.ngForm.form.status });
+        this.#formControlState = inject(FormControlStateDirective);
+        // Optionally inject NgForm for form submission tracking
+        this.#ngForm = inject(NgForm, { optional: true });
         /**
-         * Computed signal for form state with validity and errors.
-         * Used by templates and tests as vestForm.formState().valid/errors
-         *
-         * Uses custom equality function to prevent unnecessary recalculations
-         * when form status changes but actual values/errors remain the same.
+         * Input signal for error display mode.
+         * Works seamlessly with hostDirectives in Angular 19+.
          */
-        this.formState = computed(() => {
-            // Tie to status signal to ensure recomputation on validation changes
-            this.#statusSignal();
-            return {
-                valid: this.ngForm.form.valid,
-                errors: getAllFormErrors(this.ngForm.form),
-                value: this.#formValueSignal(),
-            };
-        }, { ...(ngDevMode ? { debugName: "formState" } : {}), equal: (a, b) => {
-                // Fast path: reference equality
-                if (a === b)
-                    return true;
-                // Null/undefined check
-                if (!a || !b)
-                    return false;
-                // Deep equality check for form state properties
-                return (a.valid === b.valid &&
-                    fastDeepEqual(a.errors, b.errors) &&
-                    fastDeepEqual(a.value, b.value));
-            } });
+        this.errorDisplayMode = input(inject(NGX_ERROR_DISPLAY_MODE_TOKEN, { optional: true }) ??
+            inject(SC_ERROR_DISPLAY_MODE_TOKEN, { optional: true }) ??
+            SC_ERROR_DISPLAY_MODE_DEFAULT, ...(ngDevMode ? [{ debugName: "errorDisplayMode" }] : []));
         /**
-         * The value of the form, this is needed for the validation part.
-         * Using input() here because two-way binding is provided via formValueChange output.
-         * In the minimal core directive (form-core.directive.ts), this would be model() instead.
+         * Input signal for warning display mode.
+         * Controls whether warnings are shown only after touch or also after validation.
          */
-        this.formValue = input(null, ...(ngDevMode ? [{ debugName: "formValue" }] : []));
+        this.warningDisplayMode = input(inject(NGX_WARNING_DISPLAY_MODE_TOKEN, { optional: true }) ??
+            SC_WARNING_DISPLAY_MODE_DEFAULT, ...(ngDevMode ? [{ debugName: "warningDisplayMode" }] : []));
+        // 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;
+        this.hasBeenValidated = this.#formControlState.hasBeenValidated;
         /**
-         * Static vest suite that will be used to feed our angular validators.
-         * Accepts both NgxVestSuite and NgxTypedVestSuite through compatible type signatures.
-         * NgxTypedVestSuite<T> is assignable to NgxVestSuite<T> due to bivariance and
-         * FormFieldName<T> (string literal union) being assignable to string.
+         * 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.suite = input(null, ...(ngDevMode ? [{ debugName: "suite" }] : []));
+        this.updateOn = this.#formControlState.updateOn;
         /**
-         * The shape of our form model. This is a deep required version of the form model
-         * The goal is to add default values to the shape so when the template-driven form
-         * contains values that shouldn't be there (typo's) that the developer gets run-time
-         * errors in dev mode
+         * Internal trigger signal that updates whenever form submit or status changes.
+         * Used to ensure reactive tracking for the formSubmitted computed signal.
          */
-        this.formShape = input(null, ...(ngDevMode ? [{ debugName: "formShape" }] : []));
+        this.#formEventTrigger = this.#ngForm
+            ? toSignal(merge(this.#ngForm.ngSubmit, this.#ngForm.statusChanges ?? of()).pipe(startWith(null)), { initialValue: null })
+            : signal(null);
         /**
-         * Updates the validation config which is a dynamic object that will be used to
-         * trigger validations on the dependant fields
-         * Eg: ```typescript
-         * validationConfig = {
-         *     'passwords.password': ['passwords.confirmPassword']
-         * }
-         * ```
-         *
-         * This will trigger the updateValueAndValidity on passwords.confirmPassword every time the passwords.password gets a new value
+         * Signal that tracks NgForm.submitted state reactively.
          *
-         * @param v
-         */
-        this.validationConfig = input(null, ...(ngDevMode ? [{ debugName: "validationConfig" }] : []));
-        this.pending$ = this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v === 'PENDING'), distinctUntilChanged());
-        /**
-         * Emits every time the form status changes in a state
-         * that is not PENDING
-         * We need this to assure that the form is in 'idle' state
-         */
-        this.idle$ = this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v !== 'PENDING'), distinctUntilChanged());
-        /**
-         * Triggered as soon as the form value changes
-         * It also contains the disabled values (raw values)
+         * 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)
          *
-         * Cleanup is handled automatically by the directive when it's destroyed.
+         * This ensures proper sync with both submit and reset operations.
          */
-        this.formValueChange = outputFromObservable(this.ngForm.form.events.pipe(filter((v) => v instanceof ValueChangeEvent), map((v) => v.value), distinctUntilChanged((prev, curr) => {
-            // Use efficient deep equality instead of JSON.stringify for better performance
-            return fastDeepEqual(prev, curr);
-        }), map(() => mergeValuesAndRawValues(this.ngForm.form)), takeUntilDestroyed(this.destroyRef)));
+        this.formSubmitted = computed(() => {
+            // Trigger signal ensures this recomputes on submit/status changes
+            this.#formEventTrigger();
+            return this.#ngForm?.submitted ?? false;
+        }, ...(ngDevMode ? [{ debugName: "formSubmitted" }] : []));
         /**
-         * 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
+         * Determines if errors should be shown based on the specified display mode
+         * and the control's state (touched/submitted/validated).
          *
-         * Cleanup is handled automatically by the directive when it's destroyed.
-         */
-        this.errorsChange = outputFromObservable(this.ngForm.form.events.pipe(filter((v) => v instanceof StatusChangeEvent), map((v) => v.status), filter((v) => v !== 'PENDING'), map(() => getAllFormErrors(this.ngForm.form)), takeUntilDestroyed(this.destroyRef)));
-        /**
-         * Triggered as soon as the form becomes dirty
+         * Note: We check both hasErrors (extracted error messages) AND isInvalid (Angular's validation state)
+         * because in some cases (like conditional validations via validationConfig), the control is marked
+         * as invalid by Angular before error messages are extracted from Vest. This ensures aria-invalid
+         * is set correctly even during the validation propagation delay.
          *
-         * Cleanup is handled automatically by the directive when it's destroyed.
-         */
-        this.dirtyChange = outputFromObservable(this.ngForm.form.events.pipe(filter((v) => v instanceof PristineChangeEvent), map((v) => !v.pristine), startWith(this.ngForm.form.dirty), distinctUntilChanged(), takeUntilDestroyed(this.destroyRef)));
-        /**
-         * Fired when the status of the root form changes.
+         * For validationConfig-triggered validations: A field can be validated without being touched
+         * (e.g., confirmPassword validated when password changes). We check hasBeenValidated to show
+         * errors in these scenarios, providing better UX and proper ARIA attributes.
          */
-        this.statusChanges$ = this.ngForm.form.statusChanges.pipe(startWith(this.ngForm.form.status), distinctUntilChanged());
+        this.shouldShowErrors = computed(() => {
+            const mode = this.errorDisplayMode();
+            const isTouched = this.isTouched();
+            const isInvalid = this.isInvalid();
+            const hasErrors = this.errorMessages().length > 0;
+            const updateOn = this.updateOn();
+            const formSubmitted = this.formSubmitted();
+            // Consider errors present if either we have error messages OR the control is invalid
+            // This handles the race condition where Angular marks control invalid before Vest errors propagate
+            const hasErrorState = hasErrors || isInvalid;
+            // Always only show errors after submit if updateOn is 'submit'
+            if (updateOn === 'submit') {
+                return !!(formSubmitted && hasErrorState);
+            }
+            // on-blur: show errors after blur (touch)
+            if (mode === 'on-blur') {
+                return !!(isTouched && 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" }] : []));
         /**
-         * Triggered When the form becomes valid but waits until the form is idle
-         *
-         * Cleanup is handled automatically by the directive when it's destroyed.
+         * Errors to display (filtered for pending state)
          */
-        this.validChange = outputFromObservable(this.statusChanges$.pipe(filter((e) => e === 'VALID' || e === 'INVALID'), map((v) => v === 'VALID'), distinctUntilChanged(), takeUntilDestroyed(this.destroyRef)));
+        this.errors = computed(() => {
+            if (this.hasPendingValidation())
+                return [];
+            return this.errorMessages();
+        }, ...(ngDevMode ? [{ debugName: "errors" }] : []));
         /**
-         * Track validation in progress to prevent circular triggering (Issue #19)
+         * Warnings to display (filtered for pending state)
          */
-        this.validationInProgress = new Set();
+        this.warnings = computed(() => {
+            if (this.hasPendingValidation())
+                return [];
+            return this.warningMessages();
+        }, ...(ngDevMode ? [{ debugName: "warnings" }] : []));
         /**
-         * Trigger shape validations if the form gets updated
-         * This is how we can throw run-time errors
+         * Whether the control is currently being validated (pending)
+         * Excludes pristine+untouched controls to prevent "Validating..." on initial load
          */
-        if (isDevMode()) {
-            effect(() => {
-                const v = this.formValue();
-                if (v && this.formShape()) {
-                    validateShape(v, this.formShape());
+        this.isPending = computed(() => {
+            // Don't show pending state for pristine untouched controls
+            // This prevents "Validating..." message appearing on initial page load
+            const state = this.#formControlState.controlState();
+            if (state.isPristine && !state.isTouched) {
+                return false;
+            }
+            return this.hasPendingValidation();
+        }, ...(ngDevMode ? [{ debugName: "isPending" }] : []));
+        // 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: "21.1.1", ngImport: i0, type: FormErrorDisplayDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: FormErrorDisplayDirective, isStandalone: true, selector: "[formErrorDisplay], [ngxErrorDisplay]", inputs: { errorDisplayMode: { classPropertyName: "errorDisplayMode", publicName: "errorDisplayMode", isSignal: true, isRequired: false, transformFunction: null }, warningDisplayMode: { classPropertyName: "warningDisplayMode", publicName: "warningDisplayMode", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["formErrorDisplay", "ngxErrorDisplay"], hostDirectives: [{ directive: FormControlStateDirective }], ngImport: i0 }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormErrorDisplayDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[formErrorDisplay], [ngxErrorDisplay]',
+                    exportAs: 'formErrorDisplay, ngxErrorDisplay',
+                    hostDirectives: [FormControlStateDirective],
+                }]
+        }], ctorParameters: () => [], propDecorators: { errorDisplayMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "errorDisplayMode", required: false }] }], warningDisplayMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "warningDisplayMode", required: false }] }] } });
+
+/**
+ * Creates a debounced pending state signal that prevents flashing validation messages.
+ *
+ * This utility helps implement a better UX for async validations by:
+ * 1. Delaying the display of "Validating..." messages until validation takes longer than `showAfter`ms (default: 200ms)
+ * 2. Keeping the message visible for at least `minimumDisplay`ms (default: 500ms) once shown to prevent flickering
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (showPendingMessage()) {
+ *       <div role="status" aria-live="polite">Validating…</div>
+ *     }
+ *   `
+ * })
+ * export class CustomControlWrapperComponent {
+ *   protected readonly errorDisplay = inject(FormErrorDisplayDirective, { self: true });
+ *
+ *   // Create debounced pending state
+ *   private readonly pendingState = createDebouncedPendingState(
+ *     this.errorDisplay.isPending,
+ *     { showAfter: 200, minimumDisplay: 500 }
+ *   );
+ *
+ *   protected readonly showPendingMessage = this.pendingState.showPendingMessage;
+ * }
+ * ```
+ *
+ * @param isPending - Signal indicating whether async validation is currently pending
+ * @param options - Configuration options for debouncing behavior
+ * @returns Object containing the debounced showPendingMessage signal and cleanup function
+ */
+function createDebouncedPendingState(isPending, options = {}) {
+    const { showAfter = 200, minimumDisplay = 500 } = options;
+    // Create writable signal for debounced state
+    const showPendingMessageSignal = signal(false, ...(ngDevMode ? [{ debugName: "showPendingMessageSignal" }] : []));
+    // Track timeouts
+    let pendingTimeout = null;
+    let minimumDisplayTimeout = null;
+    // Cleanup function
+    const cleanup = () => {
+        if (pendingTimeout) {
+            clearTimeout(pendingTimeout);
+            pendingTimeout = null;
+        }
+        if (minimumDisplayTimeout) {
+            clearTimeout(minimumDisplayTimeout);
+            minimumDisplayTimeout = null;
+        }
+    };
+    // Effect to manage debounced pending message display
+    effect((onCleanup) => {
+        const pending = isPending();
+        if (pending) {
+            // Clear any existing minimum display timeout
+            if (minimumDisplayTimeout) {
+                clearTimeout(minimumDisplayTimeout);
+                minimumDisplayTimeout = null;
+            }
+            // Start delay timer before showing pending message
+            pendingTimeout = setTimeout(() => {
+                showPendingMessageSignal.set(true);
+                pendingTimeout = null;
+            }, showAfter);
+            onCleanup(() => {
+                if (pendingTimeout) {
+                    clearTimeout(pendingTimeout);
+                    pendingTimeout = null;
                 }
             });
         }
-        /**
-         * Mark all the fields as touched when the form is submitted
-         */
-        this.ngForm.ngSubmit
-            .pipe(takeUntilDestroyed(this.destroyRef))
-            .subscribe(() => {
-            this.ngForm.form.markAllAsTouched();
-        });
-        /**
-         * Single bidirectional synchronization effect using linkedSignal.
-         * Uses proper deep comparison and change tracking for correct sync direction.
-         * Note: formValue is read-only input(), so we emit changes via formValueChange output.
-         */
-        effect(() => {
-            const formValue = this.#formValueSignal();
-            const modelValue = this.formValue();
-            // Skip if either is null
-            if (!formValue && !modelValue)
-                return;
-            // Compute change flags first
-            const formChanged = !fastDeepEqual(formValue, this.#lastSyncedFormValue);
-            const modelChanged = !fastDeepEqual(modelValue, this.#lastSyncedModelValue);
-            // Early return if nothing changed
-            if (!formChanged && !modelChanged) {
-                return;
-            }
-            if (formChanged && !modelChanged) {
-                // Form was modified by user -> form wins
-                // Note: We can't call this.formValue.set() since it's an input()
-                // The formValueChange output will emit the new value
-                // Use untracked() to avoid infinite loops - we're updating tracking state here
-                untracked(() => {
-                    this.#lastSyncedFormValue = formValue;
-                    this.#lastSyncedModelValue = formValue;
-                });
+        else {
+            // Validation completed
+            if (pendingTimeout) {
+                // Validation completed before delay - don't show message
+                clearTimeout(pendingTimeout);
+                pendingTimeout = null;
             }
-            else if (modelChanged && !formChanged) {
-                // Model was modified programmatically -> model wins
-                // Use untracked() to avoid infinite loops - we're updating tracking state here
-                untracked(() => {
-                    // Update form controls with new model values
-                    if (modelValue) {
-                        // IMPORTANT: Use root patchValue instead of per-key setValue.
-                        // - Supports nested objects (ngModelGroup) without throwing when partial objects are provided.
-                        // - patchValue ignores missing controls/keys, which is compatible with DeepPartial form models.
-                        // - emitEvent:false prevents feedback loops; validation still updates internally.
-                        this.ngForm.form.patchValue(modelValue, { emitEvent: false });
+            else if (showPendingMessageSignal()) {
+                // Message was shown - keep it visible for minimum duration
+                minimumDisplayTimeout = setTimeout(() => {
+                    showPendingMessageSignal.set(false);
+                    minimumDisplayTimeout = null;
+                }, minimumDisplay);
+                onCleanup(() => {
+                    if (minimumDisplayTimeout) {
+                        clearTimeout(minimumDisplayTimeout);
+                        minimumDisplayTimeout = null;
                     }
-                    this.#lastSyncedFormValue = modelValue;
-                    this.#lastSyncedModelValue = modelValue;
                 });
             }
-            else if (formChanged && modelChanged) {
-                // Both form and model changed simultaneously
-                // Check if they changed to the same value (synchronized change) or different values (conflict)
-                const valuesEqual = fastDeepEqual(formValue, modelValue);
-                if (valuesEqual) {
-                    // Both changed to the same value - this is a synchronized change, not a conflict
-                    // Just update tracking to acknowledge the change
-                    untracked(() => {
-                        this.#lastSyncedFormValue = formValue;
-                        this.#lastSyncedModelValue = formValue;
-                    });
-                }
-                else {
-                    // Both changed to different values - this is a true conflict
-                    // This is an edge case that should rarely happen in practice.
-                    // We intentionally do nothing here to avoid breaking the Angular event flow.
-                    // The form will continue with its current values, and validation will run normally.
-                    // The next change (either form or model) will trigger proper synchronization.
-                }
-            }
-        });
-        // Set up validation config reactively
-        this.#setupValidationConfig();
-    }
-    /**
-     * Manually trigger form validation update.
-     *
-     * This is useful when form structure changes but no control values change,
-     * which means validation state might be stale. This method forces a re-evaluation
-     * of all form validators and updates the form validity state.
-     *
-     * **IMPORTANT: This method validates ALL form fields by design.**
-     * This is intentional for structure changes as conditional validators may now
-     * apply to different fields, requiring a complete validation refresh.
-     *
-     * **CRITICAL: This method does NOT mark fields as touched or show errors.**
-     * It only re-runs validation logic. To show all errors (e.g., on submit),
-     * use `markAllAsTouched()` instead or in combination.
-     *
-     * **When to use each:**
-     * - `triggerFormValidation()` - Re-run validation when structure changes
-     * - `markAllAsTouched()` - Show all errors to user (e.g., on submit)
-     * - Both together - Rare, only if structure changed AND you want to show errors
-     *
-     * **Note on form submission:**
-     * When using the default error display mode (`on-blur-or-submit`), you typically
-     * don't need to call this method on submit. The form directive automatically marks
-     * all fields as touched on `ngSubmit`, and errors will display automatically.
-     * Only use this method when form structure changes without value changes.
-     *
-     * **Use Cases:**
-     * - Conditionally showing/hiding form controls based on other field values
-     * - Adding or removing form controls dynamically
-     * - Switching between different form layouts where validation requirements change
-     * - Any scenario where form structure changes but no ValueChangeEvent is triggered
-     *
-     * **Example:**
-     * When switching from a form with required input fields to one with only informational content,
-     * the form should become valid, but this won't happen automatically
-     * when no value changes occur (e.g., switching from input fields to informational content).
-     *
-     * **Performance Note:**
-     * This method calls `updateValueAndValidity({ emitEvent: true })` on the root form,
-     * which validates all form controls. For large forms, consider if more granular
-     * validation updates are possible.
-     *
-     * @example
-     * ```typescript
-     * /// After changing form structure
-     * onProcedureTypeChange(newType: string) {
-     *   this.procedureType.set(newType);
-     *   /// Structure changed but no control values changed
-     *   this.formDirective.triggerFormValidation();
-     * }
-     *
-     * /// For submit with multiple forms (show all errors)
-     * submitAll() {
-     *   // Mark all as touched to show errors
-     *   this.form1Ref().markAllAsTouched();
-     *   this.form2Ref().markAllAsTouched();
-     *   // Only needed if structure changed without value changes
-     *   // this.form1Ref().triggerFormValidation();
-     *   // this.form2Ref().triggerFormValidation();
-     * }
-     * ```
-     */
-    triggerFormValidation(path) {
-        if (path) {
-            const control = this.ngForm.form.get(path);
-            if (control) {
-                control.updateValueAndValidity({ emitEvent: true });
-            }
-            else if (isDevMode()) {
-                logWarning(NGX_VEST_FORMS_ERRORS.CONTROL_NOT_FOUND, path);
+        }
+    });
+    return {
+        showPendingMessage: showPendingMessageSignal.asReadonly(),
+        cleanup,
+    };
+}
+
+// Counter for unique IDs
+let nextUniqueId$2 = 0;
+/**
+ * Accessible form control wrapper with WCAG 2.2 AA compliance.
+ *
+ * Wrap form fields to automatically display validation errors, warnings, and pending states
+ * with proper accessibility attributes.
+ *
+ * @usageNotes
+ *
+ * ### Basic Usage
+ * ```html
+ * <ngx-control-wrapper>
+ *   <label for="email">Email</label>
+ *   <input id="email" name="email" [ngModel]="formValue().email" />
+ * </ngx-control-wrapper>
+ * ```
+ *
+ * ### Error Display Modes
+ * Control when errors appear using the `errorDisplayMode` input:
+ * - `'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
+ *
+ * ```html
+ * <ngx-control-wrapper [errorDisplayMode]="'on-submit'">
+ *   <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
+ * - `aria-invalid="true"` when errors are shown
+ * - 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
+ *
+ *   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"
+ *   - 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 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 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>
+ *     <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):
+ *   <ngx-control-wrapper>
+ *     <input name="username" ngModel />
+ *   </ngx-control-wrapper>
+ *   /// If async validation is running for >200ms, 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.
+ *
+ * Example (global config):
+ *   import { provide } from '@angular/core';
+ *   import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
+ *   @Component({
+ *     providers: [
+ *       provide(NGX_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.
+ *   - Validate with tools like Accessibility Insights and real screen reader testing.
+ *
+ * @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA19 - ARIA19: Using ARIA role=alert
+ * @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22 - ARIA22: Using role=status
+ */
+class ControlWrapperComponent {
+    mergeAriaDescribedBy(existing, wrapperActiveIds) {
+        const existingTokens = (existing ?? '')
+            .split(/\s+/)
+            .map((t) => t.trim())
+            .filter(Boolean);
+        // Remove any previous wrapper-owned IDs from the existing list.
+        const existingWithoutWrapper = existingTokens.filter((t) => !this.wrapperOwnedDescribedByIds.includes(t));
+        // Append current wrapper IDs, preserving existing order and uniqueness.
+        const merged = [...existingWithoutWrapper];
+        for (const id of wrapperActiveIds) {
+            if (!merged.includes(id)) {
+                merged.push(id);
             }
         }
-        else {
-            // Update all form controls validity which will trigger all form events
-            this.ngForm.form.updateValueAndValidity({ emitEvent: true });
-        }
-    }
-    /**
-     * Convenience method to mark all form controls as touched.
-     *
-     * This is useful for showing all validation errors at once, typically when
-     * the user clicks a submit button. When a field is marked as touched,
-     * the error display logic (based on `errorDisplayMode`) will show its errors.
-     *
-     * **Note on automatic behavior:**
-     * When using the default error display mode (`on-blur-or-submit`), you typically
-     * don't need to call this method manually for regular form submissions. The form
-     * directive automatically marks all fields as touched on `ngSubmit`, so errors
-     * will display automatically when the user submits the form.
-     *
-     * **When to use this method:**
-     * - Multiple forms with a single submit button (forms without their own submit)
-     * - Programmatic form submission without triggering `ngSubmit`
-     * - Custom validation flows outside the normal submit process
-     *
-     * **Note:** This method only marks fields as touched—it does NOT re-run validation.
-     * If you also need to re-run validation (e.g., after structure changes), call
-     * `triggerFormValidation()` as well.
-     *
-     * @example
-     * ```typescript
-     * /// Standard form submission - NO need to call markAllAsTouched()
-     * /// The directive handles this automatically on ngSubmit
-     * <form ngxVestForm (ngSubmit)="save()">
-     *   <button type="submit">Submit</button>
-     * </form>
-     *
-     * /// Multiple forms with one submit button
-     * submitAll() {
-     *   this.form1().markAllAsTouched();
-     *   this.form2().markAllAsTouched();
-     *   if (this.form1().formState().valid && this.form2().formState().valid) {
-     *     /// Submit all forms
-     *   }
-     * }
-     * ```
-     */
-    markAllAsTouched() {
-        this.ngForm.form.markAllAsTouched();
-    }
-    /**
-     * Resets the form to a pristine, untouched state with optional new values.
-     *
-     * This method properly resets the form by:
-     * 1. Resetting Angular's underlying NgForm with the provided value
-     * 2. Clearing the bidirectional sync tracking state
-     * 3. Forcing a form validity update to clear any stale validation errors
-     *
-     * **Why this method exists:**
-     * When using the pattern `formValue.set({})` to reset a form, there can be a timing
-     * issue where the form controls in the DOM still hold their old values while the
-     * signal has already been updated. This creates a conflict in the bidirectional
-     * sync logic, requiring workarounds like calling `formValue.set({})` twice with
-     * a setTimeout. This method provides a proper solution by:
-     * - Calling Angular's `NgForm.resetForm()` which properly clears all controls
-     * - Clearing the internal sync tracking state to avoid stale comparisons
-     * - Triggering a form validity update to ensure validation state is current
-     *
-     * **Usage:**
-     * Instead of the double-set workaround:
-     * ```typescript
-     * // ❌ Old workaround (avoid)
-     * reset(): void {
-     *   this.formValue.set({});
-     *   setTimeout(() => this.formValue.set({}), 0);
-     * }
-     *
-     * // ✅ Preferred approach
-     * vestForm = viewChild.required('vestForm', { read: FormDirective });
-     * reset(): void {
-     *   this.formValue.set({});
-     *   this.vestForm().resetForm();
-     * }
-     * ```
-     *
-     * **With new values:**
-     * ```typescript
-     * // Reset and set new initial values
-     * resetWithDefaults(): void {
-     *   const defaults = { firstName: '', lastName: '', age: 18 };
-     *   this.formValue.set(defaults);
-     *   this.vestForm().resetForm(defaults);
-     * }
-     * ```
-     *
-     * @param value - Optional new value to reset the form to. If not provided,
-     *                resets to empty/default values.
-     *
-     * @see {@link markAllAsTouched} for showing validation errors
-     * @see {@link triggerFormValidation} for re-running validation without reset
-     */
-    resetForm(value) {
-        // Reset Angular's form to clear all controls and mark as pristine/untouched
-        this.ngForm.resetForm(value ?? undefined);
-        // Clear the bidirectional sync tracking state so the next formValue change
-        // is treated as a model change (not a conflict with stale form values)
-        this.#lastSyncedFormValue = null;
-        this.#lastSyncedModelValue = null;
-        this.#lastLinkedValue = null;
-        // Force change detection to ensure DOM updates are reflected
-        // Note: This is still needed even with signals because we're modifying NgForm
-        // (reactive forms), not signals. The formValue signal updates happen in the
-        // consumer component. detectChanges() ensures NgForm's reset is reflected in
-        // the DOM before we update validity.
-        this.cdr.detectChanges();
-        // Trigger validation update to clear any stale errors
-        // Now synchronous since detectChanges() has flushed DOM updates
-        this.ngForm.form.updateValueAndValidity({ emitEvent: true });
+        return merged.length > 0 ? merged.join(' ') : null;
     }
-    /**
-     * 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.
-     */
-    createAsyncValidator(field, validationOptions) {
-        const suite = this.suite();
-        if (!suite)
-            return () => of(null);
-        return (control) => {
-            const model = mergeValuesAndRawValues(this.ngForm.form);
-            // Targeted snapshot with candidate value injected at path
-            // mergeValuesAndRawValues already returns a deep clone (via structuredClone),
-            // so we can modify it directly without affecting the form state.
-            const snapshot = model;
-            setValueAtPath(snapshot, field, control.value);
-            // Use timer() instead of ReplaySubject for proper debouncing
-            return timer(validationOptions.debounceTime ?? 0).pipe(map(() => snapshot), switchMap((snap) => new Observable((observer) => {
-                try {
-                    // Cast to NgxVestSuite to accept string field parameter
-                    // Both NgxVestSuite and NgxTypedVestSuite work with string at runtime
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    suite(snap, field).done((result) => {
-                        const errors = result.getErrors()[field];
-                        const warnings = result.getWarnings()[field];
-                        const out = errors?.length || warnings?.length
-                            ? {
-                                ...(errors?.length && { errors }),
-                                ...(warnings?.length && { warnings }),
-                            }
-                            : null;
-                        // CRITICAL: Ensure DOM validity classes update for OnPush components.
-                        //
-                        // Angular's template-driven forms update `ng-valid`/`ng-invalid` host classes
-                        // during change detection. When async validation completes, there may be no
-                        // follow-up change detection pass for OnPush hosts, leaving the DOM in a stale
-                        // visual state (even though the control status has updated).
-                        //
-                        // We schedule a detectChanges() on the next microtask to avoid calling it
-                        // synchronously inside Angular's own validation pipeline.
-                        queueMicrotask(() => {
-                            try {
-                                this.cdr.detectChanges();
-                            }
-                            catch {
-                                // Fallback: mark for check when immediate detectChanges isn't safe.
-                                // This keeps behavior resilient in edge cases.
-                                this.cdr.markForCheck();
-                            }
-                        });
-                        observer.next(out);
-                        observer.complete();
-                    });
+    constructor() {
+        this.errorDisplay = inject(FormErrorDisplayDirective, {
+            self: true,
+        });
+        this.elementRef = inject(ElementRef);
+        this.destroyRef = inject(DestroyRef);
+        /**
+         * Controls how this wrapper applies ARIA attributes to descendant controls.
+         *
+         * - `all-controls` (default, backwards compatible): apply `aria-describedby` / `aria-invalid`
+         *   to all `input/select/textarea` elements inside the wrapper.
+         * - `single-control`: apply ARIA attributes only when exactly one control is found.
+         *   (Useful for wrappers that sometimes contain helper buttons/controls.)
+         * - `none`: do not mutate descendant controls at all (group-safe mode).
+         *
+         * Notes:
+         * - Use `none` when wrapping a container (e.g. `NgModelGroup`) to avoid stamping ARIA
+         *   across multiple child controls.
+         * - This does not affect whether messages render; it only affects ARIA wiring.
+         */
+        this.ariaAssociationMode = input('all-controls', ...(ngDevMode ? [{ debugName: "ariaAssociationMode" }] : []));
+        // Generate unique IDs for ARIA associations
+        this.uniqueId = `ngx-control-wrapper-${nextUniqueId$2++}`;
+        this.errorId = `${this.uniqueId}-error`;
+        this.warningId = `${this.uniqueId}-warning`;
+        this.pendingId = `${this.uniqueId}-pending`;
+        // Track form controls found in the wrapper
+        this.formControls = signal([], ...(ngDevMode ? [{ debugName: "formControls" }] : []));
+        // Signals when content is initialized so effects can safely touch the DOM.
+        this.contentInitialized = signal(false, ...(ngDevMode ? [{ debugName: "contentInitialized" }] : []));
+        // MutationObserver to detect dynamically added/removed controls
+        this.mutationObserver = null;
+        /**
+         * Debounced pending state to prevent flashing for quick async validations.
+         * Uses createDebouncedPendingState utility with 500ms delay and 500ms minimum display.
+         */
+        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, { showAfter: 500, minimumDisplay: 500 });
+        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.
+         *
+         * 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.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" }] : []));
+        /**
+         * Computed signal that builds aria-describedby string based on visible regions
+         */
+        this.ariaDescribedBy = computed(() => {
+            const ids = [];
+            if (this.errorDisplay.shouldShowErrors()) {
+                ids.push(this.errorId);
+            }
+            if (this.shouldShowWarnings()) {
+                ids.push(this.warningId);
+            }
+            if (this.showPendingMessage()) {
+                ids.push(this.pendingId);
+            }
+            return ids.length > 0 ? ids.join(' ') : null;
+        }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
+        /**
+         * IDs managed by this wrapper when composing aria-describedby.
+         *
+         * We remove only these from the consumer-provided aria-describedby tokens and then
+         * append the currently-relevant wrapper IDs. This prevents clobbering app-provided
+         * hint/help text associations.
+         */
+        this.wrapperOwnedDescribedByIds = [
+            this.errorId,
+            this.warningId,
+            this.pendingId,
+        ];
+        // Effect to update aria-describedby and aria-invalid on form controls
+        effect(() => {
+            if (!this.contentInitialized())
+                return;
+            const mode = this.ariaAssociationMode();
+            if (mode === 'none') {
+                return;
+            }
+            const describedBy = this.ariaDescribedBy();
+            const wrapperActiveIds = describedBy
+                ? describedBy.split(/\s+/).filter(Boolean)
+                : [];
+            const shouldShowErrors = this.errorDisplay.shouldShowErrors();
+            const targets = (() => {
+                const controls = this.formControls();
+                if (mode === 'single-control') {
+                    return controls.length === 1 ? controls : [];
                 }
-                catch {
-                    observer.next({ vestInternalError: 'Validation failed' });
-                    observer.complete();
+                return controls;
+            })();
+            targets.forEach((control) => {
+                // Update aria-describedby (merge, don't overwrite)
+                const nextDescribedBy = this.mergeAriaDescribedBy(control.getAttribute('aria-describedby'), wrapperActiveIds);
+                if (nextDescribedBy) {
+                    control.setAttribute('aria-describedby', nextDescribedBy);
                 }
-            })), catchError(() => of({ vestInternalError: 'Validation failed' })), take(1));
-        };
+                else {
+                    control.removeAttribute('aria-describedby');
+                }
+                // Update aria-invalid
+                if (shouldShowErrors) {
+                    control.setAttribute('aria-invalid', 'true');
+                }
+                else {
+                    control.removeAttribute('aria-invalid');
+                }
+            });
+        });
+        // Clean up MutationObserver when component is destroyed
+        this.destroyRef.onDestroy(() => {
+            this.mutationObserver?.disconnect();
+            this.mutationObserver = null;
+        });
+        // Effect to enable/disable DOM observation based on ariaAssociationMode.
+        // This keeps the wrapper cheap in group-safe mode.
+        effect(() => {
+            if (!this.contentInitialized())
+                return;
+            const mode = this.ariaAssociationMode();
+            if (mode === 'none') {
+                this.mutationObserver?.disconnect();
+                this.mutationObserver = null;
+                if (this.formControls().length > 0) {
+                    this.formControls.set([]);
+                }
+                return;
+            }
+            // Ensure controls list is up to date.
+            this.updateFormControls();
+            // Ensure MutationObserver is installed (dynamic @if/@for support).
+            if (!this.mutationObserver) {
+                this.mutationObserver = new MutationObserver(() => {
+                    this.updateFormControls();
+                });
+                this.mutationObserver.observe(this.elementRef.nativeElement, {
+                    childList: true,
+                    subtree: true,
+                });
+            }
+        });
     }
-    /**
-     * Set up validation config reactively using v2 pattern with toObservable + switchMap.
-     * This provides automatic cleanup when config changes.
-     */
-    #setupValidationConfig() {
-        const form = this.ngForm.form;
-        toObservable(this.validationConfig)
-            .pipe(distinctUntilChanged(), switchMap((config) => {
-            // Cast to the expected type for the helper method
-            const typedConfig = config;
-            return this.#createValidationStreams(form, typedConfig);
-        }), takeUntilDestroyed(this.destroyRef))
-            .subscribe();
+    ngAfterContentInit() {
+        this.contentInitialized.set(true);
+        // ARIA wiring + observer setup is managed by effects so that the wrapper can
+        // opt out (ariaAssociationMode="none").
     }
-    /**
-     * Creates validation streams for the provided configuration.
-     * Returns EMPTY if config is null/undefined, otherwise merges all trigger field streams.
-     *
-     * @param form - The NgForm instance
-     * @param config - The validation configuration mapping trigger fields to dependent fields
-     * @returns Observable that emits when any trigger field changes and dependent fields need validation
-     */
-    #createValidationStreams(form, config) {
-        if (!config) {
-            this.validationInProgress.clear();
-            return EMPTY;
-        }
-        const streams = Object.keys(config).map((triggerField) => {
-            const dependents = config[triggerField] || [];
-            return this.#createTriggerStream(form, triggerField, dependents);
-        });
-        return streams.length > 0 ? merge(...streams) : EMPTY;
+    ngOnDestroy() {
+        this.mutationObserver?.disconnect();
+        this.mutationObserver = null;
     }
     /**
-     * Creates a stream for a single trigger field that revalidates its dependent fields.
-     *
-     * This method handles:
-     * 1. Waiting for the trigger control to exist in the form (for @if scenarios)
-     * 2. Listening to value changes with debouncing
-     * 3. Waiting for form to be idle before triggering dependents
-     * 4. Waiting for all dependent controls to exist
-     * 5. Updating dependent field validity with loop prevention
-     * 6. Touch state propagation from trigger to dependents
-     *
-     * @param form - The NgForm instance
-     * @param triggerField - Field path that triggers validation (e.g., 'password')
-     * @param dependents - Array of dependent field paths to revalidate (e.g., ['confirmPassword'])
-     * @returns Observable that completes after dependent fields are validated
+     * Query and update the list of form controls within this wrapper.
+     * Called on init and whenever the DOM structure changes.
      */
-    #createTriggerStream(form, triggerField, dependents) {
-        // Wait for trigger control to exist, then stop listening (take(1) prevents feedback loops)
-        const triggerControl$ = form.statusChanges.pipe(startWith(form.status), map(() => form.get(triggerField)), filter((c) => !!c), 
-        // CRITICAL: take(1) to stop listening after control is found
-        // Without this, the pipeline continues to listen to statusChanges,
-        // creating a feedback loop where validation triggers re-trigger the pipeline
-        take(1));
-        return triggerControl$.pipe(switchMap((control) => {
-            return control.valueChanges.pipe(
-            // CRITICAL: Filter out changes when this field is being validated by another field's config
-            // This prevents circular triggers in bidirectional validationConfig
-            filter(() => !this.validationInProgress.has(triggerField)), debounceTime(this.configDebounceTime), switchMap(() => {
-                return this.#waitForFormIdle(form, control);
-            }), switchMap(() => this.#waitForDependentControls(form, dependents, control)), tap(() => this.#updateDependentFields(form, control, triggerField, dependents)));
-        }));
+    updateFormControls() {
+        const controls = this.elementRef.nativeElement.querySelectorAll('input, select, textarea');
+        this.formControls.set(Array.from(controls));
     }
-    /**
-     * Waits for the form to reach a non-PENDING state before proceeding.
-     * This prevents validation race conditions where dependent field validation
-     * triggers while the trigger field's validation is still running.
-     *
-     * If the form stays PENDING for longer than 2 seconds (e.g., slow async validators),
-     * proceeds anyway to prevent blocking the validation pipeline.
-     *
-     * @param form - The NgForm instance
-     * @param control - The trigger control to pass through
-     * @returns Observable that emits the control once form is idle or timeout
-     */
-    #waitForFormIdle(form, control) {
-        // If form is already non-PENDING, return immediately
-        if (form.status !== 'PENDING') {
-            return of(control);
-        }
-        // Form is PENDING, wait for it to become idle
-        const idle$ = form.statusChanges.pipe(filter((s) => s !== 'PENDING'), take(1));
-        const timeout$ = timer(2000);
-        return race(idle$, timeout$).pipe(map(() => control));
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ControlWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.1", type: ControlWrapperComponent, isStandalone: true, selector: "ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]", inputs: { ariaAssociationMode: { classPropertyName: "ariaAssociationMode", publicName: "ariaAssociationMode", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class.ngx-control-wrapper--invalid": "errorDisplay.shouldShowErrors()", "attr.aria-busy": "errorDisplay.isPending() ? 'true' : null" }, classAttribute: "ngx-control-wrapper sc-control-wrapper" }, hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode", "warningDisplayMode", "warningDisplayMode"] }], ngImport: i0, template: "<div class=\"ngx-control-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  WCAG 2.2 AA Compliance for Inline Field Validation:\n\n  IMPORTANT DISTINCTION - Field-level vs Form-level errors:\n  - FIELD-LEVEL errors (this component): Use role=\"status\" with aria-live=\"polite\"\n    These are inline validation messages that appear as users interact with fields.\n    Using \"assertive\" would be too disruptive when users are filling out multiple fields.\n  - FORM-LEVEL blocking errors (e.g., submission failed): Should use role=\"alert\" with\n    aria-live=\"assertive\" in a separate form-level error summary component.\n\n  This component handles FIELD-LEVEL messages:\n  - Errors: role=\"status\" with aria-live=\"polite\" (non-disruptive, field is already\n    marked with aria-invalid=\"true\" and aria-describedby points here)\n  - Warnings: role=\"status\" with aria-live=\"polite\" (informational, doesn't block)\n  - Pending: role=\"status\" with aria-live=\"polite\" (status update)\n\n  The aria-invalid=\"true\" + aria-describedby association on the input provides\n  the primary accessibility pathway; the live region is supplementary.\n\n  @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA21 - Using aria-invalid\n  @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22 - Using role=status\n-->\n<div\n  [id]=\"errorId\"\n  class=\"text-sm text-red-600\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.shouldShowErrors()) {\n    <ul class=\"m-0 mt-1 list-none space-y-1 p-0\">\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!--\n  Warnings: Non-blocking validation messages (Vest warn())\n  - Use role=\"status\" with aria-live=\"polite\" per WCAG ARIA22\n  - Default: show after validation runs or touch; configurable to require touch only\n  - Warnings do NOT affect field validity - they're informational only\n-->\n<div\n  [id]=\"warningId\"\n  class=\"text-sm text-yellow-700\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (shouldShowWarnings()) {\n    <ul class=\"m-0 mt-1 list-none space-y-1 p-0\">\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!-- Pending state is also stable; content appears only after the debounce delay -->\n<div\n  [id]=\"pendingId\"\n  class=\"absolute top-0 right-0 flex items-center gap-1 text-xs text-gray-500\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (showPendingMessage()) {\n    <span\n      class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      aria-hidden=\"true\"\n    ></span>\n    Validating\u2026\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ControlWrapperComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-control-wrapper, sc-control-wrapper, [scControlWrapper], [ngxControlWrapper], [ngx-control-wrapper], [sc-control-wrapper]', changeDetection: ChangeDetectionStrategy.OnPush, host: {
+                        class: 'ngx-control-wrapper sc-control-wrapper',
+                        '[class.ngx-control-wrapper--invalid]': 'errorDisplay.shouldShowErrors()',
+                        '[attr.aria-busy]': "errorDisplay.isPending() ? 'true' : null",
+                    }, hostDirectives: [
+                        {
+                            directive: FormErrorDisplayDirective,
+                            inputs: ['errorDisplayMode', 'warningDisplayMode'],
+                        },
+                    ], template: "<div class=\"ngx-control-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  WCAG 2.2 AA Compliance for Inline Field Validation:\n\n  IMPORTANT DISTINCTION - Field-level vs Form-level errors:\n  - FIELD-LEVEL errors (this component): Use role=\"status\" with aria-live=\"polite\"\n    These are inline validation messages that appear as users interact with fields.\n    Using \"assertive\" would be too disruptive when users are filling out multiple fields.\n  - FORM-LEVEL blocking errors (e.g., submission failed): Should use role=\"alert\" with\n    aria-live=\"assertive\" in a separate form-level error summary component.\n\n  This component handles FIELD-LEVEL messages:\n  - Errors: role=\"status\" with aria-live=\"polite\" (non-disruptive, field is already\n    marked with aria-invalid=\"true\" and aria-describedby points here)\n  - Warnings: role=\"status\" with aria-live=\"polite\" (informational, doesn't block)\n  - Pending: role=\"status\" with aria-live=\"polite\" (status update)\n\n  The aria-invalid=\"true\" + aria-describedby association on the input provides\n  the primary accessibility pathway; the live region is supplementary.\n\n  @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA21 - Using aria-invalid\n  @see https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22 - Using role=status\n-->\n<div\n  [id]=\"errorId\"\n  class=\"text-sm text-red-600\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (errorDisplay.shouldShowErrors()) {\n    <ul class=\"m-0 mt-1 list-none space-y-1 p-0\">\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!--\n  Warnings: Non-blocking validation messages (Vest warn())\n  - Use role=\"status\" with aria-live=\"polite\" per WCAG ARIA22\n  - Default: show after validation runs or touch; configurable to require touch only\n  - Warnings do NOT affect field validity - they're informational only\n-->\n<div\n  [id]=\"warningId\"\n  class=\"text-sm text-yellow-700\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (shouldShowWarnings()) {\n    <ul class=\"m-0 mt-1 list-none space-y-1 p-0\">\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<!-- Pending state is also stable; content appears only after the debounce delay -->\n<div\n  [id]=\"pendingId\"\n  class=\"absolute top-0 right-0 flex items-center gap-1 text-xs text-gray-500\"\n  role=\"status\"\n  aria-live=\"polite\"\n  aria-atomic=\"true\"\n>\n  @if (showPendingMessage()) {\n    <span\n      class=\"inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent\"\n      aria-hidden=\"true\"\n    ></span>\n    Validating\u2026\n  }\n</div>\n", styles: [":host{display:block;position:relative}\n"] }]
+        }], ctorParameters: () => [], propDecorators: { ariaAssociationMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaAssociationMode", required: false }] }] } });
+
+let nextUniqueId$1 = 0;
+/**
+ * Group-safe wrapper for `NgModelGroup` containers.
+ *
+ * This component renders group-level errors/warnings/pending UI, but intentionally
+ * does **not** stamp `aria-describedby` / `aria-invalid` onto descendant controls.
+ *
+ * Use this when you want a wrapper around a container that has multiple inputs.
+ * For single inputs, prefer `<ngx-control-wrapper>`.
+ */
+class FormGroupWrapperComponent {
+    constructor() {
+        this.errorDisplay = inject(FormErrorDisplayDirective, {
+            self: true,
+        });
+        /**
+         * Controls the debounce behavior for the pending message.
+         * Defaults are conservative to avoid flashing.
+         */
+        this.pendingDebounce = input({
+            showAfter: 500,
+            minimumDisplay: 500,
+        }, ...(ngDevMode ? [{ debugName: "pendingDebounce" }] : []));
+        this.uniqueId = `ngx-form-group-wrapper-${nextUniqueId$1++}`;
+        this.errorId = `${this.uniqueId}-error`;
+        this.warningId = `${this.uniqueId}-warning`;
+        this.pendingId = `${this.uniqueId}-pending`;
+        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, this.pendingDebounce());
+        this.showPendingMessage = this.pendingState.showPendingMessage;
+        /**
+         * Helpful if consumers want to wire aria-describedby manually (e.g. fieldset/legend pattern).
+         */
+        this.describedByIds = computed(() => {
+            const ids = [];
+            if (this.errorDisplay.shouldShowErrors()) {
+                ids.push(this.errorId);
+            }
+            if (this.errorDisplay.warnings().length > 0) {
+                ids.push(this.warningId);
+            }
+            if (this.showPendingMessage()) {
+                ids.push(this.pendingId);
+            }
+            return ids.length > 0 ? ids.join(' ') : null;
+        }, ...(ngDevMode ? [{ debugName: "describedByIds" }] : []));
     }
-    /**
-     * Waits for all dependent controls to exist in the form.
-     * This handles @if scenarios where controls are conditionally rendered.
-     *
-     * @param form - The NgForm instance
-     * @param dependents - Array of dependent field paths
-     * @param control - The trigger control to pass through
-     * @returns Observable that emits the control once all dependents exist
-     */
-    #waitForDependentControls(form, dependents, control) {
-        const allDependentsExist = dependents.every((depField) => !!form.get(depField));
-        if (allDependentsExist) {
-            return of(control);
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormGroupWrapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.1", type: FormGroupWrapperComponent, isStandalone: true, selector: "ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper], [ngx-form-group-wrapper], [sc-form-group-wrapper]", inputs: { pendingDebounce: { classPropertyName: "pendingDebounce", publicName: "pendingDebounce", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class.ngx-form-group-wrapper--invalid": "errorDisplay.shouldShowErrors()", "attr.aria-busy": "errorDisplay.isPending() ? 'true' : null" }, classAttribute: "ngx-form-group-wrapper sc-form-group-wrapper" }, exportAs: ["formGroupWrapper", "ngxFormGroupWrapper"], hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0, template: "<div class=\"ngx-form-group-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Keep regions stable in the DOM so IDs are always valid targets.\n  This wrapper does NOT modify descendant controls.\n-->\n<div [id]=\"errorId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.shouldShowErrors() && errorDisplay.errors().length > 0) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"warningId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"pendingId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (showPendingMessage()) {\n    <span aria-hidden=\"true\">Validating\u2026</span>\n  }\n</div>\n", styles: [":host{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormGroupWrapperComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-form-group-wrapper, sc-form-group-wrapper, [ngxFormGroupWrapper], [scFormGroupWrapper], [ngx-form-group-wrapper], [sc-form-group-wrapper]', exportAs: 'formGroupWrapper, ngxFormGroupWrapper', changeDetection: ChangeDetectionStrategy.OnPush, host: {
+                        class: 'ngx-form-group-wrapper sc-form-group-wrapper',
+                        '[class.ngx-form-group-wrapper--invalid]': 'errorDisplay.shouldShowErrors()',
+                        '[attr.aria-busy]': "errorDisplay.isPending() ? 'true' : null",
+                    }, hostDirectives: [
+                        {
+                            directive: FormErrorDisplayDirective,
+                            inputs: ['errorDisplayMode'],
+                        },
+                    ], template: "<div class=\"ngx-form-group-wrapper__content\">\n  <ng-content />\n</div>\n\n<!--\n  Keep regions stable in the DOM so IDs are always valid targets.\n  This wrapper does NOT modify descendant controls.\n-->\n<div [id]=\"errorId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.shouldShowErrors() && errorDisplay.errors().length > 0) {\n    <ul>\n      @for (error of errorDisplay.errors(); track error) {\n        <li>{{ error }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"warningId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (errorDisplay.warnings().length > 0) {\n    <ul>\n      @for (warn of errorDisplay.warnings(); track warn) {\n        <li>{{ warn }}</li>\n      }\n    </ul>\n  }\n</div>\n\n<div [id]=\"pendingId\" role=\"status\" aria-live=\"polite\" aria-atomic=\"true\">\n  @if (showPendingMessage()) {\n    <span aria-hidden=\"true\">Validating\u2026</span>\n  }\n</div>\n", styles: [":host{display:block}\n"] }]
+        }], propDecorators: { pendingDebounce: [{ type: i0.Input, args: [{ isSignal: true, alias: "pendingDebounce", required: false }] }] } });
+
+let nextUniqueId = 0;
+/**
+ * Wires a control container to its error/warning/pending regions.
+ *
+ * This directive is intended for custom wrappers/components.
+ * It composes `FormErrorDisplayDirective` (and thus `FormControlStateDirective`)
+ * and applies `aria-invalid` / `aria-describedby` to descendant controls.
+ *
+ * It does not render any UI; you can use the generated IDs to render messages.
+ */
+class FormErrorControlDirective {
+    mergeAriaDescribedBy(existing, activeIds) {
+        const existingTokens = (existing ?? '')
+            .split(/\s+/)
+            .map((t) => t.trim())
+            .filter(Boolean);
+        const existingWithoutOwned = existingTokens.filter((t) => !this.ownedDescribedByIds.includes(t));
+        const merged = [...existingWithoutOwned];
+        for (const id of activeIds) {
+            if (!merged.includes(id)) {
+                merged.push(id);
+            }
         }
-        // Wait for dependent controls to be added to the form
-        return form.statusChanges.pipe(startWith(form.status), filter(() => dependents.every((depField) => !!form.get(depField))), take(1), map(() => control));
+        return merged.length > 0 ? merged.join(' ') : null;
     }
-    /**
-     * Updates validation for all dependent fields.
-     *
-     * Handles:
-     * - Touch state propagation (mark dependents touched when trigger is touched)
-     * - Loop prevention via validationInProgress set
-     * - Silent validation (emitEvent: false) to prevent feedback loops
-     *
-     * @param form - The NgForm instance
-     * @param control - The trigger control
-     * @param triggerField - Field path of the trigger
-     * @param dependents - Array of dependent field paths to update
-     */
-    #updateDependentFields(form, control, triggerField, dependents) {
-        // Mark trigger field as in-progress to prevent it from being re-triggered
-        this.validationInProgress.add(triggerField);
-        for (const depField of dependents) {
-            const dependentControl = form.get(depField);
-            if (!dependentControl) {
-                continue;
+    constructor() {
+        this.errorDisplay = inject(FormErrorDisplayDirective, {
+            self: true,
+        });
+        this.elementRef = inject((ElementRef));
+        /**
+         * Controls how this directive applies ARIA attributes to descendant controls.
+         *
+         * - `all-controls` (default): apply ARIA attributes to all input/select/textarea descendants.
+         * - `single-control`: apply ARIA attributes only when exactly one control is found.
+         * - `none`: do not mutate descendant controls.
+         */
+        this.ariaAssociationMode = input('all-controls', ...(ngDevMode ? [{ debugName: "ariaAssociationMode" }] : []));
+        /**
+         * Unique ID prefix for this instance.
+         * Use these IDs to render message regions and to support aria-describedby.
+         */
+        this.uniqueId = `ngx-error-control-${nextUniqueId++}`;
+        this.errorId = `${this.uniqueId}-error`;
+        this.warningId = `${this.uniqueId}-warning`;
+        this.pendingId = `${this.uniqueId}-pending`;
+        this.formControls = signal([], ...(ngDevMode ? [{ debugName: "formControls" }] : []));
+        this.contentInitialized = signal(false, ...(ngDevMode ? [{ debugName: "contentInitialized" }] : []));
+        this.mutationObserver = null;
+        this.pendingState = createDebouncedPendingState(this.errorDisplay.isPending, { showAfter: 500, minimumDisplay: 500 });
+        this.showPendingMessage = this.pendingState.showPendingMessage;
+        /**
+         * aria-describedby value representing the *currently relevant* message regions.
+         */
+        this.ariaDescribedBy = computed(() => {
+            const ids = [];
+            if (this.errorDisplay.shouldShowErrors()) {
+                ids.push(this.errorId);
             }
-            // Only validate if not already in progress (prevents bidirectional loops)
-            if (!this.validationInProgress.has(depField)) {
-                // CRITICAL: Mark the dependent field as in-progress BEFORE calling updateValueAndValidity
-                // This prevents the dependent field's valueChanges from triggering its own validationConfig
-                this.validationInProgress.add(depField);
-                // Propagate touch state BEFORE validation to avoid duplicate class updates
-                // markAsTouched() triggers change detection, so we do it once before updateValueAndValidity
-                if (control.touched && !dependentControl.touched) {
-                    dependentControl.markAsTouched({ onlySelf: true });
+            if (this.errorDisplay.warnings().length > 0) {
+                ids.push(this.warningId);
+            }
+            if (this.showPendingMessage()) {
+                ids.push(this.pendingId);
+            }
+            return ids.length > 0 ? ids.join(' ') : null;
+        }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
+        this.ownedDescribedByIds = [
+            this.errorId,
+            this.warningId,
+            this.pendingId,
+        ];
+        // Effect for ARIA attribute updates
+        effect(() => {
+            if (!this.contentInitialized())
+                return;
+            const mode = this.ariaAssociationMode();
+            if (mode === 'none')
+                return;
+            const describedBy = this.ariaDescribedBy();
+            const activeIds = describedBy
+                ? describedBy.split(/\s+/).filter(Boolean)
+                : [];
+            const shouldShowErrors = this.errorDisplay.shouldShowErrors();
+            const targets = (() => {
+                const controls = this.formControls();
+                if (mode === 'single-control') {
+                    return controls.length === 1 ? controls : [];
+                }
+                return controls;
+            })();
+            for (const control of targets) {
+                const nextDescribedBy = this.mergeAriaDescribedBy(control.getAttribute('aria-describedby'), activeIds);
+                if (nextDescribedBy) {
+                    control.setAttribute('aria-describedby', nextDescribedBy);
+                }
+                else {
+                    control.removeAttribute('aria-describedby');
+                }
+                if (shouldShowErrors) {
+                    control.setAttribute('aria-invalid', 'true');
+                }
+                else {
+                    control.removeAttribute('aria-invalid');
                 }
-                // emitEvent: true is REQUIRED for async validators to actually run
-                // The validationInProgress Set prevents infinite loops:
-                // 1. Field A changes → triggers validation on dependent field B
-                // 2. B is added to validationInProgress Set
-                // 3. B's statusChanges emits → #handleValueChange checks validationInProgress
-                // 4. Since B is in validationInProgress, its validationConfig is not triggered
-                // 5. After 500ms timeout, B is removed from validationInProgress
-                // This way:
-                // - Async validators CAN run (emitEvent: true)
-                // - BUT circular triggers are prevented (validationInProgress check)
-                dependentControl.updateValueAndValidity({
-                    onlySelf: true,
-                    emitEvent: true, // Changed from false - REQUIRED for validators to run!
-                });
-                // CRITICAL: Force immediate change detection for OnPush components
-                // updateValueAndValidity updates the control's status, but doesn't automatically
-                // trigger change detection. Components using OnPush won't see the ng-invalid class
-                // update in the DOM without this. Using detectChanges() instead of markForCheck()
-                // to force immediate synchronous update rather than waiting for next CD cycle.
-                this.cdr.detectChanges();
             }
-        }
-        // Keep fields marked as in-progress for a short time to prevent immediate re-triggering
-        // Use setTimeout to ensure async validators have time to complete before allowing new triggers
-        // INCREASED from 100ms to 500ms to fix bidirectional validation issues with password/date fields
-        // This gives validators enough time to complete and propagate before allowing re-triggering
-        // Bidirectional validations need more time because both fields validate each other
-        setTimeout(() => {
-            this.validationInProgress.delete(triggerField);
-            for (const depField of dependents) {
-                this.validationInProgress.delete(depField);
+        });
+        // Effect for MutationObserver setup with proper cleanup
+        effect((onCleanup) => {
+            if (!this.contentInitialized())
+                return;
+            const mode = this.ariaAssociationMode();
+            if (mode === 'none') {
+                this.mutationObserver?.disconnect();
+                this.mutationObserver = null;
+                if (this.formControls().length > 0) {
+                    this.formControls.set([]);
+                }
+                return;
+            }
+            this.updateFormControls();
+            if (!this.mutationObserver) {
+                this.mutationObserver = new MutationObserver(() => {
+                    this.updateFormControls();
+                });
+                this.mutationObserver.observe(this.elementRef.nativeElement, {
+                    childList: true,
+                    subtree: true,
+                });
             }
-        }, 500);
+            // Proper cleanup using onCleanup callback (Angular 21 best practice)
+            onCleanup(() => {
+                this.mutationObserver?.disconnect();
+                this.mutationObserver = null;
+            });
+        });
+    }
+    ngAfterContentInit() {
+        this.contentInitialized.set(true);
+    }
+    ngOnDestroy() {
+        this.mutationObserver?.disconnect();
+        this.mutationObserver = null;
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: FormDirective, isStandalone: true, selector: "form[scVestForm], form[ngxVestForm]", inputs: { formValue: { classPropertyName: "formValue", publicName: "formValue", isSignal: true, isRequired: false, transformFunction: null }, suite: { classPropertyName: "suite", publicName: "suite", isSignal: true, isRequired: false, transformFunction: null }, formShape: { classPropertyName: "formShape", publicName: "formShape", isSignal: true, isRequired: false, transformFunction: null }, validationConfig: { classPropertyName: "validationConfig", publicName: "validationConfig", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { formValueChange: "formValueChange", errorsChange: "errorsChange", dirtyChange: "dirtyChange", validChange: "validChange" }, exportAs: ["scVestForm", "ngxVestForm"], ngImport: i0 }); }
+    updateFormControls() {
+        const controls = this.elementRef.nativeElement.querySelectorAll('input, select, textarea');
+        this.formControls.set(Array.from(controls));
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormErrorControlDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: FormErrorControlDirective, isStandalone: true, selector: "[formErrorControl], [ngxErrorControl]", inputs: { ariaAssociationMode: { classPropertyName: "ariaAssociationMode", publicName: "ariaAssociationMode", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["formErrorControl", "ngxErrorControl"], hostDirectives: [{ directive: FormErrorDisplayDirective, inputs: ["errorDisplayMode", "errorDisplayMode"] }], ngImport: i0 }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormDirective, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormErrorControlDirective, decorators: [{
             type: Directive,
             args: [{
-                    selector: 'form[scVestForm], form[ngxVestForm]',
-                    exportAs: 'scVestForm, ngxVestForm',
+                    selector: '[formErrorControl], [ngxErrorControl]',
+                    exportAs: 'formErrorControl, ngxErrorControl',
+                    hostDirectives: [
+                        {
+                            directive: FormErrorDisplayDirective,
+                            inputs: ['errorDisplayMode'],
+                        },
+                    ],
                 }]
-        }], ctorParameters: () => [], propDecorators: { formValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "formValue", required: false }] }], suite: [{ type: i0.Input, args: [{ isSignal: true, alias: "suite", required: false }] }], formShape: [{ type: i0.Input, args: [{ isSignal: true, alias: "formShape", required: false }] }], validationConfig: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationConfig", required: false }] }], formValueChange: [{ type: i0.Output, args: ["formValueChange"] }], errorsChange: [{ type: i0.Output, args: ["errorsChange"] }], dirtyChange: [{ type: i0.Output, args: ["dirtyChange"] }], validChange: [{ type: i0.Output, args: ["validChange"] }] } });
+        }], ctorParameters: () => [], propDecorators: { ariaAssociationMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaAssociationMode", required: false }] }] } });
 
 /**
  * Hooks into the ngModelGroup selector and triggers an asynchronous validation for a form group
@@ -2511,8 +2715,8 @@ class FormModelGroupDirective {
             return of(null);
         }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormModelGroupDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: FormModelGroupDirective, isStandalone: true, selector: "[ngModelGroup],[ngxModelGroup]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormModelGroupDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: FormModelGroupDirective, isStandalone: true, selector: "[ngModelGroup],[ngxModelGroup]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
             {
                 provide: NG_ASYNC_VALIDATORS,
                 useExisting: FormModelGroupDirective,
@@ -2520,7 +2724,7 @@ class FormModelGroupDirective {
             },
         ], ngImport: i0 }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormModelGroupDirective, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormModelGroupDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: '[ngModelGroup],[ngxModelGroup]',
@@ -2578,8 +2782,8 @@ class FormModelDirective {
             return of(null);
         }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormModelDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: FormModelDirective, isStandalone: true, selector: "[ngModel],[ngxModel]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormModelDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: FormModelDirective, isStandalone: true, selector: "[ngModel],[ngxModel]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
             {
                 provide: NG_ASYNC_VALIDATORS,
                 useExisting: FormModelDirective,
@@ -2587,7 +2791,7 @@ class FormModelDirective {
             },
         ], ngImport: i0 }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: FormModelDirective, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: FormModelDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: '[ngModel],[ngxModel]',
@@ -2824,8 +3028,8 @@ class ValidateRootFormDirective {
             }), take(1), takeUntilDestroyed(this.destroyRef));
         };
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: ValidateRootFormDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
-    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.0", type: ValidateRootFormDirective, isStandalone: true, selector: "form[validateRootForm], form[ngxValidateRootForm]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null }, formValue: { classPropertyName: "formValue", publicName: "formValue", isSignal: true, isRequired: false, transformFunction: null }, suite: { classPropertyName: "suite", publicName: "suite", isSignal: true, isRequired: false, transformFunction: null }, validateRootForm: { classPropertyName: "validateRootForm", publicName: "validateRootForm", isSignal: true, isRequired: false, transformFunction: null }, ngxValidateRootForm: { classPropertyName: "ngxValidateRootForm", publicName: "ngxValidateRootForm", isSignal: true, isRequired: false, transformFunction: null }, validateRootFormMode: { classPropertyName: "validateRootFormMode", publicName: "validateRootFormMode", isSignal: true, isRequired: false, transformFunction: null }, ngxValidateRootFormMode: { classPropertyName: "ngxValidateRootFormMode", publicName: "ngxValidateRootFormMode", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ValidateRootFormDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive }); }
+    static { this.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.1.1", type: ValidateRootFormDirective, isStandalone: true, selector: "form[validateRootForm], form[ngxValidateRootForm]", inputs: { validationOptions: { classPropertyName: "validationOptions", publicName: "validationOptions", isSignal: true, isRequired: false, transformFunction: null }, formValue: { classPropertyName: "formValue", publicName: "formValue", isSignal: true, isRequired: false, transformFunction: null }, suite: { classPropertyName: "suite", publicName: "suite", isSignal: true, isRequired: false, transformFunction: null }, validateRootForm: { classPropertyName: "validateRootForm", publicName: "validateRootForm", isSignal: true, isRequired: false, transformFunction: null }, ngxValidateRootForm: { classPropertyName: "ngxValidateRootForm", publicName: "ngxValidateRootForm", isSignal: true, isRequired: false, transformFunction: null }, validateRootFormMode: { classPropertyName: "validateRootFormMode", publicName: "validateRootFormMode", isSignal: true, isRequired: false, transformFunction: null }, ngxValidateRootFormMode: { classPropertyName: "ngxValidateRootFormMode", publicName: "ngxValidateRootFormMode", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
             {
                 provide: NG_ASYNC_VALIDATORS,
                 useExisting: ValidateRootFormDirective,
@@ -2833,7 +3037,7 @@ class ValidateRootFormDirective {
             },
         ], ngImport: i0 }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: ValidateRootFormDirective, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ValidateRootFormDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: 'form[validateRootForm], form[ngxValidateRootForm]',
@@ -3693,5 +3897,5 @@ function keepFieldsWhen(currentState, conditions) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=ngx-vest-forms.mjs.map