@ckeditor/ckeditor5-engine 30.0.0

package/src/model/nodelist.js

@@ -0,0 +1,217 @@
+/**
+ * @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/nodelist
+ */
+
+import Node from './node';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * Provides an interface to operate on a list of {@link module:engine/model/node~Node nodes}. `NodeList` is used internally
+ * in classes like {@link module:engine/model/element~Element Element}
+ * or {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment}.
+ */
+export default class NodeList {
+	/**
+	 * Creates an empty node list.
+	 *
+	 * @protected
+	 * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes contained in this node list.
+	 */
+	constructor( nodes ) {
+		/**
+		 * Nodes contained in this node list.
+		 *
+		 * @private
+		 * @member {Array.<module:engine/model/node~Node>}
+		 */
+		this._nodes = [];
+
+		if ( nodes ) {
+			this._insertNodes( 0, nodes );
+		}
+	}
+
+	/**
+	 * Iterable interface.
+	 *
+	 * Iterates over all nodes contained inside this node list.
+	 *
+	 * @returns {Iterable.<module:engine/model/node~Node>}
+	 */
+	[ Symbol.iterator ]() {
+		return this._nodes[ Symbol.iterator ]();
+	}
+
+	/**
+	 * Number of nodes contained inside this node list.
+	 *
+	 * @readonly
+	 * @type {Number}
+	 */
+	get length() {
+		return this._nodes.length;
+	}
+
+	/**
+	 * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes contained inside this node list.
+	 *
+	 * @readonly
+	 * @type {Number}
+	 */
+	get maxOffset() {
+		return this._nodes.reduce( ( sum, node ) => sum + node.offsetSize, 0 );
+	}
+
+	/**
+	 * Gets the node at the given index. Returns `null` if incorrect index was passed.
+	 *
+	 * @param {Number} index Index of node.
+	 * @returns {module:engine/model/node~Node|null} Node at given index.
+	 */
+	getNode( index ) {
+		return this._nodes[ index ] || null;
+	}
+
+	/**
+	 * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+	 *
+	 * @param {module:engine/model/node~Node} node Child node to look for.
+	 * @returns {Number|null} Child node's index.
+	 */
+	getNodeIndex( node ) {
+		const index = this._nodes.indexOf( node );
+
+		return index == -1 ? null : index;
+	}
+
+	/**
+	 * Returns the starting offset of given node. Starting offset is equal to the sum of
+	 * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+	 *
+	 * @param {module:engine/model/node~Node} node Node to look for.
+	 * @returns {Number|null} Node's starting offset.
+	 */
+	getNodeStartOffset( node ) {
+		const index = this.getNodeIndex( node );
+
+		return index === null ? null : this._nodes.slice( 0, index ).reduce( ( sum, node ) => sum + node.offsetSize, 0 );
+	}
+
+	/**
+	 * Converts index to offset in node list.
+	 *
+	 * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+	 * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+	 *
+	 * @param {Number} index Node's index.
+	 * @returns {Number} Node's starting offset.
+	 */
+	indexToOffset( index ) {
+		if ( index == this._nodes.length ) {
+			return this.maxOffset;
+		}
+
+		const node = this._nodes[ index ];
+
+		if ( !node ) {
+			/**
+			 * Given index cannot be found in the node list.
+			 *
+			 * @error model-nodelist-index-out-of-bounds
+			 */
+			throw new CKEditorError( 'model-nodelist-index-out-of-bounds', this );
+		}
+
+		return this.getNodeStartOffset( node );
+	}
+
+	/**
+	 * Converts offset in node list to index.
+	 *
+	 * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+	 * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+	 *
+	 * @param {Number} offset Offset to look for.
+	 * @returns {Number} Index of a node that occupies given offset.
+	 */
+	offsetToIndex( offset ) {
+		let totalOffset = 0;
+
+		for ( const node of this._nodes ) {
+			if ( offset >= totalOffset && offset < totalOffset + node.offsetSize ) {
+				return this.getNodeIndex( node );
+			}
+
+			totalOffset += node.offsetSize;
+		}
+
+		if ( totalOffset != offset ) {
+			/**
+			 * Given offset cannot be found in the node list.
+			 *
+			 * @error model-nodelist-offset-out-of-bounds
+			 * @param {Number} offset
+			 * @param {module:engine/model/nodelist~NodeList} nodeList Stringified node list.
+			 */
+			throw new CKEditorError( 'model-nodelist-offset-out-of-bounds',
+				this,
+				{
+					offset,
+					nodeList: this
+				}
+			);
+		}
+
+		return this.length;
+	}
+
+	/**
+	 * Inserts given nodes at given index.
+	 *
+	 * @protected
+	 * @param {Number} index Index at which nodes should be inserted.
+	 * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes to be inserted.
+	 */
+	_insertNodes( index, nodes ) {
+		// Validation.
+		for ( const node of nodes ) {
+			if ( !( node instanceof Node ) ) {
+				/**
+				 * Trying to insert an object which is not a Node instance.
+				 *
+				 * @error model-nodelist-insertnodes-not-node
+				 */
+				throw new CKEditorError( 'model-nodelist-insertnodes-not-node', this );
+			}
+		}
+
+		this._nodes.splice( index, 0, ...nodes );
+	}
+
+	/**
+	 * Removes one or more nodes starting at the given index.
+	 *
+	 * @protected
+	 * @param {Number} indexStart Index of the first node to remove.
+	 * @param {Number} [howMany=1] Number of nodes to remove.
+	 * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
+	 */
+	_removeNodes( indexStart, howMany = 1 ) {
+		return this._nodes.splice( indexStart, howMany );
+	}
+
+	/**
+	 * Converts `NodeList` instance to an array containing nodes that were inserted in the node list. Nodes
+	 * are also converted to their plain object representation.
+	 *
+	 * @returns {Array.<module:engine/model/node~Node>} `NodeList` instance converted to `Array`.
+	 */
+	toJSON() {
+		return this._nodes.map( node => node.toJSON() );
+	}
+}

