feat(playground): register Header tool

Header wasn't wired into the playground, so there was no way to see its config-driven toolbox running in the actual editor rather than only in its own unit tests. Registered with all six levels enabled via config.levels.

Getting it to actually work surfaced two bugs: BlockManager.insert flattened a block's data onto its top-level properties instead of nesting it under data, dropping every tool's data on insert; and ToolboxUI.addTool only added one toolbox entry for a tool with several, instead of iterating all of them.

Author: Reversean

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

@@ -143,6 +143,22 @@ describe('BlocksManager (unit, mocked deps)', () => {
       );
     });
 
+    it('should nest data under a data property instead of flattening it onto the block', () => {
+      blocksManager.insert({
+        type: 'header',
+        data: { level: 2 }
+      });
+
+      expect(model.addBlock).toHaveBeenCalledWith(
+        USER_ID,
+        expect.objectContaining({
+          name: 'header',
+          data: { level: 2 }
+        }),
+        BLOCKS_COUNT
+      );
+    });
+
     it('should use model.length as insertion/removal index when replace is true and index is omitted', () => {
       blocksManager.insert({
         replace: true

packages/core/src/components/BlockManager.ts

@@ -145,7 +145,7 @@ export class BlocksManager {
     }
 
     this.#model.addBlock(userId, {
-      ...data,
+      data,
       id,
       name: type,
     }, newIndex);

packages/editorjs/src/index.spec.ts

@@ -79,4 +79,23 @@ describe('EditorJS bundle', () => {
     expect(registered).toContain('ClipboardPlugin');
     expect(registered).toContain('ShortcutsPlugin');
   });
+
+  it('forwards a tuple-registered user tool\'s options to core.use', () => {
+    initialize.mockResolvedValue(undefined);
+    class Header { public static name = 'header'; }
+    const options = { config: { levels: [1, 2, 3] } };
+
+    void new EditorJS({ tools: { header: [Header, options] } } as any);
+
+    expect(use).toHaveBeenCalledWith(Header, options);
+  });
+
+  it('registers a bare user tool with no options', () => {
+    initialize.mockResolvedValue(undefined);
+    class Header { public static name = 'header'; }
+
+    void new EditorJS({ tools: { header: Header } } as any);
+
+    expect(use).toHaveBeenCalledWith(Header, undefined);
+  });
 });

packages/editorjs/src/index.ts

@@ -9,7 +9,7 @@ import { LinkInlineTool } from '@editorjs/inline-link';
 import { ClipboardPlugin } from '@editorjs/clipboard-plugin';
 import { ShortcutsPlugin } from '@editorjs/shortcuts-plugin';
 import { EditorjsUI, BlocksUI, InlineToolbarUI, ToolbarUI, ToolboxUI } from '@editorjs/ui';
-import { mergeTools } from './mergeTools.js';
+import { mergeTools, type ToolEntry } from './mergeTools.js';
 
 /**
  * Default tools registered by the bundle, keyed later by their static `name`.
@@ -32,8 +32,10 @@ export type EditorJSConfig = Omit<CoreConfig, 'tools'> & {
   /**
    * User tools to register on top of the defaults. A tool provided under a name
    * that matches a default tool replaces that default instead of duplicating it.
+   * Pass a `[tool, options]` tuple instead of a bare constructor to forward
+   * options (most commonly `config`) to `core.use`.
    */
-  tools?: Record<string, ToolConstructable>;
+  tools?: Record<string, ToolEntry>;
 };
 
 /**
@@ -77,8 +79,8 @@ export default class EditorJS {
     /**
      * Default tools merged with user-provided `config.tools` (user wins by name).
      */
