perf(core): tree shake unused dynamic [field] binding instructions (#65599)

leonsenft · pkozlowski-opensource · commit e6d5632a3059 · 2025-12-03T15:10:49.000+01:00
Move the instructions used to dynamically bind a `Field` directive to a form control onto the `Field` itself. This way the instructions are only retained if the app uses the `Field` directive. PR Close #65599
diff --git a/goldens/public-api/forms/signals/compat/index.api.md b/goldens/public-api/forms/signals/compat/index.api.md
@@ -18,8 +18,10 @@ import { ValidatorFn } from '@angular/forms';
 import { WritableSignal } from '@angular/core';
 import { ɵCONTROL } from '@angular/core';
 import { ɵControl } from '@angular/core';
+import { ɵcontrolUpdate } from '@angular/core';
 import { ɵFieldState } from '@angular/core';
 import { ɵInteropControl } from '@angular/core';
+import { ɵɵcontrolCreate } from '@angular/core';
 
 // @public
 export function compatForm<TModel>(model: WritableSignal<TModel>): FieldTree<TModel>;
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -27,8 +27,10 @@ import { ValidatorFn } from '@angular/forms';
 import { WritableSignal } from '@angular/core';
 import { ɵCONTROL } from '@angular/core';
 import { ɵControl } from '@angular/core';
+import { ɵcontrolUpdate } from '@angular/core';
 import { ɵFieldState } from '@angular/core';
 import { ɵInteropControl } from '@angular/core';
+import { ɵɵcontrolCreate } from '@angular/core';
 
 // @public
 export function aggregateMetadata<TValue, TMetadataItem, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, key: AggregateMetadataKey<any, TMetadataItem>, logic: NoInfer<LogicFn<TValue, TMetadataItem, TPathKind>>): void;
