ckeditor5-blazor 0.1.0

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

@@ -0,0 +1,112 @@
+import type { DotNetInterop } from '../types';
+
+import { ensureEditorElementsRegistered } from '../elements';
+import { EditorsRegistry } from '../elements/editor/editors-registry';
+import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
+import { getEditorRootsValues } from '../elements/editor/utils';
+import { markElementAsInteractive, shallowEqual } from '../shared';
+import { createEditorValueSync, createNoopSync } from './utils/create-editor-value-sync';
+
+/**
+ * Creates an interop layer to synchronize a CKEditor 5 instance with a Blazor component.
+ *
+ * @param element - The root HTML element of the editor component, used to identify the editor 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 createEditorBlazorInterop(element: HTMLElement, interop: DotNetInterop) {
+  const editorId = element.getAttribute('data-cke-editor-id');
+
+  let unmounted = false;
+  let unmountCKEditorListeners: VoidFunction | null = null;
+
+  let sync = createNoopSync<Record<string, string>>();
+  let editorRef: unknown | null = null;
+
+  // Handles data change events dispatched by the CKEditor plugin.
+  // Dispatches updates back to Blazor if the data has changed.
+  const onDataChange = (event: Event) => {
+    if (!(event instanceof CKEditor5ChangeDataEvent) || event.detail.editorId !== editorId) {
+      return;
+    }
+
+    if (sync.shouldNotify(event.detail.roots)) {
+      void interop.invokeMethodAsync('OnChangeEditorData', editorRef!, event.detail.roots);
+    }
+  };
+
+  /**
+   * Initializes the focus tracker and model listeners for the editor.
+   */
+  const initializeSynchronization = async () => {
+    const editor = await EditorsRegistry.the.waitFor(editorId);
+
+    editorRef = globalThis.DotNet.createJSObjectReference(editor);
+    sync = createEditorValueSync(editor, {
+      getCurrentValue: () => getEditorRootsValues(editor),
+      applyValue: value => editor.setData(value),
+      isEqual: shallowEqual,
+    });
+
+    // Notify Blazor of focus changes so it can trigger the appropriate callbacks.
+    const onFocusChange = (_evt: unknown, _name: unknown, isFocused: boolean) => {
+      const method = isFocused ? 'OnEditorFocus' : 'OnEditorBlur';
+
+      void interop.invokeMethodAsync(method, editorRef);
+    };
+
+    editor.ui.focusTracker.on('change:isFocused', onFocusChange);
+
+    // Notify Blazor that the editor instance is ready so the consumer can
+    // retain an IJSObjectReference or perform additional JS calls directly.
+    // This mirrors the `OnChangeEditorData` (which now also drives the public
+    // `OnChange` event) as well as `OnEditorFocus` and `OnEditorBlur` callbacks
+    // that already exist on the .NET side.
+    void interop.invokeMethodAsync('OnEditorReady', editorRef);
+
+    // When the Blazor component is disposed, clean up event listeners.
+    unmountCKEditorListeners = () => {
+      editor.ui.focusTracker.off('change:isFocused', onFocusChange);
+    };
+  };
+
+  void initializeSynchronization();
+  document.body.addEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
+
+  ensureEditorElementsRegistered();
+  markElementAsInteractive(element);
+
+  return {
+    /**
+     * Updates the editor data from Blazor. If the editor is focused, the update is deferred until blur to avoid interrupting the user.
+     */
+    setValue: async (value: Record<string, string>) => {
+      if (unmounted) {
+        return;
+      }
+
+      await EditorsRegistry.the.waitFor(editorId);
+      sync.setValue(value);
+    },
+
+    /**
+     * Cleans up all event listeners when the Blazor component is disposed.
+     */
+    unmount() {
+      if (unmounted) {
+        return;
+      }
+
+      document.body.removeEventListener(CKEditor5ChangeDataEvent.EVENT_NAME, onDataChange);
+      sync.unmount();
+      unmountCKEditorListeners?.();
+
+      if (editorRef) {
+        globalThis.DotNet.disposeJSObjectReference(editorRef);
+        editorRef = null;
+      }
+
+      unmounted = true;
+    },
+  };
+}

package/src/interop/create-ui-part-blazor-interop.test.ts