package/src/model/operation/attributeoperation.js

@@ -0,0 +1,202 @@
+/**
+ * @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/attributeoperation
+ */
+
+import Operation from './operation';
+import Range from '../range';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import { _setAttribute } from './utils';
+import { isEqual } from 'lodash-es';
+
+/**
+ * Operation to change nodes' attribute.
+ *
+ * Using this class you can add, remove or change value of the attribute.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class AttributeOperation extends Operation {
+	/**
+	 * Creates an operation that changes, removes or adds attributes.
+	 *
+	 * If only `newValue` is set, attribute will be added on a node. Note that all nodes in operation's range must not
+	 * have an attribute with the same key as the added attribute.
+	 *
+	 * If only `oldValue` is set, then attribute with given key will be removed. Note that all nodes in operation's range
+	 * must have an attribute with that key added.
+	 *
+	 * If both `newValue` and `oldValue` are set, then the operation will change the attribute value. Note that all nodes in
+	 * operation's ranges must already have an attribute with given key and `oldValue` as value
+	 *
+	 * @param {module:engine/model/range~Range} range Range on which the operation should be applied. Must be a flat range.
+	 * @param {String} key Key of an attribute to change or remove.
+	 * @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 {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( range, key, oldValue, newValue, baseVersion ) {
+		super( baseVersion );
+
+		/**
+		 * Range on which operation should be applied.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/range~Range}
+		 */
+		this.range = range.clone();
+
+		/**
+		 * Key of an attribute to change or remove.
+		 *
+		 * @readonly
+		 * @member {String}
+		 */
+		this.key = key;
+
+		/**
+		 * Old value of the attribute with given key or `null`, if attribute was not set before.
+		 *
+		 * @readonly
+		 * @member {*}
+		 */
+		this.oldValue = oldValue === undefined ? null : oldValue;
+
+		/**
+		 * New value of the attribute with given key or `null`, if operation should remove attribute.
+		 *
+		 * @readonly
+		 * @member {*}
+		 */
+		this.newValue = newValue === undefined ? null : newValue;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		if ( this.oldValue === null ) {
+			return 'addAttribute';
+		} else if ( this.newValue === null ) {
+			return 'removeAttribute';
+		} else {
+			return 'changeAttribute';
+		}
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/attributeoperation~AttributeOperation} Clone of this operation.
+	 */
+	clone() {
+		return new AttributeOperation( this.range, this.key, this.oldValue, this.newValue, this.baseVersion );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/attributeoperation~AttributeOperation}
+	 */
+	getReversed() {
+		return new AttributeOperation( this.range, this.key, this.newValue, this.oldValue, this.baseVersion + 1 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	toJSON() {
+		const json = super.toJSON();
+
+		json.range = this.range.toJSON();
+
+		return json;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_validate() {
+		if ( !this.range.isFlat ) {
+			/**
+			 * The range to change is not flat.
+			 *
+			 * @error attribute-operation-range-not-flat
+			 */
+			throw new CKEditorError( 'attribute-operation-range-not-flat', this );
+		}
+
+		for ( const item of this.range.getItems( { shallow: true } ) ) {
+			if ( this.oldValue !== null && !isEqual( item.getAttribute( this.key ), this.oldValue ) ) {
+				/**
+				 * Changed node has different attribute value than operation's old attribute value.
+				 *
+				 * @error attribute-operation-wrong-old-value
+				 * @param {module:engine/model/item~Item} item
+				 * @param {String} key
+				 * @param {*} value
+				 */
+				throw new CKEditorError(
+					'attribute-operation-wrong-old-value',
+					this,
+					{ item, key: this.key, value: this.oldValue }
+				);
+			}
+
+			if ( this.oldValue === null && this.newValue !== null && item.hasAttribute( this.key ) ) {
+				/**
+				 * The attribute with given key already exists for the given node.
+				 *
+				 * @error attribute-operation-attribute-exists
+				 * @param {module:engine/model/node~Node} node
+				 * @param {String} key
+				 */
+				throw new CKEditorError(
+					'attribute-operation-attribute-exists',
+					this,
+					{ node: item, key: this.key }
+				);
+			}
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_execute() {
+		// If value to set is same as old value, don't do anything.
+		if ( !isEqual( this.oldValue, this.newValue ) ) {
+			// Execution.
+			_setAttribute( this.range, this.key, this.newValue );
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get className() {
+		return 'AttributeOperation';
+	}
+
+	/**
+	 * Creates `AttributeOperation` 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/attributeoperation~AttributeOperation}
+	 */
+	static fromJSON( json, document ) {
+		return new AttributeOperation( Range.fromJSON( json.range, document ), json.key, json.oldValue, json.newValue, json.baseVersion );
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `AttributeOperation( ${ this.baseVersion } ): ` +
+	// @if CK_DEBUG_ENGINE //		`"${ this.key }": ${ JSON.stringify( this.oldValue ) }` +
+	// @if CK_DEBUG_ENGINE //		` -> ${ JSON.stringify( this.newValue ) }, ${ this.range }`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/detachoperation.js

@@ -0,0 +1,103 @@
+/**
+ * @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/detachoperation
+ */
+
+import Operation from './operation';
+import Range from '../range';
+import { _remove } from './utils';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+// @if CK_DEBUG_ENGINE // const ModelRange = require( '../range' ).default;
+
+/**
+ * Operation to permanently remove node from detached root.
+ * Note this operation is only a local operation and won't be send to the other clients.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class DetachOperation extends Operation {
+	/**
+	 * Creates an insert 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`.
+	 */
+	constructor( sourcePosition, howMany ) {
+		super( null );
+
+		/**
+		 * Position before the first {@link module:engine/model/item~Item model item} to detach.
+		 *
+		 * @member {module:engine/model/position~Position} #sourcePosition
+		 */
+		this.sourcePosition = sourcePosition.clone();
+
+		/**
+		 * Offset size of moved range.
+		 *
+		 * @member {Number} #howMany
+		 */
+		this.howMany = howMany;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		return 'detach';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	toJSON() {
+		const json = super.toJSON();
+
+		json.sourcePosition = this.sourcePosition.toJSON();
+
+		return json;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_validate() {
+		if ( this.sourcePosition.root.document ) {
+			/**
+			 * Cannot detach document node.
+			 *
+			 * @error detach-operation-on-document-node
+			 */
+			throw new CKEditorError( 'detach-operation-on-document-node', this );
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_execute() {
+		_remove( Range._createFromPositionAndShift( this.sourcePosition, this.howMany ) );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get className() {
+		return 'DetachOperation';
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // const range = ModelRange._createFromPositionAndShift( this.sourcePosition, this.howMany );
+	// @if CK_DEBUG_ENGINE //	const nodes = Array.from( range.getItems() );
+	// @if CK_DEBUG_ENGINE //	const nodeString = nodes.length > 1 ? `[ ${ nodes.length } ]` : nodes[ 0 ];
+
+	// @if CK_DEBUG_ENGINE //	return `DetachOperation( ${ this.baseVersion } ): ${ nodeString } -> ${ range }`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/insertoperation.js

@@ -0,0 +1,188 @@
+/**
+ * @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/insertoperation
+ */
+
+import Operation from './operation';
+import Position from '../position';
+import NodeList from '../nodelist';
+import MoveOperation from './moveoperation';
+import { _insert, _normalizeNodes } from './utils';
+import Text from '../text';
+import Element from '../element';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * Operation to insert one or more nodes at given position in the model.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class InsertOperation extends Operation {
+	/**
+	 * Creates an insert operation.
+	 *
+	 * @param {module:engine/model/position~Position} position Position of insertion.
+	 * @param {module:engine/model/node~NodeSet} nodes The list of nodes to 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( position, nodes, baseVersion ) {
+		super( baseVersion );
+
+		/**
+		 * Position of insertion.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/insertoperation~InsertOperation#position
+		 */
+		this.position = position.clone();
+		this.position.stickiness = 'toNone';
+
+		/**
+		 * List of nodes to insert.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/nodelist~NodeList} module:engine/model/operation/insertoperation~InsertOperation#nodeList
+		 */
+		this.nodes = new NodeList( _normalizeNodes( nodes ) );
+
+		/**
+		 * 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.
+		 *
+		 * @member {Boolean} module:engine/model/operation/insertoperation~InsertOperation#shouldReceiveAttributes
+		 */
+		this.shouldReceiveAttributes = false;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		return 'insert';
+	}
+
+	/**
+	 * Total offset size of inserted nodes.
+	 *
+	 * @returns {Number}
+	 */
+	get howMany() {
+		return this.nodes.maxOffset;
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/insertoperation~InsertOperation} Clone of 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()`}.
+	 *
+	 * @returns {module:engine/model/operation/moveoperation~MoveOperation}
+	 */
+	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
+	 */
+	_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
+	 */
+	_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 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/insertoperation~InsertOperation}
+	 */
+	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;
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	const nodeString = this.nodes.length > 1 ? `[ ${ this.nodes.length } ]` : this.nodes.getNode( 0 );
+
+	// @if CK_DEBUG_ENGINE //	return `InsertOperation( ${ this.baseVersion } ): ${ nodeString } -> ${ this.position }`;
+	// @if CK_DEBUG_ENGINE // }
+}