ckeditor5-phoenix 0.1.0

package/src/hooks/editor/editor.test.ts

@@ -0,0 +1,333 @@
+import { ClassicEditor, DecoupledEditor, InlineEditor, MultiRootEditor } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditableHtmlElement,
+  createEditorHtmlElement,
+  createEditorPreset,
+  getTestEditorInput,
+  isEditorShown,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { EditorHook } from './editor';
+import { EditorsRegistry } from './editors-registry';
+
+describe('editor hook', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  afterEach(async () => {
+    await EditorsRegistry.the.destroyAllEditors();
+  });
+
+  describe('mount', () => {
+    it('should save the editor instance in the registry with provided editorId', async () => {
+      const hookElement = createEditorHtmlElement({
+        id: 'magic-editor',
+      });
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      expect(await EditorsRegistry.the.waitForEditor('magic-editor')).toBeInstanceOf(ClassicEditor);
+    });
+
+    describe('classic', () => {
+      it('should create an classic editor with default preset', async () => {
+        const hookElement = createEditorHtmlElement();
+
+        document.body.appendChild(hookElement);
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).to.toBeInstanceOf(ClassicEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+
+      it('should assign default value to the editor using "cke-initial-value" attribute', async () => {
+        const initialValue = `<p>Hello World! Today is ${new Date().toLocaleDateString()}</p>`;
+        const hookElement = createEditorHtmlElement({
+          initialValue,
+        });
+
+        document.body.appendChild(hookElement);
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor.getData()).toBe(initialValue);
+      });
+
+      it('should create an editor even if `cke-initial-value` is not set', async () => {
+        const hookElement = createEditorHtmlElement({
+          initialValue: null,
+        });
+
+        document.body.appendChild(hookElement);
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(ClassicEditor);
+        expect(editor.getData()).toBe('');
+
+        expect(isEditorShown()).toBe(true);
+      });
+    });
+
+    describe('decoupled', () => {
+      it('should be possible to create decoupled editor with editable', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('decoupled'),
+        });
+
+        document.body.appendChild(hookElement);
+        document.body.appendChild(createEditableHtmlElement());
+
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(DecoupledEditor);
+        expect(editor.getData()).toBe('<p>Test content</p>');
+
+        expect(isEditorShown()).toBe(true);
+      });
+
+      it('if the initial value is specified on the editable, it should ignore initial value set on the editor', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('decoupled'),
+          initialValue: '<p>Ignored content</p>',
+        });
+
+        document.body.appendChild(hookElement);
+        document.body.appendChild(createEditableHtmlElement({
+          initialValue: '<p>Editable value</p>',
+        }));
+
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(DecoupledEditor);
+        expect(editor.getData()).toBe('<p>Editable value</p>');
+
+        expect(isEditorShown()).toBe(true);
+      });
+
+      it('should not match editables form the other editors', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('decoupled'),
+          initialValue: null,
+        });
+
+        const editables = {
+          current: createEditableHtmlElement({
+            id: 'test-editor',
+            initialValue: '<p>XD</p>',
+          }),
+          other: createEditableHtmlElement({
+            id: 'other-editor',
+            name: 'main',
+            initialValue: '<p>Other content</p>',
+            editorId: 'other-editor-1',
+          }),
+          other1: createEditableHtmlElement({
+            id: 'other-editor-1',
+            name: 'main',
+            initialValue: '<p>Other content 1</p>',
+            editorId: 'other-editor-1',
+          }),
+        };
+
+        document.body.appendChild(hookElement);
+        document.body.appendChild(editables.other1);
+        document.body.appendChild(editables.current);
+        document.body.appendChild(editables.other);
+
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(DecoupledEditor);
+        expect(editor.getData()).toBe('<p>XD</p>');
+      });
+    });
+
+    describe('inline', () => {
+      it('should create an inline editor with default preset', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('inline'),
+        });
+
+        document.body.appendChild(hookElement);
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(InlineEditor);
+        expect(isEditorShown()).toBe(true);
+      });
+    });
+
+    describe('multiroot', () => {
+      it('should create a multiroot editor without editables', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('multiroot'),
+        });
+
+        document.body.appendChild(hookElement);
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+      });
+
+      it('should create a multiroot editor with editables', async () => {
+        const hookElement = createEditorHtmlElement({
+          preset: createEditorPreset('multiroot'),
+        });
+
+        document.body.appendChild(hookElement);
+        document.body.appendChild(createEditableHtmlElement({
+          name: 'main',
+          initialValue: '<p>Main root</p>',
+        }));
+
+        document.body.appendChild(createEditableHtmlElement({
+          name: 'second',
+          initialValue: '<p>Second root</p>',
+        }));
+
+        EditorHook.mounted.call({ el: hookElement });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor).toBeInstanceOf(MultiRootEditor);
+        expect(editor.getData({ rootName: 'main' })).toBe('<p>Main root</p>');
+        expect(editor.getData({ rootName: 'second' })).toBe('<p>Second root</p>');
+      });
+    });
+  });
+
+  describe('destroy', () => {
+    it('should destroy editor on hook destruction', async () => {
+      const hookElement = createEditorHtmlElement();
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      const editor = await waitForTestEditor();
+
+      EditorHook.destroyed.call({ el: hookElement });
+
+      expect(EditorsRegistry.the.getEditors()).toContain(editor);
+
+      await new Promise((resolve) => {
+        editor.once('destroy', resolve);
+        editor.destroy();
+      });
+
+      expect(EditorsRegistry.the.getEditors()).not.toContain(editor);
+    });
+
+    it('should mark the element as hidden during destruction', async () => {
+      const hookElement = createEditorHtmlElement();
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      await waitForTestEditor();
+
+      expect(hookElement.style.display).toBe('');
+
+      EditorHook.destroyed.call({ el: hookElement });
+
+      expect(hookElement.style.display).toBe('none');
+    });
+  });
+
+  describe('value synchronization', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should not crash if input is not present', async () => {
+      const initialValue = `<p>Test content</p>`;
+      const hookElement = createEditorHtmlElement({
+        initialValue,
+        withInput: false,
+      });
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      await waitForTestEditor();
+    });
+
+    it('should initialize the input with the initial value', async () => {
+      const initialValue = `<p>Test content</p>`;
+      const hookElement = createEditorHtmlElement({
+        initialValue,
+        withInput: true,
+      });
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      await waitForTestEditor();
+
+      const input = getTestEditorInput();
+
+      expect(input.value).toBe(initialValue);
+    });
+
+    it('should sync editor data with a hidden input', async () => {
+      const initialValue = `<p>Initial content</p>`;
+      const hookElement = createEditorHtmlElement({
+        initialValue,
+        withInput: true,
+      });
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      const editor = await waitForTestEditor();
+      const input = getTestEditorInput();
+
+      editor.setData('<p>Updated content</p>');
+
+      // Test if sync is debounced
+      expect(input.value).toBe(initialValue);
+
+      await vi.advanceTimersByTimeAsync(500);
+
+      expect(input.value).toBe('<p>Updated content</p>');
+    });
+  });
+
+  describe('`cke-editable-height` attribute', () => {
+    it('should set the height of the editable area', async () => {
+      const editableHeight = 255;
+      const hookElement = createEditorHtmlElement({
+        editableHeight,
+      });
+
+      document.body.appendChild(hookElement);
+      EditorHook.mounted.call({ el: hookElement });
+
+      const editor = await waitForTestEditor();
+      const editable = editor.editing.view.document.getRoot('main');
+
+      expect(editable?.getStyle('height')).toBe(`${editableHeight}px`);
+    });
+  });
+});

package/src/hooks/editor/editor.ts

@@ -0,0 +1,179 @@
+import type { Editor } from 'ckeditor5';
+
+import type { EditorId, EditorType } from './typings';
+
+import {
+  debounce,
+  mapObjectValues,
+  parseIntIfNotNull,
+} from '../../shared';
+import { ClassHook, makeHook } from '../../shared/hook';
+import { EditorsRegistry } from './editors-registry';
+import {
+  isSingleEditingLikeEditor,
+  loadEditorConstructor,
+  loadEditorPlugins,
+  queryAllEditorEditables,
+  readPresetOrThrow,
+  setEditorEditableHeight,
+} from './utils';
+
+/**
+ * Editor hook for Phoenix LiveView.
+ *
+ * This class is a hook that can be used with Phoenix LiveView to integrate
+ * the CKEditor 5 WYSIWYG editor.
+ */
+class EditorHookImpl extends ClassHook {
+  /**
+   * The name of the hook.
+   */
+  private editorPromise: Promise<Editor> | null = null;
+
+  /**
+   * Attributes for the editor instance.
+   */
+  private get attrs() {
+    const value = {
+      editorId: this.el.getAttribute('id')!,
+      preset: readPresetOrThrow(this.el),
+      editableHeight: parseIntIfNotNull(this.el.getAttribute('cke-editable-height')),
+    };
+
+    Object.defineProperty(this, 'attrs', {
+      value,
+      writable: false,
+      configurable: false,
+      enumerable: true,
+    });
+
+    return value;
+  }
+
+  /**
+   * Mounts the editor component.
+   */
+  override async mounted() {
+    this.editorPromise = this.createEditor();
+
+    EditorsRegistry.the.register(this.attrs.editorId, await this.editorPromise);
+  }
+
+  /**
+   * Destroys the editor instance when the component is destroyed.
+   * This is important to prevent memory leaks and ensure that the editor is properly cleaned up.
+   */
+  override async destroyed() {
+    // Let's hide the element during destruction to prevent flickering.
+    this.el.style.display = 'none';
+
+    // Let's wait for the mounted promise to resolve before proceeding with destruction.
+    (await this.editorPromise)?.destroy();
+    this.editorPromise = null;
+
+    EditorsRegistry.the.unregister(this.attrs.editorId);
+  }
+
+  /**
+   * Creates the CKEditor instance.
+   */
+  private createEditor = async () => {
+    const { preset, editorId, editableHeight } = this.attrs;
+    const { type, license, config: { plugins, ...config } } = preset;
+
+    const Constructor = await loadEditorConstructor(type);
+    const rootEditables = getInitialRootsContentElements(editorId, type);
+
+    const editor = await Constructor.create(
+      rootEditables as any,
+      {
+        ...config,
+        initialData: getInitialRootsValues(editorId, type),
+        licenseKey: license.key,
+        plugins: await loadEditorPlugins(plugins),
+      },
+    );
+
+    if (isSingleEditingLikeEditor(type)) {
+      const input = document.getElementById(`${editorId}_input`) as HTMLInputElement | null;
+
+      if (input) {
+        syncEditorToInput(input, editor);
+      }
+
+      if (editableHeight) {
+        setEditorEditableHeight(editor, editableHeight);
+      }
+    }
+
+    return editor;
+  };
+}
+
+/**
+ * Synchronizes the editor's content with a hidden input field.
+ *
+ * @param input The input element to synchronize with the editor.
+ * @param editor The CKEditor instance.
+ */
+function syncEditorToInput(input: HTMLInputElement, editor: Editor) {
+  const sync = () => {
+    input.value = editor.getData();
+  };
+
+  editor.model.document.on('change:data', debounce(250, sync));
+  sync();
+}
+
+/**
+ * Gets the initial root elements for the editor based on its type.
+ *
+ * @param editorId The editor's ID.
+ * @param type The type of the editor.
+ * @returns The root element(s) for the editor.
+ */
+function getInitialRootsContentElements(editorId: EditorId, type: EditorType) {
+  if (isSingleEditingLikeEditor(type)) {
+    return document.getElementById(`${editorId}_editor`)!;
+  }
+
+  const editables = queryAllEditorEditables(editorId);
+
+  return mapObjectValues(editables, ({ content }) => content);
+}
+
+/**
+ * Gets the initial data for the roots of the editor. If the editor is a single editing-like editor,
+ * it retrieves the initial value from the element's attribute. Otherwise, it returns an object mapping
+ * editable names to their initial values.
+ *
+ * @param editorId The editor's ID.
+ * @param type The type of the editor.
+ * @returns The initial values for the editor's roots.
+ */
+function getInitialRootsValues(editorId: EditorId, type: EditorType) {
+  // If the editor is decoupled, the initial value might be specified in the `main` editable.
+  if (type === 'decoupled') {
+    const mainEditableValue = queryAllEditorEditables(editorId)['main']?.initialValue;
+
+    if (mainEditableValue) {
+      return mainEditableValue;
+    }
+  }
+
+  // Let's check initial value assigned to the editor element.
+  if (isSingleEditingLikeEditor(type)) {
+    const initialValue = document.getElementById(editorId)?.getAttribute('cke-initial-value') || '';
+
+    return initialValue;
+  }
+
+  const editables = queryAllEditorEditables(editorId);
+
+  return mapObjectValues(editables, ({ initialValue }) => initialValue);
+}
+
+/**
+ * Phoenix LiveView hook for CKEditor 5.
+ */
+export const EditorHook = makeHook(EditorHookImpl);