@@ -0,0 +1,30 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createUIPartBlazorInterop } from './create-ui-part-blazor-interop';
+
+describe('createUIPartBlazorInterop', () => {
+  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);
+
+    createUIPartBlazorInterop(element);
+
+    expect(element.getAttribute('data-cke-interactive')).toBe('true');
+  });
+
+  it('unmount should not throw', () => {
+    const interop = createUIPartBlazorInterop(element);
+
+    expect(() => interop.unmount()).not.toThrow();
+  });
+});

package/src/interop/create-ui-part-blazor-interop.ts

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

package/src/interop/index.ts

@@ -0,0 +1,4 @@
+export * from './create-context-blazor-interop';
+export * from './create-editable-blazor-interop';
+export * from './create-editor-blazor-interop';
+export * from './create-ui-part-blazor-interop';

package/src/interop/utils/create-editor-value-sync.test.ts

@@ -0,0 +1,302 @@
+import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createEditorValueSync, createNoopSync } from './create-editor-value-sync';
+
+describe('editorValueSync', () => {
+  let editor: ClassicEditor;
+  let element: HTMLDivElement;
+
+  beforeEach(async () => {
+    element = document.createElement('div');
+    document.body.appendChild(element);
+
+    editor = await ClassicEditor.create(element, {
+      licenseKey: 'GPL',
+      plugins: [Essentials, Paragraph],
+      toolbar: [],
+    });
+  });
+
+  afterEach(async () => {
+    await editor.destroy();
+    element.remove();
+  });
+
+  describe('createNoopSync', () => {
+    it('noop: shouldNotify always returns false', () => {
+      const sync = createNoopSync<string>();
+
+      expect(sync.shouldNotify('hello')).toBe(false);
+      expect(sync.shouldNotify('')).toBe(false);
+    });
+
+    it('noop: setValue and unmount do not throw', () => {
+      const sync = createNoopSync<string>();
+
+      expect(() => sync.setValue('x')).not.toThrow();
+      expect(() => sync.unmount()).not.toThrow();
+    });
+  });
+
+  describe('shouldNotify', () => {
+    it('returns true on first call', () => {
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue: v => editor.setData(v),
+        isEqual: (a, b) => a === b,
+      });
+
+      expect(sync.shouldNotify('first')).toBe(true);
+      sync.unmount();
+    });
+
+    it('returns false when the same value is passed twice', () => {
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue: v => editor.setData(v),
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.shouldNotify('same');
+      expect(sync.shouldNotify('same')).toBe(false);
+      sync.unmount();
+    });
+
+    it('returns true when the value changes', () => {
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue: v => editor.setData(v),
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.shouldNotify('first');
+      expect(sync.shouldNotify('second')).toBe(true);
+      sync.unmount();
+    });
+  });
+
+  describe('setValue — editor not focused', () => {
+    it('applies value immediately when editor is not focused', () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.setValue('<p>hello</p>');
+
+      expect(applyValue).toHaveBeenCalledOnce();
+      expect(applyValue).toHaveBeenCalledWith('<p>hello</p>');
+      sync.unmount();
+    });
+
+    it('skips applying when value matches lastSyncedValue', () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.setValue('<p>hello</p>');
+      applyValue.mockClear();
+
+      sync.setValue('<p>hello</p>');
+      expect(applyValue).not.toHaveBeenCalled();
+      sync.unmount();
+    });
+
+    it('skips when value equals lastSyncedValue set by shouldNotify', () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.shouldNotify('<p>blazor-sent</p>');
+      sync.setValue('<p>blazor-sent</p>');
+
+      expect(applyValue).not.toHaveBeenCalled();
+      sync.unmount();
+    });
+  });
+
+  describe('setValue — editor focused', () => {
+    it('defers value while editor is focused, applies on blur', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      editor.editing.view.focus();
+      expect(editor.ui.focusTracker.isFocused).toBe(true);
+
+      sync.setValue('<p>deferred</p>');
+      expect(applyValue).not.toHaveBeenCalled();
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).toHaveBeenCalledOnce();
+      expect(applyValue).toHaveBeenCalledWith('<p>deferred</p>');
+      sync.unmount();
+    });
+
+    it('last value wins when setValue is called multiple times while focused', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      editor.editing.view.focus();
+
+      sync.setValue('<p>v1</p>');
+      sync.setValue('<p>v2</p>');
+      sync.setValue('<p>v3</p>');
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).toHaveBeenCalledOnce();
+      expect(applyValue).toHaveBeenCalledWith('<p>v3</p>');
+      sync.unmount();
+    });
+
+    it('discards pending value when user types before blur', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      editor.editing.view.focus();
+      sync.setValue('<p>stale</p>');
+
+      // Simulate user typing (internal model change → clears pendingValue)
+      editor.model.change((writer) => {
+        const root = editor.model.document.getRoot()!;
+        const paragraph = writer.createElement('paragraph');
+        writer.append(paragraph, root);
+        writer.insertText('typed', paragraph);
+      });
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).not.toHaveBeenCalled();
+      sync.unmount();
+    });
+
+    it('does not apply pending value on blur when it matches current editor content', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+
+      editor.setData('<p>already here</p>');
+
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      editor.editing.view.focus();
+      sync.setValue('<p>already here</p>');
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).not.toHaveBeenCalled();
+      sync.unmount();
+    });
+  });
+
+  describe('unmount', () => {
+    it('stops applying deferred values after unmount', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      editor.editing.view.focus();
+      sync.setValue('<p>pending</p>');
+
+      sync.unmount();
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).not.toHaveBeenCalled();
+    });
+
+    it('is safe to call multiple times', () => {
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue: v => editor.setData(v),
+        isEqual: (a, b) => a === b,
+      });
+
+      expect(() => {
+        sync.unmount();
+        sync.unmount();
+      }).not.toThrow();
+    });
+  });
+
+  describe('integration', () => {
+    it('stale Blazor update does not overwrite user edits', async () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.shouldNotify('<p>Hello</p>');
+
+      editor.editing.view.focus();
+
+      // Blazor sends back the old (stale) value while user is typing
+      sync.setValue('<p>Hello</p>');
+
+      // User types something — change:data fires and discards the pending value
+      editor.model.change((writer) => {
+        const root = editor.model.document.getRoot()!;
+        const paragraph = writer.createElement('paragraph');
+        writer.append(paragraph, root);
+        writer.insertText(' World', paragraph);
+      });
+
+      (document.activeElement as HTMLElement)?.blur();
+      await vi.waitFor(() => expect(editor.ui.focusTracker.isFocused).toBe(false));
+
+      expect(applyValue).not.toHaveBeenCalled();
+      sync.unmount();
+    });
+
+    it('fresh Blazor value is applied when editor is idle', () => {
+      const applyValue = vi.fn((v: string) => editor.setData(v));
+      const sync = createEditorValueSync(editor, {
+        getCurrentValue: () => editor.getData(),
+        applyValue,
+        isEqual: (a, b) => a === b,
+      });
+
+      sync.shouldNotify('<p>old</p>');
+      applyValue.mockClear();
+
+      sync.setValue('<p>brand new</p>');
+
+      expect(applyValue).toHaveBeenCalledWith('<p>brand new</p>');
+      sync.unmount();
+    });
+  });
+});

