ngx-vest-forms 2.5.1 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-vest-forms",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "license": "MIT",
   "author": "Brecht Billiet, Arjen Althoff",
   "description": "Opinionated template-driven forms library for Angular with Vest.js integration",
@@ -42,5 +42,6 @@
       "types": "./types/ngx-vest-forms.d.ts",
       "default": "./fesm2022/ngx-vest-forms.mjs"
     }
-  }
+  },
+  "type": "module"
 }

package/types/ngx-vest-forms.d.ts

@@ -85,7 +85,8 @@ declare class FormControlStateDirective {
     /**
      * 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 is primarily used for warning display and other derived state that should react
+     * to validationConfig-triggered validation even before the user touches the field.
      */
     readonly hasBeenValidated: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormControlStateDirective, never>;
@@ -144,21 +145,26 @@ declare class FormErrorDisplayDirective {
      * This keeps programmatic `NgForm.onSubmit()` reactive in zoneless mode and
      * avoids depending on `NgForm.submitted`, whose getter intentionally reads an
      * internal signal with `untracked()`.
+     *
+     * Note: when this directive is used outside an `NgForm` (no parent form), no
+     * subscription is wired up and this signal stays `false` for the lifetime of
+     * the directive. Consumers relying on submitted state must host the field
+     * inside an `NgForm` (or `ngxVestForm`).
      */
     readonly formSubmitted: Signal<boolean>;
     constructor();
     /**
      * Determines if errors should be shown based on the specified display mode
-     * and the control's state (touched/submitted/validated).
+     * and the control's state (touched/submitted/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.
      *
-     * 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.
+     * For validationConfig-triggered validations, a field may become invalid before it has been
+     * touched. Error visibility still respects the field's own `errorDisplayMode`, so untouched
+     * dependent fields can remain visually quiet until blur or submit.
      */
     readonly shouldShowErrors: Signal<boolean>;
     /**
@@ -993,6 +999,34 @@ type NgxTypedVestSuite<T> = StaticSuite<string, string, NgxTypedSuiteCallback<T>
  * This ensures backward compatibility while supporting the new typed API.
  */
 type NgxValidationConfig<T = unknown> = Record<string, string[]> | ValidationConfigMap<T> | null;
+/**
+ * Payload emitted when a named control inside the form loses focus.
+ *
+ * This is intentionally low-level so app code can build workflows such as
+ * draft auto-save, analytics, or blur-driven side effects without the form
+ * library taking ownership of persistence behavior.
+ *
+ * It is not intended as a blur-time workaround for dependent field validation;
+ * for that pattern, prefer `validationConfig` plus each target field's own
+ * `errorDisplayMode`.
+ *
+ * The emitted `field` is the full dotted control path (e.g.
+ * `passwords.confirm`, `businessHours.values.0.from`) regardless of whether
+ * the surrounding groups use static `ngModelGroup="key"` or dynamic
+ * `[ngModelGroup]="expr"` bindings, because the path is read from the live
+ * `NgModel` directive registered with the form.
+ *
+ * @publicApi
+ */
+type NgxFieldBlurEvent<T = unknown> = {
+    field: string;
+    value: unknown;
+    formValue: T | null;
+    dirty: boolean;
+    touched: boolean;
+    valid: boolean;
+    pending: boolean;
+};
 /**
  * Main form directive for ngx-vest-forms that bridges Angular template-driven forms with Vest.js validation.
  *
@@ -1142,6 +1176,12 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * Cleanup is handled automatically by the directive when it's destroyed.
      */
     readonly validChange: _angular_core.OutputRef<boolean>;
+    /**
+     * Emits when a named control inside the form loses focus.
+     *
+     * Useful for application-level workflows such as draft auto-save on blur.
+     */
+    readonly fieldBlur: _angular_core.OutputEmitterRef<NgxFieldBlurEvent<T>>;
     /**
      * Track validation in progress to prevent circular triggering (Issue #19)
      */
@@ -1251,6 +1291,48 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * ```
      */
     markAllAsTouched(): void;
+    /**
+     * 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(): void;
     /**
      * Finds the first invalid element in this form, scrolls it into view, and focuses it.
      *
@@ -1272,7 +1354,7 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * Host handler: called whenever any descendant field loses focus.
      * Used to make touched-path tracking react immediately on blur/tab.
      */
-    onFormFocusOut(): void;
+    onFormFocusOut(event: FocusEvent): void;
     /**
      * Resets the form to a pristine, untouched state with optional new values.
      *
@@ -1338,7 +1420,7 @@ declare class FormDirective<T extends Record<string, unknown>> {
      */
     createAsyncValidator(field: string, validationOptions: ValidationOptions): AsyncValidatorFn;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormDirective<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormDirective<any>, "form[scVestForm], form[ngxVestForm]", ["scVestForm", "ngxVestForm"], { "formValue": { "alias": "formValue"; "required": false; "isSignal": true; }; "suite": { "alias": "suite"; "required": false; "isSignal": true; }; "formShape": { "alias": "formShape"; "required": false; "isSignal": true; }; "validationConfig": { "alias": "validationConfig"; "required": false; "isSignal": true; }; }, { "formValueChange": "formValueChange"; "errorsChange": "errorsChange"; "dirtyChange": "dirtyChange"; "validChange": "validChange"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FormDirective<any>, "form[scVestForm], form[ngxVestForm]", ["scVestForm", "ngxVestForm"], { "formValue": { "alias": "formValue"; "required": false; "isSignal": true; }; "suite": { "alias": "suite"; "required": false; "isSignal": true; }; "formShape": { "alias": "formShape"; "required": false; "isSignal": true; }; "validationConfig": { "alias": "validationConfig"; "required": false; "isSignal": true; }; }, { "formValueChange": "formValueChange"; "errorsChange": "errorsChange"; "dirtyChange": "dirtyChange"; "validChange": "validChange"; "fieldBlur": "fieldBlur"; }, never, never, true, never>;
 }
 
 /**
@@ -1431,12 +1513,16 @@ declare class ValidateRootFormDirective<T> implements AsyncValidator, AfterViewI
     readonly ngxValidateRootForm: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /**
      * Validation mode:
-     * - 'submit' (default): Only validates after form submission
-     * - 'live': Validates on every value change
-     * Accepts both validateRootFormMode and ngxValidateRootFormMode
+     * - `'submit'` (effective default): Only validates after form submission.
+     * - `'live'`: Validates on every value change.
+     *
+     * Both inputs default to `undefined` so we can detect whether the consumer
+     * set them explicitly. Precedence is `ngx ?? legacy ?? 'submit'`, which
+     * matches the documented behavior — observable only when both attributes
+     * are set explicitly on the same form.
      */
-    readonly validateRootFormMode: _angular_core.InputSignal<"submit" | "live">;
-    readonly ngxValidateRootFormMode: _angular_core.InputSignal<"submit" | "live">;
+    readonly validateRootFormMode: _angular_core.InputSignal<"submit" | "live" | undefined>;
+    readonly ngxValidateRootFormMode: _angular_core.InputSignal<"submit" | "live" | undefined>;
     constructor();
     /**
      * Subscribe to form submit event using NgForm.ngSubmit EventEmitter
@@ -2260,15 +2346,6 @@ declare function getFormGroupField(rootForm: FormGroup, control: AbstractControl
  * @param form
  */
 declare function mergeValuesAndRawValues<T>(form: FormGroup): T;
-/**
- * Performs a deep-clone of an object
- * @param obj
- *
- * @deprecated Use official ES {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone structuredClone} instead
- *
- * Browser Support: structuredClone is available in all modern browsers (Chrome 98+, Firefox 94+, Safari 15.4+, Edge 98+)
- * and Node.js 17+. A polyfill is provided in test-setup.ts for Jest test environments.
- */
 declare function cloneDeep<T>(object: T): T;
 /**
  * Sets a value in an object at the provided field path.
@@ -2318,6 +2395,12 @@ type DebouncedPendingStateOptions = {
      */
     minimumDisplay?: number;
 };
+/**
+ * Accepts either a static options object or a reactive `Signal` (e.g. an
+ * `input()` accessor) so consumers can update debounce timings at runtime
+ * without recreating the pending-state machine.
+ */
+type DebouncedPendingStateOptionsInput = DebouncedPendingStateOptions | Signal<DebouncedPendingStateOptions>;
 /**
  * Result of createDebouncedPendingState containing the debounced signal
  * and cleanup function.
@@ -2367,7 +2450,7 @@ type DebouncedPendingStateResult = {
  * @param options - Configuration options for debouncing behavior
  * @returns Object containing the debounced showPendingMessage signal and cleanup function
  */
-declare function createDebouncedPendingState(isPending: Signal<boolean>, options?: DebouncedPendingStateOptions): DebouncedPendingStateResult;
+declare function createDebouncedPendingState(isPending: Signal<boolean>, options?: DebouncedPendingStateOptionsInput): DebouncedPendingStateResult;
 
 /**
  * Validates a form value against a shape to catch typos in `name` or `ngModelGroup` attributes.
@@ -2458,11 +2541,13 @@ declare function shallowEqual(obj1: unknown, obj2: unknown): boolean;
  * - 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)
+ * - Set objects (reference equality only)
+ * - Map objects (reference equality only)
+ * - Functions (reference equality only — distinct function instances are never equal,
+ *   even if their source code is identical)
  *
  * **Safety Features:**
- * - **Circular reference protection**: MaxDepth parameter prevents infinite recursion
+ * - **Circular reference handling**: Tracks visited object pairs with `WeakMap<object, WeakSet<object>>`
  * - **Type coercion prevention**: Strict type checking before comparison
  * - **Null safety**: Proper handling of null and undefined values
  *
@@ -2474,7 +2559,8 @@ declare function shallowEqual(obj1: unknown, obj2: unknown): boolean;
  * ///
  * /// Memory usage:
  * /// JSON.stringify:    Creates temporary strings (high GC pressure)
- * /// fastDeepEqual:     Zero allocations during comparison
+ * /// fastDeepEqual:     One small WeakMap of visited object pairs is allocated lazily on
+ * ///                    first nested-container descent; primitive-only comparisons allocate nothing.
  * ```
  *
  * **Typical Usage in Forms:**
@@ -2490,10 +2576,15 @@ declare function shallowEqual(obj1: unknown, obj2: unknown): boolean;
  *
  * @param obj1 - First object to compare
  * @param obj2 - Second object to compare
- * @param maxDepth - Maximum recursion depth to prevent infinite loops (default: 10)
+ *
+ * Cyclic arrays and plain objects are compared structurally by tracking visited object
+ * pairs. Distinct cyclic graphs with the same structure compare equal. `Date` and
+ * `RegExp` values compare structurally. `Map` and `Set` values compare by reference
+ * only, so distinct instances are considered different even if their contents match.
+ *
  * @returns true if objects are deeply equal by value
  */
-declare function fastDeepEqual(obj1: unknown, obj2: unknown, maxDepth?: number): boolean;
+declare function fastDeepEqual(obj1: unknown, obj2: unknown): boolean;
 
 /**
  * @deprecated Use NGX_ERROR_DISPLAY_MODE_TOKEN instead
@@ -2565,5 +2656,46 @@ declare const NGX_WARNING_DISPLAY_MODE_TOKEN: InjectionToken<NgxWarningDisplayMo
  */
 declare const NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN: InjectionToken<number>;
 
-export { ControlWrapperComponent, DEFAULT_FOCUS_SELECTOR, DEFAULT_INVALID_SELECTOR, 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, mergeAriaDescribedBy, mergeValuesAndRawValues, objectToArray, parseAriaIdTokens, parseFieldPath, resolveAssociationTargets, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
-export type { AriaAssociationMode, DebouncedPendingStateOptions, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxFieldKey, NgxFirstInvalidOptions, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, NgxWarningDisplayMode, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };
+/**
+ * Signature of a deep-equality comparator. Must return `true` iff `a` and `b`
+ * are considered equal for the purpose of change detection.
+ */
+type NgxEqualityFn = (a: unknown, b: unknown) => boolean;
+/**
+ * Injection token for the deep-equality function used internally by
+ * {@link FormDirective} for change detection — `formValueChange`
+ * `distinctUntilChanged`, the form↔model two-way sync effect, and the
+ * `formState` signal's structural comparator.
+ *
+ * The default factory returns {@link fastDeepEqual}. Override this token to
+ * plug in a smaller or differently-tuned comparator (e.g. `dequal/lite`,
+ * `lodash.isEqual`) without forking the directive.
+ *
+ * @example Bring-your-own equality at the application level
+ * ```ts
+ * import { dequal } from 'dequal/lite';
+ * import { NGX_EQUALITY_FN } from 'ngx-vest-forms';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     { provide: NGX_EQUALITY_FN, useValue: dequal },
+ *   ],
+ * };
+ * ```
+ *
+ * @example Per-component override (e.g. for tests)
+ * ```ts
+ * @Component({
+ *   providers: [
+ *     { provide: NGX_EQUALITY_FN, useValue: (a, b) => a === b },
+ *   ],
+ * })
+ * export class TestFormComponent {}
+ * ```
+ *
+ * @default {@link fastDeepEqual}
+ */
+declare const NGX_EQUALITY_FN: InjectionToken<NgxEqualityFn>;
+
+export { ControlWrapperComponent, DEFAULT_FOCUS_SELECTOR, DEFAULT_INVALID_SELECTOR, FormControlStateDirective, FormDirective, FormErrorControlDirective, FormErrorDisplayDirective, FormGroupWrapperComponent, FormModelDirective, FormModelGroupDirective, NGX_EQUALITY_FN, 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, mergeAriaDescribedBy, mergeValuesAndRawValues, objectToArray, parseAriaIdTokens, parseFieldPath, resolveAssociationTargets, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
+export type { AriaAssociationMode, DebouncedPendingStateOptions, DebouncedPendingStateOptionsInput, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxEqualityFn, NgxFieldBlurEvent, NgxFieldKey, NgxFirstInvalidOptions, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, NgxWarningDisplayMode, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };