feat(forms): add field param to submit action and onInvalid

mmalerba · AndrewKushnir · commit f56bb07d83a0 · 2026-02-09T14:49:43.000-08:00
The `action` and `onInvalid` handlers now recevie two pieces of
information:
1. The form that is being submitted
2. The specific field that the submit was triggered on

Remove the `submit()` method on field state - supporting this is complex
from a typing perspective, since the `FieldState` only knows its
`TValue` type, not the `TModel` type of its owning `FieldTree`. Rather
than try to pack additional generics on to `FieldState`, we'll just
leave the `submit` function as a standalone importable function.
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -210,14 +210,20 @@ export interface FormFieldBindingOptions {
 export interface FormOptions<TModel> {
     injector?: Injector;
     name?: string;
-    submission?: FormSubmitOptions<TModel>;
+    submission?: FormSubmitOptions<TModel, unknown>;
 }
 
 // @public
-export interface FormSubmitOptions<TModel> {
-    action: (form: FieldTree<TModel>) => Promise<TreeValidationResult>;
+export interface FormSubmitOptions<TRootModel, TSubmittedModel> {
+    action: (field: FieldTree<TRootModel & TSubmittedModel>, detail: {
+        root: FieldTree<TRootModel>;
+        submitted: FieldTree<TSubmittedModel>;
+    }) => Promise<TreeValidationResult>;
     ignoreValidators?: 'pending' | 'none' | 'all';
-    onInvalid?: (form: FieldTree<TModel>) => void;
+    onInvalid?: (field: FieldTree<TRootModel & TSubmittedModel>, detail: {
+        root: FieldTree<TRootModel>;
+        submitted: FieldTree<TSubmittedModel>;
+    }) => void;
 }
 
 // @public
@@ -558,10 +564,10 @@ export type Subfields<TModel> = {
 };
 
 // @public
-export function submit<TModel>(form: FieldTree<TModel>, options?: FormSubmitOptions<TModel>): Promise<boolean>;
+export function submit<TModel>(form: FieldTree<TModel>, options?: NoInfer<FormSubmitOptions<unknown, TModel>>): Promise<boolean>;
 
 // @public (undocumented)
-export function submit<TModel>(form: FieldTree<TModel>, action: FormSubmitOptions<TModel>['action']): Promise<boolean>;
+export function submit<TModel>(form: FieldTree<TModel>, action: NoInfer<FormSubmitOptions<unknown, TModel>['action']>): Promise<boolean>;
 
 // @public
 export function transformedValue<TValue, TRaw>(value: ModelSignal<TValue>, options: TransformedValueOptions<TValue, TRaw>): TransformedValueSignal<TRaw>;
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
@@ -24,9 +24,11 @@ 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 {ValidationError} from './rules';
 import type {
+  FieldState,
   FieldTree,
+  FormSubmitOptions,
   ItemType,
   LogicFn,
   OneOrMany,
@@ -35,28 +37,8 @@ import type {
   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.
  *
@@ -72,7 +54,7 @@ export interface FormOptions<TModel> {
   /** The name of the root form, used in generating name attributes for the fields. */
   name?: string;
   /** Options that define how to handle form submission. */
-  submission?: FormSubmitOptions<TModel>;
+  submission?: FormSubmitOptions<TModel, unknown>;
 
   /**
    * Adapter allows managing fields in a more flexible way.
@@ -216,7 +198,7 @@ export function form<TModel>(...args: any[]): FieldTree<TModel> {
   const fieldManager = new FormFieldManager(
     injector,
     options?.name,
-    options?.submission as FormSubmitOptions<unknown> | undefined,
+    options?.submission as FormSubmitOptions<unknown, unknown> | undefined,
   );
   const adapter = options?.adapter ?? new BasicFieldAdapter();
   const fieldRoot = FieldNode.newRoot(fieldManager, model, pathNode, adapter);
@@ -402,35 +384,39 @@ export function applyWhenValue(
  */
 export async function submit<TModel>(
   form: FieldTree<TModel>,
-  options?: FormSubmitOptions<TModel>,
+  options?: NoInfer<FormSubmitOptions<unknown, TModel>>,
 ): Promise<boolean>;
 export async function submit<TModel>(
   form: FieldTree<TModel>,
-  action: FormSubmitOptions<TModel>['action'],
+  action: NoInfer<FormSubmitOptions<unknown, TModel>['action']>,
 ): Promise<boolean>;
 export async function submit<TModel>(
   form: FieldTree<TModel>,
-  options?: FormSubmitOptions<TModel> | FormSubmitOptions<TModel>['action'],
+  options?: FormSubmitOptions<unknown, TModel> | FormSubmitOptions<unknown, TModel>['action'],
 ): Promise<boolean> {
-  const node = form() as unknown as FieldNode;
-  const opts =
+  const node = untracked(form) as FieldState<unknown> as FieldNode;
+
+  const field = options === undefined ? node.structure.root.fieldProxy : form;
+  const detail = {root: node.structure.root.fieldProxy, submitted: form};
+
+  // Normalize options.
+  options =
     typeof options === 'function'
       ? {action: options}
-      : ({
-          ...(node.structure.fieldManager.submitOptions ?? {}),
-          ...(options ?? {}),
-        } as Partial<FormSubmitOptions<TModel>>);
-  const action = opts?.action;
+      : (options ?? node.structure.fieldManager.submitOptions);
+
+  // Verify that an action was provided.
+  const action = options?.action as FormSubmitOptions<unknown, unknown>['action'];
   if (!action) {
     throw new RuntimeError(
       RuntimeErrorCode.MISSING_SUBMIT_ACTION,
-      ngDevMode &&
+      (typeof ngDevMode === 'undefined' || 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';
+  const onInvalid = options?.onInvalid as FormSubmitOptions<unknown, unknown>['onInvalid'];
+  const ignoreValidators = options?.ignoreValidators ?? 'pending';
 
   // Determine whether or not to run the action based on the current validity.
   let shouldRunAction = true;
@@ -448,18 +434,45 @@ export async function submit<TModel>(
   try {
     if (shouldRunAction) {
       node.submitState.selfSubmitting.set(true);
-      const errors = await untracked(() => action?.(form));
+      const errors = await untracked(() => action?.(field, detail));
       errors && setSubmissionErrors(node, errors);
       return !errors || (isArray(errors) && errors.length === 0);
     } else {
-      untracked(() => onInvalid?.(form));
+      untracked(() => onInvalid?.(field, detail));
     }
     return false;
   } finally {
     node.submitState.selfSubmitting.set(false);
   }
 }
 
+/**
+ * Creates a `Schema` that adds logic rules to a form.
+ * @param fn A **non-reactive** function that sets up reactive logic rules for the form.
+ * @returns A schema object that implements the given logic.
+ * @template TValue The value type of a `FieldTree` that this schema binds to.
+ *
+ * @category structure
+ * @experimental 21.0.0
+ */
+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);
+  }
+}
+
 /**
  * Sets a list of submission errors to their individual fields.
  *
@@ -488,30 +501,3 @@ function setSubmissionErrors(
     field.submitState.submissionErrors.set(fieldErrors);
   }
 }
-
-/**
- * Creates a `Schema` that adds logic rules to a form.
- * @param fn A **non-reactive** function that sets up reactive logic rules for the form.
- * @returns A schema object that implements the given logic.
- * @template TValue The value type of a `FieldTree` that this schema binds to.
- *
- * @category structure
- * @experimental 21.0.0
- */
-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,47 @@ 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<TRootModel, TSubmittedModel> {
+  /**
+   * Function to run when submitting the form data (when form is valid).
+   *
+   * @param field The contextually relevant field for this action function (the root field when
+   *   specified during form creation, and the submitted field when specified as part of the
+   *   `submit()` call)
+   * @param detail An object containing the root field of the submitted form as well as the
+   *   submitted field itself
+   */
+  action: (
+    field: FieldTree<TRootModel & TSubmittedModel>,
+    detail: {root: FieldTree<TRootModel>; submitted: FieldTree<TSubmittedModel>},
+  ) => Promise<TreeValidationResult>;
+  /**
+   * Function to run when attempting to submit the form data but validation is failing.
+   *
+   * @param field The contextually relevant field for this onInvalid function (the root field when
+   *   specified during form creation, and the submitted field when specified as part of the
+   *   `submit()` call)
+   * @param detail An object containing the root field of the submitted form as well as the
+   *   submitted field itself
+   */
+  onInvalid?: (
+    field: FieldTree<TRootModel & TSubmittedModel>,
+    detail: {root: FieldTree<TRootModel>; submitted: FieldTree<TSubmittedModel>},
+  ) => 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).
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';
 
 /**
@@ -20,12 +20,12 @@ import type {FieldNodeStructure} from './structure';
 export class FormFieldManager {
   readonly injector: Injector;
   readonly rootName: string;
-  readonly submitOptions: FormSubmitOptions<unknown> | undefined;
+  readonly submitOptions: FormSubmitOptions<unknown, unknown> | undefined;
 
   constructor(
     injector: Injector,
     rootName: string | undefined,
-    submitOptions: FormSubmitOptions<unknown> | undefined,
+    submitOptions: FormSubmitOptions<unknown, unknown> | undefined,
   ) {
     this.injector = injector;
     this.rootName = rootName ?? `${this.injector.get(APP_ID)}.form${nextFormId++}`;
diff --git a/packages/forms/signals/src/field/node.ts b/packages/forms/signals/src/field/node.ts
@@ -7,7 +7,6 @@
  */
 
 import {computed, linkedSignal, type Signal, untracked, type WritableSignal} from '@angular/core';
-import type {FormField} from '../directive/form_field_directive';
 import {
   MAX,
   MAX_LENGTH,
@@ -19,6 +18,7 @@ import {
 } from '../api/rules/metadata';
 import type {ValidationError} from '../api/rules/validation/validation_errors';
 import type {DisabledReason, FieldContext, FieldState, FieldTree} from '../api/types';
+import type {FormField} from '../directive/form_field_directive';
 import {DYNAMIC} from '../schema/logic';
 import {LogicNode} from '../schema/logic_node';
 import {FieldPathNode} from '../schema/path_node';
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>, {
-        action: () => {
+      const result = submit(f, {
+        action: (field) => {
+          expect(field.name().value()).toBe('pirojok-the-cat');
+          expect(field.age().control()).toBe(control);
           return promise;
         },
       });
diff --git a/packages/forms/signals/test/node/submit.spec.ts b/packages/forms/signals/test/node/submit.spec.ts
