@ckeditor/ckeditor5-engine 34.0.0 → 35.0.0

package/LICENSE.md

@@ -2,7 +2,7 @@ Software License Agreement
 ==========================
 
 **CKEditor 5 editing engine** – https://github.com/ckeditor/ckeditor5-engine <br>
-Copyright (c) 2003-2022, [CKSource](http://cksource.com) Holding sp. z o.o. All rights reserved.
+Copyright (c) 2003-2022, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
 
@@ -11,7 +11,11 @@ Sources of Intellectual Property Included in CKEditor
 
 Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
 
+The following libraries are included in CKEditor under the [MIT license](https://opensource.org/licenses/MIT):
+
+* lodash - Copyright (c) JS Foundation and other contributors https://js.foundation/. Based on Underscore.js, copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors http://underscorejs.org/.
+
 Trademarks
 ----------
 
-**CKEditor** is a trademark of [CKSource](http://cksource.com) Holding sp. z o.o. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.
+**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "34.0.0",
+  "version": "35.0.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,30 +23,30 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "^34.0.0",
+    "@ckeditor/ckeditor5-utils": "^35.0.0",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^34.0.0",
-    "@ckeditor/ckeditor5-block-quote": "^34.0.0",
-    "@ckeditor/ckeditor5-clipboard": "^34.0.0",
-    "@ckeditor/ckeditor5-cloud-services": "^34.0.0",
-    "@ckeditor/ckeditor5-core": "^34.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^34.0.0",
-    "@ckeditor/ckeditor5-enter": "^34.0.0",
-    "@ckeditor/ckeditor5-essentials": "^34.0.0",
-    "@ckeditor/ckeditor5-heading": "^34.0.0",
-    "@ckeditor/ckeditor5-image": "^34.0.0",
-    "@ckeditor/ckeditor5-link": "^34.0.0",
-    "@ckeditor/ckeditor5-list": "^34.0.0",
-    "@ckeditor/ckeditor5-mention": "^34.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^34.0.0",
-    "@ckeditor/ckeditor5-table": "^34.0.0",
-    "@ckeditor/ckeditor5-theme-lark": "^34.0.0",
-    "@ckeditor/ckeditor5-typing": "^34.0.0",
-    "@ckeditor/ckeditor5-ui": "^34.0.0",
-    "@ckeditor/ckeditor5-undo": "^34.0.0",
-    "@ckeditor/ckeditor5-widget": "^34.0.0",
+    "@ckeditor/ckeditor5-basic-styles": "^35.0.0",
+    "@ckeditor/ckeditor5-block-quote": "^35.0.0",
+    "@ckeditor/ckeditor5-clipboard": "^35.0.0",
+    "@ckeditor/ckeditor5-cloud-services": "^35.0.0",
+    "@ckeditor/ckeditor5-core": "^35.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^35.0.0",
+    "@ckeditor/ckeditor5-enter": "^35.0.0",
+    "@ckeditor/ckeditor5-essentials": "^35.0.0",
+    "@ckeditor/ckeditor5-heading": "^35.0.0",
+    "@ckeditor/ckeditor5-image": "^35.0.0",
+    "@ckeditor/ckeditor5-link": "^35.0.0",
+    "@ckeditor/ckeditor5-list": "^35.0.0",
+    "@ckeditor/ckeditor5-mention": "^35.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^35.0.0",
+    "@ckeditor/ckeditor5-table": "^35.0.0",
+    "@ckeditor/ckeditor5-theme-lark": "^35.0.0",
+    "@ckeditor/ckeditor5-typing": "^35.0.0",
+    "@ckeditor/ckeditor5-ui": "^35.0.0",
+    "@ckeditor/ckeditor5-undo": "^35.0.0",
+    "@ckeditor/ckeditor5-widget": "^35.0.0",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
   },
@@ -67,6 +67,7 @@
     "lang",
     "src",
     "theme",
-    "ckeditor5-metadata.json"
+    "ckeditor5-metadata.json",
+    "CHANGELOG.md"
   ]
 }

package/src/conversion/upcastdispatcher.js

