fix(forms): restrict SignalFormsConfig to a readonly API

leonsenft · atscott · commit 3e7ce0dafcf1 · 2026-03-10T15:07:42.000-07:00
Introduce `FormFieldBinding` to represent a binding between a field and a UI control through a `FormField` directive. This interface is used to restrict `SignalFormsConfig` and `formFieldBindings` to a readonly API. Fix #65779.
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -180,6 +180,14 @@ export class FormField<T> {
     static ɵfac: i0.ɵɵFactoryDeclaration<FormField<any>, never>;
 }
 
+// @public
+export interface FormFieldBinding {
+    readonly element: HTMLElement;
+    focus(options?: FocusOptions): void;
+    readonly injector: Injector;
+    readonly state: Signal<ReadonlyFieldState<unknown>>;
+}
+
 // @public (undocumented)
 export interface FormFieldBindingOptions {
     readonly focus?: (focusOptions?: FocusOptions) => void;
@@ -480,7 +488,7 @@ export interface ReadonlyFieldState<TValue, TKey extends string | number = strin
     readonly errorSummary: Signal<ValidationError.WithFieldTree[]>;
     readonly fieldTree: ReadonlyFieldTree<unknown, TKey>;
     focusBoundControl(options?: FocusOptions): void;
-    readonly formFieldBindings: Signal<readonly FormField<unknown>[]>;
+    readonly formFieldBindings: Signal<readonly FormFieldBinding[]>;
     hasMetadata(key: MetadataKey<any, any, any>): boolean;
     readonly hidden: Signal<boolean>;
     readonly invalid: Signal<boolean>;
@@ -580,7 +588,7 @@ export type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> =
 // @public
 export interface SignalFormsConfig {
     classes?: {
-        [className: string]: (state: FormField<unknown>) => boolean;
+        [className: string]: (formField: FormFieldBinding) => boolean;
     };
 }
 
diff --git a/packages/forms/signals/src/api/di.ts b/packages/forms/signals/src/api/di.ts
@@ -7,8 +7,8 @@
  */
 
 import {type Provider} from '@angular/core';
+import type {FormFieldBinding} from '../api/types';
 import {SIGNAL_FORMS_CONFIG} from '../field/di';
-import type {FormField} from '../directive/form_field_directive';
 
 /**
  * Configuration options for signal forms.
@@ -17,7 +17,9 @@ import type {FormField} from '../directive/form_field_directive';
  */
 export interface SignalFormsConfig {
   /** A map of CSS class names to predicate functions that determine when to apply them. */
-  classes?: {[className: string]: (state: FormField<unknown>) => boolean};
+  classes?: {
+    [className: string]: (formField: FormFieldBinding) => boolean;
+  };
 }
 
 /**
diff --git a/packages/forms/signals/src/api/types.ts b/packages/forms/signals/src/api/types.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Signal, WritableSignal} from '@angular/core';
+import {Injector, Signal, WritableSignal} from '@angular/core';
 import {AbstractControl} from '@angular/forms';
 import type {FormField} from '../directive/form_field_directive';
 import type {MetadataKey, ValidationError} from './rules';
@@ -451,7 +451,7 @@ export interface ReadonlyFieldState<TValue, TKey extends string | number = strin
   /**
    * The {@link FormField} directives that bind this field to a UI control.
    */
-  readonly formFieldBindings: Signal<readonly FormField<unknown>[]>;
+  readonly formFieldBindings: Signal<readonly FormFieldBinding[]>;
 
   /**
    * Reads a metadata value from the field.
@@ -573,6 +573,36 @@ export type FieldStateByMode<
   TMode extends 'writable' | 'readonly',
 > = TMode extends 'writable' ? FieldState<TValue, TKey> : ReadonlyFieldState<TValue, TKey>;
 
+/**
+ * Represents a binding between a field and a UI control through a {@link FormField} directive.
+ *
+ * @experimental 21.3.0
+ */
+export interface FormFieldBinding {
+  /**
+   * The HTML element on which the {@link FormField} directive is applied.
+   */
+  readonly element: HTMLElement;
+
+  /**
+   * The node injector for the element hosting this field binding.
+   */
+  readonly injector: Injector;
+
+  /**
+   * The {@link FieldState} of the field bound to the {@link FormField} directive.
+   */
+  readonly state: Signal<ReadonlyFieldState<unknown>>;
+
+  /**
+   * Focuses this field binding.
+   *
+   * By default, this will focus {@link element}. However, custom controls can implement their own
+   * focus behavior.
+   */
+  focus(options?: FocusOptions): void;
+}
+
 /**
  * Allows declaring whether the Rules are supported for a given path.
  *
diff --git a/packages/forms/signals/src/directive/form_field_directive.ts b/packages/forms/signals/src/directive/form_field_directive.ts
@@ -115,7 +115,7 @@ export class FormField<T> {
   readonly destroyRef = inject(DestroyRef);
 
   /**
-   * The node injector for the element this field binding.
+   * The node injector for the DOM element hosting this field binding.
    */
   readonly injector = inject(Injector);
 
@@ -196,8 +196,7 @@ export class FormField<T> {
    */
   private installClassBindingEffect(): void {
     const classes = Object.entries(this.config?.classes ?? {}).map(
-      ([className, computation]) =>
-        [className, computed(() => computation(this as FormField<unknown>))] as const,
+      ([className, computation]) => [className, computed(() => computation(this))] as const,
     );
     if (classes.length === 0) {
       return;
