[Feature]: insert() API method (#814)

docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - `Improvements` — Inline Toolbar now works on mobile devices [#706](https://github.com/codex-team/editor.js/issues/706)
 - `Improvements` — Toolbar looks better on mobile devices [#706](https://github.com/codex-team/editor.js/issues/706)
+- `New` — New [`blocks.insert()`](api.md) API method [#715](https://github.com/codex-team/editor.js/issues/715).  
+- `Deprecated` — [`blocks.insertNewBlock()`](api.md) method is deprecated. Use `blocks.insert()` instead.  
 - `Fix` — Resolve bug with deleting leading new lines [#726](https://github.com/codex-team/editor.js/issues/726)
 - `Fix` — Fix inline link Tool to support different link types like `mailto` and `tel` [#809](https://github.com/codex-team/editor.js/issues/809)
 - `Fix` — Added `typeof` util method to check exact object type [#805](https://github.com/codex-team/editor.js/issues/805)

docs/api.md

@@ -38,7 +38,9 @@ Methods that working with Blocks
 
 `stretchBlock(index: number, status: boolean)` - make Block stretched
 
-`insertNewBlock()` - insert new Block after working place
+`insertNewBlock()` - __Deprecated__ insert new Block after working place 
+
+`insert(type?: string, data?: BlockToolData, config?: ToolConfig, index?: number, needToFocus?: boolean)` - insert new Block with passed parameters
 
 #### SanitizerAPI
 

src/components/modules/api/blocks.ts

@@ -1,9 +1,8 @@
 import Module from '../../__module';
 
 import {Blocks} from '../../../../types/api';
-import {OutputData} from '../../../../types';
-import Block from '../../block';
-import {ModuleConfig} from '../../../types-internal/module-config';
+import {BlockToolData, OutputData, ToolConfig} from '../../../../types';
+import _ from './../../utils';
 
 /**
  * @class BlocksAPI
@@ -26,6 +25,7 @@ export default class BlocksAPI extends Module {
       getBlocksCount: () => this.getBlocksCount(),
       stretchBlock: (index: number, status: boolean = true) => this.stretchBlock(index, status),
       insertNewBlock: () => this.insertNewBlock(),
+      insert: this.insert,
     };
   }
 
@@ -140,12 +140,42 @@ export default class BlocksAPI extends Module {
     block.stretched = status;
   }
 
+  /**
+   * Insert new Block
+   *
+   * @param {string} type — Tool name
+   * @param {BlockToolData} data — Tool data to insert
+   * @param {ToolConfig} config — Tool config
+   * @param {number?} index — index where to insert new Block
+   * @param {boolean?} needToFocus - flag to focus inserted Block
+   */
+  public insert = (
+    type: string = this.config.initialBlock,
+    data: BlockToolData = {},
+    config: ToolConfig = {},
+    index?: number,
+    needToFocus?: boolean,
+  ): void => {
+    this.Editor.BlockManager.insert(
+      type,
+      data,
+      config,
+      index,
+      needToFocus,
+    );
+  }
+
   /**
    * Insert new Block
    * After set caret to this Block
+   *
+   * @todo: remove in 3.0.0
+   *
+   * @deprecated with insert() method
    */
-  public insertNewBlock() {
-    const newBlock = this.Editor.BlockManager.insert();
-    this.Editor.Caret.setToBlock(newBlock);
+  public insertNewBlock(): void {
+    _.log('Method blocks.insertNewBlock() is deprecated and it will be removed in next major release. ' +
+      'Use blocks.insert() instead.', 'warn');
+    this.insert();
   }
 }

src/components/modules/blockEvents.ts

@@ -293,7 +293,7 @@ export default class BlockEvents extends Module {
     BlockSelection.copySelectedBlocks();
 
     const selectionPositionIndex = BlockManager.removeSelectedBlocks();
-    Caret.setToBlock(BlockManager.insertAtIndex(selectionPositionIndex, true), Caret.positions.START);
+    Caret.setToBlock(BlockManager.insertInitialBlockAtIndex(selectionPositionIndex, true), Caret.positions.START);
 
     /** Clear selection */
     BlockSelection.clearSelection();
@@ -351,7 +351,7 @@ export default class BlockEvents extends Module {
      * If enter has been pressed at the start of the text, just insert paragraph Block above
      */
     if (this.Editor.Caret.isAtStart && !this.Editor.BlockManager.currentBlock.hasMedia) {
-      this.Editor.BlockManager.insertAtIndex(this.Editor.BlockManager.currentBlockIndex);
+      this.Editor.BlockManager.insertInitialBlockAtIndex(this.Editor.BlockManager.currentBlockIndex);
     } else {
       /**
        * Split the Current Block into two blocks

src/components/modules/blockManager.ts

@@ -223,20 +223,26 @@ export default class BlockManager extends Module {
    * @param {String} toolName — plugin name, by default method inserts initial block type
    * @param {Object} data — plugin data
    * @param {Object} settings - default settings
+   * @param {number} index - index where to insert new Block
+   * @param {boolean} needToFocus - flag shows if needed to update current Block index
    *
    * @return {Block}
    */
   public insert(
     toolName: string = this.config.initialBlock,
     data: BlockToolData = {},
     settings: ToolConfig = {},
+    index: number = this.currentBlockIndex + 1,
+    needToFocus: boolean = true,
   ): Block {
-    // Increment index before construct,
-    // because developers can use API/Blocks/getCurrentInputIndex on the render() method
-    const newIndex = ++this.currentBlockIndex;
     const block = this.composeBlock(toolName, data, settings);
 
-    this._blocks[newIndex] = block;
+    this._blocks[index] = block;
+
+    if (needToFocus) {
+      this.currentBlockIndex = index;
+    }
+
     return block;
   }
 
@@ -274,9 +280,11 @@ export default class BlockManager extends Module {
    * @param {number} index - index where Block should be inserted
    * @param {boolean} needToFocus - if true, updates current Block index
    *
+   * TODO: Remove method and use insert() with index instead (?)
+   *
    * @return {Block} inserted Block
    */
-  public insertAtIndex(index: number, needToFocus: boolean = false) {
+  public insertInitialBlockAtIndex(index: number, needToFocus: boolean = false) {
     const block = this.composeBlock(this.config.initialBlock, {}, {});
 
     this._blocks[index] = block;

src/components/modules/toolbar/inline.ts

@@ -199,8 +199,15 @@ export default class InlineToolbar extends Module {
      * By default, Inline Toolbar has top-corner at the center
      * We are adding a modifiers for to move corner to the left or right
      */
-    this.nodes.wrapper.classList.toggle(this.CSS.inlineToolbarLeftOriented, realLeftCoord < this.Editor.UI.contentRect.left);
-    this.nodes.wrapper.classList.toggle(this.CSS.inlineToolbarRightOriented, realRightCoord > this.Editor.UI.contentRect.right);
+    this.nodes.wrapper.classList.toggle(
+      this.CSS.inlineToolbarLeftOriented,
+      realLeftCoord < this.Editor.UI.contentRect.left,
+    );
+
+    this.nodes.wrapper.classList.toggle(
+      this.CSS.inlineToolbarRightOriented,
+      realRightCoord > this.Editor.UI.contentRect.right,
+    );
 
     this.nodes.wrapper.style.left = Math.floor(newCoords.x) + 'px';
     this.nodes.wrapper.style.top = Math.floor(newCoords.y) + 'px';

src/components/modules/ui.ts

@@ -353,7 +353,7 @@ export default class UI extends Module {
 
     if (BlockSelection.anyBlockSelected) {
       const selectionPositionIndex = BlockManager.removeSelectedBlocks();
-      Caret.setToBlock(BlockManager.insertAtIndex(selectionPositionIndex, true), Caret.positions.START);
+      Caret.setToBlock(BlockManager.insertInitialBlockAtIndex(selectionPositionIndex, true), Caret.positions.START);
 
       /** Clear selection */
       BlockSelection.clearSelection();
@@ -436,7 +436,7 @@ export default class UI extends Module {
 
     if (BlockSelection.anyBlockSelected) {
       const selectionPositionIndex = BlockManager.removeSelectedBlocks();
-      Caret.setToBlock(BlockManager.insertAtIndex(selectionPositionIndex, true), Caret.positions.START);
+      Caret.setToBlock(BlockManager.insertInitialBlockAtIndex(selectionPositionIndex, true), Caret.positions.START);
 
       /** Clear selection */
       BlockSelection.clearSelection();

types/api/blocks.d.ts

@@ -1,4 +1,5 @@
 import {OutputData} from '../data-formats/output-data';
+import {BlockToolData, ToolConfig} from "../tools";
 
 /**
  * Describes methods to manipulate with Editor`s blocks
@@ -63,6 +64,26 @@ export interface Blocks {
 
   /**
    * Insert new Initial Block after current Block
+   *
+   * @deprecated
    */
   insertNewBlock(): void;
+
+  /**
+   * Insert new Block
+   *
+   * @param {string} type — Tool name
+   * @param {BlockToolData} data — Tool data to insert
+   * @param {ToolConfig} config — Tool config
+   * @param {number?} index — index where to insert new Block
+   * @param {boolean?} needToFocus - flag to focus inserted Block
+   */
+  insert(
+    type?: string,
+    data?: BlockToolData,
+    config?: ToolConfig,
+    index?: number,
+    needToFocus?: boolean,
+  ): void;
+
 }