feat(blocks-api): the insert() method now has the optional id param

* refactor: added id to the insert method  to allow user pass and existing id to the method

When  working with multiple editor at the same and need to link  all  blocks to each editor and keeping the same ids in all.

* moved the position of the block_id params to the end to aaviod breaking cha

* doc: updated  the  documentation on insert method params

* refactor :  formatted  the code to  add/remove  space

* refactor: moved the position of the `id` and its description to the respective position

* refactor: rollback to previous commit

* added back the removed default value

* fix error, remove garbage

* test added, changelog added

Co-authored-by: Umang G. Patel <23169768+robonetphy@users.noreply.github.com>
Co-authored-by: Peter Savchenko <specc.dev@gmail.com>

docs/CHANGELOG.md

@@ -7,6 +7,7 @@
 - `New` — *Block Tunes API* — Now `render()` method of a Block Tune can return config with just icon, label and callback instead of custom HTML. This impovement is a key to the new straightforward way of configuring tune's appearance in Block Tunes menu.
 - `New` — *Tools API* — As well as `render()` in `Tunes API`, Tool's `renderSettings()` now also supports new configuration format.
 - `New` — *UI* — Meet the new icons from [CodeX Icons](https://github.com/codex-team/icons) pack 🛍 💝
+- `New` — *BlocksAPI* — the `blocks.insert()` method now also have the optional `id` param. If passed, this id will be used instead of the generated one.
 - `Deprecated` — *Styles API* — CSS classes `.cdx-settings-button` and `.cdx-settings-button--active` are not recommended to use. Consider configuring your block settings with new JSON API instead.
 - `Fix` — Wrong element not highlighted anymore when popover opened.
 - `Fix` — When Tunes Menu open keydown events can not be handled inside plugins.

src/components/modules/api/blocks.ts

@@ -227,6 +227,7 @@ export default class BlocksAPI extends Module {
    * @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 {string} id — An optional id for the new block. If omitted then the new id will be generated
    */
   public insert = (
     type: string = this.config.defaultBlock,
@@ -235,9 +236,11 @@ export default class BlocksAPI extends Module {
     config: ToolConfig = {},
     index?: number,
     needToFocus?: boolean,
-    replace?: boolean
+    replace?: boolean,
+    id?: string
   ): BlockAPIInterface => {
     const insertedBlock = this.Editor.BlockManager.insert({
+      id,
       tool: type,
       data,
       index,

test/cypress/tests/api/blocks.spec.ts

@@ -119,4 +119,26 @@ describe('api.blocks', () => {
       });
     });
   });
+
+  /**
+   * api.blocks.insert(type, data, config, index, needToFocus, replace, id)
+   */
+  describe('.insert()', function () {
+    it('should preserve block id if it is passed', function () {
+      cy.get('@editorInstance').then(async (editor: any) => {
+        const type = 'paragraph';
+        const data = { text: 'codex' };
+        const config = undefined;
+        const index = undefined;
+        const needToFocus = undefined;
+        const replace = undefined;
+        const id = 'test-id-123';
+
+        const block = editor.blocks.insert(type, data, config, index, needToFocus, replace, id);
+
+        expect(block).not.to.be.undefined;
+        expect(block.id).to.be.eq(id);
+      });
+    });
+  });
 });

types/api/blocks.d.ts

@@ -102,6 +102,8 @@ export interface Blocks {
    * @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
+   * @param {string} id — An optional id for the new block. If omitted then the new id will be generated
+
    */
   insert(
     type?: string,
@@ -110,6 +112,7 @@ export interface Blocks {
     index?: number,
     needToFocus?: boolean,
     replace?: boolean,
+    id?: string,
   ): BlockAPI;