ckeditor5-blazor 0.1.0

package/src/elements/editor/editor.ts

@@ -0,0 +1,330 @@
+import type { WaitForInteractiveResult } from '../../shared';
+import type { EditorId, EditorLanguage, EditorPreset } from './typings';
+import type { EditorCreator } from './utils';
+import type { Editor } from 'ckeditor5';
+
+import {
+  isEmptyObject,
+  waitFor,
+  waitForDOMReady,
+  waitForInteractiveAttribute,
+} from '../../shared';
+import { ContextsRegistry } from '../context';
+import { EditorsRegistry } from './editors-registry';
+import {
+  createDispatchEditorRootsChangeEventPlugin,
+  createSyncEditorWithInputPlugin,
+} from './plugins';
+import {
+  createEditorInContext,
+  isSingleRootEditor,
+  loadAllEditorTranslations,
+  loadEditorConstructor,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+  queryEditablesElements,
+  queryEditablesSnapshotContent,
+  resolveEditorConfigElementReferences,
+  resolveEditorConfigTranslations,
+  setEditorEditableHeight,
+  unwrapEditorContext,
+  unwrapEditorWatchdog,
+  wrapWithWatchdog,
+} from './utils';
+
+/**
+ * The Blazor hook that manages the lifecycle of CKEditor5 instances.
+ */
+export class EditorComponentElement extends HTMLElement {
+  /**
+   * The promise that resolves to the editor instance.
+   */
+  private editorPromise: Promise<Editor> | null = null;
+
+  /**
+   * Wait result for the interactive attribute.
+   */
+  private interactiveWait?: WaitForInteractiveResult;
+
+  /**
+   * Mounts the editor component.
+   */
+  async connectedCallback(): Promise<void> {
+    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);
+
+    // Let's start preloading the editor constructor. We are still waiting for the interactive attribute, but
+    // at least we will have the constructor ready when it arrives. It makes no difference which editor type is being
+    // preloaded as they are loaded from the same package, so let's just preload the classic editor constructor.
+    void loadEditorConstructor('classic');
+
+    await this.interactiveWait.promise;
+    await this.initializeEditor();
+  }
+
+  /**
+   * Initializes the editor instance.
+   */
+  private async initializeEditor(): Promise<void> {
+    const editorId = this.getAttribute('data-cke-editor-id')!;
+
+    EditorsRegistry.the.resetErrors(editorId);
+
+    try {
+      this.style.display = 'block';
+      this.editorPromise = this.createEditor();
+
+      const editor = await this.editorPromise;
+
+      // Do not even try to broadcast about the registration of the editor
+      // if hook was immediately destroyed.
+      /* v8 ignore else -- @preserve */
+      if (this.isConnected) {
+        EditorsRegistry.the.register(editorId, editor);
+
+        editor.once('destroy', () => {
+          if (EditorsRegistry.the.hasItem(editorId)) {
+            EditorsRegistry.the.unregister(editorId);
+          }
+        });
+      }
+    }
+    catch (error: any) {
+      /* v8 ignore start -- @preserve */
+      console.error(`Error initializing CKEditor5 instance with ID "${editorId}":`, error);
+      this.editorPromise = null;
+      EditorsRegistry.the.error(editorId, error);
+      /* v8 ignore end */
+    }
+  }
+
+  /**
+   * Destroys the editor instance when the component is destroyed.
+   * This is important to prevent memory leaks and ensure that the editor is properly cleaned up.
+   */
+  async disconnectedCallback() {
+    // Disconnect the observer if present.
+    this.interactiveWait?.disconnect();
+
+    // 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 editor = await this.editorPromise;
+
+      /* v8 ignore next -- @preserve */
+      if (!editor) {
+        return;
+      }
+
+      const editorContext = unwrapEditorContext(editor);
+      const watchdog = unwrapEditorWatchdog(editor);
+
+      if (editorContext) {
+        // If context is present, make sure it's not in unmounting phase, as it'll kill the editors.
+        // If it's being destroyed, don't do anything, as the context will take care of it.
+        if (editorContext.state !== 'unavailable') {
+          await editorContext.context.remove(editorContext.editorContextId);
+        }
+      }
+      else if (watchdog) {
+        await watchdog.destroy();
+      }
+      else {
+        await editor.destroy();
+      }
+    }
+    finally {
+      this.editorPromise = null;
+    }
+  }
+
+  /**
+   * Creates the CKEditor instance.
+   */
+  private async createEditor() {
+    const editorId = this.getAttribute('data-cke-editor-id')!;
+    const preset = JSON.parse(this.getAttribute('data-cke-preset')!) as EditorPreset;
+    const contextId = this.getAttribute('data-cke-context-id');
+    const editableHeight = this.getAttribute('data-cke-editable-height') ? Number.parseInt(this.getAttribute('data-cke-editable-height')!, 10) : null;
+    const saveDebounceMs = Number.parseInt(this.getAttribute('data-cke-save-debounce-ms')!, 10);
+    const language = JSON.parse(this.getAttribute('data-cke-language')!) as EditorLanguage;
+    const watchdog = this.hasAttribute('data-cke-watchdog');
+    const content = JSON.parse(this.getAttribute('data-cke-content')!) as Record<string, string>;
+
+    const {
+      customTranslations,
+      editorType,
+      licenseKey,
+      config: { plugins, ...config },
+    } = preset;
+
+    // Wrap editor creator with watchdog if needed.
+    let Constructor: EditorCreator = await loadEditorConstructor(editorType);
+    const context = await (
+      contextId
+        ? ContextsRegistry.the.waitFor(contextId)
+        : null
+    );
+
+    // Do not use editor specific watchdog if context is attached, as the context is by default protected.
+    if (watchdog && !context) {
+      const wrapped = await wrapWithWatchdog(Constructor);
+
+      ({ Constructor } = wrapped);
+      wrapped.watchdog.on('restart', () => {
+        const newInstance = wrapped.watchdog.editor!;
+
+        this.editorPromise = Promise.resolve(newInstance);
+
+        EditorsRegistry.the.register(editorId, newInstance);
+      });
+    }
+
+    const { loadedPlugins, hasPremium } = await loadEditorPlugins(plugins);
+
+    loadedPlugins.push(
+      await createDispatchEditorRootsChangeEventPlugin({
+        saveDebounceMs,
+        editorId,
+        targetElement: this,
+      }),
+    );
+
+    if (isSingleRootEditor(editorType)) {
+      loadedPlugins.push(
+        await createSyncEditorWithInputPlugin(saveDebounceMs),
+      );
+    }
+
+    // Mix custom translations with loaded translations.
+    const loadedTranslations = await loadAllEditorTranslations(language, hasPremium);
+    const mixedTranslations = [
+      ...loadedTranslations,
+      normalizeCustomTranslations(customTranslations || {}),
+    ]
+      .filter(translations => !isEmptyObject(translations));
+
+    // Let's query all elements, and create basic configuration.
+    let initialData: string | Record<string, string> = {
+      ...content,
+      ...queryEditablesSnapshotContent(editorId),
+    };
+
+    if (isSingleRootEditor(editorType)) {
+      initialData = initialData['main'] || '';
+    }
+
+    // Depending of the editor type, and parent lookup for nearest context or initialize it without it.
+    const editor = await (async () => {
+      let sourceElementOrData: HTMLElement | Record<string, HTMLElement> = queryEditablesElements(editorId);
+
+      // Handle special case when user specified `initialData` of several root elements, but editable components
+      // are not yet present in the DOM. In other words - editor is initialized before attaching root elements.
+      if (!sourceElementOrData['main']) {
+        const requiredRoots = (
+          isSingleRootEditor(editorType)
+            ? ['main']
+            : Object.keys(initialData as Record<string, string>)
+        );
+
+        if (!checkIfAllRootsArePresent(sourceElementOrData, requiredRoots)) {
+          sourceElementOrData = await waitForAllRootsToBePresent(editorId, requiredRoots);
+          initialData = {
+            ...content,
+            ...queryEditablesSnapshotContent(editorId),
+          };
+        }
+      }
+
+      // If single root editor, unwrap the element from the object.
+      if (isSingleRootEditor(editorType) && 'main' in sourceElementOrData) {
+        sourceElementOrData = sourceElementOrData['main'];
+      }
+
+      // 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);
+
+      // Construct parsed config.
+      const parsedConfig = {
+        ...resolvedConfig,
+        initialData,
+        licenseKey,
+        plugins: loadedPlugins,
+        language,
+        ...mixedTranslations.length && {
+          translations: mixedTranslations,
+        },
+      };
+
+      if (!context || !(sourceElementOrData instanceof HTMLElement)) {
+        return Constructor.create(sourceElementOrData as any, parsedConfig);
+      }
+
+      const result = await createEditorInContext({
+        context,
+        element: sourceElementOrData,
+        creator: Constructor,
+        config: parsedConfig,
+      });
+
+      return result.editor;
+    })();
+
+    if (isSingleRootEditor(editorType) && editableHeight) {
+      setEditorEditableHeight(editor, editableHeight);
+    }
+
+    return editor;
+  };
+}
+
+/**
+ * Checks if all required root elements are present in the elements object.
+ *
+ * @param elements The elements object mapping root IDs to HTMLElements.
+ * @param requiredRoots The list of required root IDs.
+ * @returns True if all required roots are present, false otherwise.
+ */
+function checkIfAllRootsArePresent(elements: Record<string, HTMLElement>, requiredRoots: string[]): boolean {
+  return requiredRoots.every(rootId => elements[rootId]);
+}
+
+/**
+ * Waits for all required root elements to be present in the DOM.
+ *
+ * @param editorId The editor's ID.
+ * @param requiredRoots The list of required root IDs.
+ * @returns A promise that resolves to the record of root elements.
+ */
+async function waitForAllRootsToBePresent(
+  editorId: EditorId,
+  requiredRoots: string[],
+): Promise<Record<string, HTMLElement>> {
+  return waitFor(
+    () => {
+      const elements = queryEditablesElements(editorId) as unknown as Record<string, HTMLElement>;
+
+      if (!checkIfAllRootsArePresent(elements, requiredRoots)) {
+        throw new Error(
+          'It looks like not all required root elements are present yet.\n'
+          + '* If you want to wait for them, ensure they are registered before editor initialization.\n'
+          + '* If you want lazy initialize roots, consider removing root values from the `initialData` config '
+          + 'and assign initial data in editable components.\n'
+          + `Missing roots: ${requiredRoots.filter(rootId => !elements[rootId]).join(', ')}.`,
+        );
+      }
+
+      return elements;
+    },
+    { timeOutAfter: 2000, retryAfter: 100 },
+  );
+}

