refactor(core): add framework support for binding form controls (angular#63773)

Move most of the implementation of the `Control` directive into core
framework instructions. This allows field state changes to be propagated
to their corresponding UI controls directly during execution of a
template update block, instead of relying on `effect()`s to synchronize
each change later during the update (and too late in the case of
required inputs).

* Define a private API in `@angular/core` for signal forms to implement:
  * `ɵControl` for the `Control` directive.
  * `ɵFieldState` for the control's associated `FieldState`.
* Emit specialized instructions when compiling a `[control]` binding:
  * `ɵɵcontrolCreate` sets up the `ɵControl` directive if present,
    determines whether it's bound to a native control element or a
    custom control component, and adds the appropriate event listeners
    to notify the `ɵFieldState` of UI changes.
  * `ɵɵcontrol` propagates changes from `ɵFieldState` properties to their
    corresponding UI control properties (in additional to binding the `control`
    property itself).

PR Close angular#63773

Author: leonsenft

goldens/public-api/core/errors.api.md

@@ -76,6 +76,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     INVALID_BINDING_TARGET = 316,
     // (undocumented)
+    INVALID_CONTROL_HOST = 318,
+    // (undocumented)
     INVALID_DIFFER_INPUT = 900,
     // (undocumented)
     INVALID_EVENT_BINDING = 306,

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

@@ -4,22 +4,22 @@
 
 ```ts
 
-import { ControlValueAccessor } from '@angular/forms';
 import { DestroyableInjector } from '@angular/core';
-import { ElementRef } from '@angular/core';
 import { HttpResourceOptions } from '@angular/common/http';
 import { HttpResourceRequest } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { InjectionToken } from '@angular/core';
 import { Injector } from '@angular/core';
 import { InputSignal } from '@angular/core';
 import { ModelSignal } from '@angular/core';
-import { NgControl } from '@angular/forms';
 import { OutputRef } from '@angular/core';
 import { ResourceRef } from '@angular/core';
 import { Signal } from '@angular/core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { WritableSignal } from '@angular/core';
+import { ɵCONTROL } from '@angular/core';
+import { ɵControl } from '@angular/core';
+import { ɵFieldState } from '@angular/core';
 
 // @public
 export class AggregateProperty<TAcc, TItem> {
@@ -69,17 +69,17 @@ export interface ChildFieldContext<TValue> extends RootFieldContext<TValue> {
 export const CONTROL: InjectionToken<Control<unknown>>;
 
 // @public
-export class Control<T> {
-    get cva(): ControlValueAccessor | undefined;
-    readonly cvaArray: ControlValueAccessor[] | null;
-    readonly el: ElementRef<HTMLElement>;
-    readonly field: i0.WritableSignal<FieldTree<T>>;
+export class Control<T> implements ɵControl<T> {
+    // (undocumented)
+    readonly [ɵCONTROL]: undefined;
+    // (undocumented)
+    readonly field: i0.InputSignal<FieldTree<T>>;
+    // (undocumented)
+    register(): void;
     // (undocumented)
-    set _field(value: FieldTree<T>);
-    get ngControl(): NgControl;
     readonly state: i0.Signal<FieldState<T, string | number>>;
     // (undocumented)
-    static ɵdir: i0.ɵɵDirectiveDeclaration<Control<any>, "[control]", never, { "_field": { "alias": "control"; "required": true; }; }, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<Control<any>, "[control]", never, { "field": { "alias": "control"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<Control<any>, never>;
 }
@@ -137,29 +137,24 @@ export type FieldPath<TValue, TPathKind extends PathKind = PathKind.Root> = {
 } : unknown);
 
 // @public
-export interface FieldState<TValue, TKey extends string | number = string | number> {
+export interface FieldState<TValue, TKey extends string | number = string | number> extends ɵFieldState<TValue> {
     readonly controls: Signal<readonly Control<unknown>[]>;
     readonly dirty: Signal<boolean>;
-    readonly disabled: Signal<boolean>;
+    // (undocumented)
     readonly disabledReasons: Signal<readonly DisabledReason[]>;
+    // (undocumented)
     readonly errors: Signal<ValidationError[]>;
     readonly errorSummary: Signal<ValidationError[]>;
     hasProperty(key: Property<any> | AggregateProperty<any, any>): boolean;
     readonly hidden: Signal<boolean>;
     readonly invalid: Signal<boolean>;
     readonly keyInParent: Signal<TKey>;
-    markAsDirty(): void;
-    markAsTouched(): void;
-    readonly name: Signal<string>;
     readonly pending: Signal<boolean>;
     property<M>(prop: AggregateProperty<M, any>): Signal<M>;
     property<M>(prop: Property<M>): M | undefined;
-    readonly readonly: Signal<boolean>;
     reset(): void;
     readonly submitting: Signal<boolean>;
-    readonly touched: Signal<boolean>;
     readonly valid: Signal<boolean>;
-    readonly value: WritableSignal<TValue>;
 }
 
 // @public

packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_bindings/control_bindings/GOLDEN_PARTIAL.js

@@ -21,12 +21,16 @@ export class MyComponent {
 }
 MyComponent.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "0.0.0-PLACEHOLDER", ngImport: i0, type: MyComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
 MyComponent.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "0.0.0-PLACEHOLDER", type: MyComponent, isStandalone: true, selector: "ng-component", ngImport: i0, template: `
+    <div control="Not a form control"></div>
+    <div [attr.control]="value">Not a form control either.</div>
     <input [control]="value">
   `, isInline: true, dependencies: [{ kind: "directive", type: Control, selector: "[control]", inputs: ["control"] }] });
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "0.0.0-PLACEHOLDER", ngImport: i0, type: MyComponent, decorators: [{
             type: Component,
             args: [{
                     template: `
+    <div control="Not a form control"></div>
+    <div [attr.control]="value">Not a form control either.</div>
     <input [control]="value">
   `,
                     imports: [Control],

packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_bindings/control_bindings/control_bindings.js

@@ -1,14 +1,23 @@
 MyComponent.ɵcmp = /* @__PURE__ */i0.ɵɵdefineComponent({
   type: MyComponent,
   selectors: [["ng-component"]],
-  decls: 1,
-  vars: 1,
-  consts: [[3, "control"]],
+  decls: 4,
+  vars: 2,
+  consts: [["control", "Not a form control"], [3, "control"]],
   template: function MyComponent_Template(rf, ctx) {
     if (rf & 1) {
-      i0.ɵɵelement(0, "input", 0);
+      i0.ɵɵelement(0, "div", 0);
+      i0.ɵɵelementStart(1, "div");
+      i0.ɵɵtext(2, "Not a form control either.");
+      i0.ɵɵelementEnd();
+      i0.ɵɵelementStart(3, "input", 1);
+      i0.ɵɵcontrolCreate();
+      i0.ɵɵelementEnd();
     }
     if (rf & 2) {
+      i0.ɵɵadvance();
+      i0.ɵɵattribute("control", ctx.value);
+      i0.ɵɵadvance(2);
       i0.ɵɵcontrol(ctx.value);
     }
   },

packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_bindings/control_bindings/control_bindings.ts

@@ -7,6 +7,8 @@ export class Control {
 
 @Component({
   template: `
+    <div control="Not a form control"></div>
+    <div [attr.control]="value">Not a form control either.</div>
     <input [control]="value">
   `,
   imports: [Control],

packages/compiler/src/render3/r3_identifiers.ts

@@ -254,7 +254,9 @@ export class Identifiers {
 
   static ariaProperty: o.ExternalReference = {name: 'ɵɵariaProperty', moduleName: CORE};
   static property: o.ExternalReference = {name: 'ɵɵproperty', moduleName: CORE};
+
   static control: o.ExternalReference = {name: 'ɵɵcontrol', moduleName: CORE};
+  static controlCreate: o.ExternalReference = {name: 'ɵɵcontrolCreate', moduleName: CORE};
 
   static animationEnterListener: o.ExternalReference = {
     name: 'ɵɵanimateEnterListener',

packages/compiler/src/template/pipeline/ir/src/enums.ts

@@ -301,9 +301,17 @@ export enum OpKind {
   AnimationListener,
 
   /**
-   * An operation to bind a signal form field to a control directive.
+   * An operation to bind an expression to a `control` property of an element.
    */
   Control,
+
+  /**
+   * An operation to set up a corresponding {@link Control} operation.
+   *
+   * This is responsible for setting up event listeners on a native or custom form control when
+   * bound to a specialized control directive.
+   */
+  ControlCreate,
 }
 
 /**

packages/compiler/src/template/pipeline/ir/src/expression.ts

@@ -1234,6 +1234,7 @@ export function transformExpressionsInOp(
     case OpKind.SourceLocation:
     case OpKind.ConditionalCreate:
     case OpKind.ConditionalBranchCreate:
+    case OpKind.ControlCreate:
       // These operations contain no expressions.
       break;
     default:

packages/compiler/src/template/pipeline/ir/src/ops/create.ts

@@ -33,7 +33,7 @@ import {
 
 import {ListEndOp, NEW_OP, StatementOp, VariableOp} from './shared';
 
-import type {Interpolation, UpdateOp} from './update';
+import type {BindingOp, Interpolation, UpdateOp} from './update';
 
 /**
  * An operation usable on the creation side of the IR.
@@ -77,7 +77,8 @@ export type CreateOp =
   | AnimationListenerOp
   | AnimationStringOp
   | AnimationOp
-  | SourceLocationOp;
+  | SourceLocationOp
+  | ControlCreateOp;
 
 /**
  * An operation representing the creation of an element or container.
@@ -1950,6 +1951,21 @@ export function createSourceLocationOp(
   };
 }
 
+/**
+ * An operation that determines whether a `[control]` binding targets a specialized control
+ * directive on a native or custom form control, and if so, adds event listeners to synchronize the
+ * bound form field to the form control.
+ */
+export interface ControlCreateOp extends Op<CreateOp> {
+  kind: OpKind.ControlCreate;
+  sourceSpan: ParseSourceSpan;
+}
+
+/** Creates a {@link ControlCreateOp}. */
+export function createControlCreateOp(sourceSpan: ParseSourceSpan): ControlCreateOp {
+  return {kind: OpKind.ControlCreate, sourceSpan, ...NEW_OP};
+}
+
 /**
  * An index into the `consts` array which is shared across the compilation of all views in a
  * component.

packages/compiler/src/template/pipeline/src/ingest.ts

@@ -1344,6 +1344,12 @@ function ingestElementBindings(
         input.sourceSpan,
       ),
     );
+
+    // If the input name is 'control', this could be a form control binding which requires a
+    // `ControlCreateOp` to properly initialize.
+    if (input.type === e.BindingType.Property && input.name === 'control') {
+      unit.create.push(ir.createControlCreateOp(input.sourceSpan));
+    }
   }
 
   unit.create.push(