ckeditor5-blazor 1.9.0 → 1.10.0

package/src/elements/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/elements/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/elements/editor/utils/create-editor-in-context.ts

@@ -1,4 +1,3 @@
-import type { EditorCreator } from './wrap-with-watchdog';
 import type { Context, ContextWatchdog, Editor, EditorConfig } from 'ckeditor5';
 
 import { uid } from '../../../shared';
@@ -41,7 +40,7 @@ export async function createEditorInContext({ element, context, creator, config
 
   // Destroying of context is async. There can be situation when the destroy of the context
   // and the destroy of the editor is called in parallel. It often happens during unmounting of
-  // phoenix hooks. Let's make sure that descriptor informs other components, that context is being
+  // blazor hooks. Let's make sure that descriptor informs other components, that context is being
   // destroyed.
   const originalDestroy = context.destroy.bind(context);
   context.destroy = async () => {
@@ -87,3 +86,10 @@ type EditorContextDescriptor = {
   editorContextId: string;
   context: ContextWatchdog<Context>;
 };
+
+/**
+ * Type representing an Editor creator with a create method.
+ */
+type EditorCreator = {
+  create: (...args: any) => Promise<Editor>;
+};

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

@@ -1,3 +1,4 @@
+export * from './cleanup-orphan-editor-elements';
 export * from './create-editor-in-context';
 export * from './get-editor-roots-values';
 export * from './is-single-root-editor';

package/src/elements/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/elements/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');
 
 /**
- * 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/elements/ui-part.test.ts

@@ -136,7 +136,7 @@ describe('ui-part component', () => {
 
     it('should handle destruction when mounted promise is not resolved yet', async () => {
       document.body.innerHTML = '';
-      EditorsRegistry.the.reset();
+      await EditorsRegistry.the.reset();
 
       const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
 

package/src/elements/ui-part.ts

@@ -8,9 +8,9 @@ import { queryAllEditorIds } from './editor/utils';
  */
 export class UIPartComponentElement extends HTMLElement {
   /**
-   * The promise that resolves when the UI part is mounted.
+   * Stops observing the editor registry and immediately runs any pending cleanup.
    */
-  private mountedPromise: Promise<void> | null = null;
+  private unmountEffect: VoidFunction | null = null;
 
   /**
    * Mounts the UI part component.
@@ -26,9 +26,9 @@ export class UIPartComponentElement extends HTMLElement {
       return;
     }
 
-    // If the editor is not registered yet, we will wait for it to be registered.
     this.style.display = 'block';
-    this.mountedPromise = EditorsRegistry.the.execute(editorId, (editor) => {
+
+    this.unmountEffect = EditorsRegistry.the.mountEffect(editorId, (editor) => {
       if (!this.isConnected) {
         return;
       }
@@ -44,22 +44,23 @@ export class UIPartComponentElement extends HTMLElement {
       }
 
       this.appendChild(uiPart.element);
+
+      return () => {
+        this.innerHTML = '';
+      };
     });
   }
 
   /**
    * Destroys the UI part component. Unmounts UI parts from the editor.
    */
-  async disconnectedCallback() {
+  disconnectedCallback() {
     // 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.
-    await this.mountedPromise;
-    this.mountedPromise = null;
-
-    // Unmount all UI parts from the editor.
-    this.innerHTML = '';
+    // Stop observing the registry and run cleanup immediately.
+    this.unmountEffect?.();
+    this.unmountEffect = null;
   }
 }
 

package/src/interop/create-editable-blazor-interop.ts

@@ -20,6 +20,8 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
   const rootName = element.getAttribute('data-cke-root-name') ?? 'main';
 
   let unmounted = false;
+  let stopEffect: VoidFunction | null = null;
+
   let editorRef: unknown | null = null;
 
   let sync = createNoopSync<string>();
@@ -46,12 +48,8 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
     }
   };
 
-  /**
-   * Initializes the focus tracker and model listeners for the editor owning this editable.
-   */
-  const initializeSynchronization = async () => {
-    const editor = await EditorsRegistry.the.waitFor(editorId);
-    editorRef = DotNet.createJSObjectReference(editor);
+  stopEffect = EditorsRegistry.the.mountEffect(editorId, (editor) => {
+    editorRef = globalThis.DotNet.createJSObjectReference(editor);
 
     sync = createEditorValueSync(editor, {
       getCurrentValue: () => editor.getData({ rootName }) ?? '',
@@ -60,9 +58,20 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
     });
 
     syncRootAttributes = createRootAttributesUpdater(editor, rootName);
-  };
 
-  void initializeSynchronization();
+    return () => {
+      sync.unmount();
+
+      /* v8 ignore else -- @preserve */
+      if (editorRef) {
+        globalThis.DotNet?.disposeJSObjectReference(editorRef);
+        editorRef = null;
+      }
+
+      syncRootAttributes = null;
+    };
+  });
+
   document.body.addEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
   markElementAsInteractive(element);
 
@@ -76,14 +85,10 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
       }
 
       document.body.removeEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
-      sync.unmount();
 
-      if (editorRef) {
-        DotNet.disposeJSObjectReference(editorRef);
-        editorRef = null;
-      }
+      stopEffect?.();
+      stopEffect = null;
 
-      syncRootAttributes = null;
       unmounted = true;
     },
 
@@ -97,8 +102,6 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
       }
 
       await EditorsRegistry.the.waitFor(editorId);
-
-      // Ensure sync is initialized before forwarding (waitFor guarantees the editor exists)
       sync.setValue(value);
     },