docs(form-field): update documentation regarding label and placeholder (#11037)

* docs(form-field): update documentation regarding label and placeholder

* address comments

Author: mmalerba

src/lib/form-field/form-field.html

@@ -22,13 +22,15 @@
                *ngIf="_hasFloatingLabel()"
                [ngSwitch]="_hasLabel()">
 
+          <!-- @deletion-target 8.0.0 remove in favor of mat-label element an placeholder attr. -->
           <ng-container *ngSwitchCase="false">
             <ng-content select="mat-placeholder"></ng-content>
             {{_control.placeholder}}
           </ng-container>
 
           <ng-content select="mat-label" *ngSwitchCase="true"></ng-content>
 
+          <!-- @deletion-target 8.0.0 remove `mat-placeholder-required` class -->
           <span
             class="mat-placeholder-required mat-form-field-required-marker"
             aria-hidden="true"

src/lib/form-field/form-field.md

@@ -42,15 +42,22 @@ want a floating label, add a `<mat-label>` to the `mat-form-filed`.
 
 The floating label is a text label displayed on top of the form field control when
 the control does not contain any text. By default, when text is present the floating label
-floats above the form field control. The label for a form field can be defined either through a
-`mat-label` element, by setting the `placeholder` attribute on the form control or using the
-`mat-placeholder` element. If there are multiple clashing values (e.g. a `placeholder` and a
-label) the `mat-label` will take precedence and the `placeholder` will be shown only when there is
-no value.
-
-Placeholder text can be specified using the `placeholder` property on the form field control, or
-by adding a `<mat-placeholder>` element inside the form field. Only one of these options should be
-used, specifying both will raise an error.
+floats above the form field control. The label for a form field can be specified by adding a
+`mat-label` element.
+ 
+In the legacy version of the `<mat-form-field>` (one that has no `appearance` attribute or has
+`appearance="legacy"`) if a label is not specified, the `placeholder` attribute on the form control
+is promoted to a label. If a label is specified, the `placeholder` will be displayed as a normal
+placeholder. The `placeholder` will never be promoted to a label for `standard`, `fill`, and
+`outline` form fields. If you want to create a legacy form field with a placeholder but no label,
+you will need to specify an empty label to prevent the `placeholder` from being promoted.
+
+```html
+<mat-form-field>
+  <mat-label></mat-label>
+  <input placeholder="Just a placeholder">
+</mat-form-field>
+```
 
 If the form field control is marked with a `required` attribute, an asterisk will be appended to the
 label to indicate the fact that it is a required field. If unwanted, this can be disabled by
@@ -154,7 +161,8 @@ Any errors and hints added to the form field are automatically added to the form
 
 This error occurs when you have specified two conflicting placeholders. Make sure that you haven't
 included both a `placeholder` property on your form field control and a `<mat-placeholder>`
-element.
+element. The `<mat-placeholder>` element is deprecated, you should use `placeholder` for
+placeholders and `<mat-label>` for labels.
 
 #### Error: A hint was already declared for align="..."
 

src/lib/form-field/placeholder.ts

@@ -9,7 +9,12 @@
 import {Directive} from '@angular/core';
 
 
-/** The placeholder text for an `MatFormField`. */
+/**
+ * The placeholder text for an `MatFormField`.
+ * @deprecated Use `<mat-label>` to specify the label and the `placeholder` attribute to specify the
+ *     placeholder.
+ * @deletion-target 8.0.0
+ */
 @Directive({
   selector: 'mat-placeholder'
 })

src/lib/input/input.md

@@ -9,9 +9,8 @@ All of the attributes that can be used with normal `<input>` and `<textarea>` el
 on elements inside `<mat-form-field>` as well. This includes Angular directives such as `ngModel`
 and `formControl`.
 
-The only limitations are that the `type` attribute can only be one of the values supported by
-`matInput` and the native element cannot specify a `placeholder` attribute if the `<mat-form-field>`
-also contains an `<mat-placeholder>` element.
+The only limitation is that the `type` attribute can only be one of the values supported by
+`matInput`.
 
 ### Supported `<input>` types
 
@@ -40,12 +39,11 @@ additional information about these features, see the
 
 ### Placeholder
 
-A placeholder is a text label displayed in the input area when the input does not contain text.
-When text is present, the placeholder will float above the input area. The placeholder can be
-specified either via a `placeholder` attribute on the input or a `<mat-placeholder>` element in the
-same form field as the `matInput`. The `<mat-form-field>` also has additional options for changing
-the behavior of the placeholder. For more information see the
-[form field placeholder documentation](https://material.angular.io/components/form-field/overview#floating-placeholder).
+The placeholder is text shown when the `<mat-form-field>` label is floating but the input is empty.
+It is used to give the user an additional hint about what they should type in the input. The
+placeholder can be specified by setting the `placeholder` attribute on the `<input>` or `<textarea>`
+element. In some cases that `<mat-form-field>` may use the placeholder as the label (see the
+[form field label documentation](https://material.angular.io/components/form-field/overview#floating-label)).
 
 ### Changing when error messages are shown
 
@@ -90,10 +88,9 @@ for detecting when an input becomes autofilled and changing the appearance of th
 
 The `matInput` directive works with native `<input>` to provide an accessible experience.
 
-If a placeholder attribute is added to the input, or a `mat-placeholder` element is added
-in the form field, the placeholder text will automatically be used as the label for the input.
-If there's no placeholder specified, `aria-label`, `aria-labelledby` or `<label for=...>` should be
-added.
+If the containing `<mat-form-field>` has a label it will automatically be used as the `aria-label`
+for the `<input>`. However, if there's no label specified in the form field, `aria-label`,
+`aria-labelledby` or `<label for=...>` should be added.
 
 Any `mat-error` and `mat-hint` are automatically added to the input's `aria-describedby` list, and
 `aria-invalid` is automatically updated based on the input's validity state.

src/lib/select/select.md

@@ -36,12 +36,11 @@ these features, see the
 
 ### Setting a static placeholder
 
-The placeholder is a text label displayed in the select trigger area when no value is selected. When
-a value is selected, the placeholder will float above the select trigger area. The placeholder can
-be specified either via a `placeholder` attribute on the `<mat-select>` or a `<mat-placeholder>`
-element in the same form field as the `<mat-select>`. The `<mat-form-field>` also has additional
-options for changing the behavior of the placeholder. For more information see the
-[form field placeholder documentation](https://material.angular.io/components/form-field/overview#floating-placeholder).
+The placeholder is text shown when the `<mat-form-field>` label is floating but the `<mat-select>`
+is empty. It is used to give the user an additional hint about the value they should select. The
+placeholder can be specified by setting the `placeholder` attribute on the `<mat-select>` element.
+In some cases that `<mat-form-field>` may use the placeholder as the label (see the
+[form field label documentation](https://material.angular.io/components/form-field/overview#floating-label)).
 
 ### Disabling the select or individual options
 

src/material-examples/form-field-label/form-field-label-example.html

@@ -29,6 +29,6 @@
       <mat-option>-- None --</mat-option>
       <mat-option value="option">Option</mat-option>
     </mat-select>
-    <mat-placeholder><mat-icon>favorite</mat-icon> <b> Fancy</b> <i> placeholder</i></mat-placeholder>
+    <mat-label><mat-icon>favorite</mat-icon> <b> Fancy</b> <i> label</i></mat-label>
   </mat-form-field>
 </div>