@@ -144,7 +146,10 @@ export const FIELD: InjectionToken<Field<unknown>>;
 // @public
 export class Field<T> implements ɵControl<T> {
     // (undocumented)
-    readonly [ɵCONTROL]: undefined;
+    readonly [ɵCONTROL]: {
+        readonly create: typeof ɵɵcontrolCreate;
+        readonly update: typeof ɵcontrolUpdate;
+    };
     // (undocumented)
     readonly classes: (readonly [string, i0.Signal<boolean>])[];
     // (undocumented)
diff --git a/packages/core/src/core_render3_private_export.ts b/packages/core/src/core_render3_private_export.ts
@@ -94,6 +94,7 @@ export {
   ɵɵcontentQuerySignal,
   ɵɵcontrol,
   ɵɵcontrolCreate,
+  ɵcontrolUpdate,
   ɵɵcomponentInstance,
   ɵɵdefineComponent,
   ɵɵdefineDirective,
diff --git a/packages/core/src/render3/dynamic_bindings.ts b/packages/core/src/render3/dynamic_bindings.ts
@@ -11,8 +11,9 @@ import {RuntimeError, RuntimeErrorCode} from '../errors';
 import {Type, Writable} from '../interface/type';
 import {assertNotDefined} from '../util/assert';
 import {bindingUpdated} from './bindings';
-import {ɵɵcontrolCreate as controlCreate, updateControl} from './instructions/control';
 import {setDirectiveInput, storePropertyBindingMetadata} from './instructions/shared';
+import {ɵCONTROL} from './interfaces/control';
+import {TNode} from './interfaces/node';
 import {TVIEW} from './interfaces/view';
 import {getCurrentTNode, getLView, getSelectedTNode, nextBindingIndex} from './state';
 import {stringifyForError} from './util/stringify_utils';
@@ -102,6 +103,23 @@ function inputBindingUpdate(targetDirectiveIdx: number, publicName: string, valu
   }
 }
 
+/**
+ * Instructions for dynamically binding a `Field` to a form control.
+ */
+interface ControlBinding {
+  create: () => void;
+  update: () => void;
+}
+
+/**
+ * Returns a {@link ControlBinding} for the target directive if it is a 'Field' directive.
+ */
+function controlBinding(binding: BindingInternal, tNode: TNode): ControlBinding | undefined {
+  const lView = getLView();
+  const directive = lView[tNode.directiveStart + binding.targetIdx!];
+  return directive[ɵCONTROL];
+}
+
 /**
  * Creates an input binding.
  * @param publicName Public name of the input to bind to.
@@ -125,15 +143,16 @@ export function inputBinding(publicName: string, value: () => unknown): Binding
   if (publicName === 'field') {
     const binding: BindingInternal = {
       [BINDING]: FIELD_BINDING_METADATA,
-      create: () => controlCreate(),
+      create: () => {
+        // Set up the form control bindings, if this is a 'Field' directive bound to a form control.
+        controlBinding(binding, getCurrentTNode()!)?.create();
+      },
       update: () => {
-        // Update the [field] input binding.
-        inputBindingUpdate((binding as BindingInternal).targetIdx!, publicName, value());
+        // Update the [field] input binding, regardless of whether this targets a 'Field' directive.
+        inputBindingUpdate(binding.targetIdx!, publicName, value());
 
         // Update the form control bindings, if this is a 'Field' directive bound to a form control.
-        const lView = getLView();
-        const tNode = getSelectedTNode();
-        updateControl(lView, tNode);
+        controlBinding(binding, getSelectedTNode()!)?.update();
       },
     };
     return binding;
@@ -143,7 +162,7 @@ export function inputBinding(publicName: string, value: () => unknown): Binding
   // don't get tree shaken when constructed by a function like this.
   const binding: BindingInternal = {
     [BINDING]: INPUT_BINDING_METADATA,
-    update: () => inputBindingUpdate((binding as BindingInternal).targetIdx!, publicName, value()),
+    update: () => inputBindingUpdate(binding.targetIdx!, publicName, value()),
   };
 
   return binding;
diff --git a/packages/core/src/render3/index.ts b/packages/core/src/render3/index.ts
@@ -95,6 +95,7 @@ export {
   ɵɵproperty,
   ɵɵcontrol,
   ɵɵcontrolCreate,
+  ɵcontrolUpdate,
   ɵɵcontentQuery,
   ɵɵcontentQuerySignal,
   ɵɵloadQuery,
diff --git a/packages/core/src/render3/instructions/control.ts b/packages/core/src/render3/instructions/control.ts
@@ -56,7 +56,6 @@ export function ɵɵcontrolCreate(): void {
   }
 
   const control = getControlDirective(tNode, lView);
-
   if (!control) {
     return;
   }
@@ -102,12 +101,27 @@ export function ɵɵcontrol<T>(value: T, sanitizer?: SanitizerFn | null): void {
 }
 
 /**
- * Updates a `ɵControl` to manage a native or custom form control.
+ * Calls {@link updateControl} with the current `LView` and selected `TNode`.
+ *
+ * NOTE: This instruction exists solely to accommodate tree-shakeable, dynamic control bindings.
+ * It's intended to be referenced exclusively by the Signal Forms `Field` directive and should not
+ * be referenced by any other means.
+ */
+export function ɵcontrolUpdate(): void {
+  const lView = getLView();
+  const tNode = getSelectedTNode();
+  updateControl(lView, tNode);
+}
+
+/**
+ * Updates the form control properties of a `field` bound form control.
+ *
+ * Does nothing if the current node is not a `field` bound form control.
  *
  * @param lView The `LView` that contains the control.
  * @param tNode The `TNode` of the control.
  */
-export function updateControl<T>(lView: LView, tNode: TNode): void {
+function updateControl<T>(lView: LView, tNode: TNode): void {
   const control = getControlDirective(tNode, lView);
   if (control) {
     updateControlClasses(lView, tNode, control);
diff --git a/packages/core/src/render3/interfaces/control.ts b/packages/core/src/render3/interfaces/control.ts
@@ -11,12 +11,25 @@ import {WritableSignal} from '../reactivity/signal';
 /** A unique symbol used to identify {@link ɵControl} implementations. */
 export const ɵCONTROL: unique symbol = Symbol('CONTROL');
 
+/**
+ * Instructions for dynamically binding a {@link ɵControl} to a form control.
+ */
+export interface ɵControlBinding {
+  create(): void;
+  update(): void;
+}
+
 /**
  * A directive that binds a {@link ɵFieldState} to a form control.
  */
 export interface ɵControl<T> {
-  /** The presence of this property is used to identify {@link ɵControl} implementations. */
-  readonly [ɵCONTROL]: undefined;
+  /**
+   * The presence of this property is used to identify {@link ɵControl} implementations, while the
+   * value is used to store the instructions for dynamically binding to a form control. The
+   * instructions are stored on the directive so that they can be tree-shaken when the directive is
+   * not used.
+   */
+  readonly [ɵCONTROL]: ɵControlBinding;
 
   /** The state of the field bound to this control. */
   readonly state: Signal<ɵFieldState<T>>;
diff --git a/packages/core/test/bundling/create_component/bundle.golden_symbols.json b/packages/core/test/bundling/create_component/bundle.golden_symbols.json
diff --git a/packages/forms/signals/src/api/field_directive.ts b/packages/forms/signals/src/api/field_directive.ts
