feat(forms): add DI option for classes on Field directive

mmalerba · kirjs · commit 7d5c7cf99aa5 · 2025-11-25T10:33:41.000-05:00
Adds a DI configuration option for signal forms that allows the developer to specify CSS classes that should be automatically added by the `Field` directive based on the field's status. (cherry picked from commit c70e246)
diff --git a/goldens/public-api/forms/signals/compat/index.api.md b/goldens/public-api/forms/signals/compat/index.api.md
@@ -52,6 +52,9 @@ export class CompatValidationError<T = unknown> implements ValidationError {
     readonly message?: string;
 }
 
+// @public
+export const NG_STATUS_CLASSES: SignalFormsConfig['classes'];
+
 // (No @packageDocumentation comment for this package)
 
 ```
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -18,6 +18,7 @@ import { InputSignal } from '@angular/core';
 import { ModelSignal } from '@angular/core';
 import { NgControl } from '@angular/forms';
 import { OutputRef } from '@angular/core';
+import { Provider } from '@angular/core';
 import { ResourceRef } from '@angular/core';
 import { Signal } from '@angular/core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -145,6 +146,8 @@ export class Field<T> implements ɵControl<T> {
     // (undocumented)
     readonly [ɵCONTROL]: undefined;
     // (undocumented)
+    readonly classes: (readonly [string, i0.Signal<boolean>])[];
+    // (undocumented)
     readonly field: i0.InputSignal<FieldTree<T>>;
     protected getOrCreateNgControl(): InteropNgControl;
     // (undocumented)
@@ -427,6 +430,9 @@ export class PatternValidationError extends _NgValidationError {
     readonly pattern: RegExp;
 }
 
+// @public
+export function provideSignalFormsConfig(config: SignalFormsConfig): Provider[];
+
 // @public
 export function readonly<TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, logic?: NoInfer<LogicFn<TValue, boolean, TPathKind>>): void;
 
@@ -509,6 +515,13 @@ export type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> =
     [K in keyof TModel]: MaybeSchemaPathTree<TModel[K], PathKind.Child>;
 } : unknown);
 
+// @public
+export interface SignalFormsConfig {
+    classes?: {
+        [className: string]: (state: FieldState<unknown>) => boolean;
+    };
+}
+
 // @public
 export function standardSchemaError(issue: StandardSchemaV1.Issue, options: WithField<ValidationErrorOptions>): StandardSchemaValidationError;
 
diff --git a/packages/core/src/render3/instructions/control.ts b/packages/core/src/render3/instructions/control.ts
@@ -95,6 +95,8 @@ export function ɵɵcontrol<T>(value: T, sanitizer?: SanitizerFn | null): void {
 
   const control = getControlDirective(tNode, lView);
   if (control) {
+    updateControlClasses(lView, tNode, control);
+
     if (tNode.flags & TNodeFlags.isFormValueControl) {
       updateCustomControl(tNode, lView, control, 'value');
     } else if (tNode.flags & TNodeFlags.isFormCheckboxControl) {
@@ -449,6 +451,34 @@ function isRelevantSelectMutation(mutation: MutationRecord) {
   return false;
 }
 
+/**
+ * Updates the configured classes for the control.
+ *
+ * @param lView The `LView` that contains the control.
+ * @param tNode The `TNode` of the control.
+ * @param control The `ɵControl` directive instance.
+ */
+function updateControlClasses(lView: LView, tNode: TNode, control: ɵControl<unknown>) {
+  if (control.classes) {
+    const bindings = getControlBindings(lView);
+    bindings.classes ??= {};
+    const state = control.state();
+    const renderer = lView[RENDERER];
+    const element = getNativeByTNode(tNode, lView) as HTMLElement;
+
+    for (const [className, enabled] of control.classes) {
+      const isEnabled = enabled();
+      if (controlClassBindingUpdated(bindings.classes, className, isEnabled)) {
+        if (isEnabled) {
+          renderer.addClass(element, className);
+        } else {
+          renderer.removeClass(element, className);
+        }
+      }
+    }
+  }
+}
+
 /**
  * Updates the inputs of a custom form control component with the latest state from the `field`.
  *
@@ -839,6 +869,8 @@ type ControlBindingKeys = Exclude<
  */
 type ControlBindings = {
   [K in ControlBindingKeys]?: unknown;
+} & {
+  classes: {[className: string]: boolean};
 };
 
 /**
@@ -893,7 +925,7 @@ function getControlBindings(lView: LView): ControlBindings {
  */
 function controlBindingUpdated(
   bindings: ControlBindings,
-  key: ControlBindingKeys,
+  key: Exclude<ControlBindingKeys, 'classes'>,
   value: unknown,
 ): boolean {
   const oldValue = bindings[key];
@@ -904,6 +936,27 @@ function controlBindingUpdated(
   return true;
 }
 
+/**
+ * Updates a control class binding if changed, then returns whether it was updated.
+ *
+ * @param bindings The control class bindings to check.
+ * @param className The class name to check.
+ * @param value The new value to check against.
+ * @returns `true` if the class binding has changed.
+ */
+function controlClassBindingUpdated(
+  bindings: {[className: string]: boolean},
+  className: string,
+  value: boolean,
+): boolean {
+  const oldValue = bindings[className];
+  if (Object.is(oldValue, value)) {
+    return false;
+  }
+  bindings[className] = value;
+  return true;
+}
+
 /**
  * Sets a boolean attribute on an element.
  *
diff --git a/packages/core/src/render3/interfaces/control.ts b/packages/core/src/render3/interfaces/control.ts
@@ -21,6 +21,9 @@ export interface ɵControl<T> {
   /** The state of the field bound to this control. */
   readonly state: Signal<ɵFieldState<T>>;
 
+  /** Options for the control. */
+  readonly classes: ReadonlyArray<readonly [string, Signal<boolean>]>;
+
   /** A reference to the interoperable control, if one is present. */
   readonly ɵinteropControl: ɵInteropControl | undefined;
 
diff --git a/packages/forms/signals/compat/public_api.ts b/packages/forms/signals/compat/public_api.ts
@@ -13,3 +13,4 @@
  */
 export * from './src/api/compat_form';
 export * from './src/api/compat_validation_error';
+export * from './src/api/di';
diff --git a/packages/forms/signals/compat/src/api/di.ts b/packages/forms/signals/compat/src/api/di.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import type {SignalFormsConfig} from '../../../src/api/di';
+
+/**
+ * A value that can be used for `SignalFormsConfig.classes` to automatically add
+ * the `ng-*` status classes from reactive forms.
+ *
+ * @experimental 21.0.1
+ */
+export const NG_STATUS_CLASSES: SignalFormsConfig['classes'] = {
+  'ng-touched': (state) => state.touched(),
+  'ng-untouched': (state) => !state.touched(),
+  'ng-dirty': (state) => state.dirty(),
+  'ng-pristine': (state) => !state.dirty(),
+  'ng-valid': (state) => state.valid(),
+  'ng-invalid': (state) => state.invalid(),
+  'ng-pending': (state) => state.pending(),
+};
diff --git a/packages/forms/signals/public_api.ts b/packages/forms/signals/public_api.ts
@@ -14,6 +14,7 @@
 export * from './src/api/async';
 export * from './src/api/control';
 export * from './src/api/debounce';
+export * from './src/api/di';
 export * from './src/api/field_directive';
 export * from './src/api/logic';
 export * from './src/api/metadata';
diff --git a/packages/forms/signals/src/api/di.ts b/packages/forms/signals/src/api/di.ts
@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {type Provider} from '@angular/core';
+import {SIGNAL_FORMS_CONFIG} from '../field/di';
+import type {FieldState} from './types';
+
+/**
+ * Configuration options for signal forms.
+ *
+ * @experimental 21.0.1
+ */
+export interface SignalFormsConfig {
+  /** A map of CSS class names to predicate functions that determine when to apply them. */
+  classes?: {[className: string]: (state: FieldState<unknown>) => boolean};
+}
+
+/**
+ * Provides configuration options for signal forms.
+ *
+ * @experimental 21.0.1
+ */
+export function provideSignalFormsConfig(config: SignalFormsConfig): Provider[] {
+  return [{provide: SIGNAL_FORMS_CONFIG, useValue: config}];
+}
diff --git a/packages/forms/signals/src/api/field_directive.ts b/packages/forms/signals/src/api/field_directive.ts
@@ -20,6 +20,7 @@ import {
 } from '@angular/core';
 import {NG_VALUE_ACCESSOR, NgControl} from '@angular/forms';
 import {InteropNgControl} from '../controls/interop_ng_control';
+import {SIGNAL_FORMS_CONFIG} from '../field/di';
 import type {FieldNode} from '../field/node';
 import type {FieldTree} from './types';
 
@@ -61,6 +62,10 @@ export const FIELD = new InjectionToken<Field<unknown>>(
 })
 export class Field<T> implements ɵControl<T> {
   private readonly injector = inject(Injector);
+  private config = inject(SIGNAL_FORMS_CONFIG, {optional: true});
+  readonly classes = Object.entries(this.config?.classes ?? {}).map(
+    ([className, computation]) => [className, computed(() => computation(this.state()))] as const,
+  );
   readonly field = input.required<FieldTree<T>>();
   readonly state = computed(() => this.field()());
   readonly [ɵCONTROL] = undefined;
diff --git a/packages/forms/signals/src/field/di.ts b/packages/forms/signals/src/field/di.ts
@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {InjectionToken} from '@angular/core';
+import type {SignalFormsConfig} from '../api/di';
+
+/** Injection token for the signal forms configuration. */
+export const SIGNAL_FORMS_CONFIG = new InjectionToken<SignalFormsConfig>(
+  typeof ngDevMode !== 'undefined' && ngDevMode ? 'SIGNAL_FORMS_CONFIG' : '',
+);
diff --git a/packages/forms/signals/test/web/BUILD.bazel b/packages/forms/signals/test/web/BUILD.bazel
@@ -10,6 +10,7 @@ ng_project(
         "//packages/core/testing",
         "//packages/forms",
         "//packages/forms/signals",
+        "//packages/forms/signals/compat",
         "//packages/platform-browser",
         "//packages/platform-browser/testing",
         "//packages/private/testing",
diff --git a/packages/forms/signals/test/web/field_directive.spec.ts b/packages/forms/signals/test/web/field_directive.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,9 @@ export class CompatValidationError<T = unknown> implements ValidationError {`
`52`	`52`	`readonly message?: string;`
`53`	`53`	`}`
`54`	`54`
	`55`	`+// @public`
	`56`	`+export const NG_STATUS_CLASSES: SignalFormsConfig['classes'];`
	`57`	`+`
`55`	`58`	`// (No @packageDocumentation comment for this package)`
`56`	`59`
`57`	`60`	```