From ff0cc7ad7950deee8d255ba47a4ebc73f13064fa Mon Sep 17 00:00:00 2001
From: mmalerba <mmalerba@google.com>
Date: Fri, 27 Apr 2018 18:44:34 -0700
Subject: [PATCH] docs(form-field): update documentation regarding label and
 placeholder (#11037)

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

* address comments
---
 src/lib/form-field/form-field.html            |  2 ++
 src/lib/form-field/form-field.md              | 28 ++++++++++++-------
 src/lib/form-field/placeholder.ts             |  7 ++++-
 src/lib/input/input.md                        | 23 +++++++--------
 src/lib/select/select.md                      | 11 ++++----
 .../form-field-label-example.html             |  2 +-
 6 files changed, 42 insertions(+), 31 deletions(-)

diff --git a/src/lib/form-field/form-field.html b/src/lib/form-field/form-field.html
index 4f6adc89a6a9..13254c0732ef 100644
--- a/src/lib/form-field/form-field.html
+++ b/src/lib/form-field/form-field.html
@@ -22,6 +22,7 @@
                *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}}
@@ -29,6 +30,7 @@
 
           <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"
diff --git a/src/lib/form-field/form-field.md b/src/lib/form-field/form-field.md
index 0bedd24cb09e..5ac95b11581c 100644
--- a/src/lib/form-field/form-field.md
+++ b/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="..."
 
diff --git a/src/lib/form-field/placeholder.ts b/src/lib/form-field/placeholder.ts
index 8c4e6f6cfff5..1c96bd008801 100644
--- a/src/lib/form-field/placeholder.ts
+++ b/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'
 })
diff --git a/src/lib/input/input.md b/src/lib/input/input.md
index 4a77e4b686b5..07d1eb1b6d48 100644
--- a/src/lib/input/input.md
+++ b/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.
diff --git a/src/lib/select/select.md b/src/lib/select/select.md
index c2dd1c9db307..bf2ce7070d98 100644
--- a/src/lib/select/select.md
+++ b/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
 
diff --git a/src/material-examples/form-field-label/form-field-label-example.html b/src/material-examples/form-field-label/form-field-label-example.html
index 0f7066bbbf0a..4d0b41243456 100644
--- a/src/material-examples/form-field-label/form-field-label-example.html
+++ b/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>