@ckeditor/ckeditor5-engine 37.0.0-alpha.2 → 37.0.0-rc.0

package/src/model/node.js

@@ -63,7 +63,7 @@ export default class Node extends TypeCheckable {
         return null;
     }
     /**
-     * Index of this node in it's parent or `null` if the node has no parent.
+     * Index of this node in its parent or `null` if the node has no parent.
      *
      * Accessing this property throws an error if this node's parent element does not contain it.
      * This means that model tree got broken.
@@ -79,8 +79,8 @@ export default class Node extends TypeCheckable {
         return pos;
     }
     /**
-     * Offset at which this node starts in it's parent. It is equal to the sum of {@link #offsetSize offsetSize}
-     * of all it's previous siblings. Equals to `null` if node has no parent.
+     * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
+     * of all its previous siblings. Equals to `null` if node has no parent.
      *
      * Accessing this property throws an error if this node's parent element does not contain it.
      * This means that model tree got broken.
@@ -142,10 +142,14 @@ export default class Node extends TypeCheckable {
         return root;
     }
     /**
-     * Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).
+     * Returns `true` if the node is inside a document root that is attached to the document.
      */
     isAttached() {
-        return this.root.is('rootElement');
+        // If the node has no parent it means that it is a root.
+        // But this is not a `RootElement`, so it means that it is not attached.
+        //
+        // If this is not the root, check if this element's root is attached.
+        return this.parent === null ? false : this.root.isAttached();
     }
     /**
      * Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node,

package/src/model/operation/attributeoperation.d.ts

@@ -89,7 +89,7 @@ export default class AttributeOperation extends Operation {
      */
     static get className(): string;
     /**
-     * Creates `AttributeOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `AttributeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/attributeoperation.js

@@ -131,7 +131,7 @@ export default class AttributeOperation extends Operation {
         return 'AttributeOperation';
     }
     /**
-     * Creates `AttributeOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `AttributeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/insertoperation.d.ts

@@ -76,7 +76,7 @@ export default class InsertOperation extends Operation {
      */
     static get className(): string;
     /**
-     * Creates `InsertOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `InsertOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/insertoperation.js

@@ -105,7 +105,7 @@ export default class InsertOperation extends Operation {
         return 'InsertOperation';
     }
     /**
-     * Creates `InsertOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `InsertOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/mergeoperation.d.ts

@@ -86,7 +86,7 @@ export default class MergeOperation extends Operation {
      */
     static get className(): string;
     /**
-     * Creates `MergeOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `MergeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/mergeoperation.js

@@ -141,7 +141,7 @@ export default class MergeOperation extends Operation {
         return 'MergeOperation';
     }
     /**
-     * Creates `MergeOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `MergeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/moveoperation.d.ts

@@ -82,7 +82,7 @@ export default class MoveOperation extends Operation {
      */
     static get className(): string;
     /**
-     * Creates `MoveOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `MoveOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/moveoperation.js

@@ -142,7 +142,7 @@ export default class MoveOperation extends Operation {
         return 'MoveOperation';
     }
     /**
-     * Creates `MoveOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `MoveOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/operation.d.ts

@@ -80,7 +80,7 @@ export default abstract class Operation {
      */
     static get className(): string;
     /**
-     * Creates Operation object from deserilized object, i.e. from parsed JSON string.
+     * Creates `Operation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param doc Document on which this operation will be applied.

package/src/model/operation/operation.js

@@ -51,7 +51,7 @@ export default class Operation {
         return 'Operation';
     }
     /**
-     * Creates Operation object from deserilized object, i.e. from parsed JSON string.
+     * Creates `Operation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param doc Document on which this operation will be applied.

package/src/model/operation/operationfactory.js

@@ -13,6 +13,7 @@ import NoOperation from './nooperation';
 import Operation from './operation';
 import RenameOperation from './renameoperation';
 import RootAttributeOperation from './rootattributeoperation';
+import RootOperation from './rootoperation';
 import SplitOperation from './splitoperation';
 import MergeOperation from './mergeoperation';
 const operations = {};
@@ -24,6 +25,7 @@ operations[NoOperation.className] = NoOperation;
 operations[Operation.className] = Operation;
 operations[RenameOperation.className] = RenameOperation;
 operations[RootAttributeOperation.className] = RootAttributeOperation;
+operations[RootOperation.className] = RootOperation;
 operations[SplitOperation.className] = SplitOperation;
 operations[MergeOperation.className] = MergeOperation;
 /**

package/src/model/operation/rootattributeoperation.d.ts

@@ -21,24 +21,20 @@ import type RootElement from '../rootelement';
 export default class RootAttributeOperation extends Operation {
     /**
      * Root element to change.
-     *
-     * @readonly
      */
