ckeditor5-livewire 0.0.1

package/src/hooks/editable.test.ts

@@ -0,0 +1,276 @@
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditableHtmlElement,
+  createEditableSnapshot,
+  createEditorHtmlElement,
+  createEditorPreset,
+  createEditorSnapshot,
+  LivewireStub,
+  queryEditableInput,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import type { Snapshot as EditorSnapshot } from './editor';
+
+import { EditableComponentHook } from './editable';
+import { EditorComponentHook } from './editor';
+import { registerLivewireComponentHook } from './hook';
+
+describe('editable component', () => {
+  let livewireStub: LivewireStub;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    livewireStub = window.Livewire = new LivewireStub();
+
+    registerLivewireComponentHook('ckeditor5', EditorComponentHook);
+    registerLivewireComponentHook('ckeditor5-editable', EditableComponentHook);
+  });
+
+  afterEach(async () => {
+    await livewireStub.$internal.destroy();
+  });
+
+  describe('mounting editable', () => {
+    it('should add editable root to the editor after mounting editor (empty editor)', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+      });
+
+      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 () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('bar', '<p>Initial bar content</p>'),
+      });
+
+      appendMultirootEditor({
+        bar: '<p>Initial bar content</p>',
+      });
+
+      const editor = await waitForTestEditor();
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo content</p>'),
+      });
+
+      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 () => {
+      appendMultirootEditor({
+        bar: '<p>Initial bar content</p>',
+      });
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('bar', '<p>Initial bar content</p>'),
+      });
+
+      const editor = await waitForTestEditor();
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo content</p>'),
+      });
+
+      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 () => {
+      appendMultirootEditor({
+        main: '<p>Initial main content</p>',
+      });
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('main'),
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData({ rootName: 'main' })).toBe('<p>Initial main content</p>');
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('main'),
+      });
+
+      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 () => {
+      appendMultirootEditor({
+        main: '<p>Initial main content</p>',
+      });
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('main'),
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData({ rootName: 'main' })).toBe('<p>Initial main content</p>');
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('main', '<p>Updated main content</p>'),
+      });
+
+      expect(editor.getData({ rootName: 'main' })).toBe('<p>Updated main content</p>');
+    });
+  });
+
+  describe('input value synchronization', () => {
+    let editor: MultiRootEditor;
+
+    beforeEach(async () => {
+      appendMultirootEditor();
+      editor = await waitForTestEditor();
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should not crash if input is not present', () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement({
+          withInput: false,
+        }),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+      });
+
+      expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo component</p>');
+    });
+
+    it('should synchronize input value after mounting editable', async () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement({
+          id: 'editable-foo',
+        }),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+      });
+
+      const input = queryEditableInput('editable-foo')!;
+
+      expect(input.value).toBe('<p>Initial foo component</p>');
+    });
+
+    it('should debounce input value synchronization', async () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement({
+          id: 'editable-foo',
+        }),
+        ephemeral: {
+          ...createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+          saveDebounceMs: 500,
+        },
+      });
+
+      const input = queryEditableInput('editable-foo')!;
+
+      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('socket synchronization', () => {
+    let editor: MultiRootEditor;
+
+    beforeEach(async () => {
+      appendMultirootEditor();
+      editor = await waitForTestEditor();
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should synchronize socket after mounting editable', async () => {
+      const { $wire } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+      });
+
+      expect($wire.set).toHaveBeenCalledWith('content', '<p>Initial foo component</p>');
+    });
+
+    it('should debounce socket synchronization', async () => {
+      const { $wire } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-editable',
+        el: createEditableHtmlElement(),
+        ephemeral: {
+          ...createEditableSnapshot('foo', '<p>Initial foo component</p>'),
+          saveDebounceMs: 500,
+        },
+      });
+
+      expect($wire.set).toHaveBeenCalledWith('content', '<p>Initial foo component</p>');
+
+      editor.setData({
+        foo: '<p>Modified foo content</p>',
+      });
+
+      vi.advanceTimersByTime(300);
+
+      expect($wire.set).not.toHaveBeenCalledWith('content', '<p>Modified foo content</p>');
+
+      vi.advanceTimersByTime(300);
+
+      expect($wire.set).toHaveBeenCalledWith('content', '<p>Modified foo content</p>');
+    });
+  });
+
+  function appendMultirootEditor(initialContent: Record<string, string> = {}) {
+    livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+      name: 'ckeditor5',
+      el: createEditorHtmlElement(),
+      ephemeral: {
+        ...createEditorSnapshot(),
+        preset: createEditorPreset('multiroot'),
+        content: initialContent,
+      },
+    });
+  }
+});

package/src/hooks/editable.ts

@@ -0,0 +1,122 @@
+import type { MultiRootEditor } from 'ckeditor5';
+
+import { debounce } from '../shared';
+import { EditorsRegistry } from './editor/editors-registry';
+import { ClassHook } from './hook';
+
+/**
+ * Editable hook for Livewire. It allows you to create editables for multi-root editors.
+ */
+export class EditableComponentHook extends ClassHook<Snapshot> {
+  /**
+   * The promise that resolves when the editable is mounted.
+   */
+  private editorPromise: Promise<MultiRootEditor> | null = null;
+
+  /**
+   * Mounts the editable component.
+   */
+  override mounted() {
+    const { editorId, rootName, content, saveDebounceMs } = this.ephemeral;
+    const input = this.element.querySelector<HTMLInputElement>('input');
+
+    // If the editor is not registered yet, we will wait for it to be registered.
+    this.editorPromise = EditorsRegistry.the.execute(editorId, (editor: MultiRootEditor) => {
+      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.element.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;
+        }
+
+        this.$wire.set('content', html);
+      };
+
+      editor.model.document.on('change:data', debounce(saveDebounceMs, sync));
+      sync();
+
+      return editor;
+    });
+  }
+
+  /**
+   * Destroys the editable component. Unmounts root from the editor.
+   */
+  override async destroyed() {
+    const { rootName } = this.ephemeral;
+
+    // Let's hide the element during destruction to prevent flickering.
+    this.element.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') {
+      const root = editor.model.document.getRoot(rootName);
+
+      if (root && 'detachEditable' in editor) {
+        editor.detachEditable(root);
+        editor.detachRoot(rootName, false);
+      }
+    }
+  }
+}
+
+/**
+ * A snapshot of the Livewire component's state relevant to the CKEditor5 editable hook.
+ */
+export type Snapshot = {
+  /**
+   * The ID of the editor instance this editable belongs to.
+   */
+  editorId: string;
+
+  /**
+   * The name of the root element in the editor.
+   */
+  rootName: string;
+
+  /**
+   * The initial content value for the editable.
+   */
+  content: string | null;
+
+  /**
+   * The debounce time in milliseconds for saving changes.
+   */
+  saveDebounceMs: number;
+};

package/src/hooks/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/hooks/editor/custom-editor-plugins.ts

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