refactor(forms): add fieldTree property to FieldState

The `fieldTree` property of `FieldState` returns its associated
`FieldTree`.

Note that the round trip from `FieldTree` to `FieldState` and back will
lose type information. This is because `FieldState` intentionally does
not know whether it came from a pure Signal Forms field tree, or a
Reactive Forms compatible field tree:

```ts
// Pure Signal Forms:
const x: FieldTree<string>;

x();           // FieldState<string>;
x().fieldTree; // FieldTree<unknown>

// Reactive Forms compatibility:
const y: FieldTree<FormControl<string>>;

y();            // FieldState<string>;
y().fieldTree;  // FieldTree<unknown>;
```

Author: leonsenft

goldens/public-api/forms/signals/index.api.md

@@ -134,6 +134,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     // (undocumented)
     readonly errors: Signal<ValidationError.WithFieldTree[]>;
     readonly errorSummary: Signal<ValidationError.WithFieldTree[]>;
+    readonly fieldTree: FieldTree<unknown, TKey>;
     focusBoundControl(options?: FocusOptions): void;
     readonly formFieldBindings: Signal<readonly FormField<unknown>[]>;
     readonly hidden: Signal<boolean>;

packages/forms/signals/src/api/structure.ts

@@ -222,7 +222,7 @@ export function form<TModel>(...args: any[]): FieldTree<TModel> {
   const fieldRoot = FieldNode.newRoot(fieldManager, model, pathNode, adapter);
   fieldManager.createFieldManagementEffect(fieldRoot.structure);
 
-  return fieldRoot.fieldProxy as FieldTree<TModel>;
+  return fieldRoot.fieldTree as FieldTree<TModel>;
 }
 
 /**
@@ -475,7 +475,7 @@ function setSubmissionErrors(
   }
   const errorsByField = new Map<FieldNode, ValidationError.WithFieldTree[]>();
   for (const error of errors) {
-    const errorWithField = addDefaultField(error, submittedField.fieldProxy);
+    const errorWithField = addDefaultField(error, submittedField.fieldTree);
     const field = errorWithField.fieldTree() as FieldNode;
     let fieldErrors = errorsByField.get(field);
     if (!fieldErrors) {

packages/forms/signals/src/api/types.ts

@@ -218,6 +218,11 @@ export type MaybeFieldTree<TModel, TKey extends string | number = string | numbe
  * @experimental 21.0.0
  */
 export interface FieldState<TValue, TKey extends string | number = string | number> {
+  /**
+   * The {@link FieldTree} associated with this field state.
+   */
+  readonly fieldTree: FieldTree<unknown, TKey>;
+
   /**
    * A writable signal containing the value for this field.
    *

packages/forms/signals/src/field/context.ts

@@ -95,7 +95,7 @@ export class FieldNodeContext implements FieldContext<unknown> {
           }
         }
 
-        return field.fieldProxy;
+        return field.fieldTree;
       });
 
       this.cache.set(target, resolver);

packages/forms/signals/src/field/node.ts

@@ -130,6 +130,10 @@ export class FieldNode implements FieldState<unknown> {
     },
   });
 
+  get fieldTree(): FieldTree<unknown> {
+    return this.fieldProxy;
+  }
+
   get logicNode(): LogicNode {
     return this.structure.logic;
   }

packages/forms/signals/src/field/proxy.ts

@@ -22,7 +22,7 @@ export const FIELD_PROXY_HANDLER: ProxyHandler<() => FieldNode> = {
     if (child !== undefined) {
       // If so, return the child node's `FieldTree` proxy, allowing the developer to continue
       // navigating the form structure.
-      return child.fieldProxy;
+      return child.fieldTree;
     }
 
     // Otherwise, we need to consider whether the properties they're accessing are related to array
@@ -49,7 +49,7 @@ export const FIELD_PROXY_HANDLER: ProxyHandler<() => FieldNode> = {
           //
           // Instead, side-effectfully read the value here to ensure iterator creation is reactive.
           tgt.value();
-          return Array.prototype[Symbol.iterator].apply(tgt.fieldProxy);
+          return Array.prototype[Symbol.iterator].apply(tgt.fieldTree);
         };
       }
       // Note: We can consider supporting additional array methods if we want in the future,

packages/forms/signals/src/field/validation.ts

@@ -205,7 +205,7 @@ export class FieldValidationState implements ValidationState {
    * rather than a descendant.
    */
   readonly syncTreeErrors: Signal<ValidationError.WithFieldTree[]> = computed(() =>
-    this.rawSyncTreeErrors().filter((err) => err.fieldTree === this.node.fieldProxy),
+    this.rawSyncTreeErrors().filter((err) => err.fieldTree === this.node.fieldTree),
   );
 
   /**
@@ -237,7 +237,7 @@ export class FieldValidationState implements ValidationState {
       return [];
     }
     return this.rawAsyncErrors().filter(
-      (err) => err === 'pending' || err.fieldTree === this.node.fieldProxy,
+      (err) => err === 'pending' || err.fieldTree === this.node.fieldTree,
     );
   });
 

packages/forms/signals/test/node/field_node.spec.ts

@@ -159,6 +159,26 @@ describe('FieldNode', () => {
     });
   });
 
+  describe('fieldTree', () => {
+    it('should return the associated field tree from state produced by the root field tree', () => {
+      const f = form(signal(''), {injector: TestBed.inject(Injector)});
+
+      expect(f().fieldTree).toBe(f);
+    });
+
+    it('should return the associated field tree from state produced by a child field tree', () => {
+      const f = form(signal({a: 1, b: 2}), {injector: TestBed.inject(Injector)});
+
+      expect(f.a().fieldTree).toBe(f.a);
+    });
+
+    it('should return the associated field tree from state produced by an array item field tree', () => {
+      const f = form(signal([1, 2, 3]), {injector: TestBed.inject(Injector)});
+
+      expect(f[0]().fieldTree).toBe(f[0]);
+    });
+  });
+
   describe('dirty', () => {
     it('is not dirty initially', () => {
       const f = form(