@angular/forms 18.0.0-next.2 → 18.0.0-next.4

package/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * @license Angular v18.0.0-next.2
- * (c) 2010-2022 Google LLC. https://angular.io/
+ * @license Angular v18.0.0-next.4
+ * (c) 2010-2024 Google LLC. https://angular.io/
  * License: MIT
  */
 
@@ -34,9 +34,9 @@ import { Version } from '@angular/core';
  * The first type parameter TValue represents the value type of the control (`control.value`).
  * The optional type parameter TRawValue  represents the raw value type (`control.getRawValue()`).
  *
- * @see [Forms Guide](/guide/forms)
- * @see [Reactive Forms Guide](/guide/reactive-forms)
- * @see [Dynamic Forms Guide](/guide/dynamic-form)
+ * @see [Forms Guide](guide/forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
+ * @see [Dynamic Forms Guide](guide/forms/dynamic-forms)
  *
  * @publicApi
  */
@@ -175,6 +175,19 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * a `blur` event on it.
      */
     get untouched(): boolean;
+    /**
+     * A multicasting observable that emits an event every time the state of the control changes.
+     * It emits for value, status, pristine or touched changes.
+     *
+     * **Note**: On value change, the emit happens right after a value of this control is updated. The
+     * value of a parent control (for example if this FormControl is a part of a FormGroup) is updated
+     * later, so accessing a value of a parent control (using the `value` property) from the callback
+     * of this event might result in getting a value that has not been updated yet. Subscribe to the
+     * `events` of the parent control instead.
+     * For other event types, the events are emitted after the parent control has been updated.
+     *
+     */
+    readonly events: Observable<ControlEvent<TValue>>;
     /**
      * A multicasting observable that emits an event every time the value of the control changes, in
      * the UI or programmatically. It also emits an event each time you call enable() or disable()
@@ -185,6 +198,8 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * accessing a value of a parent control (using the `value` property) from the callback of this
      * event might result in getting a value that has not been updated yet. Subscribe to the
      * `valueChanges` event of the parent control instead.
+     *
+     * TODO: this should be piped from events() but is breaking in G3
      */
     readonly valueChanges: Observable<TValue>;
     /**
@@ -194,6 +209,7 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * @see {@link FormControlStatus}
      * @see {@link AbstractControl.status}
      *
+     * TODO: this should be piped from events() but is breaking in G3
      */
     readonly statusChanges: Observable<FormControlStatus>;
     /**
@@ -353,15 +369,27 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * and emits events after marking is applied.
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
+     * * `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.
      */
     markAsTouched(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     /**
      * Marks the control and all its descendant controls as `touched`.
      * @see {@link markAsTouched()}
+     *
+     * @param opts Configuration options that determine how the control propagates changes
+     * and emits events after marking is applied.
+     * * `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.
      */
-    markAllAsTouched(): void;
+    markAllAsTouched(opts?: {
+        emitEvent?: boolean;
+    }): void;
     /**
      * Marks the control as `untouched`.
      *
@@ -376,9 +404,13 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * and emits events after the marking is applied.
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
+     * * `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.
      */
     markAsUntouched(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     /**
      * Marks the control as `dirty`. A control becomes dirty when
@@ -392,9 +424,13 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * and emits events after marking is applied.
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
+     * * `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.
      */
     markAsDirty(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     /**
      * Marks the control as `pristine`.
@@ -411,9 +447,13 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * marking is applied.
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
+     * * `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.
      */
     markAsPristine(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     /**
      * Marks the control as `pending`.
@@ -427,8 +467,9 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
      * * `emitEvent`: When true or not supplied (the default), the `statusChanges`
-     * observable emits an event with the latest status the control is marked pending.
-     * When false, no events are emitted.
+     * observable emits an event with the latest status the control is marked pending
+     * and the `events` observable emits a `StatusChangeEvent` with the `status` property being
+     * `PENDING` When false, no events are emitted.
      *
      */
     markAsPending(opts?: {
@@ -447,8 +488,8 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * changes and emits events after the control is disabled.
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
-     * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
-     * `valueChanges`
+     * * `emitEvent`: When true or not supplied (the default), the `statusChanges`,
+     * `valueChanges` and `events`
      * observables emit events with the latest status and value when the control is disabled.
      * When false, no events are emitted.
      */
@@ -469,8 +510,8 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * emits events when marked as untouched
      * * `onlySelf`: When true, mark only this control. When false or not supplied,
      * marks all direct ancestors. Default is false.
-     * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
-     * `valueChanges`
+     * * `emitEvent`: When true or not supplied (the default), the `statusChanges`,
+     * `valueChanges` and `events`
      * observables emit events with the latest status and value when the control is enabled.
      * When false, no events are emitted.
      */
@@ -511,8 +552,8 @@ export declare abstract class AbstractControl<TValue = any, TRawValue extends TV
      * after updates and validity checks are applied.
      * * `onlySelf`: When true, only update this control. When false or not supplied,
      * update all direct ancestors. Default is false.
-     * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
-     * `valueChanges`
+     * * `emitEvent`: When true or not supplied (the default), the `statusChanges`,
+     * `valueChanges` and `events`
      * observables emit events with the latest status and value when the control is updated.
      * When false, no events are emitted.
      */
@@ -1101,7 +1142,7 @@ export declare class CheckboxControlValueAccessor extends BuiltInControlValueAcc
  * A Directive that adds the `required` validator to checkbox controls marked with the
  * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -1164,6 +1205,18 @@ export declare abstract class ControlContainer extends AbstractControlDirective
     get path(): string[] | null;
 }
 
+/**
+ * Base class for every event sent by `AbstractControl.events()`
+ *
+ * @publicApi
+ */
+export declare abstract class ControlEvent<T = any> {
+    /**
+     * Form control from which this event is originated.
+     */
+    abstract readonly source: AbstractControl<unknown>;
+}
+
 /**
  * @description
  * Defines an interface that acts as a bridge between the Angular forms API and a
@@ -1349,7 +1402,7 @@ declare const EMAIL_VALIDATOR: any;
  * incorporate more RFC rules. More information can be found on the [Validators.email
  * page](api/forms/Validators#email).
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -1781,7 +1834,7 @@ export declare class FormArray<TControl extends AbstractControl<any> = any> exte
  * will look for a `FormArray` registered with that name in the parent
  * `FormGroup` instance you passed into `FormGroupDirective`.
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  * @see {@link AbstractControl}
  *
  * @usageNotes
@@ -1847,7 +1900,7 @@ declare const formArrayNameProvider: any;
  * `FormControl`, `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to
  * build complex forms.
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  *
  * @publicApi
  */
@@ -2006,7 +2059,7 @@ export declare class FormBuilder {
  * See [usage examples below](#usage-notes).
  *
  * @see {@link AbstractControl}
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  * @see [Usage Notes](#usage-notes)
  *
  * @publicApi
@@ -2243,9 +2296,8 @@ export declare const FormControl: ɵFormControlCtor;
  * Note that support for using the `ngModel` input property and `ngModelChange` event with reactive
  * form directives was deprecated in Angular v6 and is scheduled for removal in
  * a future version of Angular.
- * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  * @see {@link FormControl}
  * @see {@link AbstractControl}
  *
@@ -2313,7 +2365,7 @@ export declare class FormControlDirective extends NgControl implements OnChanges
  * Syncs a `FormControl` in an existing `FormGroup` to a form control
  * element by name.
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  * @see {@link FormControl}
  * @see {@link AbstractControl}
  *
@@ -2337,8 +2389,6 @@ export declare class FormControlDirective extends NgControl implements OnChanges
  * form directives has been deprecated in Angular v6 and is scheduled for removal in
  * a future version of Angular.
  *
- * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
- *
  * @ngModule ReactiveFormsModule
  * @publicApi
  */
@@ -2816,7 +2866,7 @@ export declare class FormGroup<TControl extends {
  * 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
@@ -2996,7 +3046,7 @@ export declare class FormGroupDirective extends ControlContainer implements Form
  * form separately from the rest or to group the values of certain
  * controls into their own nested object.
  *
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  *
  * @usageNotes
  *
@@ -3158,8 +3208,8 @@ export declare interface FormRecord<TControl> {
  * Exports the required providers and directives for template-driven forms,
  * making them available for import by NgModules that import this module.
  *
- * @see [Forms Overview](/guide/forms-overview)
- * @see [Template-driven Forms Guide](/guide/forms)
+ * @see [Forms Overview](guide/forms)
+ * @see [Template-driven Forms Guide](guide/forms)
  *
  * @publicApi
  */
@@ -3398,7 +3448,7 @@ declare const MAX_VALIDATOR: Provider;
  * A directive that adds maximum length validation to controls marked with the
  * `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -3429,7 +3479,7 @@ export declare class MaxLengthValidator extends AbstractValidatorDirective {
  * A directive which installs the {@link MaxValidator} for any `formControlName`,
  * `formControl`, or control with `ngModel` that also has a `max` attribute.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -3472,7 +3522,7 @@ declare const MIN_VALIDATOR: Provider;
  * A directive that adds minimum length validation to controls marked with the
  * `minlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -3503,7 +3553,7 @@ export declare class MinLengthValidator extends AbstractValidatorDirective {
  * A directive which installs the {@link MinValidator} for any `formControlName`,
  * `formControl`, or control with `ngModel` that also has a `min` attribute.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -4249,7 +4299,7 @@ declare const PATTERN_VALIDATOR: any;
  * `pattern` attribute. The regex must match the entire control value.
  * The directive is provided with the `NG_VALIDATORS` multi-provider list.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -4294,6 +4344,17 @@ declare interface PermissiveAbstractControlOptions extends Omit<AbstractControlO
  */
 declare type PermissiveControlConfig<T> = Array<T | FormControlState<T> | ValidatorConfig>;
 
+/**
+ * Event fired when the control's pristine state changes (pristine <=> dirty).
+ *
+ * @publicApi
+ */
+export declare class PristineEvent extends ControlEvent {
+    readonly pristine: boolean;
+    readonly source: AbstractControl;
+    constructor(pristine: boolean, source: AbstractControl);
+}
+
 /**
  * @description
  * Class used by Angular to track radio buttons. For internal use only.
@@ -4442,8 +4503,8 @@ declare const REACTIVE_DRIVEN_DIRECTIVES: Type<any>[];
  * Exports the required infrastructure and directives for reactive forms,
  * making them available for import by NgModules that import this module.
  *
- * @see [Forms Overview](guide/forms-overview)
- * @see [Reactive Forms Guide](guide/reactive-forms)
+ * @see [Forms Overview](guide/forms)
+ * @see [Reactive Forms Guide](guide/forms/reactive-forms)
  *
  * @publicApi
  */
@@ -4478,7 +4539,7 @@ declare const REQUIRED_VALIDATOR: Provider;
  * A directive that adds the `required` validator to any controls marked with the
  * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
  *
- * @see [Form Validation](guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @usageNotes
  *
@@ -4659,8 +4720,30 @@ export declare type SetDisabledStateOption = 'whenDisabledForLegacyCode' | 'alwa
 
 declare const SHARED_FORM_DIRECTIVES: Type<any>[];
 
+/**
+ * Event fired when the control's status changes.
+ *
+ * @publicApi
+ */
+export declare class StatusEvent extends ControlEvent {
+    readonly status: FormControlStatus;
+    readonly source: AbstractControl;
+    constructor(status: FormControlStatus, source: AbstractControl);
+}
+
 declare const TEMPLATE_DRIVEN_DIRECTIVES: Type<any>[];
 
+/**
+ * Event fired when the control's touched status changes (touched <=> untouched).
+ *
+ * @publicApi
+ */
+export declare class TouchedEvent extends ControlEvent {
+    readonly touched: boolean;
+    readonly source: AbstractControl;
+    constructor(touched: boolean, source: AbstractControl);
+}
+
 /**
  * UntypedFormArray is a non-strongly-typed version of `FormArray`, which
  * permits heterogenous controls.
@@ -4822,7 +4905,7 @@ export declare interface ValidatorFn {
  * A validator is a function that processes a `FormControl` or collection of
  * controls and returns an error map or null. A null map means that validation has passed.
  *
- * @see [Form Validation](/guide/form-validation)
+ * @see [Form Validation](guide/forms/form-validation)
  *
  * @publicApi
  */
@@ -5093,6 +5176,17 @@ export declare class Validators {
     static composeAsync(validators: (AsyncValidatorFn | null)[]): AsyncValidatorFn | null;
 }
 
+/**
+ * Event fired when the value of a control changes.
+ *
+ * @publicApi
+ */
+export declare class ValueChangeEvent<T> extends ControlEvent<T> {
+    readonly value: T;
+    readonly source: AbstractControl;
+    constructor(value: T, source: AbstractControl);
+}
+
 /**
  * @publicApi
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/forms",
-  "version": "18.0.0-next.2",
+  "version": "18.0.0-next.4",
   "description": "Angular - directives and services for creating forms",
   "author": "angular",
   "license": "MIT",
@@ -11,9 +11,9 @@
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "@angular/core": "18.0.0-next.2",
-    "@angular/common": "18.0.0-next.2",
-    "@angular/platform-browser": "18.0.0-next.2",
+    "@angular/core": "18.0.0-next.4",
+    "@angular/common": "18.0.0-next.4",
+    "@angular/platform-browser": "18.0.0-next.4",
     "rxjs": "^6.5.3 || ^7.4.0"
   },
   "repository": {