Deprecated the coarse onArrowUp et al key handler props on DraftEditor.react to make it possible to produce editor commands from these keys

Summary:
Previously, it was impossible to do this:

```
function mapKeysToEditorCommands(e) {
  if (mentionsAutocompleteIsOpen) {
    switch (e.keyCode) {
      case Keys.UP:
        return 'MentionsAutocomplete/select-previous';
      case Keys.DOWN:
        return 'MentionsAutocomplete/select-next';
    }
  }
  return getDefaultKeyBinding(e);
}

<DraftEditor
  keyBindingFn={mapKeysToEditorCommands}
  ...
/>
```

…because we didn't give TAB, ESCAPE, LEFT, UP, RIGHT, or DOWN a chance to produce a command name.

This pull request:

1. deprecates the prop-based key handlers (`onUpArrow` et al.) and encourages people to move their custom key logic into a `keyBindingFn`, and
2. lets the named keypresses fall through to the `keyBindingFn` whenever a prop-based key handler isn't supplied.
3. Updates the homepage and the rich text example.

![tabs](https://user-images.githubusercontent.com/13243/35651838-f129bf4a-0695-11e8-971b-38dbae48fd23.gif)
Closes #1637

Differential Revision: D6864155

fbshipit-source-id: 23efb4caac25b1bc867350a1212f142b5b3ce7ab

Author: steveluscher

docs/APIReference-Editor.md

@@ -262,45 +262,22 @@ Handle other drop operations.
 
 ### Key Handlers (Optional)
 
-These prop functions expose common useful key events. Example: At Facebook, these are
-used to provide keyboard interaction for mention results in inputs.
+Draft lets you supply a custom `keyDown` handler that wraps or overrides its
+default one.
 
-#### onEscape
-```
-onEscape?: (e: SyntheticKeyboardEvent) => void
-```
-
-#### onTab
-```
-onTab?: (e: SyntheticKeyboardEvent) => void
-```
-
-#### onUpArrow
-```
-onUpArrow?: (e: SyntheticKeyboardEvent) => void
-```
-
-#### onRightArrow
-```
-onRightArrow?: (e: SyntheticKeyboardEvent) => void
-```
-
-#### onDownArrow
-```
-onDownArrow?: (e: SyntheticKeyboardEvent) => void
-```
 #### keyBindingFn
 
 ```
-keyBindingFn?: (e: SyntheticKeyboardEvent) => void
+keyBindingFn?: (e: SyntheticKeyboardEvent) => ?string
 ```
 
-This prop lets you handle key events directly and provides an opportunity to return custom editor commands. You can find a more detailed explanation of this [here](/docs/advanced-topics-key-bindings.html).
-
-#### onLeftArrow
-```
-onLeftArrow?: (e: SyntheticKeyboardEvent) => void
-```
+This prop function exposes `keyDown` events to a handler of your choosing. If an
+event of interest happens, you can perform custom logic and/or return a string
+corresponding to a `DraftEditorCommand` or a custom editor command of your
+own creation. Example: At Facebook, this is used to provide keyboard interaction
+for the mentions autocomplete menu that appears when typing a friend's name.
+You can find a more detailed explanation of this
+[here](/docs/advanced-topics-key-bindings.html).
 
 ### Mouse events
 

examples/draft-0-10-0/rich/rich.html

@@ -33,7 +33,7 @@
     <script type="text/babel">
       'use strict';
 
-      const {Editor, EditorState, RichUtils} = Draft;
+      const {Editor, EditorState, RichUtils, getDefaultKeyBinding} = Draft;
 
       class RichEditorExample extends React.Component {
         constructor(props) {
@@ -44,7 +44,7 @@
           this.onChange = (editorState) => this.setState({editorState});
 
           this.handleKeyCommand = this._handleKeyCommand.bind(this);
-          this.onTab = this._onTab.bind(this);
+          this.mapKeyToEditorCommand = this._mapKeyToEditorCommand.bind(this);
           this.toggleBlockType = this._toggleBlockType.bind(this);
           this.toggleInlineStyle = this._toggleInlineStyle.bind(this);
         }
@@ -58,9 +58,20 @@
           return false;
         }
 
-        _onTab(e) {
-          const maxDepth = 4;
-          this.onChange(RichUtils.onTab(e, this.state.editorState, maxDepth));
+        _mapKeyToEditorCommand(e) {
+          switch (e.keyCode) {
+            case 9: // TAB
+              const newEditorState = RichUtils.onTab(
+                e,
+                this.state.editorState,
+                4, /* maxDepth */
+              );
+              if (newEditorState !== this.state.editorState) {
+                this.onChange(newEditorState);
+              }
+              return;
+          }
+          return getDefaultKeyBinding(e);
         }
 
         _toggleBlockType(blockType) {
@@ -110,8 +121,8 @@
                   customStyleMap={styleMap}
                   editorState={editorState}
                   handleKeyCommand={this.handleKeyCommand}
+                  keyBindingFn={this.mapKeyToEditorCommand}
                   onChange={this.onChange}
-                  onTab={this.onTab}
                   placeholder="Tell a story..."
                   ref="editor"
                   spellCheck={true}

src/component/base/DraftEditor.react.js

@@ -165,6 +165,27 @@ class DraftEditor extends React.Component<DraftEditorProps, State> {
 
     this.getEditorKey = () => this._editorKey;
 
+    if (__DEV__) {
+      [
+        'onDownArrow',
+        'onEscape',
+        'onLeftArrow',
+        'onRightArrow',
+        'onTab',
+        'onUpArrow',
+      ].forEach(propName => {
+        if (props.hasOwnProperty(propName)) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `Supplying an \`${propName}\` prop to \`DraftEditor\` has ` +
+              'been deprecated. If your handler needs access to the keyboard ' +
+              'event, supply a custom `keyBindingFn` prop that falls back to ' +
+              'the default one (eg. https://is.gd/RG31RJ).',
+          );
+        }
+      });
+    }
+
     // See `restoreEditorDOM()`.
     this.state = {contentsKey: 0};
   }

src/component/base/DraftEditorProps.js

@@ -153,7 +153,7 @@ export type DraftEditorProps = {
   ) => DraftHandleValue,
 
   /**
-   * Non-cancelable event triggers.
+   * Deprecated event triggers.
    */
   onEscape?: (e: SyntheticKeyboardEvent<>) => void,
   onTab?: (e: SyntheticKeyboardEvent<>) => void,

src/component/handlers/edit/editOnKeyDown.js

@@ -87,7 +87,23 @@ function onKeyCommand(
 function editOnKeyDown(editor: DraftEditor, e: SyntheticKeyboardEvent<>): void {
   var keyCode = e.which;
   var editorState = editor._latestEditorState;
-
+  function callDeprecatedHandler(
+    handlerName:
+      | 'onDownArrow'
+      | 'onEscape'
+      | 'onLeftArrow'
+      | 'onRightArrow'
+      | 'onTab'
+      | 'onUpArrow',
+  ): boolean {
+    const deprecatedHandler = editor.props[handlerName];
+    if (deprecatedHandler) {
+      deprecatedHandler(e);
+      return true;
+    } else {
+      return false;
+    }
+  }
   switch (keyCode) {
     case Keys.RETURN:
       e.preventDefault();
@@ -102,23 +118,35 @@ function editOnKeyDown(editor: DraftEditor, e: SyntheticKeyboardEvent<>): void {
       break;
     case Keys.ESC:
       e.preventDefault();
-      editor.props.onEscape && editor.props.onEscape(e);
-      return;
+      if (callDeprecatedHandler('onEscape')) {
+        return;
+      }
+      break;
     case Keys.TAB:
-      editor.props.onTab && editor.props.onTab(e);
-      return;
+      if (callDeprecatedHandler('onTab')) {
+        return;
+      }
+      break;
     case Keys.UP:
-      editor.props.onUpArrow && editor.props.onUpArrow(e);
-      return;
+      if (callDeprecatedHandler('onUpArrow')) {
+        return;
+      }
+      break;
     case Keys.RIGHT:
-      editor.props.onRightArrow && editor.props.onRightArrow(e);
-      return;
+      if (callDeprecatedHandler('onRightArrow')) {
+        return;
+      }
+      break;
     case Keys.DOWN:
-      editor.props.onDownArrow && editor.props.onDownArrow(e);
-      return;
+      if (callDeprecatedHandler('onDownArrow')) {
+        return;
+      }
+      break;
     case Keys.LEFT:
-      editor.props.onLeftArrow && editor.props.onLeftArrow(e);
-      return;
+      if (callDeprecatedHandler('onLeftArrow')) {
+        return;
+      }
+      break;
     case Keys.SPACE:
       // Handling for OSX where option + space scrolls.
       if (isChrome && isOptionKeyCommand(e)) {

website/src/index.js

@@ -21,7 +21,7 @@ var unindent = require('unindent');
 var richExample = `
 'use strict';
 
-const {Editor, EditorState, RichUtils} = Draft;
+const {Editor, EditorState, RichUtils, getDefaultKeyBinding} = Draft;
 
 class RichEditorExample extends React.Component {
   constructor(props) {
@@ -32,7 +32,7 @@ class RichEditorExample extends React.Component {
     this.onChange = (editorState) => this.setState({editorState});
 
     this.handleKeyCommand = this._handleKeyCommand.bind(this);
-    this.onTab = this._onTab.bind(this);
+    this.mapKeyToEditorCommand = this._mapKeyToEditorCommand.bind(this);
     this.toggleBlockType = this._toggleBlockType.bind(this);
     this.toggleInlineStyle = this._toggleInlineStyle.bind(this);
   }
@@ -46,9 +46,20 @@ class RichEditorExample extends React.Component {
     return false;
   }
 
-  _onTab(e) {
-    const maxDepth = 4;
-    this.onChange(RichUtils.onTab(e, this.state.editorState, maxDepth));
+  _mapKeyToEditorCommand(e) {
+    switch (e.keyCode) {
+      case 9: // TAB
+        const newEditorState = RichUtils.onTab(
+          e,
+          this.state.editorState,
+          4, /* maxDepth */
+        );
+        if (newEditorState !== this.state.editorState) {
+          this.onChange(newEditorState);
+        }
+        return;
+    }
+    return getDefaultKeyBinding(e);
   }
 
   _toggleBlockType(blockType) {
@@ -98,8 +109,8 @@ class RichEditorExample extends React.Component {
             customStyleMap={styleMap}
             editorState={editorState}
             handleKeyCommand={this.handleKeyCommand}
+            keyBindingFn={this.mapKeyToEditorCommand}
             onChange={this.onChange}
-            onTab={this.onTab}
             placeholder="Tell a story..."
             ref={(ref) => this.editor = ref}
             spellCheck={true}