ckeditor5-blazor 1.10.3 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckeditor5-blazor",
-  "version": "1.10.3",
+  "version": "1.11.1",
   "description": "CKEditor 5 integration for Blazor",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
   ],
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",
-    "ckeditor5": "^47.6.0",
-    "ckeditor5-premium-features": "^47.6.0",
+    "ckeditor5": "^48.1.0",
+    "ckeditor5-premium-features": "^48.1.0",
     "happy-dom": "^20.8.9",
     "typescript": "^5.9.3",
     "vite": "^7.3.2",

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

@@ -84,102 +84,143 @@ describe('context component', () => {
       expect(context?.plugins.get('CustomPlugin')).toBeInstanceOf(CustomPlugin);
     });
 
-    it('registered plugins should support custom translations', async () => {
-      class CustomPlugin extends ContextPlugin {
-        static get pluginName() {
-          return 'CustomPlugin';
+    describe('language param', () => {
+      it('should support passing null language for context translations', async () => {
+        class CustomPlugin extends ContextPlugin {
+          static get pluginName() {
+            return 'CustomPlugin';
+          }
+
+          getHelloTitle() {
+            return this.context.t('HELLO');
+          }
         }
 
-        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'],
+            },
+          },
+          null,
+        ));
 
-      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+        const { context } = await waitForTestContext();
+        const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
 
-      renderTestContext(createContextSnapshot(DEFAULT_TEST_CONTEXT_ID, {
-        customTranslations: {
-          en: {
-            HELLO: 'Hello from 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'],
+            },
           },
-        },
-        config: {
-          plugins: ['CustomPlugin'],
-        },
-      }));
+          {
+            ui: 'pl',
+            content: 'pl',
+          },
+        ));
 
-      const { context } = await waitForTestContext();
-      const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
+        const { context } = await waitForTestContext();
+        const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
 
-      expect(plugin.getHelloTitle()).toBe('Hello from CustomPlugin');
+        expect(plugin.getHelloTitle()).toBe('Witaj z CustomPlugin');
+      });
     });
 
