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.

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