@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

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

@@ -0,0 +1,96 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/moveoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import type { Selectable } from '../selection.js';
+import type Document from '../document.js';
+/**
+ * Operation to move a range of {@link module:engine/model/item~Item model items}
+ * to given {@link module:engine/model/position~Position target position}.
+ */
+export default class MoveOperation extends Operation {
+    /**
+     * Position before the first {@link module:engine/model/item~Item model item} to move.
+     */
+    sourcePosition: Position;
+    /**
+     * Offset size of moved range.
+     */
+    howMany: number;
+    /**
+     * Position at which moved nodes will be inserted.
+     */
+    targetPosition: Position;
+    /**
+     * Creates a move operation.
+     *
+     * @param sourcePosition Position before the first {@link module:engine/model/item~Item model item} to move.
+     * @param howMany Offset size of moved range. Moved range will start from `sourcePosition` and end at
+     * `sourcePosition` with offset shifted by `howMany`.
+     * @param targetPosition Position at which moved nodes will be inserted.
+     * @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.
+     */
+    constructor(sourcePosition: Position, howMany: number, targetPosition: Position, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'move' | 'remove' | 'reinsert';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MoveOperation;
+    /**
+     * Returns the start position of the moved range after it got moved. This may be different than
+     * {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition} in some cases, i.e. when a range is moved
+     * inside the same parent but {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition targetPosition}
+     * is after {@link module:engine/model/operation/moveoperation~MoveOperation#sourcePosition sourcePosition}.
+     *
+     * ```
+     *  vv              vv
+     * abcdefg ===> adefbcg
+     *      ^          ^
+     *      targetPos  movedRangeStart
+     *      offset 6   offset 4
+     *```
+     */
+    getMovedRangeStart(): Position;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): 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.
+     */
+    static fromJSON(json: any, document: Document): MoveOperation;
+}

package/src/model/operation/moveoperation.js

