feat(forms): Unified Control State Change Events (#54579)

This commit introduces a new method to subscribe to on every `AbstractControl` subclass.
It allows to track value, pristine, touched and status changes on a given control.

Fixes #10887

PR Close #54579

goldens/public-api/forms/index.md

@@ -41,6 +41,7 @@ export abstract class AbstractControl<TValue = any, TRawValue extends TValue = T
     }): void;
     get enabled(): boolean;
     readonly errors: ValidationErrors | null;
+    readonly events: Observable<ControlEvent<TValue>>;
     get<P extends string | (readonly (string | number)[])>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null;
     get<P extends string | Array<string | number>>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null;
     getError(errorCode: string, path?: Array<string | number> | string): any;
@@ -49,22 +50,28 @@ export abstract class AbstractControl<TValue = any, TRawValue extends TValue = T
     hasError(errorCode: string, path?: Array<string | number> | string): boolean;
     hasValidator(validator: ValidatorFn): boolean;
     get invalid(): boolean;
-    markAllAsTouched(): void;
+    markAllAsTouched(opts?: {
+        emitEvent?: boolean;
+    }): void;
     markAsDirty(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     markAsPending(opts?: {
         onlySelf?: boolean;
         emitEvent?: boolean;
     }): void;
     markAsPristine(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     markAsTouched(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     markAsUntouched(opts?: {
         onlySelf?: boolean;
+        emitEvent?: boolean;
     }): void;
     get parent(): FormGroup | FormArray | null;
     abstract patchValue(value: TValue, options?: Object): void;
@@ -185,6 +192,11 @@ export abstract class ControlContainer extends AbstractControlDirective {
     get path(): string[] | null;
 }
 
+// @public
+export abstract class ControlEvent<T = any> {
+    abstract readonly source: AbstractControl<unknown>;
+}
+
 // @public
 export interface ControlValueAccessor {
     registerOnChange(fn: any): void;
@@ -769,6 +781,15 @@ export class PatternValidator extends AbstractValidatorDirective {
     static ɵfac: i0.ɵɵFactoryDeclaration<PatternValidator, never>;
 }
 
+// @public
+export class PristineEvent extends ControlEvent {
+    constructor(pristine: boolean, source: AbstractControl);
+    // (undocumented)
+    readonly pristine: boolean;
+    // (undocumented)
+    readonly source: AbstractControl;
+}
+
 // @public
 export class RadioControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor, OnDestroy, OnInit {
     constructor(renderer: Renderer2, elementRef: ElementRef, _registry: RadioControlRegistry, _injector: Injector);
@@ -854,6 +875,24 @@ export class SelectMultipleControlValueAccessor extends BuiltInControlValueAcces
 // @public
 export type SetDisabledStateOption = 'whenDisabledForLegacyCode' | 'always';
 
+// @public
+export class StatusEvent extends ControlEvent {
+    constructor(status: FormControlStatus, source: AbstractControl);
+    // (undocumented)
+    readonly source: AbstractControl;
+    // (undocumented)
+    readonly status: FormControlStatus;
+}
+
+// @public
+export class TouchedEvent extends ControlEvent {
+    constructor(touched: boolean, source: AbstractControl);
+    // (undocumented)
+    readonly source: AbstractControl;
+    // (undocumented)
+    readonly touched: boolean;
+}
+
 // @public
 export type UntypedFormArray = FormArray<any>;
 
@@ -925,6 +964,15 @@ export class Validators {
     static requiredTrue(control: AbstractControl): ValidationErrors | null;
 }
 
+// @public
+export class ValueChangeEvent<T> extends ControlEvent<T> {
+    constructor(value: T, source: AbstractControl);
+    // (undocumented)
+    readonly source: AbstractControl;
+    // (undocumented)
+    readonly value: T;
+}
+
 // @public (undocumented)
 export const VERSION: Version;
 

packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json

@@ -134,6 +134,9 @@
   {
     "name": "ControlContainer"
   },
+  {
+    "name": "ControlEvent"
+  },
   {
     "name": "DEFAULT_APP_ID"
   },
@@ -467,6 +470,9 @@
   {
     "name": "PlatformRef"
   },
+  {
+    "name": "PristineChangeEvent"
+  },
   {
     "name": "R3Injector"
   },
@@ -536,6 +542,9 @@
   {
     "name": "SkipSelf"
   },
+  {
+    "name": "StatusChangeEvent"
+  },
   {
     "name": "Subject"
   },
@@ -572,6 +581,9 @@
   {
     "name": "TestabilityRegistry"
   },
+  {
+    "name": "TouchedChangeEvent"
+  },
   {
     "name": "USE_VALUE"
   },
@@ -584,6 +596,9 @@
   {
     "name": "Validators"
   },
+  {
+    "name": "ValueChangeEvent"
+  },
   {
     "name": "ViewContainerRef"
   },

packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json

@@ -140,6 +140,9 @@
   {
     "name": "ControlContainer"
   },
+  {
+    "name": "ControlEvent"
+  },
   {
     "name": "DEFAULT_APP_ID"
   },
@@ -458,6 +461,9 @@
   {
     "name": "PlatformRef"
   },
+  {
+    "name": "PristineChangeEvent"
+  },
   {
     "name": "R3Injector"
   },
@@ -524,6 +530,9 @@
   {
     "name": "SkipSelf"
   },
+  {
+    "name": "StatusChangeEvent"
+  },
   {
     "name": "Subject"
   },
@@ -566,6 +575,9 @@
   {
     "name": "TestabilityRegistry"
   },
+  {
+    "name": "TouchedChangeEvent"
+  },
   {
     "name": "USE_VALUE"
   },
@@ -575,6 +587,9 @@
   {
     "name": "VE_ViewContainerRef"
   },
+  {
+    "name": "ValueChangeEvent"
+  },
   {
     "name": "ViewContainerRef"
   },

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 {AbstractControl, AbstractControlOptions, ControlEvent, FormControlStatus, PristineChangeEvent as PristineEvent, StatusChangeEvent as StatusEvent, TouchedChangeEvent as 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';