Add a11y docs for table, expansion panel, dialog, chips, autocomplete, and select

Author: tinayuangao

src/lib/autocomplete/autocomplete.md

@@ -95,3 +95,10 @@ desired display value. Then bind it to the autocomplete's `displayWith` property
   </md-optgroup>
 </md-autocomplete>
 ```
+
+### Accessibility
+The input for autocomplete without text or labels should be given a meaningful label via
+`aria-label` or `aria-labelledby`.
+
+Autocomplete trigger sets `aria-owns` to the autocomplete's id, and sets `aria-activedescendant` to
+the active option's id.

src/lib/chips/chips.md

@@ -38,3 +38,7 @@ also gain focus when clicked, ensuring keyboard navigation starts at the appropr
 The selected 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'`.
+
+### Accessibility
+Chips have role="option", while the chip list has `role="listbox"`. The chip input should have a
+placeholder or be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/dialog/dialog.md

@@ -126,3 +126,10 @@ that the AOT compiler knows to create the `ComponentFactory` for it.
 })
 export class AppModule() {}
 ```
+
+### Accessibility
+The dialog has `role="dialog"`, and dialog role can be overwritten to `alertdialog` in the
+appropriate context.
+
+The dialog will focus on the first tabbable element when opened,
+and restore focus to the element that was focused before the dialog opened when closed.

src/lib/expansion/expansion.md

@@ -98,3 +98,10 @@ panel can be expanded at a given time:
 
 </md-accordion>
 ```
+
+### Accessibility
+The expansion panel header has `role="button"`. The expansion panel header has attribute
+`aria-controls` with the expansion panel's id as value.
+
+The expansion panel headers are buttons. Users can use the keyboard to activate the expansion panel
+header to switch between expanded state and collapsed state.

src/lib/input/input.md

@@ -150,3 +150,13 @@ Here are the available global options:
 | Name              | Type     | Description |
 | ----------------- | -------- | ----------- |
 | errorStateMatcher | Function | Returns a boolean specifying if the error should be shown |
+
+### Accessibility
+The `mdInput` directive works with native `<input>` to provide an accessible experience.
+
+If a placeholder attributed is added to the input, or a `md-placeholder` element is added
+in the form field, the placeholder text will automatically be used as the label for the input.
+If there's no placeholder specified, `aria-label`, `aria-labelledby` or `<label for=...>` should be
+added.
+
+Any `md-error` and `md-hint` are automatically added to the input's `aria-describedby`.

src/lib/paginator/paginator.md

@@ -24,3 +24,6 @@ This will allow you to change the following:
  1. The label for the length of each page.
  2. The range text displayed to the user.
  3. The tooltip messages on the navigation buttons.
+
+### Accessibility
+The `aria-label`s for next page and previous page buttons can be set in `MdPaginatorIntl`.

src/lib/select/select.md

@@ -92,3 +92,9 @@ Here are the available global options:
 - <kbd>DOWN_ARROW</kbd>: Focus next option
 - <kbd>UP_ARROW</kbd>: Focus previous option
 - <kbd>ENTER</kbd> or <kbd>SPACE</kbd>: Select focused item
+
+### Accessibility
+The select component without text or label should be given a meaningful label via
+`aria-label` or `aria-labelledby`.
+
+The select component has `role="listbox"` and options inside select have `role="option"`.

src/lib/sort/sort.md

@@ -32,4 +32,7 @@ To prevent the user from clearing the sort sort state from an already sorted col
 When used on an `md-table` header, it is not required to set an `md-sort-header` id on because
 by default it will use the id of the column.
 
-<!-- example(table-sorting) -->
+<!-- example(table-sorting) -->
+
+### Accessibility
+The `aria-label` for the sort button can be set in `MdSortHeaderIntl`.

src/lib/table/table.md

@@ -45,3 +45,9 @@ an update via the table's data source.
 In the near future, we will provide a simplified version of the data-table with an easy-to-use
 interface, material styling, array input, and more out-of-the-box features (sorting, pagination,
 and selection).
+
+### Accessibility
+Tables without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.
+
+Table's default role is 'grid', and it can be changed through `role` attribute.

src/lib/tabs/tabs.md

@@ -79,3 +79,7 @@ provides a tab-like UI for navigating between routes.
 The tab-nav-bar is not tied to any particular router; it works with normal `<a>` elements and uses
 the `active` property to determine which tab is currently active. The corresponding
 `<router-outlet>` can be placed anywhere in the view.
+
+### Accessibility
+`MdTabNav`s without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.