Add docs for registerKeyCommand and registerExpansion editor methods

fixes #150

README.md

@@ -124,6 +124,40 @@ For more details on the API of `postEditor`, see the [API documentation](https:/
 For more details on the API for the builder, required to create new sections
 and markers, see the [builder API](https://github.com/bustlelabs/content-kit-editor/blob/master/src/js/models/post-node-builder.js).
 
+### Configuring hot keys and text expansions
+
+Content-Kit allows configuring hot keys and text expansions. For instance, the
+hot-key command-B to make selected text bold, is registered internally as:
+```javascript
+const boldKeyCommand = {
+  modifier: META,
+  str: 'B',
+  run(editor) {
+    editor.run(postEditor => postEditor.toggleMarkup('strong'));
+  }
+};
+editor.registerKeyCommand(boldKeyCommand);
+```
+
+All key commands must have `modifier`, `str` and `run` properties as shown above.
+
+Text expansions can also be registered with the editor. These are methods that
+are run when a text string is entered and then a trigger character is entered.
+For example, the text `"*"` followed by a space character triggers a method that
+turns the current section into a list item. To register a text expansion call
+`editor.registerExpansion` with an object that has `text`, `trigger` and `run`
+properties, e.g.:
+
+```javascript
+const expansion = {
+  trigger: ' ',
+  text: 'X',
+  run(editor) {
+    // use the editor to programmatically change the post
+  }
+};
+```
+
 ### Contributing
 
 Fork the repo, write a test, make a change, open a PR.

src/js/editor/editor.js

@@ -182,13 +182,29 @@ class Editor {
     return this._keyCommands;
   }
 
+  /**
+   * @method registerExpansion
+   * @param {Object} expansion The text expansion to register. It must specify a
+   * trigger character (e.g. the `<space>` character) and a text string that precedes
+   * the trigger (e.g. "*"), and a `run` method that will be passed the
+   * editor instance when the text expansion is invoked
+   * @public
+   */
   registerExpansion(expansion) {
     if (!validateExpansion(expansion)) {
       throw new Error('Expansion is not valid');
     }
     this.expansions.push(expansion);
   }
 
+  /**
+   * @method registerKeyCommand
+   * @param {Object} keyCommand The key command to register. It must specify a
+   * modifier key (meta, ctrl, etc), a string representing the ascii key, and
+   * a `run` method that will be passed the editor instance when the key command
+   * is invoked
+   * @public
+   */
   registerKeyCommand(keyCommand) {
     if (!validateKeyCommand(keyCommand)) {
       throw new Error('Key Command is not valid');

src/js/editor/key-commands.js

@@ -2,43 +2,30 @@ import Key from '../utils/key';
 import { MODIFIERS } from '../utils/key';
 import { detect } from '../utils/array-utils';
 import LinkCommand from '../commands/link';
-import BoldCommand from '../commands/bold';
-import ItalicCommand from '../commands/italic';
-
-function runSelectionCommand(editor, CommandKlass) {
-  if (editor.cursor.hasSelection()) {
-    const cmd = new CommandKlass(editor);
-    if (cmd.isActive()) {
-      cmd.unexec();
-    } else {
-      cmd.exec();
-    }
-  }
-}
 
 export const DEFAULT_KEY_COMMANDS = [{
   modifier: MODIFIERS.META,
   str: 'B',
   run(editor) {
-    runSelectionCommand(editor, BoldCommand);
+    editor.run(postEditor => postEditor.toggleMarkup('strong'));
   }
 }, {
   modifier: MODIFIERS.CTRL,
   str: 'B',
   run(editor) {
-    runSelectionCommand(editor, BoldCommand);
+    editor.run(postEditor => postEditor.toggleMarkup('strong'));
   }
 }, {
   modifier: MODIFIERS.META,
   str: 'I',
   run(editor) {
-    runSelectionCommand(editor, ItalicCommand);
+    editor.run(postEditor => postEditor.toggleMarkup('em'));
   }
 }, {
   modifier: MODIFIERS.CTRL,
   str: 'I',
   run(editor) {
-    runSelectionCommand(editor, ItalicCommand);
+    editor.run(postEditor => postEditor.toggleMarkup('em'));
   }
 }, {
   modifier: MODIFIERS.META,