From 4bbc0de9281150beee7e1a2c10710429a2d10fde Mon Sep 17 00:00:00 2001
From: Kara Erickson <karakara@google.com>
Date: Wed, 28 Dec 2016 10:41:29 -0800
Subject: [PATCH 1/2] docs(select): add basic readme and update overview

Closes #2148
---
 src/lib/select/OVERVIEW.md | 43 +++++++++++++++++++++---
 src/lib/select/README.md   | 69 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 105 insertions(+), 7 deletions(-)

diff --git a/src/lib/select/OVERVIEW.md b/src/lib/select/OVERVIEW.md
index 27aee5f25ddd..2487bd8e3dc9 100644
--- a/src/lib/select/OVERVIEW.md
+++ b/src/lib/select/OVERVIEW.md
@@ -1,8 +1,41 @@
 `<md-select>` is a form control for selecting a value from a set of options, similar to the native
-`<select>` element.
+`<select>` element. You can read more about selects in the 
+[Material Design spec](https://material.google.com/components/menus.html).
 
-<!-- example(select-overview) -->
+### Simple select
 
-### Use with `@angular/forms`
-`<md-select>` is compatible with `@angular/forms` and supports both `FormsModule` 
-and `ReactiveFormsModule`.
+In your template, create an `md-select` element. For each option you'd like in your select, add an 
+`md-option` tag. Note that you can disable items by adding the `disabled` boolean attribute or 
+binding to it.
+
+*my-comp.html*
+```html
+<md-select placeholder="State">
+   <md-option *ngFor="let state of states" [value]="state.code">{{ state.name }}</md-option>
+</md-select>
+```
+
+### Getting and setting the select value
+
+The select component is set up as a custom value accessor, so you can manipulate the select's value using 
+any of the form directives from the core `FormsModule` or `ReactiveFormsModule`: `ngModel`, `formControl`, etc.
+
+*my-comp.html*
+```html
+<md-select placeholder="State" [(ngModel)]="myState">
+   <md-option *ngFor="let state of states" [value]="state.code">{{ state.name }}</md-option>
+</md-select>
+```
+
+*my-comp.ts*
+```ts
+class MyComp {
+  myState = 'AZ';
+  states = [{code: 'AL', name: 'Alabama'}...];
+}
+```
+
+#### Keyboard interaction:
+- <kbd>DOWN_ARROW</kbd>: Focus next option
+- <kbd>UP_ARROW</kbd>: Focus previous option
+- <kbd>ENTER</kbd> or <kbd>SPACE</kbd>: Select focused item
diff --git a/src/lib/select/README.md b/src/lib/select/README.md
index 6d192d19b456..f00c2932cbb1 100644
--- a/src/lib/select/README.md
+++ b/src/lib/select/README.md
@@ -1,3 +1,68 @@
-## Work in progress!
+# md-select
 
-The select is still a work in progress, so most features have not been implemented. Not ready for use!
\ No newline at end of file
+`<md-select>` is a form control for selecting a value from a set of options, similar to the native
+`<select>` element. You can read more about selects in the 
+[Material Design spec](https://material.google.com/components/menus.html).
+
+### Not yet implemented
+
+- Multi-select support
+- Option groups
+- Select headers
+
+## Usage
+
+### Simple select
+
+In your template, create an `md-select` element. For each option you'd like in your select, add an 
+`md-option` tag. The value property of each option dictates the value that will be set in the select's 
+form control when that option is selected. What is between the `md-option` tags is what will be 
+visibly displayed in the list. Note that you can disable items by adding the `disabled` boolean 
+attribute or binding to it.
+
+*my-comp.html*
+```html
+<md-select placeholder="State">
+   <md-option *ngFor="let state of states" [value]="state.code">{{ state.name }}</md-option>
+</md-select>
+```
+
+Output:
+
+<img src="https://material.angularjs.org/material2_assets/select/basic-select-closed.png">
+<img src="https://material.angularjs.org/material2_assets/select/basic-select-open.png">
+
+### Getting and setting the select value
+
+The select component is set up as a custom value accessor, so you can manipulate the select's value using 
+any of the form directives from the core `FormsModule` or `ReactiveFormsModule`: `ngModel`, `formControl`, etc.
+
+*my-comp.html*
+```html
+<md-select placeholder="State" [(ngModel)]="myState">
+   <md-option *ngFor="let state of states" [value]="state.code">{{ state.name }}</md-option>
+</md-select>
+```
+
+*my-comp.ts*
+```ts
+class MyComp {
+  myState = 'AZ';
+  states = [{code: 'AL', name: 'Alabama'}...];
+}
+```
+
+Output:
+
+<img src="https://material.angularjs.org/material2_assets/select/value-select-closed.png">
+<img src="https://material.angularjs.org/material2_assets/select/value-select-open.png">
+
+### Accessibility
+
+The select adds role="listbox" to the main select element and role="option" to each option. It also adds the "aria-owns", "aria-disabled",
+"aria-label", "aria-required", and "aria-invalid" attributes as appropriate to the select.
+
+#### Keyboard events:
+- <kbd>DOWN_ARROW</kbd>: Focus next option
+- <kbd>UP_ARROW</kbd>: Focus previous option
+- <kbd>ENTER</kbd> or <kbd>SPACE</kbd>: Select focused item

From 82ba3734334be8cd0a1c9a7d723aed30895faa4d Mon Sep 17 00:00:00 2001
From: Kara Erickson <karakara@google.com>
Date: Wed, 4 Jan 2017 17:18:38 -0800
Subject: [PATCH 2/2] readd example comment

---
 src/lib/select/OVERVIEW.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/lib/select/OVERVIEW.md b/src/lib/select/OVERVIEW.md
index 2487bd8e3dc9..8ff4d404f6b0 100644
--- a/src/lib/select/OVERVIEW.md
+++ b/src/lib/select/OVERVIEW.md
@@ -2,6 +2,8 @@
 `<select>` element. You can read more about selects in the 
 [Material Design spec](https://material.google.com/components/menus.html).
 
+<!-- example(select-overview) -->
+
 ### Simple select
 
 In your template, create an `md-select` element. For each option you'd like in your select, add an