@angular/forms 21.1.0-next.4 → 21.1.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
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
@@ -43,12 +43,12 @@ declare class InteropNgControl implements Pick<NgControl, InteropSharedKeys | 'c
 }
 
 /**
- * Lightweight DI token provided by the {@link Field} directive.
+ * Lightweight DI token provided by the {@link FormField} directive.
  *
  * @category control
  * @experimental 21.0.0
  */
-declare const FIELD: InjectionToken<Field<unknown>>;
+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
@@ -57,9 +57,9 @@ declare const FIELD: InjectionToken<Field<unknown>>;
  *    compatibility with reactive forms. Prefer options (1) and (2).
  *
  * This directive has several responsibilities:
- * 1. Two-way binds the field's value with the UI control's value
- * 2. Binds additional forms related state on the field to the UI control (disabled, required, etc.)
- * 3. Relays relevant events on the control to the field (e.g. marks field touched on blur)
+ * 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
@@ -68,10 +68,10 @@ declare const FIELD: InjectionToken<Field<unknown>>;
  * @category control
  * @experimental 21.0.0
  */
-declare class Field<T> {
+declare class FormField<T> {
     readonly element: HTMLElement;
     readonly injector: Injector;
-    readonly field: i0.InputSignal<FieldTree<T>>;
+    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;
@@ -82,10 +82,12 @@ declare class Field<T> {
     private readonly controlValueAccessors;
     /** A lazily instantiated fake `NgControl`. */
     private interopNgControl;
-    /** Lazily instantiates a fake `NgControl` for this field. */
+    /** Lazily instantiates a fake `NgControl` for this form field. */
     protected getOrCreateNgControl(): InteropNgControl;
-    static ɵfac: i0.ɵɵFactoryDeclaration<Field<any>, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<Field<any>, "[field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    /** Focuses this UI control. */
+    focus?(): void;
+    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>;
 }
 
 /**
@@ -377,7 +379,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>`.
  *
@@ -480,9 +482,9 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
      */
     readonly keyInParent: Signal<TKey>;
     /**
-     * The {@link Field} directives that bind this field to a UI control.
+     * The {@link FormField} directives that bind this field to a UI control.
      */
-    readonly fieldBindings: Signal<readonly Field<unknown>[]>;
+    readonly formFieldBindings: Signal<readonly FormField<unknown>[]>;
     /**
      * Reads a metadata value from the field.
      * @param key The metadata key to read.
@@ -496,6 +498,11 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
      * @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.
+     */
+    focusBoundControl(): void;
 }
 /**
  * This is FieldState also providing access to the wrapped FormControl.
@@ -559,7 +566,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 +699,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 +945,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 +953,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 +992,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 +1132,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: FormField<unknown>) => boolean;
     };
 }
 /**
@@ -1192,7 +1164,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 +1532,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 FormField<unknown>[]>;
     constructor(node: FieldNode);
     /**
      * Whether this field is considered dirty.
@@ -1635,8 +1607,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 +1624,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.
      */
@@ -1762,6 +1734,16 @@ declare class FieldNode implements FieldState<unknown> {
     readonly fieldProxy: FieldTree<any>;
     private readonly pathNode;
     constructor(options: FieldNodeOptions);
+    focusBoundControl(): void;
+    /**
+     * Gets the Field directive binding that should be focused when the developer calls
+     * `focusBoundControl` on this node.
+     *
+     * This will prioritize focusable bindings to this node, and if multiple exist, it will return
+     * the first one in the DOM. If no focusable bindings exist on this node, it will return the
+     * first focusable binding in the DOM for any descendant node of this one.
+     */
+    private getBindingForFocus;
     /**
      * The `AbortController` for the currently debounced sync, or `undefined` if there is none.
      *
@@ -1786,7 +1768,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 FormField<unknown>[]>;
     get submitting(): Signal<boolean>;
     get name(): Signal<string>;
     get max(): Signal<number | undefined> | undefined;
@@ -1895,7 +1877,7 @@ declare abstract class FieldNodeStructure {
     get injector(): DestroyableInjector;
     constructor(logic: LogicNode, node: FieldNode, createChildNode: ChildNodeCtor);
     /** Gets the child fields of this field. */
-    children(): Iterable<FieldNode>;
+    children(): readonly FieldNode[];
     /** Retrieve a child `FieldNode` of this node by property key. */
     getChild(key: PropertyKey): FieldNode | undefined;
     /**
@@ -2239,7 +2221,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 +2326,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
- * into the field as a `ValidationError` on the sub-field indicated by the `field` property of the
- * server error.
+ * 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 `fieldTree` property of the
+ * submission error.
  *
  * @example
  * ```ts
@@ -2355,8 +2337,9 @@ declare function applyWhenValue<TValue>(path: SchemaPath<TValue>, predicate: (va
  *   const result = await myClient.registerNewUser(registrationForm().value());
  *   if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
  *     return [{
- *       field: registrationForm.username,
- *       error: {kind: 'server', message: 'Username already taken'}
+ *       fieldTree: registrationForm.username,
+ *       kind: 'server',
+ *       message: 'Username already taken'
  *     }];
  *   }
  *   return undefined;
@@ -2370,7 +2353,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 +2372,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, FORM_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
+ * (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
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */