@ckeditor/ckeditor5-engine 33.0.0 → 34.2.0

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

@@ -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,
@@ -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.
 	 *
@@ -903,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.
 	 *

package/src/model/schema.js

@@ -834,6 +834,23 @@ export default class Schema {
 		return null;
 	}
 
+	/**
+	 * 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.
+	 * @param {module:engine/model/writer~Writer} writer An instance of the model writer.
+	 */
+	setAllowedAttributes( node, attributes, writer ) {
+		const model = writer.model;
+
+		for ( const [ attributeName, attributeValue ] of Object.entries( attributes ) ) {
+			if ( model.schema.checkAttribute( node, attributeName ) ) {
+				writer.setAttribute( attributeName, attributeValue, node );
+			}
+		}
+	}
+
 	/**
 	 * Removes attributes disallowed by the schema.
 	 *
@@ -863,6 +880,34 @@ export default class Schema {
 		}
 	}
 
+	/**
+	 * 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.
+	 * @param {Boolean|Symbol|String|Number|Object|null|undefined} propertyValue Desired value of the property that we want to check.
+	 * When `undefined` attributes will be returned if they have set a given property no matter what the value is. If specified it will
+	 * return attributes which given property's value is equal to this parameter.
+	 * @returns {Object} Object with attributes' names as key and attributes' values as value.
+	 */
+	getAttributesWithProperty( node, propertyName, propertyValue ) {
+		const attributes = {};
+
+		for ( const [ attributeName, attributeValue ] of node.getAttributes() ) {
+			const attributeProperties = this.getAttributeProperties( attributeName );
+
+			if ( attributeProperties[ propertyName ] === undefined ) {
+				continue;
+			}
+
+			if ( propertyValue === undefined || propertyValue === attributeProperties[ propertyName ] ) {
+				attributes[ attributeName ] = attributeValue;
+			}
+		}
+
+		return attributes;
+	}
+
 	/**
 	 * Creates an instance of the schema context.
 	 *
@@ -1135,19 +1180,39 @@ mix( Schema, ObservableMixin );
  *
  * # Generic items
  *
- * There are three basic generic items: `$root`, `$block` and `$text`.
- * They are defined as follows:
+ * There are several generic items (classes of elements) available: `$root`, `$container`, `$block`, `$blockObject`,
+ * `$inlineObject`, and `$text`. They are defined as follows:
  *
- *		this.schema.register( '$root', {
+ *		schema.register( '$root', {
  *			isLimit: true
  *		} );
- *		this.schema.register( '$block', {
- *			allowIn: '$root',
+ *
+ *		schema.register( '$container', {
+ *			allowIn: [ '$root', '$container' ]
+ *		} );
+ *
+ *		schema.register( '$block', {
+ *			allowIn: [ '$root', '$container' ],
  *			isBlock: true
  *		} );
- *		this.schema.register( '$text', {
+ *
+ *		schema.register( '$blockObject', {
+ *			allowWhere: '$block',
+ *			isBlock: true,
+ *			isObject: true
+ *		} );
+ *
+ *		schema.register( '$inlineObject', {
+ *			allowWhere: '$text',
+ *			allowAttributesOf: '$text',
+ *			isInline: true,
+ *			isObject: true
+ *		} );
+ *
+ *		schema.register( '$text', {
  *			allowIn: '$block',
- *			isInline: true
+ *			isInline: true,
+ *			isContent: true
  *		} );
  *
  * They reflect typical editor content that is contained within one root, consists of several blocks
@@ -1180,14 +1245,18 @@ mix( Schema, ObservableMixin );
  *			isBlock: true
  *		} );
  *
+ * The previous rule can be written in a shorter form using inheritance:
+ *
+ *		schema.register( 'paragraph', {
+ *			inheritAllFrom: '$block'
+ *		} );
+ *
  * Make `imageBlock` a block object, which is allowed everywhere where `$block` is.
  * Also, allow `src` and `alt` attributes in it:
  *
  *		schema.register( 'imageBlock', {
- *			allowWhere: '$block',
+ *			inheritAllFrom: '$blockObject',
  *			allowAttributes: [ 'src', 'alt' ],
- *			isBlock: true,
- *			isObject: true
  *		} );
  *
  * Make `caption` allowed in `imageBlock` and make it allow all the content of `$block`s (usually, `$text`).

package/src/model/treewalker.js

@@ -233,9 +233,8 @@ export default class TreeWalker {
 
 		// Get node just after the current position.
 		// Use a highly optimized version instead of checking the text node first and then getting the node after. See #6582.
-		const positionParent = position.parent;
-		const textNodeAtPosition = getTextNodeAtPosition( position, positionParent );
-		const node = textNodeAtPosition ? textNodeAtPosition : getNodeAfterPosition( position, positionParent, textNodeAtPosition );
+		const textNodeAtPosition = getTextNodeAtPosition( position, parent );
+		const node = textNodeAtPosition ? textNodeAtPosition : getNodeAfterPosition( position, parent, textNodeAtPosition );
 
 		if ( node instanceof Element ) {
 			if ( !this.shallow ) {

package/src/model/utils/deletecontent.js

@@ -80,6 +80,17 @@ export default function deleteContent( model, selection, options = {} ) {
 			return;
 		}
 
+		// Collect attributes to copy in case of autoparagraphing.
+		const attributesForAutoparagraph = {};
+
+		if ( !options.doNotAutoparagraph ) {
+			const selectedElement = selection.getSelectedElement();
+
+			if ( selectedElement ) {
+				Object.assign( attributesForAutoparagraph, schema.getAttributesWithProperty( selectedElement, 'copyOnReplace', true ) );
+			}
+		}
+
 		// Get the live positions for the range adjusted to span only blocks selected from the user perspective.
 		const [ startPosition, endPosition ] = getLivePositionsForSelectedBlocks( selRange );
 
@@ -114,7 +125,7 @@ export default function deleteContent( model, selection, options = {} ) {
 		// Check if a text is allowed in the new container. If not, try to create a new paragraph (if it's allowed here).
 		// If autoparagraphing is off, we assume that you know what you do so we leave the selection wherever it was.
 		if ( !options.doNotAutoparagraph && shouldAutoparagraph( schema, startPosition ) ) {
-			insertParagraph( writer, startPosition, selection );
+			insertParagraph( writer, startPosition, selection, attributesForAutoparagraph );
 		}
 
 		startPosition.detach();
@@ -482,9 +493,11 @@ function isCrossingLimitElement( leftPos, rightPos, schema ) {
 	return true;
 }
 
-function insertParagraph( writer, position, selection ) {
+function insertParagraph( writer, position, selection, attributes = {} ) {
 	const paragraph = writer.createElement( 'paragraph' );
 
+	writer.model.schema.setAllowedAttributes( paragraph, attributes, writer );
+
 	writer.insert( paragraph, position );
 
 	collapseSelectionAt( writer, selection, writer.createPositionAt( paragraph, 0 ) );

package/src/model/utils/findoptimalinsertionrange.js

@@ -0,0 +1,68 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/model/utils/findoptimalinsertionrange
+ */
+
+import first from '@ckeditor/ckeditor5-utils/src/first';
+
+// Returns a model range which is optimal (in terms of UX) for inserting a widget block.
+//
+// For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
+// will be returned so that it is not split. If the selection is at the end of a paragraph,
+// the collapsed range after this paragraph will be returned.
+//
+// Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
+// is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
+// by the inserted widget block.
+//
+// **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 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'] 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();
+
+	if ( selectedElement && model.schema.isObject( selectedElement ) && !model.schema.isInline( selectedElement ) ) {
+		if ( [ 'before', 'after' ].includes( place ) ) {
+			return model.createRange( model.createPositionAt( selectedElement, place ) );
+		}
+
+		return model.createRangeOn( selectedElement );
+	}
+
+	const firstBlock = first( selection.getSelectedBlocks() );
+
+	// There are no block elements within ancestors (in the current limit element).
+	if ( !firstBlock ) {
+		return model.createRange( selection.focus );
+	}
+
+	// If inserting into an empty block – return position in that block. It will get
+	// replaced with the image by insertContent(). #42.
+	if ( firstBlock.isEmpty ) {
+		return model.createRange( model.createPositionAt( firstBlock, 0 ) );
+	}
+
+	const positionAfter = model.createPositionAfter( firstBlock );
+
+	// If selection is at the end of the block - return position after the block.
+	if ( selection.focus.isTouching( positionAfter ) ) {
+		return model.createRange( positionAfter );
+	}
+
+	// Otherwise, return position before the block.
+	return model.createRange( model.createPositionBefore( firstBlock ) );
+}