refactor(material/core): deprecate TypeScript mixin functions (#28673)

Marks the TypeScript mixin functions and their related interfaces as deprecated since they are difficult to use and not really necessary now that we have input transforms.

(cherry picked from commit 94306f3)

Author: crisbeto

src/cdk/table/can-stick.ts

@@ -36,6 +36,8 @@ export type CanStickCtor = Constructor<CanStick>;
  * changed since the last time the function was called. Essentially adds a dirty-check to the
  * sticky value.
  * @docs-private
+ * @deprecated Implement the `CanStick` interface instead.
+ * @breaking-change 19.0.0
  */
 export function mixinHasStickyInput<T extends Constructor<{}>>(base: T): CanStickCtor & T {
   return class extends base {

src/material/core/common-behaviors/color.ts

@@ -9,7 +9,11 @@
 import {AbstractConstructor, Constructor} from './constructor';
 import {ElementRef} from '@angular/core';
 
-/** @docs-private */
+/**
+ * @docs-private
+ * @deprecated Will be removed together with `mixinColor`.
+ * @breaking-change 19.0.0
+ */
 export interface CanColor {
   /** Theme color palette for the component. */
   color: ThemePalette;
@@ -21,14 +25,18 @@ export interface CanColor {
 type CanColorCtor = Constructor<CanColor> & AbstractConstructor<CanColor>;
 
 /** @docs-private */
-export interface HasElementRef {
+interface HasElementRef {
   _elementRef: ElementRef;
 }
 
 /** Possible color palette values. */
 export type ThemePalette = 'primary' | 'accent' | 'warn' | undefined;
 
-/** Mixin to augment a directive with a `color` property. */
+/**
+ * Mixin to augment a directive with a `color` property.
+ * @deprecated Use a plain input and host bindings instead.
+ * @breaking-change 19.0.0
+ */
 export function mixinColor<T extends AbstractConstructor<HasElementRef>>(
   base: T,
   defaultColor?: ThemePalette,

src/material/core/common-behaviors/disable-ripple.ts

@@ -9,15 +9,23 @@
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
 import {AbstractConstructor, Constructor} from './constructor';
 
-/** @docs-private */
+/**
+ * @docs-private
+ * @deprecated Will be removed together with `mixinDisableRipple`.
+ * @breaking-change 19.0.0
+ */
 export interface CanDisableRipple {
   /** Whether ripples are disabled. */
   disableRipple: boolean;
 }
 
 type CanDisableRippleCtor = Constructor<CanDisableRipple> & AbstractConstructor<CanDisableRipple>;
 
-/** Mixin to augment a directive with a `disableRipple` property. */
+/**
+ * Mixin to augment a directive with a `disableRipple` property.
+ * @deprecated Use an input with a transform instead.
+ * @breaking-change 19.0.0
+ */
 export function mixinDisableRipple<T extends AbstractConstructor<{}>>(
   base: T,
 ): CanDisableRippleCtor & T;

src/material/core/common-behaviors/disabled.ts

@@ -9,15 +9,23 @@
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
 import {AbstractConstructor, Constructor} from './constructor';
 
-/** @docs-private */
+/**
+ * @docs-private
+ * @deprecated Will be removed together with `mixinDisabled`.
+ * @breaking-change 19.0.0
+ */
 export interface CanDisable {
   /** Whether the component is disabled. */
   disabled: boolean;
 }
 
 type CanDisableCtor = Constructor<CanDisable> & AbstractConstructor<CanDisable>;
 
-/** Mixin to augment a directive with a `disabled` property. */
+/**
+ * Mixin to augment a directive with a `disabled` property.
+ * @deprecated Use an input with a transform instead.
+ * @breaking-change 19.0.0
+ */
 export function mixinDisabled<T extends AbstractConstructor<{}>>(base: T): CanDisableCtor & T;
 export function mixinDisabled<T extends Constructor<{}>>(base: T): CanDisableCtor & T {
   return class extends base {

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

@@ -14,7 +14,11 @@ import {AbstractConstructor, Constructor} from './constructor';
 // Declare ErrorStateMatcher as an interface to have compatibility with Closure Compiler.
 interface ErrorStateMatcher extends _ErrorStateMatcher {}
 
-/** @docs-private */
+/**
+ * @docs-private
+ * @deprecated Will be removed together with `mixinErrorState`.
+ * @breaking-change 19.0.0
+ */
 export interface CanUpdateErrorState {
   /** Updates the error state based on the provided error state matcher. */
   updateErrorState(): void;
@@ -28,7 +32,7 @@ type CanUpdateErrorStateCtor = Constructor<CanUpdateErrorState> &
   AbstractConstructor<CanUpdateErrorState>;
 
 /** @docs-private */
-export interface HasErrorState {
+interface HasErrorState {
   _parentFormGroup: FormGroupDirective;
   _parentForm: NgForm;
   _defaultErrorStateMatcher: ErrorStateMatcher;
@@ -77,6 +81,8 @@ export class _ErrorStateTracker {
 /**
  * Mixin to augment a directive with updateErrorState method.
  * For component with `errorState` and need to update `errorState`.
+ * @deprecated Implement the `updateErrorState` method directly.
+ * @breaking-change 19.0.0
  */
 export function mixinErrorState<T extends AbstractConstructor<HasErrorState>>(
   base: T,

src/material/core/common-behaviors/initialized.ts

@@ -15,6 +15,8 @@ import {Constructor} from './constructor';
  * If the subscription is made after it has already been marked as initialized, then it will trigger
  * an emit immediately.
  * @docs-private
+ * @deprecated Will be removed together with `mixinInitializer`.
+ * @breaking-change 19.0.0
  */
 export interface HasInitialized {
   /** Stream that emits once during the directive/component's ngOnInit. */
@@ -30,7 +32,11 @@ export interface HasInitialized {
 
 type HasInitializedCtor = Constructor<HasInitialized>;
 
-/** Mixin to augment a directive with an initialized property that will emits when ngOnInit ends. */
+/**
+ * Mixin to augment a directive with an initialized property that will emits when ngOnInit ends.
+ * @deprecated Track the initialized state manually.
+ * @breaking-change 19.0.0
+ */
 export function mixinInitialized<T extends Constructor<{}>>(base: T): HasInitializedCtor & T {
   return class extends base {
     /** Whether this directive has been marked as initialized. */

src/material/core/common-behaviors/tabindex.ts

@@ -10,7 +10,11 @@ import {coerceNumberProperty} from '@angular/cdk/coercion';
 import {Constructor, AbstractConstructor} from './constructor';
 import {CanDisable} from './disabled';
 
-/** @docs-private */
+/**
+ * @docs-private
+ * @deprecated Will be removed together with `mixinTabIndex`.
+ * @breaking-change 19.0.0
+ */
 export interface HasTabIndex {
   /** Tabindex of the component. */
   tabIndex: number;
@@ -21,7 +25,11 @@ export interface HasTabIndex {
 
 type HasTabIndexCtor = Constructor<HasTabIndex> & AbstractConstructor<HasTabIndex>;
 
-/** Mixin to augment a directive with a `tabIndex` property. */
+/**
+ * Mixin to augment a directive with a `tabIndex` property.
+ * @deprecated Use an input with a transform instead.
+ * @breaking-change 19.0.0
+ */
 export function mixinTabIndex<T extends AbstractConstructor<CanDisable>>(
   base: T,
   defaultTabIndex?: number,

tools/public_api_guard/cdk/table.md

@@ -496,7 +496,7 @@ export class HeaderRowOutlet implements RowOutlet {
     static ɵfac: i0.ɵɵFactoryDeclaration<HeaderRowOutlet, never>;
 }
 
-// @public
+// @public @deprecated
 export function mixinHasStickyInput<T extends Constructor<{}>>(base: T): CanStickCtor & T;
 
 // @public

tools/public_api_guard/material/core.md

@@ -53,23 +53,23 @@ export class AnimationDurations {
     static EXITING: string;
 }
 
-// @public
+// @public @deprecated
 export interface CanColor {
     color: ThemePalette;
     defaultColor: ThemePalette | undefined;
 }
 
-// @public
+// @public @deprecated
 export interface CanDisable {
     disabled: boolean;
 }
 
-// @public
+// @public @deprecated
 export interface CanDisableRipple {
     disableRipple: boolean;
 }
 
-// @public
+// @public @deprecated
 export interface CanUpdateErrorState {
     errorState: boolean;
     errorStateMatcher: ErrorStateMatcher_2;
@@ -157,13 +157,13 @@ export interface GranularSanityChecks {
     version: boolean;
 }
 
-// @public
+// @public @deprecated
 export interface HasInitialized {
     initialized: Observable<void>;
     _markInitialized: () => void;
 }
 
-// @public
+// @public @deprecated
 export interface HasTabIndex {
     defaultTabIndex: number;
     tabIndex: number;
@@ -431,22 +431,22 @@ export class MatRippleModule {
     static ɵmod: i0.ɵɵNgModuleDeclaration<MatRippleModule, never, [typeof i1_2.MatCommonModule, typeof i2.MatRipple], [typeof i2.MatRipple, typeof i1_2.MatCommonModule]>;
 }
 
-// @public
+// @public @deprecated
 export function mixinColor<T extends _AbstractConstructor<HasElementRef>>(base: T, defaultColor?: ThemePalette): CanColorCtor & T;
 
-// @public
+// @public @deprecated
 export function mixinDisabled<T extends _AbstractConstructor<{}>>(base: T): CanDisableCtor & T;
 
-// @public
+// @public @deprecated
 export function mixinDisableRipple<T extends _AbstractConstructor<{}>>(base: T): CanDisableRippleCtor & T;
 
-// @public
+// @public @deprecated
 export function mixinErrorState<T extends _AbstractConstructor<HasErrorState>>(base: T): CanUpdateErrorStateCtor & T;
 
-// @public
+// @public @deprecated
 export function mixinInitialized<T extends _Constructor<{}>>(base: T): HasInitializedCtor & T;
 
-// @public
+// @public @deprecated
 export function mixinTabIndex<T extends _AbstractConstructor<CanDisable>>(base: T, defaultTabIndex?: number): HasTabIndexCtor & T;
 
 // @public