feat(forms): Unified Control State Change Events

This commit adds a global observable to subscribe to track changes around any `AbstractControl` (its children).

This issue fixes #10887

goldens/public-api/forms/index.md

@@ -20,6 +20,12 @@ import { Renderer2 } from '@angular/core';
 import { SimpleChanges } from '@angular/core';
 import { Version } from '@angular/core';
 
+// @public (undocumented)
+export interface AbstractChangeEvent {
+    // (undocumented)
+    changedControl: AbstractControl;
+}
+
 // @public
 export abstract class AbstractControl<TValue = any, TRawValue extends TValue = TValue> {
     constructor(validators: ValidatorFn | ValidatorFn[] | null, asyncValidators: AsyncValidatorFn | AsyncValidatorFn[] | null);
@@ -29,6 +35,8 @@ export abstract class AbstractControl<TValue = any, TRawValue extends TValue = T
     set asyncValidator(asyncValidatorFn: AsyncValidatorFn | null);
     clearAsyncValidators(): void;
     clearValidators(): void;
+    // (undocumented)
+    readonly controlStateChanges: Observable<ControlEvent<TValue>>;
     get dirty(): boolean;
     disable(opts?: {
         onlySelf?: boolean;
@@ -185,6 +193,9 @@ export abstract class ControlContainer extends AbstractControlDirective {
     get path(): string[] | null;
 }
 
+// @public (undocumented)
+export type ControlEvent<T = any> = ValueChangeEvent<T> | PristineEvent | TouchedEvent | StatusEvent;
+
 // @public
 export interface ControlValueAccessor {
     registerOnChange(fn: any): void;
@@ -769,6 +780,14 @@ export class PatternValidator extends AbstractValidatorDirective {
     static ɵfac: i0.ɵɵFactoryDeclaration<PatternValidator, never>;
 }
 
+// @public (undocumented)
+export interface PristineEvent extends AbstractChangeEvent {
+    // (undocumented)
+    type: 'pristine';
+    // (undocumented)
+    value: boolean;
+}
+
 // @public
 export class RadioControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor, OnDestroy, OnInit {
     constructor(renderer: Renderer2, elementRef: ElementRef, _registry: RadioControlRegistry, _injector: Injector);
@@ -854,6 +873,22 @@ export class SelectMultipleControlValueAccessor extends BuiltInControlValueAcces
 // @public
 export type SetDisabledStateOption = 'whenDisabledForLegacyCode' | 'always';
 
+// @public (undocumented)
+export interface StatusEvent extends AbstractChangeEvent {
+    // (undocumented)
+    type: 'status';
+    // (undocumented)
+    value: FormControlStatus;
+}
+
+// @public (undocumented)
+export interface TouchedEvent extends AbstractChangeEvent {
+    // (undocumented)
+    type: 'touched';
+    // (undocumented)
+    value: boolean;
+}
+
 // @public
 export type UntypedFormArray = FormArray<any>;
 
@@ -925,6 +960,14 @@ export class Validators {
     static requiredTrue(control: AbstractControl): ValidationErrors | null;
 }
 
+// @public (undocumented)
+export interface ValueChangeEvent<T> extends AbstractChangeEvent {
+    // (undocumented)
+    type: 'value';
+    // (undocumented)
+    value: T;
+}
+
 // @public (undocumented)
 export const VERSION: Version;
 

packages/forms/src/forms.ts

@@ -43,7 +43,7 @@ export {SelectMultipleControlValueAccessor, ɵNgSelectMultipleOption} from './di
 export {SetDisabledStateOption} from './directives/shared';
 export {AsyncValidator, AsyncValidatorFn, CheckboxRequiredValidator, EmailValidator, MaxLengthValidator, MaxValidator, MinLengthValidator, MinValidator, PatternValidator, RequiredValidator, ValidationErrors, Validator, ValidatorFn} from './directives/validators';
 export {ControlConfig, FormBuilder, NonNullableFormBuilder, UntypedFormBuilder, ɵElement} from './form_builder';
-export {AbstractControl, AbstractControlOptions, FormControlStatus, ɵCoerceStrArrToNumArr, ɵGetProperty, ɵNavigate, ɵRawValue, ɵTokenize, ɵTypedOrUntyped, ɵValue, ɵWriteable} from './model/abstract_model';
+export {AbstractChangeEvent, AbstractControl, AbstractControlOptions, ControlEvent, FormControlStatus, PristineEvent, StatusEvent, TouchedEvent, ValueChangeEvent, ɵCoerceStrArrToNumArr, ɵGetProperty, ɵNavigate, ɵRawValue, ɵTokenize, ɵTypedOrUntyped, ɵValue, ɵWriteable} from './model/abstract_model';
 export {FormArray, isFormArray, UntypedFormArray, ɵFormArrayRawValue, ɵFormArrayValue} from './model/form_array';
 export {FormControl, FormControlOptions, FormControlState, isFormControl, UntypedFormControl, ɵFormControlCtor} from './model/form_control';
 export {FormGroup, FormRecord, isFormGroup, isFormRecord, UntypedFormGroup, ɵFormGroupRawValue, ɵFormGroupValue, ɵOptionalKeys} from './model/form_group';