ckeditor5-blazor 0.1.0

package/src/elements/editable.test.ts

@@ -0,0 +1,383 @@
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorPreset,
+  renderTestEditable,
+  renderTestEditor,
+  waitForDestroyAllEditors,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../shared';
+import { ensureEditorElementsRegistered } from './ensure-editor-elements-registered';
+
+describe('editable component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    await waitForDestroyAllEditors();
+
+    document.body.innerHTML = '';
+  });
+
+  describe('mounting editable', () => {
+    it('should add editable root to the editor after mounting editor (empty editor)', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo component</p>');
+      });
+    });
+
+    it('should add editable root to the editor after mounting editor (non-empty editor, other editable defined before)', async () => {
+      renderTestEditable({
+        rootName: 'bar',
+        content: '<p>Initial bar content</p>',
+      });
+
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {
+          bar: '<p>Initial bar content</p>',
+        },
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo content</p>');
+        expect(editor.getData({ rootName: 'bar' })).toBe('<p>Initial bar content</p>');
+      });
+    });
+
+    it('should add editable root to the editor after mounting editor (non-empty editor, other editable defined after)', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {
+          bar: '<p>Initial bar content</p>',
+        },
+      });
+
+      renderTestEditable({
+        rootName: 'bar',
+        content: '<p>Initial bar content</p>',
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo content</p>');
+        expect(editor.getData({ rootName: 'bar' })).toBe('<p>Initial bar content</p>');
+      });
+    });
+
+    it('should do nothing if adding existing root (without provided content)', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {
+          main: '<p>Initial main content</p>',
+        },
+      });
+
+      renderTestEditable({
+        rootName: 'main',
+        content: null,
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'main' })).toBe('<p>Initial main content</p>');
+      });
+    });
+
+    it('should update existing root content if added existing root with provided content', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {
+          main: '<p>Initial main content</p>',
+        },
+      });
+
+      renderTestEditable({
+        rootName: 'main',
+        content: '<p>Updated main content</p>',
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'main' })).toBe('<p>Updated main content</p>');
+      });
+    });
+
+    it('should auto-assign editor ID if not provided', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      await waitForTestEditor<MultiRootEditor>();
+
+      const editable = renderTestEditable({
+        editorId: '',
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editable.getAttribute('data-cke-editor-id')).toBe('test-editor');
+      });
+    });
+
+    it('should not initialize editable if element is disconnected before editor is ready', async () => {
+      const el = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Foo</p>',
+      });
+      el.remove();
+
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      await timeout(10);
+
+      expect(editor.model.document.getRoot('foo')).toBe(null);
+    });
+  });
+
+  describe('input value synchronization', () => {
+    let editor: MultiRootEditor;
+
+    beforeEach(async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      editor = await waitForTestEditor<MultiRootEditor>();
+      vi.useFakeTimers();
+    });
+
+    it('should not crash if input is not present', async () => {
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+      }, { withInput: false });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo component</p>');
+      });
+    });
+
+    it('should synchronize input value after mounting editable', async () => {
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+      }, { withInput: true });
+
+      const input = element.querySelector('input')!;
+
+      await vi.waitFor(() => {
+        expect(input.value).toBe('<p>Initial foo component</p>');
+      });
+    });
+
+    it('should debounce input value synchronization', async () => {
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+        saveDebounceMs: 500,
+      }, { withInput: true });
+
+      const input = element.querySelector('input')!;
+
+      await vi.waitFor(() => {
+        expect(input.value).toBe('<p>Initial foo component</p>');
+      });
+
+      editor.setData({
+        foo: '<p>Modified foo content</p>',
+      });
+
+      vi.advanceTimersByTime(300);
+      expect(input.value).toBe('<p>Initial foo component</p>');
+
+      vi.advanceTimersByTime(300);
+      expect(input.value).toBe('<p>Modified foo content</p>');
+    });
+  });
+
+  describe('web component events', () => {
+    let editor: MultiRootEditor;
+
+    beforeEach(async () => {
+      vi.useFakeTimers();
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+      editor = await waitForTestEditor<MultiRootEditor>();
+    });
+
+    it('should emit change event when editor data changes', async () => {
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial content</p>',
+        saveDebounceMs: 100,
+      });
+
+      const changeSpy = vi.fn();
+      element.addEventListener('change', changeSpy);
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial content</p>');
+      });
+
+      // Clear spy after initial sync
+      changeSpy.mockClear();
+
+      editor.setData({ foo: '<p>New content</p>' });
+
+      vi.advanceTimersByTime(150);
+
+      expect(changeSpy).toHaveBeenCalledTimes(1);
+      expect((changeSpy.mock.lastCall![0] as CustomEvent).detail.value).toBe('<p>New content</p>');
+    });
+  });
+
+  describe('destroy', () => {
+    it('should detach editable root from editor on component unmount', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.model.document.getRoot('foo')!.isAttached()).toBe(true);
+      });
+
+      element.remove();
+
+      await vi.waitFor(() => {
+        expect(editor.model.document.getRoot('foo')?.isAttached()).toBe(false);
+      });
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should hide element during destruction', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBeDefined();
+      });
+
+      element.remove();
+
+      expect(element.style.display).toBe('none');
+    });
+
+    it('should not crash if editor was destroyed before editable', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editorElement = document.querySelector('cke5-editor')!;
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.getData({ rootName: 'foo' })).toBeDefined();
+      });
+
+      editorElement.remove();
+
+      await vi.waitFor(() => expect(editor.state).toBe('destroyed'));
+
+      expect(() => element.remove()).not.toThrow();
+    });
+
+    it('should not attempt to detach root again if it is already detached', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+      const element = renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo content</p>',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.model.document.getRoot('foo')!.isAttached()).toBe(true);
+      });
+
+      const detachSpy = vi.spyOn(editor, 'detachRoot');
+      editor.detachRoot('foo', false);
+      expect(detachSpy).toHaveBeenCalledTimes(1);
+
+      detachSpy.mockClear();
+
+      element.remove();
+      await timeout(10);
+
+      expect(detachSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/elements/editable.ts

@@ -0,0 +1,183 @@
+import type { WaitForInteractiveResult } from '../shared';
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { CKEditor5BlazorError } from '../ckeditor5-blazor-error';
+import { debounce, waitForDOMReady, waitForInteractiveAttribute } from '../shared';
+import { EditorsRegistry } from './editor/editors-registry';
+import { queryAllEditorIds } from './editor/utils';
+
+/**
+ * Editable hook for Blazor. It allows you to create editables for multi-root editors.
+ */
+export class EditableComponentElement extends HTMLElement {
+  /**
+   * The promise that resolves when the editable is mounted.
+   */
+  private editorPromise: Promise<MultiRootEditor | null> | null = null;
+
+  /**
+   * Wait result for the interactive attribute.
+   */
+  private interactiveWait?: WaitForInteractiveResult;
+
+  /**
+   * Callbacks to be invoked before the editable is destroyed.
+   */
+  private beforeDestroyCallbacks: Array<() => void> = [];
+
+  /**
+   * Registers a callback to be called before the editable is destroyed.
+   */
+  public onBeforeDestroy(callback: () => void): void {
+    this.beforeDestroyCallbacks.push(callback);
+  }
+
+  /**
+   * Mounts the editable component.
+   */
+  async connectedCallback() {
+    await waitForDOMReady();
+
+    this.interactiveWait = waitForInteractiveAttribute(this);
+    await this.interactiveWait.promise;
+    await this.initializeEditable();
+  }
+
+  /**
+   * Initializes the editable instance.
+   */
+  private async initializeEditable(): Promise<void> {
+    if (!this.hasAttribute('data-cke-editor-id')) {
+      this.setAttribute('data-cke-editor-id', queryAllEditorIds()[0]!);
+    }
+
+    const editorId = this.getAttribute('data-cke-editor-id');
+    const rootName = this.getAttribute('data-cke-root-name');
+    const content = this.getAttribute('data-cke-content');
+    const saveDebounceMs = Number.parseInt(this.getAttribute('data-cke-save-debounce-ms')!, 10);
+
+    /* v8 ignore next if -- @preserve */
+    if (!editorId || !rootName) {
+      throw new CKEditor5BlazorError('Editor ID or Root Name is missing.');
+    }
+
+    // If the editor is not registered yet, we will wait for it to be registered.
+    this.style.display = 'block';
+    this.editorPromise = EditorsRegistry.the.execute(editorId, async (editor: MultiRootEditor) => {
+      if (!this.isConnected) {
+        return null;
+      }
+
+      const { ui, editing, model } = editor;
+
+      const input = this.querySelector('input') as HTMLInputElement | null;
+      const root = model.document.getRoot(rootName);
+
+      if (root?.isAttached()) {
+        // If the newly added root already exists, but the newly added editable has content,
+        // we need to update the root data with the editable content.
+        if (content !== null) {
+          const data = editor.getData({ rootName });
+
+          if (data && data !== content) {
+            editor.setData({
+              [rootName]: content,
+            });
+          }
+        }
+
+        return editor;
+      }
+
+      editor.addRoot(rootName, {
+        isUndoable: false,
+        ...content !== null && {
+          data: content,
+        },
+      });
+
+      const contentElement = this.querySelector('[data-cke-editable-content]') as HTMLElement | null;
+      const editable = ui.view.createEditable(rootName, contentElement!);
+
+      ui.addEditable(editable);
+      editing.view.forceRender();
+
+      // Sync data with socket and input element.
+      const sync = () => {
+        if (!model.document.getRoot(rootName)?.isAttached()) {
+          return;
+        }
+
+        const html = editor.getData({ rootName });
+
+        if (input) {
+          input.value = html;
+          input.dispatchEvent(new Event('input'));
+        }
+
+        this.dispatchEvent(new CustomEvent('change', {
+          detail: {
+            value: html,
+          },
+        }));
+      };
+
+      const debouncedSync = debounce(saveDebounceMs, sync);
+
+      editor.model.document.on('change:data', debouncedSync);
+      this.onBeforeDestroy(() => editor.model.document.off('change:data', debouncedSync));
+      sync();
+
+      return editor;
+    });
+  }
+
+  /**
+   * Destroys the editable component. Unmounts root from the editor.
+   */
+  async disconnectedCallback() {
+    // Disconnect the observer if present.
+    this.interactiveWait?.disconnect();
+
+    const rootName = this.getAttribute('data-cke-root-name');
+
+    // Let's hide the element during destruction to prevent flickering.
+    this.style.display = 'none';
+
+    // Let's wait for the mounted promise to resolve before proceeding with destruction.
+    const editor = await this.editorPromise;
+    this.editorPromise = null;
+
+    // Run all registered pre-destroy callbacks and clear the queue.
+    for (const callback of this.beforeDestroyCallbacks) {
+      callback();
+    }
+
+    this.beforeDestroyCallbacks = [];
+
+    // Unmount root from the editor if editor is still registered.
+    if (editor && editor.state !== 'destroyed' && rootName) {
+      const root = editor.model.document.getRoot(rootName);
+
+      /* v8 ignore else -- @preserve */
+      if (root && 'detachEditable' in editor) {
+        // Detaching editables seem to be buggy when something removed DOM element of the editable (e.g. Blazor re-render) before
+        // the editable is unmounted. To prevent errors in such cases, we will try to detach the editable if it exists, but ignore errors.
+        try {
+          if (editor.ui.view.editables[rootName]) {
+            editor.detachEditable(root);
+          }
+        }
+        catch (err) {
+          // Ignore errors when detaching editable.
+          /* v8 ignore next -- @preserve */
+          console.error('Unable unmount editable from root:', err);
+        }
+
+        if (root.isAttached()) {
+          editor.detachRoot(rootName, false);
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,103 @@
+import { Plugin } from 'ckeditor5';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { CustomEditorPluginsRegistry } from './custom-editor-plugins';
+
+class MockPlugin1 extends Plugin {
+  static get pluginName() {
+    return 'MockPlugin1';
+  }
+}
+
+class MockPlugin2 extends Plugin {
+  static get pluginName() {
+    return 'MockPlugin2';
+  }
+}
+
+describe('custom-editor-plugins', () => {
+  afterEach(() => {
+    CustomEditorPluginsRegistry.the.unregisterAll();
+  });
+
+  describe('register', () => {
+    it('should register a plugin successfully', async () => {
+      const unregister = CustomEditorPluginsRegistry.the.register('test-plugin', () => MockPlugin1);
+
+      expect(await CustomEditorPluginsRegistry.the.get('test-plugin')).toBe(MockPlugin1);
+      expect(typeof unregister).toBe('function');
+    });
+
+    it('should throw an error when registering a plugin with the same name', () => {
+      CustomEditorPluginsRegistry.the.register('duplicate-plugin', () => MockPlugin1);
+
+      expect(() => {
+        CustomEditorPluginsRegistry.the.register('duplicate-plugin', () => MockPlugin2);
+      }).toThrow('Plugin with name "duplicate-plugin" is already registered.');
+    });
+
+    it('should return an unregister function that removes the plugin', async () => {
+      const unregister = CustomEditorPluginsRegistry.the.register('removable-plugin', () => MockPlugin1);
+
+      expect(await CustomEditorPluginsRegistry.the.get('removable-plugin')).toBe(MockPlugin1);
+
+      unregister();
+
+      expect(await CustomEditorPluginsRegistry.the.get('removable-plugin')).toBeUndefined();
+    });
+  });
+
+  describe('unregister', () => {
+    it('should unregister an existing plugin', async () => {
+      CustomEditorPluginsRegistry.the.register('temp-plugin', () => MockPlugin1);
+
+      expect(await CustomEditorPluginsRegistry.the.get('temp-plugin')).toBe(MockPlugin1);
+
+      CustomEditorPluginsRegistry.the.unregister('temp-plugin');
+
+      expect(await CustomEditorPluginsRegistry.the.get('temp-plugin')).toBeUndefined();
+    });
+
+    it('should throw an error when unregistering a non-existent plugin', () => {
+      expect(() => {
+        CustomEditorPluginsRegistry.the.unregister('non-existent');
+      }).toThrow('Plugin with name "non-existent" is not registered.');
+    });
+  });
+
+  describe('unregisterAll', () => {
+    it('should clear all registered plugins', async () => {
+      CustomEditorPluginsRegistry.the.register('plugin-1', () => MockPlugin1);
+      CustomEditorPluginsRegistry.the.register('plugin-2', () => MockPlugin2);
+
+      expect(await CustomEditorPluginsRegistry.the.get('plugin-1')).toBe(MockPlugin1);
+      expect(await CustomEditorPluginsRegistry.the.get('plugin-2')).toBe(MockPlugin2);
+
+      CustomEditorPluginsRegistry.the.unregisterAll();
+
+      expect(await CustomEditorPluginsRegistry.the.get('plugin-1')).toBeUndefined();
+      expect(await CustomEditorPluginsRegistry.the.get('plugin-2')).toBeUndefined();
+    });
+  });
+
+  describe('get', () => {
+    it('should return the correct plugin when it exists', async () => {
+      CustomEditorPluginsRegistry.the.register('existing-plugin', () => MockPlugin1);
+
+      expect(await CustomEditorPluginsRegistry.the.get('existing-plugin')).toBe(MockPlugin1);
+    });
+
+    it('should return undefined for non-existent plugins', async () => {
+      expect(await CustomEditorPluginsRegistry.the.get('non-existent-plugin')).toBeUndefined();
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for registered plugins', () => {
+      CustomEditorPluginsRegistry.the.register('check-plugin', () => MockPlugin1);
+
+      expect(CustomEditorPluginsRegistry.the.has('check-plugin')).toBe(true);
+      expect(CustomEditorPluginsRegistry.the.has('non-existent')).toBe(false);
+    });
+  });
+});