feat: allow configurable menu focus behavior (#286)

Author: jquense

package.json

@@ -66,49 +66,49 @@
   },
   "devDependencies": {
     "@4c/rollout": "^1.2.0",
-    "@babel/cli": "^7.2.0",
+    "@babel/cli": "^7.2.3",
     "@babel/core": "^7.2.2",
-    "@babel/plugin-proposal-class-properties": "^7.2.1",
-    "@babel/polyfill": "^7.0.0",
-    "@babel/preset-env": "^7.2.0",
+    "@babel/plugin-proposal-class-properties": "^7.3.0",
+    "@babel/polyfill": "^7.2.5",
+    "@babel/preset-env": "^7.3.1",
     "@babel/preset-react": "^7.0.0",
     "babel-eslint": "^10.0.1",
-    "babel-plugin-add-module-exports": "^0.2.1",
+    "babel-plugin-add-module-exports": "^1.0.0",
     "babel-plugin-istanbul": "^5.1.0",
     "chai": "^4.2.0",
-    "codecov": "^3.1.0",
+    "codecov": "^3.2.0",
     "enzyme": "^3.8.0",
-    "enzyme-adapter-react-16": "^1.7.1",
-    "eslint": "^5.10.0",
-    "eslint-config-prettier": "^3.3.0",
-    "eslint-plugin-mocha": "^5.2.0",
-    "eslint-plugin-react": "^7.11.1",
-    "gh-pages": "^1.2.0",
-    "husky": "^0.14.3",
+    "enzyme-adapter-react-16": "^1.9.1",
+    "eslint": "^5.13.0",
+    "eslint-config-prettier": "^4.0.0",
+    "eslint-plugin-mocha": "^5.3.0",
+    "eslint-plugin-react": "^7.12.4",
+    "gh-pages": "^2.0.1",
+    "husky": "^1.3.1",
     "jquery": "^3.3.1",
-    "karma": "^3.1.4",
+    "karma": "^4.0.0",
     "karma-chrome-launcher": "^2.2.0",
     "karma-coverage": "^1.1.2",
     "karma-mocha": "^1.3.0",
     "karma-mocha-reporter": "^2.2.5",
     "karma-sinon-chai": "^2.0.2",
     "karma-sourcemap-loader": "^0.3.7",
     "karma-webpack": "4.0.0-rc.1",
-    "lint-staged": "^7.2.2",
+    "lint-staged": "^8.1.4",
     "lodash": "^4.17.11",
     "mocha": "^5.2.0",
-    "prettier": "^1.15.3",
-    "react": "^16.6.3",
+    "prettier": "^1.16.4",
+    "react": "^16.8.2",
     "react-bootstrap": "^0.32.4",
-    "react-dom": "^16.6.3",
+    "react-dom": "^16.8.2",
     "react-live": "^1.12.0",
-    "react-transition-group": "^2.5.1",
-    "rimraf": "^2.6.2",
+    "react-transition-group": "^2.5.3",
+    "rimraf": "^2.6.3",
     "simulant": "^0.2.2",
     "sinon": "^6.2.0",
     "sinon-chai": "^3.3.0",
-    "webpack": "^4.28.0",
+    "webpack": "^4.29.3",
     "webpack-atoms": "^7.0.1",
-    "webpack-cli": "^3.1.2"
+    "webpack-cli": "^3.2.3"
   }
 }

src/Dropdown.js

@@ -29,6 +29,16 @@ const propTypes = {
    */
   drop: PropTypes.oneOf(['up', 'left', 'right', 'down']),
 
+  /**
+   * Controls the focus behavior for when the Dropdown is opened. Set to
+   * `true` to always focus the first menu item, `keyboard` to focus only when
+   * navigating via the keyboard, or `false` to disable completely
+   *
+   * The Default behavior is `false` **unless** the Menu has a `role="menu"`
+   * where it will default to `keyboard` to match the recommended [ARIA Authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/#menubutton).
+   */
+  focusFirstItemOnShow: PropTypes.oneOf([false, true, 'keyboard']),
+
   /**
    * A css slector string that will return __focusable__ menu items.
    * Selectors should be relative to the menu component:
@@ -125,6 +135,8 @@ class Dropdown extends React.Component {
     if (show && !prevOpen) {
       this.maybeFocusFirst();
     }
+    this._lastSourceEvent = null;
+
     if (!show && prevOpen) {
       // if focus hasn't already moved from the menu let's return it
       // to the toggle
@@ -159,7 +171,18 @@ class Dropdown extends React.Component {
   }
 
   maybeFocusFirst() {
-    if (!this.hasMenuRole()) return;
+    const type = this._lastSourceEvent;
+    let { focusFirstItemOnShow } = this.props;
+    if (focusFirstItemOnShow == null) {
+      focusFirstItemOnShow = this.hasMenuRole() ? 'keyboard' : false;
+    }
+
+    if (
+      focusFirstItemOnShow === false ||
+      (focusFirstItemOnShow === 'keyboard' && !/^key.+$/.test(type))
+    ) {
+      return;
+    }
 
     const { itemSelector } = this.props;
     let first = qsa(this.menu, itemSelector)[0];
@@ -172,16 +195,19 @@ class Dropdown extends React.Component {
 
   handleKeyDown = event => {
     const { key, target } = event;
-    const isInput = /input|textarea/i.test(target.tagName);
+
     // Second only to https://github.com/twbs/bootstrap/blob/8cfbf6933b8a0146ac3fbc369f19e520bd1ebdac/js/src/dropdown.js#L400
     // in inscrutability
+    const isInput = /input|textarea/i.test(target.tagName);
     if (
       isInput &&
       (key === ' ' || (key !== 'Escape' && this.menu.contains(target)))
     ) {
       return;
     }
 
+    this._lastSourceEvent = event.type;
+
     switch (key) {
       case 'ArrowUp': {
         let next = this.getNextFocusedChild(target, -1);
@@ -209,6 +235,7 @@ class Dropdown extends React.Component {
 
   toggleOpen(event) {
     let show = !this.props.show;
+
     this.props.onToggle(show, event);
   }
 

src/Overlay.js

@@ -1,5 +1,6 @@
 import PropTypes from 'prop-types';
 import elementType from 'prop-types-extra/lib/elementType';
+import componentOrElement from 'prop-types-extra/lib/componentOrElement';
 import React from 'react';
 import ReactDOM from 'react-dom';
 
@@ -168,6 +169,12 @@ Overlay.propTypes = {
   /** Specify where the overlay element is positioned in relation to the target element */
   placement: PropTypes.oneOf(placements),
 
+  /**
+   * A Node, Component instance, or function that returns either. The `container` will have the Portal children
+   * appended to it.
+   */
+  container: PropTypes.oneOfType([componentOrElement, PropTypes.func]),
+
   /**
    * Enables the Popper.js `flip` modifier, allowing the Overlay to
    * automatically adjust it's placement in case of overlap with the viewport or toggle.
@@ -211,7 +218,7 @@ Overlay.propTypes = {
    * Specify event for toggling overlay
    */
   rootCloseEvent: RootCloseWrapper.propTypes.event,
-  
+
   /**
    * Specify disabled for disable RootCloseWrapper
    */
@@ -271,6 +278,7 @@ Overlay.propTypes = {
 
 export default forwardRef(
   (props, ref) => (
+    // eslint-disable-next-line react/prop-types
     <WaitForContainer container={props.container}>
       {container => <Overlay {...props} ref={ref} container={container} />}
     </WaitForContainer>