ckeditor5-blazor 0.1.0

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

@@ -0,0 +1,89 @@
+import type { EditorCreator } from './wrap-with-watchdog';
+import type { Context, ContextWatchdog, Editor, EditorConfig } from 'ckeditor5';
+
+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/get-editor-roots-values.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { getEditorRootsValues } from './get-editor-roots-values';
+
+describe('getEditorRootsValues', () => {
+  it('should return values for all regular roots', () => {
+    const editor = {
+      model: {
+        document: {
+          getRoots: () => [
+            { rootName: 'main' },
+            { rootName: 'header' },
+          ],
+        },
+      },
+      getData: ({ rootName }: { rootName: string; }) => ({
+        main: '<p>Main</p>',
+        header: '<p>Header</p>',
+      }[rootName]),
+    };
+
+    expect(getEditorRootsValues(editor as any)).toEqual({
+      main: '<p>Main</p>',
+      header: '<p>Header</p>',
+    });
+  });
+
+  it('should skip the graveyard root', () => {
+    const editor = {
+      model: {
+        document: {
+          getRoots: () => [
+            { rootName: 'main' },
+            { rootName: '$graveyard' },
+          ],
+        },
+      },
+      getData: ({ rootName }: { rootName: string; }) => ({
+        main: '<p>Main</p>',
+        $graveyard: '<p>Should not be included</p>',
+      }[rootName]),
+    };
+
+    expect(getEditorRootsValues(editor as any)).toEqual({
+      main: '<p>Main</p>',
+    });
+  });
+});

package/src/elements/editor/utils/get-editor-roots-values.ts

@@ -0,0 +1,21 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Gets values of all editor roots.
+ *
+ * @param editor The editor instance.
+ * @returns A record where keys are root names and values are root HTML strings.
+ */
+export function getEditorRootsValues(editor: Editor): Record<string, string> {
+  return Array
+    .from(editor.model.document.getRoots())
+    .reduce<Record<string, string>>((acc, root) => {
+      if (root.rootName === '$graveyard') {
+        return acc;
+      }
+
+      acc[root.rootName] = editor.getData({ rootName: root.rootName });
+
+      return acc;
+    }, Object.create({}));
+}

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

@@ -0,0 +1,13 @@
+export * from './create-editor-in-context';
+export * from './get-editor-roots-values';
+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 './resolve-editor-config-translations';
+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 type { EditorType } from '../typings';
+
+import { describe, expect, it } from 'vitest';
+
+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);
+}

package/src/elements/editor/utils/load-editor-constructor.test.ts

@@ -0,0 +1,62 @@
+import type { EditorType } from '../typings';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { loadEditorConstructor } from './load-editor-constructor';
+
+// Mock the ckeditor5 package
+vi.mock('ckeditor5', async () => {
+  const mockEditorConstructor = vi.fn();
+
+  return {
+    InlineEditor: mockEditorConstructor,
+    BalloonEditor: mockEditorConstructor,
+    ClassicEditor: mockEditorConstructor,
+    DecoupledEditor: mockEditorConstructor,
+    MultiRootEditor: mockEditorConstructor,
+  };
+});
+
+describe('loadEditorConstructor', () => {
+  it('should load InlineEditor for inline type', async () => {
+    const constructor = await loadEditorConstructor('inline');
+    expect(constructor).toBeDefined();
+  });
+
+  it('should load BalloonEditor for balloon type', async () => {
+    const constructor = await loadEditorConstructor('balloon');
+    expect(constructor).toBeDefined();
+  });
+
+  it('should load ClassicEditor for classic type', async () => {
+    const constructor = await loadEditorConstructor('classic');
+    expect(constructor).toBeDefined();
+  });
+
+  it('should load DecoupledEditor for decoupled type', async () => {
+    const constructor = await loadEditorConstructor('decoupled');
+    expect(constructor).toBeDefined();
+  });
+
+  it('should load MultiRootEditor for multiroot type', async () => {
+    const constructor = await loadEditorConstructor('multiroot');
+    expect(constructor).toBeDefined();
+  });
+
+  it('should throw error for unsupported editor type', async () => {
+    const invalidType = 'invalid' as EditorType;
+
+    await expect(loadEditorConstructor(invalidType)).rejects.toThrow(
+      'Unsupported editor type: invalid',
+    );
+  });
+
+  it('should return the correct constructor for each editor type', async () => {
+    const editorTypes: EditorType[] = ['inline', 'balloon', 'classic', 'decoupled', 'multiroot'];
+
+    for (const type of editorTypes) {
+      const constructor = await loadEditorConstructor(type);
+      expect(constructor).toBeDefined();
+    }
+  });
+});

