Block ID implementation

packages/core/src/api/BlocksAPI.integration.spec.ts

@@ -271,8 +271,11 @@ describe('BlocksAPI integration (real model, mocked DOM adapters)', () => {
       blocksAPI.render({
         identifier: 'new-doc',
         blocks: [
-          { name: 'header',
-            data: {} },
+          {
+            id: 'mock',
+            name: 'header',
+            data: {},
+          },
         ],
         properties: {},
       });
@@ -375,10 +378,16 @@ describe('BlocksAPI integration (real model, mocked DOM adapters)', () => {
       blocksAPI.render({
         identifier: 'doc-2',
         blocks: [
-          { name: 'header',
-            data: {} },
-          { name: 'list',
-            data: {} },
+          {
+            id: 'mock-header',
+            name: 'header',
+            data: {},
+          },
+          {
+            id: 'mock-list',
+            name: 'list',
+            data: {},
+          },
         ],
         properties: {},
       });

packages/core/src/api/BlocksAPI.ts

@@ -5,7 +5,7 @@ import { BlocksManager } from '../components/BlockManager.js';
 import { BlockToolData } from '@editorjs/editorjs';
 import { CoreConfigValidated } from '@editorjs/sdk';
 import { BlocksAPI as BlocksApiInterface } from '@editorjs/sdk';
-import { type BlockNodeSerialized, EditorDocumentSerialized } from '@editorjs/model';
+import { type BlockNodeInit, type EditorDocumentSerialized } from '@editorjs/model';
 
 /**
  * Blocks API
@@ -80,7 +80,7 @@ export class BlocksAPI implements BlocksApiInterface {
    * @param blocks - array of blocks to insert
    * @param [index] - index to insert blocks at. If undefined, inserts at the end
    */
-  public insertMany(blocks: BlockNodeSerialized[], index?: number): void {
+  public insertMany(blocks: BlockNodeInit[], index?: number): void {
     return this.#blocksManager.insertMany(blocks, index);
   }
 

packages/core/src/components/BlockManager.spec.ts

@@ -19,6 +19,7 @@ jest.unstable_mockModule('@editorjs/model', () => {
     initializeDocument: jest.fn(),
     clearBlocks: jest.fn(),
     getCaret: jest.fn(),
+    getBlockSerialized: jest.fn(),
     get length() {
       return BLOCKS_COUNT;
     },
@@ -222,6 +223,7 @@ describe('BlocksManager (unit, mocked deps)', () => {
         identifier: 'doc',
         blocks: [
           {
+            id: 'mock',
             name: 'x',
             data: {}
           }
@@ -255,20 +257,24 @@ describe('BlocksManager (unit, mocked deps)', () => {
 
       expect(model.removeBlock).toHaveBeenCalledWith(USER_ID, 0);
     });
+
+    it('should call model.getCaret with the configured userId to resolve current block', () => {
+      // @ts-expect-error - mock return value does not need full Caret shape
+      model.getCaret = jest.fn(() => ({ index: { blockIndex: 2 } }));
+
+      blocksManager.deleteBlock();
+
+      expect(model.getCaret).toHaveBeenCalledWith(USER_ID);
+      expect(model.removeBlock).toHaveBeenCalledWith(USER_ID, 2);
+    });
   });
 
   describe('.move()', () => {
     it('should call removeBlock and addBlock when moving current block forward', () => {
-      // @ts-expect-error - need to assign read only property to mock it
-      model.serialized = {
-        blocks: [
-          { name: 'a' },
-          { name: 'b' },
-          { name: 'c' }
-        ]
-      };
       // @ts-expect-error - mock return value does not need full Caret shape
       model.getCaret = jest.fn(() => ({ index: { blockIndex: 0 } }));
+      // @ts-expect-error - mock return value does not need full BlockNodeSerialized shape
+      model.getBlockSerialized = jest.fn(() => ({ name: 'a' }));
 
       blocksManager.move(2);
 
@@ -283,14 +289,8 @@ describe('BlocksManager (unit, mocked deps)', () => {
     });
 
     it('should pass toIndex directly when toIndex is less than fromIndex', () => {
-      // @ts-expect-error - need to assign read only property to mock it
-      model.serialized = {
-        blocks: [
-          { name: 'a' },
-          { name: 'b' },
-          { name: 'c' }
-        ]
-      };
+      // @ts-expect-error - mock return value does not need full BlockNodeSerialized shape
+      model.getBlockSerialized = jest.fn(() => ({ name: 'c' }));
 
       blocksManager.move(0, 2);
 
@@ -299,15 +299,6 @@ describe('BlocksManager (unit, mocked deps)', () => {
     });
 
     it('should do nothing when toIndex equals fromIndex', () => {
-      // @ts-expect-error - need to assign read only property to mock it
-      model.serialized = {
-        blocks: [
-          { name: 'a' },
-          { name: 'b' },
-          { name: 'c' }
-        ]
-      };
-
       blocksManager.move(1, 1);
 
       expect(model.removeBlock).not.toHaveBeenCalled();

packages/core/src/components/BlockManager.ts

@@ -1,5 +1,5 @@
 import {
-  type BlockNodeSerialized,
+  type BlockNodeInit,
   type EditorDocumentSerialized,
   EditorJSModel
 } from '@editorjs/model';
@@ -17,7 +17,10 @@ import {
  * Parameters for the BlocksManager.insert() method
  */
 interface InsertBlockParameters {
-  // id?: string;
+  /**
+   * Block ID
+   */
+  id?: string;
   /**
    * Block tool name to insert
    */
@@ -111,7 +114,7 @@ export class BlocksManager {
    * @param parameters.replace - flag indicates if block at index should be replaced
    */
   public insert({
-    // id = undefined,
+    id = undefined,
     type = this.#config.defaultBlock,
     data = {},
     index,
@@ -131,6 +134,7 @@ export class BlocksManager {
 
     this.#model.addBlock(this.#config.userId, {
       ...data,
+      id,
       name: type,
     }, newIndex);
 
@@ -146,7 +150,7 @@ export class BlocksManager {
    * @param blocks - array of blocks to insert
    * @param [index] - index to insert blocks at. If undefined, inserts at the end
    */
-  public insertMany(blocks: BlockNodeSerialized[], index: number = this.#model.length): void {
+  public insertMany(blocks: BlockNodeInit[], index: number = this.#model.length): void {
     blocks.forEach((block, i) => this.#model.addBlock(this.#config.userId, block, index + i));
   }
 
@@ -197,7 +201,7 @@ export class BlocksManager {
       return;
     }
 
-    const block = this.#model.serialized.blocks[fromIndex];
+    const block = this.#model.getBlockSerialized(fromIndex);
 
     this.#model.removeBlock(this.#config.userId, fromIndex);
     this.#model.addBlock(this.#config.userId, block, toIndex);

packages/core/src/components/BlockRenderer.spec.ts

@@ -1,7 +1,7 @@
 /* eslint-disable jsdoc/require-jsdoc, @stylistic/comma-dangle,@typescript-eslint/naming-convention */
 import { beforeEach, jest } from '@jest/globals';
 import type { BlockToolFacade, EditorJSAdapterPlugin } from '@editorjs/sdk';
-import type { Index } from '@editorjs/model';
+import type { BlockId, Index } from '@editorjs/model';
 
 const USER_ID = 'user';
 
@@ -45,6 +45,7 @@ jest.unstable_mockModule('@editorjs/model', () => {
     BlockAddedEvent,
     BlockRemovedEvent,
     EventType,
+    createBlockId: (str: string) => str,
   };
 });
 
@@ -114,8 +115,11 @@ describe('BlockRenderer (unit, mocked deps)', () => {
 
         const event = new BlockAddedEvent(
           { blockIndex: 0 } as Index,
-          { name: 'tool',
-            data: {} },
+          {
+            name: 'tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 
@@ -132,8 +136,11 @@ describe('BlockRenderer (unit, mocked deps)', () => {
       it('should throw when blockIndex is undefined', async () => {
         const event = new BlockAddedEvent(
           {} as Index,
-          { name: 'tool',
-            data: {} },
+          {
+            name: 'tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 
@@ -149,8 +156,11 @@ describe('BlockRenderer (unit, mocked deps)', () => {
 
         const event = new BlockAddedEvent(
           { blockIndex: 0 } as Index,
-          { name: 'missing-tool',
-            data: {} },
+          {
+            name: 'missing-tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 
@@ -174,8 +184,11 @@ describe('BlockRenderer (unit, mocked deps)', () => {
 
         const event = new BlockAddedEvent(
           { blockIndex: 0 } as Index,
-          { name: 'tool',
-            data: {} },
+          {
+            name: 'tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 
@@ -194,8 +207,11 @@ describe('BlockRenderer (unit, mocked deps)', () => {
       it('should dispatch BlockRemovedCoreEvent via EventBus', () => {
         const event = new BlockRemovedEvent(
           { blockIndex: 1 } as Index,
-          { name: 'tool',
-            data: {} },
+          {
+            name: 'tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 
@@ -204,24 +220,31 @@ describe('BlockRenderer (unit, mocked deps)', () => {
         expect(eventBus.dispatchEvent).toHaveBeenCalled();
       });
 
-      it('should call destroyBlockToolAdapter with the block index', () => {
+      it('should call destroyBlockToolAdapter with the block id', () => {
+        const blockId = 'test-block-id' as unknown as BlockId;
         const event = new BlockRemovedEvent(
-          { blockIndex: 2 } as Index,
-          { name: 'tool',
-            data: {} },
+          { blockIndex: 1 } as Index,
+          {
+            name: 'tool',
+            id: blockId,
+            data: {}
+          },
           USER_ID,
         );
 
         void changedListener(event);
 
-        expect(adapter.destroyBlockToolAdapter).toHaveBeenCalledWith(2);
+        expect(adapter.destroyBlockToolAdapter).toHaveBeenCalledWith(blockId);
       });
 
       it('should throw when blockIndex is undefined', () => {
         const event = new BlockRemovedEvent(
           {} as Index,
-          { name: 'tool',
-            data: {} },
+          {
+            name: 'tool',
+            id: 'test-block-id' as BlockId,
+            data: {}
+          },
           USER_ID,
         );
 

packages/core/src/components/BlockRenderer.ts

@@ -1,6 +1,7 @@
 import {
   BlockAddedEvent,
   BlockRemovedEvent,
+  createBlockId,
   EditorJSModel,
   EventType,
   ModelEvents
@@ -110,7 +111,7 @@ export class BlockRenderer {
       throw new Error(`[BlockRenderer] Block Tool ${data.name} not found`);
     }
 
-    const blockToolAdapter = this.#adapter.createBlockToolAdapter(index.blockIndex, tool.name);
+    const blockToolAdapter = this.#adapter.createBlockToolAdapter(createBlockId(data.id), tool.name);
 
     const block = tool.create({
       adapter: blockToolAdapter,
@@ -146,7 +147,7 @@ export class BlockRenderer {
       throw new Error('[BlockRenderer] Block index should be defined. Probably something wrong with the Editor Model. Please, report this issue');
     }
 
-    this.#adapter.destroyBlockToolAdapter(index.blockIndex);
+    this.#adapter.destroyBlockToolAdapter(createBlockId(data.id));
 
     this.#eventBus.dispatchEvent(new BlockRemovedCoreEvent({
       tool: data.name,

packages/core/src/components/SelectionManager.ts

@@ -15,7 +15,7 @@ import {
 import { inject, injectable } from 'inversify';
 import { TOKENS } from '../tokens.js';
 import { InlineToolFormatData } from '@editorjs/sdk';
-import ToolsManager from '../tools/ToolsManager';
+import ToolsManager from '../tools/ToolsManager.js';
 
 /**
  * SelectionManager responsible for handling selection changes and applying inline tools formatting

packages/core/src/utils/composeDataFromVersion2.ts

@@ -1,6 +1,6 @@
 import type { OutputData } from '@editorjs/editorjs';
 import type { InlineFragment } from '@editorjs/model';
-import { createInlineToolData, createInlineToolName, TextNode, ValueNode, type BlockNodeSerialized } from '@editorjs/model';
+import { createInlineToolData, createInlineToolName, TextNode, ValueNode, type BlockNodeInit } from '@editorjs/model';
 
 /**
  * Removes HTML tags from the input string
@@ -92,7 +92,7 @@ export function composeDataFromVersion2(data: OutputData): {
   /**
    * The child BlockNodes of the EditorDocument
    */
-  blocks: BlockNodeSerialized[];
+  blocks: BlockNodeInit[];
 } {
   return {
     blocks: data.blocks.map((block) => {