docs(forms): Clarify returning errors from submit functions

Update outdate comment, and add a section to the docs

Author: kirjs

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.
 

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                                 |

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;