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

tinayuangao · 2017-08-31T00:53:29Z

…, and select

rafaelss95 · 2017-08-31T01:07:54Z

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
+`MdTanNav`s without text or labels should be given a meaningful label via `aria-label` or


Typo: MdTabNav.

mmalerba · 2017-08-31T16:28:35Z

src/lib/input/input.md

@@ -150,3 +150,6 @@ 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.


Should also mention that if you add a placeholder attribute to the input or a md-placeholder element in the form field that placeholder text will automatically be used as the label for the input. If you don't specify any placeholder you need to add aria-label aria-labeledby or <label for=...>

Possibly also worth mentioning that any md-error and md-hint are automatically added to the input's aria-describedby

mmalerba · 2017-08-31T16:30:35Z

src/lib/select/select.md

@@ -92,3 +92,11 @@ 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


FYI, the placeholder, hint, and error stuff will work the same way as input after the refactor. For now this is fine though

crisbeto · 2017-08-31T16:29:34Z

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 has `role="option"` while chip list has `role="listbox"`. The chip input should have a


Chips have role="option", while the chip list has...

crisbeto · 2017-08-31T16:30:32Z

src/lib/dialog/dialog.md

@@ -126,3 +126,7 @@ that the AOT compiler knows to create the `ComponentFactory` for it.
 })
 export class AppModule() {}
 ```
+
+### Accessibility
+The dialog has `role="dialog". The dialog will focus on the first tabbable element when opened,


This should mention that the dialog role can be overwritten to alertdialog in the appropriate context.

crisbeto · 2017-08-31T16:31:21Z

src/lib/expansion/expansion.md

+The expansion panel header has `role="button"`. The expansion panel header has attribute
+`aria-controls` with the expansion panel's id as value.
+
+Users can use keyboard to activate the expansion panel header to switch between expanded state


"can use keyboard" -> "can use the keyboard".

crisbeto · 2017-08-31T16:32:43Z

src/lib/select/select.md

+`aria-label` or `aria-labelledby`.
+
+The select component has `role="listbox"` and options inside select has `role="option"`.
+Autocomplete trigger sets `aria-owns` to the autocomplete's id, and sets `aria-activedescendant` to


This one talks about autocomplete instead of select. Also select doesn't use aria-activedescendant, but it moves focus between the options.

crisbeto · 2017-08-31T16:33:21Z

src/lib/sort/sort.md

+
+### Accessibility
+The `aria-label` for sort button can be set in `MdSortHeaderIntl`.


"the aria-label for sort button" -> "the aria-label for the sort button".

tinayuangao · 2017-08-31T17:22:08Z

Comments addressed. Please take another look. Thanks!

crisbeto

LGTM, a couple of minor nits.

crisbeto · 2017-08-31T17:56:33Z

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


Seems like you're missing a backtick after the role.

crisbeto · 2017-08-31T17:57:29Z

src/lib/select/select.md

+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 has `role="option"`.


has -> have

josephperrott · 2017-08-31T22:17:35Z

src/lib/expansion/expansion.md

+The expansion panel header has `role="button"`. The expansion panel header has attribute
+`aria-controls` with the expansion panel's id as value.
+
+Users can use the keyboard to activate the expansion panel header to switch between expanded state


Is it worth noting that as the panel headers are buttons, they are able to be navigated to via keyboard as well?

tinayuangao · 2017-08-31T23:11:34Z

Comments addressed. Please take another look. Thanks!

mmalerba · 2017-08-31T23:55:13Z

LGTM for input

jelbourn · 2017-09-01T19:10:02Z

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


It would also be good to mention that the autocomplete trigger is given role="combobox"

jelbourn · 2017-09-01T19:55:29Z

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


I'd phrase this first sentence as

A chip-list behaves as a `role="listbox"`, with each chip being a `role="option"`.

jelbourn · 2017-09-01T19:57:25Z

src/lib/chips/chips.md

+
+### 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`.


This made me wonder whether we should somehow associate the chip-list and the input (Maybe aria-controls on the input? Not sure what that would do.).

Also I wonder whether having an input inside of a role="listbox" is problematic- how does the screen reader treat it now?

The screen reader treats chip input and chip list as two separate components now.

jelbourn · 2017-09-01T20:15:45Z

src/lib/dialog/dialog.md

+
+### Accessibility
+The dialog has `role="dialog"`, and dialog role can be overwritten to `alertdialog` in the
+appropriate context.


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.

