@angular/forms 21.1.0-rc.0 → 21.1.1

package/types/_structure-chunk.d.ts

@@ -1,11 +1,11 @@
 /**
- * @license Angular v21.1.0-rc.0
+ * @license Angular v21.1.1
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
 import * as i0 from '@angular/core';
-import { InjectionToken, Injector, ɵCONTROL as _CONTROL, ɵɵcontrolCreate as __controlCreate, ɵcontrolUpdate as _controlUpdate, Signal, ɵFieldState as _FieldState, Provider, WritableSignal, DestroyableInjector } from '@angular/core';
+import { ɵFormFieldBindingOptions as _FormFieldBindingOptions, InjectionToken, Injector, ɵCONTROL as _CONTROL, ɵɵcontrolCreate as __controlCreate, ɵcontrolUpdate as _controlUpdate, Signal, ɵFieldState as _FieldState, Provider, WritableSignal, DestroyableInjector } from '@angular/core';
 import * as _angular_forms from '@angular/forms';
 import { NgControl, AbstractControl, ValidationErrors, FormControlStatus, ControlValueAccessor, ValidatorFn } from '@angular/forms';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -42,52 +42,15 @@ declare class InteropNgControl implements Pick<NgControl, InteropSharedKeys | 'c
     updateValueAndValidity(): void;
 }
 
-/**
- * Lightweight DI token provided by the {@link Field} directive.
- *
- * @category control
- * @experimental 21.0.0
- */
-declare const FIELD: InjectionToken<Field<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'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)
- * 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 Field<T> {
-    readonly element: HTMLElement;
-    readonly injector: Injector;
-    readonly field: 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 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>;
+interface FormFieldBindingOptions extends _FormFieldBindingOptions {
+    /**
+     * Focuses the binding.
+     *
+     * If not specified, Signal Forms will attempt to focus the host element of the `FormField` when
+     * asked to focus this binding.
+     */
+    focus?: VoidFunction;
 }
-
 /**
  * Lightweight DI token provided by the {@link FormField} directive.
  *
@@ -119,6 +82,7 @@ declare class FormField<T> {
     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>>;
+    private readonly bindingOptions;
     readonly [_CONTROL]: {
         readonly create: typeof __controlCreate;
         readonly update: typeof _controlUpdate;
@@ -130,6 +94,15 @@ declare class FormField<T> {
     private interopNgControl;
     /** Lazily instantiates a fake `NgControl` for this form field. */
     protected getOrCreateNgControl(): InteropNgControl;
+    /**
+     * Registers this `FormField` as a binding on its associated `FieldState`.
+     *
+     * This method should be called at most once for a given `FormField`. A `FormField` placed on a
+     * custom control (`FormUiControl`) automatically registers that custom control as a binding.
+     */
+    registerAsBinding(bindingOptions?: FormFieldBindingOptions): void;
+    /** 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>;
 }
@@ -342,13 +315,6 @@ declare namespace PathKind {
         [ɵɵTYPE]: 'item';
     }
 }
-/**
- * A status indicating whether a field is unsubmitted, submitted, or currently submitting.
- *
- * @category types
- * @experimental 21.0.0
- */
-type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting';
 /**
  * A reason for a field's disablement.
  *
@@ -526,9 +492,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 formFieldBindings: Signal<readonly (Field<unknown> | FormField<unknown>)[]>;
+    readonly formFieldBindings: Signal<readonly FormField<unknown>[]>;
     /**
      * Reads a metadata value from the field.
      * @param key The metadata key to read.
@@ -542,6 +508,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.
@@ -1171,7 +1142,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> | FormField<unknown>) => boolean;
+        [className: string]: (state: FormField<unknown>) => boolean;
     };
 }
 /**
@@ -1572,7 +1543,7 @@ declare class FieldNodeState {
      */
     markAsUntouched(): void;
     /** The {@link FormField} directives that bind this field to a UI control. */
-    readonly formFieldBindings: i0.WritableSignal<readonly (Field<unknown> | FormField<unknown>)[]>;
+    readonly formFieldBindings: i0.WritableSignal<readonly FormField<unknown>[]>;
     constructor(node: FieldNode);
     /**
      * Whether this field is considered dirty.
@@ -1773,6 +1744,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.
      *
@@ -1797,7 +1778,7 @@ declare class FieldNode implements FieldState<unknown> {
     get disabledReasons(): Signal<readonly DisabledReason[]>;
     get hidden(): Signal<boolean>;
     get readonly(): Signal<boolean>;
-    get formFieldBindings(): Signal<readonly (Field<unknown> | FormField<unknown>)[]>;
+    get formFieldBindings(): Signal<readonly FormField<unknown>[]>;
     get submitting(): Signal<boolean>;
     get name(): Signal<string>;
     get max(): Signal<number | undefined> | undefined;
@@ -1834,6 +1815,10 @@ declare class FieldNode implements FieldState<unknown> {
      * Synchronizes the {@link controlValue} with the {@link value} signal immediately.
      */
     private sync;
+    /**
+     * If there is a pending sync, abort it and sync immediately.
+     */
+    private flushSync;
     /**
      * Initiates a debounced {@link sync}.
      *
@@ -1906,7 +1891,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;
     /**
@@ -2357,7 +2342,7 @@ declare function applyWhenValue<TValue>(path: SchemaPath<TValue>, predicate: (va
 /**
  * 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
+ * into the field as a `ValidationError` on the sub-field indicated by the `fieldTree` property of the
  * submission error.
  *
  * @example
@@ -2366,8 +2351,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;
@@ -2400,5 +2386,5 @@ declare function submit<TModel>(form: FieldTree<TModel>, action: (form: FieldTre
  */
 declare function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue>;
 
-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 };
+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, FormFieldBindingOptions, FormOptions, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, MetadataSetterType, OneOrMany, ReadonlyArrayLike, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, TreeValidationResult, TreeValidator, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };

