feat(forms): support FieldState.name() & propagate to controls

Automatically generate a `name` for `Field`s, and bind that on an HTML
control when available.

Author: alxhub

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

@@ -16,6 +16,7 @@ export interface FormUiControl<TValue> {
   readonly readonly?: InputSignal<boolean | undefined>;
   readonly valid?: InputSignal<boolean | undefined>;
   readonly touched?: InputSignal<boolean | undefined>;
+  readonly name?: InputSignal<string>;
 
   readonly touch?: OutputRef<void>;
 

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

@@ -30,6 +30,7 @@ export interface FormOptions {
    * current [injection context](guide/di/dependency-injection-context), will be used.
    */
   injector?: Injector;
+  name?: string;
 }
 
 /** Extracts the model, schema, and options from the arguments passed to `form()`. */
@@ -172,7 +173,7 @@ export function form<TValue>(...args: any[]): Field<TValue> {
   const [model, schema, options] = normalizeFormArgs<TValue>(args);
   const injector = options?.injector ?? inject(Injector);
   const pathNode = runInInjectionContext(injector, () => SchemaImpl.rootCompile(schema));
-  const fieldManager = new FormFieldManager(injector);
+  const fieldManager = new FormFieldManager(injector, options?.name);
   const fieldRoot = FieldNode.newRoot(fieldManager, model, pathNode);
   fieldManager.createFieldManagementEffect(fieldRoot.structure);
 
@@ -371,3 +372,9 @@ function markAllAsTouched(node: FieldNode) {
     markAllAsTouched(child);
   }
 }
+
+let nextFormId = 0;
+function nextFormName(): string {
+  // TODO: include APP_ID?
+  return `form${nextFormId++}`;
+}

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

@@ -278,6 +278,11 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
    * A signal indicating whether the field is currently in the process of being submitted.
    */
   readonly submitting: Signal<boolean>;
+  /**
+   * A signal of a unique name for the field, by default based on the name of its parent field.
+   */
+  readonly name: Signal<string>;
+
   /**
    * The property key in the parent field under which this field is stored. If the parent field is
    * array-valued, for example, this is the index of this field in that array.

packages/forms/experimental/src/controls/control.ts

@@ -94,6 +94,7 @@ export class Control<T> {
 
     this.maybeSynchronize(() => this.state().readonly(), withBooleanAttribute(input, 'readonly'));
     this.maybeSynchronize(() => this.state().disabled(), withBooleanAttribute(input, 'disabled'));
+    this.maybeSynchronize(() => this.state().name(), withAttribute(input, 'name'));
 
     this.maybeSynchronize(this.propertySource(MIN), withAttribute(input, 'min'));
     this.maybeSynchronize(this.propertySource(MIN_LENGTH), withAttribute(input, 'minLength'));
@@ -135,6 +136,7 @@ export class Control<T> {
   private setupCustomUiControl(cmp: FormUiControl<T>) {
     // Input bindings:
     this.maybeSynchronize(() => this.state().value(), withInput(cmp.value));
+    this.maybeSynchronize(() => this.state().name(), withInput(cmp.name));
     this.maybeSynchronize(() => this.state().disabled(), withInput(cmp.disabled));
     this.maybeSynchronize(() => this.state().readonly(), withInput(cmp.readonly));
     this.maybeSynchronize(() => this.state().errors(), withInput(cmp.errors));

packages/forms/experimental/src/field/manager.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {effect, Injector, untracked} from '@angular/core';
+import {APP_ID, effect, inject, Injector, untracked} from '@angular/core';
 import type {FieldNodeStructure} from './structure';
 
 /**
@@ -17,7 +17,13 @@ import type {FieldNodeStructure} from './structure';
  * destroyed, which is the job of the `FormFieldManager`.
  */
 export class FormFieldManager {
-  constructor(readonly injector: Injector) {}
+  readonly rootName: string;
+  constructor(
+    readonly injector: Injector,
+    rootName: string | undefined,
+  ) {
+    this.rootName = rootName ?? `${this.injector.get(APP_ID)}.form${nextFormId++}`;
+  }
 
   /**
    * Contains all child field structures that have been created as part of the current form.
@@ -73,3 +79,5 @@ export class FormFieldManager {
     }
   }
 }
+
+let nextFormId = 0;

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

@@ -149,12 +149,15 @@ export class FieldNode implements FieldState<unknown> {
     return this.submitState.submitting;
   }
 
+  get name(): Signal<string> {
+    return this.nodeState.name;
+  }
+
   property<M>(prop: AggregateProperty<M, any>): Signal<M>;
   property<M>(prop: Property<M>): M | undefined;
   property<M>(prop: Property<M> | AggregateProperty<M, any>): Signal<M> | M | undefined {
     return this.propertyState.get(prop);
   }
-
   hasProperty(prop: Property<unknown> | AggregateProperty<unknown, any>): boolean {
     return this.propertyState.has(prop);
   }

packages/forms/experimental/src/field/state.ts

@@ -113,4 +113,13 @@ export class FieldNodeState {
         this.node.logicNode.logic.hidden.compute(this.node.context)) ??
       false,
   );
+
+  readonly name: Signal<string> = computed(() => {
+    const parent = this.node.structure.parent;
+    if (!parent) {
+      return this.node.structure.fieldManager.rootName;
+    }
+
+    return `${parent.name()}.${this.node.structure.keyInParent()}`;
+  });
 }

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

@@ -361,6 +361,27 @@ describe('FieldNode', () => {
     });
   });
 
+  describe('names', () => {
+    it('auto-generates a name for the form', () => {
+      const f = form(signal({}), {injector: TestBed.inject(Injector)});
+      expect(f().name()).toMatch(/^a.form\d+$/);
+    });
+
+    it('uses a specific name for the form when given', () => {
+      const f = form(signal({}), {injector: TestBed.inject(Injector), name: 'test'});
+      expect(f().name()).toBe('test');
+    });
+
+    it('derives child field names from parents', () => {
+      const f = form(signal({user: {firstName: 'Alex'}}), {
+        injector: TestBed.inject(Injector),
+        name: 'test',
+      });
+      expect(f.user().name()).toBe('test.user');
+      expect(f.user.firstName().name()).toBe('test.user.firstName');
+    });
+  });
+
   describe('disabled', () => {
     it('should allow logic to make a node disabled', () => {
       const f = form(