docs(autocomplete): Adds option group example (#10666)

* docs(autocomplete): Adds option group example

Adds a option group example which displays ideal logic and best
practices for the material autocomplete component.

* docs(autocomplete): Fixes option group example

Changes code style and logic to expected logic and styleguide

Author: raygervais

src/lib/autocomplete/autocomplete.md

@@ -98,6 +98,8 @@ injection token.
 
 ### Option groups
 `mat-option` can be collected into groups using the `mat-optgroup` element:
+<!-- example(autocomplete-optgroup) -->
+
 
 ```html
 <mat-autocomplete #auto="matAutocomplete">

src/material-examples/autocomplete-optgroup/autocomplete-optgroup-example.css

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

src/material-examples/autocomplete-optgroup/autocomplete-optgroup-example.html

@@ -0,0 +1,12 @@
+<form [formGroup]="stateForm">
+  <mat-form-field>
+    <input type="text" matInput placeholder="States Group" formControlName="stateGroup" required [matAutocomplete]="autoGroup"/>
+      <mat-autocomplete #autoGroup="matAutocomplete">
+        <mat-optgroup *ngFor="let group of stateGroupOptions | async" [label]="group.letter">
+          <mat-option *ngFor="let name of group.names" [value]="name">
+            {{ name }}
+          </mat-option>
+      </mat-optgroup>
+    </mat-autocomplete>
+  </mat-form-field> 
+</form>  

src/material-examples/autocomplete-optgroup/autocomplete-optgroup-example.ts

@@ -0,0 +1,111 @@
+import {Component, OnInit} from '@angular/core';
+import {FormGroup, FormBuilder} from '@angular/forms';
+import {Observable} from 'rxjs';
+import {startWith, map} from 'rxjs/operators';
+
+export interface StateGroup {
+  letter: string;
+  names: string[];
+}
+
+/**
+ * @title Option groups autocomplete
+ */
+@Component({
+  templateUrl: './autocomplete-optgroup-example.html',
+  styleUrls: ['./autocomplete-optgroup-example.css'],
+})
+
+export class AutocompleteOptionGroupExample implements OnInit {
+  stateForm: FormGroup = this.fb.group({
+    stateGroup: '',
+  });
+
+  stateGroups: StateGroup[] = [{
+    letter: 'A',
+    names: ['Alabama', 'Alaska', 'Arizona', 'Arkansas']
+  }, {
+    letter: 'C',
+    names: ['California', 'Colorado', 'Connecticut']
+  }, {
+    letter: 'D',
+    names: ['Delaware']
+  }, {
+    letter: 'F',
+    names: ['Florida']
+  }, {
+    letter: 'G',
+    names: ['Georgia']
+  }, {
+    letter: 'H',
+    names: ['Hawaii']
+  }, {
+    letter: 'I',
+    names: ['Idaho', 'Illinois', 'Indiana', 'Iowa']
+  }, {
+    letter: 'K',
+    names: ['Kansas', 'Kentucky']
+  }, {
+    letter: 'L',
+    names: ['Louisiana']
+  }, {
+    letter: 'M',
+    names: ['Maine', 'Maryland', 'Massachusetts', 'Michigan',
+      'Minnesota', 'Mississippi', 'Missouri', 'Montana']
+  }, {
+    letter: 'N',
+    names: ['Nebraska', 'Nevada', 'New Hampshire', 'New Jersey',
+      'New Mexico', 'New York', 'North Carolina', 'North Dakota']
+  }, {
+    letter: 'O',
+    names: ['Ohio', 'Oklahoma', 'Oregon']
+  }, {
+    letter: 'P',
+    names: ['Pennsylvania']
+  }, {
+    letter: 'R',
+    names: ['Rhode Island']
+  }, {
+    letter: 'S',
+    names: ['South Carolina', 'South Dakota']
+  }, {
+    letter: 'T',
+    names: ['Tennessee', 'Texas']
+  }, {
+    letter: 'U',
+    names: ['Utah']
+  }, {
+    letter: 'V',
+    names: ['Vermont', 'Virginia']
+  }, {
+    letter: 'W',
+    names: ['Washington', 'West Virginia', 'Wisconsin', 'Wyoming']
+  }];
+
+  stateGroupOptions: Observable<StateGroup[]>;
+
+  constructor(private fb: FormBuilder) { }
+
+  ngOnInit() {
+    this.stateGroupOptions = this.stateForm.get('stateGroup')!.valueChanges
+      .pipe(
+        startWith(''),
+        map(val => this.filterGroup(val))
+      );
+  }
+
+  filterGroup(val: string): StateGroup[] {
+    if (val) {
+      return this.stateGroups
+        .map(group => ({ letter: group.letter, names: this._filter(group.names, val) }))
+        .filter(group => group.names.length > 0);
+    }
+
+    return this.stateGroups;
+  }
+
+  private _filter(opt: string[], val: string) {
+    const filterValue = val.toLowerCase();
+    return opt.filter(item => item.toLowerCase().startsWith(filterValue));
+  }
+}