@ckeditor/ckeditor5-editor-multi-root 48.1.1 → 48.2.0-alpha.1

package/dist/multirooteditor.d.ts

@@ -5,7 +5,7 @@
 /**
  * @module editor-multi-root/multirooteditor
  */
-import { Editor, type EditorConfig, type RootConfig, type EditorRootAttributes } from '@ckeditor/ckeditor5-core';
+import { Editor, type EditorConfig, type RootConfig, type EditorRootAttributes, type ViewRootElementDefinition } from '@ckeditor/ckeditor5-core';
 import { type DecoratedMethodEvent } from '@ckeditor/ckeditor5-utils';
 import { MultiRootEditorUI } from './multirooteditorui.js';
 import { type ModelRootElement } from '@ckeditor/ckeditor5-engine';
@@ -236,16 +236,23 @@ export declare class MultiRootEditor extends Editor {
      */
     detachRoot(rootName: string, isUndoable?: boolean): void;
     /**
-     * Creates and returns a new DOM editable element for the given root element.
+     * Creates and returns a DOM editable element for the given root element.
      *
-     * The new DOM editable is attached to the model root and can be used to modify the root content.
+     * The DOM editable is attached to the model root and can be used to modify the root content.
+     *
+     * When `options.element` is an existing `HTMLElement`, the method uses it as-is and returns
+     * the same element. Otherwise a fresh DOM element is created from `options.element`
+     * (descriptor or tag name) — or a default `<div>` when the option is omitted — and the caller
+     * is expected to append the returned element to the DOM.
      *
      * @label OPTIONS
      * @param root Root for which the editable element should be created.
      * @param options.placeholder Placeholder for the editable element. If not set, placeholder value from the
      * {@link module:core/editor/editorconfig~RootConfig#placeholder root configuration} will be used (if it was provided).
      * @param options.label The accessible label text describing the editable to the assistive technologies.
-     * @returns The created DOM element. Append it in a desired place in your application.
+     * @param options.element Description of the editable element to create, or an existing `HTMLElement` to use as-is.
+     * See {@link ~RootEditableOptions#element} for accepted forms and the real-time collaboration caveat.
+     * @returns The DOM element for the editable.
      */
     createEditable(root: ModelRootElement, options?: RootEditableOptions): HTMLElement;
     /**
@@ -733,9 +740,13 @@ export type AddRootOptions = {
  */
 export interface AddRootRootConfig extends RootConfig {
     /**
-     * Passing a DOM element to {@link ~MultiRootEditor#addRoot:ROOT_CONFIG `addRoot( rootName, options )`} is not supported.
+     * A description of the editable root element to create. May be a tag name string (e.g. `'h1'`) or a
+     * {@link module:core/editor/editorconfig~ViewRootElementDefinition} object.
+     *
+     * Passing an existing DOM element is not supported - `addRoot()` only registers the model root;
+     * the DOM editable is created later by {@link ~MultiRootEditor#createEditable `createEditable()`}.
      */
-    element?: undefined;
+    element?: string | ViewRootElementDefinition;
     /**
      * Whether creating the root can be undone (using the undo feature) or not.
      */
@@ -758,4 +769,22 @@ export interface RootEditableOptions {
      * The accessible label text describing the editable to the assistive technologies.
      */
     label?: string;
+    /**
+     * A description of the editable root element to create, or an existing DOM element to use.
+     *
+     * Accepted forms:
+     *
+     * * A tag name string (e.g. `'h1'`).
+     * * A {@link module:core/editor/editorconfig~ViewRootElementDefinition} object.
+     * * An existing `HTMLElement`. The element is used as-is — `createEditable()` returns the same
+     *   element instead of creating a new one, so callers do not need to append it to the DOM.
+     *
+     * When omitted, a default `<div>` is created.
+     *
+     * **Note**: an `HTMLElement` value is local to this client. It cannot be replicated through
+     * real-time collaboration, so it is not persisted with the root. Other clients calling
+     * `createEditable()` for the same root receive a fresh element built from the canonical
+     * descriptor (or the default `<div>`), unless they pass their own `HTMLElement` as well.
+     */
+    element?: string | ViewRootElementDefinition | HTMLElement;
 }

package/dist/multirooteditoruiview.d.ts

@@ -8,6 +8,7 @@
 import { EditorUIView, InlineEditableUIView, MenuBarView, ToolbarView } from '@ckeditor/ckeditor5-ui';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 import type { EditingView } from '@ckeditor/ckeditor5-engine';
+import type { ViewRootElementDefinition } from '@ckeditor/ckeditor5-core';
 /**
  * The multi-root editor UI view. It is a virtual view providing an inline
  * {@link module:editor-multi-root/multirooteditoruiview~MultiRootEditorUIView#editable} and a
@@ -53,7 +54,7 @@ export declare class MultiRootEditorUIView extends EditorUIView {
      * {@link module:ui/editableui/editableuiview~EditableUIView editable view} elements.
      */
     constructor(locale: Locale, editingView: EditingView, editableNames: Array<string>, options?: {
-        editableElements?: Record<string, HTMLElement>;
+        editableElements?: Record<string, HTMLElement | ViewRootElementDefinition>;
         shouldToolbarGroupWhenFull?: boolean;
         label?: string | Record<string, string>;
     });
@@ -68,7 +69,7 @@ export declare class MultiRootEditorUIView extends EditorUIView {
      * @param label The accessible editable label used by assistive technologies.
      * @returns The created editable instance.
      */
-    createEditable(editableName: string, editableElement?: HTMLElement, label?: string): InlineEditableUIView;
+    createEditable(editableName: string, editableElement?: HTMLElement | ViewRootElementDefinition, label?: string): InlineEditableUIView;
     /**
      * Destroys and removes the editable from the editor UI view.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-editor-multi-root",
-  "version": "48.1.1",
+  "version": "48.2.0-alpha.1",
   "description": "Multi-root editor implementation for CKEditor 5.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "CKSource (http://cksource.com/)",
@@ -25,10 +25,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "48.1.1",
-    "@ckeditor/ckeditor5-engine": "48.1.1",
-    "@ckeditor/ckeditor5-ui": "48.1.1",
-    "@ckeditor/ckeditor5-utils": "48.1.1",
+    "@ckeditor/ckeditor5-core": "48.2.0-alpha.1",
+    "@ckeditor/ckeditor5-engine": "48.2.0-alpha.1",
+    "@ckeditor/ckeditor5-ui": "48.2.0-alpha.1",
+    "@ckeditor/ckeditor5-utils": "48.2.0-alpha.1",
     "es-toolkit": "1.45.1"
   },
   "files": [