package/src/elements/editor/utils/load-editor-constructor.ts

@@ -0,0 +1,29 @@
+import type { EditorType } from '../typings';
+
+import { CKEditor5BlazorError } from '../../../ckeditor5-blazor-error';
+
+/**
+ * Returns the constructor for the specified CKEditor5 editor type.
+ *
+ * @param type - The type of the editor to load.
+ * @returns A promise that resolves to the editor constructor.
+ */
+export async function loadEditorConstructor(type: EditorType) {
+  const PKG = await import('ckeditor5');
+
+  const editorMap = {
+    inline: PKG.InlineEditor,
+    balloon: PKG.BalloonEditor,
+    classic: PKG.ClassicEditor,
+    decoupled: PKG.DecoupledEditor,
+    multiroot: PKG.MultiRootEditor,
+  } as const;
+
+  const EditorConstructor = editorMap[type];
+
+  if (!EditorConstructor) {
+    throw new CKEditor5BlazorError(`Unsupported editor type: ${type}`);
+  }
+
+  return EditorConstructor;
+}

package/src/elements/editor/utils/load-editor-plugins.test.ts

@@ -0,0 +1,100 @@
+import type { EditorPlugin } from '../typings';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { CustomEditorPluginsRegistry } from '../custom-editor-plugins';
+import { loadEditorPlugins } from './load-editor-plugins';
+
+class CustomPlugin {
+  static get pluginName() {
+    return 'CustomPlugin';
+  }
+}
+
+describe('loadEditorPlugins', () => {
+  it('should load plugins from base package', async () => {
+    const plugins: EditorPlugin[] = ['Bold', 'Italic'];
+    const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+    expect(loadedPlugins).toHaveLength(2);
+    expect(loadedPlugins[0]).toBeDefined();
+    expect(loadedPlugins[1]).toBeDefined();
+  });
+
+  it('should load plugins from premium package', async () => {
+    const plugins: EditorPlugin[] = ['ExportInlineStyles', 'Comments'];
+    const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+    expect(loadedPlugins).toHaveLength(2);
+    expect(loadedPlugins[0]).toBeDefined();
+    expect(loadedPlugins[1]).toBeDefined();
+  });
+
+  it('should handle empty plugin array', async () => {
+    const plugins: EditorPlugin[] = [];
+    const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+    expect(loadedPlugins).toHaveLength(0);
+  });
+
+  it('should prioritize base package over premium package', async () => {
+    const plugins: EditorPlugin[] = ['Bold'];
+    const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+    expect(loadedPlugins).toHaveLength(1);
+    expect(loadedPlugins[0]).toBeDefined();
+  });
+
+  it('should return plugin constructors', async () => {
+    const plugins: EditorPlugin[] = ['Bold'];
+    const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+    expect(loadedPlugins).toHaveLength(1);
+    expect(typeof loadedPlugins[0]).toBe('function');
+  });
+
+  it('should throw an error for unknown plugins', async () => {
+    const plugins: EditorPlugin[] = ['UnknownPlugin'];
+    await expect(loadEditorPlugins(plugins)).rejects.toThrowError(/not found/);
+  });
+
+  describe('custom plugins', () => {
+    afterEach(() => {
+      CustomEditorPluginsRegistry.the.unregisterAll();
+    });
+
+    it('should load custom plugins', async () => {
+      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+
+      const plugins: EditorPlugin[] = ['CustomPlugin'];
+      const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+      expect(loadedPlugins).toHaveLength(1);
+      expect(loadedPlugins[0]).toEqual(CustomPlugin);
+    });
+
+    it('should prefer loading custom plugins over base package', async () => {
+      CustomEditorPluginsRegistry.the.register('Bold', () => CustomPlugin);
+
+      const plugins: EditorPlugin[] = ['Bold'];
+      const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+      expect(loadedPlugins).toHaveLength(1);
+      expect(loadedPlugins[0]).toEqual(CustomPlugin);
+    });
+
+    it('should be possible to load async custom plugins', async () => {
+      CustomEditorPluginsRegistry.the.register('AsyncPlugin', async () => {
+        return new Promise((resolve) => {
+          setTimeout(() => resolve(CustomPlugin), 20);
+        });
+      });
+
+      const plugins: EditorPlugin[] = ['AsyncPlugin'];
+      const { loadedPlugins } = await loadEditorPlugins(plugins);
+
+      expect(loadedPlugins).toHaveLength(1);
+      expect(loadedPlugins[0]).toEqual(CustomPlugin);
+    });
+  });
+});

