ckeditor5-blazor 0.1.0

package/src/elements/editor/utils/resolve-editor-config-translations.test.ts

@@ -0,0 +1,131 @@
+import type { Translations } from 'ckeditor5';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveEditorConfigTranslations } from './resolve-editor-config-translations';
+
+describe('resolveEditorConfigTranslations', () => {
+  let translationsPacks: Translations[];
+
+  beforeEach(() => {
+    translationsPacks = [
+      makePack('en', {
+        HELLO: 'Hello world',
+        NESTED: 'nested value',
+        ARRAY: 'array value',
+      }),
+    ];
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('resolves a single translation reference', () => {
+    const config = {
+      foo: { $translation: 'HELLO' },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.foo).toBe('Hello world');
+  });
+
+  it('respects specified language when multiple packs present', () => {
+    const packs: Translations[] = [
+      makePack('en', { KEY: 'english' }),
+      makePack('pl', { KEY: 'polish' }),
+    ];
+
+    const result = resolveEditorConfigTranslations(packs, 'pl', { foo: { $translation: 'KEY' } });
+    expect(result.foo).toBe('polish');
+  });
+
+  it('returns null if translation key not found', () => {
+    const config = {
+      foo: { $translation: 'MISSING' },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.foo).toBeNull();
+  });
+
+  it('recursively resolves nested translation references', () => {
+    const config = {
+      nested: {
+        bar: { $translation: 'NESTED' },
+      },
+    };
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(result.nested.bar).toBe('nested value');
+  });
+
+  it('resolves translation references in arrays', () => {
+    const config = [
+      { $translation: 'HELLO' },
+      { $translation: 'ARRAY' },
+      { notTranslation: 123 },
+    ];
+
+    const result = resolveEditorConfigTranslations(translationsPacks, 'en', config);
+
+    expect(result[0]).toBe('Hello world');
+    expect(result[1]).toBe('array value');
+    expect(result[2]).toEqual({ notTranslation: 123 });
+  });
+
+  it('returns primitives as is', () => {
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', 42 as any)).toBe(42);
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', 'foo' as any)).toBe('foo');
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', null as any)).toBe(null);
+    expect(resolveEditorConfigTranslations(translationsPacks, 'en', undefined as any)).toBe(undefined);
+  });
+
+  it('warns for missing translation key', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = { foo: { $translation: 'UNKNOWN' } };
+
+    resolveEditorConfigTranslations(translationsPacks, 'en', config);
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Translation not found for key: UNKNOWN'));
+  });
+
+  it('selects translations based on the provided language when multiple packs are given', () => {
+    const packs: Translations[] = [
+      makePack('en', { HELLO: 'Hello world', ARRAY: 'array value' }),
+      makePack('pl', { NESTED: 'nested value' }),
+    ];
+
+    const config = {
+      foo: { $translation: 'HELLO' },
+      nested: { bar: { $translation: 'NESTED' } },
+      arr: [{ $translation: 'ARRAY' }],
+      missing: { $translation: 'NOTHING' },
+    };
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const resultEn = resolveEditorConfigTranslations(packs, 'en', config);
+
+    expect(resultEn.foo).toBe('Hello world');
+    expect(resultEn.nested.bar).toBeNull();
+    expect(resultEn.arr[0]).toBe('array value');
+    expect(resultEn.missing).toBeNull();
+
+    const resultPl = resolveEditorConfigTranslations(packs, 'pl', config);
+
+    expect(resultPl.foo).toBeNull();
+    expect(resultPl.nested.bar).toBe('nested value');
+    expect(resultPl.arr[0]).toBeNull();
+    expect(resultPl.missing).toBeNull();
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Translation not found for key: NOTHING'));
+  });
+});
+
+function makePack(lang: string, dict: Record<string, string>): Translations {
+  return {
+    [lang]: {
+      dictionary: dict,
+      getPluralForm: null,
+    },
+  };
+}

package/src/elements/editor/utils/resolve-editor-config-translations.ts

@@ -0,0 +1,77 @@
+import type { Translations } from 'ckeditor5';
+
+/**
+ * Resolves translation references in a configuration object.
+ *
+ * The configuration may contain objects with the form `{ $translation: "some.key" }`.
+ * These are replaced with the actual string from the provided translations map.
+ *
+ * The function will walk the provided object recursively, handling arrays and
+ * nested objects. Primitive values are returned as-is. If a translation key is
+ * not present in the map, a warning is logged and `null` is returned for that
+ * value.
+ *
+ * @param translations - An array of CKEditor `Translations` objects. Each translation
+ *                       pack will be searched in order for the requested key, and the
+ *                       first matching value will be returned. This mirrors the format
+ *                       returned by `loadAllEditorTranslations` and simplifies the
+ *                       caller's API.
+ * @param language - Language identifier to look up in the packs. Only this locale
+ *                   will be consulted, ensuring that keys from other languages are
+ *                   ignored even if they appear earlier in the array.
+ * @param obj - Configuration object to process
+ * @returns Processed configuration object with resolved translations.
+ */
+export function resolveEditorConfigTranslations<T>(
+  translations: Translations[],
+  language: string,
+  obj: T,
+): T {
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveEditorConfigTranslations(translations, language, item)) as T;
+  }
+
+  const anyObj = obj as any;
+
+  if (anyObj.$translation && typeof anyObj.$translation === 'string') {
+    const key: string = anyObj.$translation;
+    const value = getTranslationValue(translations, key, language);
+
+    if (value === undefined) {
+      console.warn(`Translation not found for key: ${key}`);
+    }
+
+    return (value !== undefined ? value : null) as T;
+  }
+
+  const result = Object.create(null);
+
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = resolveEditorConfigTranslations(translations, language, value);
+  }
+
+  return result as T;
+}
+
+/**
+ * Look up a translation value inside the provided map or array of CKEditor packs.
+ */
+function getTranslationValue(
+  translations: Translations[],
+  key: string,
+  language: string,
+): string | ReadonlyArray<string> | undefined {
+  for (const pack of translations) {
+    const langData = pack[language];
+
+    if (langData?.dictionary && key in langData.dictionary) {
+      return langData.dictionary[key] as string | ReadonlyArray<string>;
+    }
+  }
+
+  return undefined;
+}

