ckeditor5-livewire 0.0.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ckeditor5-livewire",
+  "version": "0.0.1",
+  "description": "CKEditor 5 integration for Laravel Livewire",
+  "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/hooks/context/context.test.ts

@@ -0,0 +1,394 @@
+import { Context, ContextPlugin, ContextWatchdog } from 'ckeditor5';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createContextHtmlElement,
+  createContextSnapshot,
+  createEditorHtmlElement,
+  createEditorSnapshot,
+  DEFAULT_TEST_CONTEXT_ID,
+  LivewireStub,
+  waitForTestContext,
+  waitForTestEditor,
+} from '~/test-utils';
+
+import type { Snapshot as EditorSnapshot } from '../editor';
+
+import { timeout } from '../../shared';
+import { EditorComponentHook } from '../editor';
+import { CustomEditorPluginsRegistry } from '../editor/custom-editor-plugins';
+import { EditorsRegistry } from '../editor/editors-registry';
+import { registerLivewireComponentHook } from '../hook';
+import { ContextComponentHook } from './context';
+import { ContextsRegistry } from './contexts-registry';
+
+describe('context component', () => {
+  let livewireStub: LivewireStub;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    livewireStub = window.Livewire = new LivewireStub();
+
+    registerLivewireComponentHook('ckeditor5', EditorComponentHook);
+    registerLivewireComponentHook('ckeditor5-context', ContextComponentHook);
+  });
+
+  afterEach(async () => {
+    CustomEditorPluginsRegistry.the.unregisterAll();
+    await livewireStub.$internal.destroy();
+  });
+
+  describe('mount', () => {
+    it('should save the context instance in the registry with provided id', async () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot('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 () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: 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(() => {});
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      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);
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: 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);
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: 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);
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: 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 () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      const { context } = await waitForTestContext();
+
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        ephemeral: createEditorSnapshot(),
+      });
+
+      await waitForTestEditor();
+
+      expect(context?.editors.first).toBeNull();
+    });
+
+    it('should attach editor to the context (editor has specified context, context initialized)', async () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      const { context } = await waitForTestContext();
+
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          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 () => {
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          contextId: DEFAULT_TEST_CONTEXT_ID,
+        },
+      });
+
+      await timeout(50);
+
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      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 () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      const { context } = await waitForTestContext();
+
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement({ id: 'editor-1' }),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          editorId: 'editor-1',
+          contextId: DEFAULT_TEST_CONTEXT_ID,
+        },
+      });
+
+      livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement({ id: 'editor-2' }),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          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 () => {
+      livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      const { context } = await waitForTestContext();
+
+      const { id: editorId } = livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          contextId: DEFAULT_TEST_CONTEXT_ID,
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(context?.editors.first).toEqual(editor);
+
+      await livewireStub.$internal.unmountComponent(editorId);
+
+      expect(context?.editors.first).toBeNull();
+    });
+
+    it('should remove the context instance from the registry on destroy', async () => {
+      const { id } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot('my-context'),
+      });
+
+      const watchdog = await ContextsRegistry.the.waitFor('my-context');
+
+      expect(watchdog).toBeInstanceOf(ContextWatchdog);
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(ContextsRegistry.the.hasItem('my-context')).toBe(false);
+      expect(watchdog.state).toBe('destroyed');
+    });
+
+    it('should hide element during destruction', async () => {
+      const { id, el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('should handle destruction when mounted promise is not resolved yet', async () => {
+      const { id, el } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      await livewireStub.$internal.unmountComponent(id);
+
+      expect(el.style.display).toBe('none');
+    });
+
+    it('destroying context should destroy all attached editors', async () => {
+      const { id: contextId } = livewireStub.$internal.appendComponentToDOM({
+        name: 'ckeditor5-context',
+        el: createContextHtmlElement(),
+        ephemeral: createContextSnapshot(),
+      });
+
+      await waitForTestContext();
+
+      const { id: editorId } = livewireStub.$internal.appendComponentToDOM<EditorSnapshot>({
+        name: 'ckeditor5',
+        el: createEditorHtmlElement(),
+        ephemeral: {
+          ...createEditorSnapshot(),
+          contextId: DEFAULT_TEST_CONTEXT_ID,
+        },
+      });
+
+      const editor = await waitForTestEditor();
+
+      expect(editor.state).toBe('ready');
+
+      await livewireStub.$internal.unmountComponent(contextId);
+
+      expect(editor.state).toBe('destroyed');
+
+      expect(ContextsRegistry.the.hasItem(DEFAULT_TEST_CONTEXT_ID)).toBe(false);
+      expect(EditorsRegistry.the.hasItem(editorId)).toBe(false);
+    });
+  });
+});

package/src/hooks/context/context.ts

@@ -0,0 +1,116 @@
+import type { Context, ContextWatchdog } from 'ckeditor5';
+
+import type { EditorLanguage } from '../editor';
+import type { ContextConfig } from './typings';
+
+import { ClassHook } from '../../hooks/hook';
+import { isEmptyObject } from '../../shared';
+import {
+  loadAllEditorTranslations,
+  loadEditorPlugins,
+  normalizeCustomTranslations,
+} from '../editor/utils';
+import { ContextsRegistry } from './contexts-registry';
+
+/**
+ * The Livewire hook that mounts CKEditor context instances.
+ */
+export class ContextComponentHook extends ClassHook<Snapshot> {
+  /**
+   * The promise that resolves to the context instance.
+   */
+  private contextPromise: Promise<ContextWatchdog<Context>> | null = null;
+
+  /**
+   * Mounts the context component.
+   */
+  override async mounted() {
+    const { contextId, language, context: contextConfig } = this.ephemeral;
+    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.isBeingDestroyed()) {
+      ContextsRegistry.the.register(contextId, context);
+    }
+  }
+
+  /**
+   * Destroys the context component. Unmounts root from the editor.
+   */
+  override async destroyed() {
+    const { contextId } = this.ephemeral;
+
+    // Let's hide the element during destruction to prevent flickering.
+    this.element.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 (ContextsRegistry.the.hasItem(contextId)) {
+        ContextsRegistry.the.unregister(contextId);
+      }
+    }
+  }
+}
+
+/**
+ * The snapshot type stored in the Livewire Context hook.
+ */
+type Snapshot = {
+  /**
+   * The unique identifier for the context instance.
+   */
+  contextId: string;
+
+  /**
+   * The context configuration for the context instance.
+   */
+  context: ContextConfig;
+
+  /**
+   * The language of the context UI and content.
+   */
+  language: EditorLanguage;
+};

package/src/hooks/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/hooks/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/hooks/context/index.ts

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

package/src/hooks/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;
+};