feat(menu): Better keyboard accessibility support. (google#4905)

Author: sgomes

demos/simple-menu.html

@@ -62,7 +62,7 @@ <h1>MDL Simple Menu</h1>
         <button class="toggle">Toggle</button>
         <span>Last Selected item: <em id="last-selected">&lt;none selected&gt;</em></span>
       </div>
-      <div class="mdl-simple-menu">
+      <div class="mdl-simple-menu" tabindex="-1">
         <ul class="mdl-simple-menu__items mdl-list" role="menu" aria-hidden="true">
           <li class="mdl-list-item" role="menuitem" tabindex="0">Back</li>
           <li class="mdl-list-item" role="menuitem" tabindex="0">Forward</li>

packages/mdl-menu/README.md

@@ -14,8 +14,8 @@ first render.
 A simple menu is usually closed, appearing when opened. It is appropriate for any display size.
 
 ```html
-<div class="mdl-simple-menu">
-  <ul class="mdl-simple-menu__items mdl-list" role="menu">
+<div class="mdl-simple-menu" tabindex="-1">
+  <ul class="mdl-simple-menu__items mdl-list" role="menu" aria-hidden="true">
     <li class="mdl-list-item" role="menuitem" tabindex="0">
       A Menu Item
     </li>
@@ -25,6 +25,11 @@ A simple menu is usually closed, appearing when opened. It is appropriate for an
   </ul>
 </div>
 ```
+> Note: adding a `tabindex` of `0` to the menu items places them in the tab order.
+  Adding a `tabindex` of `-1` to the root element makes it programmatically focusable, without
+  placing it in the tab order. This allows the menu to be focused on open, so that the next Tab
+  keypress moves to the first menu item. If you would like the first menu item to be automatically
+  focused instead, remove `tabindex="-1"` from the root element.
 
 ```js
 let menu = new mdl.SimpleMenu(document.querySelector('.mdl-simple-menu'));
@@ -61,6 +66,26 @@ menu.open = true;
 menu.open = false;
 ```
 
+It also has two lower level methods, which control the menu directly, by showing (opening) and
+hiding (closing) it:
+
+```js
+// Show (open) menu.
+menu.show();
+// Hide (close) menu.
+menu.hide();
+// Show (open) menu, and focus the menu item at index 1.
+menu.show({focusIndex: 1});
+```
+
+You can still use the `open` getter property even if showing and hiding directly:
+
+```js
+menu.show();
+console.log(`Menu is ${menu.open ? 'open' : 'closed'}.`);
+```
+
+
 #### Including in code
 
 ##### ES2015
@@ -122,6 +147,8 @@ with the following `detail` data:
 | `item` | `HTMLElement` | The DOM element for the selected item |
 | `index` | `number` | The index of the selected item |
 
+If the menu is closed with no selection made (for example, if the user hits `Escape` while it's open), a `MDLSimpleMenu:cancel` custom event is emitted instead, with no data attached.
+
 ### Using the Foundation Class
 
 MDL Simple Menu ships with an `MDLSimpleMenuFoundation` class that external frameworks and libraries can use to
@@ -140,7 +167,16 @@ The adapter for temporary drawers must provide the following functions, with cor
 | `getNumberOfItems() => numbers` | Returns the number of _item_ elements inside the items container. In our vanilla component, we determine this by counting the number of list items whose `role` attribute corresponds to the correct child role of the role present on the menu list element. For example, if the list element has a role of `menu` this queries for all elements that have a role of `menuitem`. |
 | `registerInteractionHandler(type: string, handler: EventListener) => void` | Adds an event listener `handler` for event type `type`. |
 | `deregisterInteractionHandler(type: string, handler: EventListener) => void` | Removes an event listener `handler` for event type `type`. |
+| `registerDocumentClickHandler(handler: EventListener) => void` | Adds an event listener `handler` for event type 'click'. |
+| `deregisterDocumentClickHandler(handler: EventListener) => void` | Removes an event listener `handler` for event type 'click'. |
 | `getYParamsForItemAtIndex(index: number) => {top: number, height: number}` | Returns an object with the offset top and offset height values for the _item_ element inside the items container at the provided index. Note that this is an index into the list of _item_ elements, and not necessarily every child element of the list. |
 | `setTransitionDelayForItemAtIndex(index: number, value: string) => void` | Sets the transition delay on the element inside the items container at the provided index to the provided value. The same notice for `index` applies here as above. |
 | `getIndexForEventTarget(target: EventTarget) => number` | Checks to see if the `target` of an event pertains to one of the menu items, and if so returns the index of that item. Returns -1 if the target is not one of the menu items. The same notice for `index` applies here as above. |
 | `notifySelected(evtData: {index: number}) => void` | Dispatches an event notifying listeners that a menu item has been selected. The function should accept an `evtData` parameter containing the an object with an `index` property representing the index of the selected item. Implementations may choose to supplement this data with additional data, such as the item itself. |
+| `notifyCancel() => void` | Dispatches an event notifying listeners that the menu has been closed with no selection made. |
+| `saveFocus() => void` | Stores the currently focused element on the document, for restoring with `restoreFocus`. |
+| `restoreFocus() => void` | Restores the previously saved focus state, by making the previously focused element the active focus again. |
+| `isFocused() => boolean` | Returns a boolean value indicating whether the root element of the simple menu is focused. |
+| `focus() => void` | Focuses the root element of the simple menu. |
+| `getFocusedItemIndex() => number` | Returns the index of the currently focused menu item (-1 if none). |
+| `focusItemAtIndex(index: number) => void` | Focuses the menu item with the provided index. |

packages/mdl-menu/simple/foundation.js

@@ -43,24 +43,31 @@ export default class MDLSimpleMenuFoundation extends MDLFoundation {
       getNumberOfItems: () => /* number */ 0,
       registerInteractionHandler: (/* type: string, handler: EventListener */) => {},
       deregisterInteractionHandler: (/* type: string, handler: EventListener */) => {},
+      registerDocumentClickHandler: (/* handler: EventListener */) => {},
+      deregisterDocumentClickHandler: (/* handler: EventListener */) => {},
       getYParamsForItemAtIndex: (/* index: number */) => /* {top: number, height: number} */ ({}),
       setTransitionDelayForItemAtIndex: (/* index: number, value: string */) => {},
       getIndexForEventTarget: (/* target: EventTarget */) => /* number */ 0,
-      notifySelected: (/* evtData: {index: number} */) => {}
+      notifySelected: (/* evtData: {index: number} */) => {},
+      notifyCancel: () => {},
+      saveFocus: () => {},
+      restoreFocus: () => {},
+      isFocused: () => /* boolean */ false,
+      focus: () => {},
+      getFocusedItemIndex: () => /* number */ -1,
+      focusItemAtIndex: (/* index: number */) => {}
     };
   }
 
   constructor(adapter) {
     super(Object.assign(MDLSimpleMenuFoundation.defaultAdapter, adapter));
-    this.keyupHandler_ = evt => {
-      const {keyCode, key} = evt;
-      const isEnter = key === 'Enter' || keyCode === 13;
-      const isSpace = key === 'Space' || keyCode === 32;
-      if (isEnter || isSpace) {
-        this.handlePossibleSelected_(evt);
-      }
-    };
     this.clickHandler_ = evt => this.handlePossibleSelected_(evt);
+    this.keydownHandler_ = evt => this.handleKeyboardDown_(evt);
+    this.keyupHandler_ = evt => this.handleKeyboardUp_(evt);
+    this.documentClickHandler_ = evt => {
+      this.adapter_.notifyCancel();
+      this.close();
+    };
     this.isOpen_ = false;
     this.startScaleX_ = 0;
     this.startScaleY_ = 0;
@@ -88,28 +95,15 @@ export default class MDLSimpleMenuFoundation extends MDLFoundation {
 
     this.adapter_.registerInteractionHandler('click', this.clickHandler_);
     this.adapter_.registerInteractionHandler('keyup', this.keyupHandler_);
+    this.adapter_.registerInteractionHandler('keydown', this.keydownHandler_);
   }
 
   destroy() {
     clearTimeout(this.selectedTriggerTimerId_);
     this.adapter_.deregisterInteractionHandler('click', this.clickHandler_);
     this.adapter_.deregisterInteractionHandler('keyup', this.keyupHandler_);
-  }
-
-  handlePossibleSelected_(evt) {
-    const targetIndex = this.adapter_.getIndexForEventTarget(evt.target);
-    if (targetIndex < 0) {
-      return;
-    }
-    // Debounce multiple selections
-    if (this.selectedTriggerTimerId_) {
-      return;
-    }
-    this.selectedTriggerTimerId_ = setTimeout(() => {
-      this.selectedTriggerTimerId_ = 0;
-      this.close();
-      this.adapter_.notifySelected({index: targetIndex});
-    }, numbers.SELECTED_TRIGGER_DELAY);
+    this.adapter_.deregisterInteractionHandler('keydown', this.keydownHandler_);
+    this.adapter_.deregisterDocumentClickHandler(this.documentClickHandler_);
   }
 
   // Calculate transition delays for individual menu items, so that they fade in one at a time.
@@ -206,27 +200,131 @@ export default class MDLSimpleMenuFoundation extends MDLFoundation {
     }
   }
 
-  // Open the menu.
-  open() {
+  focusOnOpen_(focusIndex) {
+    if (focusIndex === null) {
+      // First, try focusing the menu.
+      this.adapter_.focus();
+      // If that doesn't work, focus first item instead.
+      if (!this.adapter_.isFocused()) {
+        this.adapter_.focusItemAtIndex(0);
+      }
+    } else {
+      this.adapter_.focusItemAtIndex(focusIndex);
+    }
+  }
+
+  // Handle keys that we want to repeat on hold (tab and arrows).
+  handleKeyboardDown_(evt) {
+    // Do nothing if Alt, Ctrl or Meta are pressed.
+    if (evt.altKey || evt.ctrlKey || evt.metaKey) {
+      return true;
+    }
+
+    const {keyCode, key, shiftKey} = evt;
+    const isTab = key === 'Tab' || keyCode === 9;
+    const isArrowUp = key === 'ArrowUp' || keyCode === 38;
+    const isArrowDown = key === 'ArrowDown' || keyCode === 40;
+
+    const focusedItemIndex = this.adapter_.getFocusedItemIndex();
+    const lastItemIndex = this.adapter_.getNumberOfItems() - 1;
+
+    if (shiftKey && isTab && focusedItemIndex === 0) {
+      this.adapter_.focusItemAtIndex(lastItemIndex);
+      evt.preventDefault();
+      return false;
+    }
+
+    if (!shiftKey && isTab && focusedItemIndex === lastItemIndex) {
+      this.adapter_.focusItemAtIndex(0);
+      evt.preventDefault();
+      return false;
+    }
+
+    if (isArrowUp) {
+      if (focusedItemIndex === 0 || this.adapter_.isFocused()) {
+        this.adapter_.focusItemAtIndex(lastItemIndex);
+      } else {
+        this.adapter_.focusItemAtIndex(focusedItemIndex - 1);
+      }
+    }
+
+    if (isArrowDown) {
+      if (focusedItemIndex === lastItemIndex || this.adapter_.isFocused()) {
+        this.adapter_.focusItemAtIndex(0);
+      } else {
+        this.adapter_.focusItemAtIndex(focusedItemIndex + 1);
+      }
+    }
+
+    return true;
+  }
+
+  // Handle keys that we don't want to repeat on hold (Enter, Space, Escape).
+  handleKeyboardUp_(evt) {
+    // Do nothing if Alt, Ctrl or Meta are pressed.
+    if (evt.altKey || evt.ctrlKey || evt.metaKey) {
+      return true;
+    }
+
+    const {keyCode, key} = evt;
+    const isEnter = key === 'Enter' || keyCode === 13;
+    const isSpace = key === 'Space' || keyCode === 32;
+    const isEscape = key === 'Escape' || keyCode === 27;
+
+    if (isEnter || isSpace) {
+      this.handlePossibleSelected_(evt);
+    }
+
+    if (isEscape) {
+      this.adapter_.notifyCancel();
+      this.close();
+    }
+
+    return true;
+  }
+
+  handlePossibleSelected_(evt) {
+    const targetIndex = this.adapter_.getIndexForEventTarget(evt.target);
+    if (targetIndex < 0) {
+      return;
+    }
+    // Debounce multiple selections
+    if (this.selectedTriggerTimerId_) {
+      return;
+    }
+    this.selectedTriggerTimerId_ = setTimeout(() => {
+      this.selectedTriggerTimerId_ = 0;
+      this.close();
+      this.adapter_.notifySelected({index: targetIndex});
+    }, numbers.SELECTED_TRIGGER_DELAY);
+  }
+
+  // Open the menu. Optionally focus on provided item.
+  open({focusIndex = null} = {}) {
+    this.adapter_.saveFocus();
     this.adapter_.addClass(MDLSimpleMenuFoundation.cssClasses.ANIMATING);
     requestAnimationFrame(() => {
       this.dimensions_ = this.adapter_.getInnerDimensions();
       this.applyTransitionDelays_();
       this.animateMenu_();
       this.adapter_.addClass(MDLSimpleMenuFoundation.cssClasses.OPEN);
+      this.focusOnOpen_(focusIndex);
+      this.adapter_.registerDocumentClickHandler(this.documentClickHandler_);
     });
     this.isOpen_ = true;
   }
 
   // Close the menu.
   close() {
+    this.adapter_.deregisterDocumentClickHandler(this.documentClickHandler_);
     this.adapter_.addClass(MDLSimpleMenuFoundation.cssClasses.ANIMATING);
     requestAnimationFrame(() => {
       this.removeTransitionDelays_();
       this.animateMenu_();
       this.adapter_.removeClass(MDLSimpleMenuFoundation.cssClasses.OPEN);
     });
     this.isOpen_ = false;
+    this.adapter_.restoreFocus();
   }
 
   isOpen() {

packages/mdl-menu/simple/index.js

@@ -38,6 +38,14 @@ export class MDLSimpleMenu extends MDLComponent {
     }
   }
 
+  show({focusIndex = null} = {}) {
+    this.foundation_.open({focusIndex: focusIndex});
+  }
+
+  hide() {
+    this.foundation_.close();
+  }
+
   /* Return the item container element inside the component. */
   get itemsContainer_() {
     return this.root_.querySelector(MDLSimpleMenuFoundation.strings.ITEMS_SELECTOR);
@@ -72,6 +80,8 @@ export class MDLSimpleMenu extends MDLComponent {
       getNumberOfItems: () => this.items.length,
       registerInteractionHandler: (type, handler) => this.root_.addEventListener(type, handler),
       deregisterInteractionHandler: (type, handler) => this.root_.removeEventListener(type, handler),
+      registerDocumentClickHandler: handler => document.addEventListener('click', handler),
+      deregisterDocumentClickHandler: handler => document.removeEventListener('click', handler),
       getYParamsForItemAtIndex: index => {
         const {offsetTop: top, offsetHeight: height} = this.items[index];
         return {top, height};
@@ -82,7 +92,20 @@ export class MDLSimpleMenu extends MDLComponent {
       notifySelected: evtData => this.emit('MDLSimpleMenu:selected', {
         index: evtData.index,
         item: this.items[evtData.index]
-      })
+      }),
+      notifyCancel: () => this.emit('MDLSimpleMenu:cancel'),
+      saveFocus: () => {
+        this.previousFocus_ = document.activeElement;
+      },
+      restoreFocus: () => {
+        if (this.previousFocus_) {
+          this.previousFocus_.focus();
+        }
+      },
+      isFocused: () => document.activeElement === this.root_,
+      focus: () => this.root_.focus(),
+      getFocusedItemIndex: () => this.items.indexOf(document.activeElement),
+      focusItemAtIndex: index => this.items[index].focus()
     });
   }
 

packages/mdl-menu/simple/mdl-simple-menu.scss

@@ -48,6 +48,10 @@ $mdl-simple-menu-item-offset: 10px;
     background-color: #424242;
   }
 
+  &:focus {
+    outline: none;
+  }
+
   &--open {
     display: inline-block;
     transform: scale(1);