package/src/elements/editor/utils/set-editor-editable-height.test.ts

@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { setEditorEditableHeight } from './set-editor-editable-height';
+
+// Mock CKEditor5 types and interfaces
+const mockWriter = {
+  setStyle: vi.fn(),
+};
+
+const mockRoot = {
+  // Mock root element
+};
+
+const mockViewDocument = {
+  getRoot: vi.fn(() => mockRoot),
+};
+
+const mockView = {
+  change: vi.fn(callback => callback(mockWriter)),
+  document: mockViewDocument,
+};
+
+const mockEditing = {
+  view: mockView,
+};
+
+const mockEditor = {
+  editing: mockEditing,
+};
+
+describe('setEditorEditableHeight', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should set height style on editor root element', () => {
+    const height = 300;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockView.change).toHaveBeenCalledWith(expect.any(Function));
+    expect(mockViewDocument.getRoot).toHaveBeenCalled();
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '300px', mockRoot);
+  });
+
+  it('should handle different height values', () => {
+    const heights = [100, 200, 500, 1000];
+
+    heights.forEach((height) => {
+      vi.clearAllMocks();
+
+      setEditorEditableHeight(mockEditor as any, height);
+
+      expect(mockWriter.setStyle).toHaveBeenCalledWith('height', `${height}px`, mockRoot);
+    });
+  });
+
+  it('should handle zero height', () => {
+    const height = 0;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '0px', mockRoot);
+  });
+
+  it('should handle negative height values', () => {
+    const height = -100;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '-100px', mockRoot);
+  });
+
+  it('should handle decimal height values', () => {
+    const height = 250.5;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '250.5px', mockRoot);
+  });
+
+  it('should call view.change with correct callback', () => {
+    const height = 400;
+
+    setEditorEditableHeight(mockEditor as any, height);
+
+    expect(mockView.change).toHaveBeenCalledTimes(1);
+    expect(mockView.change).toHaveBeenCalledWith(expect.any(Function));
+  });
+
+  it('should work with different editor instances', () => {
+    const anotherMockEditor = {
+      editing: {
+        view: {
+          change: vi.fn(callback => callback(mockWriter)),
+          document: {
+            getRoot: vi.fn(() => mockRoot),
+          },
+        },
+      },
+    };
+
+    const height = 350;
+
+    setEditorEditableHeight(anotherMockEditor as any, height);
+
+    expect(anotherMockEditor.editing.view.change).toHaveBeenCalledWith(expect.any(Function));
+    expect(anotherMockEditor.editing.view.document.getRoot).toHaveBeenCalled();
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '350px', mockRoot);
+  });
+
+  it('should handle editor with null root gracefully', () => {
+    const mockEditorWithNullRoot = {
+      editing: {
+        view: {
+          change: vi.fn(callback => callback(mockWriter)),
+          document: {
+            getRoot: vi.fn(() => null),
+          },
+        },
+      },
+    };
+
+    const height = 200;
+
+    // Should not throw error even with null root
+    expect(() => setEditorEditableHeight(mockEditorWithNullRoot as any, height)).not.toThrow();
+
+    expect(mockWriter.setStyle).toHaveBeenCalledWith('height', '200px', null);
+  });
+});

