@angular/forms 21.1.0 → 21.2.0-next.0

package/types/_structure-chunk.d.ts

@@ -1,11 +1,11 @@
 /**
- * @license Angular v21.1.0
+ * @license Angular v21.2.0-next.0
  * (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,6 +42,15 @@ declare class InteropNgControl implements Pick<NgControl, InteropSharedKeys | 'c
     updateValueAndValidity(): void;
 }
 
+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?(options?: FocusOptions): void;
+}
 /**
  * Lightweight DI token provided by the {@link FormField} directive.
  *
@@ -73,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;
@@ -84,8 +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;
+    focus(options?: FocusOptions): 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>;
 }
@@ -298,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.
  *
@@ -501,8 +511,9 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
     /**
      * 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(): void;
+    focusBoundControl(options?: FocusOptions): void;
 }
 /**
  * This is FieldState also providing access to the wrapped FormControl.
@@ -1734,7 +1745,7 @@ declare class FieldNode implements FieldState<unknown> {
     readonly fieldProxy: FieldTree<any>;
     private readonly pathNode;
     constructor(options: FieldNodeOptions);
-    focusBoundControl(): void;
+    focusBoundControl(options?: FocusOptions): void;
     /**
      * Gets the Field directive binding that should be focused when the developer calls
      * `focusBoundControl` on this node.
@@ -1805,6 +1816,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}.
      *
@@ -2373,4 +2388,4 @@ declare function submit<TModel>(form: FieldTree<TModel>, action: (form: FieldTre
 declare function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue>;
 
 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 };
+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
+ * @license Angular v21.2.0-next.0
  * (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
+ * @license Angular v21.2.0-next.0
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */

package/types/signals.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Angular v21.1.0
+ * @license Angular v21.2.0-next.0
  * (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, FORM_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?(options?: FocusOptions): void;
 }
 /**
  * A contract for a form control that edits a `FieldTree` of type `TValue`. Any component that