ckeditor5-blazor 0.1.0

package/src/elements/ui-part.ts

@@ -0,0 +1,84 @@
+import { CKEditor5BlazorError } from '../ckeditor5-blazor-error';
+import { waitForDOMReady } from '../shared';
+import { EditorsRegistry } from './editor/editors-registry';
+import { queryAllEditorIds } from './editor/utils';
+
+/**
+ * UI Part hook for Blazor. It allows you to create UI parts for multi-root editors.
+ */
+export class UIPartComponentElement extends HTMLElement {
+  /**
+   * The promise that resolves when the UI part is mounted.
+   */
+  private mountedPromise: Promise<void> | null = null;
+
+  /**
+   * Mounts the UI part component.
+   */
+  async connectedCallback() {
+    await waitForDOMReady();
+
+    const editorId = this.getAttribute('data-cke-editor-id') || queryAllEditorIds()[0]!;
+    const name = this.getAttribute('data-cke-name');
+
+    /* v8 ignore next if -- @preserve */
+    if (!editorId || !name) {
+      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) => {
+      if (!this.isConnected) {
+        return;
+      }
+
+      const { ui } = editor;
+
+      const uiViewName = mapUIPartView(name);
+      const uiPart = (ui.view as any)[uiViewName!];
+
+      /* v8 ignore next if -- @preserve */
+      if (!uiPart) {
+        throw new CKEditor5BlazorError(`Unknown UI part name: "${name}". Supported names are "toolbar" and "menubar".`);
+      }
+
+      this.appendChild(uiPart.element);
+    });
+  }
+
+  /**
+   * Destroys the UI part component. Unmounts UI parts from the editor.
+   */
+  async 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 = '';
+  }
+}
+
+/**
+ * Maps the UI part name to the corresponding view in the editor.
+ *
+ * @param name The name of the UI part.
+ * @returns The name of the view in the editor.
+ */
+function mapUIPartView(name: string): string | null {
+  switch (name) {
+    case 'toolbar':
+      return 'toolbar';
+
+    case 'menubar':
+      return 'menuBarView';
+
+    /* v8 ignore next -- @preserve */
+    default:
+      return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { CKEditor5BlazorError } from './ckeditor5-blazor-error';
+export { ensureEditorElementsRegistered } from './elements';
+export { ContextsRegistry } from './elements/context/contexts-registry';
+export { EditableComponentElement } from './elements/editable';
+export { EditorComponentElement } from './elements/editor';
+export { CustomEditorPluginsRegistry } from './elements/editor/custom-editor-plugins';
+export { EditorsRegistry } from './elements/editor/editors-registry';
+export { CKEditor5ChangeDataEvent } from './elements/editor/plugins/dispatch-editor-roots-change-event';
+export { UIPartComponentElement } from './elements/ui-part';
+export {
+  createContextBlazorInterop,
+  createEditableBlazorInterop,
+  createEditorBlazorInterop,
+  createUIPartBlazorInterop,
+} from './interop';

package/src/interop/create-context-blazor-interop.test.ts

@@ -0,0 +1,30 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createContextBlazorInterop } from './create-context-blazor-interop';
+
+describe('createContextBlazorInterop', () => {
+  let element: HTMLElement;
+
+  beforeEach(() => {
+    element = document.createElement('ckeditor5-editable');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    element.remove();
+  });
+
+  it('should mark the element as interactive after initialization', () => {
+    expect(element.hasAttribute('data-cke-interactive')).toBe(false);
+
+    createContextBlazorInterop(element);
+
+    expect(element.getAttribute('data-cke-interactive')).toBe('true');
+  });
+
+  it('unmount should not throw', () => {
+    const interop = createContextBlazorInterop(element);
+
+    expect(() => interop.unmount()).not.toThrow();
+  });
+});

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

@@ -0,0 +1,15 @@
+import { markElementAsInteractive } from '../shared';
+
+/**
+ * Creates a simple interop layer for CKEditor 5 context to set the interactive attribute.
+ *
+ * @param element - The root HTML element of the context component, used to identify
+ * the context instance and attach necessary attributes.
+ */
+export function createContextBlazorInterop(element: HTMLElement) {
+  markElementAsInteractive(element);
+
+  return {
+    unmount() {},
+  };
+}

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

@@ -0,0 +1,213 @@
+import type { DotNetInterop } from '../types';
+import type { Mock } from 'vitest';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createDotnet,
+  createDotNetInteropMock,
+  DEFAULT_TEST_EDITOR_ID,
+  renderTestEditable,
+  renderTestEditor,
+  waitForDestroyAllEditors,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
+import { ensureEditorElementsRegistered } from '../elements/ensure-editor-elements-registered';
+import { createEditableBlazorInterop } from './create-editable-blazor-interop';
+
+describe('createEditableBlazorInterop', () => {
+  let element: HTMLElement;
+  let dotnetInterop: DotNetInterop;
+
+  beforeEach(async () => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+
+    dotnetInterop = createDotNetInteropMock();
+    globalThis.DotNet = createDotnet();
+
+    element = renderTestEditable({}, {
+      interactive: false,
+    });
+
+    renderTestEditor();
+    await waitForTestEditor();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    globalThis.DotNet = undefined as unknown as typeof DotNet;
+    document.body.innerHTML = '';
+
+    await waitForDestroyAllEditors();
+  });
+
+  it('sets [data-cke-interactive=true] attribute on the element', async () => {
+    expect(element.hasAttribute('data-cke-interactive')).toBe(false);
+
+    createEditableBlazorInterop(element, dotnetInterop);
+
+    const editor = await waitForTestEditor();
+
+    expect(editor).toBeDefined();
+    expect(element.getAttribute('data-cke-interactive')).toBe('true');
+  });
+
+  it('defaults rootName to "main" when attribute is missing', async () => {
+    element.removeAttribute('data-cke-root-name');
+
+    createEditableBlazorInterop(element, dotnetInterop);
+
+    const editor = await waitForTestEditor();
+    const changeEvent = new CKEditor5ChangeDataEvent({
+      editorId: DEFAULT_TEST_EDITOR_ID,
+      editor,
+      roots: { main: 'changed' },
+    });
+
+    document.body.dispatchEvent(changeEvent);
+
+    expect(dotnetInterop.invokeMethodAsync).toHaveBeenCalledWith(
+      'OnChangeEditableData',
+      expect.anything(),
+      'changed',
+    );
+  });
+
+  it('should ignore ckeditor5 change events from other editors', async () => {
+    createEditableBlazorInterop(element, dotnetInterop);
+
+    const editor = await waitForTestEditor();
+
+    const changeEvent = new CKEditor5ChangeDataEvent({
+      editorId: 'other-editor',
+      editor,
+      roots: { main: 'changed' },
+    });
+
+    document.body.dispatchEvent(changeEvent);
+
+    expect(dotnetInterop.invokeMethodAsync).not.toHaveBeenCalledWith(
+      'OnChangeEditableData',
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  it('should ignore events for an unknown root name', async () => {
+    const custom = renderTestEditable({ rootName: 'other' }, { interactive: false });
+
+    const interop = createEditableBlazorInterop(custom, dotnetInterop);
+    const editor = await waitForTestEditor();
+
+    const changeEvent = new CKEditor5ChangeDataEvent({
+      editorId: DEFAULT_TEST_EDITOR_ID,
+      editor,
+      roots: { unknown: 'value' },
+    });
+
+    (dotnetInterop.invokeMethodAsync as Mock).mockClear();
+    document.body.dispatchEvent(changeEvent);
+    expect(dotnetInterop.invokeMethodAsync).not.toHaveBeenCalled();
+
+    interop.unmount();
+  });
+
+  describe('setValue', () => {
+    it('should be possible to call `setValue` while editor is initializing', async () => {
+      const { setValue } = createEditableBlazorInterop(element, dotnetInterop);
+
+      expect(() => setValue('test')).not.toThrow();
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData()).toBe('<p>test</p>');
+    });
+
+    it('should not set data if the interop is unmounted before the editor is ready', async () => {
+      const { setValue, unmount } = createEditableBlazorInterop(element, dotnetInterop);
+
+      unmount();
+
+      expect(() => setValue('test')).not.toThrow();
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData()).toBe('<p>Initial content</p>');
+    });
+
+    it('should delay setting data if the editor is focused', async () => {
+      const { setValue } = createEditableBlazorInterop(element, dotnetInterop);
+      const editor = await waitForTestEditor();
+
+      editor.ui.focusTracker.isFocused = true;
+
+      await setValue('focused update');
+
+      expect(editor.getData()).toBe('<p>Initial content</p>');
+
+      editor.ui.focusTracker.isFocused = false;
+
+      await vi.waitFor(() => expect(editor.getData()).toBe('<p>focused update</p>'));
+    });
+
+    it('treats null/undefined editor data as empty string when syncing after focus', async () => {
+      const { setValue } = createEditableBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+      const originalGetData = editor.getData;
+
+      (editor as any).getData = () => null;
+
+      editor.ui.focusTracker.isFocused = true;
+      await setValue('from-blazor');
+      expect(editor.getData()).toBe(null);
+
+      editor.ui.focusTracker.isFocused = false;
+      (editor as any).getData = originalGetData;
+      expect(editor.getData()).toBe('<p>from-blazor</p>');
+    });
+  });
+
+  describe('unmount', () => {
+    it('should remove event listeners and prevent future updates', async () => {
+      const interop = createEditableBlazorInterop(element, dotnetInterop);
+      const editor = await waitForTestEditor();
+
+      const changeEvent = new CKEditor5ChangeDataEvent({
+        editorId: DEFAULT_TEST_EDITOR_ID,
+        editor,
+        roots: { main: 'changed' },
+      });
+
+      document.body.dispatchEvent(changeEvent);
+
+      expect(dotnetInterop.invokeMethodAsync).toHaveBeenCalledWith(
+        'OnChangeEditableData',
+        expect.anything(),
+        'changed',
+      );
+
+      (dotnetInterop.invokeMethodAsync as Mock).mockClear();
+
+      interop.unmount();
+      document.body.dispatchEvent(changeEvent);
+
+      expect(dotnetInterop.invokeMethodAsync).not.toBeCalled();
+    });
+
+    it('should not crash if called twice', async () => {
+      const interop = createEditableBlazorInterop(element, dotnetInterop);
+      await waitForTestEditor();
+
+      expect(() => {
+        interop.unmount();
+        interop.unmount();
+      }).not.toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,98 @@
+import type { DotNetInterop } from '../types';
+
+import { EditorsRegistry } from '../elements/editor/editors-registry';
+import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
+import { markElementAsInteractive } from '../shared';
+import { createEditorValueSync, createNoopSync } from './utils/create-editor-value-sync';
+
+/**
+ * Creates an interop layer to synchronize a single CKEditor 5 editable root with a Blazor component.
+ *
+ * @param element - The root HTML element of the editable component, used to identify
+ * the editable instance and attach necessary attributes.
+ * @param interop - The .NET object reference to trigger Blazor methods.
+ * @returns An object containing lifecycle and synchronization methods.
+ */
+export function createEditableBlazorInterop(element: HTMLElement, interop: DotNetInterop) {
+  const editorId = element.getAttribute('data-cke-editor-id');
+  const rootName = element.getAttribute('data-cke-root-name') ?? 'main';
+
+  let unmounted = false;
+  let sync = createNoopSync<string>();
+  let editorRef: unknown | null = null;
+
+  /**
+   * Handles data change events dispatched by the CKEditor plugin.
+   * Filters by both editorId and rootName, then notifies Blazor if the root value changed.
+   * The callback now includes a JS object reference to the underlying editor instance.
+   */
+  const onDataChange = (event: Event) => {
+    if (!(event instanceof CKEditor5ChangeDataEvent) || event.detail.editorId !== editorId) {
+      return;
+    }
+
+    const newValue = event.detail.roots[rootName];
+
+    if (newValue === undefined) {
+      return;
+    }
+
+    if (sync.shouldNotify(newValue)) {
+      void interop.invokeMethodAsync('OnChangeEditableData', editorRef, newValue);
+    }
+  };
+
+  /**
+   * 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);
+
+    sync = createEditorValueSync(editor, {
+      getCurrentValue: () => editor.getData({ rootName }) ?? '',
+      applyValue: value => editor.setData({ [rootName]: value }),
+      isEqual: (a, b) => a === b,
+    });
+  };
+
+  void initializeSynchronization();
+  document.body.addEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
+  markElementAsInteractive(element);
+
+  return {
+    /**
+     * Cleans up all event listeners when the Blazor component is disposed.
+     */
+    unmount() {
+      if (unmounted) {
+        return;
+      }
+
+      document.body.removeEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
+      sync.unmount();
+
+      if (editorRef) {
+        DotNet.disposeJSObjectReference(editorRef);
+        editorRef = null;
+      }
+
+      unmounted = true;
+    },
+
+    /**
+     * Updates this editable root's data from Blazor.
+     * If the editor is focused, the update is deferred until blur to avoid interrupting the user.
+     */
+    setValue: async (value: string) => {
+      if (unmounted) {
+        return;
+      }
+
+      await EditorsRegistry.the.waitFor(editorId);
+
+      // Ensure sync is initialized before forwarding (waitFor guarantees the editor exists)
+      sync.setValue(value);
+    },
+  };
+}

package/src/interop/create-editor-blazor-interop.test.ts

@@ -0,0 +1,183 @@
+import type { DotNetInterop } from '../types';
+import type { Mock } from 'vitest';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createDotnet,
+  createDotNetInteropMock,
+  DEFAULT_TEST_EDITOR_ID,
+  renderTestEditor,
+  waitForDestroyAllEditors,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../../src/shared';
+import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
+import { ensureEditorElementsRegistered } from '../elements/ensure-editor-elements-registered';
+import { createEditorBlazorInterop } from './create-editor-blazor-interop';
+
+describe('createEditorBlazorInterop', () => {
+  let element: HTMLElement;
+  let dotnetInterop: DotNetInterop;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+
+    dotnetInterop = createDotNetInteropMock();
+    globalThis.DotNet = createDotnet();
+
+    element = renderTestEditor({}, {
+      interactive: false,
+    });
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    globalThis.DotNet = undefined as unknown as typeof DotNet;
+    document.body.innerHTML = '';
+
+    await waitForDestroyAllEditors();
+  });
+
+  it('sets [data-cke-interactive=true] attribute on the element', async () => {
+    expect(element.hasAttribute('data-cke-interactive')).toBe(false);
+
+    createEditorBlazorInterop(element, dotnetInterop);
+
+    const editor = await waitForTestEditor();
+
+    expect(editor).toBeDefined();
+    expect(element.getAttribute('data-cke-interactive')).toBe('true');
+  });
+
+  it('should ignore ckeditor5 change events from other editors', async () => {
+    createEditorBlazorInterop(element, dotnetInterop);
+
+    const editor = await waitForTestEditor();
+
+    const changeEvent = new CKEditor5ChangeDataEvent({
+      editorId: 'other-editor',
+      editor,
+      roots: { main: 'changed' },
+    });
+
+    document.body.dispatchEvent(changeEvent);
+
+    expect(dotnetInterop.invokeMethodAsync).not.toHaveBeenCalledWith(
+      'OnChangeEditorData',
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  describe('setValue', () => {
+    it('should be possible to call `setValue` while editor is initializing', async () => {
+      const { setValue } = createEditorBlazorInterop(element, dotnetInterop);
+
+      expect(() => setValue({ main: 'test' })).not.toThrow();
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData()).toBe('<p>test</p>');
+    });
+
+    it('should not set data if the interop is unmounted before the editor is ready', async () => {
+      const { setValue, unmount } = createEditorBlazorInterop(element, dotnetInterop);
+
+      unmount();
+
+      expect(() => setValue({ main: 'test' })).not.toThrow();
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.getData()).toBe('<p>Initial content</p>');
+    });
+
+    it('should delay setting data if the editor is focused', async () => {
+      const { setValue } = createEditorBlazorInterop(element, dotnetInterop);
+      const editor = await waitForTestEditor();
+
+      editor.ui.focusTracker.isFocused = true;
+
+      await setValue({ main: 'focused update' });
+
+      expect(editor.getData()).toBe('<p>Initial content</p>');
+
+      editor.ui.focusTracker.isFocused = false;
+
+      await vi.waitFor(() => expect(editor.getData()).toBe('<p>focused update</p>'));
+    });
+  });
+
+  describe('focus tracking', () => {
+    it('should call OnEditorFocus if editor gets focused', async () => {
+      createEditorBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+
+      expect(dotnetInterop.invokeMethodAsync).not.toHaveBeenCalledWith('OnEditorFocus', expect.anything());
+
+      editor.ui.focusTracker.isFocused = true;
+
+      expect(dotnetInterop.invokeMethodAsync).toHaveBeenCalledWith('OnEditorFocus', expect.anything());
+    });
+
+    it('should call OnEditorBlur if editor gets blurred', async () => {
+      createEditorBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+
+      expect(dotnetInterop.invokeMethodAsync).not.toHaveBeenCalledWith('OnEditorBlur', expect.anything());
+
+      editor.ui.focusTracker.isFocused = true;
+
+      await timeout(0);
+
+      editor.ui.focusTracker.isFocused = false;
+
+      await vi.waitFor(() => expect(dotnetInterop.invokeMethodAsync).toHaveBeenCalledWith('OnEditorBlur', expect.anything()));
+    });
+  });
+
+  describe('unmount', () => {
+    it('should remove event listeners and prevent future updates', async () => {
+      const interop = createEditorBlazorInterop(element, dotnetInterop);
+      const editor = await waitForTestEditor();
+
+      const changeEvent = new CKEditor5ChangeDataEvent({
+        editorId: DEFAULT_TEST_EDITOR_ID,
+        editor,
+        roots: { main: 'changed' },
+      });
+
+      document.body.dispatchEvent(changeEvent);
+
+      expect(dotnetInterop.invokeMethodAsync).toHaveBeenCalledWith(
+        'OnChangeEditorData',
+        expect.anything(),
+        { main: 'changed' },
+      );
+
+      (dotnetInterop.invokeMethodAsync as Mock).mockClear();
+
+      interop.unmount();
+      document.body.dispatchEvent(changeEvent);
+
+      expect(dotnetInterop.invokeMethodAsync).not.toBeCalled();
+    });
+
+    it('should not crash if called twice', async () => {
+      const interop = createEditorBlazorInterop(element, dotnetInterop);
+      await waitForTestEditor();
+
+      expect(() => {
+        interop.unmount();
+        interop.unmount();
+      }).not.toThrow();
+    });
+  });
+});