feat: add Jodit "show-blocks" editor plugin

Adds a toggle plugin that visually outlines block-level elements with
dashed borders and tag-name labels, helping content editors understand
document structure at a glance.

Author: thorsten

phpmyfaq/admin/assets/src/content/editor.test.ts

@@ -92,6 +92,7 @@ vi.mock('jodit/esm/modules/uploader/uploader.js', () => ({}));
 vi.mock('jodit/esm/plugins/video/video.js', () => ({}));
 vi.mock('../plugins/phpmyfaq/phpmyfaq.js', () => ({}));
 vi.mock('../plugins/code-snippet/code-snippet.js', () => ({}));
+vi.mock('../plugins/show-blocks/show-blocks.js', () => ({}));
 
 import { getJoditEditor, renderEditor, renderPageEditor } from './editor';
 import { Jodit } from 'jodit';

phpmyfaq/admin/assets/src/content/editor.ts

@@ -42,6 +42,7 @@ import 'jodit/esm/modules/uploader/uploader.js';
 import 'jodit/esm/plugins/video/video.js';
 import '../plugins/phpmyfaq/phpmyfaq.js';
 import '../plugins/code-snippet/code-snippet.js';
+import '../plugins/show-blocks/show-blocks.js';
 import hljs from 'highlight.js';
 
 interface UploaderResponse {
@@ -187,7 +188,7 @@ export const renderEditor = () => {
     imageProcessor: { replaceDataURIToBlobIdInView: false },
     removeButtons: [],
     disablePlugins: [],
-    extraPlugins: ['phpMyFAQ', 'codeSnippet'],
+    extraPlugins: ['phpMyFAQ', 'codeSnippet', 'showBlocks'],
     extraButtons: [],
     buttons: [
       'source',
@@ -240,6 +241,7 @@ export const renderEditor = () => {
       '|',
       'phpMyFAQ',
       'codeSnippet',
+      'showBlocks',
     ],
     events: {},
     textIcons: false,

phpmyfaq/admin/assets/src/plugins/show-blocks/show-blocks.svg.ts

@@ -0,0 +1,11 @@
+const showBlocks: string = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
+ stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+<rect x="3" y="3" width="18" height="18" rx="2" stroke-dasharray="3 2"/>
+<line x1="3" y1="9" x2="21" y2="9" stroke-dasharray="3 2"/>
+<line x1="3" y1="15" x2="21" y2="15" stroke-dasharray="3 2"/>
+<text x="5" y="7.5" font-size="3.5" font-family="sans-serif" fill="currentColor" stroke="none">P</text>
+<text x="5" y="13.5" font-size="3.5" font-family="sans-serif" fill="currentColor" stroke="none">DIV</text>
+<text x="5" y="19.5" font-size="3.5" font-family="sans-serif" fill="currentColor" stroke="none">H1</text>
+</svg>`;
+
+export default showBlocks;

phpmyfaq/admin/assets/src/plugins/show-blocks/show-blocks.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockIconSet = vi.fn();
+const mockPluginsAdd = vi.fn();
+
+vi.mock('jodit', () => ({
+  Jodit: {
+    modules: {
+      Icon: {
+        set: mockIconSet,
+      },
+    },
+    plugins: {
+      add: mockPluginsAdd,
+    },
+  },
+}));
+
+describe('show-blocks.svg', () => {
+  it('should export a string containing SVG markup', async () => {
+    const { default: svgContent } = await import('./show-blocks.svg.js');
+    expect(typeof svgContent).toBe('string');
+    expect(svgContent).toContain('<svg');
+  });
+
+  it('should contain visual elements', async () => {
+    const { default: svgContent } = await import('./show-blocks.svg.js');
+    expect(svgContent).toContain('<rect');
+    expect(svgContent).toContain('<line');
+  });
+});
+
+describe('show-blocks plugin', () => {
+  const mockEditorDoc = {
+    createElement: vi.fn(),
+    head: { appendChild: vi.fn() },
+  };
+
+  const mockClassList = {
+    add: vi.fn(),
+    remove: vi.fn(),
+  };
+
+  const mockEditor = {
+    registerButton: vi.fn(),
+    registerCommand: vi.fn(),
+    editor: {
+      ownerDocument: mockEditorDoc,
+      classList: mockClassList,
+    },
+    events: { fire: vi.fn() },
+    o: { theme: 'default' },
+  };
+
+  let mockStyleElement: {
+    setAttribute: ReturnType<typeof vi.fn>;
+    textContent: string | null;
+    remove: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+
+    mockStyleElement = {
+      setAttribute: vi.fn(),
+      textContent: null,
+      remove: vi.fn(),
+    };
+
+    mockEditorDoc.createElement.mockReturnValue(mockStyleElement);
+  });
+
+  const importPlugin = async () => {
+    await import('./show-blocks');
+  };
+
+  const getPluginCallback = (): ((editor: typeof mockEditor) => void) => {
+    return mockPluginsAdd.mock.calls[0][1] as (editor: typeof mockEditor) => void;
+  };
+
+  const getCommandFn = (): (() => void) => {
+    return mockEditor.registerCommand.mock.calls[0][1] as () => void;
+  };
+
+  it('should register icon via Jodit.modules.Icon.set with name showBlocks', async () => {
+    await importPlugin();
+
+    expect(mockIconSet).toHaveBeenCalledWith('showBlocks', expect.any(String));
+  });
+
+  it('should register plugin via Jodit.plugins.add with name showBlocks', async () => {
+    await importPlugin();
+
+    expect(mockPluginsAdd).toHaveBeenCalledWith('showBlocks', expect.any(Function));
+  });
+
+  it('should register button with tooltip Show Blocks', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    expect(mockEditor.registerButton).toHaveBeenCalledWith({
+      name: 'showBlocks',
+      group: 'other',
+      options: {
+        tooltip: 'Show Blocks',
+        isActive: expect.any(Function),
+      },
+    });
+  });
+
+  it('should register command named showBlocks', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    expect(mockEditor.registerCommand).toHaveBeenCalledWith('showBlocks', expect.any(Function));
+  });
+
+  it('should report inactive state initially via isActive', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const buttonConfig = mockEditor.registerButton.mock.calls[0][0] as {
+      options: { isActive: () => boolean };
+    };
+    expect(buttonConfig.options.isActive()).toBe(false);
+  });
+
+  it('should add show-blocks class to editor on first toggle', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+    commandFn();
+
+    expect(mockClassList.add).toHaveBeenCalledWith('jodit-show-blocks');
+  });
+
+  it('should inject a style element on first toggle', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+    commandFn();
+
+    expect(mockEditorDoc.createElement).toHaveBeenCalledWith('style');
+    expect(mockStyleElement.setAttribute).toHaveBeenCalledWith('data-jodit-show-blocks', '');
+    expect(mockStyleElement.textContent).toBeTruthy();
+    expect(mockEditorDoc.head.appendChild).toHaveBeenCalledWith(mockStyleElement);
+  });
+
+  it('should include CSS rules for common block tags', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+    commandFn();
+
+    const css = mockStyleElement.textContent as string;
+    expect(css).toContain('.jodit-show-blocks p');
+    expect(css).toContain('.jodit-show-blocks div');
+    expect(css).toContain('.jodit-show-blocks h1');
+    expect(css).toContain('.jodit-show-blocks blockquote');
+    expect(css).toContain('.jodit-show-blocks table');
+    expect(css).toContain('border: 1px dashed');
+    expect(css).toContain('content: "p"');
+    expect(css).toContain('content: "h1"');
+  });
+
+  it('should fire updateToolbar event on toggle', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+    commandFn();
+
+    expect(mockEditor.events.fire).toHaveBeenCalledWith('updateToolbar');
+  });
+
+  it('should report active state after first toggle via isActive', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+    commandFn();
+
+    const buttonConfig = mockEditor.registerButton.mock.calls[0][0] as {
+      options: { isActive: () => boolean };
+    };
+    expect(buttonConfig.options.isActive()).toBe(true);
+  });
+
+  it('should remove show-blocks class and styles on second toggle', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+
+    // Toggle on
+    commandFn();
+    // Toggle off
+    commandFn();
+
+    expect(mockClassList.remove).toHaveBeenCalledWith('jodit-show-blocks');
+    expect(mockStyleElement.remove).toHaveBeenCalled();
+  });
+
+  it('should report inactive state after toggling off via isActive', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+
+    // Toggle on then off
+    commandFn();
+    commandFn();
+
+    const buttonConfig = mockEditor.registerButton.mock.calls[0][0] as {
+      options: { isActive: () => boolean };
+    };
+    expect(buttonConfig.options.isActive()).toBe(false);
+  });
+
+  it('should not create duplicate style elements on repeated activations', async () => {
+    await importPlugin();
+
+    const pluginCallback = getPluginCallback();
+    pluginCallback(mockEditor);
+
+    const commandFn = getCommandFn();
+
+    // Toggle on, off, on
+    commandFn();
+    commandFn();
+    commandFn();
+
+    // createElement should be called twice (once for first on, once for second on after removal)
+    expect(mockEditorDoc.createElement).toHaveBeenCalledTimes(2);
+  });
+});