package/src/elements/editor/editors-registry.test.ts

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

package/src/elements/editor/editors-registry.ts

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

package/src/elements/editor/index.ts

@@ -0,0 +1,2 @@
+export * from './editor';
+export * from './typings';

package/src/elements/editor/plugins/dispatch-editor-roots-change-event.ts

@@ -0,0 +1,76 @@
+import type { Editor, PluginConstructor } from 'ckeditor5';
+
+import { debounce } from '../../../shared';
+import { getEditorRootsValues } from '../utils';
+
+/**
+ * Creates a DispatchEditorRootsChangeEvent plugin class.
+ */
+export async function createDispatchEditorRootsChangeEventPlugin(
+  {
+    saveDebounceMs,
+    editorId,
+    targetElement,
+  }: {
+    saveDebounceMs: number;
+    editorId: string;
+    targetElement: HTMLElement;
+  },
+): Promise<PluginConstructor> {
+  const { Plugin } = await import('ckeditor5');
+
+  return class DispatchEditorRootsChangeEvent extends Plugin {
+    /**
+     * The name of the plugin.
+     */
+    static get pluginName() {
+      return 'DispatchEditorRootsChangeEvent' as const;
+    }
+
+    /**
+     * Initializes the plugin.
+     */
+    public afterInit(): void {
+      const { editor } = this;
+      const sync = debounce(saveDebounceMs, this.dispatch);
+
+      editor.model.document.on('change:data', sync);
+      editor.once('ready', this.dispatch);
+    }
+
+    /**
+     * Dispatches a custom event with all roots data.
+     */
+    private dispatch = (): void => {
+      const { editor } = this;
+
+      targetElement.dispatchEvent(
+        new CKEditor5ChangeDataEvent({
+          editorId,
+          editor,
+          roots: getEditorRootsValues(editor),
+        }),
+      );
+    };
+  };
+}
+
+/**
+ * A custom event dispatched by the DispatchEditorRootsChangeEvent plugin, containing all editor roots data.
+ */
+export class CKEditor5ChangeDataEvent extends CustomEvent<CKEditor5ChangeDataEventPayload> {
+  static readonly EVENT_NAME = 'ckeditor5:change:data';
+
+  constructor(detail: CKEditor5ChangeDataEventPayload) {
+    super(CKEditor5ChangeDataEvent.EVENT_NAME, {
+      detail,
+      bubbles: true,
+    });
+  }
+}
+
+type CKEditor5ChangeDataEventPayload = {
+  editorId: string;
+  editor: Editor;
+  roots: Record<string, string>;
+};

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

@@ -0,0 +1,2 @@
+export * from './dispatch-editor-roots-change-event';
+export * from './sync-editor-with-input';

package/src/elements/editor/plugins/sync-editor-with-input.ts

@@ -0,0 +1,79 @@
+import type { ClassicEditor, PluginConstructor } from 'ckeditor5';
+
+import { debounce } from '../../../shared';
+
+/**
+ * Creates a SyncEditorWithInput plugin class.
+ */
+export async function createSyncEditorWithInputPlugin(saveDebounceMs: number): Promise<PluginConstructor> {
+  const { Plugin } = await import('ckeditor5');
+
+  return class SyncEditorWithInput extends Plugin {
+    /**
+     * The input element to synchronize with.
+     */
+    private input: HTMLInputElement | null = null;
+
+    /**
+     * The form element reference for cleanup.
+     */
+    private form: HTMLFormElement | null = null;
+
+    /**
+     * The name of the plugin.
+     */
+    static get pluginName() {
+      return 'SyncEditorWithInput' as const;
+    }
+
+    /**
+     * Initializes the plugin.
+     */
+    public afterInit(): void {
+      const { editor } = this;
+      const editorElement = (editor as ClassicEditor).sourceElement as HTMLElement;
+
+      // Try to find the associated input field.
+      const editorId = editorElement.id.replace(/_editor$/, '');
+
+      this.input = document.getElementById(`${editorId}_input`) as HTMLInputElement | null;
+
+      if (!this.input) {
+        return;
+      }
+
+      // Setup handlers.
+      editor.model.document.on('change:data', debounce(saveDebounceMs, () => this.sync()));
+      editor.once('ready', this.sync);
+
+      // Setup form integration.
+      this.form = this.input.closest('form');
+      this.form?.addEventListener('submit', this.sync);
+    }
+
+    /**
+     * Synchronizes the editor's content with the input field.
+     */
+    private sync = (): void => {
+      /* v8 ignore else -- @preserve */
+      if (this.input) {
+        const newValue = this.editor.getData();
+
+        this.input.value = newValue;
+        this.input.dispatchEvent(new Event('input', { bubbles: true }));
+      }
+    };
+
+    /**
+     * Destroys the plugin.
+     */
+    public override destroy(): void {
+      if (this.form) {
+        this.form.removeEventListener('submit', this.sync);
+      }
+
+      this.input = null;
+      this.form = null;
+    }
+  };
+}