package/src/interop/utils/create-editor-value-sync.ts

@@ -0,0 +1,160 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Creates a focus-aware value synchronization layer for a CKEditor 5 instance.
+ *
+ * Handles the shared mechanics present in both the Editor and Editable Blazor interops:
+ * - Tracking `lastSyncedValue` to prevent circular Blazor ↔ JS updates.
+ * - Storing a `pendingValue` when a Blazor update arrives while the editor is focused,
+ *   and applying it safely once the user blurs.
+ * - Registering and cleaning up the `change:data` and `change:isFocused` editor listeners.
+ *
+ * @param editor - The CKEditor 5 editor instance to synchronize with.
+ * @param options - Callbacks and equality check specific to the consumer (editor vs editable).
+ * @param options.getCurrentValue - Returns the current value of the tracked root(s) from the editor.
+ * @param options.applyValue - Applies the given value to the editor (e.g. via `editor.setData`).
+ * @param options.isEqual - Returns true if two values are considered equal, used to avoid redundant updates.
+ * @returns An object with `setValue`, `shouldNotify`, and `unmount`.
+ */
+export function createEditorValueSync<T>(
+  editor: Editor,
+  options: {
+
+    /**
+     * Returns the current value of the tracked root(s) from the editor.
+     * Called to compare against the pending value before applying it.
+     */
+    getCurrentValue: () => T;
+
+    /**
+     * Applies the given value to the editor (e.g. via `editor.setData`).
+     */
+    applyValue: (value: T) => void;
+
+    /**
+     * Returns true if two values are considered equal, used to avoid redundant
+     * updates in both directions.
+     */
+    isEqual: (a: T, b: T) => boolean;
+  },
+): EditorValueSync<T> {
+  const state = {
+    /** Value received from Blazor while the editor was focused, pending application on blur. */
+    pendingValue: null as T | null,
+
+    /** The last value sent to or received from Blazor to prevent circular updates. */
+    lastSyncedValue: null as T | null,
+  };
+
+  /**
+   * Any internal model change means the pending external value is stale — discard it.
+   */
+  const onChangeData = () => {
+    state.pendingValue = null;
+  };
+
+  /**
+   * When the editor loses focus, apply any value that Blazor sent while the user was typing.
+   */
+  const onFocusChange = (_evt: unknown, _name: unknown, isFocused: boolean) => {
+    if (isFocused || state.pendingValue === null) {
+      return;
+    }
+
+    const current = options.getCurrentValue();
+
+    if (!options.isEqual(current, state.pendingValue)) {
+      options.applyValue(state.pendingValue);
+    }
+
+    state.pendingValue = null;
+  };
+
+  editor.model.document.on('change:data', onChangeData);
+  editor.ui.focusTracker.on('change:isFocused', onFocusChange);
+
+  return {
+    /**
+     * Removes all editor listeners registered by this sync instance.
+     * Call this when the Blazor component is disposed.
+     */
+    unmount() {
+      editor.model.document.off('change:data', onChangeData);
+      editor.ui.focusTracker.off('change:isFocused', onFocusChange);
+    },
+
+    /**
+     * Checks whether the given value differs from the last synced value and, if so,
+     * updates `lastSyncedValue` and returns `true` to signal that Blazor should be notified.
+     *
+     * Call this from the `CKEditor5ChangeDataEvent` handler to conditionally invoke
+     * the .NET interop method.
+     */
+    shouldNotify(value: T): boolean {
+      if (state.lastSyncedValue !== null && options.isEqual(state.lastSyncedValue, value)) {
+        return false;
+      }
+
+      state.lastSyncedValue = value;
+      return true;
+    },
+
+    /**
+     * Pushes a new value from Blazor into the editor.
+     * If the editor is currently focused, the update is deferred until blur.
+     * If the value matches the last synced state, the update is skipped entirely.
+     */
+    setValue(value: T) {
+      if (editor.ui.focusTracker.isFocused) {
+        state.pendingValue = value;
+        return;
+      }
+
+      if (state.lastSyncedValue !== null && options.isEqual(state.lastSyncedValue, value)) {
+        return;
+      }
+
+      state.lastSyncedValue = value;
+      options.applyValue(value);
+    },
+  };
+}
+
+/**
+ * Returns a no-op {@link EditorValueSync} used as a placeholder before the real editor
+ * instance is available, so callers never have to null-check `sync`.
+ */
+export function createNoopSync<T>(): EditorValueSync<T> {
+  return {
+    unmount() {},
+    shouldNotify(_value: T): boolean { return false; },
+    setValue(_value: T) {},
+  };
+}
+
+/**
+ * The public interface returned by {@link createEditorValueSync} and {@link createNoopSync}.
+ * Typed over the value shape `T` so consumers can declare `sync` variables without
+ * repeating the full return type.
+ */
+export type EditorValueSync<T> = {
+  /** Removes all editor listeners registered by this sync instance. */
+  unmount: () => void;
+
+  /**
+   * Checks whether the given value differs from the last synced value and, if so,
+   * updates `lastSyncedValue` and returns `true` to signal that Blazor should be notified.
+   */
+  /**
+   * Called by the consumer to determine if a value change should trigger a
+   * notification. Returns `true` when the value differs from the last one that
+   * was synced and updates internal tracking.
+   */
+  shouldNotify: (value: T) => boolean;
+
+  /**
+   * Pushes a new value from Blazor into the editor.
+   * Deferred until blur when the editor is focused; skipped when value is unchanged.
+   */
+  setValue: (value: T) => void;
+};

package/src/interop/utils/index.ts

@@ -0,0 +1 @@
+export * from './create-editor-value-sync';