docs: add remaining component overviews (#2338)

* snackbar overview

* menu overview

* list overview

* slide-toggle

* sidenav overview

* progress overview

* radio overview

* toolbar overview

* slider overview

* select overview

* nav-tabs

* chips

* consistency

* input edits

* fix typo in radio

* correct radio overview example name

* mention hammer, fix typos

Author: jelbourn

src/demo-app/chips/chips-demo.html

@@ -62,4 +62,4 @@ <h4>Stacked Chips</h4>
       </md-chip-list>
     </md-card-content>
   </md-card>
-</div>
+</div>

src/lib/button-toggle/OVERVIEW.md

@@ -1,6 +1,6 @@
-Button-toggles are on/off toggles with the appearance of a button. These toggles can be configured
-to behave as either radio-buttons or checkboxes. While they can be standalone, they are typically 
-part of a `md-button-toggle-group`.
+`<md-button-toggle>` are on/off toggles with the appearance of a button. These toggles can be 
+configured to behave as either radio-buttons or checkboxes. While they can be standalone, they are 
+typically part of a `md-button-toggle-group`.
 
 
 <!-- example(button-toggle-overview) -->

src/lib/card/OVERVIEW.md

@@ -1,4 +1,4 @@
-Cards are content containers for text, photos, and actions. Cards are intended to provide 
+`<md-card>` is a content container for text, photos, and actions. Cards are intended to provide 
 information on a single subject.
 
 <!-- example(card-overview) -->

src/lib/checkbox/OVERVIEW.md

@@ -1,5 +1,5 @@
 `<md-checkbox>` provides the same functionality as a native `<input type="checkbox">`
-enhanced Material Design styling and animations.
+enhanced with Material Design styling and animations.
 
 <!-- example(checkbox-overview) -->
 

src/lib/chips/OVERVIEW.md

@@ -0,0 +1,30 @@
+`<md-chip-list>` displays a list of values as individual chips.
+
+<!-- example(chips-overview) -->
+
+_Note: chips are still early in their development and more features are being actively worked on._
+
+```html
+<md-chip-list>
+  <md-chip>Papadum</md-chip>
+  <md-chip>Naan</md-chip>
+  <md-chip>Dal</md-chip>
+</md-chip-list>
+```
+
+### Unstyled chips
+By default, `<md-chip>` has Material Design styles applied. For a chip with no styles applied,
+use `<md-basic-chip>`. You can then customize the chip appearance by adding your own CSS.
+
+### Selection
+Chips can be selected via the `selected` property. Selection can be disabled by setting
+`selectable` to `false` on the `<md-chip-list>`. 
+
+### Keyboard interation
+Users can move through the chips using the arrow keys and select them with the space.
+
+
+### Theming
+The color of an `<md-chip>` can be changed by using the `color` property. By default, chips
+use a neutral background color based on the current theme (light or dark). This can be changed to 
+`'primary'`, `'accent'`, or `'warn'`.

src/lib/grid-list/OVERVIEW.md

@@ -1,12 +1,8 @@
-# md-grid-list
-
-`md-grid-list` is an alternative list view that arranges cells into grid-based layout. 
+`md-grid-list` is a two-dimensional list view that arranges cells into grid-based layout. 
 See Material Design spec [here](https://www.google.com/design/spec/components/grid-lists.html).
 
 <!-- example(grid-list-overview) -->
 
-## Usage
-
 ### Setting the number of columns
 
 An `md-grid-list` must specify a `cols` attribute which sets the number of columns in the gird. The

src/lib/icon/OVERVIEW.md

@@ -1,23 +1,14 @@
-# md-icon
-
 `md-icon` makes it easier to use _vector-based_ icons in your app.  This directive supports both
 icon fonts and SVG icons, but not bitmap-based formats (png, jpg, etc.).
 
 <!-- example(icon-example) -->
 
-## Usage
-
-### Registering new icons
+### Registering icons
 
 `MdIconRegistry` is an injectable service that allows you to associate icon names with SVG URLs and
 define aliases for CSS font classes. Its methods are discussed below and listed in the API summary.
 
-In order to prevent XSS vulnerabilities, any URLs passed to the `MdIconRegistry` must be marked as
-trusted resource URLs by using Angular's `DomSanitizer` service.
-
-### Font icons
-
-#### Ligatures
+### Font icons with ligatures
 
 Some fonts are designed to show icons by using
 [ligatures](https://en.wikipedia.org/wiki/Typographic_ligature), for example by rendering the text
@@ -31,7 +22,7 @@ You can specify a different font by setting the `fontSet` input to either the CS
 use the desired font, or to an alias previously registered with
 `MdIconRegistry.registerFontClassAlias`.
 
-#### Font icons via CSS
+### Font icons with CSS
 
 Fonts can also display icons by defining a CSS class for each icon glyph, which typically uses a
 `:before` selector to cause the icon to appear.
@@ -48,14 +39,17 @@ explicitly set by calling `MdIconRegistry.setDefaultFontSetClass`.
 When an `md-icon` component displays an SVG icon, it does so by directly inlining the SVG content
 into the page as a child of the component. (Rather than using an <img> tag or a div background
 image). This makes it easier to apply CSS styles to SVG icons. For example, the default color of the
-SVG content is the CSS [currentColor](http://www.quirksmode.org/css/color/currentcolor.html) value.
-This makes SVG icons by default have the same color as surrounding text, and allows you to change
-the color by setting the "color" style on the `md-icon` element.
+SVG content is the CSS 
+[currentColor](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentColor_keyword) 
+value. This makes SVG icons by default have the same color as surrounding text, and allows you to 
+change the color by setting the "color" style on the `md-icon` element.
 
-#### Icons from URLs
+In order to prevent XSS vulnerabilities, any SVG URLs passed to the `MdIconRegistry` must be 
+marked as trusted resource URLs by using Angular's `DomSanitizer` service.
 
-SVG icons can be used either by directly specifying the icon's URL, or by associating an icon name
-with a URL and then referring to the name. To use a URL directly, set the `svgSrc` input.
+Also note that all SVG icons are fetched via XmlHttpRequest, and due to the same-origin policy, 
+their URLs must be on the same domain as the containing page, or their servers must be configured 
+to allow cross-domain access.
 
 #### Named icons
 
@@ -78,14 +72,11 @@ as for individually registered icons.
 Multiple icon sets can be registered in the same namespace. Requesting an icon whose id appears in
 more than one icon set, the icon from the most recently registered set will be used.
 
-Note that all SVG icons are fetched via XmlHttpRequest, and due to the same-origin policy their URLs
-must be on the same domain as the containing page, or their servers must be configured to allow
-cross-domain access.
-
 ### Theming
 
-Icons can be themed to match your "primary" palette, your "accent" palette, or your "warn" palette
-using the `color` attribute. Simply pass in the desired palette name.
+By default, icons will use the current font color (`currentColor`). this color can be changed to 
+match the current theme's colors using the `color` attribute. This can be changed to 
+`'primary'`, `'accent'`, or `'warn'`.
 
 ### Accessibility
 

src/lib/input/OVERVIEW.md

@@ -1,29 +1,25 @@
-# md-input-container
+`<md-input-container>` is a wrapper for native `input` and `textarea` elements. This container 
+applies Material Design styles and behavior while still allowing direct access to the underlying
+native element.
 
-Inputs are the basic input component of Material 2. The spec can be found
-[here](https://www.google.com/design/spec/components/text-fields.html). `md-input-container` acts as
-a wrapper for native `input` and `textarea` elements that is used to add material design styles and
-behavior. The native element wrapped by the `md-input-container` must be marked with the `md-input`
-directive.
+The native element wrapped by the `md-input-container` must be marked with the `mdInput` directive.
 
 <!-- example(input-overview) -->
 
-## Usage
-
 ### `input` and `textarea` attributes
 
 All of the attributes that can be used with normal `input` and `textarea` elements can be used on
-elements within the `md-input-container` as well. This includes angular specific ones such as
+elements inside `md-input-container` 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
 `md-input-container` and the native element cannot specify a `placeholder` attribute if the
 `md-input-container` also contains a `md-placeholder` element. 
 
-#### Supported `input` types
+### Supported `input` types
 
-The following [input types](http://www.w3schools.com/TAGs/att_input_type.asp) can be used with
-`md-input-container`:
+The following [input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) can
+be used with `md-input-container`:
 * date
 * datetime-local
 * email

src/lib/list/OVERVIEW.md

@@ -0,0 +1,124 @@
+`<md-list>` is a container component that wraps and formats a series of line items. As the base 
+list component, it provides Material Design styling, but no behavior of its own.
+
+<!-- example(list-overview) -->
+
+
+### Simple lists
+
+An `<md-list>` element contains a number of `<md-list-item>` elements.
+
+```html
+<md-list>
+ <md-list-item> Pepper </md-list-item>
+ <md-list-item> Salt </md-list-item>
+ <md-list-item> Paprika </md-list-item>
+</md-list>
+```
+
+### Navigation lists
+
+Use `md-nav-list` tags for navigation lists (i.e. lists that have anchor tags).
+
+Simple navigation lists can use the `md-list-item` attribute on anchor tag elements directly:
+
+```html
+<md-nav-list>
+   <a md-list-item href="..." *ngFor="let link of links"> {{ link }} </a>
+</md-nav-list>
+```
+
+For more complex navigation lists (e.g. with more than one target per item), wrap the anchor 
+element in an `<md-list-item>`.
+
+```html
+<md-nav-list>
+  <md-list-item *ngFor="let link of links">
+     <a md-line href="...">{{ link }}</a>
+     <button md-icon-button (click)="showInfo(link)">
+        <md-icon>info</md-icon>
+     </button>
+  </md-list-item>
+</md-nav-list>
+```
+
+### Multi-line lists
+For lists that require multiple lines per item, annotate each line with an `md-line` attribute.
+Whichever heading tag is appropriate for your DOM hierarchy should be used (not necesarily `<h3>`
+as shown in the example).
+
+```html
+<!-- two line list -->
+<md-list>
+  <md-list-item *ngFor="let message of messages">
+    <h3 md-line> {{message.from}} </h3>
+    <p md-line>
+      <span> {{message.subject}} </span>
+      <span class="demo-2"> -- {{message.content}} </span>
+    </p>
+  </md-list-item>
+</md-list>
+
+<!-- three line list -->
+<md-list>
+  <md-list-item *ngFor="let message of messages">
+    <h3 md-line> {{message.from}} </h3>
+    <p md-line> {{message.subject}} </p>
+    <p md-line class="demo-2"> {{message.content}} </p>
+  </md-list-item>
+</md-list>
+```
+
+### Lists with avatars
+To include an avatar, add an image tag with an `md-list-avatar` attribute.
+
+```html
+<md-list>
+  <md-list-item *ngFor="let message of messages">
+    <img md-list-avatar src="..." alt="...">
+    <h3 md-line> {{message.from}} </h3>
+    <p md-line>
+      <span> {{message.subject}} </span>
+      <span class="demo-2"> -- {{message.content}} </span>
+    </p>
+  </md-list-item>
+</md-list>
+```
+
+### Dense lists
+Lists are also available in "dense layout" mode, which shrinks the font size and height of the list
+to suit UIs that may need to display more information. To enable this mode, add a `dense` attribute
+to the main `md-list` tag.
+
+
+```html
+<md-list dense>
+ <md-list-item> Pepper </md-list-item>
+ <md-list-item> Salt </md-list-item>
+ <md-list-item> Paprika </md-list-item>
+</md-list>
+```
+
+
+### Lists with multiple sections
+
+Subheader can be added to a list by annotating a heading tag with an `md-subheader` attribute. 
+To add a divider, use `<md-divider>`.
+
+```html
+<md-list>
+   <h3 md-subheader>Folders</h3>
+   <md-list-item *ngFor="let folder of folders">
+      <md-icon md-list-avatar>folder</md-icon>
+      <h4 md-line>{{folder.name}}</h4>
+      <p md-line class="demo-2"> {{folder.updated}} </p>
+   </md-list-item>
+   <md-divider></md-divider>
+   <h3 md-subheader>Notes</h3>
+   <md-list-item *ngFor="let note of notes">
+      <md-icon md-list-avatar>note</md-icon>
+      <h4 md-line>{{note.name}}</h4>
+      <p md-line class="demo-2"> {{note.updated}} </p>
+   </md-list-item>
+</md-list>
+```

src/lib/menu/OVERVIEW.md

@@ -0,0 +1,62 @@
+`<md-menu>` is a floating panel containing list of options. 
+
+<!-- example(menu-overview) -->
+
+By itself, the `<md-menu>` element does not render anything. The menu is attached to and opened 
+via application of the `mdMenuTriggerFor` directive:
+```ts
+<md-menu #appMenu="mdMenu">
+  <button md-menu-item> Settings </button>
+  <button md-menu-item> Help </button>
+</md-menu>
+
+<button md-icon-button [mdMenuTriggerFor]="appMenu">
+   <md-icon>more_vert</md-icon>
+</button>
+```
+
+### Toggling the menu programmatically
+The menu exposes an API to open/close programmatically. Please note that in this case, an 
+`mdMenuTriggerFor` directive is still necessary to attach the menu to a trigger element in the DOM.
+
+```ts
+class MyComponent {
+  @ViewChild(MdMenuTrigger) trigger: MdMenuTrigger;
+
+  someMethod() {
+    this.trigger.openMenu();
+  }
+}
+```
+
+### Icons
+Menus support displaying `md-icon` elements before the menu item text.
+
+*my-comp.html*
+```html
+<md-menu #menu="mdMenu">
+  <button md-menu-item>
+    <md-icon> dialpad </md-icon>
+    <span> Redial </span>
+  </button>
+  <button md-menu-item disabled>
+    <md-icon> voicemail </md-icon>
+    <span> Check voicemail </span>
+  </button>
+  <button md-menu-item>
+    <md-icon> notifications_off </md-icon>
+    <span> Disable alerts </span>
+  </button>
+</md-menu>
+```
+
+### Customizing menu position
+
+By default, the menu will display after and below its trigger.  The position can be changed
+using the `x-position` (`before | after`) and `y-position` (`above | below`) attributes.
+
+
+### Keyboard interaction
+- <kbd>DOWN_ARROW</kbd>: Focuses the next menu item
+- <kbd>UP_ARROW</kbd>: Focuses previous menu item
+- <kbd>ENTER</kbd>: Activates the focused menu item