ckeditor5-symfony 1.0.0

package/src/elements/editable.test.ts

@@ -0,0 +1,334 @@
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorPreset,
+  renderTestEditable,
+  renderTestEditor,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { EditorsRegistry } from './editor/editors-registry';
+import { registerCustomElements } from './register-custom-elements';
+
+describe('editable component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    registerCustomElements();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    document.body.innerHTML = '';
+    EditorsRegistry.the.reset();
+  });
+
+  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');
+      });
+    });
+  });
+
+  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();
+    });
+  });
+});

package/src/elements/editable.ts

@@ -0,0 +1,114 @@
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { CKEditor5SymfonyError } from '../ckeditor5-symfony-error';
+import { debounce, waitForDOMReady } from '../shared';
+import { EditorsRegistry } from './editor/editors-registry';
+import { queryAllEditorIds } from './editor/utils';
+
+/**
+ * Editable hook for Symfony. 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;
+
+  /**
+   * Mounts the editable component.
+   */
+  async connectedCallback() {
+    await waitForDOMReady();
+
+    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 3 */
+    if (!editorId || !rootName) {
+      throw new CKEditor5SymfonyError('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) => {
+      const input = this.querySelector('input') as HTMLInputElement | null;
+      const { ui, editing, model } = editor;
+
+      if (model.document.getRoot(rootName)) {
+        // 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 = () => {
+        const html = editor.getData({ rootName });
+
+        if (input) {
+          input.value = html;
+          input.dispatchEvent(new Event('input'));
+        }
+
+        this.dispatchEvent(new CustomEvent('change', { detail: { value: html } }));
+      };
+
+      editor.model.document.on('change:data', debounce(saveDebounceMs, sync));
+      sync();
+
+      return editor;
+    });
+  }
+
+  /**
+   * Destroys the editable component. Unmounts root from the editor.
+   */
+  async disconnectedCallback() {
+    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;
+
+    // Unmount root from the editor if editor is still registered.
+    if (editor && editor.state !== 'destroyed' && rootName) {
+      const root = editor.model.document.getRoot(rootName);
+
+      if (root && 'detachEditable' in editor) {
+        editor.detachEditable(root);
+        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);
+    });
+  });
+});

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

@@ -0,0 +1,86 @@
+import type { PluginConstructor } from 'ckeditor5';
+
+import type { CanBePromise } from '../../types';
+
+import { CKEditor5SymfonyError } from '../../ckeditor5-symfony-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 CKEditor5SymfonyError(`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 CKEditor5SymfonyError(`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);
+  }
+}