From 24fa4a246064864ebd96a3e2cf72dd77d797bd10 Mon Sep 17 00:00:00 2001
From: kirjs <kirts@google.com>
Date: Thu, 8 Jan 2026 14:47:54 -0500
Subject: [PATCH] docs(forms): Clarify returning errors from submit functions

Update outdate comment, and add a section to the docs

(cherry picked from commit 7d985ce08e521308c3bf90184b7916cb4f246183)
---
 .../guide/forms/signals/field-state-management.md   | 10 +++++-----
 adev/src/content/guide/forms/signals/validation.md  | 13 +++++++++++++
 packages/forms/signals/src/api/structure.ts         |  7 ++++---
 3 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/adev/src/content/guide/forms/signals/field-state-management.md b/adev/src/content/guide/forms/signals/field-state-management.md
index 093c6039063..bfc9ddb62ad 100644
--- a/adev/src/content/guide/forms/signals/field-state-management.md
+++ b/adev/src/content/guide/forms/signals/field-state-management.md
@@ -109,11 +109,11 @@ When checking validity in code, use `invalid()` instead of `!valid()` if you wan
 
 Access the array of validation errors with `errors()`. Each error object contains:
 
-| Property  | Description                                                     |
-| --------- | --------------------------------------------------------------- |
-| `kind`    | The validation rule that failed (such as "required" or "email") |
-| `message` | Optional human-readable error message                           |
-| `field`   | Reference to the `FieldTree` where the error occurred           |
+| Property    | Description                                                     |
+| ----------- | --------------------------------------------------------------- |
+| `kind`      | The validation rule that failed (such as "required" or "email") |
+| `message`   | Optional human-readable error message                           |
+| `fieldTree` | Reference to the `FieldTree` where the error occurred           |
 
 NOTE: The `message` property is optional. Validators can provide custom error messages, but if not specified, you may need to map error `kind` values to your own messages.
 
diff --git a/adev/src/content/guide/forms/signals/validation.md b/adev/src/content/guide/forms/signals/validation.md
index b1e0aa26cc6..991a02a0fd2 100644
--- a/adev/src/content/guide/forms/signals/validation.md
+++ b/adev/src/content/guide/forms/signals/validation.md
@@ -461,6 +461,19 @@ export class UrlFormComponent {
 }
 ```
 
+For submission errors that target specific fields, use the `fieldTree` property:
+
+```ts
+// In a submit function
+return [
+  {
+    fieldTree: registrationForm.username, // Target specific field
+    kind: 'server',
+    message: 'Username already taken',
+  },
+];
+```
+
 The validator function receives a `FieldContext` object with:
 
 | Property        | Type       | Description                                 |
diff --git a/packages/forms/signals/src/api/structure.ts b/packages/forms/signals/src/api/structure.ts
index 917e7081715..8cf03ff903d 100644
--- a/packages/forms/signals/src/api/structure.ts
+++ b/packages/forms/signals/src/api/structure.ts
@@ -332,7 +332,7 @@ export function applyWhenValue(
 /**
  * Submits a given `FieldTree` 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 `field` property of the
+ * into the field as a `ValidationError` on the sub-field indicated by the `fieldTree` property of the
  * submission error.
  *
  * @example
@@ -341,8 +341,9 @@ export function applyWhenValue(
  *   const result = await myClient.registerNewUser(registrationForm().value());
  *   if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
  *     return [{
- *       field: registrationForm.username,
- *       error: {kind: 'server', message: 'Username already taken'}
+ *       fieldTree: registrationForm.username,
+ *       kind: 'server',
+ *       message: 'Username already taken'
  *     }];
  *   }
  *   return undefined;