@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

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

@@ -0,0 +1,90 @@
+/**
+ * @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/insertoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import NodeList from '../nodelist.js';
+import { type NodeSet } from './utils.js';
+import type { Selectable } from '../selection.js';
+import type Document from '../document.js';
+/**
+ * Operation to insert one or more nodes at given position in the model.
+ */
+export default class InsertOperation extends Operation {
+    /**
+     * Position of insertion.
+     *
+     * @readonly
+     */
+    position: Position;
+    /**
+     * List of nodes to insert.
+     *
+     * @readonly
+     */
+    nodes: NodeList;
+    /**
+     * Flag deciding how the operation should be transformed. If set to `true`, nodes might get additional attributes
+     * during operational transformation. This happens when the operation insertion position is inside of a range
+     * where attributes have changed.
+     */
+    shouldReceiveAttributes: boolean;
+    /**
+     * Creates an insert operation.
+     *
+     * @param position Position of insertion.
+     * @param nodes The list of nodes to 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(position: Position, nodes: NodeSet, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'insert';
+    /**
+     * Total offset size of inserted nodes.
+     */
+    get howMany(): number;
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): InsertOperation;
+    /**
+     * 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 `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.
+     */
+    static fromJSON(json: any, document: Document): InsertOperation;
+}

package/src/model/operation/insertoperation.js