package/src/elements/editor/typings.ts

@@ -0,0 +1,114 @@
+/**
+ * Represents a unique identifier for a CKEditor5 editor instance.
+ * This is typically the ID of the HTML element that the editor is attached to.
+ */
+export type EditorId = string;
+
+/**
+ * Defines editor type supported by CKEditor5.
+ */
+export type EditorType = 'inline' | 'classic' | 'balloon' | 'decoupled' | 'multiroot';
+
+/**
+ * Represents a CKEditor5 plugin as a string identifier.
+ */
+export type EditorPlugin = string;
+
+/**
+ * Configuration object for CKEditor5 editor instance.
+ */
+export type EditorConfig = {
+  /**
+   * 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;
+};
+
+/**
+ * Configuration object for CKEditor5 cloud services.
+ */
+export type EditorCloudConfig = {
+  /**
+   * The version of CKEditor5 being used.
+   */
+  editorVersion: string;
+
+  /**
+   * Indicates whether the CKEditor5 instance is a premium version.
+   */
+  premium: boolean;
+
+  /**
+   * List of language codes for translations available in the CKEditor5 instance.
+   */
+  translations: string[];
+
+  /**
+   * Configuration for CKEditor5's upload adapter.
+   */
+  ckbox: {
+    version: string;
+    theme: string | null;
+  } | null;
+};
+
+/**
+ * Configuration object for the CKEditor5 hook.
+ */
+export type EditorPreset = {
+  /**
+   * The configuration of the cloud.
+   */
+  cloud: EditorCloudConfig | null;
+
+  /**
+   * The type of CKEditor5 editor to use.
+   * Must be one of the predefined types: 'inline', 'classic', 'balloon', 'decoupled', or 'multiroot'.
+   */
+  editorType: EditorType;
+
+  /**
+   * The configuration object for the CKEditor5 editor.
+   * This should match the configuration expected by CKEditor5.
+   */
+  config: EditorConfig;
+
+  /**
+   * The license key for CKEditor5.
+   * This is required for using CKEditor5 with a valid license.
+   */
+  licenseKey: string;
+
+  /**
+   * Optional watchdog configuration for error recovery.
+   */
+  watchdogConfig?: Record<string, any> | null;
+
+  /**
+   * Optional custom translations for the editor.
+   * This allows for localization of the editor interface.
+   */
+  customTranslations?: EditorCustomTranslationsDictionary | null;
+};
+
+/**
+ * Represents the language settings for the CKEditor5 editor.
+ */
+export type EditorLanguage = {
+  ui: string;
+  content: string;
+};
+
+/**
+ * Represents custom translations for the editor.
+ */
+export type EditorCustomTranslationsDictionary = {
+  [language: string]: {
+    [key: string]: string | ReadonlyArray<string>;
+  };
+};