Merge pull request #18 from HubSpot/separate-key-command-controller

Separate key command controller and add Toolbar component

Author: benbriggs

README.md

@@ -110,3 +110,48 @@ const EditorWithPlugins = plugins(Editor);
 const toHTML = plugins(convertToHTML);
 const fromHTML = plugins(convertFromHTML);
 ```
+
+***
+
+## KeyCommandController
+**Higher-order component to consolidate key command listeners across the component tree**
+
+An increasingly common pattern for rich text editors is a toolbar detached from the main `Editor` component. This toolbar will be outside of the `Editor` component subtree, but will often need to respond to key commands that would otherwise be encapsulated by the `Editor`. `KeyCommandController` is a higher-order component that allows the subscription to key commands to move up the React tree so that components outside that subtree may listen and emit changes to editor state. `KeyCommandController`. It may be used with any component, but a good example is the `Toolbar` component:
+
+```javascript
+import {Editor, Toolbar, KeyCommandController, compose} from 'draft-extend';
+
+const plugins = compose(
+  FirstPlugin,
+  SecondPlugin
+);
+
+const WrappedEditor = plugins(Editor);
+const WrappedToolbar = plugins(Toolbar);
+
+const Parent = ({editorState, onChange, handleKeyCommand, addKeyCommandListener, removeKeyCommandListener}) => {
+  return (
+    <div>
+      <WrappedEditor
+        editorState={editorState}
+        onChange={onChange}
+        handleKeyCommand={handleKeyCommand}
+        addKeyCommandListener={addKeyCommandListener}
+        removeKeyCommandListener={removeKeyCommandListener}
+      />
+      <WrappedToolbar
+        editorState={editorState}
+        onChange={onChange}
+        addKeyCommandListener={addKeyCommandListener}
+        removeKeyCommandListener={removeKeyCommandListener}
+      />
+    </div>
+  );
+};
+
+export default KeyCommandController(Parent);
+```
+
+`KeyCommandController` provides the final `handleKeyCommand` to use in the `Editor` component as well as subscribe/unsubscribe functions. As long as these props are passed from some common parent wrapped with `KeyCommandController` that also receives `editorState` and `onChange` props, other components may subscribe and emit chagnes to the editor state.
+
+Additionally, `KeyCommandController`s are composable and will defer to the highest parent instance. That is, if a `KeyCommandController` receives `handleKeyCommand`, `addKeyCommandListener`, and `removeKeyCommandListener` props (presumably from another controller) it will delegate to that controller's record of subscribed functions, keeping all listeners in one place.

example/blockStyles.html

@@ -33,6 +33,8 @@
 
       const {
         Editor,
+        Toolbar,
+        KeyCommandController,
         createPlugin
       } = window.DraftExtend;
 
@@ -88,6 +90,7 @@
       });
 
       const WithPlugin = BlockPlugin(Editor);
+      const WithPluginToolbar = BlockPlugin(Toolbar);
       const toHTML = BlockPlugin(convertToHTML);
       const fromHTML = BlockPlugin(convertFromHTML);
 
@@ -107,16 +110,26 @@
 
         render() {
           return (
-            <WithPlugin
-              editorState={this.state.editorState}
-              onChange={this.onChange}
-            />
+            <div>
+              <WithPlugin
+                {...this.props}
+                editorState={this.state.editorState}
+                onChange={this.onChange}
+              />
+              <WithPluginToolbar
+                {...this.props}
+                editorState={this.state.editorState}
+                onChange={this.onChange}
+              />
+            </div>
           );
         }
       });
 
+      const WrappedComponent = KeyCommandController(BlockStylesExample);
+
       ReactDOM.render(
-        <BlockStylesExample />,
+        <WrappedComponent />,
         document.getElementById('target')
       );
     </script>

example/inlineStyles.html

@@ -111,6 +111,7 @@
             <WithPlugin
               editorState={this.state.editorState}
               onChange={this.onChange}
+              keyCommandListeners={[Draft.RichUtils.handleKeyCommand]}
             />
           );
         }

src/components/Editor.js

@@ -6,6 +6,7 @@ import {
   CompositeDecorator,
   getDefaultKeyBinding
 } from 'draft-js';
+import KeyCommandController from './KeyCommandController';
 import OverlayWrapper from './OverlayWrapper';
 
 const propTypes = {
@@ -19,16 +20,18 @@ const propTypes = {
   blockRendererFn: PropTypes.func,
   blockStyleFn: PropTypes.func,
   keyBindingFn: PropTypes.func,
-  keyCommandListeners: PropTypes.arrayOf(PropTypes.func),
+  addKeyCommandListener: PropTypes.func.isRequired,
+  removeKeyCommandListener: PropTypes.func.isRequired,
   handleReturn: PropTypes.func,
   onEscape: PropTypes.func,
   onTab: PropTypes.func,
   onUpArrow: PropTypes.func,
   onDownArrow: PropTypes.func,
-  readOnly: PropTypes.bool
+  readOnly: PropTypes.bool,
+  showButtons: PropTypes.bool
 };
 
-export default React.createClass({
+const EditorWrapper = React.createClass({
   propTypes,
 
   childContextTypes: {
@@ -52,8 +55,8 @@ export default React.createClass({
       blockRendererFn: () => {},
       blockStyleFn: () => {},
       keyBindingFn: () => {},
-      keyCommandListeners: [],
-      readOnly: false
+      readOnly: false,
+      showButtons: true
     };
   },
 
@@ -76,10 +79,6 @@ export default React.createClass({
     };
   },
 
-  componentWillMount() {
-    this.keyCommandListeners = List(this.props.keyCommandListeners);
-  },
-
   componentWillReceiveProps(nextProps) {
     if (nextProps.decorators.length === this.state.decorator._decorators.length) {
       const allDecoratorsMatch = this.state.decorator._decorators.every((decorator, i) => {
@@ -93,16 +92,6 @@ export default React.createClass({
     this.setState({decorator: new CompositeDecorator(nextProps.decorators)});
   },
 
-  addKeyCommandListener(listener) {
-    this.keyCommandListeners = this.keyCommandListeners.unshift(listener);
-  },
-
-  removeKeyCommandListener(listener) {
-    this.keyCommandListeners = this.keyCommandListeners.filterNot((l) => {
-      return l === listener;
-    });
-  },
-
   keyBindingFn(e) {
     const pluginsCommand = this.props.keyBindingFn(e);
     if (pluginsCommand) {
@@ -112,61 +101,24 @@ export default React.createClass({
     return getDefaultKeyBinding(e);
   },
 
-  handleKeyCommand(command, keyboardEvent = null) {
-    const decoratedState = this.getDecoratedState();
-
-    const result = this.keyCommandListeners.reduce(({state, hasChanged}, listener) => {
-      if (hasChanged === true) {
-        return {
-          state,
-          hasChanged
-        };
-      }
-
-      const listenerResult = listener(state, command, keyboardEvent);
-      const isEditorState = listenerResult instanceof EditorState;
-
-      if (listenerResult === true || (isEditorState && listenerResult !== state)) {
-        if (isEditorState) {
-          this.props.onChange(listenerResult);
-          return {
-            state: listenerResult,
-            hasChanged: true
-          };
-        }
-        return {
-          state,
-          hasChanged: true
-        };
-      }
-
-      return {
-        state,
-        hasChanged
-      };
-    }, {state: decoratedState, hasChanged: false});
-
-    return result.hasChanged;
-  },
-
   handleReturn(e) {
-    return (this.props.handleReturn && this.props.handleReturn(e)) || this.handleKeyCommand('return', e);
+    return (this.props.handleReturn && this.props.handleReturn(e)) || this.props.handleKeyCommand('return', e);
   },
 
   onEscape(e) {
-    return (this.props.onEscape && this.props.onEscape(e)) || this.handleKeyCommand('escape', e);
+    return (this.props.onEscape && this.props.onEscape(e)) || this.props.handleKeyCommand('escape', e);
   },
 
   onTab(e) {
-    return (this.props.onTab && this.props.onTab(e)) || this.handleKeyCommand('tab', e);
+    return (this.props.onTab && this.props.onTab(e)) || this.props.handleKeyCommand('tab', e);
   },
 
   onUpArrow(e) {
-    return (this.props.onUpArrow && this.props.onUpArrow(e)) || this.handleKeyCommand('up-arrow', e);
+    return (this.props.onUpArrow && this.props.onUpArrow(e)) || this.props.handleKeyCommand('up-arrow', e);
   },
 
   onDownArrow(e) {
-    return (this.props.onDownArrow && this.props.onDownArrow(e)) || this.handleKeyCommand('down-arrow', e);
+    return (this.props.onDownArrow && this.props.onDownArrow(e)) || this.props.handleKeyCommand('down-arrow', e);
   },
 
   focus() {
@@ -213,23 +165,41 @@ export default React.createClass({
   },
 
   renderPluginButtons() {
+    const {
+      onChange,
+      addKeyCommandListener,
+      removeKeyCommandListener,
+      showButtons
+    } = this.props;
+
+    if (showButtons === false) {
+      return null;
+    }
+
     const decoratedState = this.getDecoratedState();
 
     return this.props.buttons.map((Button, index) => {
       return (
         <Button
           {...this.getOtherProps()}
-          addKeyCommandListener={this.addKeyCommandListener}
+          key={`button-${index}`}
+          attachedToEditor={true}
           editorState={decoratedState}
-          key={`button${index}`}
-          onChange={this.props.onChange}
-          removeKeyCommandListener={this.removeKeyCommandListener}
+          onChange={onChange}
+          addKeyCommandListener={addKeyCommandListener}
+          removeKeyCommandListener={removeKeyCommandListener}
         />
       );
     });
   },
 
   renderOverlays() {
+    const {
+      onChange,
+      addKeyCommandListener,
+      removeKeyCommandListener
+    } = this.props;
+
     const decoratedState = this.getDecoratedState();
 
     return this.props.overlays.map((Overlay, index) => {
@@ -238,9 +208,9 @@ export default React.createClass({
           <Overlay
             {...this.getOtherProps()}
             editorState={decoratedState}
-            onChange={this.props.onChange}
-            addKeyCommandListener={this.addKeyCommandListener}
-            removeKeyCommandListener={this.removeKeyCommandListener}
+            onChange={onChange}
+            addKeyCommandListener={addKeyCommandListener}
+            removeKeyCommandListener={removeKeyCommandListener}
           />
         </OverlayWrapper>
       );
@@ -253,6 +223,7 @@ export default React.createClass({
       blockRendererFn,
       blockStyleFn,
       onChange,
+      handleKeyCommand,
       ...otherProps
     } = this.props;
 
@@ -273,8 +244,8 @@ export default React.createClass({
             blockStyleFn={blockStyleFn}
             blockRendererFn={blockRendererFn}
             customStyleMap={styleMap}
+            handleKeyCommand={handleKeyCommand}
             keyBindingFn={this.keyBindingFn}
-            handleKeyCommand={this.handleKeyCommand}
             handleReturn={this.handleReturn}
             onEscape={this.onEscape}
             onTab={this.onTab}
@@ -292,3 +263,5 @@ export default React.createClass({
     );
   }
 });
+
+export default KeyCommandController(EditorWrapper);