[Feature] Multiple toolbox items for single tool

docs/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+### 2.25.0
+
+- `New` — *Tools API* — Introducing new feature — toolbox now can have multiple entries for one tool! <br>
+Due to that API changes: tool's `toolbox` getter now can return either a single config item or an array of config items
+
 ### 2.24.4
 
 - `Fix` — Keyboard selection by word [2045](https://github.com/codex-team/editor.js/issues/2045)

docs/tools.md

@@ -56,7 +56,7 @@ Options that Tool can specify. All settings should be passed as static propertie
 
 | Name | Type | Default Value | Description |
 | -- | -- | -- | -- |
-| `toolbox` | _Object_ | `undefined` | Pass here `icon` and `title` to display this `Tool` in the Editor's `Toolbox` <br /> `icon` - HTML string with icon for Toolbox <br /> `title` - optional title to display in Toolbox |
+| `toolbox` | _Object_ | `undefined` | Pass the `icon` and the `title` there to display this `Tool` in the Editor's `Toolbox` <br /> `icon` - HTML string with icon for the Toolbox <br /> `title` - title to be displayed at the Toolbox. <br /><br />May contain an array of `{icon, title, data}` to display the several variants of the tool, for example "Ordered list", "Unordered list". See details at [the documentation](https://editorjs.io/tools-api#toolbox) |
 | `enableLineBreaks` | _Boolean_ | `false` | With this option, Editor.js won't handle Enter keydowns. Can be helpful for Tools like `<code>` where line breaks should be handled by default behaviour. |
 | `isInline` | _Boolean_ | `false` | Describes Tool as a [Tool for the Inline Toolbar](tools-inline.md) |
 | `isTune` | _Boolean_ | `false` | Describes Tool as a [Block Tune](block-tunes.md) |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@editorjs/editorjs",
-  "version": "2.24.3",
+  "version": "2.25.0",
   "description": "Editor.js — Native JS, based on API and Open Source",
   "main": "dist/editor.js",
   "types": "./types/index.d.ts",

src/components/block/index.ts

@@ -4,7 +4,8 @@ import {
   BlockToolData,
   BlockTune as IBlockTune,
   SanitizerConfig,
-  ToolConfig
+  ToolConfig,
+  ToolboxConfigEntry
 } from '../../../types';
 
 import { SavedData } from '../../../types/data-formats';
@@ -734,6 +735,48 @@ export default class Block extends EventsDispatcher<BlockEvents> {
     }
   }
 
+  /**
+   * Tool could specify several entries to be displayed at the Toolbox (for example, "Heading 1", "Heading 2", "Heading 3")
+   * This method returns the entry that is related to the Block (depended on the Block data)
+   */
+  public async getActiveToolboxEntry(): Promise<ToolboxConfigEntry | undefined> {
+    const toolboxSettings = this.tool.toolbox;
+
+    /**
+     * If Tool specifies just the single entry, treat it like an active
+     */
+    if (toolboxSettings.length === 1) {
+      return Promise.resolve(this.tool.toolbox[0]);
+    }
+
+    /**
+     * If we have several entries with their own data overrides,
+     * find those who matches some current data property
+     *
+     * Example:
+     *  Tools' toolbox: [
+     *    {title: "Heading 1", data: {level: 1} },
+     *    {title: "Heading 2", data: {level: 2} }
+     *  ]
+     *
+     *  the Block data: {
+     *    text: "Heading text",
+     *    level: 2
+     *  }
+     *
+     *  that means that for the current block, the second toolbox item (matched by "{level: 2}") is active
+     */
+    const blockData = await this.data;
+    const toolboxItems = toolboxSettings;
+
+    return toolboxItems.find((item) => {
+      return Object.entries(item.data)
+        .some(([propName, propValue]) => {
+          return blockData[propName] && _.equals(blockData[propName], propValue);
+        });
+    });
+  }
+
   /**
    * Make default Block wrappers and put Tool`s content there
    *

src/components/modules/api/blocks.ts

@@ -3,6 +3,7 @@ import { BlockToolData, OutputData, ToolConfig } from '../../../../types';
 import * as _ from './../../utils';
 import BlockAPI from '../../block/api';
 import Module from '../../__module';
+import Block from '../../block';
 
 /**
  * @class BlocksAPI
@@ -31,6 +32,7 @@ export default class BlocksAPI extends Module {
       insertNewBlock: (): void => this.insertNewBlock(),
       insert: this.insert,
       update: this.update,
+      composeBlockData: this.composeBlockData,
     };
   }
 
@@ -247,6 +249,27 @@ export default class BlocksAPI extends Module {
     return new BlockAPI(insertedBlock);
   }
 
+  /**
+   * Retrieves default block data by creating fake block.
+   * Merges retrieved data with specified data object.
+   *
+   * @param toolName - block tool name
+   * @param dataOverrides - object containing overrides for default block data
+   */
+  public composeBlockData = async (toolName: string, dataOverrides = {}): Promise<BlockToolData> => {
+    const tool = this.Editor.Tools.blockTools.get(toolName);
+    const block = new Block({
+      tool,
+      api: this.Editor.API,
+      readOnly: true,
+      data: {},
+      tunesData: {},
+    });
+    const blockData = await block.data;
+
+    return Object.assign(blockData, dataOverrides);
+  }
+
   /**
    * Insert new Block
    * After set caret to this Block

src/components/modules/renderer.ts

@@ -100,8 +100,9 @@ export default class Renderer extends Module {
 
       if (Tools.unavailable.has(tool)) {
         const toolboxSettings = (Tools.unavailable.get(tool) as BlockTool).toolbox;
+        const toolboxTitle = toolboxSettings[0]?.title;
 
-        stubData.title = toolboxSettings?.title || stubData.title;
+        stubData.title = toolboxTitle || stubData.title;
       }
 
       const stub = BlockManager.insert({

src/components/modules/toolbar/conversion.ts

@@ -6,6 +6,7 @@ import Flipper from '../../flipper';
 import I18n from '../../i18n';
 import { I18nInternalNS } from '../../i18n/namespace-internal';
 import { clean } from '../../utils/sanitizer';
+import { ToolboxConfigEntry, BlockToolData } from '../../../../types';
 
 /**
  * HTML Elements used for ConversionToolbar
@@ -47,9 +48,9 @@ export default class ConversionToolbar extends Module<ConversionToolbarNodes> {
   public opened = false;
 
   /**
-   * Available tools
+   * Available tools data
    */