@@ -0,0 +1,135 @@
+/**
+ * @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/insertoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import NodeList from '../nodelist.js';
+import MoveOperation from './moveoperation.js';
+import { _insert, _normalizeNodes } from './utils.js';
+import Text from '../text.js';
+import Element from '../element.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * Operation to insert one or more nodes at given position in the model.
+ */
+export default class InsertOperation extends Operation {
+    /**
+     * Creates an insert operation.
+     *
+     * @param position Position of insertion.
+     * @param nodes The list of nodes to 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(position, nodes, baseVersion) {
+        super(baseVersion);
+        this.position = position.clone();
+        this.position.stickiness = 'toNone';
+        this.nodes = new NodeList(_normalizeNodes(nodes));
+        this.shouldReceiveAttributes = false;
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        return 'insert';
+    }
+    /**
+     * Total offset size of inserted nodes.
+     */
+    get howMany() {
+        return this.nodes.maxOffset;
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        return this.position.clone();
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        const nodes = new NodeList([...this.nodes].map(node => node._clone(true)));
+        const insert = new InsertOperation(this.position, nodes, this.baseVersion);
+        insert.shouldReceiveAttributes = this.shouldReceiveAttributes;
+        return insert;
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        const graveyard = this.position.root.document.graveyard;
+        const gyPosition = new Position(graveyard, [0]);
+        return new MoveOperation(this.position, this.nodes.maxOffset, gyPosition, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate() {
+        const targetElement = this.position.parent;
+        if (!targetElement || targetElement.maxOffset < this.position.offset) {
+            /**
+             * Insertion position is invalid.
+             *
+             * @error insert-operation-position-invalid
+             */
+            throw new CKEditorError('insert-operation-position-invalid', this);
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        // What happens here is that we want original nodes be passed to writer because we want original nodes
+        // to be inserted to the model. But in InsertOperation, we want to keep those nodes as they were added
+        // to the operation, not modified. For example, text nodes can get merged or cropped while Elements can
+        // get children. It is important that InsertOperation has the copy of original nodes in intact state.
+        const originalNodes = this.nodes;
+        this.nodes = new NodeList([...originalNodes].map(node => node._clone(true)));
+        _insert(this.position, originalNodes);
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.position = this.position.toJSON();
+        json.nodes = this.nodes.toJSON();
+        return json;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'InsertOperation';
+    }
+    /**
+     * 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.
+     */
+    static fromJSON(json, document) {
+        const children = [];
+        for (const child of json.nodes) {
+            if (child.name) {
+                // If child has name property, it is an Element.
+                children.push(Element.fromJSON(child));
+            }
+            else {
+                // Otherwise, it is a Text node.
+                children.push(Text.fromJSON(child));
+            }
+        }
+        const insert = new InsertOperation(Position.fromJSON(json.position, document), children, json.baseVersion);
+        insert.shouldReceiveAttributes = json.shouldReceiveAttributes;
+        return insert;
+    }
+}

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

@@ -0,0 +1,91 @@
+/**
+ * @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/markeroperation
+ */
+import Operation from './operation.js';
+import Range from '../range.js';
+import type Document from '../document.js';
+import type MarkerCollection from '../markercollection.js';
+import type { Selectable } from '../selection.js';
+export default class MarkerOperation extends Operation {
+    /**
+     * Marker name.
+     *
+     * @readonly
+     */
+    name: string;
+    /**
+     * Marker range before the change.
+     *
+     * @readonly
+     */
+    oldRange: Range | null;
+    /**
+     * Marker range after the change.
+     *
+     * @readonly
+     */
+    newRange: Range | null;
+    /**
+     * Specifies whether the marker operation affects the data produced by the data pipeline
+     * (is persisted in the editor's data).
+     *
+     * @readonly
+     */
+    affectsData: boolean;
+    /**
+     * Marker collection on which change should be executed.
+     */
+    private readonly _markers;
+    /**
+     * @param name Marker name.
+     * @param oldRange Marker range before the change.
+     * @param newRange Marker range after the change.
+     * @param markers Marker collection on which change should be executed.
+     * @param affectsData Specifies whether the marker operation affects the data produced by the data pipeline
+     * (is persisted in the editor's data).
+     * @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(name: string, oldRange: Range | null, newRange: Range | null, markers: MarkerCollection, affectsData: boolean, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'marker';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MarkerOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `MarkerOperation` 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): MarkerOperation;
+}

package/src/model/operation/markeroperation.js

@@ -0,0 +1,107 @@
+/**
+ * @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/markeroperation
+ */
+import Operation from './operation.js';
+import Range from '../range.js';
+export default class MarkerOperation extends Operation {
+    /**
+     * @param name Marker name.
+     * @param oldRange Marker range before the change.
+     * @param newRange Marker range after the change.
+     * @param markers Marker collection on which change should be executed.
+     * @param affectsData Specifies whether the marker operation affects the data produced by the data pipeline
+     * (is persisted in the editor's data).
+     * @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(name, oldRange, newRange, markers, affectsData, baseVersion) {
+        super(baseVersion);
+        this.name = name;
+        this.oldRange = oldRange ? oldRange.clone() : null;
+        this.newRange = newRange ? newRange.clone() : null;
+        this.affectsData = affectsData;
+        this._markers = markers;
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        return 'marker';
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        const ranges = [];
+        if (this.oldRange) {
+            ranges.push(this.oldRange.clone());
+        }
+        if (this.newRange) {
+            if (this.oldRange) {
+                ranges.push(...this.newRange.getDifference(this.oldRange));
+            }
+            else {
+                ranges.push(this.newRange.clone());
+            }
+        }
+        return ranges;
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        return new MarkerOperation(this.name, this.oldRange, this.newRange, this._markers, this.affectsData, this.baseVersion);
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        return new MarkerOperation(this.name, this.newRange, this.oldRange, this._markers, this.affectsData, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        if (this.newRange) {
+            this._markers._set(this.name, this.newRange, true, this.affectsData);
+        }
+        else {
+            this._markers._remove(this.name);
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    toJSON() {
+        const json = super.toJSON();
+        if (this.oldRange) {
+            json.oldRange = this.oldRange.toJSON();
+        }
+        if (this.newRange) {
+            json.newRange = this.newRange.toJSON();
+        }
+        delete json._markers;
+        return json;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'MarkerOperation';
+    }
+    /**
+     * Creates `MarkerOperation` 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 MarkerOperation(json.name, json.oldRange ? Range.fromJSON(json.oldRange, document) : null, json.newRange ? Range.fromJSON(json.newRange, document) : null, document.model.markers, json.affectsData, json.baseVersion);
+    }
+}

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

@@ -0,0 +1,100 @@
+/**
+ * @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/mergeoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import Range from '../range.js';
+import type Document from '../document.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Operation to merge two {@link module:engine/model/element~Element elements}.
+ *
+ * The merged element is the parent of {@link ~MergeOperation#sourcePosition} and it is merged into the parent of
+ * {@link ~MergeOperation#targetPosition}. All nodes from the merged element are moved to {@link ~MergeOperation#targetPosition}.
+ *
+ * The merged element is moved to the graveyard at {@link ~MergeOperation#graveyardPosition}.
+ */
+export default class MergeOperation extends Operation {
+    /**
+     * Position inside the merged element. All nodes from that element after that position will be moved to {@link #targetPosition}.
+     */
+    sourcePosition: Position;
+    /**
+     * Summary offset size of nodes which will be moved from the merged element to the new parent.
+     */
+    howMany: number;
+    /**
+     * Position which the nodes from the merged elements will be moved to.
+     */
+    targetPosition: Position;
+    /**
+     * Position in graveyard to which the merged element will be moved.
+     */
+    graveyardPosition: Position;
+    /**
+     * Creates a merge operation.
+     *
+     * @param sourcePosition Position inside the merged element. All nodes from that
+     * element after that position will be moved to {@link #targetPosition}.
+     * @param howMany Summary offset size of nodes which will be moved from the merged element to the new parent.
+     * @param targetPosition Position which the nodes from the merged elements will be moved to.
+     * @param graveyardPosition Position in graveyard to which the merged element will be moved.
+     * @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, graveyardPosition: Position, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'merge';
+    /**
+     * Position before the merged element (which will be deleted).
+     */
+    get deletionPosition(): Position;
+    /**
+     * Artificial range that contains all the nodes from the merged element that will be moved to {@link ~MergeOperation#sourcePosition}.
+     * The range starts at {@link ~MergeOperation#sourcePosition} and ends in the same parent, at `POSITIVE_INFINITY` offset.
+     */
+    get movedRange(): Range;
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MergeOperation;
+    /**
+     * 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 `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.
+     */
+    static fromJSON(json: any, document: Document): MergeOperation;
+}

package/src/model/operation/mergeoperation.js

@@ -0,0 +1,167 @@
+/**
+ * @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/mergeoperation
+ */
+import Operation from './operation.js';
+import SplitOperation from './splitoperation.js';
+import Position from '../position.js';
+import Range from '../range.js';
+import { _move } from './utils.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * Operation to merge two {@link module:engine/model/element~Element elements}.
+ *
+ * The merged element is the parent of {@link ~MergeOperation#sourcePosition} and it is merged into the parent of
+ * {@link ~MergeOperation#targetPosition}. All nodes from the merged element are moved to {@link ~MergeOperation#targetPosition}.
+ *
+ * The merged element is moved to the graveyard at {@link ~MergeOperation#graveyardPosition}.
+ */
+export default class MergeOperation extends Operation {
+    /**
+     * Creates a merge operation.
+     *
+     * @param sourcePosition Position inside the merged element. All nodes from that
+     * element after that position will be moved to {@link #targetPosition}.
+     * @param howMany Summary offset size of nodes which will be moved from the merged element to the new parent.
+     * @param targetPosition Position which the nodes from the merged elements will be moved to.
+     * @param graveyardPosition Position in graveyard to which the merged element will be moved.
+     * @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, graveyardPosition, baseVersion) {
+        super(baseVersion);
+        this.sourcePosition = sourcePosition.clone();
+        // This is, and should always remain, the first position in its parent.
+        this.sourcePosition.stickiness = 'toPrevious';
+        this.howMany = howMany;
+        this.targetPosition = targetPosition.clone();
+        // Except of a rare scenario in `MergeOperation` x `MergeOperation` transformation,
+        // this is, and should always remain, the last position in its parent.
+        this.targetPosition.stickiness = 'toNext';
+        this.graveyardPosition = graveyardPosition.clone();
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        return 'merge';
+    }
+    /**
+     * Position before the merged element (which will be deleted).
+     */
+    get deletionPosition() {
+        return new Position(this.sourcePosition.root, this.sourcePosition.path.slice(0, -1));
+    }
+    /**
+     * Artificial range that contains all the nodes from the merged element that will be moved to {@link ~MergeOperation#sourcePosition}.
+     * The range starts at {@link ~MergeOperation#sourcePosition} and ends in the same parent, at `POSITIVE_INFINITY` offset.
+     */
+    get movedRange() {
+        const end = this.sourcePosition.getShiftedBy(Number.POSITIVE_INFINITY);
+        return new Range(this.sourcePosition, end);
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        const mergedElement = this.sourcePosition.parent;
+        return [
+            Range._createOn(mergedElement),
+            // These could be positions but `Selectable` type only supports `Iterable<Range>`.
+            Range._createFromPositionAndShift(this.targetPosition, 0),
+            Range._createFromPositionAndShift(this.graveyardPosition, 0)
+        ];
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        return new MergeOperation(this.sourcePosition, this.howMany, this.targetPosition, this.graveyardPosition, this.baseVersion);
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        // Positions in this method are transformed by this merge operation because the split operation bases on
+        // the context after this merge operation happened (because split operation reverses it).
+        // So we need to acknowledge that the merge operation happened and those positions changed a little.
+        const targetPosition = this.targetPosition._getTransformedByMergeOperation(this);
+        const path = this.sourcePosition.path.slice(0, -1);
+        const insertionPosition = new Position(this.sourcePosition.root, path)._getTransformedByMergeOperation(this);
+        return new SplitOperation(targetPosition, this.howMany, insertionPosition, this.graveyardPosition, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate() {
+        const sourceElement = this.sourcePosition.parent;
+        const targetElement = this.targetPosition.parent;
+        // Validate whether merge operation has correct parameters.
+        if (!sourceElement.parent) {
+            /**
+             * Merge source position is invalid. The element to be merged must have a parent node.
+             *
+             * @error merge-operation-source-position-invalid
+             */
+            throw new CKEditorError('merge-operation-source-position-invalid', this);
+        }
+        else if (!targetElement.parent) {
+            /**
+             * Merge target position is invalid. The element to be merged must have a parent node.
+             *
+             * @error merge-operation-target-position-invalid
+             */
+            throw new CKEditorError('merge-operation-target-position-invalid', this);
+        }
+        else if (this.howMany != sourceElement.maxOffset) {
+            /**
+             * Merge operation specifies wrong number of nodes to move.
+             *
+             * @error merge-operation-how-many-invalid
+             */
+            throw new CKEditorError('merge-operation-how-many-invalid', this);
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        const mergedElement = this.sourcePosition.parent;
+        const sourceRange = Range._createIn(mergedElement);
+        _move(sourceRange, this.targetPosition);
+        _move(Range._createOn(mergedElement), this.graveyardPosition);
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.sourcePosition = json.sourcePosition.toJSON();
+        json.targetPosition = json.targetPosition.toJSON();
+        json.graveyardPosition = json.graveyardPosition.toJSON();
+        return json;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'MergeOperation';
+    }
+    /**
+     * 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.
+     */
+    static fromJSON(json, document) {
+        const sourcePosition = Position.fromJSON(json.sourcePosition, document);
+        const targetPosition = Position.fromJSON(json.targetPosition, document);
+        const graveyardPosition = Position.fromJSON(json.graveyardPosition, document);
+        return new this(sourcePosition, json.howMany, targetPosition, graveyardPosition, json.baseVersion);
+    }
+}