@angular/forms 21.1.0-next.4 → 21.1.0-rc.0

package/types/_structure-chunk.d.ts

@@ -1,6 +1,6 @@
 /**
- * @license Angular v21.1.0-next.4
- * (c) 2010-2025 Google LLC. https://angular.dev/
+ * @license Angular v21.1.0-rc.0
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
@@ -88,6 +88,52 @@ declare class Field<T> {
     static ɵdir: i0.ɵɵDirectiveDeclaration<Field<any>, "[field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Lightweight DI token provided by the {@link FormField} directive.
+ *
+ * @category control
+ * @experimental 21.0.0
+ */
+declare const FORM_FIELD: InjectionToken<FormField<unknown>>;
+/**
+ * Binds a form `FieldTree` to a UI control that edits it. A UI control can be one of several things:
+ * 1. A native HTML input or textarea
+ * 2. A signal forms custom control that implements `FormValueControl` or `FormCheckboxControl`
+ * 3. A component that provides a `ControlValueAccessor`. This should only be used for backwards
+ *    compatibility with reactive forms. Prefer options (1) and (2).
+ *
+ * This directive has several responsibilities:
+ * 1. Two-way binds the field state's value with the UI control's value
+ * 2. Binds additional forms related state on the field state to the UI control (disabled, required, etc.)
+ * 3. Relays relevant events on the control to the field state (e.g. marks touched on blur)
+ * 4. Provides a fake `NgControl` that implements a subset of the features available on the
+ *    reactive forms `NgControl`. This is provided to improve interoperability with controls
+ *    designed to work with reactive forms. It should not be used by controls written for signal
+ *    forms.
+ *
+ * @category control
+ * @experimental 21.0.0
+ */
+declare class FormField<T> {
+    readonly element: HTMLElement;
+    readonly injector: Injector;
+    readonly formField: i0.InputSignal<FieldTree<T>>;
+    readonly state: i0.Signal<[T] extends [_angular_forms.AbstractControl<any, any, any>] ? CompatFieldState<T, string | number> : FieldState<T, string | number>>;
+    readonly [_CONTROL]: {
+        readonly create: typeof __controlCreate;
+        readonly update: typeof _controlUpdate;
+    };
+    private config;
+    /** Any `ControlValueAccessor` instances provided on the host element. */
+    private readonly controlValueAccessors;
+    /** A lazily instantiated fake `NgControl`. */
+    private interopNgControl;
+    /** Lazily instantiates a fake `NgControl` for this form field. */
+    protected getOrCreateNgControl(): InteropNgControl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormField<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FormField<any>, "[formField]", never, { "formField": { "alias": "formField"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
  * Sets a value for the {@link MetadataKey} for this field.
  *
@@ -377,7 +423,7 @@ type AsyncValidationResult<E extends ValidationError = ValidationError> = Valida
  * @category types
  * @experimental 21.0.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 [Array<infer U>] ? ReadonlyArrayLike<MaybeFieldTree<U, number>> : TModel extends Record<string, any> ? Subfields<TModel> : object);
+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);
 /**
  * The sub-fields that a user can navigate to from a `FieldTree<TModel>`.
  *
@@ -482,7 +528,7 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
     /**
      * The {@link Field} directives that bind this field to a UI control.
      */
-    readonly fieldBindings: Signal<readonly Field<unknown>[]>;
+    readonly formFieldBindings: Signal<readonly (Field<unknown> | FormField<unknown>)[]>;
     /**
      * Reads a metadata value from the field.
      * @param key The metadata key to read.
@@ -559,7 +605,7 @@ type CompatSchemaPath<TControl extends AbstractControl, TPathKind extends PathKi
  *
  * @experimental 21.0.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 Array<any> ? unknown : TModel extends Record<string, any> ? {
+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>;
 } : unknown);
 /**
@@ -692,7 +738,7 @@ type TreeValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn
  *
  * @template TValue The type of value stored in the field being validated
  * @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
  */
@@ -938,22 +984,6 @@ declare function standardSchemaError(issue: StandardSchemaV1.Issue, options: Wit
  * @experimental 21.0.0
  */
 declare function standardSchemaError(issue: StandardSchemaV1.Issue, options?: ValidationErrorOptions): WithoutField<StandardSchemaValidationError>;
-/**
- * Create a custom error associated with the target field
- * @param obj The object to create an error from
- *
- * @category validation
- * @experimental 21.0.0
- */
-declare function customError<E extends Partial<ValidationError.WithField>>(obj: WithField<E>): CustomValidationError;
-/**
- * Create a custom error
- * @param obj The object to create an error from
- *
- * @category validation
- * @experimental 21.0.0
- */
-declare function customError<E extends Partial<ValidationError.WithField>>(obj?: E): WithoutField<CustomValidationError>;
 /**
  * Common interface for all validation errors.
  *
@@ -962,6 +992,8 @@ declare function customError<E extends Partial<ValidationError.WithField>>(obj?:
  * It's also used by the creation functions to create an instance
  * (e.g. `requiredError`, `minError`, etc.).
  *
+ * @see [Signal Form Validation](guide/forms/signals/validation)
+ * @see [Signal Form Validation Errors](guide/forms/signals/validation#validation-errors)
  * @category validation
  * @experimental 21.0.0
  */
@@ -999,30 +1031,9 @@ declare namespace ValidationError {
      */
     interface WithoutField extends ValidationError {
         /** The field associated with this error. */
-        readonly field?: never;
+        readonly fieldTree?: never;
     }
 }
-/**
- * A custom error that may contain additional properties
- *
- * @category validation
- * @experimental 21.0.0
- */
-declare class CustomValidationError implements ValidationError {
-    /** Brand the class to avoid Typescript structural matching */
-    private __brand;
-    /**
-     * Allow the user to attach arbitrary other properties.
-     */
-    [key: PropertyKey]: unknown;
-    /** Identifies the kind of error. */
-    readonly kind: string;
-    /** The field associated with this error. */
-    readonly fieldTree: FieldTree<unknown>;
-    /** Human readable error message. */
-    readonly message?: string;
-    constructor(options?: ValidationErrorOptions);
-}
 /**
  * Internal version of `NgValidationError`, we create this separately so we can change its type on
  * the exported version to a type union of the possible sub-classes.
@@ -1160,7 +1171,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: Field<unknown>) => boolean;
+        [className: string]: (state: Field<unknown> | FormField<unknown>) => boolean;
     };
 }
 /**
@@ -1192,7 +1203,7 @@ interface Predicate {
  *
  * Consider the following example:
  *
- * ```
+ * ```ts
  * const s = schema(p => {
  *   disabled(p.data);
  *   applyWhen(p.next, ({valueOf}) => valueOf(p.data) === 1, s);
@@ -1560,8 +1571,8 @@ declare class FieldNodeState {
      * Marks this specific field as not touched.
      */
     markAsUntouched(): void;
-    /** The {@link Field} directives that bind this field to a UI control. */
-    readonly fieldBindings: i0.WritableSignal<readonly Field<unknown>[]>;
+    /** The {@link FormField} directives that bind this field to a UI control. */
+    readonly formFieldBindings: i0.WritableSignal<readonly (Field<unknown> | FormField<unknown>)[]>;
     constructor(node: FieldNode);
     /**
      * Whether this field is considered dirty.
@@ -1635,8 +1646,8 @@ declare class FieldSubmitState {
      * and is still in the process of submitting.
      */
     readonly selfSubmitting: WritableSignal<boolean>;
-    /** Server errors that are associated with this field. */
-    readonly serverErrors: WritableSignal<readonly ValidationError.WithField[]>;
+    /** Submission errors that are associated with this field. */
+    readonly submissionErrors: WritableSignal<readonly ValidationError.WithField[]>;
     constructor(node: FieldNode);
     /**
      * Whether this form is currently in the process of being submitted.
@@ -1652,8 +1663,8 @@ interface ValidationState {
      */
     rawSyncTreeErrors: Signal<ValidationError.WithField[]>;
     /**
-     * The full set of synchronous errors for this field, including synchronous tree errors and server
-     * errors. Server errors are considered "synchronous" because they are imperatively added. From
+     * The full set of synchronous errors for this field, including synchronous tree errors and submission
+     * errors. Submission errors are considered "synchronous" because they are imperatively added. From
      * the perspective of the field state they are either there or not, they are never in a pending
      * state.
      */
@@ -1786,7 +1797,7 @@ declare class FieldNode implements FieldState<unknown> {
     get disabledReasons(): Signal<readonly DisabledReason[]>;
     get hidden(): Signal<boolean>;
     get readonly(): Signal<boolean>;
-    get fieldBindings(): Signal<readonly Field<unknown>[]>;
+    get formFieldBindings(): Signal<readonly (Field<unknown> | FormField<unknown>)[]>;
     get submitting(): Signal<boolean>;
     get name(): Signal<string>;
     get max(): Signal<number | undefined> | undefined;
@@ -2239,7 +2250,7 @@ declare function form<TModel>(model: WritableSignal<TModel>, schemaOrOptions: Sc
  * ```ts
  * const nameForm = form(signal({first: '', last: ''}), (name) => {
  *   required(name.first);
- *   validate(name.last, ({value}) => !/^[a-z]+$/i.test(value()) ? customError({kind: 'alphabet-only'}) : undefined);
+ *   validate(name.last, ({value}) => !/^[a-z]+$/i.test(value()) ? {kind: 'alphabet-only'} : undefined);
  * });
  * nameForm().valid(); // false
  * nameForm().value.set({first: 'John', last: 'Doe'});
@@ -2344,10 +2355,10 @@ declare function applyWhenValue<TValue, TNarrowed extends TValue>(path: SchemaPa
  */
 declare function applyWhenValue<TValue>(path: SchemaPath<TValue>, predicate: (value: TValue) => boolean, schema: NoInfer<SchemaOrSchemaFn<TValue>>): void;
 /**
- * Submits a given `FieldTree` using the given action function and applies any server errors
- * resulting from the action to the field. Server errors returned by the `action` will be integrated
+ * Submits a given `FieldTree` using the given action function and applies any submission errors
+ * resulting from the action to the field. Submission errors returned by the `action` will be integrated
  * into the field as a `ValidationError` on the sub-field indicated by the `field` property of the
- * server error.
+ * submission error.
  *
  * @example
  * ```ts
@@ -2370,7 +2381,7 @@ declare function applyWhenValue<TValue>(path: SchemaPath<TValue>, predicate: (va
  * ```
  *
  * @param form The field to submit.
- * @param action An asynchronous action used to submit the field. The action may return server
+ * @param action An asynchronous action used to submit the field. The action may return submission
  * errors.
  * @template TModel The data type of the field being submitted.
  *
@@ -2389,5 +2400,5 @@ declare function submit<TModel>(form: FieldTree<TModel>, action: (form: FieldTre
  */
 declare function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue>;
 
-export { CustomValidationError, EmailValidationError, FIELD, Field, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MetadataReducer, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PathKind, PatternValidationError, REQUIRED, RequiredValidationError, SchemaPathRules, StandardSchemaValidationError, ValidationError, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, customError, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit };
+export { EmailValidationError, FIELD, FORM_FIELD, Field, FormField, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MetadataReducer, MinLengthValidationError, MinValidationError, 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 };
 export type { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, Debouncer, DisabledReason, FieldContext, FieldState, FieldTree, FieldValidator, FormOptions, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, MetadataSetterType, OneOrMany, ReadonlyArrayLike, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, SubmittedStatus, TreeValidationResult, TreeValidator, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };

package/types/forms.d.ts

@@ -1,6 +1,6 @@
 /**
- * @license Angular v21.1.0-next.4
- * (c) 2010-2025 Google LLC. https://angular.dev/
+ * @license Angular v21.1.0-rc.0
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
@@ -1073,7 +1073,7 @@ type ɵFormArrayRawValue<T extends AbstractControl<any>> = ɵTypedOrUntyped<T, A
  * the `FormArray` directly, as that result in strange and unexpected behavior such
  * as broken change detection.
  *
- * @see [FormArray: Dynamic, Homogenous Collections](guide/forms/typed-forms#formcontrol-getting-started)
+ * @see [FormArray: Dynamic, Homogenous Collections](guide/forms/typed-forms#formarray-dynamic-homogenous-collections)
  * @see [Creating dynamic forms](guide/forms/reactive-forms#creating-dynamic-forms)
  *
  * @publicApi
@@ -2769,9 +2769,7 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      *
      * @usageNotes
      *
-     * ### Reference to a ValidatorFn
-     *
-     * ```
+     * ```ts
      * // Reference to the RequiredValidator
      * const ctrl = new FormControl<string | null>('', Validators.required);
      * ctrl.removeValidators(Validators.required);
@@ -2809,9 +2807,7 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      *
      * @usageNotes
      *
-     * ### Reference to a ValidatorFn
-     *
-     * ```
+     * ```ts
      * // Reference to the RequiredValidator
      * const ctrl = new FormControl<number | null>(0, Validators.required);
      * expect(ctrl.hasValidator(Validators.required)).toEqual(true)
@@ -2867,6 +2863,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `TouchedChangeEvent` with the `touched` property being `true`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAsTouched(opts?: {
         onlySelf?: boolean;
@@ -2881,6 +2880,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `PristineChangeEvent` with the `pristine` property being `false`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAllAsDirty(opts?: {
         emitEvent?: boolean;
@@ -2894,6 +2896,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `TouchedChangeEvent` with the `touched` property being `true`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAllAsTouched(opts?: {
         emitEvent?: boolean;
@@ -2915,6 +2920,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `TouchedChangeEvent` with the `touched` property being `false`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAsUntouched(opts?: {
         onlySelf?: boolean;
@@ -2935,6 +2943,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `PristineChangeEvent` with the `pristine` property being `false`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAsDirty(opts?: {
         onlySelf?: boolean;
@@ -2958,6 +2969,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * * `emitEvent`: When true or not supplied (the default), the `events`
      * observable emits a `PristineChangeEvent` with the `pristine` property being `true`.
      * When false, no events are emitted.
+     *
+     * @see [Managing form control state](guide/forms/reactive-forms#managing-form-control-state)
+     *
      */
     markAsPristine(opts?: {
         onlySelf?: boolean;
@@ -3064,6 +3078,9 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * `valueChanges` and `events`
      * observables emit events with the latest status and value when the control is updated.
      * When false, no events are emitted.
+     *
+     * @see [Understanding propagation control](guide/forms/reactive-forms#understanding-event-emission)
+     *
      */
     updateValueAndValidity(opts?: {
         onlySelf?: boolean;

package/types/signals-compat.d.ts

@@ -1,6 +1,6 @@
 /**
- * @license Angular v21.1.0-next.4
- * (c) 2010-2025 Google LLC. https://angular.dev/
+ * @license Angular v21.1.0-rc.0
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */