ckeditor5-symfony 1.0.0

package/src/elements/editor/editor.ts

@@ -0,0 +1,279 @@
+import type { Editor } from 'ckeditor5';
+
+import type { EditorId, EditorLanguage, EditorPreset } from './typings';
+import type { EditorCreator } from './utils';
+
+import { isEmptyObject, waitFor, waitForDOMReady } from '../../shared';
+import { ContextsRegistry } from '../context';
+import { EditorsRegistry } from './editors-registry';
+import { createSyncEditorWithInputPlugin } from './plugins';
+import {
+  createEditorInContext,
+  isSingleRootEditor,
+  loadAllEditorTranslations,
+  loadEditorConstructor,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+  queryEditablesElements,
+  queryEditablesSnapshotContent,
+  resolveEditorConfigElementReferences,
+  setEditorEditableHeight,
+  unwrapEditorContext,
+  unwrapEditorWatchdog,
+  wrapWithWatchdog,
+} from './utils';
+
+/**
+ * The Symfony 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;
+
+  /**
+   * Mounts the editor component.
+   */
+  async connectedCallback(): Promise<void> {
+    await waitForDOMReady();
+
+    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.
+      if (this.isConnected) {
+        EditorsRegistry.the.register(editorId, editor);
+
+        editor.once('destroy', () => {
+          if (EditorsRegistry.the.hasItem(editorId)) {
+            EditorsRegistry.the.unregister(editorId);
+          }
+        });
+      }
+      /* v8 ignore next 6 */
+    }
+    catch (error: any) {
+      console.error(`Error initializing CKEditor5 instance with ID "${editorId}":`, error);
+      this.editorPromise = null;
+      EditorsRegistry.the.error(editorId, error);
+    }
+  }
+
+  /**
+   * 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() {
+    // 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 3 */
+      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);
+
+    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.
+      const parsedConfig = {
+        ...resolveEditorConfigElementReferences(config),
+        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/index.ts

@@ -0,0 +1 @@
+export * from './sync-editor-with-input';

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

@@ -0,0 +1,78 @@
+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 => {
+      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>;
+  };
+};

package/src/elements/editor/utils/create-editor-in-context.ts

@@ -0,0 +1,90 @@
+import type { Context, ContextWatchdog, Editor, EditorConfig } from 'ckeditor5';
+
+import type { EditorCreator } from './wrap-with-watchdog';
+
+import { uid } from '../../../shared';
+
+/**
+ * Symbol used to store the context watchdog on the editor instance.
+ * Internal use only.
+ */
+const CONTEXT_EDITOR_WATCHDOG_SYMBOL = Symbol.for('context-editor-watchdog');
+
+/**
+ * Creates a CKEditor 5 editor instance within a given context watchdog.
+ *
+ * @param params Parameters for editor creation.
+ * @param params.element The DOM element or data for the editor.
+ * @param params.context The context watchdog instance.
+ * @param params.creator The editor creator utility.
+ * @param params.config The editor configuration object.
+ * @returns The created editor instance.
+ */
+export async function createEditorInContext({ element, context, creator, config }: Attrs) {
+  const editorContextId = uid();
+
+  await context.add({
+    creator: (_element, _config) => creator.create(_element, _config),
+    id: editorContextId,
+    sourceElementOrData: element,
+    type: 'editor',
+    config,
+  });
+
+  const editor = context.getItem(editorContextId) as Editor;
+  const contextDescriptor: EditorContextDescriptor = {
+    state: 'available',
+    editorContextId,
+    context,
+  };
+
+  (editor as any)[CONTEXT_EDITOR_WATCHDOG_SYMBOL] = contextDescriptor;
+
+  // Destroying of context is async. There can be situation when the destroy of the context
+  // and the destroy of the editor is called in parallel. It often happens during unmounting of
+  // phoenix hooks. Let's make sure that descriptor informs other components, that context is being
+  // destroyed.
+  const originalDestroy = context.destroy.bind(context);
+  context.destroy = async () => {
+    contextDescriptor.state = 'unavailable';
+    return originalDestroy();
+  };
+
+  return {
+    ...contextDescriptor,
+    editor,
+  };
+}
+
+/**
+ * Retrieves the context watchdog from an editor instance, if available.
+ *
+ * @param editor The editor instance.
+ * @returns The context watchdog or null if not found.
+ */
+export function unwrapEditorContext(editor: Editor): EditorContextDescriptor | null {
+  if (CONTEXT_EDITOR_WATCHDOG_SYMBOL in editor) {
+    return (editor as any)[CONTEXT_EDITOR_WATCHDOG_SYMBOL];
+  }
+
+  return null;
+}
+
+/**
+ * Parameters for creating an editor in a context.
+ */
+type Attrs = {
+  context: ContextWatchdog<Context>;
+  creator: EditorCreator;
+  element: HTMLElement;
+  config: EditorConfig;
+};
+
+/**
+ * Descriptor for an editor context.
+ */
+type EditorContextDescriptor = {
+  state: 'available' | 'unavailable';
+  editorContextId: string;
+  context: ContextWatchdog<Context>;
+};

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

@@ -0,0 +1,11 @@
+export * from './create-editor-in-context';
+export * from './is-single-root-editor';
+export * from './load-editor-constructor';
+export * from './load-editor-plugins';
+export * from './load-editor-translations';
+export * from './normalize-custom-translations';
+export * from './query-all-editor-ids';
+export * from './query-editor-editables';
+export * from './resolve-editor-config-elements-references';
+export * from './set-editor-editable-height';
+export * from './wrap-with-watchdog';

package/src/elements/editor/utils/is-single-root-editor.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import type { EditorType } from '../typings';
+
+import { isSingleRootEditor } from './is-single-root-editor';
+
+describe('isSingleRootEditor', () => {
+  it('should return true for inline editor', () => {
+    expect(isSingleRootEditor('inline')).toBe(true);
+  });
+
+  it('should return true for classic editor', () => {
+    expect(isSingleRootEditor('classic')).toBe(true);
+  });
+
+  it('should return true for balloon editor', () => {
+    expect(isSingleRootEditor('balloon')).toBe(true);
+  });
+
+  it('should return false for decoupled editor', () => {
+    expect(isSingleRootEditor('decoupled')).toBe(true);
+  });
+
+  it('should return false for multiroot editor', () => {
+    expect(isSingleRootEditor('multiroot')).toBe(false);
+  });
+
+  it('should handle all valid editor types', () => {
+    const singleEditingTypes: EditorType[] = ['inline', 'classic', 'balloon', 'decoupled'];
+    const multiEditingTypes: EditorType[] = ['multiroot'];
+
+    singleEditingTypes.forEach((type) => {
+      expect(isSingleRootEditor(type)).toBe(true);
+    });
+
+    multiEditingTypes.forEach((type) => {
+      expect(isSingleRootEditor(type)).toBe(false);
+    });
+  });
+});

package/src/elements/editor/utils/is-single-root-editor.ts

@@ -0,0 +1,11 @@
+import type { EditorType } from '../typings';
+
+/**
+ * Checks if the given editor type is one of the single editing-like editors.
+ *
+ * @param editorType - The type of the editor to check.
+ * @returns `true` if the editor type is 'inline', 'classic', or 'balloon', otherwise `false`.
+ */
+export function isSingleRootEditor(editorType: EditorType): boolean {
+  return ['inline', 'classic', 'balloon', 'decoupled'].includes(editorType);
+}