docs(a11y): Add a11y docs for table, expansion panel, dialog, chips, autocomplete… (#6751)

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

* address comments

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 is given `role="combobox"`. The 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
+A chip-list behaves as a `role="listbox"`, with each chip being a `role="option"`. 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,22 @@ that the AOT compiler knows to create the `ComponentFactory` for it.
 })
 export class AppModule() {}
 ```
+
+### Accessibility
+By default, each dialog has `role="dialog"` on the root element. The role can be changed to
+`alertdialog` via the `MdDialogConfig` when opening.
+
+The `aria-label`, `aria-labelledby`, and `aria-describedby` attributes can all be set to the
+dialog element via the `MdDialogConfig` as well. Each dialog should typically have a label
+set via `aria-label` or `aria-labelledby`.
+
+#### Focus management
+By default, the first tabbable element within the dialog will receive focus upon open.
+
+Tabbing through the elements of the dialog will keep focus inside of the dialog element,
+wrapping back to the first tabbable element when reaching the end of the tab sequence.
+
+#### Keyboard interaction
+By default pressing the escape key will close the dialog. While this behavior can
+be turned off via the `disableClose` option, users should generally avoid doing so
+as it breaks the expected interaction pattern for screen-reader users.

src/lib/expansion/expansion.md

@@ -98,3 +98,12 @@ panel can be expanded at a given time:
 
 </md-accordion>
 ```
+
+### Accessibility
+The expansion-panel aims to mimic the experience of the native `<details>` and `<summary>` elements.
+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. Because the header acts as a button,
+additional interactive elements should not be put inside of the header.

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 attribute 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,12 @@ 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`. The `aria-readonly` defaults to `true` if it's not set.
+
+Table's default role is `grid`, and it can be changed to `treegrid` through `role` attribute.
+
+`md-table` does not manage any focus/keyboard interaction on its own. Users can add desired
+focus/keyboard interactions in their application.

src/lib/tabs/tabs.md

@@ -79,3 +79,16 @@ 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
+Tabs without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`. For `MdTabNav`, the `<nav>` element should have a label as well.
+
+
+#### Keyboard shortcuts
+
+| Shortcut             | Action                     |
+|----------------------|----------------------------|
+| `LEFT_ARROW`         | Move focus to previous tab |
+| `RIGHT_ARROW`        | Move focus to next tab     |
+| `SPACE` or 'ENTER'   | Switch to focused tab      |