feat(froms): add submit method to field state

mmalerba · mmalerba · commit 022efea29299 · 2026-02-03T14:10:05.000-08:00
Changes the `submit` function from a separately imported function to a
method on the `FieldState`
diff --git a/adev/src/content/examples/signal-forms/src/login-validation-complete/app/app.ts b/adev/src/content/examples/signal-forms/src/login-validation-complete/app/app.ts
@@ -7,7 +7,7 @@
  */
 
 import {ChangeDetectionStrategy, Component, signal} from '@angular/core';
-import {email, form, FormField, required, submit} from '@angular/forms/signals';
+import {email, form, FormField, required} from '@angular/forms/signals';
 
 interface LoginData {
   email: string;
@@ -36,7 +36,7 @@ export class App {
 
   onSubmit(event: Event) {
     event.preventDefault();
-    submit(this.loginForm, {
+    this.loginForm().submit({
       action: async () => {
         const credentials = this.loginModel();
         // In a real app, this would be async:
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -153,6 +153,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     readonly readonly: Signal<boolean>;
     readonly required: Signal<boolean>;
     reset(value?: TValue): void;
+    submit(options?: FormSubmitOptions<TValue>): Promise<boolean>;
     readonly submitting: Signal<boolean>;
     readonly touched: Signal<boolean>;
     readonly valid: Signal<boolean>;
@@ -559,7 +560,7 @@ export type Subfields<TModel> = {
     [Symbol.iterator](): Iterator<[string, MaybeFieldTree<TModel[keyof TModel], string>]>;
 };
 
-// @public
+// @public @deprecated
 export function submit<TModel>(form: FieldTree<TModel>, options?: FormSubmitOptions<TModel>): Promise<boolean>;
 
 // @public (undocumented)
diff --git a/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts b/packages/forms/signals/compat/src/signal_form_control/signal_form_control.ts
@@ -108,7 +108,7 @@ export class SignalFormControl<T> extends AbstractControl {
     this.fieldTree = wrapFieldTreeForSyncUpdates(rawTree, () =>
       this.parent?.updateValueAndValidity({sourceControl: this} as any),
     );
-    this.fieldState = this.fieldTree();
+    this.fieldState = this.fieldTree() as FieldState<T>;
 
     this.defineCompatProperties();
 
diff --git a/packages/forms/signals/src/api/structure.ts b/packages/forms/signals/src/api/structure.ts
@@ -6,57 +6,27 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {
-  inject,
-  Injector,
-  runInInjectionContext,
-  ɵRuntimeError as RuntimeError,
-  untracked,
-  WritableSignal,
-} from '@angular/core';
-import {RuntimeErrorCode} from '../errors';
+import {inject, Injector, runInInjectionContext, WritableSignal} from '@angular/core';
 import {BasicFieldAdapter, FieldAdapter} from '../field/field_adapter';
 import {FormFieldManager} from '../field/manager';
 import {FieldNode} from '../field/node';
-import {addDefaultField} from '../field/validation';
 import {DYNAMIC} from '../schema/logic';
 import {FieldPathNode} from '../schema/path_node';
 import {assertPathIsCurrent, SchemaImpl} from '../schema/schema';
 import {normalizeFormArgs} from '../util/normalize_form_args';
-import {isArray} from '../util/type_guards';
-import type {ValidationError} from './rules/validation/validation_errors';
 import type {
+  FieldState,
   FieldTree,
+  FormSubmitOptions,
   ItemType,
   LogicFn,
-  OneOrMany,
   PathKind,
   Schema,
   SchemaFn,
   SchemaOrSchemaFn,
   SchemaPath,
-  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.
  *
@@ -399,6 +369,7 @@ export function applyWhenValue(
  *
  * @category submission
  * @experimental 21.0.0
+ * @deprecated Use `form().submit(options)` instead.
  */
 export async function submit<TModel>(
   form: FieldTree<TModel>,
@@ -412,81 +383,8 @@ export async function submit<TModel>(
   form: FieldTree<TModel>,
   options?: FormSubmitOptions<TModel> | FormSubmitOptions<TModel>['action'],
 ): Promise<boolean> {
-  const node = form() as unknown as FieldNode;
-  const opts =
-    typeof options === 'function'
-      ? {action: options}
-      : ({
-          ...(node.structure.fieldManager.submitOptions ?? {}),
-          ...(options ?? {}),
-        } as Partial<FormSubmitOptions<TModel>>);
-  const action = opts?.action;
-  if (!action) {
-    throw new RuntimeError(
-      RuntimeErrorCode.MISSING_SUBMIT_ACTION,
-      ngDevMode &&
-        'Cannot submit form with no submit action. Specify the action when creating the form, or as an additional argument to `submit()`.',
-    );
-  }
-
-  const onInvalid = opts?.onInvalid;
-  const ignoreValidators = opts?.ignoreValidators ?? 'pending';
-
-  // Determine whether or not to run the action based on the current validity.
-  let shouldRunAction = true;
-  untracked(() => {
-    markAllAsTouched(node);
-
-    if (ignoreValidators === 'none') {
-      shouldRunAction = node.valid();
-    } else if (ignoreValidators === 'pending') {
-      shouldRunAction = !node.invalid();
-    }
-  });
-
-  // Run the action (or alternatively the `onInvalid` callback)
-  try {
-    if (shouldRunAction) {
-      node.submitState.selfSubmitting.set(true);
-      const errors = await untracked(() => action?.(form));
-      errors && setSubmissionErrors(node, errors);
-      return !errors || (isArray(errors) && errors.length === 0);
-    } else {
-      untracked(() => onInvalid?.(form));
-    }
-    return false;
-  } finally {
-    node.submitState.selfSubmitting.set(false);
-  }
-}
-
-/**
- * Sets a list of submission errors to their individual fields.
- *
- * @param submittedField The field that was submitted, resulting in the errors.
- * @param errors The errors to set.
- */
-function setSubmissionErrors(
-  submittedField: FieldNode,
-  errors: OneOrMany<ValidationError.WithOptionalFieldTree>,
-) {
-  if (!isArray(errors)) {
-    errors = [errors];
-  }
-  const errorsByField = new Map<FieldNode, ValidationError.WithFieldTree[]>();
-  for (const error of errors) {
-    const errorWithField = addDefaultField(error, submittedField.fieldProxy);
-    const field = errorWithField.fieldTree() as FieldNode;
-    let fieldErrors = errorsByField.get(field);
-    if (!fieldErrors) {
-      fieldErrors = [];
-      errorsByField.set(field, fieldErrors);
-    }
-    fieldErrors.push(errorWithField);
-  }
-  for (const [field, fieldErrors] of errorsByField) {
-    field.submitState.submissionErrors.set(fieldErrors);
-  }
+  const opts = typeof options === 'function' ? {action: options} : options;
+  return (form() as FieldState<any>).submit(opts);
 }
 
 /**
@@ -501,17 +399,3 @@ function setSubmissionErrors(
 export function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue> {
   return SchemaImpl.create(fn) as unknown as Schema<TValue>;
 }
-
-/** Marks a {@link node} and its descendants as touched. */
-function markAllAsTouched(node: FieldNode) {
-  // Don't mark hidden, disabled, or readonly fields as touched since they don't contribute to the
-  // form's validity. This also prevents errors from appearing immediately if they're later made
-  // interactive.
-  if (node.validationState.shouldSkipValidation()) {
-    return;
-  }
-  node.markAsTouched();
-  for (const child of node.structure.children()) {
-    markAllAsTouched(child);
-  }
-}
diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts
@@ -16,6 +16,25 @@ import type {MetadataKey, ValidationError} from './rules';
  */
 declare const ɵɵTYPE: unique symbol;
 
+/**
+ * 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';
+}
+
 /**
  * A type that represents either a single value of type `T` or a readonly array of `T`.
  * @template T The type of the value(s).
@@ -395,6 +414,40 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
    * @param options Optional focus options to pass to the native focus() method.
    */
   focusBoundControl(options?: FocusOptions): void;
+
+  /**
+   * Submits the form using the given action function and applies any submission errors
+   * resulting from the action to the field. Submission errors returned by the `action` will be integrated
+   * into the field as a `ValidationError` on the sub-field indicated by the `fieldTree` property of the
+   * submission error.
+   *
+   * @example
+   * ```ts
+   * async function registerNewUser(registrationForm: FieldTree<{username: string, password: string}>) {
+   *   const result = await myClient.registerNewUser(registrationForm().value());
+   *   if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
+   *     return [{
+   *       fieldTree: registrationForm.username,
+   *       kind: 'server',
+   *       message: 'Username already taken'
+   *     }];
+   *   }
+   *   return undefined;
+   * }
+   *
+   * const registrationForm = form(signal({username: 'god', password: ''}));
+   * registrationForm().submit({
+   *   action: async (f) => {
+   *     return registerNewUser(registrationForm);
+   *   }
+   * });
+   * registrationForm.username().errors(); // [{kind: 'server', message: 'Username already taken'}]
+   * ```
+   *
+   * @param options Options for the submission.
+   * @returns Whether the submission was successful.
+   */
+  submit(options?: FormSubmitOptions<TValue>): Promise<boolean>;
 }
 
 /**
diff --git a/packages/forms/signals/src/field/manager.ts b/packages/forms/signals/src/field/manager.ts
@@ -7,7 +7,7 @@
  */
 
 import {APP_ID, effect, Injector, untracked} from '@angular/core';
-import type {FormSubmitOptions} from '../api/structure';
+import type {FormSubmitOptions} from '../api/types';
 import type {FieldNodeStructure} from './structure';
 
 /**
diff --git a/packages/forms/signals/src/field/node.ts b/packages/forms/signals/src/field/node.ts
diff --git a/packages/forms/signals/test/node/compat/compat.spec.ts b/packages/forms/signals/test/node/compat/compat.spec.ts
diff --git a/packages/forms/signals/test/node/submit.spec.ts b/packages/forms/signals/test/node/submit.spec.ts
