From 9b7da504e4e9808d53817e350ed968920b947568 Mon Sep 17 00:00:00 2001
From: azibodusi osain <azibodusiosain@gmail.com>
Date: Fri, 25 Nov 2022 20:59:38 +0100
Subject: [PATCH] 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                     |  1 +
 src/components/modules/api/blocks.ts  |  5 ++++-
 test/cypress/tests/api/blocks.spec.ts | 22 ++++++++++++++++++++++
 types/api/blocks.d.ts                 |  3 +++
 4 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index aeeb5b2e..1b71da9d 100644
--- a/docs/CHANGELOG.md
+++ b/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.
diff --git a/src/components/modules/api/blocks.ts b/src/components/modules/api/blocks.ts
index c5a98941..a711d52f 100644
--- a/src/components/modules/api/blocks.ts
+++ b/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,
diff --git a/test/cypress/tests/api/blocks.spec.ts b/test/cypress/tests/api/blocks.spec.ts
index a29e7077..ab3f2ac8 100644
--- a/test/cypress/tests/api/blocks.spec.ts
+++ b/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);
+      });
+    });
+  });
 });
diff --git a/types/api/blocks.d.ts b/types/api/blocks.d.ts
index f684bf78..0a90b031 100644
--- a/types/api/blocks.d.ts
+++ b/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;