ngx-vest-forms 2.5.0 → 2.6.0

package/README.md

@@ -401,6 +401,7 @@ const shape: NgxDeepRequired<MyFormModel> = {
 ### Advanced Patterns
 
 - **[ValidationConfig vs Root-Form](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)** - Cross-field dependencies and form-level rules
+- **[Clear Submitted State](./docs/CLEAR-SUBMITTED-STATE.md)** - End a submit cycle without resetting values or control metadata
 - **[Field Path Types](./docs/FIELD-PATHS.md)** - Type-safe dot-notation paths for nested properties
 - **[Structure Change Detection](./docs/STRUCTURE_CHANGE_DETECTION.md)** - Handle dynamic form structure updates
 - **[Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md)** - Type-safe utilities for clearing nested form values

package/fesm2022/ngx-vest-forms.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, isDevMode, inject, ElementRef, DestroyRef, ChangeDetectorRef, signal, linkedSignal, computed, input, effect, untracked, Directive, contentChild, Injector, afterEveryRender, ChangeDetectionStrategy, Component, booleanAttribute, Optional } from '@angular/core';
-import { isFormArray, isFormGroup, NgForm, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, FormGroup, FormArray, NgModel, NgModelGroup, NG_ASYNC_VALIDATORS, ControlContainer, FormsModule } from '@angular/forms';
+import { InjectionToken, isDevMode, signal, inject, ElementRef, DestroyRef, ChangeDetectorRef, linkedSignal, computed, input, effect, untracked, Directive, contentChild, Injector, afterEveryRender, ChangeDetectionStrategy, Component, booleanAttribute, Optional } from '@angular/core';
+import { isFormArray, isFormGroup, NgForm, StatusChangeEvent, ValueChangeEvent, PristineChangeEvent, FormGroup, FormArray, NgModel, NgModelGroup, FormSubmittedEvent, FormResetEvent, NG_ASYNC_VALIDATORS, ControlContainer, FormsModule } from '@angular/forms';
 import { toSignal, outputFromObservable, takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 import { startWith, merge, filter, map, switchMap, take, of, scan, distinctUntilChanged, timer, Observable, catchError, EMPTY, debounceTime, tap, race, from } from 'rxjs';
 
@@ -896,6 +896,46 @@ function validateFormValueAgainstShape(formValue, shape, path = '') {
     }
 }
 
