refactor(material/core): no longer define stateChanges in mixinErrorState

The error state mixin provided in `@angular/material/core` currently
defines the `stateChanges` class member as part of the mixin. This
is unexpected as consumers might deal with the `stateChanges` member
differently. e.g. in some components the `stateChanges` field is
intended to show up in the docs, or the JSDoc descripton varies. e.g.
the observable could emit whenever form-field state changes, and it
should be updated, or it emits always when something changes (e.g.
even a component input which is not relevant for the form-field
control).

In general we want to avoid this member being defined in the mixin
as the mixin is rather about the error state, and not defining a
subject that can emit whenever "state" changes.

Author: devversion

src/material-experimental/mdc-chips/chip-grid.ts

@@ -36,7 +36,7 @@ import {
 } from '@angular/material-experimental/mdc-core';
 import {MatFormFieldControl} from '@angular/material-experimental/mdc-form-field';
 import {MatChipTextControl} from './chip-text-control';
-import {merge, Observable, Subscription} from 'rxjs';
+import {merge, Observable, Subject, Subscription} from 'rxjs';
 import {startWith, takeUntil} from 'rxjs/operators';
 import {MatChipEvent} from './chip';
 import {MatChipRow} from './chip-row';
@@ -57,13 +57,24 @@ export class MatChipGridChange {
  * @docs-private
  */
 class MatChipGridBase extends MatChipSet {
+  /**
+   * Emits whenever the component state changes and should cause the parent
+   * form-field to update. Implemented as part of `MatFormFieldControl`.
+   * @docs-private
+   */
+  readonly stateChanges = new Subject<void>();
+
   constructor(_elementRef: ElementRef,
               _changeDetectorRef: ChangeDetectorRef,
               _dir: Directionality,
               public _defaultErrorStateMatcher: ErrorStateMatcher,
               public _parentForm: NgForm,
               public _parentFormGroup: FormGroupDirective,
-              /** @docs-private */
+              /**
+               * Form control bound to the component.
+               * Implemented as part of `MatFormFieldControl`.
+               * @docs-private
+               */
               public ngControl: NgControl) {
     super(_elementRef, _changeDetectorRef, _dir);
   }

src/material/chips/chip-list.ts

@@ -43,10 +43,21 @@ import {MatChipTextControl} from './chip-text-control';
 // Boilerplate for applying mixins to MatChipList.
 /** @docs-private */
 const _MatChipListBase = mixinErrorState(class {
+  /**
+   * Emits whenever the component state changes and should cause the parent
+   * form-field to update. Implemented as part of `MatFormFieldControl`.
+   * @docs-private
+   */
+  readonly stateChanges = new Subject<void>();
+
   constructor(public _defaultErrorStateMatcher: ErrorStateMatcher,
               public _parentForm: NgForm,
               public _parentFormGroup: FormGroupDirective,
-              /** @docs-private */
+              /**
+               * Form control bound to the component.
+               * Implemented as part of `MatFormFieldControl`.
+               * @docs-private
+               */
               public ngControl: NgControl) {}
 });
 

src/material/core/common-behaviors/error-state.ts

@@ -14,8 +14,6 @@ import {AbstractConstructor, Constructor} from './constructor';
 
 /** @docs-private */
 export interface CanUpdateErrorState {
-  /** Emits whenever the component state changes. */
-  readonly stateChanges: Subject<void>;
   /** Updates the error state based on the provided error state matcher. */
   updateErrorState(): void;
   /** Whether the component is in an error state. */
@@ -37,7 +35,12 @@ export interface HasErrorState {
   _parentFormGroup: FormGroupDirective;
   _parentForm: NgForm;
   _defaultErrorStateMatcher: ErrorStateMatcher;
+
+  // These properties are defined as per the `MatFormFieldControl` interface. Since
+  // this mixin is commonly used with custom form-field controls, we respect the
+  // properties (also with the public name they need according to `MatFormFieldControl`).
   ngControl: NgControl;
+  stateChanges: Subject<void>;
 }
 
 /**
@@ -49,13 +52,6 @@ export function mixinErrorState<T extends AbstractConstructor<HasErrorState>>(ba
 export function mixinErrorState<T extends Constructor<HasErrorState>>(base: T):
   CanUpdateErrorStateCtor & T {
   return class extends base {
-    // This class member exists as an interop with `MatFormFieldControl` which expects
-    // a public `stateChanges` observable to emit whenever the form field should be updated.
-    // The description is not specifically mentioning the error state, as classes using this
-    // mixin can/should emit an event in other cases too.
-    /** Emits whenever the component state changes. */
-    readonly stateChanges = new Subject<void>();
-
     /** Whether the component is in an error state. */
     errorState: boolean = false;
 

src/material/datepicker/date-range-input-parts.ts

@@ -71,7 +71,10 @@ export const MAT_DATE_RANGE_INPUT_PARENT =
 abstract class MatDateRangeInputPartBase<D>
   extends MatDatepickerInputBase<DateRange<D>> implements OnInit, DoCheck {
 
-  /** @docs-private */
+  /**
+   * Form control bound to this input part.
+   * @docs-private
+   */
   ngControl: NgControl;
 
   /** @docs-private */

src/material/input/input.ts

@@ -53,10 +53,21 @@ let nextUniqueId = 0;
 // Boilerplate for applying mixins to MatInput.
 /** @docs-private */
 const _MatInputBase = mixinErrorState(class {
+  /**
+   * Emits whenever the component state changes and should cause the parent
+   * form-field to update. Implemented as part of `MatFormFieldControl`.
+   * @docs-private
+   */
+  readonly stateChanges = new Subject<void>();
+
   constructor(public _defaultErrorStateMatcher: ErrorStateMatcher,
               public _parentForm: NgForm,
               public _parentFormGroup: FormGroupDirective,
-              /** @docs-private */
+              /**
+               * Form control bound to the component.
+               * Implemented as part of `MatFormFieldControl`.
+               * @docs-private
+               */
               public ngControl: NgControl) {}
 });
 

src/material/select/select.ts

@@ -181,10 +181,22 @@ export class MatSelectChange {
 /** @docs-private */
 const _MatSelectMixinBase =
   mixinDisableRipple(mixinTabIndex(mixinDisabled(mixinErrorState(class {
+    /**
+     * Emits whenever the component state changes and should cause the parent
+     * form-field to update. Implemented as part of `MatFormFieldControl`.
+     * @docs-private
+     */
+    readonly stateChanges = new Subject<void>();
+
     constructor(public _elementRef: ElementRef,
                 public _defaultErrorStateMatcher: ErrorStateMatcher,
                 public _parentForm: NgForm,
                 public _parentFormGroup: FormGroupDirective,
+                /**
+                 * Form control bound to the component.
+                 * Implemented as part of `MatFormFieldControl`.
+                 * @docs-private
+                 */
                 public ngControl: NgControl) {}
   }))));
 

tools/public_api_guard/material/core.md

@@ -84,7 +84,6 @@ export type CanDisableRippleCtor = Constructor<CanDisableRipple> & AbstractConst
 export interface CanUpdateErrorState {
     errorState: boolean;
     errorStateMatcher: ErrorStateMatcher;
-    readonly stateChanges: Subject<void>;
     updateErrorState(): void;
 }