@angular/forms 21.0.0-next.1 → 21.0.0-next.10

package/{index.d.ts → types/forms.d.ts}

@@ -1,6 +1,6 @@
 /**
- * @license Angular v21.0.0-next.1
- * (c) 2010-2025 Google LLC. https://angular.io/
+ * @license Angular v21.0.0-next.10
+ * (c) 2010-2025 Google LLC. https://angular.dev/
  * License: MIT
  */
 
@@ -1100,6 +1100,8 @@ declare class FormArray<TControl extends AbstractControl<any> = any> extends Abs
      * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
      * `valueChanges` observables emit events with the latest status and value when the control is
      * inserted. When false, no events are emitted.
+     *
+     * NOTE: Pushing to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
      */
     push(control: TControl | Array<TControl>, options?: {
         emitEvent?: boolean;
@@ -1116,6 +1118,8 @@ declare class FormArray<TControl extends AbstractControl<any> = any> extends Abs
      * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
      * `valueChanges` observables emit events with the latest status and value when the control is
      * inserted. When false, no events are emitted.
+     *
+     * NOTE: Inserting to the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
      */
     insert(index: number, control: TControl, options?: {
         emitEvent?: boolean;
@@ -1131,6 +1135,8 @@ declare class FormArray<TControl extends AbstractControl<any> = any> extends Abs
      * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
      * `valueChanges` observables emit events with the latest status and value when the control is
      * removed. When false, no events are emitted.
+     *
+     * NOTE: Removing the FormArray will not mark it dirty. If you want to mark if dirty, call `markAsDirty()`.
      */
     removeAt(index: number, options?: {
         emitEvent?: boolean;
@@ -1279,6 +1285,7 @@ declare class FormArray<TControl extends AbstractControl<any> = any> extends Abs
     reset(value?: ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, options?: {
         onlySelf?: boolean;
         emitEvent?: boolean;
+        overwriteDefaultValue?: boolean;
     }): void;
     /**
      * The aggregate value of the array, including any disabled controls.
@@ -1345,6 +1352,8 @@ declare const UntypedFormArray: UntypedFormArrayCtor;
  * @description
  * Asserts that the given control is an instance of `FormArray`
  *
+ * @see [Utility functions for narrowing form control types](guide/forms/reactive-forms#utility-functions-for-narrowing-form-control-types)
+ *
  * @publicApi
  */
 declare const isFormArray: (control: unknown) => control is FormArray;
@@ -1577,7 +1586,7 @@ interface FormControl<TValue = any> extends AbstractControl<TValue> {
      * value. See {@link FormControlOptions#nonNullable} for more information on configuring
      * a default value.
      */
-    readonly defaultValue: TValue;
+    defaultValue: TValue;
     /**
      * Sets a new value for the form control.
      *
@@ -1653,11 +1662,13 @@ interface FormControl<TValue = any> extends AbstractControl<TValue> {
      * `valueChanges`
      * observables emit events with the latest status and value when the control is reset.
      * When false, no events are emitted.
+     * * `overwriteDefaultValue`: When true, the value used to reset the control becomes the new default value of the control.
      *
      */
     reset(formState?: TValue | FormControlState<TValue>, options?: {
         onlySelf?: boolean;
         emitEvent?: boolean;
+        overwriteDefaultValue?: boolean;
     }): void;
     /**
      * For a simple FormControl, the raw value is equivalent to the value.
@@ -1695,6 +1706,8 @@ declare const UntypedFormControl: UntypedFormControlCtor;
  * @description
  * Asserts that the given control is an instance of `FormControl`
  *
+ * @see [Utility functions for narrowing form control types](guide/forms/reactive-forms#utility-functions-for-narrowing-form-control-types)
+ *
  * @publicApi
  */
 declare const isFormControl: (control: unknown) => control is FormControl;
@@ -2093,6 +2106,7 @@ declare class FormGroup<TControl extends {
     reset(value?: ɵTypedOrUntyped<TControl, ɵFormGroupArgumentValue<TControl>, any>, options?: {
         onlySelf?: boolean;
         emitEvent?: boolean;
+        overwriteDefaultValue?: boolean;
     }): void;
     /**
      * The aggregate value of the `FormGroup`, including any disabled controls.
@@ -2120,6 +2134,8 @@ declare const UntypedFormGroup: UntypedFormGroupCtor;
  * @description
  * Asserts that the given control is an instance of `FormGroup`
  *
+ * @see [Utility functions for narrowing form control types](guide/forms/reactive-forms#utility-functions-for-narrowing-form-control-types)
+ *
  * @publicApi
  */
 declare const isFormGroup: (control: unknown) => control is FormGroup;
@@ -2233,6 +2249,8 @@ interface FormRecord<TControl> {
  * @description
  * Asserts that the given control is an instance of `FormRecord`
  *
+ * @see [Utility functions for narrowing form control types](guide/forms/reactive-forms#utility-functions-for-narrowing-form-control-types)
+ *
  * @publicApi
  */
 declare const isFormRecord: (control: unknown) => control is FormRecord;
@@ -2269,6 +2287,8 @@ declare abstract class ControlEvent<T = any> {
 /**
  * Event fired when the value of a control changes.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 declare class ValueChangeEvent<T> extends ControlEvent<T> {
@@ -2279,6 +2299,8 @@ declare class ValueChangeEvent<T> extends ControlEvent<T> {
 /**
  * Event fired when the control's pristine state changes (pristine <=> dirty).
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi */
 declare class PristineChangeEvent extends ControlEvent {
     readonly pristine: boolean;
@@ -2288,6 +2310,8 @@ declare class PristineChangeEvent extends ControlEvent {
 /**
  * Event fired when the control's touched status changes (touched <=> untouched).
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 declare class TouchedChangeEvent extends ControlEvent {
@@ -2298,6 +2322,8 @@ declare class TouchedChangeEvent extends ControlEvent {
 /**
  * Event fired when the control's status changes.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 declare class StatusChangeEvent extends ControlEvent {
@@ -2308,6 +2334,8 @@ declare class StatusChangeEvent extends ControlEvent {
 /**
  * Event fired when a form is submitted
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 declare class FormSubmittedEvent extends ControlEvent {
@@ -2317,6 +2345,8 @@ declare class FormSubmittedEvent extends ControlEvent {
 /**
  * Event fired when a form is reset.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 declare class FormResetEvent extends ControlEvent {
@@ -2635,6 +2665,7 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      * `events` of the parent control instead.
      * For other event types, the events are emitted after the parent control has been updated.
      *
+     * @see [Unified control state change events](guide/forms/reactive-forms#unified-control-state-change-events)
      */
     readonly events: Observable<ControlEvent<TValue>>;
     /**
@@ -3028,6 +3059,8 @@ declare abstract class AbstractControl<TValue = any, TRawValue extends TValue =
      *
      * Calling `setErrors` also updates the validity of the parent control.
      *
+     * Note: Manually set errors are always overwritten by the results of the next validation run.
+     *
      * @param opts Configuration options that determine how the control propagates
      * changes and emits events after the control errors are set.
      * * `emitEvent`: When true or not supplied (the default), the `statusChanges`
@@ -4061,7 +4094,7 @@ type SetDisabledStateOption = 'whenDisabledForLegacyCode' | 'always';
  *
  * To inspect the properties of the associated `FormControl` (like the validity state),
  * export the directive into a local template variable using `ngModel` as the key (ex:
- * `#myVar="ngModel"`). You can then access the control using the directive's `control` property.
+ * `#myVar="ngModel"`). You can then access the control using the directive's `field` property.
  * However, the most commonly used properties (like `valid` and `dirty`) also exist on the control
  * for direct access. See a full list of properties directly available in
  * `AbstractControlDirective`.