package/src/elements/editor/utils/set-editor-editable-height.ts

@@ -0,0 +1,15 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Sets the height of the editable area in the CKEditor instance.
+ *
+ * @param instance - The CKEditor instance to modify.
+ * @param height - The height in pixels to set for the editable area.
+ */
+export function setEditorEditableHeight(instance: Editor, height: number): void {
+  const { editing } = instance;
+
+  editing.view.change((writer) => {
+    writer.setStyle('height', `${height}px`, editing.view.document.getRoot()!);
+  });
+}

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

@@ -0,0 +1,45 @@
+import { ClassicEditor, EditorWatchdog } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { unwrapEditorWatchdog, wrapWithWatchdog } from './wrap-with-watchdog';
+
+describe('wrap with watchdog', () => {
+  let element: HTMLElement;
+
+  beforeEach(async () => {
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    element.remove();
+  });
+
+  it('returns editor instance after calling Constructor.create', async () => {
+    const { Constructor } = await wrapWithWatchdog(ClassicEditor);
+    const editor = await Constructor.create(element, {
+      licenseKey: 'GPL',
+    });
+
+    expect(editor).toBeInstanceOf(ClassicEditor);
+
+    await editor.destroy();
+  });
+
+  it('returns instance of watchdog', async () => {
+    const { watchdog } = await wrapWithWatchdog(ClassicEditor);
+
+    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',
+    });
+
+    expect(unwrapEditorWatchdog(editor)).toBeInstanceOf(EditorWatchdog);
+
+    await editor.destroy();
+  });
+});

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

@@ -0,0 +1,51 @@
+import type { Editor, EditorWatchdog } from 'ckeditor5';
+
+const EDITOR_WATCHDOG_SYMBOL = Symbol.for('elixir-editor-watchdog');
+
+/**
+ * Wraps an Editor creator with a watchdog for automatic recovery.
+ *
+ * @param Editor - The Editor creator to wrap.
+ * @returns The Editor creator wrapped with a watchdog.
+ */
+export async function wrapWithWatchdog(Editor: EditorCreator) {
+  const { EditorWatchdog } = await import('ckeditor5');
+  const watchdog = new EditorWatchdog(Editor);
+
+  watchdog.setCreator(async (...args: Parameters<typeof Editor['create']>) => {
+    const editor = await Editor.create(...args);
+
+    (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!;
+      },
+    },
+  };
+}
+
+/**
+ * Unwraps the EditorWatchdog from the editor instance.
+ */
+export function unwrapEditorWatchdog(editor: Editor): EditorWatchdog | null {
+  if (EDITOR_WATCHDOG_SYMBOL in editor) {
+    return (editor as any)[EDITOR_WATCHDOG_SYMBOL] as EditorWatchdog;
+  }
+
+  return null;
+}
+
+/**
+ * Type representing an Editor creator with a create method.
+ */
+export type EditorCreator = {
+  create: (...args: any) => Promise<Editor>;
+};

package/src/elements/ensure-editor-elements-registered.ts

