ngx-vest-forms 2.5.1 → 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,5 +1,5 @@
 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 { 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,10 +2264,14 @@ class FormErrorDisplayDirective {
     #formControlState;
     // Optionally inject NgForm for form submission tracking
     #ngForm;
+    #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+.
@@ -2220,14 +2310,7 @@ class FormErrorDisplayDirective {
          * avoids depending on `NgForm.submitted`, whose getter intentionally reads an
          * internal signal with `untracked()`.
          */
-        this.formSubmitted = this.#ngForm
-            ? (() => {
-                const ngForm = this.#ngForm;
-                return toSignal(ngForm.form.events.pipe(filter((event) => event.source === ngForm.form &&
-                    (event instanceof FormSubmittedEvent ||
-                        event instanceof FormResetEvent)), map((event) => event instanceof FormSubmittedEvent), startWith(ngForm.submitted)), { initialValue: ngForm.submitted });
-            })()
-            : signal(false);
+        this.formSubmitted = this.#formSubmittedState;
         /**
          * Determines if errors should be shown based on the specified display mode
          * and the control's state (touched/submitted/validated).
@@ -2346,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();