feat(forms): update submit function to accept options object

mmalerba · leonsenft · commit dd208ca25952 · 2026-02-03T12:43:31.000-08:00
Changes the `submit` function signature to accept a `FormSubmitOptions` object instead of a direct action callback.
This allows for more flexibility, including:

- `action`: The standard submit action to perform with the data.
- `onInvalid`: A callback to execute when the submit action is not triggered due to failing validation
- `ignoreValidators`: Controls whether pending validators or invalid validators should be ignored

Also updates the return value of `submit` to a `Promise&lt;boolean` to indicate submission success.
diff --git a/goldens/public-api/forms/signals/compat/index.api.md b/goldens/public-api/forms/signals/compat/index.api.md
@@ -7,7 +7,6 @@
 import { AbstractControl } from '@angular/forms';
 import * as _angular_forms from '@angular/forms';
 import { ControlValueAccessor } from '@angular/forms';
-import { DestroyableInjector } from '@angular/core';
 import { EventEmitter } from '@angular/core';
 import { FormControlState } from '@angular/forms';
 import { FormControlStatus } from '@angular/forms';
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -7,7 +7,6 @@
 import { AbstractControl } from '@angular/forms';
 import * as _angular_forms from '@angular/forms';
 import { ControlValueAccessor } from '@angular/forms';
-import { DestroyableInjector } from '@angular/core';
 import { FormControlStatus } from '@angular/forms';
 import { HttpResourceOptions } from '@angular/common/http';
 import { HttpResourceRequest } from '@angular/common/http';
@@ -210,12 +209,17 @@ export interface FormFieldBindingOptions {
 
 // @public
 export interface FormOptions {
-    adapter?: FieldAdapter;
     injector?: Injector;
-    // (undocumented)
     name?: string;
 }
 
+// @public
+export interface FormSubmitOptions<TModel> {
+    action: (form: FieldTree<TModel>) => Promise<TreeValidationResult>;
+    ignoreValidators?: 'pending' | 'none' | 'all';
+    onInvalid?: (form: FieldTree<TModel>) => void;
+}
+
 // @public
 export interface FormUiControl<TValue> {
     readonly dirty?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
@@ -555,7 +559,7 @@ export type Subfields<TModel> = {
 };
 
 // @public
-export function submit<TModel>(form: FieldTree<TModel>, action: (form: FieldTree<TModel>) => Promise<TreeValidationResult>): Promise<void>;
+export function submit<TModel>(form: FieldTree<TModel>, options: FormSubmitOptions<TModel>): Promise<boolean>;
 
 // @public
 export type TreeValidationResult<E extends ValidationError.WithOptionalFieldTree = ValidationError.WithOptionalFieldTree> = ValidationSuccess | OneOrMany<E>;
diff --git a/packages/forms/signals/src/api/structure.ts b/packages/forms/signals/src/api/structure.ts
@@ -31,6 +31,25 @@ import type {
   TreeValidationResult,
 } from './types';
 
+/**
+ * Options that can be specified when submitting a form.
+ *
+ * @experimental 21.2.0
+ */
+export interface FormSubmitOptions<TModel> {
+  /** Function to run when submitting the form data (when form is valid). */
+  action: (form: FieldTree<TModel>) => Promise<TreeValidationResult>;
+  /** Function to run when attempting to submit the form data but validation is failing. */
+  onInvalid?: (form: FieldTree<TModel>) => void;
+  /**
+   * Whether to ignore any of the validators when submitting:
+   * - 'pending': Will submit if there are no invalid validators, pending validators do not block submission (default)
+   * - 'none': Will not submit unless all validators are passing, pending validators block submission
+   * - 'ignore': Will always submit regardless of invalid or pending validators
+   */
+  ignoreValidators?: 'pending' | 'none' | 'all';
+}
+
 /**
  * Options that may be specified when creating a form.
  *
@@ -43,11 +62,13 @@ export interface FormOptions {
    * current [injection context](guide/di/dependency-injection-context), will be used.
    */
   injector?: Injector;
+  /** The name of the root form, used in generating name attributes for the fields. */
   name?: string;
 
   /**
    * Adapter allows managing fields in a more flexible way.
    * Currently this is used to support interop with reactive forms.
+   * @internal
    */
   adapter?: FieldAdapter;
 }
@@ -350,42 +371,56 @@ export function applyWhenValue(
  * }
  *
  * const registrationForm = form(signal({username: 'god', password: ''}));
- * submit(registrationForm, async (f) => {
- *   return registerNewUser(registrationForm);
+ * submit(registrationForm, {
+ *   action: async (f) => {
+ *     return registerNewUser(registrationForm);
+ *   }
  * });
  * registrationForm.username().errors(); // [{kind: 'server', message: 'Username already taken'}]
  * ```
  *
  * @param form The field to submit.
- * @param action An asynchronous action used to submit the field. The action may return submission
- * errors.
+ * @param options Options for the submission.
+ * @returns Whether the submission was successful.
  * @template TModel The data type of the field being submitted.
  *
  * @category submission
  * @experimental 21.0.0
  */
 export async function submit<TModel>(
   form: FieldTree<TModel>,
-  action: (form: FieldTree<TModel>) => Promise<TreeValidationResult>,
-) {
-  const node = form() as unknown as FieldNode;
-  const invalid = untracked(() => {
+  options: FormSubmitOptions<TModel>,
+): Promise<boolean> {
+  return untracked(async () => {
+    const {action, onInvalid} = options;
+    const ignoreValidators = options.ignoreValidators ?? 'pending';
+    const node = form() as unknown as FieldNode;
+
     markAllAsTouched(node);
-    return node.invalid();
-  });
 
-  // Fail fast if the form is already invalid.
-  if (invalid) {
-    return;
-  }
+    // Determine whether or not to run the action based on the current validity.
+    let shouldRunAction = true;
+    if (ignoreValidators === 'none') {
+      shouldRunAction = node.valid();
+    } else if (ignoreValidators === 'pending') {
+      shouldRunAction = !node.invalid();
+    }
 
-  node.submitState.selfSubmitting.set(true);
-  try {
-    const errors = await action(form);
-    errors && setSubmissionErrors(node, errors);
-  } finally {
-    node.submitState.selfSubmitting.set(false);
-  }
+    // Run the action (or alternatively the `onInvalid` callback)
+    try {
+      if (shouldRunAction) {
+        node.submitState.selfSubmitting.set(true);
+        const errors = await action(form);
+        errors && setSubmissionErrors(node, errors);
+        return !errors || (isArray(errors) && errors.length === 0);
+      } else if (onInvalid) {
+        onInvalid(form);
+      }
+      return false;
+    } finally {
+      node.submitState.selfSubmitting.set(false);
+    }
+  });
 }
 
 /**
diff --git a/packages/forms/signals/test/node/compat/compat.spec.ts b/packages/forms/signals/test/node/compat/compat.spec.ts
@@ -347,8 +347,10 @@ describe('Forms compat', () => {
 
       const {promise, resolve} = promiseWithResolvers<TreeValidationResult>();
 
-      const result = submit(f as unknown as FieldTree<void>, () => {
-        return promise;
+      const result = submit(f as unknown as FieldTree<void>, {
+        action: () => {
+          return promise;
+        },
       });
 
       expect(f().submitting()).toBe(true);
diff --git a/packages/forms/signals/test/node/submit.spec.ts b/packages/forms/signals/test/node/submit.spec.ts
