docs(autocomplete): add docs and example for autoActiveFirstOption (a…

…ngular#9735)

Adds some documentation and a live example for the `MatAutocomplete.autoActiveFirstOption` property.

src/lib/autocomplete/autocomplete.md

@@ -82,6 +82,15 @@ desired display value. Then bind it to the autocomplete's `displayWith` property
 
 <!-- example(autocomplete-display) -->
 
+### Automatically highlighting the first option
+
+If your use case requires for the first autocomplete option to be highlighted when the user opens
+the panel, you can do so by setting the `autoActiveFirstOption` input on the `mat-autocomplete`
+component. This behavior can be configured globally using the `MAT_AUTOCOMPLETE_DEFAULT_OPTIONS`
+injection token.
+
+<!-- example(autocomplete-auto-active-first-option) -->
+
 ### Keyboard interaction
 - <kbd>DOWN_ARROW</kbd>: Next option becomes active.
 - <kbd>UP_ARROW</kbd>: Previous option becomes active.

src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.css

@@ -0,0 +1,9 @@
+.example-form {
+  min-width: 150px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.example-full-width {
+  width: 100%;
+}

src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.html

@@ -0,0 +1,10 @@
+<form class="example-form">
+  <mat-form-field class="example-full-width">
+    <input type="text" placeholder="Pick one" aria-label="Number" matInput [formControl]="myControl" [matAutocomplete]="auto">
+    <mat-autocomplete autoActiveFirstOption #auto="matAutocomplete">
+      <mat-option *ngFor="let option of filteredOptions | async" [value]="option">
+        {{ option }}
+      </mat-option>
+    </mat-autocomplete>
+  </mat-form-field>
+</form>

src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.ts

@@ -0,0 +1,31 @@
+import {Component} from '@angular/core';
+import {FormControl} from '@angular/forms';
+import {Observable} from 'rxjs/Observable';
+import {startWith} from 'rxjs/operators/startWith';
+import {map} from 'rxjs/operators/map';
+
+/**
+ * @title Highlight the first autocomplete option
+ */
+@Component({
+  selector: 'autocomplete-auto-active-first-option-example',
+  templateUrl: 'autocomplete-auto-active-first-option-example.html',
+  styleUrls: ['autocomplete-auto-active-first-option-example.css']
+})
+export class AutocompleteAutoActiveFirstOptionExample {
+  myControl: FormControl = new FormControl();
+  options = ['One', 'Two', 'Three'];
+  filteredOptions: Observable<string[]>;
+
+  ngOnInit() {
+    this.filteredOptions = this.myControl.valueChanges.pipe(
+      startWith(''),
+      map(val => this.filter(val))
+    );
+  }
+
+  filter(val: string): string[] {
+    return this.options.filter(option => option.toLowerCase().indexOf(val.toLowerCase()) === 0);
+  }
+
+}