feat(commands): Allow users to define custom omnibar commands (#2358)

* feat(commands): allow users to define custom omnibar commands

This introduces `api.addCommand(name, description, action)` to allow
users to add their own commands to the omnibar.

The implementation involves a message-passing architecture to
communicate between the user script context and the sandboxed UI
frame:

- A new `addCommand` function on the user-facing API stores the
command's action function and dispatches a registration event.
- The `front.js` content script forwards this event to the
`frontend.js` UI script.
- The UI script registers the command with the omnibar, creating a
proxy action.
- When the command is executed, this proxy dispatches an
 `executeUserCommand` event back to the user script context, which then
 looks up and runs the original function.

* docs: add `addCommand`

Author: twio142

docs/API.md

@@ -104,6 +104,9 @@
 *   [RUNTIME][100]
     *   [Parameters][101]
     *   [Examples][102]
+*   [addCommand][103]
+    *   [Parameters][104]
+    *   [Examples][105]
 
 ## mapkey
 
@@ -702,6 +705,24 @@ RUNTIME('getTabs', {queryInfo: {currentWindow: true}}, response => {
 });
 ```
 
+## addCommand
+
+Add a command into Omnibar.
+
+### Parameters
+
+*   `name` **[string][103]** the name of the command, used as command name in omnibar.
+*   `description` **[string][103]** a help message to describe the command.
+*   `jscode` **[function][104]** a Javascript function to be bound. If the command receives an argument, the argument will be passed to the function.
+
+### Examples
+
+```javascript
+addCommand("example", "An example command", function(arg) {
+    console.log("You entered: " + arg);
+});
+```
+
 [1]: #mapkey
 
 [2]: #parameters
@@ -906,22 +927,28 @@ RUNTIME('getTabs', {queryInfo: {currentWindow: true}}, response => {
 
 [102]: #examples-23
 
-[103]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[103]: #addcommand
+
+[104]: #parameters-38
+
+[105]: #examples-24
+
+[106]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[104]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[107]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[105]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[108]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[106]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[109]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[107]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[110]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[108]: https://developer.mozilla.org/docs/Web/HTML/Element
+[111]: https://developer.mozilla.org/docs/Web/HTML/Element
 
-[109]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[112]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[110]: https://github.com/brookhong/Surfingkeys/wiki/Register-inline-query
+[113]: https://github.com/brookhong/Surfingkeys/wiki/Register-inline-query
 
-[111]: https://developer.mozilla.org/docs/Web/API/Element
+[114]: https://developer.mozilla.org/docs/Web/API/Element
 
-[112]: https://github.com/ajaxorg/ace/blob/ec450c03b51aba3724cf90bb133708078d1f3de6/lib/ace/keyboard/vim.js#L927-L1099
+[115]: https://github.com/ajaxorg/ace/blob/ec450c03b51aba3724cf90bb133708078d1f3de6/lib/ace/keyboard/vim.js#L927-L1099

src/content_scripts/front.js

@@ -494,6 +494,13 @@ function createFront(insert, normal, hints, visual, browser) {
                 vimKeyMap
             });
         },
+        addCommand: (name, description) => {
+            applyUICommand({
+                action: 'addCommand',
+                name: name,
+                description: description
+            });
+        },
         highlightElement,
         hidePopup,
         openFinder: () => {
@@ -661,6 +668,10 @@ function createFront(insert, normal, hints, visual, browser) {
         visual.emptySelection();
     };
 
+    _actions["executeUserCommand"] = function(message) {
+        dispatchSKEvent('user', ['executeUserCommand', message.name, message.args]);
+    };
+
     var _active = window === top;
     _actions['deactivated'] = function(message) {
         _active = false;

src/content_scripts/ui/frontend.js

@@ -454,6 +454,16 @@ const Front = (function() {
     _actions['addVimKeyMap'] = function (message) {
         self.vimKeyMap = message.vimKeyMap;
     };
+    _actions['addCommand'] = function(message) {
+        const proxyAction = (...args) => {
+            self.contentCommand({
+                action: 'executeUserCommand',
+                name: message.name,
+                args: args
+            });
+        };
+        omnibar.command(message.name, message.description, proxyAction);
+    };
     _actions['getUsage'] = function (message) {
         // send response in callback from buildUsage
         delete message.ack;

src/user_scripts/index.js

@@ -50,6 +50,12 @@ function vmapkey(keys, annotation, jscode, options) {
    }
 }
 
+const userDefinedCommands = {};
+function addCommand(name, description, action) {
+    userDefinedCommands[name] = action;
+    dispatchSKEvent('front', ['addCommand', name, description]);
+}
+
 function map(new_keystroke, old_keystroke, domain, new_annotation) {
     dispatchSKEvent('api', ['map', new_keystroke, old_keystroke, domain, new_annotation]);
 }
@@ -76,6 +82,11 @@ initSKFunctionListener("user", {
             userDefinedFunctions[keys](para);
         }
     },
+    executeUserCommand: (name, args) => {
+        if (userDefinedCommands.hasOwnProperty(name)) {
+            userDefinedCommands[name](...args);
+        }
+    },
     getSearchSuggestions: (url, response, request, callbackId, origin) => {
         if (functionsToListSuggestions.hasOwnProperty(url)) {
             const ret = functionsToListSuggestions[url](response, request);
@@ -138,6 +149,7 @@ const api = {
     aceVimMap,
     addVimMapKey,
     addSearchAlias,
+    addCommand,
     cmap,
     imap,
     imapkey,