Improved block.insert() by allowing passing parameters as an object

docs/CHANGELOG.md

@@ -5,6 +5,7 @@
 - `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
 - `New` — *Blocks API* — `composeBlockData()` method was added.
+- `Improvement` — *Blocks API* — the `insert()` method now allows passing parameters as an object instead of set.
 
 ### 2.24.4
 

src/components/modules/api/blocks.ts

@@ -1,4 +1,4 @@
-import { BlockAPI as BlockAPIInterface, Blocks } from '../../../../types/api';
+import { BlockAPI as BlockAPIInterface, Blocks, NewBlock } from '../../../../types/api';
 import { BlockToolData, OutputData, ToolConfig } from '../../../../types';
 import * as _ from './../../utils';
 import BlockAPI from '../../block/api';
@@ -221,29 +221,23 @@ export default class BlocksAPI extends Module {
   }
 
   /**
-   * Insert new Block and returns it's API
+   * Insert new Block and returns its API
    *
-   * @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
-   * @param replace - pass true to replace the Block existed under passed index
+   * @param {NewBlock} newBlock — the block that will be inserted
    */
   public insert = (
-    type: string = this.config.defaultBlock,
-    data: BlockToolData = {},
-    config: ToolConfig = {},
-    index?: number,
-    needToFocus?: boolean,
-    replace?: boolean
+    newBlock: NewBlock = {
+      type: this.config.defaultBlock,
+      data: {},
+      config: {}
+    }
   ): BlockAPIInterface => {
     const insertedBlock = this.Editor.BlockManager.insert({
-      tool: type,
-      data,
-      index,
-      needToFocus,
-      replace,
+      tool: newBlock.type,
+      data: newBlock.data,
+      index: newBlock.index,
+      needToFocus: newBlock.needToFocus,
+      replace: newBlock.replace,
     });
 
     return new BlockAPI(insertedBlock);

src/components/ui/toolbox.ts

@@ -404,14 +404,13 @@ export default class Toolbox extends EventsDispatcher<ToolboxEvent> {
       blockData = Object.assign(defaultBlockData, blockDataOverrides);
     }
 
-    const newBlock = this.api.blocks.insert(
-      toolName,
-      blockData,
-      undefined,
+    const newBlock = this.api.blocks.insert({
+      type: toolName,
+      data: blockData,
+      config: undefined,
       index,
-      undefined,
-      currentBlock.isEmpty
-    );
+      replace: currentBlock.isEmpty,
+    });
 
     /**
      * Apply callback before inserting html

types/api/block.d.ts

@@ -74,3 +74,39 @@ export interface BlockAPI {
    */
   dispatchChange(): void;
 }
+
+/**
+ * @interface NewBlock Describes new block configuration
+ */
+
+export interface NewBlock {
+  /**
+   * Tool name
+   */
+  type: string;
+
+  /**
+   * Tool data to insert
+   */
+  data: BlockToolData;
+
+  /**
+   * Tool config
+   */
+  config: ToolConfig;
+
+  /**
+   * index where to insert new Block
+   */
+  index?: number;
+
+  /**
+   * flag to focus inserted Block
+   */
+  needToFocus?: boolean;
+
+  /**
+   * should the existed Block on that index be replaced or not
+   */
+  replace?: boolean;
+}

types/api/blocks.d.ts

@@ -1,6 +1,6 @@
 import {OutputData} from '../data-formats/output-data';
 import {BlockToolData, ToolConfig} from '../tools';
-import {BlockAPI} from './block';
+import {BlockAPI, NewBlock} from './block';
 
 /**
  * Describes methods to manipulate with Editor`s blocks
@@ -96,21 +96,10 @@ export interface Blocks {
   /**
    * Insert new Block and return inserted Block API
    *
-   * @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
-   * @param {boolean?} replace - should the existed Block on that index be replaced or not
-   */
-  insert(
-    type?: string,
-    data?: BlockToolData,
-    config?: ToolConfig,
-    index?: number,
-    needToFocus?: boolean,
-    replace?: boolean,
-  ): BlockAPI;
+   * @param{NewBlock} newBlock - new block config
+   *
+   */
+  insert(newBlock: NewBlock): BlockAPI;
 
 
   /**