refactor(material): deprecate MAT_LABEL_GLOBAL_OPTIONS in favo… (#18017)

As of Angular Material version 9, the `MAT_LABEL_GLOBAL_OPTIONS`
injection token is deprecated. The default floating label behavior
should be set through the `MAT_FORM_FIELD_DEFAULT_OPTIONS` token.

DEPRECATED: `MAT_LABEL_GLOBAL_OPTIONS` exported in
`@angular/material/core` is deprecated. Use `MAT_FORM_FIELD_DEFAULT_OPTIONS`
from `@angular/material/form-field`. Note that the property `float` is
now matching the input name `floatLabel`.

DEPRECATED: `FloatLabelType` exported in `@angular/material/core` is
deprecated. Import the symbol from `@angular/material/from-field`.

src/material/core/label/label-options.ts

@@ -8,14 +8,27 @@
 
 import {InjectionToken} from '@angular/core';
 
-/** InjectionToken that can be used to specify the global label options. */
+/**
+ * InjectionToken that can be used to specify the global label options.
+ * @deprecated Use `MAT_FORM_FIELD_DEFAULT_OPTIONS` injection token from
+ *     `@angular/material/form-field` instead.
+ * @breaking-change 11.0.0
+ */
 export const MAT_LABEL_GLOBAL_OPTIONS =
   new InjectionToken<LabelOptions>('mat-label-global-options');
 
-/** Type for the available floatLabel values. */
+/**
+ * Type for the available floatLabel values.
+ * @deprecated Use `FloatLabelType` from `@angular/material/form-field` instead.
+ * @breaking-change 11.0.0
+ */
 export type FloatLabelType = 'always' | 'never' | 'auto';
 
-/** Configurable options for floating labels. */
+/**
+ * Configurable options for floating labels.
+ * @deprecated Use `MatFormFieldDefaultOptions` from `@angular/material/form-field` instead.
+ * @breaking-change 11.0.0
+ */
 export interface LabelOptions {
   /**
    * Whether the label should float `always`, `never`, or `auto` (only when necessary).

src/material/form-field/form-field.ts

@@ -30,7 +30,6 @@ import {
 } from '@angular/core';
 import {
   CanColor, CanColorCtor,
-  FloatLabelType,
   LabelOptions,
   MAT_LABEL_GLOBAL_OPTIONS,
   mixinColor,
@@ -83,13 +82,21 @@ const _MatFormFieldMixinBase: CanColorCtor & typeof MatFormFieldBase =
  */
 export type MatFormFieldAppearance = 'legacy' | 'standard' | 'fill' | 'outline';
 
+/** Possible values for the "floatLabel" form-field input. */
+export type FloatLabelType = 'always' | 'never' | 'auto';
+
 /**
  * Represents the default options for the form field that can be configured
  * using the `MAT_FORM_FIELD_DEFAULT_OPTIONS` injection token.
  */
 export interface MatFormFieldDefaultOptions {
   appearance?: MatFormFieldAppearance;
   hideRequiredMarker?: boolean;
+  /**
+   * Whether the label for form-fields should by default float `always`,
+   * `never`, or `auto` (only when necessary).
+   */
+  floatLabel?: FloatLabelType;
 }
 
 /**
@@ -227,7 +234,7 @@ export class MatFormField extends _MatFormFieldMixinBase
   }
   set floatLabel(value: FloatLabelType) {
     if (value !== this._floatLabel) {
-      this._floatLabel = value || this._labelOptions.float || 'auto';
+      this._floatLabel = value || this._getDefaultFloatLabelState();
       this._changeDetectorRef.markForCheck();
     }
   }
@@ -280,7 +287,7 @@ export class MatFormField extends _MatFormFieldMixinBase
     super(_elementRef);
 
     this._labelOptions = labelOptions ? labelOptions : {};
-    this.floatLabel = this._labelOptions.float || 'auto';
+    this.floatLabel = this._getDefaultFloatLabelState();
     this._animationsEnabled = _animationMode !== 'NoopAnimations';
 
     // Set the default through here so we invoke the setter on the first run.
@@ -473,6 +480,11 @@ export class MatFormField extends _MatFormFieldMixinBase
     }
   }
 
+  /** Gets the default float label state. */
+  private _getDefaultFloatLabelState(): FloatLabelType {
+    return (this._defaults && this._defaults.floatLabel) || this._labelOptions.float || 'auto';
+  }
+
   /**
    * Sets the list of element IDs that describe the child control. This allows the control to update
    * its `aria-describedby` attribute accordingly.

src/material/input/input.spec.ts

@@ -61,7 +61,7 @@ describe('MatInput without forms', () => {
         'Expected MatInput to set floatingLabel to auto by default.');
   }));
 
-  it('should default to global floating label type', fakeAsync(() => {
+  it('should default to floating label type from deprecated global label options', fakeAsync(() => {
     let fixture = createComponent(MatInputWithId, [{
       provide: MAT_LABEL_GLOBAL_OPTIONS, useValue: {float: 'always'}
     }]);
@@ -73,6 +73,18 @@ describe('MatInput without forms', () => {
       'Expected MatInput to set floatingLabel to always from global option.');
   }));
 
+  it('should default to floating label type provided by global default options', fakeAsync(() => {
+    let fixture = createComponent(MatInputWithId, [{
+      provide: MAT_FORM_FIELD_DEFAULT_OPTIONS, useValue: {floatLabel: 'always'}
+    }]);
+    fixture.detectChanges();
+
+    let formField = fixture.debugElement.query(By.directive(MatFormField))!
+      .componentInstance as MatFormField;
+    expect(formField.floatLabel).toBe('always',
+      'Expected MatInput to set floatingLabel to always from global option.');
+  }));
+
   it('should not be treated as empty if type is date', fakeAsync(() => {
     const platform = new Platform();
 

tools/public_api_guard/material/form-field.d.ts

@@ -1,3 +1,5 @@
+export declare type FloatLabelType = 'always' | 'never' | 'auto';
+
 export declare function getMatFormFieldDuplicatedHintError(align: string): Error;
 
 export declare function getMatFormFieldMissingControlError(): Error;
@@ -88,6 +90,7 @@ export declare abstract class MatFormFieldControl<T> {
 
 export interface MatFormFieldDefaultOptions {
     appearance?: MatFormFieldAppearance;
+    floatLabel?: FloatLabelType;
     hideRequiredMarker?: boolean;
 }