@ckeditor/ckeditor5-engine 36.0.0 → 37.0.0-alpha.0

package/src/conversion/mapper.js

@@ -29,7 +29,6 @@ import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * 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
  */
 export default class Mapper extends EmitterMixin() {
     /**
@@ -39,24 +38,15 @@ export default class Mapper extends EmitterMixin() {
         super();
         /**
          * Model element to view element mapping.
-         *
-         * @private
-         * @member {WeakMap}
          */
         this._modelToViewMapping = new WeakMap();
         /**
          * View element to model element mapping.
-         *
-         * @private
-         * @member {WeakMap}
          */
         this._viewToModelMapping = new WeakMap();
         /**
          * A map containing callbacks between view element names and functions evaluating length of view elements
          * in model.
-         *
-         * @private
-         * @member {Map}
          */
         this._viewToModelLengthCallbacks = new Map();
         /**
@@ -64,33 +54,21 @@ export default class Mapper extends EmitterMixin() {
          *
          * Keys are `String`s while values are `Set`s with {@link module:engine/view/element~Element view elements}.
          * One marker (name) can be mapped to multiple elements.
-         *
-         * @private
-         * @member {Map}
          */
         this._markerNameToElements = new Map();
         /**
          * View element to model marker names mapping.
          *
          * This is reverse to {@link ~Mapper#_markerNameToElements} map.
-         *
-         * @private
-         * @member {Map}
          */
         this._elementToMarkerNames = new Map();
         /**
          * 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
-         * @member {Set.<module:engine/model/markercollection~Marker>}
          */
         this._unboundMarkerNames = new Set();
         // Default mapper algorithm for mapping model position to view position.
@@ -129,8 +107,8 @@ export default class Mapper extends EmitterMixin() {
      * {@link module:engine/conversion/mapper~Mapper#toViewElement toViewElement} methods.
      * The information that elements are bound is also used to translate positions.
      *
-     * @param {module:engine/model/element~Element} modelElement Model element.
-     * @param {module:engine/view/element~Element} viewElement View element.
+     * @param modelElement Model element.
+     * @param viewElement View element.
      */
     bindElements(modelElement, viewElement) {
         this._modelToViewMapping.set(modelElement, viewElement);
@@ -145,9 +123,9 @@ export default class Mapper extends EmitterMixin() {
      * 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
+     * @param viewElement View element to unbind.
+     * @param options The options object.
+     * @param options.defer Controls whether the binding should be removed immediately or deferred until a
      * {@link #flushDeferredBindings `flushDeferredBindings()`} call.
      */
     unbindViewElement(viewElement, options = {}) {
@@ -176,7 +154,7 @@ export default class Mapper extends EmitterMixin() {
      * 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.
      *
-     * @param {module:engine/model/element~Element} modelElement Model element to unbind.
+     * @param modelElement Model element to unbind.
      */
     unbindModelElement(modelElement) {
         const viewElement = this.toViewElement(modelElement);
@@ -189,8 +167,8 @@ export default class Mapper extends EmitterMixin() {
      * 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.
+     * @param element Element to bind.
+     * @param name Marker name.
      */
     bindElementToMarker(element, name) {
         const elements = this._markerNameToElements.get(name) || new Set();
@@ -203,8 +181,8 @@ export default class Mapper extends EmitterMixin() {
     /**
      * Unbinds an element from given marker name.
      *
-     * @param {module:engine/view/element~Element} element Element to unbind.
-     * @param {String} name Marker name.
+     * @param element Element to unbind.
+     * @param name Marker name.
      */
     unbindElementFromMarkerName(element, name) {
         const nameToElements = this._markerNameToElements.get(name);
@@ -225,8 +203,6 @@ export default class Mapper extends EmitterMixin() {
     /**
      * 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>}
      */
     flushUnboundMarkerNames() {
         const markerNames = Array.from(this._unboundMarkerNames);
@@ -267,8 +243,8 @@ export default class Mapper extends EmitterMixin() {
     /**
      * Gets the corresponding model range.
      *
-     * @param {module:engine/view/range~Range} viewRange View range.
-     * @returns {module:engine/model/range~Range} Corresponding model range.
+     * @param viewRange View range.
+     * @returns Corresponding model range.
      */
     toModelRange(viewRange) {
         return new ModelRange(this.toModelPosition(viewRange.start), this.toModelPosition(viewRange.end));
@@ -276,8 +252,8 @@ export default class Mapper extends EmitterMixin() {
     /**
      * Gets the corresponding view range.
      *
-     * @param {module:engine/model/range~Range} modelRange Model range.
-     * @returns {module:engine/view/range~Range} Corresponding view range.
+     * @param modelRange Model range.
+     * @returns Corresponding view range.
      */
     toViewRange(modelRange) {
         return new ViewRange(this.toViewPosition(modelRange.start), this.toViewPosition(modelRange.end));
@@ -286,8 +262,8 @@ export default class Mapper extends EmitterMixin() {
      * Gets the corresponding model position.
      *
      * @fires viewToModelPosition
-     * @param {module:engine/view/position~Position} viewPosition View position.
-     * @returns {module:engine/model/position~Position} Corresponding model position.
+     * @param viewPosition View position.
+     * @returns Corresponding model position.
      */
     toModelPosition(viewPosition) {
         const data = {
@@ -301,11 +277,11 @@ export default class Mapper extends EmitterMixin() {
      * Gets the corresponding view position.
      *
      * @fires modelToViewPosition
-     * @param {module:engine/model/position~Position} modelPosition Model position.
-     * @param {Object} [options] Additional options for position mapping process.
-     * @param {Boolean} [options.isPhantom=false] Should be set to `true` if the model position to map is pointing to a place
+     * @param modelPosition Model position.
+     * @param options Additional options for position mapping process.
+     * @param options.isPhantom Should be set to `true` if the model position to map is pointing to a place
      * in model tree which no longer exists. For example, it could be an end of a removed model range.
-     * @returns {module:engine/view/position~Position} Corresponding view position.
+     * @returns Corresponding view position.
      */
     toViewPosition(modelPosition, options = {}) {
         const data = {
@@ -319,8 +295,8 @@ export default class Mapper extends EmitterMixin() {
     /**
      * 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 the given marker name or `null`
+     * @param name Marker name.
+     * @returns View elements bound with the given marker name or `null`
      * if no elements are bound to the given marker name.
      */
     markerNameToElements(name) {
@@ -347,28 +323,30 @@ export default class Mapper extends EmitterMixin() {
      * 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 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
-     *		// may be greater than one. In the callback it's checked how many nested list items are in evaluated list item.
+     * ```ts
+     * // 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
+     * // may be greater than one. In the callback it's checked how many nested list items are in evaluated list item.
      *
-     *		function getViewListItemLength( element ) {
-     *			let length = 1;
+     * function getViewListItemLength( element ) {
+     * 	let length = 1;
      *
-     *			for ( let child of element.getChildren() ) {
-     *				if ( child.name == 'ul' || child.name == 'ol' ) {
-     *					for ( let item of child.getChildren() ) {
-     *						length += getViewListItemLength( item );
-     *					}
-     *				}
-     *			}
+     * 	for ( let child of element.getChildren() ) {
+     * 		if ( child.name == 'ul' || child.name == 'ol' ) {
+     * 			for ( let item of child.getChildren() ) {
+     * 				length += getViewListItemLength( item );
+     * 			}
+     * 		}
+     * 	}
      *
-     *			return length;
-     *		}
+     * 	return length;
+     * }
      *
-     *		mapper.registerViewToModelLength( 'li', getViewListItemLength );
+     * mapper.registerViewToModelLength( 'li', getViewListItemLength );
+     * ```
      *
-     * @param {String} viewElementName Name of view element for which callback is registered.
-     * @param {Function} lengthCallback Function return a length of view element instance in model.
+     * @param viewElementName Name of view element for which callback is registered.
+     * @param lengthCallback Function return a length of view element instance in model.
      */
     registerViewToModelLength(viewElementName, lengthCallback) {
         this._viewToModelLengthCallbacks.set(viewElementName, lengthCallback);
@@ -377,8 +355,7 @@ export default class Mapper extends EmitterMixin() {
      * 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 a mapped ancestor should be found.
-     * @returns {module:engine/view/element~Element}
+     * @param viewPosition Position for which a mapped ancestor should be found.
      */
     findMappedViewAncestor(viewPosition) {
         let parent = viewPosition.parent;
@@ -392,18 +369,21 @@ export default class Mapper extends EmitterMixin() {
      *
      * Example:
      *
-     *		<p>foo<b>ba|r</b></p> // _toModelOffset( b, 2, p ) -> 5
+     * ```html
+     * <p>foo<b>ba|r</b></p> // _toModelOffset( b, 2, p ) -> 5
+     * ```
      *
      * Is a sum of:
      *
-     *		<p>foo|<b>bar</b></p> // _toModelOffset( p, 3, p ) -> 3
-     *		<p>foo<b>ba|r</b></p> // _toModelOffset( b, 2, b ) -> 2
+     * ```html
+     * <p>foo|<b>bar</b></p> // _toModelOffset( p, 3, p ) -> 3
+     * <p>foo<b>ba|r</b></p> // _toModelOffset( b, 2, b ) -> 2
+     * ```
      *
-     * @private
-     * @param {module:engine/view/element~Element} viewParent Position parent.
-     * @param {Number} viewOffset Position offset.
-     * @param {module:engine/view/element~Element} viewBlock Block used as a base to calculate offset.
-     * @returns {Number} Offset in the model.
+     * @param viewParent Position parent.
+     * @param viewOffset Position offset.
+     * @param viewBlock Block used as a base to calculate offset.
+     * @returns Offset in the model.
      */
     _toModelOffset(viewParent, viewOffset, viewBlock) {
         if (viewBlock != viewParent) {
@@ -438,13 +418,15 @@ export default class Mapper extends EmitterMixin() {
      *
      * Examples:
      *
-     *		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.
+     * ```
+     * 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.
+     * ```
      *
-     * @param {module:engine/view/element~Element} viewNode View node.
-     * @returns {Number} Length of the node in the tree model.
+     * @param viewNode View node.
+     * @returns Length of the node in the tree model.
      */
     getModelLength(viewNode) {
         if (this._viewToModelLengthCallbacks.get(viewNode.name)) {
@@ -473,24 +455,26 @@ export default class Mapper extends EmitterMixin() {
      *
      * Example:
      *
-     *		<p>fo<b>bar</b>bom</p> -> expected offset: 4
+     * ```
+     * <p>fo<b>bar</b>bom</p> -> expected offset: 4
      *
-     *		findPositionIn( p, 4 ):
-     *		<p>|fo<b>bar</b>bom</p> -> expected offset: 4, actual offset: 0
-     *		<p>fo|<b>bar</b>bom</p> -> expected offset: 4, actual offset: 2
-     *		<p>fo<b>bar</b>|bom</p> -> expected offset: 4, actual offset: 5 -> we are too far
+     * findPositionIn( p, 4 ):
+     * <p>|fo<b>bar</b>bom</p> -> expected offset: 4, actual offset: 0
+     * <p>fo|<b>bar</b>bom</p> -> expected offset: 4, actual offset: 2
+     * <p>fo<b>bar</b>|bom</p> -> expected offset: 4, actual offset: 5 -> we are too far
      *
-     *		findPositionIn( b, 4 - ( 5 - 3 ) ):
-     *		<p>fo<b>|bar</b>bom</p> -> expected offset: 2, actual offset: 0
-     *		<p>fo<b>bar|</b>bom</p> -> expected offset: 2, actual offset: 3 -> we are too far
+     * findPositionIn( b, 4 - ( 5 - 3 ) ):
+     * <p>fo<b>|bar</b>bom</p> -> expected offset: 2, actual offset: 0
+     * <p>fo<b>bar|</b>bom</p> -> expected offset: 2, actual offset: 3 -> we are too far
      *
-     *		findPositionIn( bar, 2 - ( 3 - 3 ) ):
-     *		We are in the text node so we can simple find the offset.
-     *		<p>fo<b>ba|r</b>bom</p> -> expected offset: 2, actual offset: 2 -> position found
+     * findPositionIn( bar, 2 - ( 3 - 3 ) ):
+     * We are in the text node so we can simple find the offset.
+     * <p>fo<b>ba|r</b>bom</p> -> expected offset: 2, actual offset: 2 -> position found
+     * ```
      *
-     * @param {module:engine/view/element~Element} viewParent Tree view element in which we are looking for the position.
-     * @param {Number} expectedOffset Expected offset.
-     * @returns {module:engine/view/position~Position} Found position.
+     * @param viewParent Tree view element in which we are looking for the position.
+     * @param expectedOffset Expected offset.
+     * @returns Found position.
      */
     findPositionIn(viewParent, expectedOffset) {
         // Last scanned view node.
@@ -526,13 +510,14 @@ export default class Mapper extends EmitterMixin() {
      * 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
+     * ```
+     * <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 the text node.
-     * @returns {module:engine/view/position~Position} Position in the text node if possible.
+     * @param viewPosition Position potentially next to the text node.
+     * @returns Position in the text node if possible.
      */
     _moveViewPositionToTextNode(viewPosition) {
         // If the position is just after a text node, put it at the end of that text node.

package/src/conversion/modelconsumable.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/conversion/modelconsumable
+ */
+import TextProxy from '../model/textproxy';
+import type Item from '../model/item';
+import type Selection from '../model/selection';
+import type DocumentSelection from '../model/documentselection';
+import type Range from '../model/range';
+/**
+ * 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 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 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 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 th {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
+ * gather consumable values, so there is no need to use
+ * 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
+ * able to convert one or more parts of the model. However, when one of those callbacks actually converts
+ * 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:
+ *
+ * ```ts
+ * // Converter for custom `imageBlock` element that might have a `caption` element inside which changes
+ * // how the image is displayed in the view:
+ * //
+ * // Model:
+ * //
+ * // [imageBlock]
+ * //   └─ [caption]
+ * //       └─ foo
+ * //
+ * // View:
+ * //
+ * // <figure>
+ * //   ├─ <img />
+ * //   └─ <caption>
+ * //       └─ foo
+ * modelConversionDispatcher.on( 'insert:imageBlock', ( evt, data, conversionApi ) => {
+ * 	// First, consume the `imageBlock` element.
+ * 	conversionApi.consumable.consume( data.item, 'insert' );
+ *
+ * 	// Just create normal image element for the view.
+ * 	// Maybe it will be "decorated" later.
+ * 	const viewImage = new ViewElement( 'img' );
+ * 	const insertPosition = conversionApi.mapper.toViewPosition( data.range.start );
+ * 	const viewWriter = conversionApi.writer;
+ *
+ * 	// Check if the `imageBlock` element has children.
+ * 	if ( data.item.childCount > 0 ) {
+ * 		const modelCaption = data.item.getChild( 0 );
+ *
+ * 		// `modelCaption` insertion change is consumed from consumable values.
+ * 		// It will not be converted by other converters, but it's children (probably some text) will be.
+ * 		// Through mapping, converters for text will know where to insert contents of `modelCaption`.
+ * 		if ( conversionApi.consumable.consume( modelCaption, 'insert' ) ) {
+ * 			const viewCaption = new ViewElement( 'figcaption' );
+ *
+ * 			const viewImageHolder = new ViewElement( 'figure', null, [ viewImage, viewCaption ] );
+ *
+ * 			conversionApi.mapper.bindElements( modelCaption, viewCaption );
+ * 			conversionApi.mapper.bindElements( data.item, viewImageHolder );
+ * 			viewWriter.insert( insertPosition, viewImageHolder );
+ * 		}
+ * 	} else {
+ * 		conversionApi.mapper.bindElements( data.item, viewImage );
+ * 		viewWriter.insert( insertPosition, viewImage );
+ * 	}
+ *
+ * 	evt.stop();
+ * } );
+ * ```
+ */
+export default class ModelConsumable {
+    /**
+     * Contains list of consumable values.
+     */
+    private _consumable;
+    /**
+     * 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 _textProxyRegistry;
+    /**
+     * Adds a consumable value to the consumables list and links it with a given model item.
+     *
+     * ```ts
+     * modelConsumable.add( modelElement, 'insert' ); // Add `modelElement` insertion change to consumable values.
+     * modelConsumable.add( modelElement, 'addAttribute:bold' ); // Add `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.add( modelElement, 'removeAttribute:bold' ); // Add `bold` attribute removal on `modelElement` change.
+     * modelConsumable.add( modelSelection, 'selection' ); // Add `modelSelection` to consumable values.
+     * modelConsumable.add( modelRange, 'range' ); // Add `modelRange` to consumable values.
+     * ```
+     *
+     * @param item Model item, range or selection that has the consumable.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * Second colon and everything after will be cut. Passing event name is a safe and good practice.
+     */
+    add(item: Item | Selection | DocumentSelection | Range, type: string): void;
+    /**
+     * Removes a given consumable value from a given model item.
+     *
+     * ```ts
+     * modelConsumable.consume( modelElement, 'insert' ); // Remove `modelElement` insertion change from consumable values.
+     * modelConsumable.consume( modelElement, 'addAttribute:bold' ); // Remove `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.consume( modelElement, 'removeAttribute:bold' ); // Remove `bold` attribute removal on `modelElement` change.
+     * modelConsumable.consume( modelSelection, 'selection' ); // Remove `modelSelection` from consumable values.
+     * modelConsumable.consume( modelRange, 'range' ); // Remove 'modelRange' from consumable values.
+     * ```
+     *
+     * @param item Model item, range or selection from which consumable will be consumed.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * Second colon and everything after will be cut. Passing event name is a safe and good practice.
+     * @returns `true` if consumable value was available and was consumed, `false` otherwise.
+     */
+    consume(item: Item | Selection | DocumentSelection | Range, type: string): boolean;
+    /**
+     * Tests whether there is a consumable value of a given type connected with a given model item.
+     *
+     * ```ts
+     * modelConsumable.test( modelElement, 'insert' ); // Check for `modelElement` insertion change.
+     * modelConsumable.test( modelElement, 'addAttribute:bold' ); // Check for `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.test( modelElement, 'removeAttribute:bold' ); // Check for `bold` attribute removal on `modelElement` change.
+     * modelConsumable.test( modelSelection, 'selection' ); // Check if `modelSelection` is consumable.
+     * modelConsumable.test( modelRange, 'range' ); // Check if `modelRange` is consumable.
+     * ```
+     *
+     * @param item Model item, range or selection to be tested.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * Second colon and everything after will be cut. Passing event name is a safe and good practice.
+     * @returns `null` if such consumable was never added, `false` if the consumable values was
+     * already consumed or `true` if it was added and not consumed yet.
+     */
+    test(item: Item | Selection | DocumentSelection | Range, type: string): boolean | null;
+    /**
+     * Reverts consuming of a consumable value.
+     *
+     * ```ts
+     * modelConsumable.revert( modelElement, 'insert' ); // Revert consuming `modelElement` insertion change.
+     * modelConsumable.revert( modelElement, 'addAttribute:bold' ); // Revert consuming `bold` attribute insert from `modelElement`.
+     * modelConsumable.revert( modelElement, 'removeAttribute:bold' ); // Revert consuming `bold` attribute remove from `modelElement`.
+     * modelConsumable.revert( modelSelection, 'selection' ); // Revert consuming `modelSelection`.
+     * modelConsumable.revert( modelRange, 'range' ); // Revert consuming `modelRange`.
+     * ```
+     *
+     * @param item Model item, range or selection to be reverted.
+     * @param type Consumable type.
+     * @returns `true` if consumable has been reversed, `false` otherwise. `null` if the consumable has
+     * never been added.
+     */
+    revert(item: Item | Selection | DocumentSelection | Range, type: string): boolean | null;
+    /**
+     * Verifies if all events from the specified group were consumed.
+     *
+     * @param eventGroup The events group to verify.
+     */
+    verifyAllConsumed(eventGroup: string): void;
+    /**
+     * 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.
+     *
+     * @internal
+     * @param textProxy `TextProxy` instance to get a symbol for.
+     * @returns Symbol representing all equal instances of `TextProxy`.
+     */
+    _getSymbolForTextProxy(textProxy: TextProxy): symbol;
+    /**
+     * Adds a symbol for the given {@link module:engine/model/textproxy~TextProxy} instance.
+     *
+     * Used internally to correctly consume `TextProxy` instances.
+     *
+     * @param textProxy Text proxy instance.
+     * @returns Symbol generated for given `TextProxy`.
+     */
+    private _addSymbolForTextProxy;
+}