package/src/elements/editor/utils/load-editor-plugins.ts

@@ -0,0 +1,72 @@
+import type { EditorPlugin } from '../typings';
+import type { PluginConstructor } from 'ckeditor5';
+
+import { CKEditor5BlazorError } from '../../../ckeditor5-blazor-error';
+import { CustomEditorPluginsRegistry } from '../custom-editor-plugins';
+
+/**
+ * Loads CKEditor plugins from base and premium packages.
+ * First tries to load from the base 'ckeditor5' package, then falls back to 'ckeditor5-premium-features'.
+ *
+ * @param plugins - Array of plugin names to load
+ * @returns Promise that resolves to an array of loaded Plugin instances
+ * @throws Error if a plugin is not found in either package
+ */
+export async function loadEditorPlugins(plugins: EditorPlugin[]): Promise<LoadedPlugins> {
+  const basePackage = await import('ckeditor5');
+  let premiumPackage: Record<string, any> | null = null;
+
+  const loaders = plugins.map(async (plugin) => {
+    // Let's first try to load the plugin from the base package.
+    // Coverage is disabled due to Vitest issues with mocking dynamic imports.
+
+    // If the plugin is not found in the base package, try custom plugins.
+    const customPlugin = await CustomEditorPluginsRegistry.the.get(plugin);
+
+    if (customPlugin) {
+      return customPlugin;
+    }
+
+    // If not found, try to load from the base package.
+    const { [plugin]: basePkgImport } = basePackage as Record<string, unknown>;
+
+    if (basePkgImport) {
+      return basePkgImport as PluginConstructor;
+    }
+
+    // Plugin not found in base package, try premium package.
+    /* v8 ignore start -- @preserve */
+    if (!premiumPackage) {
+      try {
+        premiumPackage = await import('ckeditor5-premium-features');
+      }
+      catch (error) {
+        console.error(`Failed to load premium package: ${error}`);
+        throw new CKEditor5BlazorError(`Plugin "${plugin}" not found in base package and failed to load premium package.`);
+      }
+    }
+    /* v8 ignore end */
+
+    const { [plugin]: premiumPkgImport } = premiumPackage || {};
+
+    if (premiumPkgImport) {
+      return premiumPkgImport as PluginConstructor;
+    }
+
+    // Plugin not found in either package, throw an error.
+    throw new CKEditor5BlazorError(`Plugin "${plugin}" not found in base or premium packages.`);
+  });
+
+  return {
+    loadedPlugins: await Promise.all(loaders),
+    hasPremium: !!premiumPackage,
+  };
+}
+
+/**
+ * Type representing the loaded plugins and whether premium features are available.
+ */
+type LoadedPlugins = {
+  loadedPlugins: PluginConstructor<any>[];
+  hasPremium: boolean;
+};