@ckeditor/ckeditor5-engine 30.0.0

package/src/model/operation/operation.js

@@ -0,0 +1,139 @@
+/**
+ * @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/operation
+ */
+
+/**
+ * Abstract base operation class.
+ *
+ * @abstract
+ */
+export default class Operation {
+	/**
+	 * Base operation constructor.
+	 *
+	 * @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( baseVersion ) {
+		/**
+		 * {@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.
+		 *
+		 * @member {Number}
+		 */
+		this.baseVersion = baseVersion;
+
+		/**
+		 * Defines whether operation is executed on attached or detached {@link module:engine/model/item~Item items}.
+		 *
+		 * @readonly
+		 * @member {Boolean} #isDocumentOperation
+		 */
+		this.isDocumentOperation = this.baseVersion !== null;
+
+		/**
+		 * {@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.
+		 *
+		 * @member {module:engine/model/batch~Batch|null} #batch
+		 */
+		this.batch = null;
+
+		/**
+		 * Operation type.
+		 *
+		 * @readonly
+		 * @member {String} #type
+		 */
+
+		/**
+		 * Creates and returns an operation that has the same parameters as this operation.
+		 *
+		 * @method #clone
+		 * @returns {module:engine/model/operation/operation~Operation} Clone of this 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.
+		 *
+		 * @method #getReversed
+		 * @returns {module:engine/model/operation/operation~Operation} Reversed operation.
+		 */
+
+		/**
+		 * Executes the operation - modifications described by the operation properties will be applied to the model tree.
+		 *
+		 * @protected
+		 * @method #_execute
+		 */
+	}
+
+	/**
+	 * Checks whether the operation's parameters are correct and the operation can be correctly executed. Throws
+	 * an error if operation is not valid.
+	 *
+	 * @protected
+	 * @method #_validate
+	 */
+	_validate() {
+	}
+
+	/**
+	 * Custom toJSON method to solve child-parent circular dependencies.
+	 *
+	 * @method #toJSON
+	 * @returns {Object} 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.
+	 *
+	 * @type {String}
+	 */
+	static get className() {
+		return 'Operation';
+	}
+
+	/**
+	 * Creates Operation object from deserilized object, i.e. from parsed JSON string.
+	 *
+	 * @param {Object} json Deserialized JSON object.
+	 * @param {module:engine/model/document~Document} doc Document on which this operation will be applied.
+	 * @returns {module:engine/model/operation/operation~Operation}
+	 */
+	static fromJSON( json ) {
+		return new this( json.baseVersion );
+	}
+
+	// @if CK_DEBUG_ENGINE // log() {
+	// @if CK_DEBUG_ENGINE // 	console.log( this.toString() );
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/operationfactory.js

@@ -0,0 +1,49 @@
+/**
+ * @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/operationfactory
+ */
+
+import AttributeOperation from '../operation/attributeoperation';
+import InsertOperation from '../operation/insertoperation';
+import MarkerOperation from '../operation/markeroperation';
+import MoveOperation from '../operation/moveoperation';
+import NoOperation from '../operation/nooperation';
+import Operation from '../operation/operation';
+import RenameOperation from '../operation/renameoperation';
+import RootAttributeOperation from '../operation/rootattributeoperation';
+import SplitOperation from '../operation/splitoperation';
+import MergeOperation from '../operation/mergeoperation';
+
+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[ SplitOperation.className ] = SplitOperation;
+operations[ MergeOperation.className ] = MergeOperation;
+
+/**
+ * A factory class for creating operations.
+ *
+ * @abstract
+ */
+export default class OperationFactory {
+	/**
+	 * Creates an operation instance from a JSON object (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/operation~Operation}
+	 */
+	static fromJSON( json, document ) {
+		return operations[ json.__className ].fromJSON( json, document );
+	}
+}

package/src/model/operation/renameoperation.js

