refactor(forms): rename Field to FieldTree (angular#64214)

There are two primary reasons for this renaming:
1. It better reflects the actual nature of the proxy object, namely that
   the form is represented as a tree, and that this object is used for
   navigating the tree structure (while `FieldState` is used for getting
   the state at a particular point in the structure).
2. This frees up the name `Field` to be used for the directive that
   binds a `FieldTree` to a UI control.

PR Close angular#64214

Author: mmalerba

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

@@ -73,9 +73,9 @@ export class Control<T> {
     get cva(): ControlValueAccessor | undefined;
     readonly cvaArray: ControlValueAccessor[] | null;
     readonly el: ElementRef<HTMLElement>;
-    readonly field: i0.WritableSignal<Field<T>>;
+    readonly field: i0.WritableSignal<FieldTree<T>>;
     // (undocumented)
-    set _field(value: Field<T>);
+    set _field(value: FieldTree<T>);
     get ngControl(): NgControl;
     readonly state: i0.Signal<FieldState<T, string | number>>;
     // (undocumented)
@@ -97,7 +97,7 @@ export function customError<E extends Partial<ValidationError>>(obj?: E): Withou
 export class CustomValidationError implements ValidationError {
     constructor(options?: ValidationErrorOptions);
     [key: PropertyKey]: unknown;
-    readonly field: Field<unknown>;
+    readonly field: FieldTree<unknown>;
     readonly kind: string;
     readonly message?: string;
 }
@@ -107,7 +107,7 @@ export function disabled<TValue, TPathKind extends PathKind = PathKind.Root>(pat
 
 // @public
 export interface DisabledReason {
-    readonly field: Field<unknown>;
+    readonly field: FieldTree<unknown>;
     readonly message?: string;
 }
 
@@ -126,9 +126,6 @@ export class EmailValidationError extends _NgValidationError {
     readonly kind = "email";
 }
 
-// @public
-export type Field<TValue, TKey extends string | number = string | number> = (() => FieldState<TValue, TKey>) & (TValue extends Array<infer U> ? ReadonlyArrayLike<MaybeField<U, number>> : TValue extends Record<string, any> ? Subfields<TValue> : unknown);
-
 // @public
 export type FieldContext<TValue, TPathKind extends PathKind = PathKind.Root> = TPathKind extends PathKind.Item ? ItemFieldContext<TValue> : TPathKind extends PathKind.Child ? ChildFieldContext<TValue> : RootFieldContext<TValue>;
 
@@ -165,20 +162,23 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     readonly value: WritableSignal<TValue>;
 }
 
+// @public
+export type FieldTree<TValue, TKey extends string | number = string | number> = (() => FieldState<TValue, TKey>) & (TValue extends Array<infer U> ? ReadonlyArrayLike<MaybeFieldTree<U, number>> : TValue extends Record<string, any> ? Subfields<TValue> : unknown);
+
 // @public
 export type FieldValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<WithoutField<E>>;
 
 // @public
 export type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, FieldValidationResult, TPathKind>;
 
 // @public
-export function form<TValue>(model: WritableSignal<TValue>): Field<TValue>;
+export function form<TValue>(model: WritableSignal<TValue>): FieldTree<TValue>;
 
 // @public
-export function form<TValue>(model: WritableSignal<TValue>, schemaOrOptions: SchemaOrSchemaFn<TValue> | FormOptions): Field<TValue>;
+export function form<TValue>(model: WritableSignal<TValue>, schemaOrOptions: SchemaOrSchemaFn<TValue> | FormOptions): FieldTree<TValue>;
 
 // @public
-export function form<TValue>(model: WritableSignal<TValue>, schema: SchemaOrSchemaFn<TValue>, options: FormOptions): Field<TValue>;
+export function form<TValue>(model: WritableSignal<TValue>, schema: SchemaOrSchemaFn<TValue>, options: FormOptions): FieldTree<TValue>;
 
 // @public
 export interface FormCheckboxControl extends FormUiControl {
@@ -295,10 +295,10 @@ export class MaxValidationError extends _NgValidationError {
 }
 
 // @public
-export type MaybeField<TValue, TKey extends string | number = string | number> = (TValue & undefined) | Field<Exclude<TValue, undefined>, TKey>;
+export type MaybeFieldPath<TValue, TPathKind extends PathKind = PathKind.Root> = (TValue & undefined) | FieldPath<Exclude<TValue, undefined>, TPathKind>;
 
 // @public
-export type MaybeFieldPath<TValue, TPathKind extends PathKind = PathKind.Root> = (TValue & undefined) | FieldPath<Exclude<TValue, undefined>, TPathKind>;
+export type MaybeFieldTree<TValue, TKey extends string | number = string | number> = (TValue & undefined) | FieldTree<Exclude<TValue, undefined>, TKey>;
 
 // @public
 export const MIN: AggregateProperty<number | undefined, number | undefined>;
@@ -445,8 +445,8 @@ export class RequiredValidationError extends _NgValidationError {
 
 // @public
 export interface RootFieldContext<TValue> {
-    readonly field: Field<TValue>;
-    readonly fieldOf: <P>(p: FieldPath<P>) => Field<P>;
+    readonly field: FieldTree<TValue>;
+    readonly fieldOf: <P>(p: FieldPath<P>) => FieldTree<P>;
     readonly state: FieldState<TValue>;
     readonly stateOf: <P>(p: FieldPath<P>) => FieldState<P>;
     readonly value: Signal<TValue>;
@@ -484,11 +484,11 @@ export class StandardSchemaValidationError extends _NgValidationError {
 
 // @public
 export type Subfields<TValue> = {
-    readonly [K in keyof TValue as TValue[K] extends Function ? never : K]: MaybeField<TValue[K], string>;
+    readonly [K in keyof TValue as TValue[K] extends Function ? never : K]: MaybeFieldTree<TValue[K], string>;
 };
 
 // @public
-export function submit<TValue>(form: Field<TValue>, action: (form: Field<TValue>) => Promise<TreeValidationResult>): Promise<void>;
+export function submit<TValue>(form: FieldTree<TValue>, action: (form: FieldTree<TValue>) => Promise<TreeValidationResult>): Promise<void>;
 
 // @public
 export type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting';
@@ -516,7 +516,7 @@ export function validateTree<TValue, TPathKind extends PathKind = PathKind.Root>
 
 // @public
 export interface ValidationError {
-    readonly field: Field<unknown>;
+    readonly field: FieldTree<unknown>;
     readonly kind: string;
     readonly message?: string;
 }
@@ -532,12 +532,12 @@ export type Validator<TValue, TPathKind extends PathKind = PathKind.Root> = Logi
 
 // @public
 export type WithField<T> = T & {
-    field: Field<unknown>;
+    field: FieldTree<unknown>;
 };
 
 // @public
 export type WithOptionalField<T> = Omit<T, 'field'> & {
-    field?: Field<unknown>;
+    field?: FieldTree<unknown>;
 };
 
 // @public

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

@@ -104,14 +104,14 @@ export interface FormUiControl {
 }
 
 /**
- * A contract for a form control that edits a `Field` of type `TValue`. Any component that
+ * A contract for a form control that edits a `FieldTree` of type `TValue`. Any component that
  * implements this contract can be used with the `Control` directive.
  *
  * Many of the properties declared on this contract are optional. They do not need to be
  * implemented, but if they are will be kept in sync with the field state of the field bound to the
  * `Control` directive.
  *
- * @template TValue The type of `Field` that the implementing component can edit.
+ * @template TValue The type of `FieldTree` that the implementing component can edit.
  *
  * @category control
  * @experimental 21.0.0
@@ -120,7 +120,7 @@ export interface FormValueControl<TValue> extends FormUiControl {
   /**
    * The value is the only required property in this contract. A component that wants to integrate
    * with the `Control` directive via this contract, *must* provide a `model()` that will be kept in
-   * sync with the value of the bound `Field`.
+   * sync with the value of the bound `FieldTree`.
    */
   readonly value: ModelSignal<TValue>;
   // TODO: We currently require that a `checked` input not be present, as we may want to introduce a
@@ -135,7 +135,7 @@ export interface FormValueControl<TValue> extends FormUiControl {
 }
 
 /**
- * A contract for a form control that edits a boolean checkbox `Field`. Any component that
+ * A contract for a form control that edits a boolean checkbox `FieldTree`. Any component that
  * implements this contract can be used with the `Control` directive.
  *
  * Many of the properties declared on this contract are optional. They do not need to be
@@ -149,7 +149,7 @@ export interface FormCheckboxControl extends FormUiControl {
   /**
    * The checked is the only required property in this contract. A component that wants to integrate
    * with the `Control` directive, *must* provide a `model()` that will be kept in sync with the
-   * value of the bound `Field`.
+   * value of the bound `FieldTree`.
    */
   readonly checked: ModelSignal<boolean>;
   // TODO: maybe this doesn't have to be strictly `undefined`? It just can't be a model signal.

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

@@ -40,7 +40,7 @@ import {
 } from '../util/private';
 import {FormCheckboxControl, FormUiControl, FormValueControl} from './control';
 import {AggregateProperty, MAX, MAX_LENGTH, MIN, MIN_LENGTH, PATTERN, REQUIRED} from './property';
-import type {Field} from './types';
+import type {FieldTree} from './types';
 
 /**
  * Lightweight DI token provided by the {@link Control} directive.
@@ -50,7 +50,7 @@ export const CONTROL = new InjectionToken<Control<unknown>>(
 );
 
 /**
- * Binds a form `Field` to a UI control that edits it. A UI control can be one of several things:
+ * Binds a form `FieldTree` to a UI control that edits it. A UI control can be one of several things:
  * 1. A native HTML input or textarea
  * 2. A signal forms custom control that implements `FormValueControl` or `FormCheckboxControl`
  * 3. A component that provides a ControlValueAccessor. This should only be used to backwards
@@ -89,7 +89,7 @@ export class Control<T> {
   private initialized = false;
 
   /** The field that is bound to this control. */
-  readonly field = signal<Field<T>>(undefined as any);
+  readonly field = signal<FieldTree<T>>(undefined as any);
 
   // If `[control]` is applied to a custom UI control, it wants to synchronize state in the field w/
   // the inputs of that custom control. This is difficult to do in user-land. We use `effect`, but
@@ -103,7 +103,7 @@ export class Control<T> {
   // before the important lifecycle hooks of the UI control. We can then initialize all our effects
   // and force them to run immediately, ensuring all required inputs have values.
   @Input({required: true, alias: 'control'})
-  set _field(value: Field<T>) {
+  set _field(value: FieldTree<T>) {
     this.field.set(value);
     if (!this.initialized) {
       this.initialize();

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

@@ -16,8 +16,8 @@ import {FieldPathNode} from '../schema/path_node';
 import {assertPathIsCurrent, isSchemaOrSchemaFn, SchemaImpl} from '../schema/schema';
 import {isArray} from '../util/type_guards';
 import type {
-  Field,
   FieldPath,
+  FieldTree,
   LogicFn,
   OneOrMany,
   PathKind,
@@ -73,8 +73,8 @@ function normalizeFormArgs<TValue>(
 }
 
 /**
- * Creates a form wrapped around the given model data. A form is represented as simply a `Field` of
- * the model data.
+ * Creates a form wrapped around the given model data. A form is represented as simply a `FieldTree`
+ * of the model data.
  *
  * `form` uses the given model as the source of truth and *does not* maintain its own copy of the
  * data. This means that updating the value on a `FieldState` updates the originally passed in model
@@ -92,17 +92,17 @@ function normalizeFormArgs<TValue>(
  * @param model A writable signal that contains the model data for the form. The resulting field
  * structure will match the shape of the model and any changes to the form data will be written to
  * the model.
- * @return A `Field` representing a form around the data model.
+ * @return A `FieldTree` representing a form around the data model.
  * @template TValue The type of the data model.
  *
  * @category structure
  * @experimental 21.0.0
  */
-export function form<TValue>(model: WritableSignal<TValue>): Field<TValue>;
+export function form<TValue>(model: WritableSignal<TValue>): FieldTree<TValue>;
 
 /**
- * Creates a form wrapped around the given model data. A form is represented as simply a `Field` of
- * the model data.
+ * Creates a form wrapped around the given model data. A form is represented as simply a `FieldTree`
+ * of the model data.
  *
  * `form` uses the given model as the source of truth and *does not* maintain its own copy of the
  * data. This means that updating the value on a `FieldState` updates the originally passed in model
@@ -139,7 +139,7 @@ export function form<TValue>(model: WritableSignal<TValue>): Field<TValue>;
  *   1. A schema or a function used to specify logic for the form (e.g. validation, disabled fields, etc.).
  *      When passing a schema, the form options can be passed as a third argument if needed.
  *   2. The form options
- * @return A `Field` representing a form around the data model
+ * @return A `FieldTree` representing a form around the data model
  * @template TValue The type of the data model.
  *
  * @category structure
@@ -148,11 +148,11 @@ export function form<TValue>(model: WritableSignal<TValue>): Field<TValue>;
 export function form<TValue>(
   model: WritableSignal<TValue>,
   schemaOrOptions: SchemaOrSchemaFn<TValue> | FormOptions,
-): Field<TValue>;
+): FieldTree<TValue>;
 
 /**
- * Creates a form wrapped around the given model data. A form is represented as simply a `Field` of
- * the model data.
+ * Creates a form wrapped around the given model data. A form is represented as simply a `FieldTree`
+ * of the model data.
  *
  * `form` uses the given model as the source of truth and *does not* maintain its own copy of the
  * data. This means that updating the value on a `FieldState` updates the originally passed in model
@@ -187,7 +187,7 @@ export function form<TValue>(
  * the model.
  * @param schema A schema or a function used to specify logic for the form (e.g. validation, disabled fields, etc.)
  * @param options The form options
- * @return A `Field` representing a form around the data model.
+ * @return A `FieldTree` representing a form around the data model.
  * @template TValue The type of the data model.
  *
  * @category structure
@@ -197,9 +197,9 @@ export function form<TValue>(
   model: WritableSignal<TValue>,
   schema: SchemaOrSchemaFn<TValue>,
   options: FormOptions,
-): Field<TValue>;
+): FieldTree<TValue>;
 
-export function form<TValue>(...args: any[]): Field<TValue> {
+export function form<TValue>(...args: any[]): FieldTree<TValue> {
   const [model, schema, options] = normalizeFormArgs<TValue>(args);
   const injector = options?.injector ?? inject(Injector);
   const pathNode = runInInjectionContext(injector, () => SchemaImpl.rootCompile(schema));
@@ -208,7 +208,7 @@ export function form<TValue>(...args: any[]): Field<TValue> {
   const fieldRoot = FieldNode.newRoot(fieldManager, model, pathNode, adapter);
   fieldManager.createFieldManagementEffect(fieldRoot.structure);
 
-  return fieldRoot.fieldProxy as Field<TValue>;
+  return fieldRoot.fieldProxy as FieldTree<TValue>;
 }
 
 /**
@@ -225,8 +225,8 @@ export function form<TValue>(...args: any[]): Field<TValue> {
  * });
  * ```
  *
- * When binding logic to the array items, the `Field` for the array item is passed as an additional
- * argument. This can be used to reference other properties on the item.
+ * When binding logic to the array items, the `FieldTree` for the array item is passed as an
+ * additional argument. This can be used to reference other properties on the item.
  *
  * @example
  * ```
@@ -358,14 +358,14 @@ export function applyWhenValue(
 }
 
 /**
- * Submits a given `Field` using the given action function and applies any server errors resulting
- * from the action to the field. Server 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 server
- * error.
+ * Submits a given `FieldTree` using the given action function and applies any server errors
+ * resulting from the action to the field. Server 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
+ * server error.
  *
  * @example
  * ```
- * async function registerNewUser(registrationForm: Field<{username: string, password: string}>) {
+ * async function registerNewUser(registrationForm: FieldTree<{username: string, password: string}>) {
  *   const result = await myClient.registerNewUser(registrationForm().value());
  *   if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
  *     return [{
@@ -392,8 +392,8 @@ export function applyWhenValue(
  * @experimental 21.0.0
  */
 export async function submit<TValue>(
-  form: Field<TValue>,
-  action: (form: Field<TValue>) => Promise<TreeValidationResult>,
+  form: FieldTree<TValue>,
+  action: (form: FieldTree<TValue>) => Promise<TreeValidationResult>,
 ) {
   const node = form() as FieldNode;
   markAllAsTouched(node);
@@ -445,7 +445,7 @@ function setServerErrors(
  * 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 `Field` that this schema binds to.
+ * @template TValue The value type of a `FieldTree` that this schema binds to.
  *
  * @category structure
  * @experimental 21.0.0