ckeditor5-blazor 0.1.0

package/src/elements/context/context.test.ts

@@ -0,0 +1,323 @@
+import { Context, ContextPlugin, ContextWatchdog } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createContextSnapshot,
+  DEFAULT_TEST_CONTEXT_ID,
+  renderTestContext,
+  renderTestEditor,
+  waitForDestroyAllEditors,
+  waitForTestContext,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../../shared';
+import { CustomEditorPluginsRegistry } from '../editor/custom-editor-plugins';
+import { EditorsRegistry } from '../editor/editors-registry';
+import { ensureEditorElementsRegistered } from '../ensure-editor-elements-registered';
+import { ContextsRegistry } from './contexts-registry';
+
+describe('context component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    ensureEditorElementsRegistered();
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    vi.resetAllMocks();
+
+    document.body.innerHTML = '';
+
+    await waitForDestroyAllEditors();
+  });
+
+  describe('mount', () => {
+    it('should save the context instance in the registry with provided id', async () => {
+      renderTestContext({ contextId: 'my-context' });
+
+      const watchdog = await ContextsRegistry.the.waitFor('my-context');
+
+      expect(watchdog).toBeInstanceOf(ContextWatchdog);
+      expect(watchdog.context).toBeInstanceOf(Context);
+    });
+
+    it('should initialize context with empty creator config', async () => {
+      renderTestContext(createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
+        config: {},
+      }));
+
+      expect(await waitForTestContext()).toBeInstanceOf(ContextWatchdog);
+    });
+
+    it('should print console error if `itemError` event is fired', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      renderTestContext();
+
+      const watchdog = await waitForTestContext();
+
+      (watchdog as any)._fire('itemError', 'test-error', { some: 'data' });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Context item error:', null, 'test-error', { some: 'data' });
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should initialize custom plugins passed to context', async () => {
+      class CustomPlugin extends ContextPlugin {
+        static get pluginName() {
+          return 'CustomPlugin';
+        }
+      }
+
+      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+
+      renderTestContext(createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
+        config: {
+          plugins: ['CustomPlugin'],
+        },
+      }));
+
+      const { context } = await waitForTestContext();
+
+      expect(context?.plugins.get('CustomPlugin')).toBeInstanceOf(CustomPlugin);
+    });
+
+    it('registered plugins should support custom translations', async () => {
+      class CustomPlugin extends ContextPlugin {
+        static get pluginName() {
+          return 'CustomPlugin';
+        }
+
+        getHelloTitle() {
+          return this.context.t('HELLO');
+        }
+      }
+
+      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+
+      renderTestContext(createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
+        customTranslations: {
+          en: {
+            HELLO: 'Hello from CustomPlugin',
+          },
+        },
+        config: {
+          plugins: ['CustomPlugin'],
+        },
+      }));
+
+      const { context } = await waitForTestContext();
+      const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
+
+      expect(plugin.getHelloTitle()).toBe('Hello from CustomPlugin');
+    });
+
+    it('should support custom language for context translations', async () => {
+      class CustomPlugin extends ContextPlugin {
+        static get pluginName() {
+          return 'CustomPlugin';
+        }
+
+        getHelloTitle() {
+          return this.context.t('HELLO');
+        }
+      }
+
+      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+
+      renderTestContext(createContextSnapshot(
+        DEFAULT_TEST_CONTEXT_ID,
+        {
+          customTranslations: {
+            en: {
+              HELLO: 'Hello from CustomPlugin',
+            },
+            pl: {
+              HELLO: 'Witaj z CustomPlugin',
+            },
+          },
+          config: {
+            plugins: ['CustomPlugin'],
+          },
+        },
+        {
+          ui: 'pl',
+          content: 'pl',
+        },
+      ));
+
+      const { context } = await waitForTestContext();
+      const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
+
+      expect(plugin.getHelloTitle()).toBe('Witaj z CustomPlugin');
+    });
+
+    it('should support translations references in config', async () => {
+      renderTestContext(createContextSnapshot(
+        DEFAULT_TEST_CONTEXT_ID,
+        {
+          customTranslations: {
+            en: {
+              HELLO: 'Hello from CustomPlugin',
+            },
+            pl: {
+              HELLO: 'Witaj z CustomPlugin',
+            },
+          },
+          config: {
+            customConfig: { $translation: 'HELLO' },
+          },
+        },
+        {
+          ui: 'pl',
+          content: 'pl',
+        },
+      ));
+
+      const { context } = await waitForTestContext();
+      const translation = context?.config.get('customConfig') as string;
+
+      expect(translation).toBe('Witaj z CustomPlugin');
+    });
+  });
+
+  describe('attaching editor', () => {
+    it('should not attach editor to the context (editor has no specified context, context initialized)', async () => {
+      renderTestContext();
+
+      const { context } = await waitForTestContext();
+
+      renderTestEditor();
+
+      await waitForTestEditor();
+
+      expect(context?.editors.first).toBeNull();
+    });
+
+    it('should attach editor to the context (editor has specified context, context initialized)', async () => {
+      renderTestContext();
+
+      const { context } = await waitForTestContext();
+
+      renderTestEditor({
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(context?.editors.first).toEqual(editor);
+    });
+
+    it('should pause editor initialization when context is not yet initialized', async () => {
+      renderTestEditor({
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+
+      await timeout(50);
+
+      renderTestContext();
+
+      const { context } = await waitForTestContext();
+      const editor = await waitForTestEditor();
+
+      expect(context?.editors.first).toEqual(editor);
+    });
+
+    it('should be possible to attach multiple editors to the same context', async () => {
+      renderTestContext();
+
+      const { context } = await waitForTestContext();
+
+      renderTestEditor({
+        editorId: 'editor-1',
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+
+      renderTestEditor({
+        editorId: 'editor-2',
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+
+      const editors = await Promise.all([
+        waitForTestEditor('editor-1'),
+        waitForTestEditor('editor-2'),
+      ]);
+
+      expect(context?.editors.length).toBe(2);
+      expect([...context!.editors]).toEqual(editors);
+    });
+  });
+
+  describe('destroy', () => {
+    it('destroyed editor is removed from the context editors collection', async () => {
+      renderTestContext();
+
+      const { context } = await waitForTestContext();
+
+      const editorEl = renderTestEditor({
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(context?.editors.first).toEqual(editor);
+
+      editorEl.remove();
+
+      await expect.poll(() => context?.editors.first).toBeNull();
+    });
+
+    it('should remove the context instance from the registry on destroy', async () => {
+      const el = renderTestContext({ contextId: 'my-context' });
+
+      const watchdog = await ContextsRegistry.the.waitFor('my-context');
+
+      expect(watchdog).toBeInstanceOf(ContextWatchdog);
+
+      el.remove();
+
+      await expect.poll(() => ContextsRegistry.the.hasItem('my-context')).toBe(false);
+      expect(watchdog.state).toBe('destroyed');
+    });
+
+    it('should hide element during destruction', async () => {
+      const el = renderTestContext();
+
+      el.remove();
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should handle destruction when mounted promise is not resolved yet', async () => {
+      const el = renderTestContext();
+
+      el.remove();
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('destroying context should destroy all attached editors', async () => {
+      const contextEl = renderTestContext();
+
+      await waitForTestContext();
+
+      const editorEl = renderTestEditor({
+        contextId: DEFAULT_TEST_CONTEXT_ID,
+      });
+      const editorId = editorEl.getAttribute('data-cke-editor-id')!;
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.state).toBe('ready');
+
+      contextEl.remove();
+
+      await expect.poll(() => editor.state).toBe('destroyed');
+
+      expect(ContextsRegistry.the.hasItem(DEFAULT_TEST_CONTEXT_ID)).toBe(false);
+      await expect.poll(() => EditorsRegistry.the.hasItem(editorId)).toBe(false);
+    });
+  });
+});

package/src/elements/context/context.ts

@@ -0,0 +1,128 @@
+import type { WaitForInteractiveResult } from '../../shared';
+import type { EditorLanguage } from '../editor';
+import type { ContextConfig } from './typings';
+import type { Context, ContextWatchdog } from 'ckeditor5';
+
+import { isEmptyObject, waitForDOMReady, waitForInteractiveAttribute } from '../../shared';
+import {
+  loadAllEditorTranslations,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+  resolveEditorConfigElementReferences,
+  resolveEditorConfigTranslations,
+} from '../editor/utils';
+import { ContextsRegistry } from './contexts-registry';
+
+/**
+ * The Blazor hook that mounts CKEditor context instances.
+ */
+export class ContextComponentElement extends HTMLElement {
+  /**
+   * The promise that resolves to the context instance.
+   */
+  private contextPromise: Promise<ContextWatchdog<Context>> | null = null;
+
+  /**
+   * Wait result for the interactive attribute.
+   */
+  private interactiveWait?: WaitForInteractiveResult;
+
+  /**
+   * Mounts the context component.
+   */
+  async connectedCallback() {
+    await waitForDOMReady();
+
+    // By default, components do not bootstrap from web components.
+    // They bootstrap only when they receive the data-cke-interactive flag, which the interop sets.
+    // This is a fallback for situations where CKEditor 5 is rendered on a non-interactive page.
+    this.interactiveWait = waitForInteractiveAttribute(this);
+
+    await this.interactiveWait.promise;
+    await this.initializeContext();
+  }
+
+  /**
+   * Initializes the context component.
+   */
+  private async initializeContext(): Promise<void> {
+    const contextId = this.getAttribute('data-cke-context-id')!;
+    const language = JSON.parse(this.getAttribute('data-cke-language')!) as EditorLanguage;
+    const contextConfig = JSON.parse(this.getAttribute('data-cke-context')!) as ContextConfig;
+
+    const { customTranslations, watchdogConfig, config: { plugins, ...config } } = contextConfig;
+    const { loadedPlugins, hasPremium } = await loadEditorPlugins(plugins ?? []);
+
+    // Mix custom translations with loaded translations.
+    const loadedTranslations = await loadAllEditorTranslations(language, hasPremium);
+    const mixedTranslations = [
+      ...loadedTranslations,
+      normalizeCustomTranslations(customTranslations || {}),
+    ]
+      .filter(translations => !isEmptyObject(translations));
+
+    // Initialize context with watchdog.
+    this.contextPromise = (async () => {
+      const { ContextWatchdog, Context } = await import('ckeditor5');
+
+      const instance = new ContextWatchdog(Context, {
+        crashNumberLimit: 10,
+        ...watchdogConfig,
+      });
+
+      // Construct parsed config. First resolve DOM element references in the provided configuration.
+      let resolvedConfig = resolveEditorConfigElementReferences(config);
+
+      // Then resolve translation references in the provided configuration, using the mixed translations.
+      resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+
+      await instance.create({
+        ...resolvedConfig,
+        language,
+        plugins: loadedPlugins,
+        ...mixedTranslations.length && {
+          translations: mixedTranslations,
+        },
+      });
+
+      instance.on('itemError', (...args) => {
+        console.error('Context item error:', ...args);
+      });
+
+      return instance;
+    })();
+
+    const context = await this.contextPromise;
+
+    if (this.isConnected) {
+      ContextsRegistry.the.register(contextId, context);
+    }
+  }
+
+  /**
+   * Destroys the context component. Unmounts root from the editor.
+   */
+  async disconnectedCallback() {
+    // Disconnect the observer if present.
+    this.interactiveWait?.disconnect();
+
+    const contextId = this.getAttribute('data-cke-context-id');
+
+    // 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.
+    try {
+      const context = await this.contextPromise;
+
+      await context?.destroy();
+    }
+    finally {
+      this.contextPromise = null;
+
+      if (contextId && ContextsRegistry.the.hasItem(contextId)) {
+        ContextsRegistry.the.unregister(contextId);
+      }
+    }
+  }
+}

package/src/elements/context/contexts-registry.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+
+import { AsyncRegistry } from '../../shared/async-registry';
+import { ContextsRegistry } from './contexts-registry';
+
+describe('contexts registry', () => {
+  it('should be singleton of async registry', () => {
+    expect(ContextsRegistry.the).toBeInstanceOf(AsyncRegistry);
+  });
+});

package/src/elements/context/contexts-registry.ts

@@ -0,0 +1,10 @@
+import type { Context, ContextWatchdog } from 'ckeditor5';
+
+import { AsyncRegistry } from '../../shared';
+
+/**
+ * It provides a way to register contexts and execute callbacks on them when they are available.
+ */
+export class ContextsRegistry extends AsyncRegistry<ContextWatchdog<Context>> {
+  static readonly the = new ContextsRegistry();
+}

package/src/elements/context/index.ts

@@ -0,0 +1,3 @@
+export * from './context';
+export * from './contexts-registry';
+export * from './typings';

package/src/elements/context/typings.ts

@@ -0,0 +1,38 @@
+import type { EditorCustomTranslationsDictionary, EditorPlugin } from '../editor';
+import type { WatchdogConfig } from 'ckeditor5';
+
+/**
+ * Configuration object for CKEditor5 context instance.
+ */
+export type ContextConfig = {
+  /**
+   * Optional custom translations for the editor.
+   * This allows for localization of the editor interface.
+   */
+  customTranslations?: EditorCustomTranslationsDictionary | null;
+
+  /**
+   * Watchdog configuration for the context.
+   */
+  watchdogConfig: WatchdogConfig | null;
+
+  /**
+   * Configuration options for the context instance.
+   */
+  config: ContextCreatorConfig;
+};
+
+/**
+ * Configuration options for the context instance.
+ */
+export type ContextCreatorConfig = {
+  /**
+   * Array of plugin identifiers to be loaded by the editor.
+   */
+  plugins?: EditorPlugin[];
+
+  /**
+   * Other configuration options are flexible and can be any key-value pairs.
+   */
+  [key: string]: any;
+};