@@ -0,0 +1,24 @@
+import { ContextComponentElement } from './context';
+import { EditableComponentElement } from './editable';
+import { EditorComponentElement } from './editor';
+import { UIPartComponentElement } from './ui-part';
+
+const CUSTOM_ELEMENTS = {
+  'cke5-editor': EditorComponentElement,
+  'cke5-context': ContextComponentElement,
+  'cke5-ui-part': UIPartComponentElement,
+  'cke5-editable': EditableComponentElement,
+};
+
+/**
+ * Registers all available Blazor component hooks.
+ */
+export function ensureEditorElementsRegistered() {
+  for (const [name, CustomElement] of Object.entries(CUSTOM_ELEMENTS)) {
+    if (window.customElements.get(name)) {
+      continue;
+    }
+
+    window.customElements.define(name, CustomElement);
+  }
+}

package/src/elements/index.ts

@@ -0,0 +1,14 @@
+export {
+  ContextComponentElement,
+  type ContextConfig,
+  type ContextCreatorConfig,
+  ContextsRegistry,
+} from './context';
+export { EditableComponentElement } from './editable';
+export {
+  type EditorCloudConfig,
+  EditorComponentElement,
+  type EditorConfig,
+} from './editor';
+export { ensureEditorElementsRegistered } from './ensure-editor-elements-registered';
+export { UIPartComponentElement } from './ui-part';

package/src/elements/ui-part.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorPreset,
+  createUIPartSnapshot,
+  renderTestEditor,
+  renderTestUIPart,
+  waitForDestroyAllEditors,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../shared';
+import { EditorsRegistry } from './editor/editors-registry';
+import { ensureEditorElementsRegistered } from './ensure-editor-elements-registered';
+
+describe('ui-part component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    await waitForDestroyAllEditors();
+    document.body.innerHTML = '';
+  });
+
+  describe('mounting ui part', () => {
+    it('should mount toolbar to the editor after mounting editor', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+
+    it('should mount menubar to the editor after mounting editor', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const menubarElement = (editor.ui.view as any).menuBarView.element;
+
+      const el = renderTestUIPart(createUIPartSnapshot('menubar'));
+
+      await vi.waitFor(() => {
+        expect(el.children.length).toBeGreaterThan(0);
+      });
+
+      expect(el.contains(menubarElement)).toBe(true);
+    });
+
+    it('should mount UI part before editor is created', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+
+    it('should default to first editor ID if data-cke-editor-id is missing', async () => {
+      appendMultirootEditor();
+
+      const editor = await waitForTestEditor();
+      const toolbarElement = editor.ui.view.toolbar?.element;
+
+      // Render UI part without editorId
+      const el = renderTestUIPart({ editorId: undefined } as any);
+
+      await vi.waitFor(() => {
+        expect(el.contains(toolbarElement!)).toBe(true);
+      });
+
+      expect(toolbarElement).toBeTruthy();
+    });
+
+    it('should not mount UI part if element is disconnected before editor is ready', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+      el.remove();
+
+      appendMultirootEditor();
+
+      await waitForTestEditor();
+      await timeout(10);
+
+      expect(el.innerHTML).toBe('');
+    });
+  });
+
+  describe('destroying ui part', () => {
+    beforeEach(async () => {
+      appendMultirootEditor();
+      await waitForTestEditor();
+    });
+
+    it('should clear UI part element on destruction', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      await vi.waitFor(() => {
+        expect(el.children.length).toBeGreaterThan(0);
+      });
+
+      el.remove();
+
+      await vi.waitFor(() => {
+        expect(el.innerHTML).toBe('');
+      });
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should hide element during destruction', async () => {
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      // If we remove immediately, disconnectedCallback should hide it.
+      el.remove();
+
+      // Ensure style is updated synchronously or microtask
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should handle destruction when mounted promise is not resolved yet', async () => {
+      document.body.innerHTML = '';
+      EditorsRegistry.the.reset();
+
+      const el = renderTestUIPart(createUIPartSnapshot('toolbar'));
+
+      el.remove();
+
+      expect(el.innerHTML).toBe('');
+      expect(el.style.display).toBe('none');
+    });
+  });
+
+  function appendMultirootEditor(initialContent: Record<string, string> = {}) {
+    renderTestEditor({
+      preset: createEditorPreset('multiroot'),
+      content: initialContent,
+    });
+  }
+});