(ariaLabel being added in #6558)

We can expand this in a later PR to mention the focus control attributes from cdkFocusTrap once we have documentation for that

jelbourn · 2017-09-01T20:17:56Z

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


I'd add a sentence at the beginning like

The expansion-panel aims to mimic the experience of the native `<details>` and `<summary>` elements.

jelbourn · 2017-09-01T20:18:54Z

src/lib/expansion/expansion.md

+`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.


I'd add another sentence

Because the header acts as a button, additional interactive elements should not be put inside of the header.

jelbourn · 2017-09-01T20:20:15Z

src/lib/table/table.md

+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.


We should mention that it can be changed to treegrid specifically, since that's the only other role that makes sense (being that it contains rows and gridcells)

jelbourn · 2017-09-01T20:22:43Z

src/lib/table/table.md

+
+### Accessibility
+Tables without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.


We should mention aria-readonly regardless of what we do with it.

(it defaults to true if it's not set, but most people probably make readonly tables)

jelbourn · 2017-09-01T20:24:26Z

src/lib/table/table.md

+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.


It's probably also worth mentioning that the md-table does not manage any focus/keyboard interaction on its own; if users want to add this, it can be added in their application.

jelbourn · 2017-09-01T20:25:29Z

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


This is true for either tab variant, not just the nav-tabs.

For nav-tabs, the <nav> element should probably have a label as well.

jelbourn · 2017-09-01T20:26:20Z

src/lib/tabs/tabs.md

+
+### Accessibility
+`MdTabNav`s without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.


Oh, and we should mention the keyboard shortcuts for md-tab-group

jelbourn · 2017-09-01T20:29:06Z

src/lib/dialog/dialog.md

+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,


I forgot about escape, too:

#### 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.

kara · 2017-09-01T20:33:43Z

src/lib/input/input.md

+### 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


Typo: attributed -> attribute

…, and select

tinayuangao · 2017-09-01T22:31:14Z

Comments addressed. Please take another look. Thanks!

jelbourn

LGTM, one last nit; add "merge-ready" when ready

jelbourn · 2017-09-02T00:08:39Z

src/lib/tabs/tabs.md

+`aria-labelledby`. For `MdTabNav`, the `<nav>` element should have a label as well.
+
+
+### Keyboard shortcuts


Should be level 4 header ####

angular-automatic-lock-bot · 2019-09-07T00:03:12Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

tinayuangao requested review from andrewseguin, crisbeto, jelbourn, josephperrott, kara and mmalerba as code owners August 31, 2017 00:53

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Aug 31, 2017

tinayuangao added Accessibility This issue is related to accessibility (a11y) docs This issue is related to documentation pr: needs review labels Aug 31, 2017

rafaelss95 reviewed Aug 31, 2017

View reviewed changes

mmalerba reviewed Aug 31, 2017

View reviewed changes

crisbeto reviewed Aug 31, 2017

View reviewed changes

crisbeto approved these changes Aug 31, 2017

View reviewed changes

josephperrott reviewed Aug 31, 2017

View reviewed changes

tinayuangao force-pushed the a11y-docs2 branch from f10853a to b80386e Compare August 31, 2017 23:11

mmalerba approved these changes Aug 31, 2017

View reviewed changes

jelbourn reviewed Sep 1, 2017

View reviewed changes

kara reviewed Sep 1, 2017

View reviewed changes

Add a11y docs for table, expansion panel, dialog, chips, autocomplete…

5d16bf9

…, and select

tinayuangao force-pushed the a11y-docs2 branch from b80386e to 371060c Compare September 1, 2017 22:25

jelbourn approved these changes Sep 2, 2017

View reviewed changes

jelbourn added pr: lgtm and removed pr: needs review labels Sep 2, 2017

address comments

f356a72

tinayuangao force-pushed the a11y-docs2 branch from 371060c to f356a72 Compare September 2, 2017 00:27

tinayuangao added the action: merge The PR is ready for merge by the caretaker label Sep 2, 2017

tinayuangao merged commit 5527e22 into angular:master Sep 6, 2017

tinayuangao deleted the a11y-docs2 branch September 6, 2017 17:12

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 7, 2019


		### Accessibility
		The `aria-label` for sort button can be set in `MdSortHeaderIntl`.

		`aria-labelledby`. For `MdTabNav`, the `<nav>` element should have a label as well.


		### Keyboard shortcuts

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

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

Uh oh!

Conversation

tinayuangao commented Aug 31, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tinayuangao commented Aug 31, 2017

Uh oh!

crisbeto left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tinayuangao commented Aug 31, 2017

Uh oh!

mmalerba commented Aug 31, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tinayuangao commented Sep 1, 2017

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

angular-automatic-lock-bot bot commented Sep 7, 2019

Uh oh!

Uh oh!