@ckeditor/ckeditor5-engine 32.0.0 → 33.0.0

package/src/dev-utils/model.js

@@ -31,6 +31,7 @@ import Mapper from '../conversion/mapper';
 import {
 	convertCollapsedSelection,
 	convertRangeSelection,
+	insertAttributesAndChildren,
 	insertElement,
 	insertText,
 	insertUIElement,
@@ -233,6 +234,7 @@ export function stringify( node, selectionOrPositionOrRange = null, markers = nu
 	mapper.bindElements( node.root, viewRoot );
 
 	downcastDispatcher.on( 'insert:$text', insertText() );
+	downcastDispatcher.on( 'insert', insertAttributesAndChildren(), { priority: 'lowest' } );
 	downcastDispatcher.on( 'attribute', ( evt, data, conversionApi ) => {
 		if ( data.item instanceof ModelSelection || data.item instanceof DocumentSelection || data.item.is( '$textProxy' ) ) {
 			const converter = wrap( ( modelAttributeValue, { writer } ) => {
@@ -260,28 +262,28 @@ export function stringify( node, selectionOrPositionOrRange = null, markers = nu
 		return writer.createUIElement( name );
 	} ) );
 
+	const markersMap = new Map();
+
+	if ( markers ) {
+		// To provide stable results, sort markers by name.
+		for ( const marker of Array.from( markers ).sort( ( a, b ) => a.name < b.name ? 1 : -1 ) ) {
+			markersMap.set( marker.name, marker.getRange() );
+		}
+	}
+
 	// Convert model to view.
 	const writer = view._writer;
-	downcastDispatcher.convertInsert( range, writer );
+	downcastDispatcher.convert( range, markersMap, writer );
 
 	// Convert model selection to view selection.
 	if ( selection ) {
 		downcastDispatcher.convertSelection( selection, markers || model.markers, writer );
 	}
 
-	if ( markers ) {
-		// To provide stable results, sort markers by name.
-		markers = Array.from( markers ).sort( ( a, b ) => a.name < b.name ? 1 : -1 );
-
-		for ( const marker of markers ) {
-			downcastDispatcher.convertMarkerAdd( marker.name, marker.getRange(), writer );
-		}
-	}
-
 	// Parse view to data string.
 	let data = viewStringify( viewRoot, viewDocument.selection, { sameSelectionCharacters: true } );
 
-	// Removing unneccessary <div> and </div> added because `viewRoot` was also stringified alongside input data.
+	// Removing unnecessary <div> and </div> added because `viewRoot` was also stringified alongside input data.
 	data = data.substr( 5, data.length - 11 );
 
 	view.destroy();

package/src/index.js

@@ -28,6 +28,7 @@ export { default as LivePosition } from './model/liveposition';
 export { default as Model } from './model/model';
 export { default as TreeWalker } from './model/treewalker';
 export { default as Element } from './model/element';
+export { default as History } from './model/history';
 
 export { default as DomConverter } from './view/domconverter';
 export { default as Renderer } from './view/renderer';

package/src/model/batch.js

@@ -27,20 +27,20 @@ export default class Batch {
 	 *
 	 * @see module:engine/model/model~Model#enqueueChange
 	 * @see module:engine/model/model~Model#change
-	 * @param {Object} [type] Set of flags that specifies the type of the batch. Batch type can alter how some of the features work when
-	 * encountering given `Batch` instance (for example, when a feature listens to applied operations).
-	 * @param {Boolean} [type.isUndoable=true] Whether batch can be undone through undo feature.
-	 * @param {Boolean} [type.isLocal=true] Whether batch includes operations created locally (`true`) or operations created on
+	 * @param {Object} [type] A set of flags that specify the type of the batch. Batch type can alter how some of the features work
+	 * when encountering a given `Batch` instance (for example, when a feature listens to applied operations).
+	 * @param {Boolean} [type.isUndoable=true] Whether a batch can be undone through undo feature.
+	 * @param {Boolean} [type.isLocal=true] Whether a batch includes operations created locally (`true`) or operations created on
 	 * other, remote editors (`false`).
-	 * @param {Boolean} [type.isUndo=false] Whether batch was created by the undo feature and undoes other operations.
-	 * @param {Boolean} [type.isTyping=false] Whether batch includes operations connected with typing action.
+	 * @param {Boolean} [type.isUndo=false] Whether a batch was created by the undo feature and undoes other operations.
+	 * @param {Boolean} [type.isTyping=false] Whether a batch includes operations connected with a typing action.
 	 */
 	constructor( type = {} ) {
 		if ( typeof type === 'string' ) {
 			type = type === 'transparent' ? { isUndoable: false } : {};
 
 			/**
-			 * The string value for `type` property of the `Batch` constructor has been deprecated and will be removed in the near future.
+			 * The string value for a `type` property of the `Batch` constructor has been deprecated and will be removed in the near future.
 			 * Please refer to the {@link module:engine/model/batch~Batch#constructor `Batch` constructor API documentation} for more
 			 * information.
 			 *
@@ -60,7 +60,7 @@ export default class Batch {
 		this.operations = [];
 
 		/**
-		 * Whether batch can be undone through the undo feature.
+		 * Whether the batch can be undone through the undo feature.
 		 *
 		 * @readonly
 		 * @type {Boolean}
@@ -68,7 +68,7 @@ export default class Batch {
 		this.isUndoable = isUndoable;
 
 		/**
-		 * Whether batch includes operations created locally (`true`) or operations created on other, remote editors (`false`).
+		 * Whether the batch includes operations created locally (`true`) or operations created on other, remote editors (`false`).
 		 *
 		 * @readonly
 		 * @type {Boolean}
@@ -76,7 +76,7 @@ export default class Batch {
 		this.isLocal = isLocal;
 
 		/**
-		 * Whether batch was created by the undo feature and undoes other operations.
+		 * Whether the batch was created by the undo feature and undoes other operations.
 		 *
 		 * @readonly
 		 * @type {Boolean}
@@ -84,7 +84,7 @@ export default class Batch {
 		this.isUndo = isUndo;
 
 		/**
-		 * Whether batch includes operations connected with typing.
+		 * Whether the batch includes operations connected with typing.
 		 *
 		 * @readonly
 		 * @type {Boolean}
@@ -95,7 +95,7 @@ export default class Batch {
 	/**
 	 * The type of the batch.
 	 *
-	 * **This property has been deprecated and is always set to `'default'` value.**
+	 * **This property has been deprecated and is always set to the `'default'` value.**
 	 *
 	 * It can be one of the following values:
 	 * * `'default'` – All "normal" batches. This is the most commonly used type.

package/src/model/differ.js

@@ -58,11 +58,12 @@ export default class Differ {
 		 * A map that stores all changed markers.
 		 *
 		 * The keys of the map are marker names.
-		 * The values of the map are objects with the `oldRange` and `newRange` properties. They store the marker range
-		 * state before and after the change.
+		 * The values of the map are objects with the following properties:
+		 * - `oldMarkerData`,
+		 * - `newMarkerData`.
 		 *
 		 * @private
-		 * @type {Map}
+		 * @type {Map.<String, Object>}
 		 */
 		this._changedMarkers = new Map();
 
@@ -98,6 +99,14 @@ export default class Differ {
 		 * @type {Array.<Object>|null}
 		 */
 		this._cachedChangesWithGraveyard = null;
+
+		/**
+		 * Set of model items that were marked to get refreshed in {@link #_refreshItem}.
+		 *
+		 * @private
+		 * @type {Set.<module:engine/model/item~Item>}
+		 */
+		this._refreshedItems = new Set();
 	}
 
 	/**
@@ -110,32 +119,6 @@ export default class Differ {
 		return this._changesInElement.size == 0 && this._changedMarkers.size == 0;
 	}
 
-	/**
-	 * Marks given `item` in differ to be "refreshed". It means that the item will be marked as removed and inserted in the differ changes
-	 * set, so it will be effectively re-converted when differ changes will be handled by a dispatcher.
-	 *
-	 * @param {module:engine/model/item~Item} item Item to refresh.
-	 */
-	refreshItem( item ) {
-		if ( this._isInInsertedElement( item.parent ) ) {
-			return;
-		}
-
-		this._markRemove( item.parent, item.startOffset, item.offsetSize );
-		this._markInsert( item.parent, item.startOffset, item.offsetSize );
-
-		const range = Range._createOn( item );
-
-		for ( const marker of this._markerCollection.getMarkersIntersectingRange( range ) ) {
-			const markerRange = marker.getRange();
-
-			this.bufferMarkerChange( marker.name, markerRange, markerRange, marker.affectsData );
-		}
-
-		// Clear cache after each buffered operation as it is no longer valid.
-		this._cachedChanges = null;
-	}
-
 	/**
 	 * Buffers the given operation. An operation has to be buffered before it is executed.
 	 *
@@ -208,9 +191,9 @@ export default class Differ {
 				const range = Range._createFromPositionAndShift( operation.position, 1 );
 
 				for ( const marker of this._markerCollection.getMarkersIntersectingRange( range ) ) {
-					const markerRange = marker.getRange();
+					const markerData = marker.getData();
 
-					this.bufferMarkerChange( marker.name, markerRange, markerRange, marker.affectsData );
+					this.bufferMarkerChange( marker.name, markerData, markerData );
 				}
 
 				break;
@@ -267,27 +250,23 @@ export default class Differ {
 	 * Buffers a marker change.
 	 *
 	 * @param {String} markerName The name of the marker that changed.
-	 * @param {module:engine/model/range~Range|null} oldRange Marker range before the change or `null` if the marker has just
-	 * been created.
-	 * @param {module:engine/model/range~Range|null} newRange Marker range after the change or `null` if the marker was removed.
-	 * @param {Boolean} affectsData Flag indicating whether marker affects the editor data.
+	 * @param {module:engine/model/markercollection~MarkerData} oldMarkerData Marker data before the change.
+	 * @param {module:engine/model/markercollection~MarkerData} newMarkerData Marker data after the change.
 	 */
-	bufferMarkerChange( markerName, oldRange, newRange, affectsData ) {
+	bufferMarkerChange( markerName, oldMarkerData, newMarkerData ) {
 		const buffered = this._changedMarkers.get( markerName );
 
 		if ( !buffered ) {
 			this._changedMarkers.set( markerName, {
-				oldRange,
-				newRange,
-				affectsData
+				newMarkerData,
+				oldMarkerData
 			} );
 		} else {
-			buffered.newRange = newRange;
-			buffered.affectsData = affectsData;
+			buffered.newMarkerData = newMarkerData;
 
-			if ( buffered.oldRange == null && buffered.newRange == null ) {
-				// The marker is going to be removed (`newRange == null`) but it did not exist before the first buffered change
-				// (`buffered.oldRange == null`). In this case, do not keep the marker in buffer at all.
+			if ( buffered.oldMarkerData.range == null && newMarkerData.range == null ) {
+				// The marker is going to be removed (`newMarkerData.range == null`) but it did not exist before the first buffered change
+				// (`buffered.oldMarkerData.range == null`). In this case, do not keep the marker in buffer at all.
 				this._changedMarkers.delete( markerName );
 			}
 		}
@@ -302,8 +281,8 @@ export default class Differ {
 		const result = [];
 
 		for ( const [ name, change ] of this._changedMarkers ) {
-			if ( change.oldRange != null ) {
-				result.push( { name, range: change.oldRange } );
+			if ( change.oldMarkerData.range != null ) {
+				result.push( { name, range: change.oldMarkerData.range } );
 			}
 		}
 
@@ -319,8 +298,8 @@ export default class Differ {
 		const result = [];
 
 		for ( const [ name, change ] of this._changedMarkers ) {
-			if ( change.newRange != null ) {
-				result.push( { name, range: change.newRange } );
+			if ( change.newMarkerData.range != null ) {
+				result.push( { name, range: change.newMarkerData.range } );
 			}
 		}
 
@@ -333,12 +312,12 @@ export default class Differ {
 	 * @returns {Array.<Object>}
 	 */
 	getChangedMarkers() {
-		return Array.from( this._changedMarkers ).map( item => (
+		return Array.from( this._changedMarkers ).map( ( [ name, change ] ) => (
 			{
-				name: item[ 0 ],
+				name,
 				data: {
-					oldRange: item[ 1 ].oldRange,
-					newRange: item[ 1 ].newRange
+					oldRange: change.oldMarkerData.range,
+					newRange: change.newMarkerData.range
 				}
 			}
 		) );
@@ -351,13 +330,23 @@ export default class Differ {
 	 *
 	 * * model structure changes,
 	 * * attribute changes,
-	 * * changes of markers which were defined as `affectingData`.
+	 * * changes of markers which were defined as `affectsData`,
+	 * * changes of markers' `affectsData` property.
 	 *
 	 * @returns {Boolean}
 	 */
 	hasDataChanges() {
-		for ( const [ , change ] of this._changedMarkers ) {
-			if ( change.affectsData ) {
+		for ( const { newMarkerData, oldMarkerData } of this._changedMarkers.values() ) {
+			if ( newMarkerData.affectsData !== oldMarkerData.affectsData ) {
+				return true;
+			}
+
+			if ( newMarkerData.affectsData ) {
+				// Skip markers, which ranges have not changed.
+				if ( newMarkerData.range && oldMarkerData.range && newMarkerData.range.isEqual( oldMarkerData.range ) ) {
+					return false;
+				}
+
 				return true;
 			}
 		}
@@ -540,16 +529,25 @@ export default class Differ {
 		this._changeCount = 0;
 
 		// Cache changes.
-		this._cachedChangesWithGraveyard = diffSet.slice();
+		this._cachedChangesWithGraveyard = diffSet;
 		this._cachedChanges = diffSet.filter( _changesInGraveyardFilter );
 
 		if ( options.includeChangesInGraveyard ) {
-			return this._cachedChangesWithGraveyard;
+			return this._cachedChangesWithGraveyard.slice();
 		} else {
-			return this._cachedChanges;
+			return this._cachedChanges.slice();
 		}
 	}
 
+	/**
+	 * Returns a set of model items that were marked to get refreshed.
+	 *
+	 * @return {Set.<module:engine/model/item~Item>}
+	 */
+	getRefreshedItems() {
+		return new Set( this._refreshedItems );
+	}
+
 	/**
 	 * Resets `Differ`. Removes all buffered changes.
 	 */
@@ -557,6 +555,36 @@ export default class Differ {
 		this._changesInElement.clear();
 		this._elementSnapshots.clear();
 		this._changedMarkers.clear();
+		this._refreshedItems = new Set();
+		this._cachedChanges = null;
+	}
+
+	/**
+	 * Marks the given `item` in differ to be "refreshed". It means that the item will be marked as removed and inserted
+	 * in the differ changes set, so it will be effectively re-converted when the differ changes are handled by a dispatcher.
+	 *
+	 * @protected
+	 * @param {module:engine/model/item~Item} item Item to refresh.
+	 */
+	_refreshItem( item ) {
+		if ( this._isInInsertedElement( item.parent ) ) {
+			return;
+		}
+
+		this._markRemove( item.parent, item.startOffset, item.offsetSize );
+		this._markInsert( item.parent, item.startOffset, item.offsetSize );
+
+		this._refreshedItems.add( item );
+
+		const range = Range._createOn( item );
+
+		for ( const marker of this._markerCollection.getMarkersIntersectingRange( range ) ) {
+			const markerData = marker.getData();
+
+			this.bufferMarkerChange( marker.name, markerData, markerData );
+		}
+
+		// Clear cache after each buffered operation as it is no longer valid.
 		this._cachedChanges = null;
 	}
 

package/src/model/document.js

@@ -157,14 +157,23 @@ export default class Document {
 		// Buffer marker changes.
 		// This is not covered in buffering operations because markers may change outside of them (when they
 		// are modified using `model.markers` collection, not through `MarkerOperation`).
-		this.listenTo( model.markers, 'update', ( evt, marker, oldRange, newRange ) => {
+		this.listenTo( model.markers, 'update', ( evt, marker, oldRange, newRange, oldMarkerData ) => {
+			// Copy the `newRange` to the new marker data as during the marker removal the range is not updated.
+			const newMarkerData = { ...marker.getData(), range: newRange };
+
 			// Whenever marker is updated, buffer that change.
-			this.differ.bufferMarkerChange( marker.name, oldRange, newRange, marker.affectsData );
+			this.differ.bufferMarkerChange( marker.name, oldMarkerData, newMarkerData );
 
 			if ( oldRange === null ) {
 				// If this is a new marker, add a listener that will buffer change whenever marker changes.
 				marker.on( 'change', ( evt, oldRange ) => {
-					this.differ.bufferMarkerChange( marker.name, oldRange, marker.getRange(), marker.affectsData );
+					const markerData = marker.getData();
+
+					this.differ.bufferMarkerChange(
+						marker.name,
+						{ ...markerData, range: oldRange },
+						markerData
+					);
 				} );
 			}
 		} );

package/src/model/markercollection.js

@@ -106,6 +106,8 @@ export default class MarkerCollection {
 		const oldMarker = this._markers.get( markerName );
 
 		if ( oldMarker ) {
+			const oldMarkerData = oldMarker.getData();
+
 			const oldRange = oldMarker.getRange();
 			let hasChanged = false;
 
@@ -125,7 +127,7 @@ export default class MarkerCollection {
 			}
 
 			if ( hasChanged ) {
-				this.fire( 'update:' + markerName, oldMarker, oldRange, range );
+				this.fire( 'update:' + markerName, oldMarker, oldRange, range, oldMarkerData );
 			}
 
 			return oldMarker;
@@ -135,7 +137,7 @@ export default class MarkerCollection {
 		const marker = new Marker( markerName, liveRange, managedUsingOperations, affectsData );
 
 		this._markers.set( markerName, marker );
-		this.fire( 'update:' + markerName, marker, null, range );
+		this.fire( 'update:' + markerName, marker, null, range, { ...marker.getData(), range: null } );
 
 		return marker;
 	}
@@ -154,7 +156,7 @@ export default class MarkerCollection {
 
 		if ( oldMarker ) {
 			this._markers.delete( markerName );
-			this.fire( 'update:' + markerName, oldMarker, oldMarker.getRange(), null );
+			this.fire( 'update:' + markerName, oldMarker, oldMarker.getRange(), null, oldMarker.getData() );
 
 			this._destroyMarker( oldMarker );
 
@@ -188,7 +190,7 @@ export default class MarkerCollection {
 
 		const range = marker.getRange();
 
-		this.fire( 'update:' + markerName, marker, range, range, marker.managedUsingOperations, marker.affectsData );
+		this.fire( 'update:' + markerName, marker, range, range, marker.getData() );
 	}
 
 	/**
@@ -273,11 +275,20 @@ export default class MarkerCollection {
 	 * means that marker is just added.
 	 * @param {module:engine/model/range~Range|null} newRange Marker range after update. When is not defined it
 	 * means that marker is just removed.
+	 * @param {module:engine/model/markercollection~MarkerData} oldMarkerData Data of the marker before the change.
 	 */
 }
 
 mix( MarkerCollection, EmitterMixin );
 
+/**
+ * @typedef {Object} module:engine/model/markercollection~MarkerData
+ *
+ * @property {module:engine/model/range~Range|null} range Marker range. `null` if the marker was removed.
+ * @property {Boolean} affectsData A property defining if the marker affects data.
+ * @property {Boolean} managedUsingOperations A property defining if the marker is managed using operations.
+ */
+
 /**
  * `Marker` is a continuous parts of model (like a range), is named and represent some kind of information about marked
  * part of model document. In contrary to {@link module:engine/model/node~Node nodes}, which are building blocks of
@@ -418,6 +429,19 @@ class Marker {
 		return this._affectsData;
 	}
 
+	/**
+	 * Returns the marker data (properties defining the marker).
+	 *
+	 * @returns {module:engine/model/markercollection~MarkerData}
+	 */
+	getData() {
+		return {
+			range: this.getRange(),
+			affectsData: this.affectsData,
+			managedUsingOperations: this.managedUsingOperations
+		};
+	}
+
 	/**
 	 * Returns current marker start position.
 	 *

package/src/model/model.js

@@ -215,7 +215,7 @@ export default class Model {
 	 *
 	 * Second, it lets you define the {@link module:engine/model/batch~Batch} into which you want to add your changes.
 	 * By default, a new batch with the default {@link module:engine/model/batch~Batch#constructor batch type} is created.
-	 * In the sample above, `change` and `enqueueChange` blocks will use a different batch (and a different
+	 * In the sample above, the `change` and `enqueueChange` blocks will use a different batch (and a different
 	 * {@link module:engine/model/writer~Writer} instance since each of them operates on a separate batch).
 	 *
 	 *		model.enqueueChange( { isUndoable: false }, writer => {
@@ -516,6 +516,7 @@ export default class Model {
 	 * @param {Object} [options]
 	 * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
 	 * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
+	 * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
 	 */
 	modifySelection( selection, options ) {
 		modifySelection( this, selection, options );

package/src/model/utils/modifyselection.js

@@ -10,7 +10,7 @@
 import Position from '../position';
 import TreeWalker from '../treewalker';
 import Range from '../range';
-import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckeditor5-utils/src/unicode';
+import { isInsideSurrogatePair, isInsideCombinedSymbol, isInsideEmojiSequence } from '@ckeditor/ckeditor5-utils/src/unicode';
 import DocumentSelection from '../documentselection';
 
 const wordBoundaryCharacters = ' ,.?!:;"-()';
@@ -49,11 +49,13 @@ const wordBoundaryCharacters = ' ,.?!:;"-()';
  * @param {Object} [options]
  * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
  * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
+ * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
  */
 export default function modifySelection( model, selection, options = {} ) {
 	const schema = model.schema;
 	const isForward = options.direction != 'backward';
 	const unit = options.unit ? options.unit : 'character';
+	const treatEmojiAsSingleUnit = !!options.treatEmojiAsSingleUnit;
 
 	const focus = selection.focus;
 
@@ -63,7 +65,7 @@ export default function modifySelection( model, selection, options = {} ) {
 		direction: isForward ? 'forward' : 'backward'
 	} );
 
-	const data = { walker, schema, isForward, unit };
+	const data = { walker, schema, isForward, unit, treatEmojiAsSingleUnit };
 
 	let next;
 
@@ -89,10 +91,10 @@ export default function modifySelection( model, selection, options = {} ) {
 }
 
 // Checks whether the selection can be extended to the the walker's next value (next position).
-// @param {{ walker, unit, isForward, schema }} data
+// @param {{ walker, unit, isForward, schema, treatEmojiAsSingleUnit }} data
 // @param {module:engine/view/treewalker~TreeWalkerValue} value
 function tryExtendingTo( data, value ) {
-	const { isForward, walker, unit, schema } = data;
+	const { isForward, walker, unit, schema, treatEmojiAsSingleUnit } = data;
 	const { type, item, nextPosition } = value;
 
 	// If found text, we can certainly put the focus in it. Let's just find a correct position
@@ -102,7 +104,7 @@ function tryExtendingTo( data, value ) {
 			return getCorrectWordBreakPosition( walker, isForward );
 		}
 
-		return getCorrectPosition( walker, unit, isForward );
+		return getCorrectPosition( walker, unit, treatEmojiAsSingleUnit );
 	}
 
 	// Entering an element.
@@ -139,14 +141,19 @@ function tryExtendingTo( data, value ) {
 //
 // @param {module:engine/model/treewalker~TreeWalker} walker
 // @param {String} unit The unit by which selection should be modified.
-function getCorrectPosition( walker, unit ) {
+// @param {Boolean} treatEmojiAsSingleUnit
+function getCorrectPosition( walker, unit, treatEmojiAsSingleUnit ) {
 	const textNode = walker.position.textNode;
 
 	if ( textNode ) {
 		const data = textNode.data;
 		let offset = walker.position.offset - textNode.startOffset;
 
-		while ( isInsideSurrogatePair( data, offset ) || ( unit == 'character' && isInsideCombinedSymbol( data, offset ) ) ) {
+		while (
+			isInsideSurrogatePair( data, offset ) ||
+			( unit == 'character' && isInsideCombinedSymbol( data, offset ) ) ||
+			( treatEmojiAsSingleUnit && isInsideEmojiSequence( data, offset ) )
+		) {
 			walker.next();
 
 			offset = walker.position.offset - textNode.startOffset;

package/src/model/writer.js

@@ -27,7 +27,7 @@ import DocumentSelection from './documentselection';
 
 import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
 
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import CKEditorError, { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
  * The model can only be modified by using the writer. It should be used whenever you want to create a node, modify
@@ -968,30 +968,8 @@ export default class Writer {
 	 * As the first parameter you can set marker name or instance. If none of them is provided, new marker, with a unique
 	 * name is created and returned.
 	 *
-	 * As the second parameter you can set the new marker data or leave this parameter as empty which will just refresh
-	 * the marker by triggering downcast conversion for it. Refreshing the marker is useful when you want to change
-	 * the marker {@link module:engine/view/element~Element view element} without changing any marker data.
-	 *
-	 * 		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;
-	 *
-	 * 		// And refresh the marker to convert it with additional class.
-	 * 		model.change( writer => writer.updateMarker( 'comment' ) );
+	 * **Note**: If you want to change the {@link module:engine/view/element~Element view element} of the marker while its data in the model
+	 * remains the same, use the dedicated {@link module:engine/controller/editingcontroller~EditingController#reconvertMarker} method.
 	 *
 	 * The `options.usingOperation` parameter lets you change if the marker should be managed by operations or not. See
 	 * {@link module:engine/model/markercollection~Marker marker class description} to learn about the difference between
@@ -1037,7 +1015,7 @@ export default class Writer {
 
 		if ( !currentMarker ) {
 			/**
-			 * Marker with provided name does not exists.
+			 * Marker with provided name does not exist and will not be updated.
 			 *
 			 * @error writer-updatemarker-marker-not-exists
 			 */
@@ -1045,6 +1023,18 @@ export default class Writer {
 		}
 
 		if ( !options ) {
+			/**
+			 * The usage of `writer.updateMarker()` only to reconvert (refresh) a
+			 * {@link module:engine/model/markercollection~Marker model marker} was deprecated and may not work in the future.
+			 * Please update your code to use
+			 * {@link module:engine/controller/editingcontroller~EditingController#reconvertMarker `editor.editing.reconvertMarker()`}
+			 * instead.
+			 *
+			 * @error writer-updatemarker-reconvert-using-editingcontroller
+			 * @param {String} markerName The name of the updated marker.
+			 */
+			logWarning( 'writer-updatemarker-reconvert-using-editingcontroller', { markerName } );
+
 			this.model.markers._refresh( currentMarker );
 
 			return;

package/src/view/document.js

@@ -141,7 +141,8 @@ export default class Document {
 	 *
 	 * * adding or removing attribute from elements,
 	 * * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
-	 * * {@link module:engine/model/differ~Differ#refreshItem marking some of the model elements to be re-converted}.
+	 * * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
+	 * re-converted}.
 	 *
 	 * Try to avoid changes which touch view structure:
 	 *