ckeditor5-blazor 1.8.0 → 1.9.0

package/dist/interop/create-editable-blazor-interop.d.ts

@@ -17,5 +17,10 @@ export declare function createEditableBlazorInterop(element: HTMLElement, intero
      * If the editor is focused, the update is deferred until blur to avoid interrupting the user.
      */
     setValue: (value: string) => Promise<void>;
+    /**
+     * Updates the root attributes on the editor. This is useful when the Blazor component
+     * re-renders with new root attributes.
+     */
+    setRootAttributes: (rootAttributes?: Record<string, unknown> | null) => Promise<void>;
 };
 //# sourceMappingURL=create-editable-blazor-interop.d.ts.map

package/dist/interop/create-editable-blazor-interop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-editable-blazor-interop.d.ts","sourceRoot":"","sources":["../../../src/interop/create-editable-blazor-interop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAQ9C;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa;IAgDpF;;OAEG;;IAiBH;;;OAGG;sBACqB,MAAM;EAWjC"}
+{"version":3,"file":"create-editable-blazor-interop.d.ts","sourceRoot":"","sources":["../../../src/interop/create-editable-blazor-interop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAS9C;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa;IAoDpF;;OAEG;;IAkBH;;;OAGG;sBACqB,MAAM;IAW9B;;;OAGG;yCACwC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;EAU5E"}

package/dist/interop/create-editor-blazor-interop.d.ts

@@ -11,6 +11,10 @@ export declare function createEditorBlazorInterop(element: HTMLElement, interop:
      * Updates the editor data from Blazor. If the editor is focused, the update is deferred until blur to avoid interrupting the user.
      */
     setValue: (value: Record<string, string>) => Promise<void>;
+    /**
+     * Updates the root attributes on the editor instance.
+     */
+    setRootAttributes: (rootAttributes?: Record<string, unknown> | null) => Promise<void>;
     /**
      * Cleans up all event listeners when the Blazor component is disposed.
      */

package/dist/interop/create-editor-blazor-interop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-editor-blazor-interop.d.ts","sourceRoot":"","sources":["../../../src/interop/create-editor-blazor-interop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa;IA+DlF;;OAEG;sBACqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAS9C;;OAEG;;IAkBH;;;;OAIG;;EAWN"}
+{"version":3,"file":"create-editor-blazor-interop.d.ts","sourceRoot":"","sources":["../../../src/interop/create-editor-blazor-interop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAW9C;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa;IAmElF;;OAEG;sBACqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAS9C;;OAEG;yCACwC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAUzE;;OAEG;;IAmBH;;;;OAIG;;EAWN"}

package/dist/interop/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from './create-editor-value-sync';
+export * from './sync-root-attributes';
 //# sourceMappingURL=index.d.ts.map

package/dist/interop/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/interop/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/interop/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC"}

package/dist/interop/utils/sync-root-attributes.d.ts

@@ -0,0 +1,16 @@
+import { Editor } from 'ckeditor5';
+/**
+ * Creates a function that synchronizes root attributes on the given editor root.
+ *
+ * The returned function tracks which attributes were set by itself and will only
+ * remove attributes it previously managed. This avoids interfering with other
+ * consumers that may also change attributes on the same root.
+ *
+ * @param editor The editor instance containing the root to manage.
+ * @param rootName The name of the root to manage attributes on.
+ * @returns A function that can be called with the desired set of attributes to apply them to the root.
+ *          Calling the function with `null` or an empty object will clear all attributes previously set by it.
+ */
+export declare function createRootAttributesUpdater(editor: Editor, rootName: string): RootAttributesUpdater;
+export type RootAttributesUpdater = (rootAttributes?: Record<string, unknown> | null) => void;
+//# sourceMappingURL=sync-root-attributes.d.ts.map

package/dist/interop/utils/sync-root-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-root-attributes.d.ts","sourceRoot":"","sources":["../../../../src/interop/utils/sync-root-attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CA6BnG;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckeditor5-blazor",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "CKEditor 5 integration for Blazor",
   "license": "MIT",
   "repository": {

package/src/elements/editable.test.ts

@@ -139,6 +139,63 @@ describe('editable component', () => {
       });
     });
 
+    it('should apply provided root attributes to the editable root', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+        rootAttributes: {
+          'data-test-attr': 'foo-root',
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(editor.model.document.getRoot('foo')!.getAttribute('data-test-attr')).toBe('foo-root');
+      });
+    });
+
+    it('should apply provided root attributes when editable is mounted after root already exists', async () => {
+      renderTestEditor({
+        preset: createEditorPreset('multiroot'),
+        content: {},
+      });
+
+      const editor = await waitForTestEditor<MultiRootEditor>();
+
+      renderTestEditable({
+        rootName: 'foo',
+        content: '<p>Initial foo component</p>',
+        rootAttributes: {
+          'data-test-attr': 'foo-root',
+        },
+      });
+
+      editor.model.change((writer) => {
+        writer.addRoot('foo-2');
+      });
+
+      renderTestEditable({
+        rootName: 'foo-2',
+        content: '<p>Initial foo-2 component</p>',
+        rootAttributes: {
+          'data-test-attr': 'foo-2-root',
+        },
+      });
+
+      await vi.waitFor(() => {
+        const { document } = editor.model;
+
+        expect(document.getRoot('foo')!.getAttribute('data-test-attr')).toBe('foo-root');
+        expect(document.getRoot('foo-2')!.getAttribute('data-test-attr')).toBe('foo-2-root');
+      });
+    });
+
     it('should auto-assign editor ID if not provided', async () => {
       renderTestEditor({
         preset: createEditorPreset('multiroot'),

package/src/elements/editable.ts

@@ -2,7 +2,7 @@ import type { WaitForInteractiveResult } from '../shared';
 import type { MultiRootEditor } from 'ckeditor5';
 
 import { CKEditor5BlazorError } from '../ckeditor5-blazor-error';
-import { debounce, waitForDOMReady, waitForInteractiveAttribute } from '../shared';
+import { debounce, isEmptyObject, waitForDOMReady, waitForInteractiveAttribute } from '../shared';
 import { EditorsRegistry } from './editor/editors-registry';
 import { queryAllEditorIds } from './editor/utils';
 
@@ -53,6 +53,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 content = this.getAttribute('data-cke-content');
     const saveDebounceMs = Number.parseInt(this.getAttribute('data-cke-save-debounce-ms')!, 10);
 
@@ -86,11 +87,20 @@ export class EditableComponentElement extends HTMLElement {
           }
         }
 
+        // Assign attributes to the root if they are not empty.
+        // This allows users to add custom attributes to the root element of the editable.
+        if (!isEmptyObject(rootAttributes)) {
+          editor.model.change((writer) => {
+            writer.setAttributes(rootAttributes, root);
+          });
+        }
+
         return editor;
       }
 
       editor.addRoot(rootName, {
         isUndoable: false,
+        attributes: { ...rootAttributes },
         ...content !== null && {
           data: content,
         },

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

@@ -103,6 +103,21 @@ describe('editor component', () => {
 
         expect(editor.getData()).toBe('');
       });
+
+      it('should apply provided root attributes to the editor root', async () => {
+        renderTestEditor({
+          rootAttributes: {
+            'data-test-attr': '123',
+            'data-another-attr': 'abc',
+          },
+        });
+
+        const editor = await waitForTestEditor();
+        const root = editor.model.document.getRoot()!;
+
+        expect(root.getAttribute('data-test-attr')).toBe('123');
+        expect(root.getAttribute('data-another-attr')).toBe('abc');
+      });
     });
 
     describe('inline', () => {

package/src/elements/editor/editor.ts

@@ -151,6 +151,7 @@ export class EditorComponentElement extends HTMLElement {
     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;
@@ -279,6 +280,13 @@ export class EditorComponentElement extends HTMLElement {
       return result.editor;
     })();
 
+    // Assign root attributes if they are not empty. This is needed to support custom attributes on the root element of the editor.
+    if (!isEmptyObject(rootAttributes)) {
+      editor.model.change((writer) => {
+        writer.setAttributes(rootAttributes, editor.model.document.getRoot()!);
+      });
+    }
+
     if (isSingleRootEditor(editorType) && editableHeight) {
       setEditorEditableHeight(editor, editableHeight);
     }

package/src/interop/create-editable-blazor-interop.test.ts

@@ -149,6 +149,48 @@ describe('createEditableBlazorInterop', () => {
       expect(editor.getData()).toBe('<p>test</p>');
     });
 
+    it('should set root attributes on the editor when requested', async () => {
+      const { setRootAttributes } = createEditableBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+
+      await setRootAttributes({ 'data-test': 'value' });
+
+      expect(root.getAttribute('data-test')).toBe('value');
+    });
+
+    it('should only remove attributes that it previously set', async () => {
+      const { setRootAttributes } = createEditableBlazorInterop(element, dotnetInterop);
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      // Simulate another consumer setting an attribute.
+      editor.model.change(writer => writer.setAttribute('data-keep', 'true', root));
+      expect(root.getAttribute('data-keep')).toBe('true');
+
+      await setRootAttributes({ 'data-test': 'value' });
+      expect(root.getAttribute('data-test')).toBe('value');
+      expect(root.getAttribute('data-keep')).toBe('true');
+
+      // Updating with the same key should not remove it.
+      await setRootAttributes({ 'data-test': 'updated' });
+      expect(root.getAttribute('data-test')).toBe('updated');
+
+      // Clearing with an empty object should remove only the attribute managed by us.
+      await setRootAttributes({});
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+      expect(root.getAttribute('data-keep')).toBe('true');
+
+      // Clearing with null should still not remove attributes managed by others.
+      await setRootAttributes(null);
+
+      expect(root.getAttribute('data-keep')).toBe('true');
+    });
+
     it('should not set data if the interop is unmounted before the editor is ready', async () => {
       const { setValue, unmount } = createEditableBlazorInterop(element, dotnetInterop);
 
@@ -161,6 +203,19 @@ describe('createEditableBlazorInterop', () => {
       expect(editor.getData()).toBe('<p>Initial content</p>');
     });
 
+    it('should not set root attributes if the interop is unmounted before the editor is ready', async () => {
+      const { setRootAttributes, unmount } = createEditableBlazorInterop(element, dotnetInterop);
+
+      unmount();
+
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      await setRootAttributes({ 'data-test': 'value' });
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+    });
+
     it('should delay setting data if the editor is focused', async () => {
       const { setValue } = createEditableBlazorInterop(element, dotnetInterop);
       const editor = await waitForTestEditor();

package/src/interop/create-editable-blazor-interop.ts

@@ -1,10 +1,11 @@
 import type { DotNetInterop } from '../types';
+import type { RootAttributesUpdater } from './utils';
 
 import { EditorsRegistry } from '../elements/editor/editors-registry';
 import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
 import { queryAllEditorIds } from '../elements/editor/utils';
 import { markElementAsInteractive } from '../shared';
-import { createEditorValueSync, createNoopSync } from './utils/create-editor-value-sync';
+import { createEditorValueSync, createNoopSync, createRootAttributesUpdater } from './utils';
 
 /**
  * Creates an interop layer to synchronize a single CKEditor 5 editable root with a Blazor component.
@@ -19,9 +20,11 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
   const rootName = element.getAttribute('data-cke-root-name') ?? 'main';
 
   let unmounted = false;
-  let sync = createNoopSync<string>();
   let editorRef: unknown | null = null;
 
+  let sync = createNoopSync<string>();
+  let syncRootAttributes: RootAttributesUpdater | null = null;
+
   /**
    * Handles data change events dispatched by the CKEditor plugin.
    * Filters by both editorId and rootName, then notifies Blazor if the root value changed.
@@ -55,6 +58,8 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
       applyValue: value => editor.setData({ [rootName]: value }),
       isEqual: (a, b) => a === b,
     });
+
+    syncRootAttributes = createRootAttributesUpdater(editor, rootName);
   };
 
   void initializeSynchronization();
@@ -78,6 +83,7 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
         editorRef = null;
       }
 
+      syncRootAttributes = null;
       unmounted = true;
     },
 
@@ -95,5 +101,19 @@ export function createEditableBlazorInterop(element: HTMLElement, interop: DotNe
       // Ensure sync is initialized before forwarding (waitFor guarantees the editor exists)
       sync.setValue(value);
     },
+
+    /**
+     * Updates the root attributes on the editor. This is useful when the Blazor component
+     * re-renders with new root attributes.
+     */
+    setRootAttributes: async (rootAttributes?: Record<string, unknown> | null) => {
+      if (unmounted) {
+        return;
+      }
+
+      await EditorsRegistry.the.waitFor(editorId);
+
+      syncRootAttributes?.(rootAttributes);
+    },
   };
 }

package/src/interop/create-editor-blazor-interop.test.ts

@@ -113,6 +113,54 @@ describe('createEditorBlazorInterop', () => {
     });
   });
 
+  describe('setRootAttributes', () => {
+    it('should update root attributes on the editor', async () => {
+      const { setRootAttributes } = createEditorBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+
+      await setRootAttributes({ 'data-test': 'value' });
+      expect(root.getAttribute('data-test')).toBe('value');
+    });
+
+    it('should only remove attributes that it previously set', async () => {
+      const { setRootAttributes } = createEditorBlazorInterop(element, dotnetInterop);
+
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      // Simulate another consumer setting an attribute.
+      editor.model.change(writer => writer.setAttribute('data-keep', 'true', root));
+      expect(root.getAttribute('data-keep')).toBe('true');
+
+      await setRootAttributes({ 'data-test': 'value' });
+      expect(root.getAttribute('data-test')).toBe('value');
+      expect(root.getAttribute('data-keep')).toBe('true');
+
+      // Clearing should remove only the attribute managed by us.
+      await setRootAttributes(null);
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+      expect(root.getAttribute('data-keep')).toBe('true');
+    });
+
+    it('should not set root attributes if the interop is unmounted', async () => {
+      const { setRootAttributes, unmount } = createEditorBlazorInterop(element, dotnetInterop);
+
+      unmount();
+
+      const editor = await waitForTestEditor();
+      const root = editor.model.document.getRoot()!;
+
+      await setRootAttributes({ 'data-test': 'value' });
+
+      expect(root.getAttribute('data-test')).toBeUndefined();
+    });
+  });
+
   describe('focus tracking', () => {
     it('should call OnEditorFocus if editor gets focused', async () => {
       createEditorBlazorInterop(element, dotnetInterop);

package/src/interop/create-editor-blazor-interop.ts

@@ -1,4 +1,5 @@
 import type { DotNetInterop } from '../types';
+import type { RootAttributesUpdater } from './utils';
 import type { Editor, FileRepository } from 'ckeditor5';
 
 import { ensureEditorElementsRegistered } from '../elements';
@@ -6,7 +7,7 @@ import { EditorsRegistry } from '../elements/editor/editors-registry';
 import { CKEditor5ChangeDataEvent } from '../elements/editor/plugins/dispatch-editor-roots-change-event';
 import { getEditorRootsValues } from '../elements/editor/utils';
 import { markElementAsInteractive, shallowEqual } from '../shared';
-import { createEditorValueSync, createNoopSync } from './utils/create-editor-value-sync';
+import { createEditorValueSync, createNoopSync, createRootAttributesUpdater } from './utils';
 
 /**
  * Creates an interop layer to synchronize a CKEditor 5 instance with a Blazor component.
@@ -22,6 +23,8 @@ export function createEditorBlazorInterop(element: HTMLElement, interop: DotNetI
   let unmountCKEditorListeners: VoidFunction | null = null;
 
   let sync = createNoopSync<Record<string, string>>();
+  let syncRootAttributes: RootAttributesUpdater | null = null;
+
   let editorRef: unknown | null = null;
 
   // Handles data change events dispatched by the CKEditor plugin.
@@ -49,6 +52,8 @@ export function createEditorBlazorInterop(element: HTMLElement, interop: DotNetI
       isEqual: shallowEqual,
     });
 
+    syncRootAttributes = createRootAttributesUpdater(editor, 'main');
+
     // Notify Blazor of focus changes so it can trigger the appropriate callbacks.
     const onFocusChange = (_evt: unknown, _name: unknown, isFocused: boolean) => {
       const method = isFocused ? 'OnEditorFocus' : 'OnEditorBlur';
@@ -90,6 +95,19 @@ export function createEditorBlazorInterop(element: HTMLElement, interop: DotNetI
       sync.setValue(value);
     },
 
+    /**
+     * Updates the root attributes on the editor instance.
+     */
+    setRootAttributes: async (rootAttributes?: Record<string, unknown> | null) => {
+      if (unmounted) {
+        return;
+      }
+
+      await EditorsRegistry.the.waitFor(editorId);
+
+      syncRootAttributes?.(rootAttributes);
+    },
+
     /**
      * Cleans up all event listeners when the Blazor component is disposed.
      */
@@ -107,6 +125,7 @@ export function createEditorBlazorInterop(element: HTMLElement, interop: DotNetI
         editorRef = null;
       }
 
+      syncRootAttributes = null;
       unmounted = true;
     },
 

package/src/interop/utils/index.ts

@@ -1 +1,2 @@
 export * from './create-editor-value-sync';
+export * from './sync-root-attributes';

package/src/interop/utils/sync-root-attributes.ts

@@ -0,0 +1,46 @@
+import type { Editor } from 'ckeditor5';
+
+/**
+ * Creates a function that synchronizes root attributes on the given editor root.
+ *
+ * The returned function tracks which attributes were set by itself and will only
+ * remove attributes it previously managed. This avoids interfering with other
+ * consumers that may also change attributes on the same root.
+ *
+ * @param editor The editor instance containing the root to manage.
+ * @param rootName The name of the root to manage attributes on.
+ * @returns A function that can be called with the desired set of attributes to apply them to the root.
+ *          Calling the function with `null` or an empty object will clear all attributes previously set by it.
+ */
+export function createRootAttributesUpdater(editor: Editor, rootName: string): RootAttributesUpdater {
+  const managedAttrs = new Set<string>();
+
+  return (rootAttributes?: Record<string, unknown> | null) => {
+    editor.model.enqueueChange({ isUndoable: false }, (writer) => {
+      const root = editor.model.document.getRoot(rootName);
+
+      /* v8 ignore next if -- @preserve */
+      if (!root) {
+        return;
+      }
+
+      // Remove previously managed attributes that are no longer requested.
+      for (const key of managedAttrs) {
+        if (rootAttributes && (key in rootAttributes)) {
+          continue;
+        }
+
+        writer.removeAttribute(key, root);
+        managedAttrs.delete(key);
+      }
+
+      // Apply or overwrite requested attributes.
+      for (const [key, value] of Object.entries(rootAttributes ?? {})) {
+        writer.setAttribute(key, value, root);
+        managedAttrs.add(key);
+      }
+    });
+  };
+}
+
+export type RootAttributesUpdater = (rootAttributes?: Record<string, unknown> | null) => void;