ckeditor5-symfony 1.0.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ckeditor5-symfony",
+  "version": "1.0.0",
+  "description": "CKEditor 5 integration for Symfony",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prepare": "pnpm run build",
+    "build": "pnpm run clean && vite build && node ./scripts/check-dist-imports.mjs",
+    "watch": "vite build --watch",
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit --pretty",
+    "test": "vitest --coverage",
+    "test:watch": "vitest --watch --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "ckeditor5": "^45.2.2",
+    "ckeditor5-premium-features": "^45.2.1",
+    "happy-dom": "^20.0.1",
+    "typescript": "^5.5.4",
+    "vite": "^7.1.11",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.3"
+  }
+}

package/src/ckeditor5-symfony-error.ts

@@ -0,0 +1,9 @@
+/**
+ * Custom error class for CKEditor5 Symfony-related errors.
+ */
+export class CKEditor5SymfonyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CKEditor5SymfonyError';
+  }
+}

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

@@ -0,0 +1,291 @@
+import { Context, ContextPlugin, ContextWatchdog } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createContextSnapshot,
+  DEFAULT_TEST_CONTEXT_ID,
+  renderTestContext,
+  renderTestEditor,
+  waitForTestContext,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import { timeout } from '../../shared';
+import { CustomEditorPluginsRegistry } from '../editor/custom-editor-plugins';
+import { EditorsRegistry } from '../editor/editors-registry';
+import { registerCustomElements } from '../register-custom-elements';
+import { ContextsRegistry } from './contexts-registry';
+
+describe('context component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    registerCustomElements();
+  });
+
+  afterEach(() => {
+    CustomEditorPluginsRegistry.the.unregisterAll();
+    EditorsRegistry.the.reset();
+    ContextsRegistry.the.reset();
+  });
+
+  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');
+    });
+  });
+
+  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,99 @@
+import type { Context, ContextWatchdog } from 'ckeditor5';
+
+import type { EditorLanguage } from '../editor';
+import type { ContextConfig } from './typings';
+
+import { isEmptyObject, waitForDOMReady } from '../../shared';
+import {
+  loadAllEditorTranslations,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+} from '../editor/utils';
+import { ContextsRegistry } from './contexts-registry';
+
+/**
+ * The Symfony 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;
+
+  /**
+   * Mounts the context component.
+   */
+  async connectedCallback() {
+    await waitForDOMReady();
+
+    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,
+      });
+
+      await instance.create({
+        ...config,
+        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() {
+    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,39 @@
+import type { WatchdogConfig } from 'ckeditor5';
+
+import type { EditorCustomTranslationsDictionary, EditorPlugin } from '../editor';
+
+/**
+ * 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;
+};