@@ -152,9 +152,9 @@ export default class UpcastDispatcher {
 		this._modelCursor = null;
 
 		/**
-		 * The list of elements that were created during splitting but should not get removed on conversion end even if they are empty.
+		 * The list of elements that were created during the splitting but should not get removed on conversion end even if they are empty.
 		 *
-		 * After the conversion process the list is cleared.
+		 * The list is cleared after the conversion process.
 		 *
 		 * @private
 		 * @type {Set.<module:engine/model/element~Element>}
@@ -464,7 +464,7 @@ export default class UpcastDispatcher {
 	}
 
 	/**
-	 * Mark an element that were created during splitting that it should not get removed on conversion end even if it's empty.
+	 * Mark an element that were created during the splitting to not get removed on conversion end even if it is empty.
 	 *
 	 * @private
 	 */
@@ -779,7 +779,7 @@ function createContextTree( contextDefinition, writer ) {
  */
 
 /**
- * Mark an element that was created during splitting that it should not get removed on conversion end even if it's empty.
+ * Mark an element that was created during splitting to not get removed on conversion end even if it is empty.
  *
  * **Note:** This is an advanced method. For most cases you will not need to keep the split empty element.
  *

package/src/conversion/upcasthelpers.js

@@ -465,6 +465,11 @@ export function convertText() {
 				return;
 			}
 
+			// Do not auto-paragraph whitespaces.
+			if ( data.viewItem.data.trim().length == 0 ) {
+				return;
+			}
+
 			position = wrapInParagraph( position, writer );
 		}
 
@@ -867,6 +872,13 @@ function prepareToAttributeConverter( config, shallow ) {
 	const matcher = new Matcher( config.view );
 
 	return ( evt, data, conversionApi ) => {
+		// Converting an attribute of an element that has not been converted to anything does not make sense
+		// because there will be nowhere to set that attribute on. At this stage, the element should've already
+		// been converted (https://github.com/ckeditor/ckeditor5/issues/11000).
+		if ( !data.modelRange && shallow ) {
+			return;
+		}
+
 		const match = matcher.match( data.viewItem );
 
 		// If there is no match, this callback should not do anything.
@@ -877,7 +889,8 @@ function prepareToAttributeConverter( config, shallow ) {
 		if ( onlyViewNameIsDefined( config.view, data.viewItem ) ) {
 			match.match.name = true;
 		} else {
-			// Do not test or consume `name` consumable.
+			// Do not test `name` consumable because it could get consumed already while upcasting some other attribute
+			// on the same element (for example <span class="big" style="color: red">foo</span>).
 			delete match.match.name;
 		}
 
@@ -908,6 +921,15 @@ function prepareToAttributeConverter( config, shallow ) {
 		// It may happen that a converter will try to set an attribute that is not allowed in the given context.
 		// In such a situation we cannot consume the attribute. See: https://github.com/ckeditor/ckeditor5/pull/9249#issuecomment-815658459.
 		if ( attributeWasSet ) {
+			// Verify if the element itself wasn't consumed yet. It could be consumed already while upcasting some other attribute
+			// on the same element (for example <span class="big" style="color: red">foo</span>).
+			// We need to consume it so other features (especially GHS) won't try to convert it.
+			// Note that it's not tested by the other element-to-attribute converters whether an element was consumed before
+			// (in case of converters that the element itself is just a context and not the primary information to convert).
+			if ( conversionApi.consumable.test( data.viewItem, { name: true } ) ) {
+				match.match.name = true;
+			}
+
 			conversionApi.consumable.consume( data.viewItem, match.match );
 		}
 	};

package/src/dataprocessor/htmldataprocessor.js

@@ -7,7 +7,7 @@
  * @module engine/dataprocessor/htmldataprocessor
  */
 
-/* globals document, DOMParser */
+/* globals DOMParser */
 
 import BasicHtmlWriter from './basichtmlwriter';
 import DomConverter from '../view/domconverter';
@@ -56,7 +56,7 @@ export default class HtmlDataProcessor {
 	 */
 	toData( viewFragment ) {
 		// Convert view DocumentFragment to DOM DocumentFragment.
-		const domFragment = this.domConverter.viewToDom( viewFragment, document );
+		const domFragment = this.domConverter.viewToDom( viewFragment );
 
 		// Convert DOM DocumentFragment to HTML output.
 		return this.htmlWriter.getHtml( domFragment );

package/src/dataprocessor/xmldataprocessor.js

@@ -7,7 +7,7 @@
  * @module engine/dataprocessor/xmldataprocessor
  */
 
-/* globals DOMParser, document */
+/* globals DOMParser */
 
 import BasicHtmlWriter from './basichtmlwriter';
 import DomConverter from '../view/domconverter';
@@ -71,7 +71,7 @@ export default class XmlDataProcessor {
 	 */
 	toData( viewFragment ) {
 		// Convert view DocumentFragment to DOM DocumentFragment.
-		const domFragment = this.domConverter.viewToDom( viewFragment, document );
+		const domFragment = this.domConverter.viewToDom( viewFragment );
 
 		// Convert DOM DocumentFragment to XML output.
 		// There is no need to use dedicated for XML serializing method because BasicHtmlWriter works well in this case.

package/src/index.js

@@ -38,6 +38,11 @@ export { default as Renderer } from './view/renderer';
 export { default as ViewDocument } from './view/document';
 export { default as ViewText } from './view/text';
 export { default as ViewElement } from './view/element';
+export { default as ViewContainerElement } from './view/containerelement';
+export { default as ViewAttributeElement } from './view/attributeelement';
+export { default as ViewEmptyElement } from './view/emptyelement';
+export { default as ViewRawElement } from './view/rawelement';
+export { default as ViewUIElement } from './view/uielement';
 export { default as ViewDocumentFragment } from './view/documentfragment';
 
 export { getFillerOffset } from './view/containerelement';

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' } );
@@ -179,6 +152,25 @@ export default class Document {
 		} );
 	}
 
+	/**
+	 * 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/model.js

@@ -525,7 +525,7 @@ export default class Model {
 	 * * 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 works only for block objects. Inline objects are inserted into text and do not split blocks.
+	 * 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.
@@ -1014,7 +1014,7 @@ export default class Model {
 	 */
 
 	/**
-	 * Event fired when {@link #insertObject} method is called.
+	 * 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.

package/src/model/schema.js

@@ -835,7 +835,7 @@ export default class Schema {
 	}
 
 	/**
-	 * Sets attributes allowed by the schema on given node.
+	 * Sets attributes allowed by the schema on a given node.
 	 *
 	 * @param {module:engine/model/node~Node} node A node to set attributes on.
 	 * @param {Object} attributes Attributes keys and values.
@@ -881,7 +881,7 @@ export default class Schema {
 	}
 
 	/**
-	 * Gets attributes of a node that have given property.
+	 * Gets attributes of a node that have a given property.
 	 *
 	 * @param {module:engine/model/node~Node} node Node to get attributes from.
 	 * @param {String} propertyName Name of the property that attribute must have to return it.

package/src/model/utils/findoptimalinsertionrange.js

@@ -21,16 +21,16 @@ import first from '@ckeditor/ckeditor5-utils/src/first';
 //
 // **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
 // This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
-// in `widget` package and inside `engine` package.
+// in the `widget` package and inside the `engine` package.
 //
 // @private
 // @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
 // The selection based on which the insertion position should be calculated.
 // @param {module:engine/model/model~Model} model Model instance.
-// @param {'auto'|'before'|'after'} [place='auto'] Place where to look for optimal insertion range.
-// Default value `auto` will determine itself the best position for insertion.
-// Value `before` will try to find a position before selection.
-// Value `after` will try to find a position after selection.
+// @param {'auto'|'before'|'after'} [place='auto'] The place where to look for optimal insertion range.
+// The default `auto` value will determine itself the best position for insertion.
+// The `before` value will try to find a position before selection.
+// The `after` value will try to find a position after selection.
 // @returns {module:engine/model/range~Range} The optimal range.
 export function findOptimalInsertionRange( selection, model, place = 'auto' ) {
 	const selectedElement = selection.getSelectedElement();

package/src/model/utils/insertobject.js

@@ -129,9 +129,9 @@ export default function insertObject( model, object, selectable, placeOrOffset,
 //
 // @private
 // @param {module:engine/model/writer~Writer} writer An instance of the model writer.
-// @param {module:engine/model/element~Element} contextElement An element to set attributes on.
-// @param {'on'|'after'} place Place where selection should be set in relation to `contextElement` element.
-// Value `on` will set selection on passed `contextElement`. Value `after` will set selection after `contextElement`.
+// @param {module:engine/model/element~Element} contextElement An element to set the attributes on.
+// @param {'on'|'after'} place The place where selection should be set in relation to the `contextElement` element.
+// Value `on` will set selection on the passed `contextElement`. Value `after` will set selection after `contextElement`.
 // @param {Object} attributes Attributes keys and values to set on a paragraph that this function can create when
 // `place` parameter is equal to `after` but there is no element with `$text` node to set selection in.
 function updateSelection( writer, contextElement, place, paragraphAttributes ) {
@@ -161,9 +161,9 @@ function updateSelection( writer, contextElement, place, paragraphAttributes ) {
 	}
 	else {
 		/**
-		 * Unsupported `options.setSelection` parameter was passed
+		 * The unsupported `options.setSelection` parameter was passed
 		 * to the {@link module:engine/model/utils/insertobject insertObject()} function.
-		 * Check {@link module:engine/model/utils/insertobject insertObject()} API documentation for allowed
+		 * Check the {@link module:engine/model/utils/insertobject insertObject()} API documentation for allowed
 		 * `options.setSelection` parameter values.
 		 *
 		 * @error insertobject-invalid-place-parameter-value