@ckeditor/ckeditor5-editor-multi-root 48.0.1-alpha.1 → 48.1.0-alpha.0

package/dist/augmentation.d.ts

@@ -2,88 +2,9 @@
  * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
-import { type RootAttributes } from './multirooteditor.js';
+import '@ckeditor/ckeditor5-core';
 declare module '@ckeditor/ckeditor5-core' {
     interface RootConfig {
-        /**
-         * Initial root attributes for a root.
-         *
-         * **Note: This configuration option is supported only by the
-         * {@link module:editor-multi-root/multirooteditor~MultiRootEditor multi-root} editor type.**
-         *
-         * **Note: You must provide full set of attributes for each root. If an attribute is not set on a root, set the value to `null`.
-         * Only provided attribute keys will be returned by
-         * {@link module:editor-multi-root/multirooteditor~MultiRootEditor#getRootsAttributes}.**
-         *
-         * Roots attributes hold additional data related to the document roots, in addition to the regular document data (which usually is
-         * HTML). In roots attributes, for each root, you can store arbitrary key-value pairs with attributes connected with that root.
-         * Use it to store any custom data that is specific to your integration or custom features.
-         *
-         * Currently, any official plugins do not use root attributes. This is a mechanism that is prepared for custom features
-         * and non-standard integrations. If you do not provide any custom feature that would use root attributes, you do not need to
-         * handle (save and load) this property.
-         *
-         * ```ts
-         * MultiRootEditor.create(
-         * 	// Roots for the editor:
-         * 	{
-         * 		uid1: document.querySelector( '#uid1' ),
-         * 		uid2: document.querySelector( '#uid2' ),
-         * 		uid3: document.querySelector( '#uid3' ),
-         * 		uid4: document.querySelector( '#uid4' )
-         * 	},
-         * 	// Config:
-         * 	{
-         * 		roots: {
-         * 			uid1: {
-         * 				modelAttributes: { order: 20, isLocked: false } // Third, unlocked.
-         * 			},
-         * 			uid2: {
-         * 				modelAttributes: { order: 10, isLocked: true } // Second, locked.
-         * 			},
-         * 			uid3: {
-         * 				modelAttributes: { order: 30, isLocked: true } // Fourth, locked.
-         * 			},
-         * 			uid4: {
-         * 				modelAttributes: { order: 0, isLocked: false } // First, unlocked.
-         * 			}
-         * 		}
-         * 	}
-         * )
-         * .then( ... )
-         * .catch( ... );
-         * ```
-         *
-         * Note, that the above code snippet is only an example. You need to implement your own features that will use these attributes.
-         *
-         * Roots attributes can be changed the same way as attributes set on other model nodes:
-         *
-         * ```ts
-         * editor.model.change( writer => {
-         * 	const root = editor.model.getRoot( 'uid3' );
-         *
-         * 	writer.setAttribute( 'order', 40, root );
-         * } );
-         * ```
-         *
-         * You can react to root attributes changes by listening to
-         * {@link module:engine/model/document~ModelDocument#event:change:data document `change:data` event}:
-         *
-         * ```ts
-         * editor.model.document.on( 'change:data', () => {
-         * 	const changedRoots = editor.model.document.differ.getChangedRoots();
-         *
-         * 	for ( const change of changedRoots ) {
-         * 		if ( change.attributes ) {
-         * 			const root = editor.model.getRoot( change.name );
-         *
-         * 			// ...
-         * 		}
-         * 	}
-         * } );
-         * ```
-         */
-        modelAttributes?: RootAttributes;
         /**
          * Flag for the root that exist in the document but is not initially loaded by the editor.
          *

package/dist/index.d.ts

@@ -8,5 +8,6 @@
 export { MultiRootEditor } from './multirooteditor.js';
 export { MultiRootEditorUI } from './multirooteditorui.js';
 export { MultiRootEditorUIView } from './multirooteditoruiview.js';
-export type { RootAttributes, AddRootEvent, DetachRootEvent, LoadRootEvent, AddRootOptions, LoadRootOptions, AddRootRootConfig, RootEditableOptions } from './multirooteditor.js';
+export type { AddRootEvent, DetachRootEvent, LoadRootEvent, AddRootOptions, LoadRootOptions, AddRootRootConfig, RootEditableOptions } from './multirooteditor.js';
+export type { EditorRootAttributes as RootAttributes } from '@ckeditor/ckeditor5-core';
 import './augmentation.js';

package/dist/index.js

@@ -2,7 +2,7 @@
  * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
-import { Editor, normalizeMultiRootEditorConstructorParams, normalizeRootsConfig, secureSourceElement } from '@ckeditor/ckeditor5-core/dist/index.js';
+import { Editor, normalizeMultiRootEditorConstructorParams, normalizeRootsConfig, secureSourceElement, registerAndInitializeRootConfigAttributes, verifyRootElements } from '@ckeditor/ckeditor5-core/dist/index.js';
 import { CKEditorError, logWarning, decodeLicenseKey, isFeatureBlockedByLicenseKey, setDataInElement } from '@ckeditor/ckeditor5-utils/dist/index.js';
 import { EditorUI, EditorUIView, ToolbarView, MenuBarView, InlineEditableUIView } from '@ckeditor/ckeditor5-ui/dist/index.js';
 import { enableViewPlaceholder } from '@ckeditor/ckeditor5-engine/dist/index.js';
@@ -310,11 +310,6 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
     /**
 	 * The elements on which the editor has been initialized.
 	 */ sourceElements;
-    /**
-	 * Holds attributes keys that were passed in
-	 * {@link module:core/editor/editorconfig~EditorConfig#roots `config.roots.<rootName>.modelAttributes`}
-	 * and should be returned by {@link #getRootsAttributes}.
-	 */ _registeredRootsAttributesKeys = new Set();
     /**
 	 * A set of lock IDs for enabling or disabling particular root.
 	 */ _readOnlyRootLocks = new Map();
@@ -366,17 +361,12 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
         });
         for (const [rootName, rootConfig] of rootsConfig){
             // Create root and `UIView` element for each editable container.
-            const root = this.model.document.createRoot('$root', rootName);
+            const root = this.model.document.createRoot(rootConfig.modelElement, rootName);
             if (rootConfig.lazyLoad) {
                 root._isLoaded = false;
             }
-            const attributes = rootConfig.modelAttributes;
-            if (attributes) {
-                for (const key of Object.keys(attributes)){
-                    this.registerRootAttribute(key);
-                }
-            }
         }