-  private tools: { [key: string]: HTMLElement } = {};
+  private tools: {name: string; toolboxItem: ToolboxConfigEntry; button: HTMLElement}[] = []
 
   /**
    * Instance of class that responses for leafing buttons by arrows/tab
@@ -135,19 +136,18 @@ export default class ConversionToolbar extends Module<ConversionToolbarNodes> {
     this.nodes.wrapper.classList.add(ConversionToolbar.CSS.conversionToolbarShowed);
 
     /**
-     * We use timeout to prevent bubbling Enter keydown on first dropdown item
+     * We use RAF to prevent bubbling Enter keydown on first dropdown item
      * Conversion flipper will be activated after dropdown will open
      */
-    setTimeout(() => {
-      this.flipper.activate(Object.values(this.tools).filter((button) => {
+    window.requestAnimationFrame(() => {
+      this.flipper.activate(this.tools.map(tool => tool.button).filter((button) => {
         return !button.classList.contains(ConversionToolbar.CSS.conversionToolHidden);
       }));
       this.flipper.focusFirst();
-
       if (_.isFunction(this.togglingCallback)) {
         this.togglingCallback(true);
       }
-    }, 50);
+    });
   }
 
   /**
@@ -167,36 +167,30 @@ export default class ConversionToolbar extends Module<ConversionToolbarNodes> {
    * Returns true if it has more than one tool available for convert in
    */
   public hasTools(): boolean {
-    const tools = Object.keys(this.tools); // available tools in array representation
+    if (this.tools.length === 1) {
+      return this.tools[0].name !== this.config.defaultBlock;
+    }
 
-    return !(tools.length === 1 && tools.shift() === this.config.defaultBlock);
+    return true;
   }
 
   /**
    * Replaces one Block with another
    * For that Tools must provide import/export methods
    *
    * @param {string} replacingToolName - name of Tool which replaces current
+   * @param blockDataOverrides - Block data overrides. Could be passed in case if Multiple Toolbox items specified
    */
-  public async replaceWithBlock(replacingToolName: string): Promise<void> {
+  public async replaceWithBlock(replacingToolName: string, blockDataOverrides?: BlockToolData): Promise<void> {
     /**
      * At first, we get current Block data
      *
      * @type {BlockToolConstructable}
      */
     const currentBlockTool = this.Editor.BlockManager.currentBlock.tool;
-    const currentBlockName = this.Editor.BlockManager.currentBlock.name;
     const savedBlock = await this.Editor.BlockManager.currentBlock.save() as SavedData;
     const blockData = savedBlock.data;
 
-    /**
-     * When current Block name is equals to the replacing tool Name,
-     * than convert this Block back to the default Block
-     */
-    if (currentBlockName === replacingToolName) {
-      replacingToolName = this.config.defaultBlock;
-    }
-
     /**
      * Getting a class of replacing Tool
      *
@@ -252,6 +246,14 @@ export default class ConversionToolbar extends Module<ConversionToolbarNodes> {
       return;
     }
 
+    /**
+     * If this conversion fired by the one of multiple Toolbox items,
+     * extend converted data with this item's "data" overrides
+     */
+    if (blockDataOverrides) {
+      newBlockData = Object.assign(newBlockData, blockDataOverrides);
+    }
+
     this.Editor.BlockManager.replace({
       tool: replacingToolName,
       data: newBlockData,
@@ -276,64 +278,93 @@ export default class ConversionToolbar extends Module<ConversionToolbarNodes> {
     Array
       .from(tools.entries())
       .forEach(([name, tool]) => {
-        const toolboxSettings = tool.toolbox;
         const conversionConfig = tool.conversionConfig;
 
-        /**
-         * Skip tools that don't pass 'toolbox' property
-         */
-        if (_.isEmpty(toolboxSettings) || !toolboxSettings.icon) {
-          return;
-        }
-
         /**
          * Skip tools without «import» rule specified
          */
         if (!conversionConfig || !conversionConfig.import) {
           return;
         }
-
-        this.addTool(name, toolboxSettings.icon, toolboxSettings.title);
+        tool.toolbox.forEach((toolboxItem) =>
+          this.addToolIfValid(name, toolboxItem)
+        );
       });
   }
 
+  /**
+   * Inserts a tool to the ConversionToolbar if the tool's toolbox config is valid
+   *
+   * @param name - tool's name
+   * @param toolboxSettings - tool's single toolbox setting
+   */
+  private addToolIfValid(name: string, toolboxSettings: ToolboxConfigEntry): void {
+    /**
+     * Skip tools that don't pass 'toolbox' property
+     */
+    if (_.isEmpty(toolboxSettings) || !toolboxSettings.icon) {
+      return;
+    }
+
+    this.addTool(name, toolboxSettings);
+  }
+
   /**
    * Add tool to the Conversion Toolbar
    *
-   * @param {string} toolName - name of Tool to add
-   * @param {string} toolIcon - Tool icon
-   * @param {string} title - button title
+   * @param toolName - name of Tool to add
+   * @param toolboxItem - tool's toolbox item data
    */
-  private addTool(toolName: string, toolIcon: string, title: string): void {
+  private addTool(toolName: string, toolboxItem: ToolboxConfigEntry): void {
     const tool = $.make('div', [ ConversionToolbar.CSS.conversionTool ]);
     const icon = $.make('div', [ ConversionToolbar.CSS.conversionToolIcon ]);
 
     tool.dataset.tool = toolName;
-    icon.innerHTML = toolIcon;
+    icon.innerHTML = toolboxItem.icon;
 
     $.append(tool, icon);
-    $.append(tool, $.text(I18n.t(I18nInternalNS.toolNames, title || _.capitalize(toolName))));
+    $.append(tool, $.text(I18n.t(I18nInternalNS.toolNames, toolboxItem.title || _.capitalize(toolName))));
 
     $.append(this.nodes.tools, tool);
-    this.tools[toolName] = tool;
+    this.tools.push({
+      name: toolName,
+      button: tool,
+      toolboxItem: toolboxItem,
+    });
 
     this.listeners.on(tool, 'click', async () => {
-      await this.replaceWithBlock(toolName);
+      await this.replaceWithBlock(toolName, toolboxItem.data);
     });
   }
 
   /**
    * Hide current Tool and show others
    */
-  private filterTools(): void {
+  private async filterTools(): Promise<void> {
     const { currentBlock } = this.Editor.BlockManager;
+    const currentBlockActiveToolboxEntry = await currentBlock.getActiveToolboxEntry();
 
     /**
-     * Show previously hided
+     * Compares two Toolbox entries
+     *
+     * @param entry1 - entry to compare
+     * @param entry2 - entry to compare with
      */
-    Object.entries(this.tools).forEach(([name, button]) => {
-      button.hidden = false;
-      button.classList.toggle(ConversionToolbar.CSS.conversionToolHidden, name === currentBlock.name);
+    function isTheSameToolboxEntry(entry1, entry2): boolean {
+      return entry1.icon === entry2.icon && entry1.title === entry2.title;
+    }
+
+    this.tools.forEach(tool => {
+      let hidden = false;
+
+      if (currentBlockActiveToolboxEntry) {
+        const isToolboxItemActive = isTheSameToolboxEntry(currentBlockActiveToolboxEntry, tool.toolboxItem);
+
+        hidden = (tool.button.dataset.tool === currentBlock.name && isToolboxItemActive);
+      }
+
+      tool.button.hidden = hidden;
+      tool.button.classList.toggle(ConversionToolbar.CSS.conversionToolHidden, hidden);
     });
   }
 

src/components/modules/toolbar/inline.ts

@@ -463,7 +463,7 @@ export default class InlineToolbar extends Module<InlineToolbarNodes> {
   /**
    * Changes Conversion Dropdown content for current block's Tool
    */
-  private setConversionTogglerContent(): void {
+  private async setConversionTogglerContent(): Promise<void> {
     const { BlockManager } = this.Editor;
     const { currentBlock } = BlockManager;
     const toolName = currentBlock.name;
@@ -480,7 +480,7 @@ export default class InlineToolbar extends Module<InlineToolbarNodes> {
     /**
      * Get icon or title for dropdown
      */
-    const toolboxSettings = currentBlock.tool.toolbox || {};
+    const toolboxSettings = await currentBlock.getActiveToolboxEntry() || {};
 
     this.nodes.conversionTogglerContent.innerHTML =
       toolboxSettings.icon ||