-    for (const tool of mergeTools(DEFAULT_TOOLS, tools)) {
-      this.#core.use(tool);
+    for (const [tool, options] of mergeTools(DEFAULT_TOOLS, tools)) {
+      this.#core.use(tool, options);
     }
 
     /**

packages/editorjs/src/mergeTools.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from '@jest/globals';
-import type { ToolConstructable } from '@editorjs/sdk';
+import type { ToolConstructable, ToolStaticOptions } from '@editorjs/sdk';
 import { mergeTools } from './mergeTools.js';
 
 /**
@@ -15,16 +15,16 @@ describe('mergeTools', () => {
   const bold = toolStub('bold');
   const defaults = [paragraph, bold];
 
-  it('returns the defaults when no user tools are provided', () => {
-    expect(mergeTools(defaults)).toEqual([paragraph, bold]);
+  it('returns the defaults with no options when no user tools are provided', () => {
+    expect(mergeTools(defaults)).toEqual([[paragraph, undefined], [bold, undefined]]);
   });
 
   it('adds a user tool registered under a new name', () => {
     const header = toolStub('header');
 
     const result = mergeTools(defaults, { header });
 
-    expect(result).toContain(header);
+    expect(result).toContainEqual([header, undefined]);
     expect(result).toHaveLength(defaults.length + 1);
   });
 
@@ -33,17 +33,33 @@ describe('mergeTools', () => {
 
     const result = mergeTools(defaults, { paragraph: customParagraph });
 
-    expect(result).toContain(customParagraph);
-    expect(result).not.toContain(paragraph);
-    expect(result.filter(tool => tool.name === 'paragraph')).toHaveLength(1);
+    expect(result).toContainEqual([customParagraph, undefined]);
+    expect(result.filter(([tool]) => tool.name === 'paragraph')).toHaveLength(1);
     expect(result).toHaveLength(defaults.length);
   });
 
+  it('attaches options to a user tool registered as a [tool, options] tuple', () => {
+    const header = toolStub('header');
+    const options: ToolStaticOptions = { config: { levels: [1, 2, 3] } };
+
+    const result = mergeTools(defaults, { header: [header, options] });
+
+    expect(result).toContainEqual([header, options]);
+  });
+
   it('throws when a config.tools key does not match the tool\'s static name', () => {
     const mismatched = toolStub('customParagraph');
 
     expect(() => mergeTools(defaults, { paragraph: mismatched })).toThrow(
       /customParagraph/
     );
   });
+
+  it('throws when a config.tools key does not match a tuple-registered tool\'s static name', () => {
+    const mismatched = toolStub('customParagraph');
+
+    expect(() => mergeTools(defaults, { paragraph: [mismatched, {}] })).toThrow(
+      /customParagraph/
+    );
+  });
 });

packages/editorjs/src/mergeTools.ts

@@ -1,4 +1,17 @@
-import type { ToolConstructable } from '@editorjs/sdk';
+import type { ToolConstructable, ToolStaticOptions } from '@editorjs/sdk';
+
+/**
+ * A user tool entry in `config.tools`: a bare constructor, or a
+ * `[constructor, options]` tuple when `core.use` needs a second argument
+ * (most commonly `{ config }`).
+ */
+export type ToolEntry = ToolConstructable | [ToolConstructable, ToolStaticOptions];
+
+/**
+ * A merged tool paired with the options it should be passed to `core.use` with,
+ * if any.
+ */
+export type MergedTool = [ToolConstructable, ToolStaticOptions | undefined];
 
 /**
  * Merges user-provided tools over the default tools, keyed by name.
@@ -13,23 +26,25 @@ import type { ToolConstructable } from '@editorjs/sdk';
  */
 export function mergeTools(
   defaults: ToolConstructable[],
-  userTools?: Record<string, ToolConstructable>
-): ToolConstructable[] {
-  const merged = new Map<string, ToolConstructable>();
+  userTools?: Record<string, ToolEntry>
+): MergedTool[] {
+  const merged = new Map<string, MergedTool>();
 
   for (const tool of defaults) {
-    merged.set(tool.name, tool);
+    merged.set(tool.name, [tool, undefined]);
   }
 
   if (userTools !== undefined) {
-    for (const [name, tool] of Object.entries(userTools)) {
+    for (const [name, entry] of Object.entries(userTools)) {
+      const [tool, options] = Array.isArray(entry) ? entry : [entry, undefined];
+
       if (name !== tool.name) {
         throw new Error(
           `Tool registered under key "${name}" in config.tools has a static name of "${tool.name}". The key must match the tool's name.`
         );
       }
 
-      merged.set(name, tool);
+      merged.set(name, [tool, options]);
     }
   }
 

packages/playground/package.json

@@ -17,6 +17,7 @@
   },
   "dependencies": {
     "@editorjs/editorjs": "workspace:^",
+    "@editorjs/header": "workspace:^",
     "@editorjs/model": "workspace:^",
     "@editorjs/sdk": "workspace:^",
     "vue": "^3.3.4"

packages/playground/src/App.vue

@@ -4,6 +4,7 @@ import { EditorDocument, EditorJSModel } from '@editorjs/model';
 import EditorJS from '@editorjs/editorjs';
 import { ref, onMounted } from 'vue';
 import { Node } from './components';
+import { Header } from '@editorjs/header';
 /**
  * Editor document for visualizing
  */
@@ -58,6 +59,9 @@ onMounted(() => {
       editorDocument.value = (m as EditorJSModel).devModeGetDocument();
     },
 
+    tools: {
+      header: [Header, { config: { levels: [1, 2, 3, 4, 5, 6] } }],
+    },
   });
 
   editor.isReady.catch((error: unknown) => console.error('Editor.js failed to initialize', error));

packages/playground/tsconfig.json

@@ -44,6 +44,9 @@
     },
     {
       "path": "../ui/tsconfig.json"
+    },
+    {
+      "path": "../tools/header/tsconfig.json"
     }
   ]
 }

packages/playground/vite.config.ts

@@ -9,6 +9,11 @@ export default defineConfig({
       '@': path.resolve(__dirname, './src'),
     },
   },
+  server: {
+    fs: {
+      allow: [path.resolve(__dirname, '../..')],
+    },
+  },
   optimizeDeps: {
     exclude: [
       '@editorjs/ui',