@@ -0,0 +1,155 @@
+/**
+ * @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/renameoperation
+ */
+
+import Operation from './operation';
+import Element from '../element';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import Position from '../position';
+
+/**
+ * Operation to change element's name.
+ *
+ * Using this class you can change element's name.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class RenameOperation extends Operation {
+	/**
+	 * Creates an operation that changes element's name.
+	 *
+	 * @param {module:engine/model/position~Position} position Position before an element to change.
+	 * @param {String} oldName Current name of the element.
+	 * @param {String} newName New name for the element.
+	 * @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, oldName, newName, baseVersion ) {
+		super( baseVersion );
+
+		/**
+		 * Position before an element to change.
+		 *
+		 * @member {module:engine/model/position~Position} module:engine/model/operation/renameoperation~RenameOperation#position
+		 */
+		this.position = position;
+		// This position sticks to the next node because it is a position before the node that we want to change.
+		this.position.stickiness = 'toNext';
+
+		/**
+		 * Current name of the element.
+		 *
+		 * @member {String} module:engine/model/operation/renameoperation~RenameOperation#oldName
+		 */
+		this.oldName = oldName;
+
+		/**
+		 * New name for the element.
+		 *
+		 * @member {String} module:engine/model/operation/renameoperation~RenameOperation#newName
+		 */
+		this.newName = newName;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		return 'rename';
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/renameoperation~RenameOperation} Clone of this operation.
+	 */
+	clone() {
+		return new RenameOperation( this.position.clone(), this.oldName, this.newName, this.baseVersion );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/renameoperation~RenameOperation}
+	 */
+	getReversed() {
+		return new RenameOperation( this.position.clone(), this.newName, this.oldName, this.baseVersion + 1 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_validate() {
+		const element = this.position.nodeAfter;
+
+		if ( !( element instanceof Element ) ) {
+			/**
+			 * Given position is invalid or node after it is not instance of Element.
+			 *
+			 * @error rename-operation-wrong-position
+			 */
+			throw new CKEditorError(
+				'rename-operation-wrong-position',
+				this
+			);
+		} else if ( element.name !== this.oldName ) {
+			/**
+			 * Element to change has different name than operation's old name.
+			 *
+			 * @error rename-operation-wrong-name
+			 */
+			throw new CKEditorError(
+				'rename-operation-wrong-name',
+				this
+			);
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_execute() {
+		const element = this.position.nodeAfter;
+
+		element.name = this.newName;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	toJSON() {
+		const json = super.toJSON();
+
+		json.position = this.position.toJSON();
+
+		return json;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get className() {
+		return 'RenameOperation';
+	}
+
+	/**
+	 * Creates `RenameOperation` 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/attributeoperation~AttributeOperation}
+	 */
+	static fromJSON( json, document ) {
+		return new RenameOperation( Position.fromJSON( json.position, document ), json.oldName, json.newName, json.baseVersion );
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `RenameOperation( ${ this.baseVersion } ): ` +
+	// @if CK_DEBUG_ENGINE //		`${ this.position }: "${ this.oldName }" -> "${ this.newName }"`;
+	// @if CK_DEBUG_ENGINE // }
+}

package/src/model/operation/rootattributeoperation.js

@@ -0,0 +1,211 @@
+/**
+ * @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/rootattributeoperation
+ */
+
+import Operation from './operation';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * Operation to change root element's attribute. Using this class you can add, remove or change value of the attribute.
+ *
+ * This operation is needed, because root elements can't be changed through
+ * @link module:engine/model/operation/attributeoperation~AttributeOperation}.
+ * It is because {@link module:engine/model/operation/attributeoperation~AttributeOperation}
+ * requires a range to change and root element can't
+ * be a part of range because every {@link module:engine/model/position~Position} has to be inside a root.
+ * {@link module:engine/model/position~Position} can't be created before a root element.
+ *
+ * @extends module:engine/model/operation/operation~Operation
+ */
+export default class RootAttributeOperation extends Operation {
+	/**
+	 * Creates an operation that changes, removes or adds attributes on root element.
+	 *
+	 * @see module:engine/model/operation/attributeoperation~AttributeOperation
+	 * @param {module:engine/model/rootelement~RootElement} root Root element to change.
+	 * @param {String} key Key of an attribute to change or remove.
+	 * @param {*} oldValue Old value of the attribute with given key or `null` if adding a new attribute.
+	 * @param {*} newValue New value to set for the attribute. If `null`, then the operation just removes the attribute.
+	 * @param {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( root, key, oldValue, newValue, baseVersion ) {
+		super( baseVersion );
+
+		/**
+		 * Root element to change.
+		 *
+		 * @readonly
+		 * @member {module:engine/model/rootelement~RootElement}
+		 */
+		this.root = root;
+
+		/**
+		 * 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 adding a new attribute.
+		 *
+		 * @readonly
+		 * @member {*}
+		 */
+		this.oldValue = oldValue;
+
+		/**
+		 * New value to set for the attribute. If `null`, then the operation just removes the attribute.
+		 *
+		 * @readonly
+		 * @member {*}
+		 */
+		this.newValue = newValue;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	get type() {
+		if ( this.oldValue === null ) {
+			return 'addRootAttribute';
+		} else if ( this.newValue === null ) {
+			return 'removeRootAttribute';
+		} else {
+			return 'changeRootAttribute';
+		}
+	}
+
+	/**
+	 * Creates and returns an operation that has the same parameters as this operation.
+	 *
+	 * @returns {module:engine/model/operation/rootattributeoperation~RootAttributeOperation} Clone of this operation.
+	 */
+	clone() {
+		return new RootAttributeOperation( this.root, this.key, this.oldValue, this.newValue, this.baseVersion );
+	}
+
+	/**
+	 * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+	 *
+	 * @returns {module:engine/model/operation/rootattributeoperation~RootAttributeOperation}
+	 */
+	getReversed() {
+		return new RootAttributeOperation( this.root, this.key, this.newValue, this.oldValue, this.baseVersion + 1 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_validate() {
+		if ( this.root != this.root.root || this.root.is( 'documentFragment' ) ) {
+			/**
+			 * The element to change is not a root element.
+			 *
+			 * @error rootattribute-operation-not-a-root
+			 * @param {module:engine/model/rootelement~RootElement} root
+			 * @param {String} key
+			 * @param {*} value
+			 */
+			throw new CKEditorError(
+				'rootattribute-operation-not-a-root',
+				this,
+				{ root: this.root, key: this.key }
+			);
+		}
+
+		if ( this.oldValue !== null && this.root.getAttribute( this.key ) !== this.oldValue ) {
+			/**
+			 * The attribute which should be removed does not exists for the given node.
+			 *
+			 * @error rootattribute-operation-wrong-old-value
+			 * @param {module:engine/model/rootelement~RootElement} root
+			 * @param {String} key
+			 * @param {*} value
+			 */
+			throw new CKEditorError(
+				'rootattribute-operation-wrong-old-value',
+				this,
+				{ root: this.root, key: this.key }
+			);
+		}
+
+		if ( this.oldValue === null && this.newValue !== null && this.root.hasAttribute( this.key ) ) {
+			/**
+			 * The attribute with given key already exists for the given node.
+			 *
+			 * @error rootattribute-operation-attribute-exists
+			 * @param {module:engine/model/rootelement~RootElement} root
+			 * @param {String} key
+			 */
+			throw new CKEditorError(
+				'rootattribute-operation-attribute-exists',
+				this,
+				{ root: this.root, key: this.key }
+			);
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	_execute() {
+		if ( this.newValue !== null ) {
+			this.root._setAttribute( this.key, this.newValue );
+		} else {
+			this.root._removeAttribute( this.key );
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	toJSON() {
+		const json = super.toJSON();
+
+		json.root = this.root.toJSON();
+
+		return json;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get className() {
+		return 'RootAttributeOperation';
+	}
+
+	/**
+	 * Creates RootAttributeOperation 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/rootattributeoperation~RootAttributeOperation}
+	 */
+	static fromJSON( json, document ) {
+		if ( !document.getRoot( json.root ) ) {
+			/**
+			 * Cannot create RootAttributeOperation for document. Root with specified name does not exist.
+			 *
+			 * @error rootattribute-operation-fromjson-no-root
+			 * @param {String} rootName
+			 */
+			throw new CKEditorError( 'rootattribute-operation-fromjson-no-root', this, { rootName: json.root } );
+		}
+
+		return new RootAttributeOperation( document.getRoot( json.root ), json.key, json.oldValue, json.newValue, json.baseVersion );
+	}
+
+	// @if CK_DEBUG_ENGINE // toString() {
+	// @if CK_DEBUG_ENGINE // 	return `RootAttributeOperation( ${ this.baseVersion } ): ` +
+	// @if CK_DEBUG_ENGINE //		`"${ this.key }": ${ JSON.stringify( this.oldValue ) }` +
+	// @if CK_DEBUG_ENGINE //		` -> ${ JSON.stringify( this.newValue ) }, ${ this.root.rootName }`;
+	// @if CK_DEBUG_ENGINE // }
+}