@angular/forms 22.0.0-next.0 → 22.0.0-next.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/forms",
-  "version": "22.0.0-next.0",
+  "version": "22.0.0-next.2",
   "description": "Angular - directives and services for creating forms",
   "author": "angular",
   "license": "MIT",
@@ -12,9 +12,9 @@
     "@standard-schema/spec": "^1.0.0"
   },
   "peerDependencies": {
-    "@angular/core": "22.0.0-next.0",
-    "@angular/common": "22.0.0-next.0",
-    "@angular/platform-browser": "22.0.0-next.0",
+    "@angular/core": "22.0.0-next.2",
+    "@angular/common": "22.0.0-next.2",
+    "@angular/platform-browser": "22.0.0-next.2",
     "rxjs": "^6.5.3 || ^7.4.0"
   },
   "repository": {

package/types/_structure-chunk.d.ts

@@ -1,11 +1,11 @@
 /**
- * @license Angular v22.0.0-next.0
+ * @license Angular v22.0.0-next.2
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
 import * as i0 from '@angular/core';
-import { WritableSignal, Signal, InjectionToken, Injector, Provider } from '@angular/core';
+import { Signal, WritableSignal, Injector, InjectionToken, Provider } from '@angular/core';
 import { AbstractControl, ValidationErrors, FormControlStatus, ControlValueAccessor, ValidatorFn } from '@angular/forms';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
@@ -16,7 +16,7 @@ declare const ɵɵTYPE: unique symbol;
 /**
  * Options that can be specified when submitting a form.
  *
- * @experimental 21.2.0
+ * @experimental 21.2
  */
 interface FormSubmitOptions<TRootModel, TSubmittedModel> {
     /**
@@ -57,13 +57,13 @@ interface FormSubmitOptions<TRootModel, TSubmittedModel> {
  * A type that represents either a single value of type `T` or a readonly array of `T`.
  * @template T The type of the value(s).
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type OneOrMany<T> = T | readonly T[];
 /**
  * The kind of `FieldPath` (`Root`, `Child` of another `FieldPath`, or `Item` in a `FieldPath` array)
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type PathKind = PathKind.Root | PathKind.Child | PathKind.Item;
 declare namespace PathKind {
@@ -95,11 +95,11 @@ declare namespace PathKind {
  * A reason for a field's disablement.
  *
  * @category logic
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 interface DisabledReason {
     /** The field that is disabled. */
-    readonly fieldTree: FieldTree<unknown>;
+    readonly fieldTree: ReadonlyFieldTree<unknown>;
     /** A user-facing message describing the reason for the disablement. */
     readonly message?: string;
 }
@@ -107,7 +107,7 @@ interface DisabledReason {
  * The absence of an error which indicates a successful validation result.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type ValidationSuccess = null | undefined | void;
 /**
@@ -122,7 +122,7 @@ type ValidationSuccess = null | undefined | void;
  * @template E the type of error (defaults to {@link ValidationError}).
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type TreeValidationResult<E extends ValidationError.WithOptionalFieldTree = ValidationError.WithOptionalFieldTree> = ValidationSuccess | OneOrMany<E>;
 /**
@@ -136,7 +136,7 @@ type TreeValidationResult<E extends ValidationError.WithOptionalFieldTree = Vali
  * @template E the type of error (defaults to {@link ValidationError}).
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type ValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<E>;
 /**
@@ -149,7 +149,7 @@ type ValidationResult<E extends ValidationError = ValidationError> = ValidationS
  * @template E the type of error (defaults to {@link ValidationError}).
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type AsyncValidationResult<E extends ValidationError = ValidationError> = ValidationResult<E> | 'pending';
 /**
@@ -159,68 +159,81 @@ type AsyncValidationResult<E extends ValidationError = ValidationError> = Valida
  * @template TKey The type of the property key which this field resides under in its parent.
  *
  * @category types
- * @experimental 21.2.0
+ * @experimental 21.2
  */
 type Field<TValue, TKey extends string | number = string | number> = () => FieldState<TValue, TKey>;
 /**
  * An object that represents a tree of fields in a form. This includes both primitive value fields
  * (e.g. fields that contain a `string` or `number`), as well as "grouping fields" that contain
- * sub-fields. `FieldTree` objects are arranged in a tree whose structure mimics the structure of the
- * underlying data. For example a `FieldTree<{x: number}>` has a property `x` which contains a
+ * sub-fields. `FieldTree` objects are arranged in a tree whose structure mimics the structure of
+ * the underlying data. For example a `FieldTree<{x: number}>` has a property `x` which contains a
  * `FieldTree<number>`. To access the state associated with a field, call it as a function.
  *
  * @template TValue The type of the data which the field is wrapped around.
  * @template TKey The type of the property key which this field resides under in its parent.
+ * @template TMode Determines whether the field state is readonly or writable. Defaults to writable.
+ *   For readonly, use {@link ReadonlyFieldTree}.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
+ */
+type FieldTree<TModel, TKey extends string | number = string | number, TMode extends 'writable' | 'readonly' = 'writable'> = (() => [TModel] extends [AbstractControl] ? CompatFieldState<TModel, TKey, TMode> : FieldStateByMode<TModel, TKey, TMode>) & ([TModel] extends [AbstractControl] ? object : [TModel] extends [ReadonlyArray<infer U>] ? ReadonlyArrayLike<MaybeFieldTree<U, number, TMode>> : TModel extends Record<string, any> ? Subfields<TModel, TMode> : object);
+/**
+ * A readonly {@link FieldTree}.
+ *
+ * @category types
+ * @experimental 22.0
  */
-type FieldTree<TModel, TKey extends string | number = string | number> = (() => [TModel] extends [AbstractControl] ? CompatFieldState<TModel, TKey> : FieldState<TModel, TKey>) & ([TModel] extends [AbstractControl] ? object : [TModel] extends [ReadonlyArray<infer U>] ? ReadonlyArrayLike<MaybeFieldTree<U, number>> : TModel extends Record<string, any> ? Subfields<TModel> : object);
+type ReadonlyFieldTree<TModel, TKey extends string | number = string | number> = FieldTree<TModel, TKey, 'readonly'>;
 /**
  * The sub-fields that a user can navigate to from a `FieldTree<TModel>`.
  *
  * @template TModel The type of the data which the parent field is wrapped around.
+ * @template TMode Determines whether the field state is readonly or writable.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
-type Subfields<TModel> = {
-    readonly [K in keyof TModel as TModel[K] extends Function ? never : K]: MaybeFieldTree<TModel[K], string>;
+type Subfields<TModel, TMode extends 'writable' | 'readonly' = 'writable'> = {
+    readonly [K in keyof TModel as TModel[K] extends Function ? never : K]: MaybeFieldTree<TModel[K], string, TMode>;
 } & {
-    [Symbol.iterator](): Iterator<[string, MaybeFieldTree<TModel[keyof TModel], string>]>;
+    [Symbol.iterator](): Iterator<[string, MaybeFieldTree<TModel[keyof TModel], string, TMode>]>;
 };
 /**
  * An iterable object with the same shape as a readonly array.
  *
  * @template T The array item type.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type ReadonlyArrayLike<T> = Pick<ReadonlyArray<T>, number | 'length' | typeof Symbol.iterator>;
 /**
- * Helper type for defining `FieldTree`. Given a type `TValue` that may include `undefined`, it extracts
- * the `undefined` outside the `FieldTree` type.
+ * Helper type for defining `FieldTree`. Given a type `TValue` that may include `undefined`,
+ * it extracts the `undefined` outside the `FieldTree` type.
  *
- * For example `MaybeField<{a: number} | undefined, TKey>` would be equivalent to
+ * For example `MaybeFieldTree<{a: number} | undefined, TKey>` would be equivalent to
  * `undefined | FieldTree<{a: number}, TKey>`.
  *
  * @template TModel The type of the data which the field is wrapped around.
  * @template TKey The type of the property key which this field resides under in its parent.
+ * @template TMode Determines whether the field state is readonly or writable.
  *
- * @experimental 21.0.0
+ * @experimental 22.0
  */
-type MaybeFieldTree<TModel, TKey extends string | number = string | number> = (TModel & undefined) | FieldTree<Exclude<TModel, undefined>, TKey>;
+type MaybeFieldTree<TModel, TKey extends string | number = string | number, TMode extends 'writable' | 'readonly' = 'writable'> = (TModel & undefined) | FieldTree<Exclude<TModel, undefined>, TKey, TMode>;
 /**
- * Contains all of the state (e.g. value, statuses, etc.) associated with a `FieldTree`, exposed as
- * signals.
+ * A readonly view of a {@link FieldTree}'s state.
+ *
+ * @template TValue The type of the data which the field is wrapped around.
+ * @template TKey The type of the property key which this field resides under in its parent.
  *
  * @category structure
- * @experimental 21.0.0
+ * @experimental 22.0
  */
-interface FieldState<TValue, TKey extends string | number = string | number> {
+interface ReadonlyFieldState<TValue, TKey extends string | number = string | number> {
     /**
      * The {@link FieldTree} associated with this field state.
      */
-    readonly fieldTree: FieldTree<unknown, TKey>;
+    readonly fieldTree: ReadonlyFieldTree<unknown, TKey>;
     /**
      * A writable signal containing the value for this field.
      *
@@ -229,7 +242,15 @@ interface FieldState<TValue, TKey extends string | number = string | number> {
      * While updates from the UI control are eventually reflected here, they may be delayed if
      * debounced.
      */
-    readonly value: WritableSignal<TValue>;
+    readonly value: Signal<TValue>;
+    /**
+     * A signal containing the value of the control to which this field is bound.
+     *
+     * This differs from {@link value} in that it's not subject to debouncing, and thus is used to
+     * buffer debounced updates from the control to the field. This will also not take into account
+     * the {@link controlValue} of children.
+     */
+    readonly controlValue: Signal<TValue>;
     /**
      * A signal indicating whether the field is currently disabled.
      */
@@ -341,7 +362,47 @@ interface FieldState<TValue, TKey extends string | number = string | number> {
     /**
      * 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.
+     * @param key The metadata key to read.
+     */
+    metadata<M>(key: MetadataKey<M, any, any>): M | undefined;
+    /**
+     * Checks whether a metadata value exists on the field.
+     * @param key The metadata key to check.
+     */
+    hasMetadata(key: MetadataKey<any, any, any>): boolean;
+    /**
+     * Focuses the first UI control in the DOM that is bound to this field state.
+     * If no UI control is bound, does nothing.
+     * @param options Optional focus options to pass to the native focus() method.
+     */
+    focusBoundControl(options?: FocusOptions): void;
+}
+/**
+ * A writable view of a {@link FieldTree}'s state.
+ *
+ * @template TValue The type of the data which the field is wrapped around.
+ * @template TKey The type of the property key which this field resides under in its parent.
+ *
+ * @category structure
+ * @experimental 21.0
+ */
+interface FieldState<TValue, TKey extends string | number = string | number> extends ReadonlyFieldState<TValue, TKey> {
+    /**
+     * The {@link FieldTree} associated with this field state.
+     */
+    readonly fieldTree: FieldTree<unknown, TKey>;
+    /**
+     * A writable signal containing the value for this field.
+     *
+     * Updating this signal will update the data model that the field is bound to.
+     *
+     * While updates from the UI control are eventually reflected here, they may be delayed if
+     * debounced.
+     */
+    readonly value: WritableSignal<TValue>;
     /**
      * A signal containing the value of the control to which this field is bound.
      *
@@ -358,11 +419,6 @@ interface FieldState<TValue, TKey extends string | number = string | number> {
      * Sets the touched status of the field to `true`.
      */
     markAsTouched(): void;
-    /**
-     * Reads a metadata value from the field.
-     * @param key The metadata key to read.
-     */
-    metadata<M>(key: MetadataKey<M, any, any>): M | undefined;
     /**
      * Resets the {@link touched} and {@link dirty} state of the field and its descendants.
      *
@@ -371,26 +427,62 @@ interface FieldState<TValue, TKey extends string | number = string | number> {
      * @param value Optional value to set to the form. If not passed, the value will not be changed.
      */
     reset(value?: TValue): void;
-    /**
-     * Focuses the first UI control in the DOM that is bound to this field state.
-     * If no UI control is bound, does nothing.
-     * @param options Optional focus options to pass to the native focus() method.
-     */
-    focusBoundControl(options?: FocusOptions): void;
 }
 /**
  * This is FieldState also providing access to the wrapped FormControl.
  *
  * @category interop
- * @experimental 21.0.0
+ * @experimental 21.0
  */
-type CompatFieldState<TControl extends AbstractControl, TKey extends string | number = string | number> = FieldState<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, TKey> & {
+type CompatFieldState<TControl extends AbstractControl, TKey extends string | number = string | number, TMode extends 'writable' | 'readonly' = 'writable'> = FieldStateByMode<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, TKey, TMode> & {
     control: Signal<TControl>;
 };
+/**
+ * A readonly {@link CompatFieldState}.
+ *
+ * @category interop
+ * @experimental 22.0
+ */
+type ReadonlyCompatFieldState<TControl extends AbstractControl, TKey extends string | number = string | number> = CompatFieldState<TControl, TKey, 'readonly'>;
+/**
+ * Helper type that resolves to either a {@link FieldState} or {@link ReadonlyFieldState} based on
+ * the access mode.
+ *
+ * @template TValue The type of the value stored in the field.
+ * @template TKey The type of the property key.
+ * @template TMode The access mode ('readonly' or 'writable').
+ */
+type FieldStateByMode<TValue, TKey extends string | number, 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 22.0
+ */
+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.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  **/
 type SchemaPathRules = SchemaPathRules.Supported | SchemaPathRules.Unsupported;
 declare namespace SchemaPathRules {
@@ -412,7 +504,7 @@ declare namespace SchemaPathRules {
  * @template TPathKind The kind of path (root field, child field, or item of an array)
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type SchemaPath<TValue, TSupportsRules extends SchemaPathRules = SchemaPathRules.Supported, TPathKind extends PathKind = PathKind.Root> = {
     [ɵɵTYPE]: {
@@ -425,7 +517,7 @@ type SchemaPath<TValue, TSupportsRules extends SchemaPathRules = SchemaPathRules
  * Schema path used if the value is an AbstractControl.
  *
  * @category interop
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type CompatSchemaPath<TControl extends AbstractControl, TPathKind extends PathKind = PathKind.Root> = SchemaPath<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, SchemaPathRules.Unsupported, TPathKind> & {
     [ɵɵTYPE]: {
@@ -438,7 +530,7 @@ type CompatSchemaPath<TControl extends AbstractControl, TPathKind extends PathKi
  * It mirrors the structure of a given data structure, and allows applying rules to the appropriate
  * fields.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = ([TModel] extends [AbstractControl] ? CompatSchemaPath<TModel, TPathKind> : SchemaPath<TModel, SchemaPathRules.Supported, TPathKind>) & (TModel extends AbstractControl ? unknown : TModel extends ReadonlyArray<any> ? unknown : TModel extends Record<string, any> ? {
     [K in keyof TModel]: MaybeSchemaPathTree<TModel[K], PathKind.Child>;
@@ -453,7 +545,7 @@ type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = ([TMod
  * @template TValue The type of the data which the field is wrapped around.
  * @template TPathKind The kind of path (root field, child field, or item of an array)
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type MaybeSchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = (TModel & undefined) | SchemaPathTree<Exclude<TModel, undefined>, TPathKind>;
 /**
@@ -495,7 +587,7 @@ type MaybeSchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = (
  * @template TModel Data type.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type Schema<in TModel> = {
     [ɵɵTYPE]: SchemaFn<TModel, PathKind.Root>;
@@ -519,7 +611,7 @@ type Schema<in TModel> = {
  * @template TPathKind The kind of path this schema function can be bound to.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type SchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = (p: SchemaPathTree<TModel, TPathKind>) => void;
 /**
@@ -529,7 +621,7 @@ type SchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = (p: SchemaPa
  * @template TPathKind The kind of path this schema function can be bound to.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type SchemaOrSchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = Schema<TModel> | SchemaFn<TModel, TPathKind>;
 /**
@@ -541,7 +633,7 @@ type SchemaOrSchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = Sche
  * @template TPathKind The kind of path the logic is applied to (root field, child field, or item of an array)
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root> = (ctx: FieldContext<TValue, TPathKind>) => TReturn;
 /**
@@ -552,7 +644,7 @@ type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root> = (ctx
  * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
  *
  * @category validation
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult<ValidationError.WithoutFieldTree>, TPathKind>;
 /**
@@ -563,7 +655,7 @@ type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicF
  * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type TreeValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, TreeValidationResult, TPathKind>;
 /**
@@ -575,7 +667,7 @@ type TreeValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn
  * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
  * @see [Signal Form Validation](/guide/forms/signals/validation)
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type Validator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult, TPathKind>;
 /**
@@ -583,28 +675,28 @@ type Validator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TVa
  * up state of other fields based on a `FieldPath`.
  *
  * @category types
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type FieldContext<TValue, TPathKind extends PathKind = PathKind.Root> = TPathKind extends PathKind.Item ? ItemFieldContext<TValue> : TPathKind extends PathKind.Child ? ChildFieldContext<TValue> : RootFieldContext<TValue>;
 /**
  * The base field context that is available for all fields.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 interface RootFieldContext<TValue> {
     /** A signal containing the value of the current field. */
     readonly value: Signal<TValue>;
     /** The state of the current field. */
-    readonly state: FieldState<TValue>;
+    readonly state: ReadonlyFieldState<TValue>;
     /** The current field. */
-    readonly fieldTree: FieldTree<TValue>;
+    readonly fieldTree: ReadonlyFieldTree<TValue>;
     /** Gets the value of the field represented by the given path. */
     valueOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): PValue;
     /** Gets the state of the field represented by the given path. */
-    stateOf<PControl extends AbstractControl>(p: CompatSchemaPath<PControl>): CompatFieldState<PControl>;
-    stateOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): FieldState<PValue>;
+    stateOf<PControl extends AbstractControl>(p: CompatSchemaPath<PControl>): ReadonlyCompatFieldState<PControl>;
+    stateOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): ReadonlyFieldState<PValue>;
     /** Gets the field represented by the given path. */
-    fieldTreeOf<PModel>(p: SchemaPathTree<PModel>): FieldTree<PModel>;
+    fieldTreeOf<PModel>(p: SchemaPathTree<PModel>): ReadonlyFieldTree<PModel>;
     /** The list of keys that lead from the root field to the current field. */
     readonly pathKeys: Signal<readonly string[]>;
 }
@@ -612,7 +704,7 @@ interface RootFieldContext<TValue> {
  * Field context that is available for all fields that are a child of another field.
  *
  * @category structure
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 interface ChildFieldContext<TValue> extends RootFieldContext<TValue> {
     /** The key of the current field in its parent field. */
@@ -621,7 +713,7 @@ interface ChildFieldContext<TValue> extends RootFieldContext<TValue> {
 /**
  * Field context that is available for all fields that are an item in an array field.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 interface ItemFieldContext<TValue> extends ChildFieldContext<TValue> {
     /** The index of the current field in its parent field. */
@@ -630,7 +722,7 @@ interface ItemFieldContext<TValue> extends ChildFieldContext<TValue> {
 /**
  * Gets the item type of an object that is possibly an array.
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type ItemType<T extends Object> = T extends ReadonlyArray<any> ? T[number] : T[keyof T];
 /**
@@ -642,7 +734,7 @@ type ItemType<T extends Object> = T extends ReadonlyArray<any> ? T[number] : T[k
  * @template TValue The type of value stored in the field.
  * @template TPathKind The kind of path the debouncer is applied to (root field, child field, or item of an array).
  *
- * @experimental 21.0.0
+ * @experimental 21.0
  */
 type Debouncer<TValue, TPathKind extends PathKind = PathKind.Root> = (context: FieldContext<TValue, TPathKind>, abortSignal: AbortSignal) => Promise<void> | void;
 
@@ -908,8 +1000,8 @@ interface CombinedControl {
  * equivalent in signal forms.
  */
 declare class InteropNgControl implements CombinedControl {
-    protected field: () => FieldState<unknown>;
-    constructor(field: () => FieldState<unknown>);
+    protected field: () => ReadonlyFieldState<unknown>;
+    constructor(field: () => ReadonlyFieldState<unknown>);
     readonly control: AbstractControl<any, any>;
     get value(): any;
     get valid(): boolean;
@@ -965,13 +1057,16 @@ declare const FORM_FIELD: InjectionToken<FormField<unknown>>;
  * @experimental 21.0.0
  */
 declare class FormField<T> {
+    /**
+     * The field to bind to the underlying form control.
+     */
     readonly field: i0.InputSignal<Field<T>>;
     /**
      * `FieldState` for the currently bound field.
      */
     readonly state: Signal<FieldState<T, string | number>>;
     /**
-     * The node injector for the element this field binding.
+     * The node injector for the DOM element hosting this field binding.
      */
     readonly injector: Injector;
     /**
@@ -1041,7 +1136,7 @@ interface ValidationErrorOptions {
  * @experimental 21.0.0
  */
 type WithFieldTree<T> = T & {
-    fieldTree: FieldTree<unknown>;
+    fieldTree: ReadonlyFieldTree<unknown>;
 };
 /** @deprecated Use `WithFieldTree` instead  */
 type WithField<T> = WithFieldTree<T>;
@@ -1052,7 +1147,7 @@ type WithField<T> = WithFieldTree<T>;
  * @experimental 21.0.0
  */
 type WithOptionalFieldTree<T> = Omit<T, 'fieldTree'> & {
-    fieldTree?: FieldTree<unknown>;
+    fieldTree?: ReadonlyFieldTree<unknown>;
 };
 /** @deprecated Use `WithOptionalFieldTree` instead  */
 type WithOptionalField<T> = WithOptionalFieldTree<T>;
@@ -1216,7 +1311,7 @@ declare namespace ValidationError {
      */
     interface WithFieldTree extends ValidationError {
         /** The field associated with this error. */
-        readonly fieldTree: FieldTree<unknown>;
+        readonly fieldTree: ReadonlyFieldTree<unknown>;
         readonly formField?: FormField<unknown>;
     }
     /** @deprecated Use `ValidationError.WithFieldTree` instead  */
@@ -1235,7 +1330,7 @@ declare namespace ValidationError {
      */
     interface WithOptionalFieldTree extends ValidationError {
         /** The field associated with this error. */
-        readonly fieldTree?: FieldTree<unknown>;
+        readonly fieldTree?: ReadonlyFieldTree<unknown>;
     }
     /** @deprecated Use `ValidationError.WithOptionalFieldTree` instead  */
     type WithOptionalField = WithOptionalFieldTree;
@@ -1264,7 +1359,7 @@ declare abstract class BaseNgValidationError implements ValidationError {
     /** Identifies the kind of error. */
     readonly kind: string;
     /** The field associated with this error. */
-    readonly fieldTree: FieldTree<unknown>;
+    readonly fieldTree: ReadonlyFieldTree<unknown>;
     /** Human readable error message. */
     readonly message?: string;
     constructor(options?: ValidationErrorOptions);
@@ -1387,7 +1482,7 @@ type NgValidationError = RequiredValidationError | MinValidationError | MaxValid
 interface SignalFormsConfig {
     /** A map of CSS class names to predicate functions that determine when to apply them. */
     classes?: {
-        [className: string]: (state: FormField<unknown>) => boolean;
+        [className: string]: (formField: FormFieldBinding) => boolean;
     };
 }
 /**
@@ -1667,4 +1762,4 @@ declare function submit<TModel>(form: FieldTree<TModel>, action: NoInfer<FormSub
 declare function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue>;
 
 export { BaseNgValidationError, EmailValidationError, FORM_FIELD, FormField, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MetadataReducer, MinLengthValidationError, MinValidationError, NativeInputParseError, NgValidationError, PATTERN, PathKind, PatternValidationError, REQUIRED, RequiredValidationError, SchemaPathRules, StandardSchemaValidationError, ValidationError, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit, validateStandardSchema, ɵNgFieldDirective };
-export type { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, Debouncer, DisabledReason, Field, FieldContext, FieldState, FieldTree, FieldValidator, FormFieldBindingOptions, FormOptions, FormSubmitOptions, IgnoreUnknownProperties, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, MetadataSetterType, OneOrMany, ReadonlyArrayLike, RemoveStringIndexUnknownKey, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, TreeValidationResult, TreeValidator, ValidationErrorOptions, ValidationResult, ValidationSuccess, Validator, WithField, WithFieldTree, WithOptionalField, WithOptionalFieldTree, WithoutField, WithoutFieldTree };
+export type { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, Debouncer, DisabledReason, Field, FieldContext, FieldState, FieldStateByMode, FieldTree, FieldValidator, FormFieldBinding, FormFieldBindingOptions, FormOptions, FormSubmitOptions, IgnoreUnknownProperties, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, MetadataSetterType, OneOrMany, ReadonlyArrayLike, ReadonlyCompatFieldState, ReadonlyFieldState, ReadonlyFieldTree, RemoveStringIndexUnknownKey, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, TreeValidationResult, TreeValidator, ValidationErrorOptions, ValidationResult, ValidationSuccess, Validator, WithField, WithFieldTree, WithOptionalField, WithOptionalFieldTree, WithoutField, WithoutFieldTree };

package/types/forms.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v22.0.0-next.0
+ * @license Angular v22.0.0-next.2
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */

package/types/signals-compat.d.ts

@@ -1,11 +1,11 @@
 /**
- * @license Angular v22.0.0-next.0
+ * @license Angular v22.0.0-next.2
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
 import { WritableSignal, EventEmitter } from '@angular/core';
-import { FormOptions, FieldTree, SchemaOrSchemaFn, ValidationError, SignalFormsConfig, SchemaFn } from './_structure-chunk.js';
+import { FormOptions, FieldTree, SchemaOrSchemaFn, ValidationError, ReadonlyFieldTree, SignalFormsConfig, SchemaFn } from './_structure-chunk.js';
 import { AbstractControl, FormControlStatus, FormControlState } from '@angular/forms';
 import '@standard-schema/spec';
 
@@ -121,7 +121,7 @@ declare function compatForm<TModel>(model: WritableSignal<TModel>, schema: Schem
 declare class CompatValidationError<T = unknown> implements ValidationError {
     readonly kind: string;
     readonly control: AbstractControl;
-    readonly fieldTree: FieldTree<unknown>;
+    readonly fieldTree: ReadonlyFieldTree<unknown>;
     readonly context: T;
     readonly message?: string;
     constructor({ context, kind, control }: {