package/types/forms.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v21.1.0-rc.0
+ * @license Angular v21.1.1
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
@@ -4538,7 +4538,7 @@ declare class NgForm extends ControlContainer implements Form, AfterViewInit {
  * and `FormArray` instances to child `FormControlName`, `FormGroupName`,
  * and `FormArrayName` directives.
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  * @see {@link AbstractControl}
  *
  * @usageNotes

package/types/signals-compat.d.ts

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

package/types/signals.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Angular v21.1.0-rc.0
+ * @license Angular v21.1.1
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
 import { Signal, ResourceRef, InputSignal, InputSignalWithTransform, ModelSignal, OutputRef } from '@angular/core';
 import { PathKind, SchemaPath, SchemaPathRules, LogicFn, OneOrMany, ValidationError, SchemaPathTree, FieldValidator, FieldContext, TreeValidationResult, TreeValidator, WithOptionalField, DisabledReason, Debouncer } from './_structure-chunk.js';
-export { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, EmailValidationError, FIELD, FORM_FIELD, Field, FieldState, FieldTree, FormField, FormOptions, ItemFieldContext, ItemType, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MaybeFieldTree, MaybeSchemaPathTree, MetadataKey, MetadataReducer, MetadataSetterType, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PatternValidationError, REQUIRED, ReadonlyArrayLike, RequiredValidationError, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SignalFormsConfig, StandardSchemaValidationError, Subfields, SubmittedStatus, ValidationResult, ValidationSuccess, Validator, WithField, WithoutField, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit } from './_structure-chunk.js';
+export { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, EmailValidationError, FORM_FIELD, FieldState, FieldTree, FormField, FormFieldBindingOptions, FormOptions, ItemFieldContext, ItemType, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MaybeFieldTree, MaybeSchemaPathTree, MetadataKey, MetadataReducer, MetadataSetterType, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PatternValidationError, REQUIRED, ReadonlyArrayLike, RequiredValidationError, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SignalFormsConfig, StandardSchemaValidationError, Subfields, ValidationResult, ValidationSuccess, Validator, WithField, WithoutField, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit } from './_structure-chunk.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import '@angular/forms';
@@ -504,6 +504,13 @@ interface FormUiControl {
      * will automatically bind the value patterns from the bound field to this input.
      */
     readonly pattern?: InputSignal<readonly RegExp[]> | InputSignalWithTransform<readonly RegExp[], unknown>;
+    /**
+     * Focuses the UI control.
+     *
+     * If the focus method is not implemented, Signal Forms will attempt to focus the host element
+     * when asked to focus this control.
+     */
+    focus?(): void;
 }
 /**
  * A contract for a form control that edits a `FieldTree` of type `TValue`. Any component that