feat(forms): add [formField] directive

mmalerba · kirjs · commit 2d85ae581156 · 2026-01-06T17:21:06.000-05:00
This will replace the `[field]` directive, since `[field]` is a very
generic name for signal forms to commandeer

refactor(forms): hook up `formField` directive in compiler

Hooks up the `formField` direcive to get the same treatment as the
`field` directive in the compiler.

apply updated formatting
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -170,7 +170,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     // (undocumented)
     readonly errors: Signal<ValidationError.WithField[]>;
     readonly errorSummary: Signal<ValidationError.WithField[]>;
-    readonly fieldBindings: Signal<readonly Field<unknown>[]>;
+    readonly formFieldBindings: Signal<readonly (Field<unknown> | FormField<unknown>)[]>;
     readonly hidden: Signal<boolean>;
     readonly invalid: Signal<boolean>;
     readonly keyInParent: Signal<TKey>;
@@ -196,12 +196,37 @@ export function form<TModel>(model: WritableSignal<TModel>, schemaOrOptions: Sch
 // @public
 export function form<TModel>(model: WritableSignal<TModel>, schema: SchemaOrSchemaFn<TModel>, options: FormOptions): FieldTree<TModel>;
 
+// @public
+export const FORM_FIELD: InjectionToken<FormField<unknown>>;
+
 // @public
 export interface FormCheckboxControl extends FormUiControl {
     readonly checked: ModelSignal<boolean>;
     readonly value?: undefined;
 }
 
+// @public
+export class FormField<T> {
+    // (undocumented)
+    readonly [ɵCONTROL]: {
+        readonly create: typeof ɵɵcontrolCreate;
+        readonly update: typeof ɵcontrolUpdate;
+    };
+    // (undocumented)
+    readonly element: HTMLElement;
+    // (undocumented)
+    readonly formField: i0.InputSignal<FieldTree<T>>;
+    protected getOrCreateNgControl(): InteropNgControl;
+    // (undocumented)
+    readonly injector: Injector;
+    // (undocumented)
+    readonly state: i0.Signal<[T] extends [_angular_forms.AbstractControl<any, any, any>] ? CompatFieldState<T, string | number> : FieldState<T, string | number>>;
+    // (undocumented)
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FormField<any>, "[formField]", never, { "formField": { "alias": "formField"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormField<any>, never>;
+}
+
 // @public
 export interface FormOptions {
     adapter?: FieldAdapter;
@@ -520,7 +545,7 @@ export type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> =
 // @public
 export interface SignalFormsConfig {
     classes?: {
-        [className: string]: (state: Field<unknown>) => boolean;
+        [className: string]: (state: Field<unknown> | FormField<unknown>) => boolean;
     };
 }
 
diff --git a/packages/compiler-cli/src/ngtsc/typecheck/src/ops/signal_forms.ts b/packages/compiler-cli/src/ngtsc/typecheck/src/ops/signal_forms.ts
@@ -22,15 +22,15 @@ import {
   TmplAstTemplate,
 } from '@angular/compiler';
 import ts from 'typescript';
-import {TcbOp} from './base';
-import type {Context} from './context';
-import type {Scope} from './scope';
-import {addParseSpanInfo} from '../diagnostics';
-import {tsDeclareVariable} from '../ts_util';
 import {TypeCheckableDirectiveMeta} from '../../api';
-import {tcbExpression} from './expression';
 import {markIgnoreDiagnostics} from '../comments';
+import {addParseSpanInfo} from '../diagnostics';
+import {tsDeclareVariable} from '../ts_util';
+import {TcbOp} from './base';
 import {TcbBoundAttribute} from './bindings';
+import type {Context} from './context';
+import {tcbExpression} from './expression';
+import type {Scope} from './scope';
 
 /** Possible types of custom form control directives. */
 export type CustomFormControlType = 'value' | 'checkbox';
@@ -103,7 +103,11 @@ export class TcbNativeFieldOp extends TcbOp {
   override execute(): null {
     const inputs = this.node instanceof TmplAstHostElement ? this.node.bindings : this.node.inputs;
     const fieldBinding =
-      inputs.find((input) => input.type === BindingType.Property && input.name === 'field') ?? null;
+      inputs.find(
+        (input) =>
+          input.type === BindingType.Property &&
+          (input.name === 'field' || input.name === 'formField'),
+      ) ?? null;
 
     // This should only happen if there's something like `<input field="static"/>`
     // which will be caught by the input type checking of the `Field` directive.
@@ -227,7 +231,8 @@ export function expandBoundAttributesForField(
   customFormControlType: CustomFormControlType | null,
 ): TcbBoundAttribute[] | null {
   const fieldBinding = node.inputs.find(
-    (input) => input.type === BindingType.Property && input.name === 'field',
+    (input) =>
+      input.type === BindingType.Property && (input.name === 'field' || input.name === 'formField'),
   );
 
   if (!fieldBinding) {
@@ -281,7 +286,7 @@ export function expandBoundAttributesForField(
 }
 
 export function isFieldDirective(meta: TypeCheckableDirectiveMeta): boolean {
-  if (meta.name !== 'Field') {
+  if (meta.name !== 'Field' && meta.name !== 'FormField') {
     return false;
   }
 
diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_bindings/control_bindings/control_bindings.js b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_bindings/control_bindings/control_bindings.js
@@ -19,7 +19,7 @@ export class MyComponent {
         i0.ɵɵadvance();
         i0.ɵɵattribute("field", ctx.value);
         i0.ɵɵadvance(2);
-        i0.ɵɵcontrol(ctx.value);
+        i0.ɵɵcontrol(ctx.value, "field");
       }
     },
     dependencies: [Field],
diff --git a/packages/compiler/src/render3/view/compiler.ts b/packages/compiler/src/render3/view/compiler.ts
@@ -8,9 +8,9 @@
 
 import {ConstantPool} from '../../constant_pool';
 import * as core from '../../core';
+import {CssSelector} from '../../directive_matching';
 import * as o from '../../output/output_ast';
 import {ParseError, ParseSourceSpan} from '../../parse_util';
-import {CssSelector} from '../../directive_matching';
 import {ShadowCss} from '../../shadow_css';
 import {CompilationJobKind, TemplateCompilationMode} from '../../template/pipeline/src/compilation';
 import {emitHostBindingFunction, emitTemplateFn, transform} from '../../template/pipeline/src/emit';
diff --git a/packages/compiler/src/template/pipeline/ir/src/ops/update.ts b/packages/compiler/src/template/pipeline/ir/src/ops/update.ts
@@ -1067,7 +1067,8 @@ export function createStoreLetOp(
 /**
  * A specialized {@link PropertyOp} that may bind a form field to a control.
  */
-export interface ControlOp extends Omit<PropertyOp, 'kind' | 'name'> {
+// TODO: Omit name when we remove the `Field` directive.
+export interface ControlOp extends Omit<PropertyOp, 'kind'> {
   kind: OpKind.Control;
 }
 
@@ -1076,6 +1077,7 @@ export function createControlOp(op: BindingOp): ControlOp {
   return {
     kind: OpKind.Control,
     target: op.target,
+    name: op.name,
     expression: op.expression,
     bindingKind: op.bindingKind,
     securityContext: op.securityContext,
diff --git a/packages/compiler/src/template/pipeline/src/ingest.ts b/packages/compiler/src/template/pipeline/src/ingest.ts
@@ -318,7 +318,9 @@ function ingestElement(unit: ViewCompilationUnit, element: t.Element): void {
 
   // We want to ensure that the controlCreateOp is after the ops that create the element
   const fieldInput = element.inputs.find(
-    (input) => input.name === 'field' && input.type === e.BindingType.Property,
+    (input) =>
+      (input.name === 'field' || input.name === 'formField') &&
+      input.type === e.BindingType.Property,
   );
   if (fieldInput) {
     // If the input name is 'field', this could be a form control binding which requires a
diff --git a/packages/compiler/src/template/pipeline/src/instruction.ts b/packages/compiler/src/template/pipeline/src/instruction.ts
@@ -596,6 +596,7 @@ export function property(
 }
 
 export function control(
+  name: string,
   expression: o.Expression | ir.Interpolation,
   sanitizer: o.Expression | null,
   sourceSpan: ParseSourceSpan,
@@ -606,6 +607,7 @@ export function control(
   } else {
     args.push(expression);
   }
+  args.push(o.literal(name));
   if (sanitizer !== null) {
     args.push(sanitizer);
   }
diff --git a/packages/compiler/src/template/pipeline/src/phases/attribute_extraction.ts b/packages/compiler/src/template/pipeline/src/phases/attribute_extraction.ts
@@ -62,7 +62,7 @@ export function extractAttributes(job: CompilationJob): void {
               op.target,
               ir.BindingKind.Property,
               null,
-              'field',
+              op.name,
               /* expression */ null,
               /* i18nContext */ null,
               /* i18nMessage */ null,
diff --git a/packages/compiler/src/template/pipeline/src/phases/binding_specialization.ts b/packages/compiler/src/template/pipeline/src/phases/binding_specialization.ts
@@ -127,7 +127,7 @@ export function specializeBindings(job: CompilationJob): void {
                 op.sourceSpan,
               ),
             );
-          } else if (op.name === 'field') {
+          } else if (op.name === 'field' || op.name === 'formField') {
             ir.OpList.replace<ir.UpdateOp>(op, ir.createControlOp(op));
           } else {
             ir.OpList.replace<ir.UpdateOp>(
diff --git a/packages/compiler/src/template/pipeline/src/phases/reify.ts b/packages/compiler/src/template/pipeline/src/phases/reify.ts
@@ -743,7 +743,7 @@ function reifyProperty(op: ir.PropertyOp): ir.UpdateOp {
 }
 
 function reifyControl(op: ir.ControlOp): ir.UpdateOp {
-  return ng.control(op.expression, op.sanitizer, op.sourceSpan);
+  return ng.control(op.name, op.expression, op.sanitizer, op.sourceSpan);
 }
 
 function reifyIrExpression(expr: o.Expression): o.Expression {
diff --git a/packages/core/src/render3/instructions/control.ts b/packages/core/src/render3/instructions/control.ts
@@ -85,15 +85,15 @@ export function ɵɵcontrolCreate(): void {
  *
  * @codeGenApi
  */
-export function ɵɵcontrol<T>(value: T, sanitizer?: SanitizerFn | null): void {
+export function ɵɵcontrol<T>(value: T, name: string, sanitizer?: SanitizerFn | null): void {
   const lView = getLView();
   const tNode = getSelectedTNode();
   const bindingIndex = nextBindingIndex();
 
   if (bindingUpdated(lView, bindingIndex, value)) {
     const tView = getTView();
-    setPropertyAndInputs(tNode, lView, 'field', value, lView[RENDERER], sanitizer);
-    ngDevMode && storePropertyBindingMetadata(tView.data, tNode, 'field', bindingIndex);
+    setPropertyAndInputs(tNode, lView, name, value, lView[RENDERER], sanitizer);
+    ngDevMode && storePropertyBindingMetadata(tView.data, tNode, name, bindingIndex);
   }
 
   updateControl(lView, tNode);
@@ -146,7 +146,7 @@ function updateControl<T>(lView: LView, tNode: TNode): void {
 function initializeControlFirstCreatePass<T>(tView: TView, tNode: TNode, lView: LView): void {
   ngDevMode && assertFirstCreatePass(tView);
 
-  const directiveIndices = tNode.inputs?.['field'];
+  const directiveIndices = tNode.inputs?.['field'] ?? tNode.inputs?.['formField'];
   if (!directiveIndices) {
     return; // There are no matching inputs for the `[field]` property binding.
   }
diff --git a/packages/forms/signals/public_api.ts b/packages/forms/signals/public_api.ts
@@ -14,6 +14,7 @@
 export * from './src/api/control';
 export * from './src/api/di';
 export * from './src/api/field_directive';
+export * from './src/api/form_field_directive';
 export * from './src/api/rules';
 export * from './src/api/rules/debounce';
 export * from './src/api/rules/metadata';
diff --git a/packages/forms/signals/src/api/di.ts b/packages/forms/signals/src/api/di.ts
@@ -9,6 +9,7 @@
 import {type Provider} from '@angular/core';
 import {SIGNAL_FORMS_CONFIG} from '../field/di';
 import type {Field} from './field_directive';
+import type {FormField} from './form_field_directive';
 
 /**
  * Configuration options for signal forms.
@@ -17,7 +18,7 @@ import type {Field} from './field_directive';
  */
 export interface SignalFormsConfig {
   /** A map of CSS class names to predicate functions that determine when to apply them. */
-  classes?: {[className: string]: (state: Field<unknown>) => boolean};
+  classes?: {[className: string]: (state: Field<unknown> | FormField<unknown>) => boolean};
 }
 
 /**
diff --git a/packages/forms/signals/src/api/field_directive.ts b/packages/forms/signals/src/api/field_directive.ts
@@ -117,12 +117,12 @@ export class Field<T> {
     effect(
       (onCleanup) => {
         const fieldNode = this.state() as unknown as FieldNode;
-        fieldNode.nodeState.fieldBindings.update((controls) => [
+        fieldNode.nodeState.formFieldBindings.update((controls) => [
           ...controls,
           this as Field<unknown>,
         ]);
         onCleanup(() => {
-          fieldNode.nodeState.fieldBindings.update((controls) =>
+          fieldNode.nodeState.formFieldBindings.update((controls) =>
             controls.filter((c) => c !== this),
           );
         });
diff --git a/packages/forms/signals/src/api/form_field_directive.ts b/packages/forms/signals/src/api/form_field_directive.ts
diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts
diff --git a/packages/forms/signals/src/field/node.ts b/packages/forms/signals/src/field/node.ts
diff --git a/packages/forms/signals/src/field/state.ts b/packages/forms/signals/src/field/state.ts
diff --git a/packages/forms/signals/test/web/dynamic_binding.spec.ts b/packages/forms/signals/test/web/dynamic_binding.spec.ts
diff --git a/packages/forms/signals/test/web/field_directive.spec.ts b/packages/forms/signals/test/web/field_directive.spec.ts
diff --git a/packages/forms/signals/test/web/form_field_directive.spec.ts b/packages/forms/signals/test/web/form_field_directive.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ export class MyComponent {`
`19`	`19`	`i0.ɵɵadvance();`
`20`	`20`	`i0.ɵɵattribute("field", ctx.value);`
`21`	`21`	`i0.ɵɵadvance(2);`
`22`		`- i0.ɵɵcontrol(ctx.value);`
	`22`	`+ i0.ɵɵcontrol(ctx.value, "field");`
`23`	`23`	`}`
`24`	`24`	`},`
`25`	`25`	`dependencies: [Field],`
Original file line number	Diff line number	Diff line change
`@@ -596,6 +596,7 @@ export function property(`
`596`	`596`	`}`
`597`	`597`
`598`	`598`	`export function control(`
	`599`	`+ name: string,`
`599`	`600`	`expression: o.Expression \| ir.Interpolation,`
`600`	`601`	`sanitizer: o.Expression \| null,`
`601`	`602`	`sourceSpan: ParseSourceSpan,`
`@@ -606,6 +607,7 @@ export function control(`
`606`	`607`	`} else {`
`607`	`608`	`args.push(expression);`
`608`	`609`	`}`
	`610`	`+ args.push(o.literal(name));`
`609`	`611`	`if (sanitizer !== null) {`
`610`	`612`	`args.push(sanitizer);`
`611`	`613`	`}`
Original file line number	Diff line number	Diff line change
`@@ -743,7 +743,7 @@ function reifyProperty(op: ir.PropertyOp): ir.UpdateOp {`
`743`	`743`	`}`
`744`	`744`
`745`	`745`	`function reifyControl(op: ir.ControlOp): ir.UpdateOp {`
`746`		`- return ng.control(op.expression, op.sanitizer, op.sourceSpan);`
	`746`	`+ return ng.control(op.name, op.expression, op.sanitizer, op.sourceSpan);`
`747`	`747`	`}`
`748`	`748`
`749`	`749`	`function reifyIrExpression(expr: o.Expression): o.Expression {`