docs(a11y): add accessibility sections to datepicker, menu, slide … (angular#6710)

Author: tinayuangao

src/demo-app/expansion/expansion-demo.html

@@ -27,10 +27,16 @@ <h1>Accordion</h1>
   <p>Accordion Options</p>
   <div>
     <md-slide-toggle [(ngModel)]="multi">Allow Multi Expansion</md-slide-toggle>
-    <md-slide-toggle [(ngModel)]="hideToggle">Hide Indicators</md-slide-toggle>
     <md-slide-toggle [(ngModel)]="disabled">Disable Panel 2</md-slide-toggle>
     <md-slide-toggle [(ngModel)]="showPanel3">Show Panel 3</md-slide-toggle>
   </div>
+  <div>
+    <md-radio-group [(ngModel)]="hideToggle">
+      <md-radio-button value="start">Start</md-radio-button>
+      <md-radio-button value="end">End</md-radio-button>
+      <md-radio-button value="hidden">Hidden</md-radio-button>
+    </md-radio-group>
+  </div>
   <p>Accordion Style</p>
   <md-radio-group [(ngModel)]="displayMode">
     <md-radio-button value="default">Default</md-radio-button>

src/lib/datepicker/datepicker.md

@@ -229,3 +229,52 @@ application root module.
 })
 export class MyApp {}
 ```
+### Accessibility
+The `MdDatepickerInput` directive adds `aria-haspopup` attribute to the native input element, and it
+triggers a calendar dialog with `role="dialog"`.
+
+`MdDatepickerIntl` includes strings that are used for `aria-label`s. The datepicker input
+should have a placeholder or be given a meaningful label via `aria-label`, `aria-labelledby` or
+`MdDatepickerIntl`.
+
+#### Keyboard shortcuts
+The keyboard shortcuts to handle datepicker are:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `ALT` + `DOWN_ARROW` | Open the calendar pop-up            |
+| `ESCAPE`             | Close the calendar pop-up           |
+
+
+In month view:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `LEFT_ARROW`         | Go to previous day                  |
+| `RIGHT_ARROW`        | Go to next day                      |
+| `UP_ARROW`           | Go to same day in the previous week |
+| `DOWN_ARROW`         | Go to same day in the next week     |
+| `HOME`               | Go to the first day of the month    |
+| `END`                | Go to the last day of the month     |
+| `PAGE_UP`            | Go to previous month                |
+| `ALT` + `PAGE_UP`    | Go to previous year                 |
+| `PAGE_DOWN`          | Go to next month                    |
+| `ALT` + `PAGE_DOWN`  | Go to next year                     |
+| `ENTER`              | Select current date                 |
+
+
+In year view:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `LEFT_ARROW`         | Go to previous month                |
+| `RIGHT_ARROW`        | Go to next month                    |
+| `UP_ARROW`           | Go to previous 6 months             |
+| `DOWN_ARROW`         | Go to next 6 months                 |
+| `HOME`               | Go to the first month of the year   |
+| `END`                | Go to the last month of the year    |
+| `PAGE_UP`            | Go to previous year                 |
+| `ALT` + `PAGE_UP`    | Go to previous 10 years             |
+| `PAGE_DOWN`          | Go to next year                     |
+| `ALT` + `PAGE_DOWN`  | Go to next 10 years                 |
+| `ENTER`              | Select current month                |

src/lib/expansion/accordion.ts

@@ -31,9 +31,7 @@ export class CdkAccordion {
   private  _multi: boolean = false;
 
   /** Whether the expansion indicator should be hidden. */
-  @Input() get hideToggle(): boolean { return this._hideToggle; }
-  set hideToggle(show: boolean) { this._hideToggle = coerceBooleanProperty(show); }
-  private  _hideToggle: boolean = false;
+  @Input() hideToggle = 'end';
 
   /**
    * The display mode used for all expansion panels in the accordion. Currently two display

src/lib/expansion/expansion-panel-header.html

@@ -3,5 +3,5 @@
   <ng-content select="md-panel-description, mat-panel-description"></ng-content>
   <ng-content></ng-content>
 </span>
-<span [@indicatorRotate]="_getExpandedState()" *ngIf="_showToggle()"
+<span [@indicatorRotate]="_getExpandedState()" *ngIf="_indicatorLocation() !== 'hidden'"
       class="mat-expansion-indicator"></span>

src/lib/expansion/expansion-panel-header.ts

@@ -137,8 +137,11 @@ export class MdExpansionPanelHeader implements OnDestroy {
   }
 
   /** Gets whether the expand indicator should be shown. */
-  _showToggle(): boolean {
-    return !this.panel.hideToggle && !this.panel.disabled;
+  _indicatorLocation(): string {
+    if (this.panel.disabled) {
+      return 'hidden';
+    }
+    return this.panel.hideToggle;
   }
 
   /** Handle keyup event calling to toggle() if appropriate. */

src/lib/expansion/expansion-panel.ts

@@ -73,7 +73,7 @@ export const EXPANSION_PANEL_ANIMATION_TIMING = '225ms cubic-bezier(0.4,0.0,0.2,
 })
 export class MdExpansionPanel extends AccordionItem implements OnChanges, OnDestroy {
   /** Whether the toggle indicator should be hidden. */
-  @Input() hideToggle: boolean = false;
+  @Input() hideToggle: string = 'end';
 
   /** Stream that emits for changes in `@Input` properties. */
   _inputChanges = new Subject<SimpleChanges>();
@@ -86,11 +86,11 @@ export class MdExpansionPanel extends AccordionItem implements OnChanges, OnDest
   }
 
   /** Whether the expansion indicator should be hidden. */
-  _getHideToggle(): boolean {
+  _getHideToggle(): string {
     if (this.accordion) {
-      return this.accordion.hideToggle;
+      return this.accordion.hideToggle ? '' : 'hidden';
     }
-    return this.hideToggle;
+    return this.hideToggle ? '' : 'hidden';
   }
 
   /** Determines whether the expansion panel should have spacing between it and its siblings. */

src/lib/menu/menu.md

@@ -98,3 +98,7 @@ that should trigger the sub-menu:
 - <kbd>RIGHT_ARROW</kbd>: Opens the menu item's sub-menu
 - <kbd>LEFT_ARROW</kbd>: Closes the current menu, if it is a sub-menu.
 - <kbd>ENTER</kbd>: Activates the focused menu item
+
+### Accessibility
+Menu triggers or menu items without text or labels should be given a meaningful label via
+`aria-label` or `aria-labelledby`.

src/lib/slide-toggle/slide-toggle.md

@@ -22,3 +22,11 @@ and `ReactiveFormsModule`.
 ### Theming
 The color of a `<md-slide-toggle>` can be changed by using the `color` property. By default, 
 slide-toggles use the theme's accent color. This can be changed to `'primary'` or `'warn'`.  
+
+### Accessibility
+The `<md-slide-toggle>` uses an internal `<input type="checkbox">` to provide an accessible
+experience. This internal checkbox receives focus and is automatically labelled by the text content
+of the `<md-slide-toggle>` element.
+
+Slide toggles without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.

src/lib/slider/slider.md

@@ -85,3 +85,7 @@ The slider has the following keyboard bindings:
 | Page down   | Decrement the slider value by 10 steps.                                            |
 | End         | Set the value to the maximum possible.                                             |
 | Home        | Set the value to the minimum possible.                                             |
+
+### Accessibility
+Sliders without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.

src/lib/snack-bar/snack-bar.md

@@ -72,3 +72,8 @@ export class MessageArchivedComponent {
   constructor(@Inject(MD_SNACK_BAR_DATA) public data: any) { }
 }
 ```
+### Accessibility
+Snack-bar messages are announced via an `aria-live` region. Focus is not moved to
+the snack-bar element, as this would be disruptive to a user in the middle of a
+workflow. For any action offered in the snack-bar, the application should offer the
+user an alternative way to perform the action (typically via keyboard shortcut).

src/lib/toolbar/toolbar.md

@@ -49,3 +49,13 @@ easily accomplished with `display: flex`:
 The color of a `<md-toolbar>` can be changed by using the `color` property. By default, toolbars
 use a neutral background color based on the current theme (light or dark). This can be changed to 
 `'primary'`, `'accent'`, or `'warn'`.  
+
+### Accessibility
+By default, the toolbar assumes that it will be used in a purely decorative fashion and thus sets
+no roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of `<div>`
+elements on the page.
+
+Generally, the toolbar is used as a header where `role="header"` would be appropriate.
+
+Only if the use-case of the toolbar match that of role="toolbar", the user should add the role and
+an appropriate label via `aria-label` or `aria-labelledby`.