@ckeditor/ckeditor5-engine 30.0.0

package/src/model/operation/markeroperation.js

@@ -0,0 +1,154 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. 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';
+import Range from '../range';
+
+/**
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class MarkerOperation extends Operation {
+	/**
+	 * @param {String} name Marker name.
+	 * @param {module:engine/model/range~Range} oldRange Marker range before the change.
+	 * @param {module:engine/model/range~Range} newRange Marker range after the change.
+	 * @param {module:engine/model/markercollection~MarkerCollection} markers Marker collection on which change should be executed.
+	 * @param {Boolean} affectsData Specifies whether the marker operation affects the data produced by the data pipeline
+	 * (is persisted in the editor's data).
+	 * @param {Number|null} 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 );
+
+		/**
+		 * Marker name.
+		 *
+		 * @readonly
+		 * @member {String}
+		 */
+		this.name = name;
+
+		/**
+		 * Marker range before the change.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/range~Range}
+		 */
+		this.oldRange = oldRange ? oldRange.clone() : null;
+
+		/**
+		 * Marker range after the change.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/range~Range}
+		 */
+		this.newRange = newRange ? newRange.clone() : null;
+
+		/**
+		 * Specifies whether the marker operation affects the data produced by the data pipeline
+		 * (is persisted in the editor's data).
+		 *
+		 * @readonly
+		 * @member {Boolean}
+		 */
+		this.affectsData = affectsData;
+
+		/**
+		 * Marker collection on which change should be executed.
+		 *
+		 * @private
+		 * @member {module:engine/model/markercollection~MarkerCollection}
+		 */
+		this._markers = markers;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		return 'marker';
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/markeroperation~MarkerOperation} Clone of 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()`}.
+	 *
+	 * @returns {module:engine/model/operation/markeroperation~MarkerOperation}
+	 */
+	getReversed() {
+		return new MarkerOperation( this.name, this.newRange, this.oldRange, this._markers, this.affectsData, this.baseVersion + 1 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_execute() {
+		const type = this.newRange ? '_set' : '_remove';
+
+		this._markers[ type ]( this.name, this.newRange, true, this.affectsData );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	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 {Object} json Deserialized JSON object.
+	 * @param {module:engine/model/document~Document} document Document on which this operation will be applied.
+	 * @returns {module:engine/model/operation/markeroperation~MarkerOperation}
+	 */
+	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
+		);
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `MarkerOperation( ${ this.baseVersion } ): ` +
+	// @if CK_DEBUG_ENGINE //		`"${ this.name }": ${ this.oldRange } -> ${ this.newRange }`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/mergeoperation.js

@@ -0,0 +1,216 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. 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';
+import SplitOperation from './splitoperation';
+import Position from '../position';
+import Range from '../range';
+import { _move } from './utils';
+
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * 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}.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class MergeOperation extends Operation {
+	/**
+	 * Creates a merge operation.
+	 *
+	 * @param {module:engine/model/position~Position} sourcePosition Position inside the merged element. All nodes from that
+	 * element after that position will be moved to {@link ~#targetPosition}.
+	 * @param {Number} howMany Summary offset size of nodes which will be moved from the merged element to the new parent.
+	 * @param {module:engine/model/position~Position} targetPosition Position which the nodes from the merged elements will be moved to.
+	 * @param {module:engine/model/position~Position} graveyardPosition Position in graveyard to which the merged element will be moved.
+	 * @param {Number|null} 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 );
+
+		/**
+		 * Position inside the merged element. All nodes from that element after that position will be moved to {@link ~#targetPosition}.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/mergeoperation~MergeOperation#sourcePosition
+		 */
+		this.sourcePosition = sourcePosition.clone();
+		// This is, and should always remain, the first position in its parent.
+		this.sourcePosition.stickiness = 'toPrevious';
+
+		/**
+		 * Summary offset size of nodes which will be moved from the merged element to the new parent.
+		 *
+		 * @member {Number} module:engine/model/operation/mergeoperation~MergeOperation#howMany
+		 */
+		this.howMany = howMany;
+
+		/**
+		 * Position which the nodes from the merged elements will be moved to.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/mergeoperation~MergeOperation#targetPosition
+		 */
+		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';
+
+		/**
+		 * Position in graveyard to which the merged element will be moved.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/mergeoperation~MergeOperation#graveyardPosition
+		 */
+		this.graveyardPosition = graveyardPosition.clone();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		return 'merge';
+	}
+
+	/**
+	 * Position before the merged element (which will be deleted).
+	 *
+	 * @readonly
+	 * @type {module:engine/model/position~Position}
+	 */
+	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.
+	 *
+	 * @readonly
+	 * @type {module:engine/model/range~Range}
+	 */
+	get movedRange() {
+		const end = this.sourcePosition.getShiftedBy( Number.POSITIVE_INFINITY );
+
+		return new Range( this.sourcePosition, end );
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/mergeoperation~MergeOperation} Clone of this operation.
+	 */
+	clone() {
+		return new this.constructor( this.sourcePosition, this.howMany, this.targetPosition, this.graveyardPosition, this.baseVersion );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/splitoperation~SplitOperation}
+	 */
+	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
+	 */
+	_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
+	 */
+	_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 deserilized object, i.e. from parsed JSON string.
+	 *
+	 * @param {Object} json Deserialized JSON object.
+	 * @param {module:engine/model/document~Document} document Document on which this operation will be applied.
+	 * @returns {module:engine/model/operation/mergeoperation~MergeOperation}
+	 */
+	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 );
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `MergeOperation( ${ this.baseVersion } ): ` +
+	// @if CK_DEBUG_ENGINE //		`${ this.sourcePosition } -> ${ this.targetPosition }` +
+	// @if CK_DEBUG_ENGINE //		` ( ${ this.howMany } ), ${ this.graveyardPosition }`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/moveoperation.js

@@ -0,0 +1,209 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. 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';
+import Position from '../position';
+import Range from '../range';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import compareArrays from '@ckeditor/ckeditor5-utils/src/comparearrays';
+import { _move } from './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}.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class MoveOperation extends Operation {
+	/**
+	 * Creates a move operation.
+	 *
+	 * @param {module:engine/model/position~Position} sourcePosition
+	 * Position before the first {@link module:engine/model/item~Item model item} to move.
+	 * @param {Number} howMany Offset size of moved range. Moved range will start from `sourcePosition` and end at
+	 * `sourcePosition` with offset shifted by `howMany`.
+	 * @param {module:engine/model/position~Position} targetPosition Position at which moved nodes will be inserted.
+	 * @param {Number|null} 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 );
+
+		/**
+		 * Position before the first {@link module:engine/model/item~Item model item} to move.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/moveoperation~MoveOperation#sourcePosition
+		 */
+		this.sourcePosition = sourcePosition.clone();
+		// `'toNext'` because `sourcePosition` is a bit like a start of the moved range.
+		this.sourcePosition.stickiness = 'toNext';
+
+		/**
+		 * Offset size of moved range.
+		 *
+		 * @member {Number} module:engine/model/operation/moveoperation~MoveOperation#howMany
+		 */
+		this.howMany = howMany;
+
+		/**
+		 * Position at which moved nodes will be inserted.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/moveoperation~MoveOperation#targetPosition
+		 */
+		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';
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/moveoperation~MoveOperation} Clone of this operation.
+	 */
+	clone() {
+		return new this.constructor( 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
+	 *
+	 * @returns {module:engine/model/position~Position}
+	 */
+	getMovedRangeStart() {
+		return this.targetPosition._getTransformedByDeletion( this.sourcePosition, this.howMany );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/moveoperation~MoveOperation}
+	 */
+	getReversed() {
+		const newTargetPosition = this.sourcePosition._getTransformedByInsertion( this.targetPosition, this.howMany );
+
+		return new this.constructor( this.getMovedRangeStart(), this.howMany, newTargetPosition, this.baseVersion + 1 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_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
+	 */
+	_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 deserilized object, i.e. from parsed JSON string.
+	 *
+	 * @param {Object} json Deserialized JSON object.
+	 * @param {module:engine/model/document~Document} document Document on which this operation will be applied.
+	 * @returns {module:engine/model/operation/moveoperation~MoveOperation}
+	 */
+	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 );
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	const range = ModelRange._createFromPositionAndShift( this.sourcePosition, this.howMany );
+
+	// @if CK_DEBUG_ENGINE //	return `MoveOperation( ${ this.baseVersion } ): ${ range } -> ${ this.targetPosition }`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/nooperation.js

@@ -0,0 +1,58 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. 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';
+
+/**
+ * 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.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class NoOperation extends Operation {
+	get type() {
+		return 'noop';
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/nooperation~NoOperation} Clone of this operation.
+	 */
+	clone() {
+		return new NoOperation( this.baseVersion );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/nooperation~NoOperation}
+	 */
+	getReversed() {
+		return new NoOperation( this.baseVersion + 1 );
+	}
+
+	_execute() {
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get className() {
+		return 'NoOperation';
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `NoOperation( ${ this.baseVersion } )`;
+	// @if CK_DEBUG_ENGINE // }
+}