+        registerAndInitializeRootConfigAttributes(this);
         // Registering `$rootEditableOptions` attribute to make it available in the editor model.
         // This allows to store editable options for each root in the model, and make them available on other RTC clients.
         // We do not use `registerRootAttribute()` method here, as this attribute is used internally
@@ -390,11 +380,6 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
             }, (writer)=>{
                 for (const [rootName, rootConfig] of rootsConfig){
                     const root = this.model.document.getRoot(rootName);
-                    for (const [key, value] of Object.entries(rootConfig.modelAttributes || {})){
-                        if (value !== null) {
-                            writer.setAttribute(key, value, root);
-                        }
-                    }
                     // Set editable config for consistency with `addRoot()` method. This will allow features
                     // to use the same configuration for both initially loaded and dynamically added roots.
                     const rootEditableOptions = {
@@ -517,7 +502,7 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
 	 * 	console.log( 'Editor was destroyed' );
 	 * } );
 	 * ```
-	 */ destroy() {
+	 */ async destroy() {
         const shouldUpdateSourceElement = this.config.get('updateSourceElementOnDestroy');
         // Cache the data and editable DOM elements, then destroy.
         // It's safe to assume that the model->view conversion will not work after `super.destroy()`,
@@ -529,16 +514,32 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
             }) : '';
         }
         this.ui.destroy();
-        return super.destroy().then(()=>{
-            for (const rootName of Object.keys(this.sourceElements)){
-                setDataInElement(this.sourceElements[rootName], data[rootName]);
-            }
-        });
+        await super.destroy();
+        for (const rootName of Object.keys(this.sourceElements)){
+            setDataInElement(this.sourceElements[rootName], data[rootName]);
+        }
+        // To satisfy the return type and to keep it backward compatible.
+        // eslint-disable-next-line no-useless-return
+        return;
     }
     addRoot(rootName, options = {}) {
         const initialData = options.initialData || options.data || '';
         const modelAttributes = options.modelAttributes || options.attributes || {};
-        const modelElement = options.elementName || '$root';
+        const modelElement = options.modelElement || options.elementName || '$root';
+        if (!this.model.schema.isLimit(modelElement)) {
+            /**
+			 * The model root element must be a {@link module:engine/model/schema~ModelSchemaItemDefinition#isLimit limit element}.
+			 * The element name specified in {@link ~MultiRootEditor#addRoot `addRoot()`} options must be registered in the schema
+			 * with `isLimit` set to `true`.
+			 *
+			 * @error multi-root-editor-add-root-element-is-not-limit
+			 * @param rootName The name of the root that uses a non-limit element.
+			 * @param elementName The name of the model element used for the root.
+			 */ throw new CKEditorError('multi-root-editor-add-root-element-is-not-limit', this, {
+                rootName,
+                elementName: modelElement
+            });
+        }
         if (isElement(options.element)) {
             /**
 			 * The `element` option is not supported in {@link #addRoot `addRoot()`} method, and will be ignored.
@@ -751,38 +752,6 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
         }
         return rootsAttributes;
     }
-    /**
-	 * Returns attributes for the specified root.
-	 *
-	 * Note: all and only {@link ~MultiRootEditor#registerRootAttribute registered} roots attributes will be returned.
-	 * If a registered root attribute is not set for a given root, `null` will be returned.
-	 */ getRootAttributes(rootName) {
-        const rootAttributes = {};
-        const root = this.model.document.getRoot(rootName);
-        for (const key of this._registeredRootsAttributesKeys){
-            rootAttributes[key] = root.hasAttribute(key) ? root.getAttribute(key) : null;
-        }
-        return rootAttributes;
-    }
-    /**
-	 * Registers given string as a root attribute key. Registered root attributes are added to
-	 * {@link module:engine/model/schema~ModelSchema schema}, and also returned by
-	 * {@link ~MultiRootEditor#getRootAttributes `getRootAttributes()`} and
-	 * {@link ~MultiRootEditor#getRootsAttributes `getRootsAttributes()`}.
-	 *
-	 * Note: attributes passed in
-	 * {@link module:core/editor/editorconfig~EditorConfig#roots `config.roots.<rootName>.modelAttributes`}
-	 * are automatically registered as the editor is initialized. However, registering the same attribute twice does not have any
-	 * negative impact, so it is recommended to use this method in any feature that uses roots attributes.
-	 */ registerRootAttribute(key) {
-        if (this._registeredRootsAttributesKeys.has(key)) {
-            return;
-        }
-        this._registeredRootsAttributesKeys.add(key);
-        this.editing.model.schema.extend('$root', {
-            allowAttributes: key
-        });
-    }
     /**
 	 * Switches given editor root to the read-only mode.
 	 *
@@ -860,17 +829,21 @@ import { isElement as isElement$1 } from 'es-toolkit/compat';
             locksForGivenRoot.delete(lockId);
         }
     }
-    static create(sourceElementsOrDataOrConfig, config = {}) {
-        return new Promise((resolve)=>{
-            const editor = new this(sourceElementsOrDataOrConfig, config);
-            resolve(editor.initPlugins().then(()=>editor.ui.init()).then(()=>{
-                const initialData = extractRootsConfigField(editor.config.get('roots'), 'initialData');
-                // This is checked directly before setting the initial data,
-                // as plugins may change `EditorConfig#initialData` value.
-                editor._verifyRootsWithInitialData(initialData);
-                return editor.data.init(initialData);
-            }).then(()=>editor.fire('ready')).then(()=>editor));
-        });
+    static async create(sourceElementsOrDataOrConfig, config = {}) {
+        const editor = new this(sourceElementsOrDataOrConfig, config);
+        await editor.initPlugins();
+        // Roots are created in the editor constructor (before plugins are loaded), but the schema is only fully
+        // built after plugins register their items during init(). Custom root element names (e.g. registered by a
+        // plugin) may not exist in the schema at construction time, so we defer this check until here.
+        verifyRootElements(editor);
+        await editor.ui.init();
+        const initialData = extractRootsConfigField(editor.config.get('roots'), 'initialData');
+        // This is checked directly before setting the initial data,
+        // as plugins may change `EditorConfig#initialData` value.
+        editor._verifyRootsWithInitialData(initialData);
+        await editor.data.init(initialData);
+        editor.fire('ready');
+        return editor;
     }
     /**
 	 * @internal