ckeditor5-blazor 1.10.2 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckeditor5-blazor",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "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

@@ -14,6 +14,8 @@ import {
   createSyncEditorWithInputPlugin,
 } from './plugins';
 import {
+  assignInitialDataToEditorConfig,
+  assignSourceElementsToEditorConfig,
   cleanupOrphanEditorElements,
   createEditorInContext,
   isSingleRootEditor,
@@ -21,6 +23,7 @@ import {
   loadEditorConstructor,
   loadEditorPlugins,
   normalizeCustomTranslations,
+  normalizeEditorLanguage,
   queryEditablesElements,
   queryEditablesSnapshotContent,
   resolveEditorConfigElementReferences,
@@ -140,16 +143,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 +152,19 @@ 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 content = JSON.parse(this.getAttribute('data-cke-content')!) as Record<string, string>;
+    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
@@ -205,19 +212,19 @@ export class EditorComponentElement extends HTMLElement {
 
       // 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);
+        let sourceElements: 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']) {
+        if (!sourceElements['main']) {
           const requiredRoots = (
             isSingleRootEditor(editorType)
               ? ['main']
               : Object.keys(initialData as Record<string, string>)
           );
 
-          if (!checkIfAllRootsArePresent(sourceElementOrData, requiredRoots)) {
-            sourceElementOrData = await waitForAllRootsToBePresent(editorId, requiredRoots);
+          if (!checkIfAllRootsArePresent(sourceElements, requiredRoots)) {
+            sourceElements = await waitForAllRootsToBePresent(editorId, requiredRoots);
             initialData = {
               ...content,
               ...queryEditablesSnapshotContent(editorId),
@@ -226,20 +233,13 @@ export class EditorComponentElement extends HTMLElement {
         }
 
         // If single root editor, unwrap the element from the object.
-        if (isSingleRootEditor(editorType) && 'main' in sourceElementOrData) {
-          sourceElementOrData = sourceElementOrData['main'];
+        if (isSingleRootEditor(editorType) && 'main' in sourceElements) {
+          sourceElements = sourceElements['main'];
         }
 
-        // 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,
+        // Do some postprocessing on received configuration.
+        let resolvedConfig = {
+          ...config,
           licenseKey,
           plugins: loadedPlugins,
           language,
@@ -248,15 +248,19 @@ export class EditorComponentElement extends HTMLElement {
           },
         };
 
-        if (!context || !(sourceElementOrData instanceof HTMLElement)) {
-          return Constructor.create(sourceElementOrData as any, parsedConfig);
+        resolvedConfig = resolveEditorConfigElementReferences(resolvedConfig);
+        resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+        resolvedConfig = assignSourceElementsToEditorConfig(Constructor, sourceElements, resolvedConfig);
+        resolvedConfig = assignInitialDataToEditorConfig(initialData, resolvedConfig);
+
+        if (!context) {
+          return Constructor.create(resolvedConfig);
         }
 
         const result = await createEditorInContext({
           context,
-          element: sourceElementOrData,
           creator: Constructor,
-          config: parsedConfig,
+          config: resolvedConfig,
         });
 
         return result.editor;

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-initial-data-to-editor-config.ts

@@ -0,0 +1,47 @@
+import type { EditorConfig } from 'ckeditor5';
+
+/**
+ * Assigns initial data to specified editor config.
+ *
+ * @param dataOrMap Initial data to be assigned to config.
+ * @param config Config of the editor.
+ * @returns The updated configuration object.
+ */
+export function assignInitialDataToEditorConfig<C extends EditorConfig>(
+  dataOrMap: string | Record<string, string>,
+  config: C,
+): C {
+  const dataMap = toDataMap(dataOrMap);
+  const allRootsKeys = new Set([
+    ...Object.keys(dataMap),
+    ...Object.keys(config.roots ?? {}),
+  ]);
+
+  const rootsConfig = Array.from(allRootsKeys).reduce((acc, rootKey) => ({
+    ...acc,
+    [rootKey]: {
+      ...config.roots?.[rootKey],
+      ...rootKey === 'main' ? config.root : {},
+
+      /* v8 ignore next 5 */
+      ...rootKey in dataMap
+        ? {
+            initialData: dataMap[rootKey],
+          }
+        : {},
+    },
+  }), Object.create(config.roots || {}));
+
+  const mappedConfig: C = {
+    ...config,
+    roots: rootsConfig,
+  };
+
+  delete mappedConfig.root;
+
+  return mappedConfig;
+}
+
+function toDataMap(element: string | Record<string, string>): Record<string, string> {
+  return typeof element === 'string' ? { main: element } : { ...element };
+}

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

@@ -0,0 +1,59 @@
+import type { EditorRelaxedConstructor } from '../types/editor-relaxed-constructor.type';
+import type { EditorConfig } from 'ckeditor5';
+
+/**
+ * Assigns a DOM element to the editor configuration in a way that is compatible with the specific editor type.
+ *
+ * @param Editor Constructor of the editor used to determine the location of element config entry.
+ * @param elementOrMap Element to be assigned to config.
+ * @param config Config of the editor.
+ * @returns The updated configuration object.
+ */
+export function assignSourceElementsToEditorConfig<C extends EditorConfig>(
+  Editor: EditorRelaxedConstructor,
+  elementOrMap: HTMLElement | Record<string, HTMLElement>,
+  config: C,
+): C {
+  const elementsMap = toElementsMap(elementOrMap);
+
+  if (!Editor.editorName || Editor.editorName === 'ClassicEditor') {
+    return {
+      ...config,
+      attachTo: elementsMap['main'],
+    };
+  }
+
+  const allRootsKeys = new Set([
+    ...Object.keys(elementsMap),
+    ...Object.keys(config.roots ?? {}),
+  ]);
+
+  const rootsConfig = Array.from(allRootsKeys).reduce((acc, rootKey) => ({
+    ...acc,
+    [rootKey]: {
+      /* v8 ignore next */
+      ...config.roots?.[rootKey],
+      ...rootKey === 'main' ? config.root : {},
+
+      /* v8 ignore next 5 */
+      ...rootKey in elementsMap
+        ? {
+            element: elementsMap[rootKey],
+          }
+        : {},
+    },
+  }), Object.create(config.roots || {}));
+
+  const mappedConfig: C = {
+    ...config,
+    roots: rootsConfig,
+  };
+
+  delete mappedConfig.root;
+
+  return mappedConfig;
+}
+
+function toElementsMap(element: HTMLElement | Record<string, HTMLElement>): Record<string, HTMLElement> {
+  return element instanceof HTMLElement ? { main: element } : { ...element };
+}

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,5 @@
+export * from './assign-initial-data-to-editor-config';
+export * from './assign-source-elements-to-editor-config';
 export * from './cleanup-orphan-editor-elements';
 export * from './create-editor-in-context';
 export * from './get-editor-roots-values';
@@ -6,6 +8,7 @@ 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-ids';
 export * from './query-editor-editables';
 export * from './resolve-editor-config-elements-references';

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);
+    });
+  });
+});

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

@@ -0,0 +1,25 @@
+import type { EditorLanguage } from '../typings';
+
+/**
+ * Normalize editor language into object.
+ *
+ * @param lang Editor language.
+ * @returns Language object.
+ */
+export function normalizeEditorLanguage(lang: EditorLanguage | string): EditorLanguage {
+  if (!lang) {
+    return {
+      ui: 'en',
+      content: 'en',
+    };
+  }
+
+  if (typeof lang === 'string') {
+    return {
+      ui: lang,
+      content: lang,
+    };
+  }
+
+  return lang;
+}