ckeditor5-blazor 1.11.0 → 1.12.0

package/package.json

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

package/src/elements/editable.test.ts

@@ -233,6 +233,42 @@ describe('editable component', () => {
 
       expect(editor.model.document.getRoot('foo')).toBe(null);
     });
+
+    it('should set proper root element name on initial added root', async () => {
+      renderTestEditable({
+        content: '<p>Foo</p>',
+        rootName: 'foo',
+        rootModelElementName: '$inlineRoot',
+      });
+
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      expect(editor.model.document.getRoot('foo')?.name).to.be.equal('$inlineRoot');
+    });
+
+    it('should set proper root element name on lazy added root', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        content: '<p>Foo</p>',
+        rootName: 'foo',
+        rootModelElementName: '$inlineRoot',
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.model.document.getRoot('foo')?.name).to.be.equal('$inlineRoot');
+      });
+    });
   });
 
   describe('input value synchronization', () => {
@@ -252,7 +288,8 @@ describe('editable component', () => {
       renderTestEditable({
         rootName: 'foo',
         content: '<p>Initial foo component</p>',
-      }, { withInput: false });
+        withInput: false,
+      });
 
       await vi.waitFor(() => {
         expect(editor.getData({ rootName: 'foo' })).toBe('<p>Initial foo component</p>');
@@ -263,7 +300,8 @@ describe('editable component', () => {
       const element = renderTestEditable({
         rootName: 'foo',
         content: '<p>Initial foo component</p>',
-      }, { withInput: true });
+        withInput: true,
+      });
 
       const input = element.querySelector('input')!;
 
@@ -277,7 +315,8 @@ describe('editable component', () => {
         rootName: 'foo',
         content: '<p>Initial foo component</p>',
         saveDebounceMs: 500,
-      }, { withInput: true });
+        withInput: true,
+      });
 
       const input = element.querySelector('input')!;
 

package/src/elements/editable.ts

@@ -42,6 +42,7 @@ export class EditableComponentElement extends HTMLElement {
     const editorId = this.getAttribute('data-cke-editor-id');
     const rootName = this.getAttribute('data-cke-root-name');
     const rootAttributes = JSON.parse(this.getAttribute('data-cke-root-attributes') || '{}');
+    const rootModelElement = this.getAttribute('data-cke-root-model-element-name') || '$root';
     const content = this.getAttribute('data-cke-content');
     const saveDebounceMs = Number.parseInt(this.getAttribute('data-cke-save-debounce-ms')!, 10);
 
@@ -89,6 +90,7 @@ export class EditableComponentElement extends HTMLElement {
       editor.addRoot(rootName, {
         isUndoable: false,
         modelAttributes: { ...rootAttributes },
+        modelElement: rootModelElement,
         ...content !== null && {
           initialData: content,
         },

package/src/elements/editor/editor.test.ts

@@ -12,7 +12,6 @@ import {
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
-  createEditableSnapshot,
   createEditorPreset,
   getTestEditorInput,
   html,
@@ -118,6 +117,16 @@ describe('editor component', () => {
         expect(root.getAttribute('data-test-attr')).toBe('123');
         expect(root.getAttribute('data-another-attr')).toBe('abc');
       });
+
+      it('should be possible to specify root element name', async () => {
+        renderTestEditor({
+          rootModelElementName: '$inlineRoot',
+        });
+
+        const editor = await waitForTestEditor();
+
+        expect(editor.model.document.getRoot()?.name).toBe('$inlineRoot');
+      });
     });
 
     describe('inline', () => {
@@ -134,7 +143,7 @@ describe('editor component', () => {
     describe('decoupled', () => {
       it('should create a decoupled editor with `main` editable and default preset', async () => {
         renderTestEditor({ preset: createEditorPreset('decoupled') });
-        renderTestEditable(createEditableSnapshot('main', null));
+        renderTestEditable();
 
         const editor = await waitForTestEditor();
 
@@ -146,7 +155,7 @@ describe('editor component', () => {
         const initialEditableContent = '<p>Initial editable content</p>';
 
         renderTestEditor({ preset: createEditorPreset('decoupled') });
-        renderTestEditable(createEditableSnapshot('main', initialEditableContent));
+        renderTestEditable({ content: initialEditableContent });
 
         const editor = await waitForTestEditor();
 
@@ -159,13 +168,64 @@ describe('editor component', () => {
 
         await timeout(200);
 
-        renderTestEditable(createEditableSnapshot('main', null));
+        renderTestEditable({});
 
         const editor = await waitForTestEditor();
 
         expect(editor).to.toBeInstanceOf(DecoupledEditor);
         expect(isEditorShown()).toBe(true);
       });
+
+      it('should be possible to specify root element name using editable config alone', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('decoupled'),
+          content: {},
+        });
+
+        renderTestEditable({
+          rootModelElementName: '$inlineRoot',
+        });
+
+        const editor = await waitForTestEditor<DecoupledEditor>();
+
+        await vi.waitFor(() => {
+          expect(editor.model.document.getRoot()?.name).toEqual('$inlineRoot');
+        });
+      });
+
+      it('should use editable root element name config if both specified', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('decoupled'),
+          content: {},
+          rootModelElementName: '$miamia',
+        });
+
+        renderTestEditable({
+          rootModelElementName: '$inlineRoot',
+        });
+
+        const editor = await waitForTestEditor<DecoupledEditor>();
+
+        await vi.waitFor(() => {
+          expect(editor.model.document.getRoot()?.name).toEqual('$inlineRoot');
+        });
+      });
+
+      it('should use default `$root` if editable root name is not specified', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('decoupled'),
+          content: {},
+          rootModelElementName: '$miamia',
+        });
+
+        renderTestEditable();
+
+        const editor = await waitForTestEditor<DecoupledEditor>();
+
+        await vi.waitFor(() => {
+          expect(editor.model.document.getRoot()?.name).toEqual('$root');
+        });
+      });
     });
 
     describe('balloon', () => {
@@ -201,7 +261,7 @@ describe('editor component', () => {
 
         await timeout(500); // Simulate some delay before adding the root.
 
-        renderTestEditable(createEditableSnapshot('header'));
+        renderTestEditable({ rootName: 'header' });
 
         const editor = await waitForTestEditor();
 
@@ -219,7 +279,10 @@ describe('editor component', () => {
 
         await timeout(500); // Simulate some delay before adding the root.
 
-        renderTestEditable(createEditableSnapshot('header', ''));
+        renderTestEditable({
+          rootName: 'header',
+          content: '',
+        });
 
         const editor = await waitForTestEditor();
 
@@ -235,9 +298,10 @@ describe('editor component', () => {
           },
         });
 
-        renderTestEditable(
-          createEditableSnapshot('header', '<p>Editable content overrides snapshot content</p>'),
-        );
+        renderTestEditable({
+          rootName: 'header',
+          content: '<p>Editable content overrides snapshot content</p>',
+        });
 
         const editor = await waitForTestEditor();
 
@@ -270,14 +334,34 @@ describe('editor component', () => {
 
         const editor = await waitForTestEditor<MultiRootEditor>();
 
-        editor.addRoot('existingRoot', { data: '<p>Old content</p>' });
+        editor.addRoot('existingRoot', { initialData: '<p>Old content</p>' });
 
-        renderTestEditable(createEditableSnapshot('existingRoot', '<p>New content</p>'));
+        renderTestEditable({
+          rootName: 'existingRoot',
+          content: '<p>New content</p>',
+        });
 
         await vi.waitFor(() => {
           expect(editor.getData({ rootName: 'existingRoot' })).toBe('<p>New content</p>');
         });
       });
+
+      it('should create a multiroot editor with inline editables', async () => {
+        renderTestEditor({
+          preset: createEditorPreset('multiroot'),
+          content: {},
+        });
+
+        renderTestEditable({ rootName: 'second', rootModelElementName: '$inlineRoot' });
+        renderTestEditable({ rootName: 'third', rootModelElementName: '$inlineRoot' });
+
+        const editor = await waitForTestEditor();
+
+        await vi.waitFor(() => {
+          expect(editor.model.document.getRoot('second')?.name).toEqual('$inlineRoot');
+          expect(editor.model.document.getRoot('third')?.name).toEqual('$inlineRoot');
+        });
+      });
     });
   });
 
@@ -537,8 +621,8 @@ describe('editor component', () => {
 
       component.addEventListener('ckeditor5:change:data', changeSpy);
 
-      renderTestEditable(createEditableSnapshot('header'));
-      renderTestEditable(createEditableSnapshot('footer'));
+      renderTestEditable({ rootName: 'header' });
+      renderTestEditable({ rootName: 'footer' });
 
       const editor = await waitForTestEditor<MultiRootEditor>();
 

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,8 +15,7 @@ import {
   createSyncEditorWithInputPlugin,
 } from './plugins';
 import {
-  assignInitialDataToEditorConfig,
-  assignSourceElementsToEditorConfig,
+  assignEditorRootsToConfig,
   cleanupOrphanEditorElements,
   createEditorInContext,
   isSingleRootEditor,
@@ -24,8 +24,7 @@ import {
   loadEditorPlugins,
   normalizeCustomTranslations,
   normalizeEditorLanguage,
-  queryEditablesElements,
-  queryEditablesSnapshotContent,
+  queryAllEditorEditables,
   resolveEditorConfigElementReferences,
   resolveEditorConfigTranslations,
   setEditorEditableHeight,
@@ -158,7 +157,6 @@ export class EditorComponentElement extends HTMLElement {
     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')!)
@@ -200,59 +198,36 @@ 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 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 (!sourceElements['main']) {
-          const requiredRoots = (
-            isSingleRootEditor(editorType)
-              ? ['main']
-              : Object.keys(initialData as Record<string, string>)
-          );
-
-          if (!checkIfAllRootsArePresent(sourceElements, requiredRoots)) {
-            sourceElements = await waitForAllRootsToBePresent(editorId, requiredRoots);
-            initialData = {
-              ...content,
-              ...queryEditablesSnapshotContent(editorId),
-            };
-          }
-        }
-
-        // If single root editor, unwrap the element from the object.
-        if (isSingleRootEditor(editorType) && 'main' in sourceElements) {
-          sourceElements = sourceElements['main'];
-        }
+      if (!checkIfAllRootsArePresent(editables, requiredRoots)) {
+        editables = await waitForAllRootsToBePresent(editorId, requiredRoots);
+      }
 
-        // Do some postprocessing on received configuration.
-        let resolvedConfig = {
-          ...config,
-          licenseKey,
-          plugins: loadedPlugins,
-          language,
-          ...mixedTranslations.length && {
-            translations: mixedTranslations,
-          },
-        };
+      // Do some postprocessing on received configuration.
+      let resolvedConfig = {
+        ...config,
+        licenseKey,
+        plugins: loadedPlugins,
+        language,
+        ...mixedTranslations.length && {
+          translations: mixedTranslations,
+        },
+      };
 
-        resolvedConfig = resolveEditorConfigElementReferences(resolvedConfig);
-        resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
-        resolvedConfig = assignSourceElementsToEditorConfig(Constructor, sourceElements, resolvedConfig);
-        resolvedConfig = assignInitialDataToEditorConfig(initialData, resolvedConfig);
+      resolvedConfig = resolveEditorConfigElementReferences(resolvedConfig);
+      resolvedConfig = resolveEditorConfigTranslations([...mixedTranslations].reverse(), language.ui, resolvedConfig);
+      resolvedConfig = assignEditorRootsToConfig(Constructor, editables, resolvedConfig);
 
+      const editor = await (async () => {
         if (!context) {
           return Constructor.create(resolvedConfig);
         }
@@ -313,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/utils/assign-editor-roots-to-config.ts

@@ -0,0 +1,61 @@
+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 12 */
+      ...rootKey in editables
+        ? {
+            ...editables[rootKey]!.content !== null && {
+              initialData: editables[rootKey]!.content,
+            },
+            modelElement: editables[rootKey]!.modelElement || '$root',
+            ...!isClassicEditor && editables[rootKey]!.element !== null && {
+              element: editables[rootKey]!.element,
+            },
+          }
+        : {},
+    },
+  }), { ...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/get-editor-roots-values.ts

@@ -17,5 +17,5 @@ export function getEditorRootsValues(editor: Editor): Record<string, string> {
       acc[root.rootName] = editor.getData({ rootName: root.rootName });
 
       return acc;
-    }, Object.create({}));
+    }, Object.create(null));
 }

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

@@ -1,5 +1,4 @@
-export * from './assign-initial-data-to-editor-config';
-export * from './assign-source-elements-to-editor-config';
+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';
@@ -9,8 +8,8 @@ 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/query-all-editor-editables.ts

@@ -0,0 +1,81 @@
+import type { EditorId } from '../typings';
+
+/**
+ * Queries all editable elements within a specific editor instance. It picks
+ * initial values from actually rendered elements or from the editor container's
+ * `data-cke-content` attribute, whichever is available.
+ *
+ * Roots present in the editor container's content but without a matching
+ * `cke5-editable` element yet are included with `element: null` — these are
+ * "pending" roots that haven't been attached to the DOM yet.
+ *
+ * @param editorId The ID of the editor to query.
+ * @returns An object mapping root names to their corresponding elements and content.
+ */
+export function queryAllEditorEditables(editorId: EditorId): Record<string, EditableItem> {
+  const acc = Array
+    .from(document.querySelectorAll<HTMLElement>(`cke5-editable[data-cke-editor-id="${editorId}"]`))
+    .reduce<Record<string, EditableItem>>((acc, element) => {
+      const rootName = element.getAttribute('data-cke-root-name')!;
+      const modelElement = element.getAttribute('data-cke-root-model-element-name') || null;
+
+      acc[rootName] = {
+        element: element.querySelector<HTMLElement>('[data-cke-editable-content]'),
+        content: element.getAttribute('data-cke-content'),
+        modelElement,
+      };
+
+      return acc;
+    }, Object.create(null));
+
+  const rootEditorElement = document.querySelector<HTMLElement>(`cke5-editor[data-cke-editor-id="${editorId}"]`);
+
+  /* v8 ignore next -- @preserve */
+  if (!rootEditorElement) {
+    return acc;
+  }
+
+  // v8 ignore next -- @preserve
+  const editorContent: Record<string, string> = JSON.parse(rootEditorElement.getAttribute('data-cke-content')!) ?? {};
+  const classicMainElement = document.querySelector<HTMLElement>(`#${editorId}_editor`);
+  const rootEditorModelElement = rootEditorElement.getAttribute('data-cke-root-model-element-name');
+
+  if (classicMainElement && !acc['main']) {
+    acc['main'] = {
+      element: classicMainElement,
+      content: editorContent['main'] || '',
+      modelElement: rootEditorModelElement,
+    };
+  }
+
+  for (const [rootName, rootContent] of Object.entries(editorContent)) {
+    if (acc[rootName]) {
+      // Editable element is already present — fill content from editor level if the editable didn't provide its own.
+      acc[rootName] = {
+        ...acc[rootName],
+        content: acc[rootName].content ?? rootContent,
+        modelElement: acc[rootName].modelElement ?? rootEditorModelElement,
+      };
+    }
+    else {
+      // Root has server-provided content but its editable element hasn't been attached to the DOM yet.
+      acc[rootName] = {
+        element: null,
+        content: rootContent,
+        modelElement: rootEditorModelElement,
+      };
+    }
+  }
+
+  return acc;
+}
+
+/**
+ * Type representing an editable item within an editor.
+ * `element` is null when the root's DOM element hasn't appeared yet (pending root).
+ */
+export type EditableItem = {
+  element: HTMLElement | null;
+  content: string | null;
+  modelElement: string | null;
+};