@@ -0,0 +1,164 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/moveoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import Range from '../range.js';
+import { _move } from './utils.js';
+import { CKEditorError, compareArrays } from '@ckeditor/ckeditor5-utils';
+// @if CK_DEBUG_ENGINE // const ModelRange = require( '../range' ).default;
+/**
+ * Operation to move a range of {@link module:engine/model/item~Item model items}
+ * to given {@link module:engine/model/position~Position target position}.
+ */
+export default class MoveOperation extends Operation {
+    /**
+     * Creates a move operation.
+     *
+     * @param sourcePosition Position before the first {@link module:engine/model/item~Item model item} to move.
+     * @param howMany Offset size of moved range. Moved range will start from `sourcePosition` and end at
+     * `sourcePosition` with offset shifted by `howMany`.
+     * @param targetPosition Position at which moved nodes will be inserted.
+     * @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.
+     */
+    constructor(sourcePosition, howMany, targetPosition, baseVersion) {
+        super(baseVersion);
+        this.sourcePosition = sourcePosition.clone();
+        // `'toNext'` because `sourcePosition` is a bit like a start of the moved range.
+        this.sourcePosition.stickiness = 'toNext';
+        this.howMany = howMany;
+        this.targetPosition = targetPosition.clone();
+        this.targetPosition.stickiness = 'toNone';
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        if (this.targetPosition.root.rootName == '$graveyard') {
+            return 'remove';
+        }
+        else if (this.sourcePosition.root.rootName == '$graveyard') {
+            return 'reinsert';
+        }
+        return 'move';
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        return [
+            Range._createFromPositionAndShift(this.sourcePosition, this.howMany),
+            Range._createFromPositionAndShift(this.targetPosition, 0)
+        ];
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        return new MoveOperation(this.sourcePosition, this.howMany, this.targetPosition, this.baseVersion);
+    }
+    /**
+     * Returns the start position of the moved range after it got moved. This may be different than
+     * {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition} in some cases, i.e. when a range is moved
+     * inside the same parent but {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition targetPosition}
+     * is after {@link module:engine/model/operation/moveoperation~MoveOperation#sourcePosition sourcePosition}.
+     *
+     * ```
+     *  vv              vv
+     * abcdefg ===> adefbcg
+     *      ^          ^
+     *      targetPos  movedRangeStart
+     *      offset 6   offset 4
+     *```
+     */
+    getMovedRangeStart() {
+        return this.targetPosition._getTransformedByDeletion(this.sourcePosition, this.howMany);
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        const newTargetPosition = this.sourcePosition._getTransformedByInsertion(this.targetPosition, this.howMany);
+        return new MoveOperation(this.getMovedRangeStart(), this.howMany, newTargetPosition, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate() {
+        const sourceElement = this.sourcePosition.parent;
+        const targetElement = this.targetPosition.parent;
+        const sourceOffset = this.sourcePosition.offset;
+        const targetOffset = this.targetPosition.offset;
+        // Validate whether move operation has correct parameters.
+        // Validation is pretty complex but move operation is one of the core ways to manipulate the document state.
+        // We expect that many errors might be connected with one of scenarios described below.
+        if (sourceOffset + this.howMany > sourceElement.maxOffset) {
+            /**
+             * The nodes which should be moved do not exist.
+             *
+             * @error move-operation-nodes-do-not-exist
+             */
+            throw new CKEditorError('move-operation-nodes-do-not-exist', this);
+        }
+        else if (sourceElement === targetElement && sourceOffset < targetOffset && targetOffset < sourceOffset + this.howMany) {
+            /**
+             * Trying to move a range of nodes into the middle of that range.
+             *
+             * @error move-operation-range-into-itself
+             */
+            throw new CKEditorError('move-operation-range-into-itself', this);
+        }
+        else if (this.sourcePosition.root == this.targetPosition.root) {
+            if (compareArrays(this.sourcePosition.getParentPath(), this.targetPosition.getParentPath()) == 'prefix') {
+                const i = this.sourcePosition.path.length - 1;
+                if (this.targetPosition.path[i] >= sourceOffset && this.targetPosition.path[i] < sourceOffset + this.howMany) {
+                    /**
+                     * Trying to move a range of nodes into one of nodes from that range.
+                     *
+                     * @error move-operation-node-into-itself
+                     */
+                    throw new CKEditorError('move-operation-node-into-itself', this);
+                }
+            }
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        _move(Range._createFromPositionAndShift(this.sourcePosition, this.howMany), this.targetPosition);
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.sourcePosition = this.sourcePosition.toJSON();
+        json.targetPosition = this.targetPosition.toJSON();
+        return json;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'MoveOperation';
+    }
+    /**
+     * 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.
+     */
+    static fromJSON(json, document) {
+        const sourcePosition = Position.fromJSON(json.sourcePosition, document);
+        const targetPosition = Position.fromJSON(json.targetPosition, document);
+        return new this(sourcePosition, json.howMany, targetPosition, json.baseVersion);
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/nooperation
+ */
+import Operation from './operation.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Operation which is doing nothing ("empty operation", "do-nothing operation", "noop"). This is an operation,
+ * which when executed does not change the tree model. It still has some parameters defined for transformation purposes.
+ *
+ * In most cases this operation is a result of transforming operations. When transformation returns
+ * {@link module:engine/model/operation/nooperation~NoOperation} it means that changes done by the transformed operation
+ * have already been applied.
+ */
+export default class NoOperation extends Operation {
+    get type(): 'noop';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): NoOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /** @internal */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+}

package/src/model/operation/nooperation.js

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/nooperation
+ */
+import Operation from './operation.js';
+/**
+ * Operation which is doing nothing ("empty operation", "do-nothing operation", "noop"). This is an operation,
+ * which when executed does not change the tree model. It still has some parameters defined for transformation purposes.
+ *
+ * In most cases this operation is a result of transforming operations. When transformation returns
+ * {@link module:engine/model/operation/nooperation~NoOperation} it means that changes done by the transformed operation
+ * have already been applied.
+ */
+export default class NoOperation extends Operation {
+    get type() {
+        return 'noop';
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        return null;
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        return new NoOperation(this.baseVersion);
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        return new NoOperation(this.baseVersion + 1);
+    }
+    /** @internal */
+    _execute() {
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'NoOperation';
+    }
+}

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

@@ -0,0 +1,96 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/operation
+ */
+import type Batch from '../batch.js';
+import type Document from '../document.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Abstract base operation class.
+ */
+export default abstract class Operation {
+    /**
+     * {@link module:engine/model/document~Document#version} on which operation can be applied. If you try to
+     * {@link module:engine/model/model~Model#applyOperation apply} operation with different base version than the
+     * {@link module:engine/model/document~Document#version document version} the
+     * {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
+     */
+    baseVersion: number | null;
+    /**
+     * Defines whether operation is executed on attached or detached {@link module:engine/model/item~Item items}.
+     */
+    readonly isDocumentOperation: boolean;
+    /**
+     * {@link module:engine/model/batch~Batch Batch} to which the operation is added or `null` if the operation is not
+     * added to any batch yet.
+     */
+    batch: Batch | null;
+    /**
+     * Operation type.
+     */
+    abstract readonly type: string;
+    /**
+     * Base operation constructor.
+     *
+     * @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.
+     */
+    constructor(baseVersion: number | null);
+    /**
+     * A selectable that will be affected by the operation after it is executed.
+     *
+     * The exact returned parameter differs between operation types.
+     */
+    abstract get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     *
+     * @returns Clone of this operation.
+     */
+    abstract clone(): Operation;
+    /**
+     * Creates and returns a reverse operation. Reverse operation when executed right after
+     * the original operation will bring back tree model state to the point before the original
+     * operation execution. In other words, it reverses changes done by the original operation.
+     *
+     * Keep in mind that tree model state may change since executing the original operation,
+     * so reverse operation will be "outdated". In that case you will need to transform it by
+     * all operations that were executed after the original operation.
+     *
+     * @returns Reversed operation.
+     */
+    abstract getReversed(): Operation;
+    /**
+     * Executes the operation - modifications described by the operation properties will be applied to the model tree.
+     *
+     * @internal
+     */
+    abstract _execute(): void;
+    /**
+     * Checks whether the operation's parameters are correct and the operation can be correctly executed. Throws
+     * an error if operation is not valid.
+     *
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * Custom toJSON method to solve child-parent circular dependencies.
+     *
+     * @returns Clone of this object with the operation property replaced with string.
+     */
+    toJSON(): unknown;
+    /**
+     * Name of the operation class used for serialization.
+     */
+    static get className(): 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.
+     */
+    static fromJSON(json: any, document: Document): Operation;
+}

package/src/model/operation/operation.js

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * Abstract base operation class.
+ */
+export default class Operation {
+    /**
+     * Base operation constructor.
+     *
+     * @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.
+     */
+    constructor(baseVersion) {
+        this.baseVersion = baseVersion;
+        this.isDocumentOperation = this.baseVersion !== null;
+        this.batch = null;
+    }
+    /**
+     * Checks whether the operation's parameters are correct and the operation can be correctly executed. Throws
+     * an error if operation is not valid.
+     *
+     * @internal
+     */
+    _validate() {
+    }
+    /**
+     * Custom toJSON method to solve child-parent circular dependencies.
+     *
+     * @returns Clone of this object with the operation property replaced with string.
+     */
+    toJSON() {
+        // This method creates only a shallow copy, all nested objects should be defined separately.
+        // See https://github.com/ckeditor/ckeditor5-engine/issues/1477.
+        const json = Object.assign({}, this);
+        json.__className = this.constructor.className;
+        // Remove reference to the parent `Batch` to avoid circular dependencies.
+        delete json.batch;
+        // Only document operations are shared with other clients so it is not necessary to keep this information.
+        delete json.isDocumentOperation;
+        return json;
+    }
+    /**
+     * Name of the operation class used for serialization.
+     */
+    static get className() {
+        return 'Operation';
+    }
+    /**
+     * 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.
+     */
+    static fromJSON(json, document) {
+        return new this(json.baseVersion);
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import Operation from './operation.js';
+import type Document from '../document.js';
+/**
+ * A factory class for creating operations.
+ */
+export default abstract class OperationFactory {
+    /**
+     * Creates an operation instance from a JSON object (parsed JSON string).
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): Operation;
+}

package/src/model/operation/operationfactory.js

@@ -0,0 +1,44 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/operationfactory
+ */
+import AttributeOperation from './attributeoperation.js';
+import InsertOperation from './insertoperation.js';
+import MarkerOperation from './markeroperation.js';
+import MoveOperation from './moveoperation.js';
+import NoOperation from './nooperation.js';
+import Operation from './operation.js';
+import RenameOperation from './renameoperation.js';
+import RootAttributeOperation from './rootattributeoperation.js';
+import RootOperation from './rootoperation.js';
+import SplitOperation from './splitoperation.js';
+import MergeOperation from './mergeoperation.js';
+const operations = {};
+operations[AttributeOperation.className] = AttributeOperation;
+operations[InsertOperation.className] = InsertOperation;
+operations[MarkerOperation.className] = MarkerOperation;
+operations[MoveOperation.className] = MoveOperation;
+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;
+/**
+ * A factory class for creating operations.
+ */
+export default class OperationFactory {
+    /**
+     * Creates an operation instance from a JSON object (parsed JSON string).
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json, document) {
+        return operations[json.__className].fromJSON(json, document);
+    }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/renameoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import type Document from '../document.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Operation to change element's name.
+ *
+ * Using this class you can change element's name.
+ */
+export default class RenameOperation extends Operation {
+    /**
+     * Position before an element to change.
+     */
+    position: Position;
+    /**
+     * Current name of the element.
+     */
+    oldName: string;
+    /**
+     * New name for the element.
+     */
+    newName: string;
+    /**
+     * Creates an operation that changes element's name.
+     *
+     * @param position Position before an element to change.
+     * @param oldName Current name of the element.
+     * @param newName New name for the element.
+     * @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.
+     */
+    constructor(position: Position, oldName: string, newName: string, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'rename';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     *
+     * @returns Clone of this operation.
+     */
+    clone(): RenameOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `RenameOperation` 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): RenameOperation;
+}