-    it('should support custom language for context translations', async () => {
-      class CustomPlugin extends ContextPlugin {
-        static get pluginName() {
-          return 'CustomPlugin';
-        }
+    describe('translations', () => {
+      it('registered plugins should support custom translations', async () => {
+        class CustomPlugin extends ContextPlugin {
+          static get pluginName() {
+            return 'CustomPlugin';
+          }
 
-        getHelloTitle() {
-          return this.context.t('HELLO');
+          getHelloTitle() {
+            return this.context.t('HELLO');
+          }
         }
-      }
 
-      CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
+        CustomEditorPluginsRegistry.the.register('CustomPlugin', () => CustomPlugin);
 
-      renderTestContext(createContextSnapshot(
-        DEFAULT_TEST_CONTEXT_ID,
-        {
+        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;
+        const { context } = await waitForTestContext();
+        const plugin = context?.plugins.get('CustomPlugin') as CustomPlugin;
 
-      expect(plugin.getHelloTitle()).toBe('Witaj z CustomPlugin');
-    });
+        expect(plugin.getHelloTitle()).toBe('Hello from CustomPlugin');
+      });
 
-    it('should support translations references in config', async () => {
-      renderTestContext(createContextSnapshot(
-        DEFAULT_TEST_CONTEXT_ID,
-        {
-          customTranslations: {
-            en: {
-              HELLO: 'Hello from CustomPlugin',
+      it('should support translations references in config', async () => {
+        renderTestContext(createContextSnapshot(
+          DEFAULT_TEST_CONTEXT_ID,
+          {
+            customTranslations: {
+              en: {
+                HELLO: 'Hello from CustomPlugin',
+              },
+              pl: {
+                HELLO: 'Witaj z CustomPlugin',
+              },
             },
-            pl: {
-              HELLO: 'Witaj z CustomPlugin',
+            config: {
+              customConfig: { $translation: 'HELLO' },
             },
           },
-          config: {
-            customConfig: { $translation: 'HELLO' },
+          {
+            ui: 'pl',
+            content: 'pl',
           },
-        },
-        {
-          ui: 'pl',
-          content: 'pl',
-        },
-      ));
+        ));
 
-      const { context } = await waitForTestContext();
-      const translation = context?.config.get('customConfig') as string;
+        const { context } = await waitForTestContext();
+        const translation = context?.config.get('customConfig') as string;
 
-      expect(translation).toBe('Witaj z CustomPlugin');
+        expect(translation).toBe('Witaj z CustomPlugin');
+      });
     });
   });
 

package/src/elements/context/context.ts

@@ -8,6 +8,7 @@ import {
   loadAllEditorTranslations,
   loadEditorPlugins,
   normalizeCustomTranslations,
+  normalizeEditorLanguage,
   resolveEditorConfigElementReferences,
   resolveEditorConfigTranslations,
 } from '../editor/utils';
@@ -46,11 +47,16 @@ export class ContextComponentElement extends HTMLElement {
    * Initializes the context component.
    */
   private async initializeContext(): Promise<void> {
-    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 contextId = this.getAttribute('data-cke-context-id')!;
+    const language = (
+      this.getAttribute('data-cke-language')
+        ? JSON.parse(this.getAttribute('data-cke-language')!)
+        : normalizeEditorLanguage(config['language'])
+    ) as EditorLanguage;
+
     const { loadedPlugins, hasPremium } = await loadEditorPlugins(plugins ?? []);
 
     // Mix custom translations with loaded translations.

package/src/elements/editable.ts

@@ -88,9 +88,9 @@ export class EditableComponentElement extends HTMLElement {
 
       editor.addRoot(rootName, {
         isUndoable: false,
-        attributes: { ...rootAttributes },
+        modelAttributes: { ...rootAttributes },
         ...content !== null && {
-          data: content,
+          initialData: content,
         },
       });
 

package/src/elements/editor/editor.ts

@@ -1,5 +1,6 @@
 import type { WaitForInteractiveResult } from '../../shared';
 import type { EditorId, EditorLanguage, EditorPreset } from './typings';
+import type { EditableItem } from './utils';
 
 import {
   isEmptyObject,
@@ -14,6 +15,7 @@ import {
   createSyncEditorWithInputPlugin,
 } from './plugins';
 import {
+  assignEditorRootsToConfig,
   cleanupOrphanEditorElements,
   createEditorInContext,
   isSingleRootEditor,
@@ -21,8 +23,8 @@ import {
   loadEditorConstructor,
   loadEditorPlugins,
   normalizeCustomTranslations,
-  queryEditablesElements,
-  queryEditablesSnapshotContent,
+  normalizeEditorLanguage,
+  queryAllEditorEditables,
   resolveEditorConfigElementReferences,
   resolveEditorConfigTranslations,
   setEditorEditableHeight,
@@ -140,16 +142,7 @@ export class EditorComponentElement extends HTMLElement {
    * 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 rootAttributes = JSON.parse(this.getAttribute('data-cke-root-attributes') || '{}');
-    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 useWatchdog = this.hasAttribute('data-cke-watchdog');
-    const content = JSON.parse(this.getAttribute('data-cke-content')!) as Record<string, string>;
-
     const {
       customTranslations,
       editorType,
@@ -158,6 +151,18 @@ export class EditorComponentElement extends HTMLElement {
       config: { plugins, ...config },
     } = preset;
 
+    const editorId = this.getAttribute('data-cke-editor-id')!;
+    const contextId = this.getAttribute('data-cke-context-id');
+    const rootAttributes = JSON.parse(this.getAttribute('data-cke-root-attributes') || '{}');
+    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 useWatchdog = this.hasAttribute('data-cke-watchdog');
+    const language = (
+      this.getAttribute('data-cke-language')
+        ? JSON.parse(this.getAttribute('data-cke-language')!)
+        : normalizeEditorLanguage(preset.config['language'])
+    ) as EditorLanguage;
+
     const Constructor = await loadEditorConstructor(editorType);
     const context = await (
       contextId
@@ -193,70 +198,44 @@ export class EditorComponentElement extends HTMLElement {
       ]
         .filter(translations => !isEmptyObject(translations));
 
-      // Let's query all elements, and create basic configuration.
-      let initialData: string | Record<string, string> = {
-        ...content,
-        ...queryEditablesSnapshotContent(editorId),
-      };
+      // Query all editable elements along with their content in one pass.
+      // Roots present in the editor container's data-cke-content but not yet in the DOM
+      // are included with element: null so we know which roots to wait for.
+      let editables = queryAllEditorEditables(editorId);
+      const requiredRoots = Object.keys(editables);
 
       if (isSingleRootEditor(editorType)) {
-        initialData = initialData['main'] || '';
+        requiredRoots.push('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 (!checkIfAllRootsArePresent(editables, requiredRoots)) {
+        editables = await waitForAllRootsToBePresent(editorId, requiredRoots);
+      }
 
-        // If single root editor, unwrap the element from the object.
-        if (isSingleRootEditor(editorType) && 'main' in sourceElementOrData) {
-          sourceElementOrData = sourceElementOrData['main'];
-        }
+      // Do some postprocessing on received configuration.
+      let resolvedConfig = {
+        ...config,
+        licenseKey,
+        plugins: loadedPlugins,
+        language,
+        ...mixedTranslations.length && {
+          translations: mixedTranslations,
+        },
+      };
 
-        // 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,
-          },
-        };
+      resolvedConfig = resolveEditorConfigElementReferences(resolvedConfig);
+      resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+      resolvedConfig = assignEditorRootsToConfig(Constructor, editables, resolvedConfig);
 
-        if (!context || !(sourceElementOrData instanceof HTMLElement)) {
-          return Constructor.create(sourceElementOrData as any, parsedConfig);
+      const editor = await (async () => {
+        if (!context) {
+          return Constructor.create(resolvedConfig);
         }
 
         const result = await createEditorInContext({
           context,
-          element: sourceElementOrData,
           creator: Constructor,
-          config: parsedConfig,
+          config: resolvedConfig,
         });
 
         return result.editor;
@@ -309,42 +288,42 @@ export class EditorComponentElement extends HTMLElement {
 }
 
 /**
- * Checks if all required root elements are present in the elements object.
+ * Checks if all required root elements are present (i.e. have a non-null element) in the editables map.
  *
- * @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.
+ * @param editables The editables map keyed by root name.
+ * @param requiredRoots The list of required root names.
+ * @returns True if all required roots have a DOM element attached, false otherwise.
  */
-function checkIfAllRootsArePresent(elements: Record<string, HTMLElement>, requiredRoots: string[]): boolean {
-  return requiredRoots.every(rootId => elements[rootId]);
+function checkIfAllRootsArePresent(editables: Record<string, EditableItem>, requiredRoots: string[]): boolean {
+  return requiredRoots.every(rootId => editables[rootId]?.element);
 }
 
 /**
  * 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.
+ * @param requiredRoots The list of required root names.
+ * @returns A promise that resolves to the updated editables map once all elements are attached.
  */
 async function waitForAllRootsToBePresent(
   editorId: EditorId,
   requiredRoots: string[],
-): Promise<Record<string, HTMLElement>> {
+): Promise<Record<string, EditableItem>> {
   return waitFor(
     () => {
-      const elements = queryEditablesElements(editorId) as unknown as Record<string, HTMLElement>;
+      const editables = queryAllEditorEditables(editorId);
 
-      if (!checkIfAllRootsArePresent(elements, requiredRoots)) {
+      if (!checkIfAllRootsArePresent(editables, 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(', ')}.`,
+          + `Missing roots: ${requiredRoots.filter(rootId => !editables[rootId]?.element).join(', ')}.`,
         );
       }
 
-      return elements;
+      return editables;
     },
     { timeOutAfter: 2000, retryAfter: 100 },
   );

package/src/elements/editor/types/editor-relaxed-constructor.type.ts

@@ -0,0 +1,6 @@
+import type { Editor } from 'ckeditor5';
+
+export type EditorRelaxedConstructor<TEditor extends Editor = Editor> = {
+  create: (...args: any) => Promise<TEditor>;
+  editorName?: string;
+};

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

@@ -0,0 +1 @@
+export * from './editor-relaxed-constructor.type';

package/src/elements/editor/utils/assign-editor-roots-to-config.ts

@@ -0,0 +1,60 @@
+import type { EditorRelaxedConstructor } from '../types/editor-relaxed-constructor.type';
+import type { EditableItem } from './query-all-editor-editables';
+import type { EditorConfig } from 'ckeditor5';
+
+/**
+ * Assigns DOM elements and initial data to the editor configuration in a way that is compatible
+ * with the specific editor type.
+ *
+ * Roots with `element: null` (pending roots not yet in the DOM) contribute only `initialData`
+ * and are skipped for element assignment.
+ *
+ * @param Editor Constructor of the editor used to determine the location of element config entry.
+ * @param editables Map of editable items (element + content) keyed by root name.
+ * @param config Config of the editor.
+ * @returns The updated configuration object.
+ */
+export function assignEditorRootsToConfig<C extends EditorConfig>(
+  Editor: EditorRelaxedConstructor,
+  editables: Record<string, EditableItem>,
+  config: C,
+): C {
+  const isClassicEditor = !Editor.editorName || Editor.editorName === 'ClassicEditor';
+  const allRootsKeys = new Set([
+    ...Object.keys(editables),
+    ...Object.keys(config.roots ?? {}),
+  ]);
+
+  const rootsConfig = Array.from(allRootsKeys).reduce((acc, rootKey) => ({
+    ...acc,
+    [rootKey]: {
+      /* v8 ignore next 1 */
+      ...config.roots?.[rootKey],
+      ...rootKey === 'main' ? config.root : {},
+
+      /* v8 ignore next 11 */
+      ...rootKey in editables
+        ? {
+            ...editables[rootKey]!.content !== null && {
+              initialData: editables[rootKey]!.content,
+            },
+            ...!isClassicEditor && editables[rootKey]!.element !== null && {
+              element: editables[rootKey]!.element,
+            },
+          }
+        : {},
+    },
+  }), Object.create(config.roots || {}));
+
+  const mappedConfig: C = {
+    ...config,
+    roots: rootsConfig,
+    ...isClassicEditor && editables['main']?.element && {
+      attachTo: editables['main'].element,
+    },
+  };
+
+  delete mappedConfig.root;
+
+  return mappedConfig;
+}

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

@@ -12,19 +12,17 @@ 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) {
+export async function createEditorInContext({ context, creator, config }: Attrs) {
   const editorContextId = uid();
 
   await context.add({
-    creator: (_element, _config) => creator.create(_element, _config),
+    creator: creator.create.bind(creator),
     id: editorContextId,
-    sourceElementOrData: element,
     type: 'editor',
     config,
   });
@@ -74,7 +72,6 @@ export function unwrapEditorContext(editor: Editor): EditorContextDescriptor | n
 type Attrs = {
   context: ContextWatchdog<Context>;
   creator: EditorCreator;
-  element: HTMLElement;
   config: EditorConfig;
 };
 

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

@@ -1,3 +1,4 @@
+export * from './assign-editor-roots-to-config';
 export * from './cleanup-orphan-editor-elements';
 export * from './create-editor-in-context';
 export * from './get-editor-roots-values';
@@ -6,8 +7,9 @@ export * from './load-editor-constructor';
 export * from './load-editor-plugins';
 export * from './load-editor-translations';
 export * from './normalize-custom-translations';
+export * from './normalize-editor-language';
+export * from './query-all-editor-editables';
 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';

package/src/elements/editor/utils/normalize-editor-language.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeEditorLanguage } from './normalize-editor-language';
+
+describe('normalizeEditorLanguage', () => {
+  describe('when lang is falsy', () => {
+    it('returns default object with "en" for empty string', () => {
+      expect(normalizeEditorLanguage('')).toEqual({ ui: 'en', content: 'en' });
+    });
+
+    it('returns default object with "en" for null', () => {
+      expect(normalizeEditorLanguage(null as any)).toEqual({ ui: 'en', content: 'en' });
+    });
+
+    it('returns default object with "en" for undefined', () => {
+      expect(normalizeEditorLanguage(undefined as any)).toEqual({ ui: 'en', content: 'en' });
+    });
+  });
+
+  describe('when lang is a string', () => {
+    it('returns object with ui and content set to the given language', () => {
+      expect(normalizeEditorLanguage('pl')).toEqual({ ui: 'pl', content: 'pl' });
+    });
+
+    it('handles "en" language code correctly', () => {
+      expect(normalizeEditorLanguage('en')).toEqual({ ui: 'en', content: 'en' });
+    });
+
+    it('handles "de" language code correctly', () => {
+      expect(normalizeEditorLanguage('de')).toEqual({ ui: 'de', content: 'de' });
+    });
+  });
+
+  describe('when lang is an object', () => {
+    it('returns the object unchanged when ui and content are the same', () => {
+      const lang = { ui: 'pl', content: 'pl' };
+      expect(normalizeEditorLanguage(lang)).toEqual(lang);
+    });
+
+    it('returns the object unchanged when ui and content differ', () => {
+      const lang = { ui: 'pl', content: 'en' };
+      expect(normalizeEditorLanguage(lang)).toEqual(lang);
+    });
+
+    it('returns the exact same object reference', () => {
+      const lang = { ui: 'fr', content: 'en' };
+      expect(normalizeEditorLanguage(lang)).toBe(lang);
+    });
+  });
+});