[ADD] frontend: documentation for the editor's Powerbox

This adds a simple documentation for the editor's Powerbox and creates
the base for the editor's own documentation in general.

closes odoo/documentation#2586

Signed-off-by: Antoine Guenet (age) <age@odoo.com>

content/developer/reference/frontend.rst

@@ -19,4 +19,5 @@ JavaScript framework
     frontend/javascript_reference
     frontend/mobile
     frontend/qweb
+    frontend/odoo_editor
     frontend/icons_library

content/developer/reference/frontend/odoo_editor.rst

@@ -0,0 +1,231 @@
+===========
+Odoo Editor
+===========
+
+Odoo Editor is Odoo's own rich text editor. Its sources can be found in the
+`odoo-editor directory
+<{GITHUB_PATH}/addons/web_editor/static/src/js/editor/odoo-editor>`_.
+
+Powerbox
+========
+
+The Powerbox is a piece of user interface that contains
+:ref:`commands <reference/frontend/odoo_editor/powerbox/command>` organized
+into :ref:`categories <reference/frontend/odoo_editor/powerbox/category>`. It
+appears when typing `/` in the editor. The commands can be filtered when the
+user inputs text, and navigated with the arrow keys.
+
+.. image:: odoo_editor/powerbox.png
+   :align: center
+   :alt: The Powerbox opened after typing "/".
+
+Modifying the Powerbox
+----------------------
+
+Only one Powerbox should be instantiated at the time, and that job is done by
+the editor itself. Its Powerbox instance can be found in its `powerbox` instance
+variable.
+To change the Powerbox's contents and options, change the options passed to the
+editor before it gets instantiated.
+
+.. important::
+   Never instantiate the Powerbox yourself. Always use the current editor's own
+   instance instead.
+
+.. example::
+    Say we want to add a new command `Document` to the Powerbox, just for the
+    `mass_mailing` module. We want to add it to a new category called
+    `Documentation` and we want it all the way at the top of the Powerbox.
+
+    `mass_mailing` `extends
+    <{GITHUB_PATH}/addons/mass_mailing/static/src/js/wysiwyg.js>`_
+    `web_editor`'s `Wysiwyg class
+    <{GITHUB_PATH}/addons/web_editor/static/src/js/wysiwyg/wysiwyg.js>`_, which
+    instantiates the editor in its `start` method. Before doing so, it
+    calls its own `_getPowerboxOptions` method, which can conveniently be
+    overridden to add our new commands.
+
+    Since `mass_mailing` already overrides `_getPowerboxOptions`, let's just add
+    our new command to it:
+
+    .. code-block:: javascript
+
+      _getPowerboxOptions: function () {
+          const options = this._super();
+          // (existing code before the return statement)
+          options.categories.push({
+              name: _t('Documentation'),
+              priority: 300,
+          });
+          options.commands.push({
+              name: _t('Document'),
+              category: _t('Documentation'),
+              description: _t("Add this text to your mailing's documentation"),
+              fontawesome: 'fa-book',
+              priority: 1, // This is the only command in its category anyway.
+          });
+          return options;
+      }
+
+    .. important::
+      In order to allow the names and descriptions of your commands and
+      categories to be translated, make sure to wrap them in the `_t` function.
+
+    .. tip::
+      To avoid out-of-control escalations, don't use random numbers for your
+      priorities: look at which other priorities already exist and choose your
+      value accordingly (like you would do for a `z-index`).
+
+Opening a custom Powerbox
+-------------------------
+
+It is possible to open the Powerbox with a custom set of categories and
+commands, bypassing all pre-existing ones. To do that, call the `open` method of
+the Powerbox and pass it your custom commands and categories.
+
+.. image:: odoo_editor/powerbox-custom.png
+   :align: center
+   :alt: The Powerbox opened with custom categories and commands when pasting an
+         image URL.
+
+.. example::
+    We need the current instance of the Powerbox, which can be found in the
+    current editor. In the `Wysiwyg class
+    <{GITHUB_PATH}/addons/web_editor/static/src/js/wysiwyg/wysiwyg.js>`_, you
+    will find it as `this.odooEditor.powerbox`.
+
+    Now to open it with our custom "Document" command in a custom
+    "Documentation" category:
+
+    .. code-block:: javascript
+
+      this.odooEditor.powerbox.open(
+          [{
+              name: _t('Document'),
+              category: _t('Documentation'),
+              description: _t("Add this text to your mailing's documentation"),
+              fontawesome: 'fa-book',
+              priority: 1, // This is the only command in its category anyway.
+          }],
+          [{
+              name: _t('Documentation'),
+              priority: 300,
+          }]
+      );
+
+Filtering commands
+------------------
+
+There are three ways to filter commands:
+
+#. Via the `powerboxFilters`
+   :ref:`Powerbox option <reference/frontend/odoo_editor/powerbox/options>`.
+#. Via a given
+   :ref:`command <reference/frontend/odoo_editor/powerbox/command>`'s
+   `isDisabled` entry.
+#. The user can filter commands by simply typing text after opening the
+   Powerbox. It will fuzzy-match that text with the names of the categories and
+   commands.
+
+.. image:: odoo_editor/powerbox-filtered.png
+   :align: center
+   :alt: The Powerbox with its commands filtered using the word "head".
+
+Reference
+---------
+
+.. _reference/frontend/odoo_editor/powerbox/category:
+
+Category
+~~~~~~~~
+
+.. list-table::
+    :widths: 20 20 60
+    :header-rows: 1
+
+    * - Name
+      - Type
+      - Description
+    * - `name`
+      - `string`
+      - the name of the category
+    * - `priority`
+      - `number`
+      - used to order the category: a category with a higher priority is
+        displayed higher into the Powerbox (categories with the same priority
+        are ordered alphabetically)
+
+.. note::
+    If several categories exist with the same name, they will be grouped into
+    one. Its priority will be that defined in the version of the category that
+    was declared last.
+
+.. _reference/frontend/odoo_editor/powerbox/command:
+
+Command
+~~~~~~~
+
+.. list-table::
+    :widths: 20 20 60
+    :header-rows: 1
+
+    * - Name
+      - Type
+      - Description
+    * - `name`
+      - `string`
+      - the name of the command
+    * - `category`
+      - `string`
+      - the name of the category the command belongs to
+    * - `description`
+      - `string`
+      - a short text to describe the command
+    * - `fontawesome`
+      - `string`
+      - the name of a *Font Awesome* that will serve as the command's icon
+    * - `priority`
+      - `number`
+      - used to order the command: a command with a higher priority is displayed
+        higher into the Powerbox (commands with the same priority are ordered
+        alphabetically)
+    * - `callback`
+      - `function` (`() => void`)
+      - the function to execute when the command is picked (can be asynchronous)
+    * - `isDisabled` (optional)
+      - `function` (`() => void`)
+      - a function used to disable the command under certain conditions (when it
+        returns `true`, the command will be disabled)
+
+.. note::
+    If the command points to a category that doesn't exist yet, that category
+    will be created and appended at the end of the Powerbox.
+
+.. _reference/frontend/odoo_editor/powerbox/options:
+
+Options
+~~~~~~~
+
+The following options can be passed to OdooEditor, that will then be passed to
+the instance of the Powerbox:
+
+.. list-table::
+    :widths: 20 20 60
+    :header-rows: 1
+
+    * - Name
+      - Type
+      - Description
+    * - `commands`
+      - `array of commands`
+      - commands to add to the default defined by the editor
+    * - `categories`
+      - `array of categories`
+      - categories to add to the default defined by the editor
+    * - `powerboxFilters`
+      - `array of functions` (`commands => commands`)
+      - functions used to filter commands displayed in the Powerbox
+    * - `getContextFromParentRect`
+      - `function` (`() => DOMRect`)
+      - a function that returns the `DOMRect` of an ancestor of the editor (can
+        be useful when the editor is in an iframe)