+const formSubmittedSignals = new WeakMap();
+function getFormSubmittedSignal(ngForm) {
+    let submitted = formSubmittedSignals.get(ngForm);
+    if (!submitted) {
+        submitted = signal(ngForm.submitted);
+        formSubmittedSignals.set(ngForm, submitted);
+    }
+    return submitted;
+}
+function setAngularFormSubmittedState(ngForm, submitted) {
+    // Angular 21.x's concrete NgForm stores submitted state on
+    // `submittedReactive`, while AbstractFormDirective-backed implementations
+    // expose `_submittedReactive` and may also provide a public setter on
+    // `submitted`. This helper is verified against Angular 21.x in this
+    // repository and falls back to the first writable `submitted` setter it can
+    // find if a future Angular version changes the concrete field names.
+    //
+    // We try the concrete/internal signal first because NgForm overrides the
+    // getter-only `submitted` property at runtime in this workspace. If neither
+    // signal exists, fall back to the first writable `submitted` setter we can
+    // find on the prototype chain. If no setter exists either, callers should
+    // still update ngx-vest-forms' shared signal so error display state remains
+    // reactive even though Angular's native submitted flag cannot be changed.
+    const signalHost = ngForm;
+    const angularSignal = signalHost.submittedReactive ?? signalHost._submittedReactive;
+    if (angularSignal) {
+        angularSignal.set(submitted);
+        return;
+    }
+    let prototype = Object.getPrototypeOf(ngForm);
+    while (prototype) {
+        const submittedDescriptor = Object.getOwnPropertyDescriptor(prototype, 'submitted');
+        if (submittedDescriptor?.set) {
+            submittedDescriptor.set.call(ngForm, submitted);
+            return;
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+}
+
 /**
  * Duration (in milliseconds) to keep fields marked as "in-progress" after validation.
  * This prevents immediate re-triggering of bidirectional validations.
@@ -1364,6 +1404,52 @@ class FormDirective {
         this.ngForm.form.markAllAsTouched();
         this.#blurTick.update((v) => v + 1);
     }
+    /**
+     * Clears the current submit cycle without resetting control values or metadata.
+     *
+     * Unlike {@link resetForm}, this only flips the submitted gate back to `false`.
+     * Touched/dirty/pristine state is preserved so consumers can end `'on-submit'`
+     * error visibility without a full form reset.
+     *
+     * **When to use:**
+     * - You use submit-gated error visibility such as `'on-submit'`
+     * - A submit attempt already happened
+     * - The user resolved the current submit-time errors
+     * - You want future untouched fields to wait for the next submit before showing errors
+     *
+     * **Why this exists:**
+     * `resetForm()` would also clear touched/dirty/pristine metadata, which is often
+     * too disruptive for long-form, multi-form, or mixed error-display flows.
+     *
+     * **What it does NOT do:**
+     * - Does not change field values
+     * - Does not mark controls pristine or untouched
+     * - Does not re-run validation
+     *
+     * @example
+     * ```typescript
+     * submitAll(): void {
+     *   for (const form of this.submitForms()) {
+     *     form.ngForm.onSubmit(new Event('submit'));
+     *   }
+     *
+     *   if (this.submitForms().every((form) => form.formState().valid)) {
+     *     for (const form of this.submitForms()) {
+     *       form.clearSubmittedState();
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link resetForm} to fully reset values and control metadata
+     * @see {@link markAllAsTouched} to manually show all errors
+     * @see {@link triggerFormValidation} to re-run validation after structure changes
+     */
+    clearSubmittedState() {
+        setAngularFormSubmittedState(this.ngForm, false);
+        getFormSubmittedSignal(this.ngForm).set(false);
+        this.#blurTick.update((v) => v + 1);
+    }
     /**
      * Finds the first invalid element in this form, scrolls it into view, and focuses it.
      *
@@ -2178,15 +2264,14 @@ class FormErrorDisplayDirective {
     #formControlState;
     // Optionally inject NgForm for form submission tracking
     #ngForm;
-    /**
-     * Internal trigger signal that updates whenever form submit or status changes.
-     * Used to ensure reactive tracking for the formSubmitted computed signal.
-     */
-    #formEventTrigger;
+    #formSubmittedState;
     constructor() {
         this.#formControlState = inject(FormControlStateDirective);
         // Optionally inject NgForm for form submission tracking
         this.#ngForm = inject(NgForm, { optional: true });
+        this.#formSubmittedState = this.#ngForm
+            ? getFormSubmittedSignal(this.#ngForm)
+            : signal(false);
         /**
          * Input signal for error display mode.
          * Works seamlessly with hostDirectives in Angular 19+.
@@ -2216,27 +2301,16 @@ class FormErrorDisplayDirective {
          * formSubmitted: true after the form is submitted (if NgForm is present)
          */
         this.updateOn = this.#formControlState.updateOn;
-        /**
-         * Internal trigger signal that updates whenever form submit or status changes.
-         * Used to ensure reactive tracking for the formSubmitted computed signal.
-         */
-        this.#formEventTrigger = this.#ngForm
-            ? toSignal(merge(this.#ngForm.ngSubmit, this.#ngForm.statusChanges ?? of()).pipe(startWith(null)), { initialValue: null })
-            : signal(null);
         /**
          * Signal that tracks NgForm.submitted state reactively.
          *
-         * 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)
+         * Map form-level submit/reset events directly to boolean state.
          *
-         * This ensures proper sync with both submit and reset operations.
+         * This keeps programmatic `NgForm.onSubmit()` reactive in zoneless mode and
+         * avoids depending on `NgForm.submitted`, whose getter intentionally reads an
+         * internal signal with `untracked()`.
          */
-        this.formSubmitted = computed(() => {
-            // Trigger signal ensures this recomputes on submit/status changes
-            this.#formEventTrigger();
-            return this.#ngForm?.submitted ?? false;
-        }, ...(ngDevMode ? [{ debugName: "formSubmitted" }] : []));
+        this.formSubmitted = this.#formSubmittedState;
         /**
          * Determines if errors should be shown based on the specified display mode
          * and the control's state (touched/submitted/validated).
@@ -2355,6 +2429,16 @@ class FormErrorDisplayDirective {
                     return hasBeenValidated || isTouched || formSubmitted;
             }
         }, ...(ngDevMode ? [{ debugName: "shouldShowWarnings" }] : []));
+        const ngForm = this.#ngForm;
+        if (ngForm) {
+            ngForm.form.events
+                .pipe(filter((event) => event.source === ngForm.form &&
+                (event instanceof FormSubmittedEvent ||
+                    event instanceof FormResetEvent)), map((event) => event instanceof FormSubmittedEvent), startWith(ngForm.submitted), takeUntilDestroyed())
+                .subscribe((submitted) => {
+                this.#formSubmittedState.set(submitted);
+            });
+        }
         // Warn about problematic combinations of updateOn and errorDisplayMode
         effect(() => {
             const mode = this.errorDisplayMode();