docs(focus): Add docs and example for focus method

Author: Andrey Okonetchnikov

src/FocusWithin.js

@@ -1,31 +1,33 @@
-import React from 'react'
-import PropTypes from 'prop-types'
+import React from "react";
+import PropTypes from "prop-types";
 
 const noOutlineStyles = {
-  outline: 'none'
-}
+  outline: "none"
+};
 
 class FocusWithin extends React.Component {
   state = {
     focused: false
-  }
+  };
 
-  ref = React.createRef()
+  ref = React.createRef();
 
-  /** @public
-   * @function focus - calls `focus` method on the container node
-   * @return void
+  /**
+   * Calls `focus` method on the container node
+   *
+   * @public
+   * @method focus
    * */
   focus() {
-    const node = this.ref.current
-    if (node != null && typeof node.focus === 'function') {
-      node.focus()
+    const node = this.ref.current;
+    if (node != null && typeof node.focus === "function") {
+      node.focus();
     }
   }
 
   onFocus = evt => {
-    const { onFocus } = this.props
-    const { focused } = this.state
+    const { onFocus } = this.props;
+    const { focused } = this.state;
 
     // TODO: Figure out if this check is "safe" or we should rely on SCU instead
     if (!focused) {
@@ -34,61 +36,61 @@ class FocusWithin extends React.Component {
           focused: true
         },
         () => {
-          onFocus(evt)
+          onFocus(evt);
         }
-      )
+      );
     }
-  }
+  };
 
   onBlur = evt => {
-    const { onBlur } = this.props
-    const { focused } = this.state
+    const { onBlur } = this.props;
+    const { focused } = this.state;
 
     // Do not blur if focus within the container or we're editing
     if (this.isFocusWithin(this.ref.current)) {
-      evt.preventDefault()
-      evt.stopPropagation()
-      return
+      evt.preventDefault();
+      evt.stopPropagation();
+      return;
     }
 
     // Persist event object
-    evt.persist()
+    evt.persist();
 
     if (focused) {
       this.setState(
         {
           focused: false
         },
         () => {
-          onBlur(evt)
+          onBlur(evt);
         }
-      )
+      );
     }
-  }
+  };
 
   isFocusWithin = node => {
     // We need to check `:focus-within` on the the parent element in order to work
-    if (process.env.NODE_ENV === 'development') {
+    if (process.env.NODE_ENV === "development") {
       if (
         node == null ||
         node.parentNode == null ||
-        typeof node.parentNode.querySelector !== 'function'
+        typeof node.parentNode.querySelector !== "function"
       ) {
         throw new Error(
-          'A ref to a DOM Node with a valid parent Node must be supplied to' +
-            ' FocusWithin.\n' +
-            ' You have probably provided a ref to a React Element.\n See https://reactjs.org/docs/react-api.html#refs'
-        )
+          "A ref to a DOM Node with a valid parent Node must be supplied to" +
+            " FocusWithin.\n" +
+            " You have probably provided a ref to a React Element.\n See https://reactjs.org/docs/react-api.html#refs"
+        );
       }
     }
-    return !!node.parentNode.querySelector(':focus-within')
-  }
+    return !!node.parentNode.querySelector(":focus-within");
+  };
 
   render() {
-    const { children } = this.props
-    const { focused } = this.state
+    const { children } = this.props;
+    const { focused } = this.state;
 
-    if (typeof children === 'function') {
+    if (typeof children === "function") {
       return React.cloneElement(
         children({
           focused,
@@ -98,14 +100,19 @@ class FocusWithin extends React.Component {
           onFocus: this.onFocus,
           onBlur: this.onBlur
         }
-      )
+      );
     }
 
     return (
-      <div ref={this.ref} onFocus={this.onFocus} onBlur={this.onBlur} style={noOutlineStyles}>
+      <div
+        ref={this.ref}
+        onFocus={this.onFocus}
+        onBlur={this.onBlur}
+        style={noOutlineStyles}
+      >
         {children}
       </div>
-    )
+    );
   }
 }
 
@@ -117,11 +124,11 @@ FocusWithin.propTypes = {
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]).isRequired,
   onBlur: PropTypes.func,
   onFocus: PropTypes.func
-}
+};
 
 FocusWithin.defaultProps = {
   onBlur: () => {},
   onFocus: () => {}
-}
+};
 
-export default FocusWithin
+export default FocusWithin;

src/Readme.md

@@ -98,6 +98,32 @@ const StyledBox = styled("div")`
 
 _Note:_ It's recommended to use `:focus-within` selector instead of interpoaltions whenever possible.
 
+## Focus method
+
+Sometimes it's needed to focus the container node programmatically. You can use the public method
+`focus`. Note that `tabIndex={-1}` needs to be set on non-interactive elements to make them
+receive focus.
+
+```jsx harmony
+const ref = React.createRef();
+<div>
+  <FocusWithin ref={ref}>
+    {({ focused, getRef }) => (
+      <span tabIndex={-1} ref={getRef}>
+        {focused ? "Focused" : "Not focused"}
+      </span>
+    )}
+  </FocusWithin>
+  <button
+    onClick={() => {
+      ref.current.focus();
+    }}
+  >
+    Focus the span
+  </button>
+</div>;
+```
+
 ## Naïve focus trap implementation
 
 ```jsx harmony