Add CDK text-field docs (#10536)

Author: mmalerba

src/cdk/text-field/autofill.ts

@@ -12,10 +12,10 @@ import {
   ElementRef,
   EventEmitter,
   Injectable,
+  NgZone,
   OnDestroy,
   OnInit,
   Output,
-  NgZone,
 } from '@angular/core';
 import {Observable, Subject} from 'rxjs';
 import {empty as observableEmpty} from 'rxjs';
@@ -46,7 +46,7 @@ const listenerOptions: any = supportsPassiveEventListeners() ? {passive: true} :
  * Based on the following blog post:
  * https://medium.com/@brunn/detecting-autofilled-fields-in-javascript-aed598d25da7
  */
-@Injectable()
+@Injectable({providedIn: 'root'})
 export class AutofillMonitor implements OnDestroy {
   private _monitoredElements = new Map<Element, MonitoredElementInfo>();
 

src/cdk/text-field/text-field-module.ts

@@ -8,14 +8,13 @@
 
 import {PlatformModule} from '@angular/cdk/platform';
 import {NgModule} from '@angular/core';
-import {AutofillMonitor, CdkAutofill} from './autofill';
+import {CdkAutofill} from './autofill';
 import {CdkTextareaAutosize} from './autosize';
 
 
 @NgModule({
   declarations: [CdkAutofill, CdkTextareaAutosize],
   imports: [PlatformModule],
   exports: [CdkAutofill, CdkTextareaAutosize],
-  providers: [AutofillMonitor],
 })
 export class TextFieldModule {}

src/cdk/text-field/text-field.md

@@ -0,0 +1,57 @@
+The `text-field` package provides useful utilities for working with text input fields such as
+`<input>` and `<textarea>`.
+
+## Automatically resizing a `<textarea>`
+
+The `cdkTextareaAutosize` directive can be applied to any `<textarea>` to make it automatically
+resize to fit its content. The minimum and maximum number of rows to expand to can be set via the
+`cdkAutosizeMinRows` and `cdkAutosizeMaxRows` properties respectively.
+
+The resize logic can be triggered programmatically by calling `resizeToFitContent`. This method
+takes an optional boolean parameter `force` that defaults to `false`. Passing true will force the
+`<textarea>` to resize even if its text content has not changed, this can be useful if the styles
+affecting the `<textarea>` have changed.
+
+<!-- example(text-field-autosize-textarea) -->
+
+## Monitoring the autofill state of an `<input>`
+
+The `AutofillMonitor` is an injectable service that allows the user to monitor the autofill state of
+an `<input>`. It has a `monitor` method that takes an element to monitor and returns an
+`Observable` of autofill event objects with a `target` and `isAutofilled` property. The observable
+emits every time the autofill state of the given `<input>` changes. Any element you monitor should
+eventually be unmonitored by calling `stopMonitoring` with the same element.
+
+<!-- example(text-field-autofill-monitor) -->
+
+To simplify this process, there is also a `cdkAutofill` directive that automatically handles
+monitoring and unmonitoring and doubles as an `@Output` binding that emits when the autofill state
+changes.
+
+<!-- example(text-field-autofill-directive) -->
+
+Note: This service requires some CSS to install animation hooks when the autofill statechanges. If
+you are using Angular Material, this CSS is included as part of the `mat-core` mixin. If you are not
+using Angular Material, you should include this CSS with the `cdk-text-field` mixin.
+
+```scss
+@import '~@angular/cdk/text-field/text-field'; 
+
+@include cdk-text-field();
+```
+
+## Styling the autofill state of an `<input>`
+
+It can be difficult to override the browser default `background` and `color` properties on an
+autofilled `<input>`. To make this simpler, the CDK includes a mixin `cdk-text-field-autofill-color`
+which can be used to set these properties. It takes a `background` value as the first parameter and
+an optional `color` value as the second parameter.
+
+```scss
+@import '~@angular/cdk/text-field/text-field'; 
+
+// Set custom-autofill inputs to have no background and red text.
+input.custom-autofill {
+  @include cdk-text-field-autofill-color(transparent, red);
+}
+```

src/lib/input/input.md

@@ -76,12 +76,15 @@ globally cause input errors to show when the input is dirty and invalid.
 
 ### Auto-resizing `<textarea>` elements
 
-`<textarea>` elements can be made to automatically resize to fit their contents by applying the
-`cdkTextareaAutosize` directive. This works with `<textarea matInput>` elements as well as plain
-native `<textarea>` elements. The min and max size of the textarea can be specified in rows, using
-the `cdkAutosizeMinRows` and `cdkAutosizeMaxRows` properties respectively.
+`<textarea>` elements can be made to automatically resize by using the
+[`cdkAutosizeTextarea` directive](https://material.angular.io/cdk/text-field/overview#automatically-resizing-a-textarea)
+available in the CDK.
 
-<!-- example(input-autosize-textarea) -->
+### Responding to changes in the autofill state of an `<input>`
+
+The CDK provides
+[utilities](https://material.angular.io/cdk/text-field/overview#monitoring-the-autofill-state-of-an-input)
+for detecting when an input becomes autofilled and changing the appearance of the autofilled state.
 
 ### Accessibility
 

src/material-examples/input-autosize-textarea/input-autosize-textarea-example.html

@@ -0,0 +1,13 @@
+<form>
+  <mat-form-field>
+    <mat-label>First name</mat-label>
+    <input matInput (cdkAutofill)="firstNameAutofilled = $event.isAutofilled">
+    <mat-hint *ngIf="firstNameAutofilled">Autofilled!</mat-hint>
+  </mat-form-field>
+  <mat-form-field>
+    <mat-label>Last name</mat-label>
+    <input matInput (cdkAutofill)="lastNameAutofilled = $event.isAutofilled">
+    <mat-hint *ngIf="lastNameAutofilled">Autofilled!</mat-hint>
+  </mat-form-field>
+  <button mat-raised-button>Submit</button>
+</form>

src/material-examples/input-autosize-textarea/input-autosize-textarea-example.ts

@@ -0,0 +1,12 @@
+import {Component} from '@angular/core';
+
+/** @title Monitoring autofill state with cdkAutofill */
+@Component({
+  selector: 'text-field-autofill-directive-example',
+  templateUrl: './text-field-autofill-directive-example.html',
+  styleUrls: ['./text-field-autofill-directive-example.css'],
+})
+export class TextFieldAutofillDirectiveExample {
+  firstNameAutofilled: boolean;
+  lastNameAutofilled: boolean;
+}

src/material-examples/input-autosize-textarea/input-autosize-textarea-example.css renamed to src/material-examples/text-field-autofill-directive/text-field-autofill-directive-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */