ckeditor5-livewire 1.9.0 → 1.11.0

package/src/hooks/editor/utils/cleanup-orphan-editor-elements.test.ts

@@ -0,0 +1,285 @@
+import type { Editor } from 'ckeditor5';
+
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { cleanupOrphanEditorElements } from './cleanup-orphan-editor-elements';
+
+describe('cleanupOrphanEditorElements', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('should remove uiElement from the DOM if it is connected', () => {
+    const uiElement = document.createElement('div');
+    document.body.appendChild(uiElement);
+
+    const mockEditor = {
+      ui: { element: uiElement },
+    } as unknown as Editor;
+
+    expect(uiElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(uiElement.isConnected).toBe(false);
+  });
+
+  it('should not remove uiElement from the DOM if it has proper attribute', () => {
+    const uiElement = document.createElement('div');
+
+    uiElement.setAttribute('data-cke-controlled', '');
+    document.body.appendChild(uiElement);
+
+    const mockEditor = {
+      ui: { element: uiElement },
+    } as unknown as Editor;
+
+    expect(uiElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(uiElement.isConnected).toBe(true);
+  });
+
+  it('should not throw an error if uiElement is not connected or does not exist', () => {
+    const uiElement = document.createElement('div');
+
+    const mockEditor = {
+      ui: { element: uiElement },
+    } as unknown as Editor;
+
+    expect(() => cleanupOrphanEditorElements(mockEditor)).not.toThrow();
+    expect(() => cleanupOrphanEditorElements({ ui: {} } as Editor)).not.toThrow();
+  });
+
+  it('should remove toolbar element from the DOM if it is connected', () => {
+    const toolbarElement = document.createElement('div');
+    document.body.appendChild(toolbarElement);
+
+    const mockEditor = {
+      ui: {
+        view: {
+          toolbar: { element: toolbarElement },
+        },
+      },
+    } as unknown as Editor;
+
+    expect(toolbarElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(toolbarElement.isConnected).toBe(false);
+  });
+
+  it('should clear toolbar element instead of removing it when it has data-cke-controlled', () => {
+    const toolbarElement = document.createElement('div');
+    toolbarElement.setAttribute('data-cke-controlled', '');
+    toolbarElement.innerHTML = '<button>Bold</button>';
+    document.body.appendChild(toolbarElement);
+
+    const mockEditor = {
+      ui: {
+        view: {
+          toolbar: { element: toolbarElement },
+        },
+      },
+    } as unknown as Editor;
+
+    expect(toolbarElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(toolbarElement.isConnected).toBe(true);
+    expect(toolbarElement.innerHTML).toBe('');
+  });
+
+  it('should not throw if toolbar element is absent', () => {
+    const mockEditor = {
+      ui: {
+        view: {
+          toolbar: {},
+        },
+      },
+    } as unknown as Editor;
+
+    expect(() => cleanupOrphanEditorElements(mockEditor)).not.toThrow();
+  });
+
+  it('should remove menuBarView element from the DOM if it is connected', () => {
+    const menuBarElement = document.createElement('div');
+    document.body.appendChild(menuBarElement);
+
+    const mockEditor = {
+      ui: {
+        view: {
+          menuBarView: { element: menuBarElement },
+        },
+      },
+    } as unknown as Editor;
+
+    expect(menuBarElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(menuBarElement.isConnected).toBe(false);
+  });
+
+  it('should clear menuBarView element instead of removing it when it has data-cke-controlled', () => {
+    const menuBarElement = document.createElement('div');
+    menuBarElement.setAttribute('data-cke-controlled', '');
+    menuBarElement.innerHTML = '<nav>File Edit</nav>';
+    document.body.appendChild(menuBarElement);
+
+    const mockEditor = {
+      ui: {
+        view: {
+          menuBarView: { element: menuBarElement },
+        },
+      },
+    } as unknown as Editor;
+
+    expect(menuBarElement.isConnected).toBe(true);
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(menuBarElement.isConnected).toBe(true);
+    expect(menuBarElement.innerHTML).toBe('');
+  });
+
+  it('should not throw if menuBarView element is absent', () => {
+    const mockEditor = {
+      ui: {
+        view: {
+          menuBarView: {},
+        },
+      },
+    } as unknown as Editor;
+
+    expect(() => cleanupOrphanEditorElements(mockEditor)).not.toThrow();
+  });
+
+  it('should remove all three ui elements when all are connected', () => {
+    const uiElement = document.createElement('div');
+    const toolbarElement = document.createElement('div');
+    const menuBarElement = document.createElement('div');
+
+    document.body.append(uiElement, toolbarElement, menuBarElement);
+
+    const mockEditor = {
+      ui: {
+        element: uiElement,
+        view: {
+          toolbar: { element: toolbarElement },
+          menuBarView: { element: menuBarElement },
+        },
+      },
+    } as unknown as Editor;
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(uiElement.isConnected).toBe(false);
+    expect(toolbarElement.isConnected).toBe(false);
+    expect(menuBarElement.isConnected).toBe(false);
+  });
+
+  it('should remove _bodyCollectionContainer from the DOM if it is connected', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+
+    const mockEditor = {
+      ui: {
+        view: {
+          body: {
+            _bodyCollectionContainer: container,
+          },
+        },
+      },
+    } as unknown as Editor;
+
+    expect(container.isConnected).toBe(true);
+    cleanupOrphanEditorElements(mockEditor);
+    expect(container.isConnected).toBe(false);
+  });
+
+  it('should clean up corresponding attributes and classes from domRoots', () => {
+    const rootElement = document.createElement('div');
+
+    rootElement.setAttribute('contenteditable', 'true');
+    rootElement.setAttribute('role', 'textbox');
+    rootElement.setAttribute('aria-label', 'Rich Text Editor');
+    rootElement.setAttribute('aria-multiline', 'true');
+    rootElement.setAttribute('spellcheck', 'false');
+
+    rootElement.classList.add(
+      'ck',
+      'ck-content',
+      'ck-editor__editable',
+      'ck-rounded-corners',
+      'ck-editor__editable_inline',
+      'ck-blurred',
+      'ck-focused',
+      'my-custom-class',
+    );
+
+    const domRoots = new Map();
+    domRoots.set('main', rootElement);
+
+    const mockEditor = {
+      editing: {
+        view: {
+          domRoots,
+        },
+      },
+    } as unknown as Editor;
+
+    cleanupOrphanEditorElements(mockEditor);
+
+    expect(rootElement.hasAttribute('contenteditable')).toBe(false);
+    expect(rootElement.hasAttribute('role')).toBe(false);
+    expect(rootElement.hasAttribute('aria-label')).toBe(false);
+    expect(rootElement.hasAttribute('aria-multiline')).toBe(false);
+    expect(rootElement.hasAttribute('spellcheck')).toBe(false);
+
+    const removedClasses = [
+      'ck',
+      'ck-content',
+      'ck-editor__editable',
+      'ck-rounded-corners',
+      'ck-editor__editable_inline',
+      'ck-blurred',
+      'ck-focused',
+    ];
+
+    removedClasses.forEach((className) => {
+      expect(rootElement.classList.contains(className)).toBe(false);
+    });
+
+    expect(rootElement.classList.contains('my-custom-class')).toBe(true);
+  });
+
+  it('should ignore objects in domRoots that are not instances of HTMLElement', () => {
+    const fakeRoot = {
+      removeAttribute: () => {},
+      classList: { remove: () => {} },
+    };
+
+    const domRoots = new Map();
+    domRoots.set('main', fakeRoot);
+
+    const mockEditor = {
+      editing: {
+        view: {
+          domRoots,
+        },
+      },
+    } as unknown as Editor;
+
+    expect(() => cleanupOrphanEditorElements(mockEditor)).not.toThrow();
+  });
+
+  it('should fail gracefully on an empty editor object', () => {
+    const emptyEditor = {} as unknown as Editor;
+
+    expect(() => cleanupOrphanEditorElements(emptyEditor)).not.toThrow();
+  });
+});

package/src/hooks/editor/utils/cleanup-orphan-editor-elements.ts

@@ -0,0 +1,60 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Removes all DOM elements injected by a specific CKEditor instance.
+ * Call this before assigning a new instance (e.g. in the 'restart' watchdog handler),
+ * because the watchdog does not clean up the previous editor's DOM on its own.
+ */
+export function cleanupOrphanEditorElements(editor: Editor): void {
+  const uiElements = [
+    editor.ui?.element,
+    editor.ui?.view?.toolbar?.element,
+    editor.ui?.view?.menuBarView?.element,
+  ].filter(Boolean) as HTMLElement[];
+
+  for (const uiElement of uiElements) {
+    removeOrReset(uiElement);
+  }
+
+  const bodyCollectionContainer = (editor.ui as any)?.view?.body?._bodyCollectionContainer;
+
+  if (bodyCollectionContainer?.isConnected) {
+    removeOrReset(bodyCollectionContainer);
+  }
+
+  const editingView = editor.editing?.view;
+
+  if (editingView) {
+    for (const domRoot of editingView.domRoots.values()) {
+      if (!(domRoot instanceof HTMLElement)) {
+        continue;
+      }
+
+      domRoot.removeAttribute('contenteditable');
+      domRoot.removeAttribute('role');
+      domRoot.removeAttribute('aria-label');
+      domRoot.removeAttribute('aria-multiline');
+      domRoot.removeAttribute('spellcheck');
+      domRoot.classList.remove(
+        'ck',
+        'ck-content',
+        'ck-editor__editable',
+        'ck-rounded-corners',
+        'ck-editor__editable_inline',
+        'ck-blurred',
+        'ck-focused',
+      );
+
+      removeOrReset(domRoot);
+    }
+  }
+
+  function removeOrReset(element: HTMLElement) {
+    if (element.hasAttribute('data-cke-controlled')) {
+      element.innerHTML = '';
+    }
+    else {
+      element.remove();
+    }
+  }
+}

package/src/hooks/editor/utils/create-editor-in-context.ts

@@ -1,7 +1,5 @@
 import type { Context, ContextWatchdog, Editor, EditorConfig } from 'ckeditor5';
 
-import type { EditorCreator } from './wrap-with-watchdog';
-
 import { uid } from '../../../shared';
 
 /**
@@ -70,6 +68,12 @@ export function unwrapEditorContext(editor: Editor): EditorContextDescriptor | n
   return null;
 }
 
+/**
+ * Type representing an Editor creator with a create method.
+ */
+type EditorCreator = {
+  create: (...args: any) => Promise<Editor>;
+};
 /**
  * Parameters for creating an editor in a context.
  */

package/src/hooks/editor/utils/index.ts

@@ -1,5 +1,7 @@
+export * from './cleanup-orphan-editor-elements';
 export * from './create-editor-in-context';
 export * from './get-editor-roots-values';
+export * from './is-multiroot-editor-instance';
 export * from './is-single-root-editor';
 export * from './load-editor-constructor';
 export * from './load-editor-plugins';

package/src/hooks/editor/utils/is-multiroot-editor-instance.ts

@@ -0,0 +1,8 @@
+import type { Editor, MultiRootEditor } from 'ckeditor5';
+
+/**
+ * Check if passed editor is multiroot editor.
+ */
+export function isMultirootEditorInstance(editor: Editor): editor is MultiRootEditor {
+  return 'addEditable' in editor.ui;
+}

package/src/hooks/editor/utils/wrap-with-watchdog.test.ts

@@ -15,31 +15,51 @@ describe('wrap with watchdog', () => {
     element.remove();
   });
 
-  it('returns editor instance after calling Constructor.create', async () => {
-    const { Constructor } = await wrapWithWatchdog(ClassicEditor);
-    const editor = await Constructor.create(element, {
-      licenseKey: 'GPL',
-    });
+  it('returns editor instance after starting the watchdog', async () => {
+    const factory = () => ClassicEditor.create(element, { licenseKey: 'GPL' });
+    const watchdog = await wrapWithWatchdog(factory, null);
 
-    expect(editor).toBeInstanceOf(ClassicEditor);
+    await watchdog.create({});
 
-    await editor.destroy();
+    expect(watchdog.editor).toBeInstanceOf(ClassicEditor);
+
+    await watchdog.destroy();
   });
 
   it('returns instance of watchdog', async () => {
-    const { watchdog } = await wrapWithWatchdog(ClassicEditor);
+    const factory = () => ClassicEditor.create(element, { licenseKey: 'GPL' });
+    const watchdog = await wrapWithWatchdog(factory, null);
 
     expect(watchdog).toBeInstanceOf(EditorWatchdog);
   });
 
   it('should be possible to unwrap watchdog from editor instance', async () => {
-    const { Constructor } = await wrapWithWatchdog(ClassicEditor);
-    const editor = await Constructor.create(element, {
-      licenseKey: 'GPL',
-    });
+    const factory = () => ClassicEditor.create(element, { licenseKey: 'GPL' });
+    const watchdog = await wrapWithWatchdog(factory, null);
+
+    await watchdog.create({});
+
+    expect(unwrapEditorWatchdog(watchdog.editor!)).toBeInstanceOf(EditorWatchdog);
+
+    await watchdog.destroy();
+  });
+
+  it('rebuilds config by calling factory again on restart', async () => {
+    let callCount = 0;
+    const factory = async () => {
+      callCount++;
+      return ClassicEditor.create(element, { licenseKey: 'GPL' });
+    };
+
+    const watchdog = await wrapWithWatchdog(factory, null);
+    await watchdog.create({});
+
+    expect(callCount).toBe(1);
+
+    await (watchdog as any)._restart();
 
-    expect(unwrapEditorWatchdog(editor)).toBeInstanceOf(EditorWatchdog);
+    expect(callCount).toBe(2);
 
-    await editor.destroy();
+    await watchdog.destroy();
   });
 });

package/src/hooks/editor/utils/wrap-with-watchdog.ts

@@ -1,35 +1,32 @@
-import type { Editor, EditorWatchdog } from 'ckeditor5';
+import type { Editor, EditorWatchdog, WatchdogConfig } from 'ckeditor5';
 
-const EDITOR_WATCHDOG_SYMBOL = Symbol.for('elixir-editor-watchdog');
+const EDITOR_WATCHDOG_SYMBOL = Symbol.for('livewire-editor-watchdog');
 
 /**
- * Wraps an Editor creator with a watchdog for automatic recovery.
+ * Wraps an editor factory with a watchdog for automatic recovery.
+ * The factory is invoked on each (re)start, so configuration is rebuilt every time.
  *
- * @param Editor - The Editor creator to wrap.
- * @returns The Editor creator wrapped with a watchdog.
+ * @param factory Async function that creates and returns an Editor instance.
+ * @param watchdogConfig Configuration of the watchdog.
+ * @returns The watchdog instance.
  */
-export async function wrapWithWatchdog(Editor: EditorCreator) {
+export async function wrapWithWatchdog(factory: () => Promise<Editor>, watchdogConfig?: WatchdogConfig | null) {
   const { EditorWatchdog } = await import('ckeditor5');
-  const watchdog = new EditorWatchdog(Editor);
 
-  watchdog.setCreator(async (...args: Parameters<typeof Editor['create']>) => {
-    const editor = await Editor.create(...args);
+  const watchdog = new EditorWatchdog(null, watchdogConfig ?? {
+    crashNumberLimit: 10,
+    minimumNonErrorTimePeriod: 5000,
+  });
+
+  watchdog.setCreator(async () => {
+    const editor = await factory();
 
     (editor as any)[EDITOR_WATCHDOG_SYMBOL] = watchdog;
 
     return editor;
   });
 
-  return {
-    watchdog,
-    Constructor: {
-      create: async (...args: Parameters<typeof Editor['create']>) => {
-        await watchdog.create(...args);
-
-        return watchdog.editor!;
-      },
-    },
-  };
+  return watchdog;
 }
 
 /**
@@ -42,10 +39,3 @@ export function unwrapEditorWatchdog(editor: Editor): EditorWatchdog | null {
 
   return null;
 }
-
-/**
- * Type representing an Editor creator with a create method.
- */
-export type EditorCreator = {
-  create: (...args: any) => Promise<Editor>;
-};

package/src/hooks/ui-part.ts

@@ -5,19 +5,13 @@ import { ClassHook } from './hook';
  * UI Part hook for Livewire. It allows you to create UI parts for multi-root editors.
  */
 export class UIPartComponentHook extends ClassHook<Snapshot> {
-  /**
-   * The promise that resolves when the UI part is mounted.
-   */
-  private mountedPromise: Promise<void> | null = null;
-
   /**
    * Mounts the UI part component.
    */
-  override async mounted() {
+  override mounted() {
     const { editorId, name } = this.canonical;
 
-    // If the editor is not registered yet, we will wait for it to be registered.
-    this.mountedPromise = EditorsRegistry.the.execute(editorId, (editor) => {
+    const unmountEffect = EditorsRegistry.the.mountEffect(editorId, (editor) => {
       /* v8 ignore next if -- @preserve */
       if (this.isBeingDestroyed()) {
         return;
@@ -34,22 +28,22 @@ export class UIPartComponentHook extends ClassHook<Snapshot> {
       }
 
       this.element.appendChild(uiPart.element);
+
+      return () => {
+        this.element.innerHTML = '';
+      };
     });
+
+    this.onBeforeDestroy(unmountEffect);
   }
 
   /**
    * Destroys the UI part component. Unmounts UI parts from the editor.
    */
-  override async destroyed() {
+  override destroyed() {
     // Let's hide the element during destruction to prevent flickering.
+    // The innerHTML cleanup is handled by the mountEffect cleanup function.
     this.element.style.display = 'none';
-
-    // Let's wait for the mounted promise to resolve before proceeding with destruction.
-    await this.mountedPromise;
-    this.mountedPromise = null;
-
-    // Unmount all UI parts from the editor.
-    this.element.innerHTML = '';
   }
 }
 

package/src/shared/are-maps-equal.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { areMapsEqual } from './are-maps-equal';
+
+describe('areMapsEqual', () => {
+  it('should return true for two empty maps', () => {
+    expect(areMapsEqual(new Map(), new Map())).toBe(true);
+  });
+
+  it('should return true for maps with identical keys and primitive values', () => {
+    const map1 = new Map([['a', 1], ['b', 2]]);
+    const map2 = new Map([['a', 1], ['b', 2]]);
+
+    expect(areMapsEqual(map1, map2)).toBe(true);
+  });
+
+  it('should return false if map sizes are different', () => {
+    const map1 = new Map([['a', 1]]);
+    const map2 = new Map([['a', 1], ['b', 2]]);
+
+    expect(areMapsEqual(map1, map2)).toBe(false);
+  });
+
+  it('should return false if the keys are different', () => {
+    const map1 = new Map([['a', 1], ['c', 2]]);
+    const map2 = new Map([['a', 1], ['b', 2]]);
+
+    expect(areMapsEqual(map1, map2)).toBe(false);
+  });
+
+  it('should return false if the values for the same keys are different', () => {
+    const map1 = new Map([['a', 1], ['b', 3]]);
+    const map2 = new Map([['a', 1], ['b', 2]]);
+
+    expect(areMapsEqual(map1, map2)).toBe(false);
+  });
+
+  it('should return false if the first map (map1) is null', () => {
+    const map2 = new Map([['a', 1]]);
+
+    expect(areMapsEqual(null, map2)).toBe(false);
+  });
+
+  it('should correctly handle objects as values using shallow comparison (reference equality)', () => {
+    const obj = { id: 1 };
+
+    const map1 = new Map([['key', obj]]);
+    const map2 = new Map([['key', obj]]);
+
+    expect(areMapsEqual(map1, map2)).toBe(true);
+
+    const map3 = new Map([['key', { id: 1 }]]);
+
+    expect(areMapsEqual(map1, map3)).toBe(false);
+  });
+});

package/src/shared/are-maps-equal.ts

@@ -0,0 +1,22 @@
+/**
+ * Compares two Map structures for equality based on their contents.
+ * The function checks if the maps have the same size, contain the exact same keys,
+ * and have strictly equal values (using shallow comparison).
+ *
+ * @param map1 - The first map to compare (can be null).
+ * @param map2 - The second map to compare.
+ * @returns Returns `true` if the maps are identical in terms of keys and values, otherwise `false`.
+ */
+export function areMapsEqual(map1: Map<any, any> | null, map2: Map<any, any>): boolean {
+  if (!map1 || map1.size !== map2.size) {
+    return false;
+  }
+
+  for (const [key, value] of map1) {
+    if (!map2.has(key) || map2.get(key) !== value) {
+      return false;
+    }
+  }
+
+  return true;
+}