ckeditor5-blazor 0.1.0

package/src/elements/editor/custom-editor-plugins.ts

@@ -0,0 +1,85 @@
+import type { CanBePromise } from '../../types';
+import type { PluginConstructor } from 'ckeditor5';
+
+import { CKEditor5BlazorError } from '../../ckeditor5-blazor-error';
+
+type PluginReader = () => CanBePromise<PluginConstructor>;
+
+/**
+ * Registry for custom CKEditor plugins.
+ * Allows registration and retrieval of custom plugins that can be used alongside built-in plugins.
+ */
+export class CustomEditorPluginsRegistry {
+  static readonly the = new CustomEditorPluginsRegistry();
+
+  /**
+   * Map of registered custom plugins.
+   */
+  private readonly plugins = new Map<string, PluginReader>();
+
+  /**
+   * Private constructor to enforce singleton pattern.
+   */
+  private constructor() {}
+
+  /**
+   * Registers a custom plugin for the CKEditor.
+   *
+   * @param name The name of the plugin.
+   * @param reader The plugin reader function that returns the plugin constructor.
+   * @returns A function to unregister the plugin.
+   */
+  register(name: string, reader: PluginReader): () => void {
+    if (this.plugins.has(name)) {
+      throw new CKEditor5BlazorError(`Plugin with name "${name}" is already registered.`);
+    }
+
+    this.plugins.set(name, reader);
+
+    return this.unregister.bind(this, name);
+  }
+
+  /**
+   * Removes a custom plugin by its name.
+   *
+   * @param name The name of the plugin to unregister.
+   * @throws Will throw an error if the plugin is not registered.
+   */
+  unregister(name: string): void {
+    if (!this.plugins.has(name)) {
+      throw new CKEditor5BlazorError(`Plugin with name "${name}" is not registered.`);
+    }
+
+    this.plugins.delete(name);
+  }
+
+  /**
+   * Removes all custom editor plugins.
+   * This is useful for cleanup in tests or when reloading plugins.
+   */
+  unregisterAll(): void {
+    this.plugins.clear();
+  }
+
+  /**
+   * Retrieves a custom plugin by its name.
+   *
+   * @param name The name of the plugin.
+   * @returns The plugin constructor or undefined if not found.
+   */
+  async get(name: string): Promise<PluginConstructor | undefined> {
+    const reader = this.plugins.get(name);
+
+    return reader?.();
+  }
+
+  /**
+   * Checks if a plugin with the given name is registered.
+   *
+   * @param name The name of the plugin.
+   * @returns `true` if the plugin is registered, `false` otherwise.
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+}

package/src/elements/editor/editor.test.ts

@@ -0,0 +1,562 @@
+import type { LanguageConfig } from 'ckeditor5';
+
+import {
+  BalloonEditor,
+  ClassicEditor,
+  DecoupledEditor,
+  Editor,
+  InlineEditor,
+  MultiRootEditor,
+  Plugin,
+} from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditableSnapshot,
+  createEditorPreset,
+  getTestEditorInput,
+  html,
+  isEditorShown,
+  renderTestEditable,
+  renderTestEditor,
+  waitForDestroyAllEditors,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../../shared/timeout';
+import { ensureEditorElementsRegistered } from '../ensure-editor-elements-registered';
+import { CustomEditorPluginsRegistry } from './custom-editor-plugins';
+import { unwrapEditorWatchdog } from './utils';
+
+describe('editor component', () => {
+  beforeEach(async () => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    document.body.innerHTML = '';
+
+    await waitForDestroyAllEditors();
+  });
+
+  it('should save the editor instance in the registry with provided editorId', async () => {
+    renderTestEditor();
+
+    const editor = await waitForTestEditor();
+
+    expect(editor).toBeInstanceOf(Editor);
+  });
+
+  it('should be possible to pass custom plugins to the editor', async () => {
+    class MyCustomPlugin extends Plugin {
+      static pluginName = 'MyCustomPlugin';
+    }
+
+    const preset = createEditorPreset('classic', {
+      toolbar: [],
+      plugins: ['MyCustomPlugin'],
+    });
+
+    CustomEditorPluginsRegistry.the.register('MyCustomPlugin', () => MyCustomPlugin);
+    renderTestEditor({ preset });
+
+    const editor = await waitForTestEditor();
+
+    expect(editor.plugins.get('MyCustomPlugin')).toBeInstanceOf(MyCustomPlugin);
+  });
+
+  describe('editor types', () => {
+    describe('classic', () => {
+      it('should create an classic editor with default preset', async () => {
+        renderTestEditor();
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(ClassicEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+
+      it('should assign default value from `content` snapshot property', async () => {
+        const initialValue = `<p>Hello World! Today is ${new Date().toLocaleDateString()}</p>`;
+
+        renderTestEditor({
+          content: {
+            main: initialValue,
+          },
+        });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor.getData()).toBe(initialValue);
+      });
+
+      it('should assign empty main value if initialized editor with empty `content` snapshot property', async () => {
+        renderTestEditor({
+          content: {},
+        });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor.getData()).toBe('');
+      });
+    });
+
+    describe('inline', () => {
+      it('should create an inline editor with default preset', async () => {
+        renderTestEditor({ preset: createEditorPreset('inline') });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(InlineEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+    });
+
+    describe('decoupled', () => {
+      it('should create a decoupled editor with `main` editable and default preset', async () => {
+        renderTestEditor({ preset: createEditorPreset('decoupled') });
+        renderTestEditable(createEditableSnapshot('main', null));
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(DecoupledEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+
+      it('should pick initial content from the editable snapshot if provided', async () => {
+        const initialEditableContent = '<p>Initial editable content</p>';
+
+        renderTestEditor({ preset: createEditorPreset('decoupled') });
+        renderTestEditable(createEditableSnapshot('main', initialEditableContent));
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(DecoupledEditor);
+        expect(editor.getData()).toBe(initialEditableContent);
+      });
+
+      it('should wait for root element to be present in DOM if it is not', async () => {
+        renderTestEditor({ preset: createEditorPreset('decoupled') });
+
+        await timeout(200);
+
+        renderTestEditable(createEditableSnapshot('main', null));
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(DecoupledEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+    });
+
+    describe('balloon', () => {
+      it('should create a balloon editor with default preset', async () => {
+        renderTestEditor({ preset: createEditorPreset('balloon') });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(BalloonEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+    });
+
+    describe('multiroot', () => {
+      it('should create a multiroot editor without editables in the DOM and initial content', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {},
+        });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+      });
+
+      it('should wait and for root elements to be present in DOM if they are not (with content=null value)', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {
+            header: '<p>Header root initial content</p>',
+          },
+        });
+
+        await timeout(500); // Simulate some delay before adding the root.
+
+        renderTestEditable(createEditableSnapshot('header'));
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+        expect(editor.getData({ rootName: 'header' })).toBe('<p>Header root initial content</p>');
+      });
+
+      it('should wait and for root elements to be present in DOM if they are not (with content=\'\' value)', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {
+            header: '<p>Header root initial content</p>',
+          },
+        });
+
+        await timeout(500); // Simulate some delay before adding the root.
+
+        renderTestEditable(createEditableSnapshot('header', ''));
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+        expect(editor.getData({ rootName: 'header' })).toBe('');
+      });
+
+      it('should wait and for root elements to be present in DOM if they are not (with set content value)', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {
+            header: '<p>Header root initial content</p>',
+          },
+        });
+
+        renderTestEditable(
+          createEditableSnapshot('header', '<p>Editable content overrides snapshot content</p>'),
+        );
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+
+        await vi.waitFor(() => {
+          expect(editor.getData({ rootName: 'header' })).toBe('<p>Editable content overrides snapshot content</p>');
+        });
+      });
+
+      it('should not crash after setting content using `setData`', async () => {
+        renderTestEditor({
+          content: {
+            main: '<p>Initial content</p>',
+          },
+        });
+
+        const editor = await waitForTestEditor();
+
+        expect(() => {
+          editor.setData('<p>New content</p>');
+        }).not.toThrow();
+      });
+
+      it('should update root data if root already exists but editable has different content', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {},
+        });
+
+        const editor = await waitForTestEditor<MultiRootEditor>();
+
+        editor.addRoot('existingRoot', { data: '<p>Old content</p>' });
+
+        renderTestEditable(createEditableSnapshot('existingRoot', '<p>New content</p>'));
+
+        await vi.waitFor(() => {
+          expect(editor.getData({ rootName: 'existingRoot' })).toBe('<p>New content</p>');
+        });
+      });
+    });
+  });
+
+  describe('`editableHeight` snapshot parameter`', () => {
+    it('should not set any height if `editableHeight` parameter is `null`', async () => {
+      renderTestEditor({ editableHeight: null });
+
+      const editor = await waitForTestEditor();
+
+      const editableElement = editor.ui.getEditableElement()!;
+
+      expect(getComputedStyle(editableElement).height).toBe('');
+    });
+
+    it('should set the editable height if `editableHeight` snapshot parameter is provided', async () => {
+      renderTestEditor({ editableHeight: 400 });
+
+      const editor = await waitForTestEditor();
+
+      const editableElement = editor.ui.getEditableElement()!;
+
+      expect(getComputedStyle(editableElement).height).toBe('400px');
+    });
+  });
+
+  describe('`saveDebounceMs` snapshot parameter`', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    it('should use parameter to debounce input sync', async () => {
+      renderTestEditor({ saveDebounceMs: 400 }, { withInput: true });
+
+      const editor = await waitForTestEditor();
+      const input = getTestEditorInput();
+
+      editor.setData('<p>Debounce test</p>');
+      expect(input.value).to.be.equal('<p>Initial content</p>');
+
+      await vi.advanceTimersByTimeAsync(399);
+      expect(input.value).to.be.equal('<p>Initial content</p>');
+
+      await vi.advanceTimersByTimeAsync(1);
+      expect(input.value).to.be.equal('<p>Debounce test</p>');
+    });
+  });
+
+  describe('`language` snapshot parameter`', () => {
+    it('should be possible to pass language configuration to the editor configuration', async () => {
+      renderTestEditor({
+        language: {
+          ui: 'pl',
+          content: 'de',
+        },
+      });
+
+      const editor = await waitForTestEditor();
+      const configLanguage = editor.config.get('language') as LanguageConfig;
+
+      expect(configLanguage.ui).toBe('pl');
+      expect(configLanguage.content).toBe('de');
+    });
+
+    it('should have buttons translated to the selected UI language', async () => {
+      renderTestEditor({
+        language: {
+          ui: 'pl',
+          content: 'pl',
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.t('Bold')).toBe('Pogrubienie');
+    });
+
+    it('should be possible to pass custom translations to the editor', async () => {
+      const preset = createEditorPreset('classic', {}, {
+        pl: {
+          Bold: 'Czcionka grubaśna',
+        },
+      });
+
+      renderTestEditor({
+        preset,
+        language: {
+          ui: 'pl',
+          content: 'pl',
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.t('Bold')).toBe('Czcionka grubaśna');
+    });
+
+    it('should resolve $translation references in the editor configuration', async () => {
+      const preset = createEditorPreset(
+        'classic',
+        {
+          customPlugin: {
+            label: { $translation: 'Custom' },
+          },
+        },
+        {
+          pl: {
+            Custom: 'Mocarna czcionka',
+          },
+        },
+      );
+
+      renderTestEditor({
+        preset,
+        language: {
+          ui: 'pl',
+          content: 'pl',
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect((editor.config.get('customPlugin') as any).label).toBe('Mocarna czcionka');
+    });
+  });
+
+  describe('`watchdog` snapshot parameter`', () => {
+    it('should not wrap editor with watchdog if `watchdog` is false', async () => {
+      renderTestEditor({
+        watchdog: false,
+      });
+
+      const editor = await waitForTestEditor();
+      const watchdog = unwrapEditorWatchdog(editor);
+
+      expect(watchdog).toBeNull();
+    });
+
+    it('should resurrect editor after crashing and broadcast the new instance when `watchdog` is enabled', async () => {
+      renderTestEditor({
+        editorId: 'editor-with-watchdog',
+        watchdog: true,
+      });
+
+      const originalEditor = await waitForTestEditor('editor-with-watchdog');
+      const watchdog = unwrapEditorWatchdog(originalEditor)!;
+
+      (watchdog as any)._restart();
+
+      await vi.waitFor(async () => {
+        const newEditor = await waitForTestEditor('editor-with-watchdog');
+
+        expect(newEditor).not.equals(originalEditor);
+      });
+    });
+  });
+
+  describe('form integration', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    it('should sync editor data to the associated input field', async () => {
+      renderTestEditor({ saveDebounceMs: 0 }, { withInput: true });
+
+      const editor = await waitForTestEditor();
+      const input = getTestEditorInput();
+
+      editor.setData('<p>Form integration test</p>');
+      await vi.advanceTimersByTimeAsync(1);
+
+      expect(input.value).to.be.equal('<p>Form integration test</p>');
+    });
+
+    it('should not crash if hidden input is not present', async () => {
+      renderTestEditor({ saveDebounceMs: 0 }, { withInput: false });
+
+      const editor = await waitForTestEditor();
+
+      expect(() => {
+        editor.setData('<p>Form integration test</p>');
+        vi.advanceTimersByTime(1);
+      }).not.to.throw();
+    });
+
+    it('should immediately sync editor data to the associated input field on form submit', async () => {
+      const form = html.form({ id: 'form' });
+      document.body.appendChild(form);
+
+      renderTestEditor({ saveDebounceMs: 5000 }, { withInput: true, container: form });
+
+      const editor = await waitForTestEditor();
+      const input = getTestEditorInput();
+
+      editor.setData('<p>Form integration test</p>');
+      await vi.advanceTimersByTimeAsync(1000);
+
+      // Value should not be synced yet due to debounce.
+      expect(input.value).to.be.equal('<p>Initial content</p>');
+
+      // Submit the form.
+      form.dispatchEvent(new Event('submit', { bubbles: true }));
+      await vi.advanceTimersByTimeAsync(1);
+
+      // Value should be synced immediately on form submit.
+      expect(input.value).to.be.equal('<p>Form integration test</p>');
+    });
+  });
+
+  describe('roots change event integration', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    it('should dispatch `ckeditor5:change:data` event with all roots values for single-root editor', async () => {
+      const component = renderTestEditor({ saveDebounceMs: 0 });
+      const changeSpy = vi.fn();
+      const bodyChangeSpy = vi.fn();
+
+      component.addEventListener('ckeditor5:change:data', changeSpy);
+      document.body.addEventListener('ckeditor5:change:data', bodyChangeSpy);
+
+      const editor = await waitForTestEditor();
+
+      editor.setData('<p>Updated main root content</p>');
+      await vi.advanceTimersByTimeAsync(1);
+
+      expect(changeSpy).toHaveBeenCalled();
+      expect((changeSpy.mock.lastCall![0] as CustomEvent).detail).toEqual({
+        editor,
+        editorId: 'test-editor',
+        roots: {
+          main: '<p>Updated main root content</p>',
+        },
+      });
+
+      expect(bodyChangeSpy).toHaveBeenCalled();
+      expect((bodyChangeSpy.mock.lastCall![0] as CustomEvent).detail).toEqual({
+        editor,
+        editorId: 'test-editor',
+        roots: {
+          main: '<p>Updated main root content</p>',
+        },
+      });
+    });
+
+    it('should dispatch `ckeditor5:change:data` event with all roots values for multiroot editor', async () => {
+      const component = renderTestEditor({
+        saveDebounceMs: 0,
+        preset: createEditorPreset('multiroot'),
+        content: {
+          header: '<p>Header root initial content</p>',
+          footer: '<p>Footer root initial content</p>',
+        },
+      });
+
+      const changeSpy = vi.fn();
+
+      component.addEventListener('ckeditor5:change:data', changeSpy);
+
+      renderTestEditable(createEditableSnapshot('header'));
+      renderTestEditable(createEditableSnapshot('footer'));
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      editor.setData({
+        header: '<p>Updated header content</p>',
+        footer: '<p>Updated footer content</p>',
+      });
+
+      await vi.advanceTimersByTimeAsync(1);
+
+      expect(changeSpy).toHaveBeenCalled();
+      expect((changeSpy.mock.lastCall![0] as CustomEvent).detail).toEqual({
+        editor,
+        editorId: 'test-editor',
+        roots: {
+          header: '<p>Updated header content</p>',
+          footer: '<p>Updated footer content</p>',
+        },
+      });
+    });
+  });
+
+  describe('destroy', () => {
+    it('should destroy editor on component unmount', async () => {
+      const component = renderTestEditor();
+
+      const editor = await waitForTestEditor();
+
+      component.remove();
+
+      await vi.waitFor(() => {
+        expect(editor.state).toBe('destroyed');
+      });
+    });
+  });
+});