-    root: RootElement;
+    readonly root: RootElement;
     /**
      * Key of an attribute to change or remove.
-     *
-     * @readonly
      */
-    key: string;
+    readonly key: string;
     /**
-     * Old value of the attribute with given key or `null` if adding a new attribute.
+     * Old value of the attribute with given key or `null`, if attribute was not set before.
      *
      * @readonly
      */
     oldValue: unknown;
     /**
-     * New value to set for the attribute. If `null`, then the operation just removes the attribute.
+     * New value of the attribute with given key or `null`, if operation should remove attribute.
      *
      * @readonly
      */
@@ -49,8 +45,8 @@ export default class RootAttributeOperation extends Operation {
      * @see module:engine/model/operation/attributeoperation~AttributeOperation
      * @param root Root element to change.
      * @param key Key of an attribute to change or remove.
-     * @param oldValue Old value of the attribute with given key or `null` if adding a new attribute.
-     * @param newValue New value to set for the attribute. If `null`, then the operation just removes the attribute.
+     * @param oldValue Old value of the attribute with given key or `null`, if attribute was not set before.
+     * @param newValue New value of the attribute with given key or `null`, if operation should remove attribute.
      * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation
      * can be applied or `null` if the operation operates on detached (non-document) tree.
      */
@@ -88,7 +84,7 @@ export default class RootAttributeOperation extends Operation {
      */
     static get className(): string;
     /**
-     * Creates RootAttributeOperation object from deserilized object, i.e. from parsed JSON string.
+     * Creates `RootAttributeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/rootattributeoperation.js

@@ -24,8 +24,8 @@ export default class RootAttributeOperation extends Operation {
      * @see module:engine/model/operation/attributeoperation~AttributeOperation
      * @param root Root element to change.
      * @param key Key of an attribute to change or remove.
-     * @param oldValue Old value of the attribute with given key or `null` if adding a new attribute.
-     * @param newValue New value to set for the attribute. If `null`, then the operation just removes the attribute.
+     * @param oldValue Old value of the attribute with given key or `null`, if attribute was not set before.
+     * @param newValue New value of the attribute with given key or `null`, if operation should remove attribute.
      * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation
      * can be applied or `null` if the operation operates on detached (non-document) tree.
      */
@@ -33,8 +33,8 @@ export default class RootAttributeOperation extends Operation {
         super(baseVersion);
         this.root = root;
         this.key = key;
-        this.oldValue = oldValue;
-        this.newValue = newValue;
+        this.oldValue = oldValue === undefined ? null : oldValue;
+        this.newValue = newValue === undefined ? null : newValue;
     }
     /**
      * @inheritDoc
@@ -82,7 +82,7 @@ export default class RootAttributeOperation extends Operation {
         }
         if (this.oldValue !== null && this.root.getAttribute(this.key) !== this.oldValue) {
             /**
-             * The attribute which should be removed does not exists for the given node.
+             * The attribute which should be removed does not exist for the given node.
              *
              * @error rootattribute-operation-wrong-old-value
              * @param root
@@ -129,7 +129,7 @@ export default class RootAttributeOperation extends Operation {
         return 'RootAttributeOperation';
     }
     /**
-     * Creates RootAttributeOperation object from deserilized object, i.e. from parsed JSON string.
+     * Creates `RootAttributeOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/rootoperation.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/model/operation/rootoperation
+ */
+import Operation from './operation';
+import type Document from '../document';
+/**
+ * Operation that creates (or attaches) or detaches a root element.
+ */
+export default class RootOperation extends Operation {
+    /**
+     * Root name to create or detach.
+     */
+    readonly rootName: string;
+    /**
+     * Root element name.
+     */
+    readonly elementName: string;
+    /**
+     * Specifies whether the operation adds (`true`) or detaches the root (`false`).
+     */
+    readonly isAdd: boolean;
+    /**
+     * Document which owns the root.
+     */
+    private readonly _document;
+    /**
+     * Creates an operation that creates or removes a root element.
+     *
+     * @param rootName Root name to create or detach.
+     * @param elementName Root element name.
+     * @param isAdd Specifies whether the operation adds (`true`) or detaches the root (`false`).
+     * @param document Document which owns the root.
+     * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation can be applied.
+     */
+    constructor(rootName: string, elementName: string, isAdd: boolean, document: Document, baseVersion: number);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'addRoot' | 'detachRoot';
+    /**
+     * @inheritDoc
+     */
+    clone(): RootOperation;
+    /**
+     * @inheritDoc
+     */
+    getReversed(): RootOperation;
+    /**
+     * @inheritDoc
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `RootOperation` object from deserialized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): RootOperation;
+}

package/src/model/operation/rootoperation.js

@@ -0,0 +1,108 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/model/operation/rootoperation
+ */
+import Operation from './operation';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * Operation that creates (or attaches) or detaches a root element.
+ */
+export default class RootOperation extends Operation {
+    /**
+     * Creates an operation that creates or removes a root element.
+     *
+     * @param rootName Root name to create or detach.
+     * @param elementName Root element name.
+     * @param isAdd Specifies whether the operation adds (`true`) or detaches the root (`false`).
+     * @param document Document which owns the root.
+     * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation can be applied.
+     */
+    constructor(rootName, elementName, isAdd, document, baseVersion) {
+        super(baseVersion);
+        this.rootName = rootName;
+        this.elementName = elementName;
+        this.isAdd = isAdd;
+        this._document = document;
+        // Make sure that the root exists ASAP, this is important for RTC.
+        // If the root was dynamically added, there will be more operations that operate on/in this root.
+        // These operations will require root element instance (in operation property or in position instance).
+        // If the root is not created ahead of time, instantiating such operations may fail.
+        if (!this._document.getRoot(this.rootName)) {
+            const root = this._document.createRoot(this.elementName, this.rootName);
+            root._isAttached = false;
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        return this.isAdd ? 'addRoot' : 'detachRoot';
+    }
+    /**
+     * @inheritDoc
+     */
+    clone() {
+        return new RootOperation(this.rootName, this.elementName, this.isAdd, this._document, this.baseVersion);
+    }
+    /**
+     * @inheritDoc
+     */
+    getReversed() {
+        return new RootOperation(this.rootName, this.elementName, !this.isAdd, this._document, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     */
+    _validate() {
+        // Keep in mind that at this point the root will always exist as it was created in the `constructor()`, even for detach operation.
+        const root = this._document.getRoot(this.rootName);
+        if (root.isAttached() && this.isAdd) {
+            /**
+             * Trying to attach a root that is already attached.
+             *
+             * @error root-operation-root-attached
+             */
+            throw new CKEditorError('root-operation-root-attached', this);
+        }
+        else if (!root.isAttached() && !this.isAdd) {
+            /**
+             * Trying to detach a root that is already detached.
+             *
+             * @error root-operation-root-detached
+             */
+            throw new CKEditorError('root-operation-root-detached', this);
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    _execute() {
+        this._document.getRoot(this.rootName)._isAttached = this.isAdd;
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        delete json._document;
+        return json;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'RootOperation';
+    }
+    /**
+     * Creates `RootOperation` object from deserialized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json, document) {
+        return new RootOperation(json.rootName, json.elementName, json.isAdd, document, json.baseVersion);
+    }
+}

package/src/model/operation/splitoperation.d.ts

@@ -95,7 +95,7 @@ export default class SplitOperation extends Operation {
      */
     static getInsertionPosition(splitPosition: Position): Position;
     /**
-     * Creates `SplitOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `SplitOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/splitoperation.js

@@ -166,7 +166,7 @@ export default class SplitOperation extends Operation {
         return new Position(splitPosition.root, path, 'toPrevious');
     }
     /**
-     * Creates `SplitOperation` object from deserilized object, i.e. from parsed JSON string.
+     * Creates `SplitOperation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
      * @param document Document on which this operation will be applied.

package/src/model/operation/transform.js

@@ -8,6 +8,7 @@ import RenameOperation from './renameoperation';
 import MarkerOperation from './markeroperation';
 import MoveOperation from './moveoperation';
 import RootAttributeOperation from './rootattributeoperation';
+import RootOperation from './rootoperation';
 import MergeOperation from './mergeoperation';
 import SplitOperation from './splitoperation';
 import NoOperation from './nooperation';
@@ -1640,6 +1641,13 @@ setTransformation(RootAttributeOperation, RootAttributeOperation, (a, b, context
     return [a];
 });
 // -----------------------
+setTransformation(RootOperation, RootOperation, (a, b, context) => {
+    if (a.rootName === b.rootName && a.isAdd === b.isAdd && !context.bWasUndone) {
+        return [new NoOperation(0)];
+    }
+    return [a];
+});
+// -----------------------
 setTransformation(SplitOperation, InsertOperation, (a, b) => {
     // The default case.
     //

package/src/model/rootelement.d.ts

@@ -19,6 +19,10 @@ export default class RootElement extends Element {
      * Document that is an owner of this root.
      */
     private readonly _document;
+    /**
+     * @internal
+     */
+    _isAttached: boolean;
     /**
      * Creates root element.
      *
@@ -32,7 +36,17 @@ export default class RootElement extends Element {
      */
     get document(): Document;
     /**
-     * Converts `RootElement` instance to `string` containing it's name.
+     * Informs if the root element is currently attached to the document, or not.
+     *
+     * A detached root is equivalent to being removed and cannot contain any children or markers.
+     *
+     * By default, a newly added root is attached. It can be detached using
+     * {@link module:engine/model/writer~Writer#detachRoot `Writer#detachRoot`}. A detached root can be re-attached again using
+     * {@link module:engine/model/writer~Writer#addRoot `Writer#addRoot`}.
+     */
+    isAttached(): boolean;
+    /**
+     * Converts `RootElement` instance to `string` containing its name.
      *
      * @returns `RootElement` instance converted to `string`.
      */

package/src/model/rootelement.js

@@ -19,6 +19,10 @@ export default class RootElement extends Element {
      */
     constructor(document, name, rootName = 'main') {
         super(name);
+        /**
+         * @internal
+         */
+        this._isAttached = true;
         this._document = document;
         this.rootName = rootName;
     }
@@ -29,7 +33,19 @@ export default class RootElement extends Element {
         return this._document;
     }
     /**
-     * Converts `RootElement` instance to `string` containing it's name.
+     * Informs if the root element is currently attached to the document, or not.
+     *
+     * A detached root is equivalent to being removed and cannot contain any children or markers.
+     *
+     * By default, a newly added root is attached. It can be detached using
+     * {@link module:engine/model/writer~Writer#detachRoot `Writer#detachRoot`}. A detached root can be re-attached again using
+     * {@link module:engine/model/writer~Writer#addRoot `Writer#addRoot`}.
+     */
+    isAttached() {
+        return this._isAttached;
+    }
+    /**
+     * Converts `RootElement` instance to `string` containing its name.
      *
      * @returns `RootElement` instance converted to `string`.
      */

package/src/model/writer.d.ts

@@ -6,6 +6,7 @@ import DocumentFragment from './documentfragment';
 import Element from './element';
 import Position, { type PositionOffset, type PositionStickiness } from './position';
 import Range from './range';
+import RootElement from './rootelement';
 import Text from './text';
 import type { Marker } from './markercollection';
 import type { default as Selection, PlaceOrOffset, Selectable } from './selection';
@@ -366,7 +367,7 @@ export default class Writer {
      * writer.move( sourceRange, image, 'after' );
      * ```
      *
-     * These parameters works the same way as {@link #createPositionAt `writer.createPositionAt()`}.
+     * These parameters work the same way as {@link #createPositionAt `writer.createPositionAt()`}.
      *
      * Note that items can be moved only within the same tree. It means that you can move items within the same root
      * (element or document fragment) or between {@link module:engine/model/document~Document#roots documents roots},
@@ -623,6 +624,33 @@ export default class Writer {
      * @param markerOrName Marker or marker name to remove.
      */
     removeMarker(markerOrName: string | Marker): void;
+    /**
+     * Adds a new root to the document (or re-attaches a {@link #detachRoot detached root}).
+     *
+     * Throws an error, if trying to add a root that is already added and attached.
+     *
+     * @param rootName Name of the added root.
+     * @param elementName The element name. Defaults to `'$root'` which also has some basic schema defined
+     * (e.g. `$block` elements are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
+     * @returns The added root element.
+     */
+    addRoot(rootName: string, elementName?: string): RootElement;
+    /**
+     * Detaches the root from the document.
+     *
+     * All content and markers are removed from the root upon detaching. New content and new markers cannot be added to the root, as long
+     * as it is detached.
+     *
+     * A root cannot be fully removed from the document, it can be only detached. A root is permanently removed only after you
+     * re-initialize the editor and do not specify the root in the initial data.
+     *
+     * A detached root can be re-attached using {@link #addRoot}.
+     *
+     * Throws an error if the root does not exist or the root is already detached.
+     *
+     * @param rootOrName Name of the detached root.
+     */
+    detachRoot(rootOrName: string | RootElement): void;
     /**
      * Sets the document's selection (ranges and direction) to the specified location based on the given
      * {@link module:engine/model/selection~Selectable selectable} or creates an empty selection if no arguments were passed.