@ckeditor/ckeditor5-engine 32.0.0 → 34.1.0

package/src/model/document.js

@@ -52,24 +52,13 @@ export default class Document {
 		 */
 		this.model = model;
 
-		/**
-		 * The document version. It starts from `0` and every operation increases the version number. It is used to ensure that
-		 * operations are applied on a proper document version.
-		 *
-		 * If the {@link module:engine/model/operation/operation~Operation#baseVersion base version} does not match the document version,
-		 * a {@link module:utils/ckeditorerror~CKEditorError model-document-applyoperation-wrong-version} error is thrown.
-		 *
-		 * @type {Number}
-		 */
-		this.version = 0;
-
 		/**
 		 * The document's history.
 		 *
 		 * @readonly
 		 * @type {module:engine/model/history~History}
 		 */
-		this.history = new History( this );
+		this.history = new History();
 
 		/**
 		 * The selection in this document.
@@ -115,21 +104,6 @@ export default class Document {
 		// Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
 		this.createRoot( '$root', graveyardName );
 
-		// First, if the operation is a document operation check if it's base version is correct.
-		this.listenTo( model, 'applyOperation', ( evt, args ) => {
-			const operation = args[ 0 ];
-
-			if ( operation.isDocumentOperation && operation.baseVersion !== this.version ) {
-				/**
-				 * Only operations with matching versions can be applied.
-				 *
-				 * @error model-document-applyoperation-wrong-version
-				 * @param {module:engine/model/operation/operation~Operation} operation
-				 */
-				throw new CKEditorError( 'model-document-applyoperation-wrong-version', this, { operation } );
-			}
-		}, { priority: 'highest' } );
-
 		// Then, still before an operation is applied on model, buffer the change in differ.
 		this.listenTo( model, 'applyOperation', ( evt, args ) => {
 			const operation = args[ 0 ];
@@ -144,7 +118,6 @@ export default class Document {
 			const operation = args[ 0 ];
 
 			if ( operation.isDocumentOperation ) {
-				this.version++;
 				this.history.addOperation( operation );
 			}
 		}, { priority: 'low' } );
@@ -157,19 +130,47 @@ export default class Document {
 		// Buffer marker changes.
 		// This is not covered in buffering operations because markers may change outside of them (when they
 		// are modified using `model.markers` collection, not through `MarkerOperation`).
-		this.listenTo( model.markers, 'update', ( evt, marker, oldRange, newRange ) => {
+		this.listenTo( model.markers, 'update', ( evt, marker, oldRange, newRange, oldMarkerData ) => {
+			// Copy the `newRange` to the new marker data as during the marker removal the range is not updated.
+			const newMarkerData = { ...marker.getData(), range: newRange };
+
 			// Whenever marker is updated, buffer that change.
-			this.differ.bufferMarkerChange( marker.name, oldRange, newRange, marker.affectsData );
+			this.differ.bufferMarkerChange( marker.name, oldMarkerData, newMarkerData );
 
 			if ( oldRange === null ) {
 				// If this is a new marker, add a listener that will buffer change whenever marker changes.
 				marker.on( 'change', ( evt, oldRange ) => {
-					this.differ.bufferMarkerChange( marker.name, oldRange, marker.getRange(), marker.affectsData );
+					const markerData = marker.getData();
+
+					this.differ.bufferMarkerChange(
+						marker.name,
+						{ ...markerData, range: oldRange },
+						markerData
+					);
 				} );
 			}
 		} );
 	}
 
+	/**
+	 * The document version. Every applied operation increases the version number. It is used to
+	 * ensure that operations are applied on a proper document version.
+	 *
+	 * This property is equal to {@link module:engine/model/history~History#version `model.Document#history#version`}.
+	 *
+	 * If the {@link module:engine/model/operation/operation~Operation#baseVersion base version} does not match the document version,
+	 * a {@link module:utils/ckeditorerror~CKEditorError model-document-applyoperation-wrong-version} error is thrown.
+	 *
+	 * @type {Number}
+	 */
+	get version() {
+		return this.history.version;
+	}
+
+	set version( version ) {
+		this.history.version = version;
+	}
+
 	/**
 	 * The graveyard tree root. A document always has a graveyard root that stores removed nodes.
 	 *

package/src/model/history.js

@@ -3,6 +3,8 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+
 /**
  * @module engine/model/history
  */
@@ -18,8 +20,9 @@ export default class History {
 		/**
 		 * Operations added to the history.
 		 *
-		 * @protected
-		 * @member {Array.<module:engine/model/operation/operation~Operation>} module:engine/model/history~History#_operations
+		 * @private
+		 * @readonly
+		 * @type {Array.<module:engine/model/operation/operation~Operation>}
 		 */
 		this._operations = [];
 
@@ -39,43 +42,164 @@ export default class History {
 		 * Holds all undone operations.
 		 *
 		 * @private
-		 * @member {Set.<module:engine/model/operation/operation~Operation>} module:engine/model/history~History#_undoneOperations
+		 * @type {Set.<module:engine/model/operation/operation~Operation>}
 		 */
 		this._undoneOperations = new Set();
+
+		/**
+		 * A map that allows retrieving the operations fast based on the given base version.
+		 *
+		 * @private
+		 * @type Map.<Number,Number>
+		 */
+		this._baseVersionToOperationIndex = new Map();
+
+		/**
+		 * The history version.
+		 *
+		 * @private
+		 * @type {Number}
+		 */
+		this._version = 0;
+
+		/**
+		 * The gap pairs kept in the <from,to> format.
+		 *
+		 * Anytime the `history.version` is set to a version larger than `history.version + 1`,
+		 * a new <lastHistoryVersion, newHistoryVersion> entry is added to the map.
+		 *
+		 * @private
+		 * @type Map.<number,number>
+		 */
+		this._gaps = new Map();
+	}
+
+	/**
+	 * The version of the last operation in the history.
+	 *
+	 * The history version is incremented automatically when a new operation is added to the history.
+	 * Setting the version manually should be done only in rare circumstances when a gap is planned
+	 * between history versions. When doing so, a gap will be created and the history will accept adding
+	 * an operation with base version equal to the new history version.
+	 *
+	 * @type {Number}
+	 */
+	get version() {
+		return this._version;
+	}
+
+	set version( version ) {
+		// Store a gap if there are some operations already in the history and the
+		// new version does not increment the latest one.
+		if ( this._operations.length && version > this._version + 1 ) {
+			this._gaps.set( this._version, version );
+		}
+
+		this._version = version;
+	}
+
+	/**
+	 * The last history operation.
+	 *
+	 * @readonly
+	 * @type {module:engine/model/operation/operation~Operation|undefined}
+	 */
+	get lastOperation() {
+		return this._operations[ this._operations.length - 1 ];
 	}
 
 	/**
-	 * Adds an operation to the history.
+	 * Adds an operation to the history and increments the history version.
+	 *
+	 * The operation's base version should be equal to the history version. Otherwise an error is thrown.
 	 *
 	 * @param {module:engine/model/operation/operation~Operation} operation Operation to add.
 	 */
 	addOperation( operation ) {
-		if ( this._operations.includes( operation ) ) {
-			return;
+		if ( operation.baseVersion !== this.version ) {
+			/**
+			 * Only operations with matching versions can be added to the history.
+			 *
+			 * @error model-document-history-addoperation-incorrect-version
+			 * @param {Object} errorData The operation and the current document history version.
+			 */
+			throw new CKEditorError( 'model-document-history-addoperation-incorrect-version', this, {
+				operation,
+				historyVersion: this.version
+			} );
 		}
 
 		this._operations.push( operation );
+		this._version++;
+
+		this._baseVersionToOperationIndex.set( operation.baseVersion, this._operations.length - 1 );
 	}
 
 	/**
-	 * Returns operations added to the history.
+	 * Returns operations from the given range of operation base versions that were added to the history.
 	 *
-	 * @param {Number} [from=Number.NEGATIVE_INFINITY] Base version from which operations should be returned (inclusive).
-	 * Defaults to `Number.NEGATIVE_INFINITY`, which means that operations from the first one will be returned.
-	 * @param {Number} [to=Number.POSITIVE_INFINITY] Base version up to which operations should be returned (exclusive).
-	 * Defaults to `Number.POSITIVE_INFINITY` which means that operations up to the last one will be returned.
-	 * @returns {Array.<module:engine/model/operation/operation~Operation>} Operations added to the history.
+	 * Note that there may be gaps in operations base versions.
+	 *
+	 * @param {Number} [fromBaseVersion] Base version from which operations should be returned (inclusive).
+	 * @param {Number} [toBaseVersion] Base version up to which operations should be returned (exclusive).
+     * @returns {Array.<module:engine/model/operation/operation~Operation>} History operations for the given range, in chronological order.
 	 */
-	getOperations( from = Number.NEGATIVE_INFINITY, to = Number.POSITIVE_INFINITY ) {
-		const operations = [];
+	getOperations( fromBaseVersion, toBaseVersion = this.version ) {
+		// When there is no operation in the history, return an empty array.
+		// After that we can be sure that `firstOperation`, `lastOperation` are not nullish.
+		if ( !this._operations.length ) {
+			return [];
+		}
+
+		const firstOperation = this._operations[ 0 ];
+
+		if ( fromBaseVersion === undefined ) {
+			fromBaseVersion = firstOperation.baseVersion;
+		}
+
+		// Change exclusive `toBaseVersion` to inclusive, so it will refer to the actual index.
+		// Thanks to that mapping from base versions to operation indexes are possible.
+		let inclusiveTo = toBaseVersion - 1;
+
+		// Check if "from" or "to" point to a gap between versions.
+		// If yes, then change the incorrect position to the proper side of the gap.
+		// Thanks to it, it will be possible to get index of the operation.
+		for ( const [ gapFrom, gapTo ] of this._gaps ) {
+			if ( fromBaseVersion > gapFrom && fromBaseVersion < gapTo ) {
+				fromBaseVersion = gapTo;
+			}
 
-		for ( const operation of this._operations ) {
-			if ( operation.baseVersion >= from && operation.baseVersion < to ) {
-				operations.push( operation );
+			if ( inclusiveTo > gapFrom && inclusiveTo < gapTo ) {
+				inclusiveTo = gapFrom - 1;
 			}
 		}
 
-		return operations;
+		// If the whole range is outside of the operation versions, then return an empty array.
+		if ( inclusiveTo < firstOperation.baseVersion || fromBaseVersion > this.lastOperation.baseVersion ) {
+			return [];
+		}
+
+		let fromIndex = this._baseVersionToOperationIndex.get( fromBaseVersion );
+
+		// If the range starts before the first operation, then use the first operation as the range's start.
+		if ( fromIndex === undefined ) {
+			fromIndex = 0;
+		}
+
+		let toIndex = this._baseVersionToOperationIndex.get( inclusiveTo );
+
+		// If the range ends after the last operation, then use the last operation as the range's end.
+		if ( toIndex === undefined ) {
+			toIndex = this._operations.length - 1;
+		}
+
+		// Return the part of the history operations based on the calculated start index and end index.
+		return this._operations.slice(
+			fromIndex,
+
+			// The `toIndex` should be included in the returned operations, so add `1`.
+			toIndex + 1
+		);
 	}
 
 	/**
@@ -86,11 +210,13 @@ export default class History {
 	 * there is no such operation in history.
 	 */
 	getOperation( baseVersion ) {
-		for ( const operation of this._operations ) {
-			if ( operation.baseVersion == baseVersion ) {
-				return operation;
-			}
+		const operationIndex = this._baseVersionToOperationIndex.get( baseVersion );
+
+		if ( operationIndex === undefined ) {
+			return;
 		}
+
+		return this._operations[ operationIndex ];
 	}
 
 	/**
@@ -135,4 +261,16 @@ export default class History {
 	getUndoneOperation( undoingOperation ) {
 		return this._undoPairs.get( undoingOperation );
 	}
+
+	/**
+	 * Resets the history of operations.
+	 */
+	reset() {
+		this._version = 0;
+		this._undoPairs = new Map();
+		this._operations = [];
+		this._undoneOperations = new Set();
+		this._gaps = new Map();
+		this._baseVersionToOperationIndex = new Map();
+	}
 }

package/src/model/markercollection.js

@@ -106,6 +106,8 @@ export default class MarkerCollection {
 		const oldMarker = this._markers.get( markerName );
 
 		if ( oldMarker ) {
+			const oldMarkerData = oldMarker.getData();
+
 			const oldRange = oldMarker.getRange();
 			let hasChanged = false;
 
@@ -125,7 +127,7 @@ export default class MarkerCollection {
 			}
 
 			if ( hasChanged ) {
-				this.fire( 'update:' + markerName, oldMarker, oldRange, range );
+				this.fire( 'update:' + markerName, oldMarker, oldRange, range, oldMarkerData );
 			}
 
 			return oldMarker;
@@ -135,7 +137,7 @@ export default class MarkerCollection {
 		const marker = new Marker( markerName, liveRange, managedUsingOperations, affectsData );
 
 		this._markers.set( markerName, marker );
-		this.fire( 'update:' + markerName, marker, null, range );
+		this.fire( 'update:' + markerName, marker, null, range, { ...marker.getData(), range: null } );
 
 		return marker;
 	}
@@ -154,7 +156,7 @@ export default class MarkerCollection {
 
 		if ( oldMarker ) {
 			this._markers.delete( markerName );
-			this.fire( 'update:' + markerName, oldMarker, oldMarker.getRange(), null );
+			this.fire( 'update:' + markerName, oldMarker, oldMarker.getRange(), null, oldMarker.getData() );
 
 			this._destroyMarker( oldMarker );
 
@@ -188,7 +190,7 @@ export default class MarkerCollection {
 
 		const range = marker.getRange();
 
-		this.fire( 'update:' + markerName, marker, range, range, marker.managedUsingOperations, marker.affectsData );
+		this.fire( 'update:' + markerName, marker, range, range, marker.getData() );
 	}
 
 	/**
@@ -273,11 +275,20 @@ export default class MarkerCollection {
 	 * means that marker is just added.
 	 * @param {module:engine/model/range~Range|null} newRange Marker range after update. When is not defined it
 	 * means that marker is just removed.
+	 * @param {module:engine/model/markercollection~MarkerData} oldMarkerData Data of the marker before the change.
 	 */
 }
 
 mix( MarkerCollection, EmitterMixin );
 
+/**
+ * @typedef {Object} module:engine/model/markercollection~MarkerData
+ *
+ * @property {module:engine/model/range~Range|null} range Marker range. `null` if the marker was removed.
+ * @property {Boolean} affectsData A property defining if the marker affects data.
+ * @property {Boolean} managedUsingOperations A property defining if the marker is managed using operations.
+ */
+
 /**
  * `Marker` is a continuous parts of model (like a range), is named and represent some kind of information about marked
  * part of model document. In contrary to {@link module:engine/model/node~Node nodes}, which are building blocks of
@@ -418,6 +429,19 @@ class Marker {
 		return this._affectsData;
 	}
 
+	/**
+	 * Returns the marker data (properties defining the marker).
+	 *
+	 * @returns {module:engine/model/markercollection~MarkerData}
+	 */
+	getData() {
+		return {
+			range: this.getRange(),
+			affectsData: this.affectsData,
+			managedUsingOperations: this.managedUsingOperations
+		};
+	}
+
 	/**
 	 * Returns current marker start position.
 	 *

package/src/model/model.js

@@ -21,6 +21,7 @@ import ModelSelection from './selection';
 import OperationFactory from './operation/operationfactory';
 
 import insertContent from './utils/insertcontent';
+import insertObject from './utils/insertobject';
 import deleteContent from './utils/deletecontent';
 import modifySelection from './utils/modifyselection';
 import getSelectedContent from './utils/getselectedcontent';
@@ -80,7 +81,7 @@ export default class Model {
 		 */
 		this._currentWriter = null;
 
-		[ 'insertContent', 'deleteContent', 'modifySelection', 'getSelectedContent', 'applyOperation' ]
+		[ 'insertContent', 'insertObject', 'deleteContent', 'modifySelection', 'getSelectedContent', 'applyOperation' ]
 			.forEach( methodName => this.decorate( methodName ) );
 
 		// Adding operation validation with `highest` priority, so it is called before any other feature would like
@@ -96,11 +97,28 @@ export default class Model {
 			isLimit: true
 		} );
 
+		this.schema.register( '$container', {
+			allowIn: [ '$root', '$container' ]
+		} );
+
 		this.schema.register( '$block', {
-			allowIn: '$root',
+			allowIn: [ '$root', '$container' ],
 			isBlock: true
 		} );
 
+		this.schema.register( '$blockObject', {
+			allowWhere: '$block',
+			isBlock: true,
+			isObject: true
+		} );
+
+		this.schema.register( '$inlineObject', {
+			allowWhere: '$text',
+			allowAttributesOf: '$text',
+			isInline: true,
+			isObject: true
+		} );
+
 		this.schema.register( '$text', {
 			allowIn: '$block',
 			isInline: true,
@@ -215,7 +233,7 @@ export default class Model {
 	 *
 	 * Second, it lets you define the {@link module:engine/model/batch~Batch} into which you want to add your changes.
 	 * By default, a new batch with the default {@link module:engine/model/batch~Batch#constructor batch type} is created.
-	 * In the sample above, `change` and `enqueueChange` blocks will use a different batch (and a different
+	 * In the sample above, the `change` and `enqueueChange` blocks will use a different batch (and a different
 	 * {@link module:engine/model/writer~Writer} instance since each of them operates on a separate batch).
 	 *
 	 *		model.enqueueChange( { isUndoable: false }, writer => {
@@ -304,6 +322,9 @@ export default class Model {
 	 * Inserts content at the position in the editor specified by the selection, as one would expect the paste
 	 * functionality to work.
 	 *
+	 * **Note**: If you want to insert an {@glink framework/guides/deep-dive/schema#object-elements object element}
+	 * (e.g. a {@link module:widget/utils~toWidget widget}), see {@link #insertObject} instead.
+	 *
 	 * This is a high-level method. It takes the {@link #schema schema} into consideration when inserting
 	 * the content, clears the given selection's content before inserting nodes and moves the selection
 	 * to its target position at the end of the process.
@@ -435,6 +456,89 @@ export default class Model {
 		return insertContent( this, content, selectable, placeOrOffset );
 	}
 
+	/**
+	 * Inserts an {@glink framework/guides/deep-dive/schema#object-elements object element} at a specific position in the editor content.
+	 *
+	 * This is a high-level API:
+	 * * It takes the {@link #schema schema} into consideration,
+	 * * It clears the content of passed `selectable` before inserting,
+	 * * It can move the selection at the end of the process,
+	 * * It will copy the selected block's attributes to preserve them upon insertion,
+	 * * It can split elements or wrap inline objects with paragraphs if they are not allowed in target position,
+	 * * etc.
+	 *
+	 * # Notes
+	 *
+	 * * If you want to insert a non-object content, see {@link #insertContent} instead.
+	 * * For lower-level API, see {@link module:engine/model/writer~Writer `Writer`}.
+	 * * Unlike {@link module:engine/model/writer~Writer `Writer`}, this method does not have to be used inside
+	 * a {@link #change `change()` block}.
+	 * * Inserting object into the model is not enough to make CKEditor 5 render that content to the user.
+	 * CKEditor 5 implements a model-view-controller architecture and what `model.insertObject()` does
+	 * is only adding nodes to the model. Additionally, you need to define
+	 * {@glink framework/guides/architecture/editing-engine#conversion converters} between the model and view
+	 * and define those nodes in the {@glink framework/guides/architecture/editing-engine#schema schema}.
+	 *
+	 * # Examples
+	 *
+	 * Use the following code to insert an object at the current selection and keep the selection on the inserted element:
+	 *
+	 *		const rawHtmlEmbedElement = writer.createElement( 'rawHtml' );
+	 *
+	 *		model.insertObject( rawHtmlEmbedElement, null, null, {
+	 *			setSelection: 'on'
+	 *		} );
+	 *
+	 * Use the following code to insert an object at the current selection and nudge the selection after the inserted object:
+	 *
+	 *		const pageBreakElement = writer.createElement( 'pageBreak' );
+ 	 *
+	 *		model.insertObject( pageBreakElement, null, null, {
+	 *			setSelection: 'after'
+	 *		} );
+	 *
+	 * Use the following code to insert an object at the current selection and avoid splitting the content (non-destructive insertion):
+	 *
+	 *		const tableElement = writer.createElement( 'table' );
+ 	 *
+	 *		model.insertObject( tableElement, null, null, {
+	 *			findOptimalPosition: 'auto'
+	 *		} );
+	 *
+	 * Use the following code to insert an object at the specific range (also: replace the content of the range):
+	 *
+	 *		const tableElement = writer.createElement( 'table' );
+	 *		const range = model.createRangeOn( model.document.getRoot().getChild( 1 ) );
+ 	 *
+	 *		model.insertObject( tableElement, range );
+	 *
+	 * @param {module:engine/model/element~Element} object An object to be inserted into the model document.
+	 * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
+	 * A selectable where the content should be inserted. If not specified, the current
+	 * {@link module:engine/model/document~Document#selection document selection} will be used instead.
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} placeOrOffset Specifies the exact place or offset for the insertion to take place,
+	 * relative to `selectable`.
+	 * @param {Object} [options] Additional options.
+	 * @param {'auto'|'before'|'after'} [options.findOptimalPosition] An option that, when set, adjusts the insertion position (relative to
+	 * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
+	 * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
+	 * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
+	 * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
+	 *
+	 * Note that this option only works for block objects. Inline objects are inserted into text and do not split blocks.
+	 * @param {'on'|'after'} [options.setSelection] An option that, when set, moves the
+	 * {@link module:engine/model/document~Document#selection document selection} after inserting the object.
+	 * * When `'on'`, the document selection will be set on the inserted object.
+	 * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
+	 * such text node, a paragraph will be created and the document selection will be moved inside it.
+	 * @returns {module:engine/model/range~Range} A range which contains all the performed changes. This is a range that, if removed,
+	 * would return the model to the state before the insertion. If no changes were preformed by `insertObject()`, returns a range collapsed
+	 * at the insertion position.
+	 */
+	insertObject( object, selectable, placeOrOffset, options ) {
+		return insertObject( this, object, selectable, placeOrOffset, options );
+	}
+
 	/**
 	 * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
 	 *
@@ -516,6 +620,7 @@ export default class Model {
 	 * @param {Object} [options]
 	 * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
 	 * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
+	 * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
 	 */
 	modifySelection( selection, options ) {
 		modifySelection( this, selection, options );
@@ -902,12 +1007,25 @@ export default class Model {
 	 * listener to this event so it can be fully customized by the features.
 	 *
 	 * **Note** The `selectable` parameter for the {@link #insertContent} is optional. When `undefined` value is passed the method uses
-	 * `model.document.selection`.
+	 * {@link module:engine/model/document~Document#selection document selection}.
 	 *
 	 * @event insertContent
 	 * @param {Array} args The arguments passed to the original method.
 	 */
 
+	/**
+	 * Event fired when the {@link #insertObject} method is called.
+	 *
+	 * The {@link #insertObject default action of that method} is implemented as a
+	 * listener to this event so it can be fully customized by the features.
+	 *
+	 * **Note** The `selectable` parameter for the {@link #insertObject} is optional. When `undefined` value is passed the method uses
+	 * {@link module:engine/model/document~Document#selection document selection}.
+	 *
+	 * @event insertObject
+	 * @param {Array} args The arguments passed to the original method.
+	 */
+
 	/**
 	 * Event fired when {@link #deleteContent} method is called.
 	 *