docs: toolbar docs for three different kinds of definitions

docs/latest/extensions/modules/toolbar.md

@@ -1,48 +1,130 @@
 # Module: Toolbar
 
-An extension can register a Toolbar Module by providing a `getToolbarModule()`
+An extension can register a Toolbar Module by defining a `getToolbarModule`
-method that returns a React Component. The component does not receive any props.
+method. This module is commonly used to define:
-If you want to modify or react to state, you will need to connect to the redux
-store. The given toolbar must determine its set of elements and the context of
-them. The set of elements will be listed on toolbar `definitions`.
 
-![Toolbar Extension](../assets/img/extensions-toolbar.gif)
+- [Toolbar buttons](#button-definitions)
+- [Nested toolbar menus](#nested-toolbar-menus)
+- [Custom components](#custom-components)
 
-<center><i>A toolbar extension example</i></center>
+![Toolbar Extension](../../assets/img/extensions-toolbar.gif)
 
-Toolbar components are rendered in the `ToolbarRow` component.
+<center><i>Example toolbar button using the Dialog Service to show CINE controls.</i></center>
 
-For a complete example implementation,
+## Example Toolbar Module
-[check out the OHIFCornerstoneViewport's Toolbar Module](https://github.com/OHIF/Viewers/blob/master/extensions/cornerstone/src/toolbarModule.js).
 
-## Toolbar Custom Component
+The Toolbar Module should return an array of `definitions` and a
-
+`defaultContext`. There are currently a few different variations of definitions,
-Toolbar elements can define its own custom react component to be consumed when
+each one is detailed further down.
-rendering it. So far, it accepts `Functional` and `Class` Components. For that,
-you just need to expose your `CustomToolbarComponent` as the value of key
-`CustomComponent`. In case the property `CustomComponent` is not present, a
-default toolbar component will be used to render it. See bellow
 
 ```js
-definitions: [
+export default {
-...
+  id: 'example-toolbar-module',
+
+  /**
+   * @param {object} params
+   * @param {ServicesManager} params.servicesManager
+   * @param {CommandsManager} params.commandsManager
+   */
+  getToolbarModule({ servicesManager, commandsManager }) {
+    return {
+      definitions: [
+        /* Array of definitions */
+      ],
+      defaultContext: ['ROUTE:VIEWER'],
+    };
+  },
+};
+```
+
+## Button Definitions
+
+The simplest definition has the following properties:
+
+```js
+{
+  id: 'StackScroll',
+  label: 'Stack Scroll',
+  icon: 'bars',
+  type: 'setToolActive',
+  commandName: 'setToolActive',
+  commandOptions: { toolName: 'StackScroll' },
+},
+```
+
+| property         | description                                                       | values                                    |
+| ---------------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| `id`             | Unique string identifier for the definition                       | \*                                        |
+| `label`          | User/display friendly to show in UI                               | \*                                        |
+| `icon`           | A string name for an icon supported by the consuming application. | \*                                        |
+| `type`           | Used to determine the button's component and behavior             | `"setToolActive"`, `"command"`            |
+| `commandName`    | (optional) The command to run when the button is used.            | Any command registed by a `CommandModule` |
+| `commandOptions` | (optional) Options to pass the target `commandName`               | \*                                        |
+| `context`        | (optional) Overrides module's `defaultContext`                    | Array of string context names             |
+
+Where a button with a `type` of `setToolActive` has an "active" styling applied
+when clicked; removing the active styling from all other buttons.
+
+## Nested Toolbar Menus
+
+You can indicate that buttons should be grouped and nested in a submenu by
+including `buttons` property in a definition:
+
+```js
+{
+  id: 'More',
+  label: 'More',
+  icon: 'ellipse-circle',
+  buttons: [
     {
+      id: 'cstInvert',
+      label: 'Invert',
+      icon: 'circle',
+      type: 'command',
+      commandName: 'invertViewport',
+    },
+  ],
+},
+```
+
+![Toolbar Extension](../../assets/img/extensions-toolbar-nested.gif)
+
+<center><i>Example toolbar button demonstrating nested buttons.</i></center>
+
+## Custom Components
+
+The Toolbar Modules supports rendering custom components in place of the
+application's default. In place of the `type`, `commandName`, and
+`commandOptions` properties, we instead specify a `CustomComponent`.
+
+```js
+{
   id: 'Custom',
   label: 'Custom',
   icon: 'custom-icon',
   CustomComponent: CustomToolbarComponent,
-    }
+}
-...
-]
 
 ```
 
-`CustomComponent` components will receive the following props:
+The `CustomComponent` components will receive the following props:
 
-- parentContext: parent context. (In most of the cases it will be a ToolbarRow
+```html
-  instance)
+<CustomComponent
-- toolbarClickCallback: callback method when clicking on toolbar
+  parentContext="{parentContext}"
-- button: its own definition object
+  toolbarClickCallback="{_handleToolbarButtonClick.bind(this)}"
-- key: react key prop
+  button="{button}"
-- activeButtons: list of active elements
+  key="{button.id}"
-- isActive: if current
+  activeButtons="{activeButtonsIds}"
+  isActive="{isActive}"
+/>
+```
+
+| Property               | Type     | Description                     |
+| ---------------------- | -------- | ------------------------------- |
+| `activeButtons`        | string[] | list of active buttons          |
+| `button`               | object   | its own definition object       |
+| `key`                  | string   | React key prop                  |
+| `isActive`             | boolean  | If current button is active     |
+| `parentContext`        | ?        | The parent component's context? |
+| `toolbarClickCallback` | func     | Callback method for clicks      |