@ckeditor/ckeditor5-engine 31.1.0 → 34.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-2021, [CKSource](http://cksource.com) Frederico Knabben. All rights reserved.
+Copyright (c) 2003-2022, [CKSource](http://cksource.com) Holding sp. z o.o. All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
 
@@ -14,4 +14,4 @@ Where not otherwise indicated, all CKEditor content is authored by CKSource engi
 Trademarks
 ----------
 
-**CKEditor** is a trademark of [CKSource](http://cksource.com) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.
+**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.

package/README.md

@@ -3,7 +3,8 @@ CKEditor 5 editing engine
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-engine.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)
 [![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
-[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://travis-ci.com/ckeditor/ckeditor5)
+[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
+![Dependency Status](https://img.shields.io/librariesio/release/npm/@ckeditor/ckeditor5-engine)
 
 The CKEditor 5 editing engine implements a flexible MVC-based architecture for creating rich text editing features.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "31.1.0",
+  "version": "34.0.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,35 +23,35 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "^31.1.0",
+    "@ckeditor/ckeditor5-utils": "^34.0.0",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^31.1.0",
-    "@ckeditor/ckeditor5-block-quote": "^31.1.0",
-    "@ckeditor/ckeditor5-clipboard": "^31.1.0",
-    "@ckeditor/ckeditor5-cloud-services": "^31.1.0",
-    "@ckeditor/ckeditor5-core": "^31.1.0",
-    "@ckeditor/ckeditor5-editor-classic": "^31.1.0",
-    "@ckeditor/ckeditor5-enter": "^31.1.0",
-    "@ckeditor/ckeditor5-essentials": "^31.1.0",
-    "@ckeditor/ckeditor5-heading": "^31.1.0",
-    "@ckeditor/ckeditor5-image": "^31.1.0",
-    "@ckeditor/ckeditor5-link": "^31.1.0",
-    "@ckeditor/ckeditor5-list": "^31.1.0",
-    "@ckeditor/ckeditor5-mention": "^31.1.0",
-    "@ckeditor/ckeditor5-paragraph": "^31.1.0",
-    "@ckeditor/ckeditor5-table": "^31.1.0",
-    "@ckeditor/ckeditor5-theme-lark": "^31.1.0",
-    "@ckeditor/ckeditor5-typing": "^31.1.0",
-    "@ckeditor/ckeditor5-ui": "^31.1.0",
-    "@ckeditor/ckeditor5-undo": "^31.1.0",
-    "@ckeditor/ckeditor5-widget": "^31.1.0",
-    "webpack": "^4.43.0",
-    "webpack-cli": "^3.3.11"
+    "@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",
+    "webpack": "^5.58.1",
+    "webpack-cli": "^4.9.0"
   },
   "engines": {
-    "node": ">=12.0.0",
+    "node": ">=14.0.0",
     "npm": ">=5.7.1"
   },
   "author": "CKSource (http://cksource.com/)",

package/src/controller/datacontroller.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -14,7 +14,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import Mapper from '../conversion/mapper';
 
 import DowncastDispatcher from '../conversion/downcastdispatcher';
-import { insertText } from '../conversion/downcasthelpers';
+import { insertAttributesAndChildren, insertText } from '../conversion/downcasthelpers';
 
 import UpcastDispatcher from '../conversion/upcastdispatcher';
 import { convertText, convertToModelFragment } from '../conversion/upcasthelpers';
@@ -31,7 +31,7 @@ import HtmlDataProcessor from '../dataprocessor/htmldataprocessor';
  * Controller for the data pipeline. The data pipeline controls how data is retrieved from the document
  * and set inside it. Hence, the controller features two methods which allow to {@link ~DataController#get get}
  * and {@link ~DataController#set set} data of the {@link ~DataController#model model}
- * using given:
+ * using the given:
  *
  * * {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor},
  * * downcast converters,
@@ -61,8 +61,8 @@ export default class DataController {
 		this.model = model;
 
 		/**
-		 * Mapper used for the conversion. It has no permanent bindings, because they are created when getting data and
-		 * cleared directly after the data are converted. However, the mapper is defined as a class property, because
+		 * Mapper used for the conversion. It has no permanent bindings, because these are created while getting data and
+		 * ae cleared directly after the data are converted. However, the mapper is defined as a class property, because
 		 * it needs to be passed to the `DowncastDispatcher` as a conversion API.
 		 *
 		 * @readonly
@@ -81,6 +81,7 @@ export default class DataController {
 			schema: model.schema
 		} );
 		this.downcastDispatcher.on( 'insert:$text', insertText(), { priority: 'lowest' } );
+		this.downcastDispatcher.on( 'insert', insertAttributesAndChildren(), { priority: 'lowest' } );
 
 		/**
 		 * Upcast dispatcher used by the {@link #set set method}. Upcast converters should be attached to it.
@@ -138,7 +139,7 @@ export default class DataController {
 		//
 		// Note that if there is no default converter for the element it will be skipped, for instance `<b>foo</b>` will be
 		// converted to nothing. We therefore add `convertToModelFragment` as a last converter so it converts children of that
-		// element to the document fragment and so `<b>foo</b>` will be converted to `foo` if there is no converter for `<b>`.
+		// element to the document fragment so `<b>foo</b>` will still be converted to `foo` even if there is no converter for `<b>`.
 		this.upcastDispatcher.on( 'text', convertText(), { priority: 'lowest' } );
 		this.upcastDispatcher.on( 'element', convertToModelFragment(), { priority: 'lowest' } );
 		this.upcastDispatcher.on( 'documentFragment', convertToModelFragment(), { priority: 'lowest' } );
@@ -147,16 +148,16 @@ export default class DataController {
 		this.decorate( 'set' );
 		this.decorate( 'get' );
 
-		// Fire the `ready` event when the initialization has completed. Such low-level listener gives possibility
+		// Fire the `ready` event when the initialization has completed. Such low-level listener offers the possibility
 		// to plug into the initialization pipeline without interrupting the initialization flow.
 		this.on( 'init', () => {
 			this.fire( 'ready' );
 		}, { priority: 'lowest' } );
 
-		// Fix empty roots after DataController is 'ready' (note that init method could be decorated and stopped).
-		// We need to handle this event because initial data could be empty and post-fixer would not get triggered.
+		// Fix empty roots after DataController is 'ready' (note that the init method could be decorated and stopped).
+		// We need to handle this event because initial data could be empty and the post-fixer would not get triggered.
 		this.on( 'ready', () => {
-			this.model.enqueueChange( 'transparent', autoParagraphEmptyRoots );
+			this.model.enqueueChange( { isUndoable: false }, autoParagraphEmptyRoots );
 		}, { priority: 'lowest' } );
 	}
 
@@ -170,7 +171,7 @@ export default class DataController {
 	 * @param {String} [options.rootName='main'] Root name.
 	 * @param {String} [options.trim='empty'] Whether returned data should be trimmed. This option is set to `empty` by default,
 	 * which means whenever editor content is considered empty, an empty string will be returned. To turn off trimming completely
-	 * use `'none'`. In such cases exact content will be returned (for example `<p>&nbsp;</p>` for an empty editor).
+	 * use `'none'`. In such cases the exact content will be returned (for example a `<p>&nbsp;</p>` for an empty editor).
 	 * @returns {String} Output data.
 	 */
 	get( options = {} ) {
@@ -179,7 +180,7 @@ export default class DataController {
 		if ( !this._checkIfRootsExists( [ rootName ] ) ) {
 			/**
 			 * Cannot get data from a non-existing root. This error is thrown when {@link #get DataController#get() method}
-			 * is called with non-existent root name. For example, if there is an editor instance with only `main` root,
+			 * is called with a non-existent root name. For example, if there is an editor instance with only `main` root,
 			 * calling {@link #get} like:
 			 *
 			 *		data.get( { rootName: 'root2' } );
@@ -203,10 +204,10 @@ export default class DataController {
 	/**
 	 * Returns the content of the given {@link module:engine/model/element~Element model's element} or
 	 * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the downcast converters
-	 * attached to {@link #downcastDispatcher} and formatted by the {@link #processor data processor}.
+	 * attached to the {@link #downcastDispatcher} and formatted by the {@link #processor data processor}.
 	 *
 	 * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
-	 * Element whose content will be stringified.
+	 * The element whose content will be stringified.
 	 * @param {Object} [options] Additional configuration passed to the conversion process.
 	 * @returns {String} Output data.
 	 */
@@ -221,12 +222,12 @@ export default class DataController {
 	/**
 	 * Returns the content of the given {@link module:engine/model/element~Element model element} or
 	 * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the downcast
-	 * converters attached to {@link #downcastDispatcher} to a
+	 * converters attached to {@link #downcastDispatcher} into a
 	 * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
 	 *
 	 * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
 	 * Element or document fragment whose content will be converted.
-	 * @param {Object} [options={}] Additional configuration that will be available through
+	 * @param {Object} [options={}] Additional configuration that will be available through the
 	 * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi#options} during the conversion process.
 	 * @returns {module:engine/view/documentfragment~DocumentFragment} Output view DocumentFragment.
 	 */
@@ -234,7 +235,7 @@ export default class DataController {
 		const viewDocument = this.viewDocument;
 		const viewWriter = this._viewWriter;
 
-		// Clear bindings so the call to this method gives correct results.
+		// Clear bindings so the call to this method returns correct results.
 		this.mapper.clearBindings();
 
 		// First, convert elements.
@@ -243,57 +244,46 @@ export default class DataController {
 
 		this.mapper.bindElements( modelElementOrFragment, viewDocumentFragment );
 
-		// Make additional options available during conversion process through `conversionApi`.
-		this.downcastDispatcher.conversionApi.options = options;
-
-		// We have no view controller and rendering to DOM in DataController so view.change() block is not used here.
-		this.downcastDispatcher.convertInsert( modelRange, viewWriter );
-
-		// Convert markers.
+		// Prepare list of markers.
 		// For document fragment, simply take the markers assigned to this document fragment.
 		// For model root, all markers in that root will be taken.
 		// For model element, we need to check which markers are intersecting with this element and relatively modify the markers' ranges.
 		// Collapsed markers at element boundary, although considered as not intersecting with the element, will also be returned.
 		const markers = modelElementOrFragment.is( 'documentFragment' ) ?
-			Array.from( modelElementOrFragment.markers ) :
+			modelElementOrFragment.markers :
 			_getMarkersRelativeToElement( modelElementOrFragment );
 
-		for ( const [ name, range ] of markers ) {
-			this.downcastDispatcher.convertMarkerAdd( name, range, viewWriter );
-		}
-
-		// Clean `conversionApi`.
-		delete this.downcastDispatcher.conversionApi.options;
+		this.downcastDispatcher.convert( modelRange, markers, viewWriter, options );
 
 		return viewDocumentFragment;
 	}
 
 	/**
-	 * Sets initial input data parsed by the {@link #processor data processor} and
+	 * Sets the initial input data parsed by the {@link #processor data processor} and
 	 * converted by the {@link #upcastDispatcher view-to-model converters}.
-	 * Initial data can be set only to document that {@link module:engine/model/document~Document#version} is equal 0.
+	 * Initial data can be only set to a document whose {@link module:engine/model/document~Document#version} is equal 0.
 	 *
 	 * **Note** This method is {@link module:utils/observablemixin~ObservableMixin#decorate decorated} which is
 	 * used by e.g. collaborative editing plugin that syncs remote data on init.
 	 *
-	 * When data is passed as a string it is initialized on a default `main` root:
+	 * When data is passed as a string, it is initialized on the default `main` root:
 	 *
-	 *		dataController.init( '<p>Foo</p>' ); // Initializes data on the `main` root.
+	 *		dataController.init( '<p>Foo</p>' ); // Initializes data on the `main` root only, as no other is specified.
 	 *
-	 * To initialize data on a different root or multiple roots at once, object containing `rootName` - `data` pairs should be passed:
+	 * To initialize data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
 	 *
-	 *		dataController.init( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Initializes data on the `main` and `title` roots.
+	 *		dataController.init( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Initializes data on both the `main` and `title` roots.
 	 *
 	 * @fires init
-	 * @param {String|Object.<String,String>} data Input data as a string or an object containing `rootName` - `data`
+	 * @param {String|Object.<String,String>} data Input data as a string or an object containing the `rootName` - `data`
 	 * pairs to initialize data on multiple roots at once.
 	 * @returns {Promise} Promise that is resolved after the data is set on the editor.
 	 */
 	init( data ) {
 		if ( this.model.document.version ) {
 			/**
-			 * Cannot set initial data to not empty {@link module:engine/model/document~Document}.
-			 * Initial data should be set once, during {@link module:core/editor/editor~Editor} initialization,
+			 * Cannot set initial data to a non-empty {@link module:engine/model/document~Document}.
+			 * Initial data should be set once, during the {@link module:core/editor/editor~Editor} initialization,
 			 * when the {@link module:engine/model/document~Document#version} is equal 0.
 			 *
 			 * @error datacontroller-init-document-not-empty
@@ -310,7 +300,7 @@ export default class DataController {
 
 		if ( !this._checkIfRootsExists( Object.keys( initialData ) ) ) {
 			/**
-			 * Cannot init data on a non-existing root. This error is thrown when {@link #init DataController#init() method}
+			 * Cannot init data on a non-existent root. This error is thrown when {@link #init DataController#init() method}
 			 * is called with non-existent root name. For example, if there is an editor instance with only `main` root,
 			 * calling {@link #init} like:
 			 *
@@ -323,7 +313,7 @@ export default class DataController {
 			throw new CKEditorError( 'datacontroller-init-non-existent-root', this );
 		}
 
-		this.model.enqueueChange( 'transparent', writer => {
+		this.model.enqueueChange( { isUndoable: false }, writer => {
 			for ( const rootName of Object.keys( initialData ) ) {
 				const modelRoot = this.model.document.getRoot( rootName );
 				writer.insert( this.parse( initialData[ rootName ], modelRoot ), modelRoot, 0 );
@@ -334,47 +324,48 @@ export default class DataController {
 	}
 
 	/**
-	 * Sets input data parsed by the {@link #processor data processor} and
+	 * Sets the input data parsed by the {@link #processor data processor} and
 	 * converted by the {@link #upcastDispatcher view-to-model converters}.
-	 * This method can be used any time to replace existing editor data by the new one without clearing the
+	 * This method can be used any time to replace existing editor data with the new one without clearing the
 	 * {@link module:engine/model/document~Document#history document history}.
 	 *
 	 * This method also creates a batch with all the changes applied. If all you need is to parse data, use
 	 * the {@link #parse} method.
 	 *
-	 * When data is passed as a string it is set on a default `main` root:
+	 * When data is passed as a string it is set on the default `main` root:
 	 *
-	 *		dataController.set( '<p>Foo</p>' ); // Sets data on the `main` root.
+	 *		dataController.set( '<p>Foo</p>' ); // Sets data on the `main` root, as no other is specified.
 	 *
-	 * To set data on a different root or multiple roots at once, object containing `rootName` - `data` pairs should be passed:
+	 * To set data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed:
 	 *
-	 *		dataController.set( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Sets data on the `main` and `title` roots.
+	 *		dataController.set( { main: '<p>Foo</p>', title: '<h1>Bar</h1>' } ); // Sets data on the `main` and `title` roots as specified.
 	 *
-	 * To set the data with preserved undo stacks and set the current change to this stack, use the `{ batchType: 'default' }` option.
+	 * To set the data with a preserved undo stack and add the change to the undo stack, set `{ isUndoable: true }` as a `batchType` option.
 	 *
-	 *		dataController.set( '<p>Foo</p>', { batchType: 'default' } ); // Sets data as a new change.
+	 *		dataController.set( '<p>Foo</p>', { batchType: { isUndoable: true } } );
 	 *
 	 * @fires set
-	 * @param {String|Object.<String,String>} data Input data as a string or an object containing `rootName` - `data`
+	 * @param {String|Object.<String,String>} data Input data as a string or an object containing the `rootName` - `data`
 	 * pairs to set data on multiple roots at once.
 	 * @param {Object} [options={}] Options for setting data.
-	 * @param {'default'|'transparent'} [options.batchType='default'] The batch type that will be used to create a batch for the changes.
-	 * When set to `default`, the undo and redo stacks will be preserved. Note that when not set, the undo feature (when present) will
-	 * override it to `transparent` and all undo steps will be lost.
+	 * @param {Object} [options.batchType] The batch type that will be used to create a batch for the changes applied by this method.
+	 * By default, the batch will be set as {@link module:engine/model/batch~Batch#isUndoable not undoable} and the undo stack will be
+	 * cleared after the new data is applied (all undo steps will be removed). If the batch type `isUndoable` flag is be set to `true`,
+	 * the undo stack will be preserved instead and not cleared when new data is applied.
 	 */
 	set( data, options = {} ) {
 		let newData = {};
 
 		if ( typeof data === 'string' ) {
-			newData.main = data; // Default root is 'main'. To set data on a different root, object should be passed.
+			newData.main = data; // The default root is 'main'. To set data on a different root, an object should be passed.
 		} else {
 			newData = data;
 		}
 
 		if ( !this._checkIfRootsExists( Object.keys( newData ) ) ) {
 			/**
-			 * Cannot set data on a non-existing root. This error is thrown when {@link #set DataController#set() method}
-			 * is called with non-existent root name. For example, if there is an editor instance with only `main` root,
+			 * Cannot set data on a non-existent root. This error is thrown when the {@link #set DataController#set() method}
+			 * is called with non-existent root name. For example, if there is an editor instance with only the default `main` root,
 			 * calling {@link #set} like:
 			 *
 			 * 		data.set( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
@@ -386,9 +377,7 @@ export default class DataController {
 			throw new CKEditorError( 'datacontroller-set-non-existent-root', this );
 		}
 
-		const batchType = options.batchType || 'default';
-
-		this.model.enqueueChange( batchType, writer => {
+		this.model.enqueueChange( options.batchType || {}, writer => {
 			writer.setSelection( null );
 			writer.removeSelectionAttribute( this.model.document.selection.getAttributeKeys() );
 
@@ -429,7 +418,7 @@ export default class DataController {
 	 * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
 	 *
 	 * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment
-	 * Element or document fragment whose content will be converted.
+	 * The element or document fragment whose content will be converted.
 	 * @param {module:engine/model/schema~SchemaContextDefinition} [context='$root'] Base context in which the view will
 	 * be converted to the model. See: {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#convert}.
 	 * @returns {module:engine/model/documentfragment~DocumentFragment} Output document fragment.
@@ -441,7 +430,7 @@ export default class DataController {
 	}
 
 	/**
-	 * Adds a style processor normalization rules.
+	 * Adds the style processor normalization rules.
 	 *
 	 * You can implement your own rules as well as use one of the available processor rules:
 	 *
@@ -457,18 +446,18 @@ export default class DataController {
 	}
 
 	/**
-	 * Registers a {@link module:engine/view/matcher~MatcherPattern} on {@link #htmlProcessor htmlProcessor}
-	 * and {@link #processor processor} for view elements whose content should be treated as a raw data
-	 * and not processed during conversion from DOM to view elements.
+	 * Registers a {@link module:engine/view/matcher~MatcherPattern} on an {@link #htmlProcessor htmlProcessor}
+	 * and a {@link #processor processor} for view elements whose content should be treated as raw data
+	 * and not processed during the conversion from DOM to view elements.
 	 *
-	 * The raw data can be later accessed by {@link module:engine/view/element~Element#getCustomProperty view element custom property}
+	 * The raw data can be later accessed by the {@link module:engine/view/element~Element#getCustomProperty view element custom property}
 	 * `"$rawContent"`.
 	 *
 	 * @param {module:engine/view/matcher~MatcherPattern} pattern Pattern matching all view elements whose content should
 	 * be treated as a raw data.
 	 */
 	registerRawContentMatcher( pattern ) {
-		// No need to register the pattern if both `htmlProcessor` and `processor` are the same instances.
+		// No need to register the pattern if both the `htmlProcessor` and `processor` are the same instances.
 		if ( this.processor && this.processor !== this.htmlProcessor ) {
 			this.processor.registerRawContentMatcher( pattern );
 		}
@@ -484,7 +473,7 @@ export default class DataController {
 	}
 
 	/**
-	 * Checks if all provided root names are existing editor roots.
+	 * Checks whether all provided root names are actually existing editor roots.
 	 *
 	 * @private
 	 * @param {Array.<String>} rootNames Root names to check.
@@ -507,7 +496,7 @@ export default class DataController {
 	 */
 
 	/**
-	 * Event fired after the {@link #init `init()` method} was run. It can be {@link #listenTo listened to} in order to adjust or modify
+	 * An event fired after the {@link #init `init()` method} was run. It can be {@link #listenTo listened to} in order to adjust or modify
 	 * the initialization flow. However, if the `init` event is stopped or prevented, the {@link #event:ready `ready` event}
 	 * should be fired manually.
 	 *
@@ -518,9 +507,9 @@ export default class DataController {
 	 */
 
 	/**
-	 * Event fired after {@link #set set() method} has been run.
+	 * An event fired after {@link #set set() method} has been run.
 	 *
-	 * The `set` event is fired by decorated {@link #set} method.
+	 * The `set` event is fired by the decorated {@link #set} method.
 	 * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
 	 *
 	 * @event set
@@ -529,7 +518,7 @@ export default class DataController {
 	/**
 	 * Event fired after the {@link #get get() method} has been run.
 	 *
-	 * The `get` event is fired by decorated {@link #get} method.
+	 * The `get` event is fired by the decorated {@link #get} method.
 	 * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
 	 *
 	 * @event get
@@ -548,7 +537,7 @@ function _getMarkersRelativeToElement( element ) {
 	const doc = element.root.document;
 
 	if ( !doc ) {
-		return [];
+		return new Map();
 	}
 
 	const elementRange = ModelRange._createIn( element );
@@ -582,7 +571,7 @@ function _getMarkersRelativeToElement( element ) {
 	// reverse DOM order, and intersecting ranges are in something approximating
 	// reverse DOM order (since reverse DOM order doesn't have a precise meaning
 	// when working with intersecting ranges).
-	return result.sort( ( [ n1, r1 ], [ n2, r2 ] ) => {
+	result.sort( ( [ n1, r1 ], [ n2, r2 ] ) => {
 		if ( r1.end.compareWith( r2.start ) !== 'after' ) {
 			// m1.end <= m2.start -- m1 is entirely <= m2
 			return 1;
@@ -609,4 +598,6 @@ function _getMarkersRelativeToElement( element ) {
 			}
 		}
 	} );
+
+	return new Map( result );
 }

package/src/controller/editingcontroller.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -11,16 +11,24 @@ import RootEditableElement from '../view/rooteditableelement';
 import View from '../view/view';
 import Mapper from '../conversion/mapper';
 import DowncastDispatcher from '../conversion/downcastdispatcher';
-import { clearAttributes, convertCollapsedSelection, convertRangeSelection, insertText, remove } from '../conversion/downcasthelpers';
+import {
+	clearAttributes,
+	convertCollapsedSelection,
+	convertRangeSelection,
+	insertAttributesAndChildren,
+	insertText,
+	remove
+} from '../conversion/downcasthelpers';
 
 import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import { convertSelectionChange } from '../conversion/upcasthelpers';
 
 // @if CK_DEBUG_ENGINE // const { dumpTrees, initDocumentDumping } = require( '../dev-utils/utils' );
 
 /**
- * Controller for the editing pipeline. The editing pipeline controls {@link ~EditingController#model model} rendering,
+ * A controller for the editing pipeline. The editing pipeline controls the {@link ~EditingController#model model} rendering,
  * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
  * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
  *
@@ -51,7 +59,7 @@ export default class EditingController {
 		this.view = new View( stylesProcessor );
 
 		/**
-		 * Mapper which describes the model-view binding.
+		 * A mapper that describes the model-view binding.
 		 *
 		 * @readonly
 		 * @member {module:engine/conversion/mapper~Mapper}
@@ -59,7 +67,7 @@ export default class EditingController {
 		this.mapper = new Mapper();
 
 		/**
-		 * Downcast dispatcher that converts changes from the model to {@link #view the editing view}.
+		 * Downcast dispatcher that converts changes from the model to the {@link #view editing view}.
 		 *
 		 * @readonly
 		 * @member {module:engine/conversion/downcastdispatcher~DowncastDispatcher} #downcastDispatcher
@@ -74,7 +82,7 @@ export default class EditingController {
 		const markers = this.model.markers;
 
 		// When plugins listen on model changes (on selection change, post fixers, etc.) and change the view as a result of
-		// model's change, they might trigger view rendering before the conversion is completed (e.g. before the selection
+		// the model's change, they might trigger view rendering before the conversion is completed (e.g. before the selection
 		// is converted). We disable rendering for the length of the outermost model change() block to prevent that.
 		//
 		// See https://github.com/ckeditor/ckeditor5-engine/issues/1528
@@ -101,6 +109,7 @@ export default class EditingController {
 
 		// Attach default model converters.
 		this.downcastDispatcher.on( 'insert:$text', insertText(), { priority: 'lowest' } );
+		this.downcastDispatcher.on( 'insert', insertAttributesAndChildren(), { priority: 'lowest' } );
 		this.downcastDispatcher.on( 'remove', remove(), { priority: 'low' } );
 
 		// Attach default model selection converters.
@@ -144,6 +153,74 @@ export default class EditingController {
 		this.view.destroy();
 		this.stopListening();
 	}
+
+	/**
+	 * Calling this method will refresh the marker by triggering the downcast conversion for it.
+	 *
+	 * Reconverting the marker is useful when you want to change its {@link module:engine/view/element~Element view element}
+	 * without changing any marker data. For instance:
+	 *
+	 *		let isCommentActive = false;
+	 *
+	 *		model.conversion.markerToHighlight( {
+	 *			model: 'comment',
+	 *			view: data => {
+	 *				const classes = [ 'comment-marker' ];
+	 *
+	 *				if ( isCommentActive ) {
+	 *					classes.push( 'comment-marker--active' );
+	 *				}
+	 *
+	 *				return { classes };
+	 *			}
+	 *		} );
+	 *
+	 *		// ...
+	 *
+	 *		// Change the property that indicates if marker is displayed as active or not.
+	 *		isCommentActive = true;
+	 *
+	 *		// Reconverting will downcast and synchronize the marker with the new isCommentActive state value.
+	 *		editor.editing.reconvertMarker( 'comment' );
+	 *
+	 * **Note**: If you want to reconvert a model item, use {@link #reconvertItem} instead.
+	 *
+	 * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of a marker to update, or a marker instance.
+	 */
+	reconvertMarker( markerOrName ) {
+		const markerName = typeof markerOrName == 'string' ? markerOrName : markerOrName.name;
+		const currentMarker = this.model.markers.get( markerName );
+
+		if ( !currentMarker ) {
+			/**
+			 * The marker with the provided name does not exist and cannot be reconverted.
+			 *
+			 * @error editingcontroller-reconvertmarker-marker-not-exist
+			 * @param {String} markerName The name of the reconverted marker.
+			 */
+			throw new CKEditorError( 'editingcontroller-reconvertmarker-marker-not-exist', this, { markerName } );
+		}
+
+		this.model.change( () => {
+			this.model.markers._refresh( currentMarker );
+		} );
+	}
+
+	/**
+	 * Calling this method will downcast a model item on demand (by requesting a refresh in the {@link module:engine/model/differ~Differ}).
+	 *
+	 * You can use it if you want the view representation of a specific item updated as a response to external modifications. For instance,
+	 * when the view structure depends not only on the associated model data but also on some external state.
+	 *
+	 * **Note**: If you want to reconvert a model marker, use {@link #reconvertMarker} instead.
+	 *
+	 * @param {module:engine/model/item~Item} item Item to refresh.
+	 */
+	reconvertItem( item ) {
+		this.model.change( () => {
+			this.model.document.differ._refreshItem( item );
+		} );
+	}
 }
 
 mix( EditingController, ObservableMixin );