@ckeditor/ckeditor5-engine 32.0.0 → 33.0.0

package/src/conversion/mapper.js

@@ -15,11 +15,12 @@ import ViewRange from '../view/range';
 import ViewText from '../view/text';
 
 import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Maps elements, positions and markers between {@link module:engine/view/document~Document the view} and
- * {@link module:engine/model/model the model}.
+ * Maps elements, positions and markers between the {@link module:engine/view/document~Document view} and
+ * the {@link module:engine/model/model model}.
  *
  * The instance of the Mapper used for the editing pipeline is available in
  * {@link module:engine/controller/editingcontroller~EditingController#mapper `editor.editing.mapper`}.
@@ -27,12 +28,12 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * Mapper uses bound elements to find corresponding elements and positions, so, to get proper results,
  * all model elements should be {@link module:engine/conversion/mapper~Mapper#bindElements bound}.
  *
- * To map complex model to/from view relations, you may provide custom callbacks for
+ * To map the complex model to/from view relations, you may provide custom callbacks for the
  * {@link module:engine/conversion/mapper~Mapper#event:modelToViewPosition modelToViewPosition event} and
  * {@link module:engine/conversion/mapper~Mapper#event:viewToModelPosition viewToModelPosition event} that are fired whenever
  * a position mapping request occurs.
- * Those events are fired by {@link module:engine/conversion/mapper~Mapper#toViewPosition toViewPosition}
- * and {@link module:engine/conversion/mapper~Mapper#toModelPosition toModelPosition} methods. `Mapper` adds it's own default callbacks
+ * Those events are fired by the {@link module:engine/conversion/mapper~Mapper#toViewPosition toViewPosition}
+ * and {@link module:engine/conversion/mapper~Mapper#toModelPosition toModelPosition} methods. `Mapper` adds its own default callbacks
  * with `'lowest'` priority. To override default `Mapper` mapping, add custom callback with higher priority and
  * stop the event.
  * @mixes module:utils/emittermixin~EmitterMixin
@@ -89,7 +90,15 @@ export default class Mapper {
 		this._elementToMarkerNames = new Map();
 
 		/**
-		 * Stores marker names of markers which has changed due to unbinding a view element (so it is assumed that the view element
+		 * The map of removed view elements with their current root (used for deferred unbinding).
+		 *
+		 * @private
+		 * @member {Map.<module:engine/view/element~Element,module:engine/view/documentfragment~DocumentFragment>}
+		 */
+		this._deferredBindingRemovals = new Map();
+
+		/**
+		 * Stores marker names of markers which have changed due to unbinding a view element (so it is assumed that the view element
 		 * has been removed, moved or renamed).
 		 *
 		 * @private
@@ -105,6 +114,18 @@ export default class Mapper {
 
 			const viewContainer = this._modelToViewMapping.get( data.modelPosition.parent );
 
+			if ( !viewContainer ) {
+				/**
+				 * A model position could not be mapped to the view because the parent of the model position
+				 * does not have a mapped view element (might have not been converted yet or it has no converter).
+				 *
+				 * Make sure that the model element is correctly converted to the view.
+				 *
+				 * @error mapping-view-position-parent-not-found
+				 */
+				throw new CKEditorError( 'mapping-view-position-parent-not-found', this, { modelPosition: data.modelPosition } );
+			}
+
 			data.viewPosition = this.findPositionIn( viewContainer, data.modelPosition.offset );
 		}, { priority: 'low' } );
 
@@ -137,37 +158,44 @@ export default class Mapper {
 	}
 
 	/**
-	 * Unbinds given {@link module:engine/view/element~Element view element} from the map.
+	 * Unbinds the given {@link module:engine/view/element~Element view element} from the map.
 	 *
 	 * **Note:** view-to-model binding will be removed, if it existed. However, corresponding model-to-view binding
-	 * will be removed only if model element is still bound to passed `viewElement`.
+	 * will be removed only if model element is still bound to the passed `viewElement`.
 	 *
-	 * This behavior lets for re-binding model element to another view element without fear of losing the new binding
+	 * This behavior allows for re-binding model element to another view element without fear of losing the new binding
 	 * when the previously bound view element is unbound.
 	 *
 	 * @param {module:engine/view/element~Element} viewElement View element to unbind.
+	 * @param {Object} [options={}] The options object.
+	 * @param {Boolean} [options.defer=false] Controls whether the binding should be removed immediately or deferred until a
+	 * {@link #flushDeferredBindings `flushDeferredBindings()`} call.
 	 */
-	unbindViewElement( viewElement ) {
+	unbindViewElement( viewElement, options = {} ) {
 		const modelElement = this.toModelElement( viewElement );
 
-		this._viewToModelMapping.delete( viewElement );
-
 		if ( this._elementToMarkerNames.has( viewElement ) ) {
 			for ( const markerName of this._elementToMarkerNames.get( viewElement ) ) {
 				this._unboundMarkerNames.add( markerName );
 			}
 		}
 
-		if ( this._modelToViewMapping.get( modelElement ) == viewElement ) {
-			this._modelToViewMapping.delete( modelElement );
+		if ( options.defer ) {
+			this._deferredBindingRemovals.set( viewElement, viewElement.root );
+		} else {
+			this._viewToModelMapping.delete( viewElement );
+
+			if ( this._modelToViewMapping.get( modelElement ) == viewElement ) {
+				this._modelToViewMapping.delete( modelElement );
+			}
 		}
 	}
 
 	/**
-	 * Unbinds given {@link module:engine/model/element~Element model element} from the map.
+	 * Unbinds the given {@link module:engine/model/element~Element model element} from the map.
 	 *
-	 * **Note:** model-to-view binding will be removed, if it existed. However, corresponding view-to-model binding
-	 * will be removed only if view element is still bound to passed `modelElement`.
+	 * **Note:** the model-to-view binding will be removed, if it existed. However, the corresponding view-to-model binding
+	 * will be removed only if the view element is still bound to the passed `modelElement`.
 	 *
 	 * This behavior lets for re-binding view element to another model element without fear of losing the new binding
 	 * when the previously bound model element is unbound.
@@ -185,8 +213,8 @@ export default class Mapper {
 	}
 
 	/**
-	 * Binds given marker name with given {@link module:engine/view/element~Element view element}. The element
-	 * will be added to the current set of elements bound with given marker name.
+	 * Binds the given marker name with the given {@link module:engine/view/element~Element view element}. The element
+	 * will be added to the current set of elements bound with the given marker name.
 	 *
 	 * @param {module:engine/view/element~Element} element Element to bind.
 	 * @param {String} name Marker name.
@@ -231,7 +259,7 @@ export default class Mapper {
 	}
 
 	/**
-	 * Returns all marker names of markers which has changed due to unbinding a view element (so it is assumed that the view element
+	 * Returns all marker names of markers which have changed due to unbinding a view element (so it is assumed that the view element
 	 * has been removed, moved or renamed) since the last flush. After returning, the marker names list is cleared.
 	 *
 	 * @returns {Array.<String>}
@@ -244,6 +272,22 @@ export default class Mapper {
 		return markerNames;
 	}
 
+	/**
+	 * Unbinds all deferred binding removals of view elements that in the meantime were not re-attached to some root or document fragment.
+	 *
+	 * See: {@link #unbindViewElement `unbindViewElement()`}.
+	 */
+	flushDeferredBindings() {
+		for ( const [ viewElement, root ] of this._deferredBindingRemovals ) {
+			// Unbind it only if it wasn't re-attached to some root or document fragment.
+			if ( viewElement.root == root ) {
+				this.unbindViewElement( viewElement );
+			}
+		}
+
+		this._deferredBindingRemovals = new Map();
+	}
+
 	/**
 	 * Removes all model to view and view to model bindings.
 	 */
@@ -253,6 +297,7 @@ export default class Mapper {
 		this._markerNameToElements = new Map();
 		this._elementToMarkerNames = new Map();
 		this._unboundMarkerNames = new Set();
+		this._deferredBindingRemovals = new Map();
 	}
 
 	/**
@@ -341,8 +386,8 @@ export default class Mapper {
 	 * Gets all view elements bound to the given marker name.
 	 *
 	 * @param {String} name Marker name.
-	 * @returns {Set.<module:engine/view/element~Element>|null} View elements bound with given marker name or `null`
-	 * if no elements are bound to given marker name.
+	 * @returns {Set.<module:engine/view/element~Element>|null} View elements bound with the given marker name or `null`
+	 * if no elements are bound to the given marker name.
 	 */
 	markerNameToElements( name ) {
 		const boundElements = this._markerNameToElements.get( name );
@@ -367,10 +412,10 @@ export default class Mapper {
 	}
 
 	/**
-	 * Registers a callback that evaluates the length in the model of a view element with given name.
+	 * Registers a callback that evaluates the length in the model of a view element with the given name.
 	 *
 	 * The callback is fired with one argument, which is a view element instance. The callback is expected to return
-	 * a number representing the length of view element in model.
+	 * a number representing the length of the view element in the model.
 	 *
 	 *		// List item in view may contain nested list, which have other list items. In model though,
 	 *		// the lists are represented by flat structure. Because of those differences, length of list view element
@@ -400,10 +445,10 @@ export default class Mapper {
 	}
 
 	/**
-	 * For given `viewPosition`, finds and returns the closest ancestor of this position that has a mapping to
+	 * For the given `viewPosition`, finds and returns the closest ancestor of this position that has a mapping to
 	 * the model.
 	 *
-	 * @param {module:engine/view/position~Position} viewPosition Position for which mapped ancestor should be found.
+	 * @param {module:engine/view/position~Position} viewPosition Position for which a mapped ancestor should be found.
 	 * @returns {module:engine/view/element~Element}
 	 */
 	findMappedViewAncestor( viewPosition ) {
@@ -464,17 +509,17 @@ export default class Mapper {
 	 * Gets the length of the view element in the model.
 	 *
 	 * The length is calculated as follows:
-	 * * if {@link #registerViewToModelLength length mapping callback} is provided for given `viewNode` it is used to
-	 * evaluate model length (`viewNode` is used as first and only parameter passed to the callback),
-	 * * length of a {@link module:engine/view/text~Text text node} is equal to the length of it's
+	 * * if a {@link #registerViewToModelLength length mapping callback} is provided for the given `viewNode`, it is used to
+	 * evaluate the model length (`viewNode` is used as first and only parameter passed to the callback),
+	 * * length of a {@link module:engine/view/text~Text text node} is equal to the length of its
 	 * {@link module:engine/view/text~Text#data data},
 	 * * length of a {@link module:engine/view/uielement~UIElement ui element} is equal to 0,
 	 * * length of a mapped {@link module:engine/view/element~Element element} is equal to 1,
-	 * * length of a not-mapped {@link module:engine/view/element~Element element} is equal to the length of it's children.
+	 * * length of a non-mapped {@link module:engine/view/element~Element element} is equal to the length of its children.
 	 *
 	 * Examples:
 	 *
-	 *		foo                          -> 3 // Text length is equal to it's data length.
+	 *		foo                          -> 3 // Text length is equal to its data length.
 	 *		<p>foo</p>                   -> 1 // Length of an element which is mapped is by default equal to 1.
 	 *		<b>foo</b>                   -> 3 // Length of an element which is not mapped is a length of its children.
 	 *		<div><p>x</p><p>y</p></div>  -> 2 // Assuming that <div> is not mapped and <p> are mapped.
@@ -505,7 +550,7 @@ export default class Mapper {
 	}
 
 	/**
-	 * Finds the position in the view node (or its children) with the expected model offset.
+	 * Finds the position in the view node (or in its children) with the expected model offset.
 	 *
 	 * Example:
 	 *
@@ -537,7 +582,7 @@ export default class Mapper {
 		let modelOffset = 0;
 		let viewOffset = 0;
 
-		// In the text node it is simple: offset in the model equals offset in the text.
+		// In the text node it is simple: the offset in the model equals the offset in the text.
 		if ( viewParent.is( '$text' ) ) {
 			return new ViewPosition( viewParent, expectedOffset );
 		}
@@ -565,20 +610,20 @@ export default class Mapper {
 	}
 
 	/**
-	 * Because we prefer positions in text nodes over positions next to text node moves view position to the text node
-	 * if it was next to it.
+	 * Because we prefer positions in the text nodes over positions next to text nodes, if the view position was next to a text node,
+	 * it moves it into the text node instead.
 	 *
 	 *		<p>[]<b>foo</b></p> -> <p>[]<b>foo</b></p> // do not touch if position is not directly next to text
 	 *		<p>foo[]<b>foo</b></p> -> <p>foo{}<b>foo</b></p> // move to text node
 	 *		<p><b>[]foo</b></p> -> <p><b>{}foo</b></p> // move to text node
 	 *
 	 * @private
-	 * @param {module:engine/view/position~Position} viewPosition Position potentially next to text node.
-	 * @returns {module:engine/view/position~Position} Position in text node if possible.
+	 * @param {module:engine/view/position~Position} viewPosition Position potentially next to the text node.
+	 * @returns {module:engine/view/position~Position} Position in the text node if possible.
 	 */
 	_moveViewPositionToTextNode( viewPosition ) {
-		// If the position is just after text node, put it at the end of that text node.
-		// If the position is just before text node, put it at the beginning of that text node.
+		// If the position is just after a text node, put it at the end of that text node.
+		// If the position is just before a text node, put it at the beginning of that text node.
 		const nodeBefore = viewPosition.nodeBefore;
 		const nodeAfter = viewPosition.nodeAfter;
 
@@ -595,8 +640,8 @@ export default class Mapper {
 	/**
 	 * Fired for each model-to-view position mapping request. The purpose of this event is to enable custom model-to-view position
 	 * mapping. Callbacks added to this event take {@link module:engine/model/position~Position model position} and are expected to
-	 * calculate {@link module:engine/view/position~Position view position}. Calculated view position should be added as `viewPosition`
-	 * value in `data` object that is passed as one of parameters to the event callback.
+	 * calculate the {@link module:engine/view/position~Position view position}. The calculated view position should be added as
+	 * a `viewPosition` value in the `data` object that is passed as one of parameters to the event callback.
 	 *
 	 * 		// Assume that "captionedImage" model element is converted to <img> and following <span> elements in view,
 	 * 		// and the model element is bound to <img> element. Force mapping model positions inside "captionedImage" to that
@@ -615,14 +660,14 @@ export default class Mapper {
 	 *			}
 	 *		} );
 	 *
-	 * **Note:** keep in mind that sometimes a "phantom" model position is being converted. "Phantom" model position is
-	 * a position that points to a non-existing place in model. Such position might still be valid for conversion, though
-	 * (it would point to a correct place in view when converted). One example of such situation is when a range is
-	 * removed from model, there may be a need to map the range's end (which is no longer valid model position). To
-	 * handle such situation, check `data.isPhantom` flag:
+	 * **Note:** keep in mind that sometimes a "phantom" model position is being converted. A "phantom" model position is
+	 * a position that points to a nonexistent place in model. Such a position might still be valid for conversion, though
+	 * (it would point to a correct place in the view when converted). One example of such a situation is when a range is
+	 * removed from the model, there may be a need to map the range's end (which is no longer a valid model position). To
+	 * handle such situations, check the `data.isPhantom` flag:
 	 *
-	 * 		// Assume that there is "customElement" model element and whenever position is before it, we want to move it
-	 * 		// to the inside of the view element bound to "customElement".
+	 * 		// Assume that there is a "customElement" model element and whenever the position is before it,
+	 * 		// we want to move it to the inside of the view element bound to "customElement".
 	 *		mapper.on( 'modelToViewPosition', ( evt, data ) => {
 	 *			if ( data.isPhantom ) {
 	 *				return;
@@ -643,19 +688,19 @@ export default class Mapper {
 	 *			evt.stop();
 	 *		} );
 	 *
-	 * **Note:** default mapping callback is provided with `low` priority setting and does not cancel the event, so it is possible to
-	 * attach a custom callback after default callback and also use `data.viewPosition` calculated by default callback
+	 * **Note:** the default mapping callback is provided with a `low` priority setting and does not cancel the event, so it is possible to
+	 * attach a custom callback after a default callback and also use `data.viewPosition` calculated by the default callback
 	 * (for example to fix it).
 	 *
-	 * **Note:** default mapping callback will not fire if `data.viewPosition` is already set.
+	 * **Note:** the default mapping callback will not fire if `data.viewPosition` is already set.
 	 *
 	 * **Note:** these callbacks are called **very often**. For efficiency reasons, it is advised to use them only when position
-	 * mapping between given model and view elements is unsolvable using just elements mapping and default algorithm. Also,
-	 * the condition that checks if special case scenario happened should be as simple as possible.
+	 * mapping between the given model and view elements is unsolvable by using just elements mapping and default algorithm.
+	 * Also, the condition that checks if a special case scenario happened should be as simple as possible.
 	 *
 	 * @event modelToViewPosition
 	 * @param {Object} data Data pipeline object that can store and pass data between callbacks. The callback should add
-	 * `viewPosition` value to that object with calculated {@link module:engine/view/position~Position view position}.
+	 * the `viewPosition` value to that object with calculated the {@link module:engine/view/position~Position view position}.
 	 * @param {module:engine/conversion/mapper~Mapper} data.mapper Mapper instance that fired the event.
 	 */
 
@@ -676,15 +721,15 @@ export default class Mapper {
 	 *			}
 	 *		} );
 	 *
-	 * **Note:** default mapping callback is provided with `low` priority setting and does not cancel the event, so it is possible to
-	 * attach a custom callback after default callback and also use `data.modelPosition` calculated by default callback
+	 * **Note:** the default mapping callback is provided with a `low` priority setting and does not cancel the event, so it is possible to
+	 * attach a custom callback after the default callback and also use `data.modelPosition` calculated by the default callback
 	 * (for example to fix it).
 	 *
-	 * **Note:** default mapping callback will not fire if `data.modelPosition` is already set.
+	 * **Note:** the default mapping callback will not fire if `data.modelPosition` is already set.
 	 *
 	 * **Note:** these callbacks are called **very often**. For efficiency reasons, it is advised to use them only when position
-	 * mapping between given model and view elements is unsolvable using just elements mapping and default algorithm. Also,
-	 * the condition that checks if special case scenario happened should be as simple as possible.
+	 * mapping between the given model and view elements is unsolvable by using just elements mapping and default algorithm.
+	 * Also, the condition that checks if special case scenario happened should be as simple as possible.
 	 *
 	 * @event viewToModelPosition
 	 * @param {Object} data Data pipeline object that can store and pass data between callbacks. The callback should add

package/src/conversion/modelconsumable.js

@@ -8,33 +8,34 @@
  */
 
 import TextProxy from '../model/textproxy';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
- * Manages a list of consumable values for {@link module:engine/model/item~Item model items}.
+ * Manages a list of consumable values for the {@link module:engine/model/item~Item model items}.
  *
- * Consumables are various aspects of the model. A model item can be broken down into singular properties that might be
+ * Consumables are various aspects of the model. A model item can be broken down into separate, single properties that might be
  * taken into consideration when converting that item.
  *
- * `ModelConsumable` is used by {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} while analyzing changed
+ * `ModelConsumable` is used by {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} while analyzing the changed
  * parts of {@link module:engine/model/document~Document the document}. The added / changed / removed model items are broken down
- * into singular properties (the item itself and it's attributes). All those parts are saved in `ModelConsumable`. Then,
- * during conversion, when given part of model item is converted (i.e. the view element has been inserted into the view,
- * but without attributes), consumable value is removed from `ModelConsumable`.
+ * into singular properties (the item itself and its attributes). All those parts are saved in `ModelConsumable`. Then,
+ * during conversion, when the given part of a model item is converted (i.e. the view element has been inserted into the view,
+ * but without attributes), the consumable value is removed from `ModelConsumable`.
  *
  * For model items, `ModelConsumable` stores consumable values of one of following types: `insert`, `addattribute:<attributeKey>`,
  * `changeattributes:<attributeKey>`, `removeattributes:<attributeKey>`.
  *
- * In most cases, it is enough to let {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
+ * In most cases, it is enough to let th {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
  * gather consumable values, so there is no need to use
- * {@link module:engine/conversion/modelconsumable~ModelConsumable#add add method} directly.
+ * the {@link module:engine/conversion/modelconsumable~ModelConsumable#add add method} directly.
  * However, it is important to understand how consumable values can be
  * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
  * See {@link module:engine/conversion/downcasthelpers default downcast converters} for more information.
  *
- * Keep in mind, that one conversion event may have multiple callbacks (converters) attached to it. Each of those is
+ * Keep in mind that one conversion event may have multiple callbacks (converters) attached to it. Each of those is
  * able to convert one or more parts of the model. However, when one of those callbacks actually converts
- * something, other should not, because they would duplicate the results. Using `ModelConsumable` helps avoiding
- * this situation, because callbacks should only convert those values, which were not yet consumed from `ModelConsumable`.
+ * something, the others should not, because they would duplicate the results. Using `ModelConsumable` helps to avoid
+ * this situation, because callbacks should only convert these values that were not yet consumed from `ModelConsumable`.
  *
  * Consuming multiple values in a single callback:
  *
@@ -101,12 +102,12 @@ export default class ModelConsumable {
 		this._consumable = new Map();
 
 		/**
-		 * For each {@link module:engine/model/textproxy~TextProxy} added to `ModelConsumable`, this registry holds parent
-		 * of that `TextProxy` and start and end indices of that `TextProxy`. This allows identification of `TextProxy`
-		 * instances that points to the same part of the model but are different instances. Each distinct `TextProxy`
-		 * is given unique `Symbol` which is then registered as consumable. This process is transparent for `ModelConsumable`
-		 * API user because whenever `TextProxy` is added, tested, consumed or reverted, internal mechanisms of
-		 * `ModelConsumable` translates `TextProxy` to that unique `Symbol`.
+		 * For each {@link module:engine/model/textproxy~TextProxy} added to `ModelConsumable`, this registry holds a parent
+		 * of that `TextProxy` and the start and end indices of that `TextProxy`. This allows identification of the `TextProxy`
+		 * instances that point to the same part of the model but are different instances. Each distinct `TextProxy`
+		 * is given a unique `Symbol` which is then registered as consumable. This process is transparent for the `ModelConsumable`
+		 * API user because whenever `TextProxy` is added, tested, consumed or reverted, the internal mechanisms of
+		 * `ModelConsumable` translate `TextProxy` to that unique `Symbol`.
 		 *
 		 * @private
 		 * @member {Map} module:engine/conversion/modelconsumable~ModelConsumable#_textProxyRegistry
@@ -115,7 +116,7 @@ export default class ModelConsumable {
 	}
 
 	/**
-	 * Adds a consumable value to the consumables list and links it with given model item.
+	 * Adds a consumable value to the consumables list and links it with a given model item.
 	 *
 	 *		modelConsumable.add( modelElement, 'insert' ); // Add `modelElement` insertion change to consumable values.
 	 *		modelConsumable.add( modelElement, 'addAttribute:bold' ); // Add `bold` attribute insertion on `modelElement` change.
@@ -143,7 +144,7 @@ export default class ModelConsumable {
 	}
 
 	/**
-	 * Removes given consumable value from given model item.
+	 * Removes a given consumable value from a given model item.
 	 *
 	 *		modelConsumable.consume( modelElement, 'insert' ); // Remove `modelElement` insertion change from consumable values.
 	 *		modelConsumable.consume( modelElement, 'addAttribute:bold' ); // Remove `bold` attribute insertion on `modelElement` change.
@@ -174,7 +175,7 @@ export default class ModelConsumable {
 	}
 
 	/**
-	 * Tests whether there is a consumable value of given type connected with given model item.
+	 * Tests whether there is a consumable value of a given type connected with a given model item.
 	 *
 	 *		modelConsumable.test( modelElement, 'insert' ); // Check for `modelElement` insertion change.
 	 *		modelConsumable.test( modelElement, 'addAttribute:bold' ); // Check for `bold` attribute insertion on `modelElement` change.
@@ -212,7 +213,7 @@ export default class ModelConsumable {
 	}
 
 	/**
-	 * Reverts consuming of consumable value.
+	 * Reverts consuming of a consumable value.
 	 *
 	 *		modelConsumable.revert( modelElement, 'insert' ); // Revert consuming `modelElement` insertion change.
 	 *		modelConsumable.revert( modelElement, 'addAttribute:bold' ); // Revert consuming `bold` attribute insert from `modelElement`.
@@ -247,12 +248,54 @@ export default class ModelConsumable {
 	}
 
 	/**
-	 * Gets a unique symbol for passed {@link module:engine/model/textproxy~TextProxy} instance. All `TextProxy` instances that
+	 * Verifies if all events from the specified group were consumed.
+	 *
+	 * @param {String} eventGroup The events group to verify.
+	 */
+	verifyAllConsumed( eventGroup ) {
+		const items = [];
+
+		for ( const [ item, consumables ] of this._consumable ) {
+			for ( const [ event, canConsume ] of consumables ) {
+				const eventPrefix = event.split( ':' )[ 0 ];
+
+				if ( canConsume && eventGroup == eventPrefix ) {
+					items.push( {
+						event,
+						item: item.name || item.description
+					} );
+				}
+			}
+		}
+
+		if ( items.length ) {
+			/**
+			 * Some of the {@link module:engine/model/item~Item model items} were not consumed while downcasting the model to view.
+			 *
+			 * This might be the effect of:
+			 *
+			 * * A missing converter for some model elements. Make sure that you registered downcast converters for all model elements.
+			 * * A custom converter that does not consume converted items. Make sure that you
+			 * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} all model elements that you converted
+			 * from the model to the view.
+			 * * A custom converter that called `event.stop()`. When providing a custom converter, keep in mind that you should not stop
+			 * the event. If you stop it then the default converter at the `lowest` priority will not trigger the conversion of this node's
+			 * attributes and child nodes.
+			 *
+			 * @error conversion-model-consumable-not-consumed
+			 * @param {Array.<module:engine/model/item~Item>} items Items that were not consumed.
+			 */
+			throw new CKEditorError( 'conversion-model-consumable-not-consumed', null, { items } );
+		}
+	}
+
+	/**
+	 * Gets a unique symbol for the passed {@link module:engine/model/textproxy~TextProxy} instance. All `TextProxy` instances that
 	 * have same parent, same start index and same end index will get the same symbol.
 	 *
 	 * Used internally to correctly consume `TextProxy` instances.
 	 *
-	 * @private
+	 * @protected
 	 * @param {module:engine/model/textproxy~TextProxy} textProxy `TextProxy` instance to get a symbol for.
 	 * @returns {Symbol} Symbol representing all equal instances of `TextProxy`.
 	 */
@@ -270,25 +313,27 @@ export default class ModelConsumable {
 		}
 
 		if ( !symbol ) {
-			symbol = this._addSymbolForTextProxy( textProxy.startOffset, textProxy.endOffset, textProxy.parent );
+			symbol = this._addSymbolForTextProxy( textProxy );
 		}
 
 		return symbol;
 	}
 
 	/**
-	 * Adds a symbol for given properties that characterizes a {@link module:engine/model/textproxy~TextProxy} instance.
+	 * Adds a symbol for the given {@link module:engine/model/textproxy~TextProxy} instance.
 	 *
 	 * Used internally to correctly consume `TextProxy` instances.
 	 *
 	 * @private
-	 * @param {Number} startIndex Text proxy start index in it's parent.
-	 * @param {Number} endIndex Text proxy end index in it's parent.
-	 * @param {module:engine/model/element~Element} parent Text proxy parent.
-	 * @returns {Symbol} Symbol generated for given properties.
+	 * @param {module:engine/model/textproxy~TextProxy} textProxy Text proxy instance.
+	 * @returns {Symbol} Symbol generated for given `TextProxy`.
 	 */
-	_addSymbolForTextProxy( start, end, parent ) {
-		const symbol = Symbol( 'textProxySymbol' );
+	_addSymbolForTextProxy( textProxy ) {
+		const start = textProxy.startOffset;
+		const end = textProxy.endOffset;
+		const parent = textProxy.parent;
+
+		const symbol = Symbol( '$textProxy:' + textProxy.data );
 		let startMap, endMap;
 
 		startMap = this._textProxyRegistry.get( start );
@@ -311,15 +356,20 @@ export default class ModelConsumable {
 	}
 }
 
-// Returns a normalized consumable type name from given string. A normalized consumable type name is a string that has
-// at most one colon, for example: `insert` or `addMarker:highlight`. If string to normalize has more "parts" (more colons),
-// the other parts are dropped, for example: `addattribute:bold:$text` -> `addattributes:bold`.
+// Returns a normalized consumable type name from the given string. A normalized consumable type name is a string that has
+// at most one colon, for example: `insert` or `addMarker:highlight`. If a string to normalize has more "parts" (more colons),
+// the further parts are dropped, for example: `addattribute:bold:$text` -> `addattributes:bold`.
 //
 // @param {String} type Consumable type.
 // @returns {String} Normalized consumable type.
 function _normalizeConsumableType( type ) {
 	const parts = type.split( ':' );
 
+	// For inserts allow passing event name, it's stored in the context of a specified element so the element name is not needed.
+	if ( parts[ 0 ] == 'insert' ) {
+		return parts[ 0 ];
+	}
+
 	// Markers are identified by the whole name (otherwise we would consume the whole markers group).
 	if ( parts[ 0 ] == 'addMarker' || parts[ 0 ] == 'removeMarker' ) {
 		return type;

package/src/conversion/upcastdispatcher.js

@@ -40,10 +40,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * The third parameter of the callback is an instance of {@link module:engine/conversion/upcastdispatcher~UpcastConversionApi}
  * which provides additional tools for converters.
  *
- * You can read more about conversion in the following guides:
- *
- * * {@glink framework/guides/deep-dive/conversion/conversion-introduction Advanced conversion concepts — attributes}
- * * {@glink framework/guides/deep-dive/conversion/custom-element-conversion Custom element conversion}
+ * You can read more about conversion in the {@glink framework/guides/deep-dive/conversion/upcast Upcast conversion} guide.
  *
  * Examples of event-based converters:
  *
@@ -127,7 +124,7 @@ export default class UpcastDispatcher {
 		/**
 		 * The list of elements that were created during splitting.
 		 *
-		 * After the conversion process the list is cleared.
+		 * After the conversion process, the list is cleared.
 		 *
 		 * @private
 		 * @type {Map.<module:engine/model/element~Element,Array.<module:engine/model/element~Element>>}

package/src/conversion/upcasthelpers.js

@@ -12,7 +12,7 @@ import priorities from '@ckeditor/ckeditor5-utils/src/priorities';
 import { isParagraphable, wrapInParagraph } from '../model/utils/autoparagraphing';
 
 /**
- * Contains {@link module:engine/view/view view} to {@link module:engine/model/model model} converters for
+ * Contains the {@link module:engine/view/view view} to {@link module:engine/model/model model} converters for
  * {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher}.
  *
  * @module engine/conversion/upcasthelpers
@@ -21,6 +21,8 @@ import { isParagraphable, wrapInParagraph } from '../model/utils/autoparagraphin
 /**
  * Upcast conversion helper functions.
  *
+ * Learn more about {@glink framework/guides/deep-dive/conversion/upcast upcast helpers}.
+ *
  * @extends module:engine/conversion/conversionhelpers~ConversionHelpers
  */
 export default class UpcastHelpers extends ConversionHelpers {

package/src/dataprocessor/htmldataprocessor.js

@@ -114,7 +114,7 @@ export default class HtmlDataProcessor {
 	 * @returns {DocumentFragment}
 	 */
 	_toDom( data ) {
-		// Wrap data with a <body> so leading non-layout nodes (like <script>, <style>, HTML comment)
+		// Wrap data with a <body> tag so leading non-layout nodes (like <script>, <style>, HTML comment)
 		// will be preserved in the body collection.
 		// Do it only for data that is not a full HTML document.
 		if ( !data.match( /<(?:html|body|head|meta)(?:\s[^>]*)?>/i ) ) {