@ckeditor/ckeditor5-engine 29.0.0 → 31.0.0

package/src/view/matcher.js

@@ -235,7 +235,7 @@ function isElementMatching( element, pattern ) {
 function matchName( pattern, name ) {
 	// If pattern is provided as RegExp - test against this regexp.
 	if ( pattern instanceof RegExp ) {
-		return pattern.test( name );
+		return !!name.match( pattern );
 	}
 
 	return pattern === name;
@@ -288,18 +288,12 @@ function matchName( pattern, name ) {
 //			]
 //
 // @param {Object} patterns Object with information about attributes to match.
-// @param {Array} items An array of key/value pairs, e.g.:
-//
-//	[
-//		[ 'src', 'https://example.com' ],
-//		[ 'rel', 'nofollow' ]
-//	]
-//
+// @param {Iterable.<String>} keys Attribute, style or class keys.
 // @param {Function} valueGetter A function providing value for a given item key.
 // @returns {Array|null} Returns array with matched attribute names or `null` if no attributes were matched.
-function matchPatterns( patterns, items, valueGetter ) {
+function matchPatterns( patterns, keys, valueGetter ) {
 	const normalizedPatterns = normalizePatterns( patterns );
-	const normalizedItems = Array.from( items );
+	const normalizedItems = Array.from( keys );
 	const match = [];
 
 	normalizedPatterns.forEach( ( [ patternKey, patternValue ] ) => {
@@ -400,7 +394,7 @@ function normalizePatterns( patterns ) {
 function isKeyMatched( patternKey, itemKey ) {
 	return patternKey === true ||
 		patternKey === itemKey ||
-		patternKey instanceof RegExp && patternKey.test( itemKey );
+		patternKey instanceof RegExp && itemKey.match( patternKey );
 }
 
 // @param {String|RegExp} patternValue A pattern representing a value we want to match.
@@ -414,7 +408,11 @@ function isValueMatched( patternValue, itemKey, valueGetter ) {
 
 	const itemValue = valueGetter( itemKey );
 
-	return patternValue === itemValue || patternValue instanceof RegExp && patternValue.test( itemValue );
+	// For now, the reducers are not returning the full tree of properties.
+	// Casting to string preserves the old behavior until the root cause is fixed.
+	// More can be found in https://github.com/ckeditor/ckeditor5/issues/10399.
+	return patternValue === itemValue ||
+		patternValue instanceof RegExp && !!String( itemValue ).match( patternValue );
 }
 
 // Checks if attributes of provided element can be matched against provided patterns.
@@ -424,7 +422,25 @@ function isValueMatched( patternValue, itemKey, valueGetter ) {
 // @param {module:engine/view/element~Element} element Element which attributes will be tested.
 // @returns {Array|null} Returns array with matched attribute names or `null` if no attributes were matched.
 function matchAttributes( patterns, element ) {
-	return matchPatterns( patterns, element.getAttributeKeys(), key => element.getAttribute( key ) );
+	const attributeKeys = new Set( element.getAttributeKeys() );
+
+	// `style` and `class` attribute keys are deprecated. Only allow them in object pattern
+	// for backward compatibility.
+	if ( isPlainObject( patterns ) ) {
+		if ( patterns.style !== undefined ) {
+			// Documented at the end of matcher.js.
+			logWarning( 'matcher-pattern-deprecated-attributes-style-key', patterns );
+		}
+		if ( patterns.class !== undefined ) {
+			// Documented at the end of matcher.js.
+			logWarning( 'matcher-pattern-deprecated-attributes-class-key', patterns );
+		}
+	} else {
+		attributeKeys.delete( 'style' );
+		attributeKeys.delete( 'class' );
+	}
+
+	return matchPatterns( patterns, attributeKeys, key => element.getAttribute( key ) );
 }
 
 // Checks if classes of provided element can be matched against provided patterns.
@@ -698,3 +714,63 @@ function matchStyles( patterns, element ) {
  * @param {Object} pattern Pattern with missing properties.
  * @error matcher-pattern-missing-key-or-value
  */
+
+/**
+ * The key-value matcher pattern for `attributes` option is using deprecated `style` key.
+ *
+ * Use `styles` matcher pattern option instead:
+ *
+ * 		// Instead of:
+ * 		const pattern = {
+ * 			attributes: {
+ * 				key1: 'value1',
+ * 				key2: 'value2',
+ * 				style: /^border.*$/
+ * 			}
+ * 		}
+ *
+ * 		// Use:
+ * 		const pattern = {
+ * 			attributes: {
+ * 				key1: 'value1',
+ * 				key2: 'value2'
+ * 			},
+ * 			styles: /^border.*$/
+ * 		}
+ *
+ * Refer to the {@glink builds/guides/migration/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * and {@link module:engine/view/matcher~MatcherPattern} documentation.
+ *
+ * @param {Object} pattern Pattern with missing properties.
+ * @error matcher-pattern-deprecated-attributes-style-key
+ */
+
+/**
+ * The key-value matcher pattern for `attributes` option is using deprecated `class` key.
+ *
+ * Use `classes` matcher pattern option instead:
+ *
+ * 		// Instead of:
+ * 		const pattern = {
+ * 			attributes: {
+ * 				key1: 'value1',
+ * 				key2: 'value2',
+ * 				class: 'foobar'
+ * 			}
+ * 		}
+ *
+ * 		// Use:
+ * 		const pattern = {
+ * 			attributes: {
+ * 				key1: 'value1',
+ * 				key2: 'value2'
+ * 			},
+ * 			classes: 'foobar'
+ * 		}
+ *
+ * Refer to the {@glink builds/guides/migration/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * and the {@link module:engine/view/matcher~MatcherPattern} documentation.
+ *
+ * @param {Object} pattern Pattern with missing properties.
+ * @error matcher-pattern-deprecated-attributes-class-key
+ */

package/src/view/observer/selectionobserver.js

@@ -20,6 +20,8 @@ import { debounce } from 'lodash-es';
  * {@link module:engine/view/document~Document#event:selectionChange} event only if a selection change was the only change in the document
  * and the DOM selection is different then the view selection.
  *
+ * This observer also manages the {@link module:engine/view/document~Document#isSelecting} property of the view document.
+ *
  * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
  *
  * @see module:engine/view/observer/mutationobserver~MutationObserver
@@ -78,8 +80,26 @@ export default class SelectionObserver extends Observer {
 		 */
 		this._fireSelectionChangeDoneDebounced = debounce( data => this.document.fire( 'selectionChangeDone', data ), 200 );
 
+		/**
+		 * When called, starts clearing the {@link #_loopbackCounter} counter in intervals of time. When the number of selection
+		 * changes exceeds a certain limit within the interval of time, the observer will not fire `selectionChange` but warn about
+		 * possible infinite selection loop.
+		 *
+		 * @private
+		 * @member {Number} #_clearInfiniteLoopInterval
+		 */
 		this._clearInfiniteLoopInterval = setInterval( () => this._clearInfiniteLoop(), 1000 );
 
+		/**
+		 * Unlocks the `isSelecting` state of the view document in case the selection observer did not record this fact
+		 * correctly (for whatever the reason). It is a safeguard (paranoid check) that returns document to the normal state
+		 * after a certain period of time (debounced, postponed by each selectionchange event).
+		 *
+		 * @private
+		 * @method #_documentIsSelectingInactivityTimeoutDebounced
+		 */
+		this._documentIsSelectingInactivityTimeoutDebounced = debounce( () => ( this.document.isSelecting = false ), 5000 );
+
 		/**
 		 * Private property to check if the code does not enter infinite loop.
 		 *
@@ -95,13 +115,39 @@ export default class SelectionObserver extends Observer {
 	observe( domElement ) {
 		const domDocument = domElement.ownerDocument;
 
-		// Add listener once per each document.
+		const startDocumentIsSelecting = () => {
+			this.document.isSelecting = true;
+
+			// Let's activate the safety timeout each time the document enters the "is selecting" state.
+			this._documentIsSelectingInactivityTimeoutDebounced();
+		};
+
+		const endDocumentIsSelecting = () => {
+			this.document.isSelecting = false;
+
+			// The safety timeout can be canceled when the document leaves the "is selecting" state.
+			this._documentIsSelectingInactivityTimeoutDebounced.cancel();
+		};
+
+		// The document has the "is selecting" state while the user keeps making (extending) the selection
+		// (e.g. by holding the mouse button and moving the cursor). The state resets when they either released
+		// the mouse button or interrupted the process by pressing or releasing any key.
+		this.listenTo( domElement, 'selectstart', startDocumentIsSelecting, { priority: 'highest' } );
+		this.listenTo( domElement, 'keydown', endDocumentIsSelecting, { priority: 'highest' } );
+		this.listenTo( domElement, 'keyup', endDocumentIsSelecting, { priority: 'highest' } );
+
+		// Add document-wide listeners only once. This method could be called for multiple editing roots.
 		if ( this._documents.has( domDocument ) ) {
 			return;
 		}
 
+		this.listenTo( domDocument, 'mouseup', endDocumentIsSelecting, { priority: 'highest' } );
 		this.listenTo( domDocument, 'selectionchange', ( evt, domEvent ) => {
 			this._handleSelectionChange( domEvent, domDocument );
+
+			// Defer the safety timeout when the selection changes (e.g. the user keeps extending the selection
+			// using their mouse).
+			this._documentIsSelectingInactivityTimeoutDebounced();
 		} );
 
 		this._documents.add( domDocument );
@@ -115,6 +161,7 @@ export default class SelectionObserver extends Observer {
 
 		clearInterval( this._clearInfiniteLoopInterval );
 		this._fireSelectionChangeDoneDebounced.cancel();
+		this._documentIsSelectingInactivityTimeoutDebounced.cancel();
 	}
 
 	/**

package/src/view/rawelement.js

@@ -131,12 +131,13 @@ export default class RawElement extends Element {
 	 *
 	 *		const myRawElement = downcastWriter.createRawElement( 'div' );
 	 *
-	 *		myRawElement.render = function( domElement ) {
-	 *			domElement.innerHTML = '<b>This is the raw content of myRawElement.</b>';
+	 *		myRawElement.render = function( domElement, domConverter ) {
+	 *			domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
 	 *		};
 	 *
 	 * @method #render
 	 * @param {HTMLElement} domElement The native DOM element representing the raw view element.
+	 * @param {module:engine/view/domconverter~DomConverter} domConverter Instance of the DomConverter used to optimize the output.
 	 */
 }
 

package/src/view/renderer.js

@@ -24,6 +24,8 @@ import isNode from '@ckeditor/ckeditor5-utils/src/dom/isnode';
 import fastDiff from '@ckeditor/ckeditor5-utils/src/fastdiff';
 import env from '@ckeditor/ckeditor5-utils/src/env';
 
+import '../../theme/renderer.css';
+
 /**
  * Renderer is responsible for updating the DOM structure and the DOM selection based on
  * the {@link module:engine/view/renderer~Renderer#markToSync information about updated view nodes}.
@@ -98,8 +100,34 @@ export default class Renderer {
 		 * this is set to `false`.
 		 *
 		 * @member {Boolean}
+		 * @observable
+		 */
+		this.set( 'isFocused', false );
+
+		/**
+		 * Indicates whether the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
+		 * When they stop selecting, the property goes back to `false`.
+		 *
+		 * Note: In some browsers, the renderer will stop rendering the selection and inline fillers while the user is making
+		 * a selection to avoid glitches in DOM selection
+		 * (https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723).
+		 *
+		 * @member {Boolean}
+		 * @observable
 		 */
-		this.isFocused = false;
+		this.set( 'isSelecting', false );
+
+		// Rendering the selection and inline filler manipulation should be postponed in (non-Android) Blink until the user finishes
+		// creating the selection in DOM to avoid accidental selection collapsing
+		// (https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723).
+		// When the user stops, selecting, all pending changes should be rendered ASAP, though.
+		if ( env.isBlink && !env.isAndroid ) {
+			this.on( 'change:isSelecting', () => {
+				if ( !this.isSelecting ) {
+					this.render();
+				}
+			} );
+		}
 
 		/**
 		 * The text node in which the inline filler was rendered.
@@ -170,29 +198,41 @@ export default class Renderer {
 	 */
 	render() {
 		let inlineFillerPosition;
+		const isInlineFillerRenderingPossible = env.isBlink && !env.isAndroid ? !this.isSelecting : true;
 
 		// Refresh mappings.
 		for ( const element of this.markedChildren ) {
 			this._updateChildrenMappings( element );
 		}
 
-		// There was inline filler rendered in the DOM but it's not
-		// at the selection position any more, so we can remove it
-		// (cause even if it's needed, it must be placed in another location).
-		if ( this._inlineFiller && !this._isSelectionInInlineFiller() ) {
-			this._removeInlineFiller();
-		}
+		// Don't manipulate inline fillers while the selection is being made in (non-Android) Blink to prevent accidental
+		// DOM selection collapsing
+		// (https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723).
+		if ( isInlineFillerRenderingPossible ) {
+			// There was inline filler rendered in the DOM but it's not
+			// at the selection position any more, so we can remove it
+			// (cause even if it's needed, it must be placed in another location).
+			if ( this._inlineFiller && !this._isSelectionInInlineFiller() ) {
+				this._removeInlineFiller();
+			}
 
-		// If we've got the filler, let's try to guess its position in the view.
-		if ( this._inlineFiller ) {
-			inlineFillerPosition = this._getInlineFillerPosition();
-		}
-		// Otherwise, if it's needed, create it at the selection position.
-		else if ( this._needsInlineFillerAtSelection() ) {
-			inlineFillerPosition = this.selection.getFirstPosition();
+			// If we've got the filler, let's try to guess its position in the view.
+			if ( this._inlineFiller ) {
+				inlineFillerPosition = this._getInlineFillerPosition();
+			}
+			// Otherwise, if it's needed, create it at the selection position.
+			else if ( this._needsInlineFillerAtSelection() ) {
+				inlineFillerPosition = this.selection.getFirstPosition();
 
-			// Do not use `markToSync` so it will be added even if the parent is already added.
-			this.markedChildren.add( inlineFillerPosition.parent );
+				// Do not use `markToSync` so it will be added even if the parent is already added.
+				this.markedChildren.add( inlineFillerPosition.parent );
+			}
+		}
+		// Paranoid check: we make sure the inline filler has any parent so it can be mapped to view position
+		// by DomConverter.
+		else if ( this._inlineFiller && this._inlineFiller.parentNode ) {
+			// While the user is making selection, preserve the inline filler at its original position.
+			inlineFillerPosition = this.domConverter.domPositionToView( this._inlineFiller );
 		}
 
 		for ( const element of this.markedAttributes ) {
@@ -209,26 +249,30 @@ export default class Renderer {
 			}
 		}
 
-		// Check whether the inline filler is required and where it really is in the DOM.
-		// At this point in most cases it will be in the DOM, but there are exceptions.
-		// For example, if the inline filler was deep in the created DOM structure, it will not be created.
-		// Similarly, if it was removed at the beginning of this function and then neither text nor children were updated,
-		// it will not be present.
-		// Fix those and similar scenarios.
-		if ( inlineFillerPosition ) {
-			const fillerDomPosition = this.domConverter.viewPositionToDom( inlineFillerPosition );
-			const domDocument = fillerDomPosition.parent.ownerDocument;
-
-			if ( !startsWithFiller( fillerDomPosition.parent ) ) {
-				// Filler has not been created at filler position. Create it now.
-				this._inlineFiller = addInlineFiller( domDocument, fillerDomPosition.parent, fillerDomPosition.offset );
+		// * Check whether the inline filler is required and where it really is in the DOM.
+		//   At this point in most cases it will be in the DOM, but there are exceptions.
+		//   For example, if the inline filler was deep in the created DOM structure, it will not be created.
+		//   Similarly, if it was removed at the beginning of this function and then neither text nor children were updated,
+		//   it will not be present. Fix those and similar scenarios.
+		// * Don't manipulate inline fillers while the selection is being made in (non-Android) Blink to prevent accidental
+		//   DOM selection collapsing
+		//   (https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723).
+		if ( isInlineFillerRenderingPossible ) {
+			if ( inlineFillerPosition ) {
+				const fillerDomPosition = this.domConverter.viewPositionToDom( inlineFillerPosition );
+				const domDocument = fillerDomPosition.parent.ownerDocument;
+
+				if ( !startsWithFiller( fillerDomPosition.parent ) ) {
+					// Filler has not been created at filler position. Create it now.
+					this._inlineFiller = addInlineFiller( domDocument, fillerDomPosition.parent, fillerDomPosition.offset );
+				} else {
+					// Filler has been found, save it.
+					this._inlineFiller = fillerDomPosition.parent;
+				}
 			} else {
-				// Filler has been found, save it.
-				this._inlineFiller = fillerDomPosition.parent;
+				// There is no filler needed.
+				this._inlineFiller = null;
 			}
-		} else {
-			// There is no filler needed.
-			this._inlineFiller = null;
 		}
 
 		// First focus the new editing host, then update the selection.
@@ -261,8 +305,8 @@ export default class Renderer {
 
 		// Removing nodes from the DOM as we iterate can cause `actualDomChildren`
 		// (which is a live-updating `NodeList`) to get out of sync with the
-		// indices that we compute as we iterate over `actions`, producing
-		// incorrect element mappings.
+		// indices that we compute as we iterate over `actions`.
+		// This would produce incorrect element mappings.
 		//
 		// Converting live list to an array to make the list static.
 		const actualDomChildren = Array.from(
@@ -401,7 +445,7 @@ export default class Renderer {
 		}
 
 		if ( isInlineFiller( domFillerNode ) ) {
-			domFillerNode.parentNode.removeChild( domFillerNode );
+			domFillerNode.remove();
 		} else {
 			domFillerNode.data = domFillerNode.data.substr( INLINE_FILLER_LENGTH );
 		}
@@ -511,11 +555,23 @@ export default class Renderer {
 
 		// Add or overwrite attributes.
 		for ( const key of viewAttrKeys ) {
-			domElement.setAttribute( key, viewElement.getAttribute( key ) );
+			const value = viewElement.getAttribute( key );
+
+			if ( !this.domConverter.shouldRenderAttribute( key, value ) ) {
+				domElement.removeAttribute( key );
+			} else {
+				domElement.setAttribute( key, value );
+			}
 		}
 
 		// Remove from DOM attributes which do not exists in the view.
 		for ( const key of domAttrKeys ) {
+			// Do not remove attributes on `script` elements with special data attributes `data-ck-hidden`.
+			if ( viewElement.name === 'script' && key === 'data-ck-hidden' ) {
+				continue;
+			}
+
+			// All other attributes not present in the DOM should be removed.
 			if ( !viewElement.hasAttribute( key ) ) {
 				domElement.removeAttribute( key );
 			}
@@ -543,7 +599,7 @@ export default class Renderer {
 		const inlineFillerPosition = options.inlineFillerPosition;
 		const actualDomChildren = this.domConverter.mapViewToDom( viewElement ).childNodes;
 		const expectedDomChildren = Array.from(
-			this.domConverter.viewChildrenToDom( viewElement, domElement.ownerDocument, { bind: true, inlineFillerPosition } )
+			this.domConverter.viewChildrenToDom( viewElement, domElement.ownerDocument, { bind: true } )
 		);
 
 		// Inline filler element has to be created as it is present in the DOM, but not in the view. It is required
@@ -684,6 +740,14 @@ export default class Renderer {
 	 * @private
 	 */
 	_updateSelection() {
+		// Block updating DOM selection in (non-Android) Blink while the user is selecting to prevent accidental selection collapsing.
+		// Note: Structural changes in DOM must trigger selection rendering, though. Nodes the selection was anchored
+		// to may disappear in DOM which would break the selection (e.g. in real-time collaboration scenarios).
+		// https://github.com/ckeditor/ckeditor5/issues/10562, https://github.com/ckeditor/ckeditor5/issues/10723
+		if ( env.isBlink && !env.isAndroid && this.isSelecting && !this.markedChildren.size ) {
+			return;
+		}
+
 		// If there is no selection - remove DOM and fake selections.
 		if ( this.selection.rangeCount === 0 ) {
 			this._removeDomSelection();

package/src/view/styles/border.js

@@ -239,26 +239,26 @@ function normalizeBorderShorthand( string ) {
 //
 // It tries to produce the most optimal output for the specified styles.
 //
-// For border style:
+// For a border style:
 //
 //      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
 //
-// It will produce: `border-style: solid` output.
-// For border style and color:
+// It will produce: `border-style: solid`.
+// For a border style and color:
 //
 //      color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
 //      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
 //
-// It will produce: `border-color: #ff0; border-style: solid`
+// It will produce: `border-color: #ff0; border-style: solid`.
 // If all border parameters are specified:
 //
 //      color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
 //      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
 //      width: {top: "2px", bottom: "2px", right: "2px", left: "2px"}
 //
-// It will combine everything into the single property: `border: 2px solid #ff0`.
+// It will combine everything into a single property: `border: 2px solid #ff0`.
 //
-// Definitions are merged only if all border selectors have the same values.
+// The definitions are merged only if all border selectors have the same values.
 //
 // @returns {Function}
 function getBorderReducer() {
@@ -295,7 +295,7 @@ function getBorderReducer() {
 			return reducedStyleTypes;
 		}, [] );
 
-		// The reduced properties (by type) and all the rest that could not be reduced.
+		// The reduced properties (by type) and all that remains that could not be reduced.
 		return [
 			...reducedStyleTypes,
 			...reduceBorderPosition( topStyles, 'top' ),
@@ -318,10 +318,10 @@ function getBorderPositionReducer( which ) {
 	return value => reduceBorderPosition( value, which );
 }
 
-// Returns an array with reduced border styles depending on specified values.
+// Returns an array with reduced border styles depending on the specified values.
 //
-// If all (width, style, color) border properties are specified, the returned selector will be
-// merged into the group: `border-*: [width] [style] [color]`.
+// If all border properties (width, style, color) are specified, the returned selector will be
+// merged into a group: `border-*: [width] [style] [color]`.
 //
 // Otherwise, the specific definitions will be returned: `border-(width|style|color)-*: [value]`.
 //

package/src/view/styles/utils.js

@@ -36,6 +36,11 @@ const COLOR_NAMES = new Set( [
 	'papayawhip', 'peachpuff', 'peru', 'pink', 'plum', 'powderblue', 'rosybrown', 'royalblue', 'saddlebrown', 'salmon',
 	'sandybrown', 'seagreen', 'seashell', 'sienna', 'skyblue', 'slateblue', 'slategray', 'slategrey', 'snow',
 	'springgreen', 'steelblue', 'tan', 'thistle', 'tomato', 'turquoise', 'violet', 'wheat', 'whitesmoke', 'yellowgreen',
+	// CSS Color Module Level 3 (System Colors)
+	'activeborder', 'activecaption', 'appworkspace', 'background', 'buttonface', 'buttonhighlight', 'buttonshadow',
+	'buttontext', 'captiontext', 'graytext', 'highlight', 'highlighttext', 'inactiveborder', 'inactivecaption',
+	'inactivecaptiontext', 'infobackground', 'infotext', 'menu', 'menutext', 'scrollbar', 'threeddarkshadow',
+	'threedface', 'threedhighlight', 'threedlightshadow', 'threedshadow', 'window', 'windowframe', 'windowtext',
 	// CSS Color Module Level 4
 	'rebeccapurple',
 	// Keywords

package/src/view/uielement.js

@@ -126,9 +126,10 @@ export default class UIElement extends Element {
 	 * Do not use inheritance to create custom rendering method, replace `render()` method instead:
 	 *
 	 *		const myUIElement = downcastWriter.createUIElement( 'span' );
-	 *		myUIElement.render = function( domDocument ) {
+	 *		myUIElement.render = function( domDocument, domConverter ) {
 	 *			const domElement = this.toDomElement( domDocument );
-	 *			domElement.innerHTML = '<b>this is ui element</b>';
+	 *
+	 *			domConverter.setContentOf( domElement, '<b>this is ui element</b>' );
 	 *
 	 *			return domElement;
 	 *		};
@@ -138,9 +139,11 @@ export default class UIElement extends Element {
 	 * after rendering your UI element.
 	 *
 	 * @param {Document} domDocument
+	 * @param {module:engine/view/domconverter~DomConverter} domConverter Instance of the DomConverter used to optimize the output.
 	 * @returns {HTMLElement}
 	 */
 	render( domDocument ) {
+		// Provide basic, default output.
 		return this.toDomElement( domDocument );
 	}
 

package/src/view/view.js

@@ -116,7 +116,7 @@ export default class View {
 		 * @type {module:engine/view/renderer~Renderer}
 		 */
 		this._renderer = new Renderer( this.domConverter, this.document.selection );
-		this._renderer.bind( 'isFocused' ).to( this.document );
+		this._renderer.bind( 'isFocused', 'isSelecting' ).to( this.document );
 
 		/**
 		 * A DOM root attributes cache. It saves the initial values of DOM root attributes before the DOM element

package/theme/renderer.css

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* Elements marked by the Renderer as hidden should be invisible in the editor. */
+.ck.ck-editor__editable span[data-ck-hidden] {
+	display: none;
+}