docs: Add unified control state change events (angular#64279)

PR Close angular#64279

Author: SkyZeroZx

adev/src/content/guide/forms/reactive-forms.md

@@ -388,6 +388,108 @@ Initially, the form contains one `Alias` field. To add another field, click the
 
 </docs-workflow>
 
+## Unified control state change events
+
+All form controls expose a single unified stream of **control state change events** through the `events` observable on `AbstractControl` (`FormControl`, `FormGroup`, `FormArray`, and `FormRecord`).  
+This unified stream lets you react to **value**, **status**, **pristine**, **touched** and **reset** state changes and also for **form-level actions** such as **submit** , allowing you to handle all updates with a one subscription instead of wiring multiple observables.
+
+### Event types
+
+Each item emitted by `events` is an instance of a specific event class:
+
+- **`ValueChangeEvent`** — when the control’s **value** changes.
+- **`StatusChangeEvent`** — when the control’s **validation status** updates to one of the `FormControlStatus` values (`VALID`, `INVALID`, `PENDING`, or `DISABLED`).
+- **`PristineChangeEvent`** — when the control’s **pristine/dirty** state changes.
+- **`TouchedChangeEvent`** — when the control’s **touched/untouched** state changes.
+- **`FormResetEvent`** — when a control or form is reset, either via the `reset()` API or a native action.
+- **`FormSubmittedEvent`** — when the form is submitted.
+
+All event classes extend `ControlEvent` and include a `source` reference to the `AbstractControl` that originated the change, which is useful in large forms.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  FormControl,
+  ValueChangeEvent,
+  StatusChangeEvent,
+  PristineChangeEvent,
+  TouchedChangeEvent,
+  FormResetEvent,
+  FormSubmittedEvent,
+  ReactiveFormsModule,
+  FormGroup,
+} from '@angular/forms';
+
+@Component({/* ... */ })
+export class UnifiedEventsBasicComponent {
+  form = new FormGroup({
+    username: new FormControl(''),
+  });
+
+  constructor() {
+    this.form.events.subscribe((e) => {
+      if (e instanceof ValueChangeEvent) {
+        console.log('Value changed to: ', e.value);
+      }
+
+      if (e instanceof StatusChangeEvent) {
+        console.log('Status changed to: ', e.status);
+      }
+
+      if (e instanceof PristineChangeEvent) {
+        console.log('Pristine status changed to: ', e.pristine);
+      }
+
+      if (e instanceof TouchedChangeEvent) {
+        console.log('Touched status changed to: ', e.touched);
+      }
+
+      if (e instanceof FormResetEvent) {
+        console.log('Form was reset');
+      }
+
+      if (e instanceof FormSubmittedEvent) {
+        console.log('Form was submitted');
+      }
+    });
+  }
+}
+```
+
+### Filtering specific events
+
+Prefer RxJS operators when you only need a subset of event types.
+
+```ts
+import { filter } from 'rxjs/operators';
+import { StatusChangeEvent } from '@angular/forms';
+
+control.events
+  .pipe(filter((e) => e instanceof StatusChangeEvent))
+  .subscribe((e) => console.log('Status:', e.status));
+```
+
+### Unifying from multiple subscriptions
+
+**Before**
+
+```ts
+import { combineLatest } from 'rxjs/operators';
+
+combineLatest([control.valueChanges, control.statusChanges])
+  .subscribe(([value, status]) => { /* ... */ });
+```
+
+**After**
+
+```ts
+control.events.subscribe((e) => {
+  // Handle ValueChangeEvent, StatusChangeEvent, etc.
+});
+```
+
+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.
+
 ## Reactive forms API summary
 
 The following table lists the base classes and services used to create and manage reactive form controls.

packages/forms/src/model/abstract_model.ts

@@ -101,6 +101,8 @@ export abstract class ControlEvent<T = any> {
 /**
  * Event fired when the value of a control changes.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 export class ValueChangeEvent<T> extends ControlEvent<T> {
@@ -115,6 +117,8 @@ export class ValueChangeEvent<T> extends ControlEvent<T> {
 /**
  * Event fired when the control's pristine state changes (pristine <=> dirty).
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi */
 export class PristineChangeEvent extends ControlEvent {
   constructor(
@@ -128,6 +132,8 @@ export class PristineChangeEvent extends ControlEvent {
 /**
  * Event fired when the control's touched status changes (touched <=> untouched).
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 export class TouchedChangeEvent extends ControlEvent {
@@ -142,6 +148,8 @@ export class TouchedChangeEvent extends ControlEvent {
 /**
  * Event fired when the control's status changes.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 export class StatusChangeEvent extends ControlEvent {
@@ -156,6 +164,8 @@ export class StatusChangeEvent extends ControlEvent {
 /**
  * Event fired when a form is submitted
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 export class FormSubmittedEvent extends ControlEvent {
@@ -166,6 +176,8 @@ export class FormSubmittedEvent extends ControlEvent {
 /**
  * Event fired when a form is reset.
  *
+ * @see {@link AbstractControl.events}
+ *
  * @publicApi
  */
 export class FormResetEvent extends ControlEvent {
@@ -750,6 +762,7 @@ export abstract class AbstractControl<
    * `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)
    */
   public readonly events = this._events.asObservable();