@ckeditor/ckeditor5-engine 27.1.0 → 29.2.0

package/src/view/matcher.js

@@ -7,6 +7,10 @@
  * @module engine/view/matcher
  */
 
+import { isPlainObject } from 'lodash-es';
+
+import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
 /**
  * View matcher class.
  * Instance of this class can be used to find {@link module:engine/view/element~Element elements} that match given pattern.
@@ -72,11 +76,6 @@ export default class Matcher {
 				item = { name: item };
 			}
 
-			// Single class name/RegExp can be provided.
-			if ( item.classes && ( typeof item.classes == 'string' || item.classes instanceof RegExp ) ) {
-				item.classes = [ item.classes ];
-			}
-
 			this._patterns.push( item );
 		}
 	}
@@ -242,40 +241,202 @@ function matchName( pattern, name ) {
 	return pattern === name;
 }
 
-// Checks if attributes of provided element can be matched against provided patterns.
+// Checks if an array of key/value pairs can be matched against provided patterns.
 //
-// @param {Object} patterns Object with information about attributes to match. Each key of the object will be
-// used as attribute name. Value of each key can be a string or regular expression to match against attribute value.
-// @param {module:engine/view/element~Element} element Element which attributes will be tested.
+// Patterns can be provided in a following ways:
+// 	- a boolean value matches any attribute with any value (or no value):
+//
+//			pattern: true
+//
+//	- a RegExp expression or object matches any attribute name:
+//
+//			pattern: /h[1-6]/
+//
+//	- an object matches any attribute that has the same name as the object item's key, where object item's value is:
+//		- equal to `true`, which matches any attribute value:
+//
+//			pattern: {
+//				required: true
+//			}
+//
+//		- a string that is equal to attribute value:
+//
+//			pattern: {
+//				rel: 'nofollow'
+//			}
+//
+//		- a regular expression that matches attribute value,
+//
+//			pattern: {
+//				src: /https.*/
+//			}
+//
+//	- an array with items, where the item is:
+//		- a string that is equal to attribute value:
+//
+//			pattern: [ 'data-property-1', 'data-property-2' ],
+//
+//		- an object with `key` and `value` property, where `key` is a regular expression matching attribute name and
+//		  `value` is either regular expression matching attribute value or a string equal to attribute value:
+//
+//			pattern: [
+//				{ key: /data-property-.*/, value: true },
+//				// or:
+//				{ key: /data-property-.*/, value: 'foobar' },
+//				// or:
+//				{ key: /data-property-.*/, value: /foo.*/ }
+//			]
+//
+// @param {Object} patterns Object with information about attributes to match.
+// @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 matchAttributes( patterns, element ) {
+function matchPatterns( patterns, keys, valueGetter ) {
+	const normalizedPatterns = normalizePatterns( patterns );
+	const normalizedItems = Array.from( keys );
 	const match = [];
 
-	for ( const name in patterns ) {
-		const pattern = patterns[ name ];
+	normalizedPatterns.forEach( ( [ patternKey, patternValue ] ) => {
+		normalizedItems.forEach( itemKey => {
+			if (
+				isKeyMatched( patternKey, itemKey ) &&
+				isValueMatched( patternValue, itemKey, valueGetter )
+			) {
+				match.push( itemKey );
+			}
+		} );
+	} );
 
-		if ( element.hasAttribute( name ) ) {
-			const attribute = element.getAttribute( name );
+	// Return matches only if there are at least as many of them as there are patterns.
+	// The RegExp pattern can match more than one item.
+	if ( !normalizedPatterns.length || match.length < normalizedPatterns.length ) {
+		return null;
+	}
 
-			if ( pattern === true ) {
-				match.push( name );
-			} else if ( pattern instanceof RegExp ) {
-				if ( pattern.test( attribute ) ) {
-					match.push( name );
-				} else {
-					return null;
+	return match;
+}
+
+// Bring all the possible pattern forms to an array of arrays where first item is a key and second is a value.
+//
+// Examples:
+//
+// Boolean pattern value:
+//
+//		true
+//
+// to
+//
+//		[ [ true, true ] ]
+//
+// Textual pattern value:
+//
+//		'attribute-name-or-class-or-style'
+//
+// to
+//
+//		[ [ 'attribute-name-or-class-or-style', true ] ]
+//
+// Regular expression:
+//
+//		/^data-.*$/
+//
+// to
+//
+//		[ [ /^data-.*$/, true ] ]
+//
+// Objects (plain or with `key` and `value` specified explicitly):
+//
+//		{
+//			src: /^https:.*$/
+//		}
+//
+// or
+//
+//		[ {
+//			key: 'src',
+//			value: /^https:.*$/
+//		} ]
+//
+// to:
+//
+//		[ [ 'src', /^https:.*$/ ] ]
+//
+// @param {Object|Array} patterns
+// @returns {Array|null} Returns an array of objects or null if provided patterns were not in an expected form.
+function normalizePatterns( patterns ) {
+	if ( Array.isArray( patterns ) ) {
+		return patterns.map( pattern => {
+			if ( isPlainObject( pattern ) ) {
+				if ( pattern.key === undefined || pattern.value === undefined ) {
+					// Documented at the end of matcher.js.
+					logWarning( 'matcher-pattern-missing-key-or-value', pattern );
 				}
-			} else if ( attribute === pattern ) {
-				match.push( name );
-			} else {
-				return null;
+
+				return [ pattern.key, pattern.value ];
 			}
-		} else {
-			return null;
+
+			// Assume the pattern is either String or RegExp.
+			return [ pattern, true ];
+		} );
+	}
+
+	if ( isPlainObject( patterns ) ) {
+		return Object.entries( patterns );
+	}
+
+	// Other cases (true, string or regexp).
+	return [ [ patterns, true ] ];
+}
+
+// @param {String|RegExp} patternKey A pattern representing a key we want to match.
+// @param {String} itemKey An actual item key (e.g. `'src'`, `'background-color'`, `'ck-widget'`) we're testing against pattern.
+// @returns {Boolean}
+function isKeyMatched( patternKey, itemKey ) {
+	return patternKey === true ||
+		patternKey === itemKey ||
+		patternKey instanceof RegExp && patternKey.test( itemKey );
+}
+
+// @param {String|RegExp} patternValue A pattern representing a value we want to match.
+// @param {String} itemKey An item key, e.g. `background`, `href`, 'rel', etc.
+// @param {Function} valueGetter A function used to provide a value for a given `itemKey`.
+// @returns {Boolean}
+function isValueMatched( patternValue, itemKey, valueGetter ) {
+	if ( patternValue === true ) {
+		return true;
+	}
+
+	const itemValue = valueGetter( itemKey );
+
+	return patternValue === itemValue || patternValue instanceof RegExp && patternValue.test( itemValue );
+}
+
+// Checks if attributes of provided element can be matched against provided patterns.
+//
+// @param {Object} patterns Object with information about attributes to match. Each key of the object will be
+// used as attribute name. Value of each key can be a string or regular expression to match against attribute value.
+// @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 ) {
+	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 match;
+	return matchPatterns( patterns, attributeKeys, key => element.getAttribute( key ) );
 }
 
 // Checks if classes of provided element can be matched against provided patterns.
@@ -284,29 +445,8 @@ function matchAttributes( patterns, element ) {
 // @param {module:engine/view/element~Element} element Element which classes will be tested.
 // @returns {Array|null} Returns array with matched class names or `null` if no classes were matched.
 function matchClasses( patterns, element ) {
-	const match = [];
-
-	for ( const pattern of patterns ) {
-		if ( pattern instanceof RegExp ) {
-			const classes = element.getClassNames();
-
-			for ( const name of classes ) {
-				if ( pattern.test( name ) ) {
-					match.push( name );
-				}
-			}
-
-			if ( match.length === 0 ) {
-				return null;
-			}
-		} else if ( element.hasClass( pattern ) ) {
-			match.push( pattern );
-		} else {
-			return null;
-		}
-	}
-
-	return match;
+	// We don't need `getter` here because patterns for classes are always normalized to `[ className, true ]`.
+	return matchPatterns( patterns, element.getClassNames() );
 }
 
 // Checks if styles of provided element can be matched against provided patterns.
@@ -316,31 +456,7 @@ function matchClasses( patterns, element ) {
 // @param {module:engine/view/element~Element} element Element which styles will be tested.
 // @returns {Array|null} Returns array with matched style names or `null` if no styles were matched.
 function matchStyles( patterns, element ) {
-	const match = [];
-
-	for ( const name in patterns ) {
-		const pattern = patterns[ name ];
-
-		if ( element.hasStyle( name ) ) {
-			const style = element.getStyle( name );
-
-			if ( pattern instanceof RegExp ) {
-				if ( pattern.test( style ) ) {
-					match.push( name );
-				} else {
-					return null;
-				}
-			} else if ( style === pattern ) {
-				match.push( name );
-			} else {
-				return null;
-			}
-		} else {
-			return null;
-		}
-	}
-
-	return match;
+	return matchPatterns( patterns, element.getStyleNames( true ), key => element.getStyle( key ) );
 }
 
 /**
@@ -358,45 +474,187 @@ function matchStyles( patterns, element ) {
  *		const pattern = /^p/;
  *
  * If `MatcherPattern` is given as an `Object`, all the object's properties will be matched with view element properties.
+ * If the view element does not meet all of the object's pattern properties, the match will not happen.
+ * Available `Object` matching properties:
+ *
+ * Matching view element:
  *
- *		// Match view element's name.
- *		const pattern = { name: /^p/ };
+ *		// Match view element's name using String:
+ *		const pattern = { name: 'p' };
  *
- *		// Match view element which has matching attributes.
+ *		// or by providing RegExp:
+ *		const pattern = { name: /^(ul|ol)$/ };
+ *
+ *		// The name can also be skipped to match any view element with matching attributes:
  *		const pattern = {
  *			attributes: {
- *				title: 'foobar',	// Attribute title should equal 'foobar'.
- *				foo: /^\w+/,		// Attribute foo should match /^\w+/ regexp.
- *				bar: true			// Attribute bar should be set (can be empty).
+ *				'title': true
  *			}
  *		};
  *
- *		// Match view element which has given class.
+ * Matching view element attributes:
+ *
+ *		// Match view element with any attribute value.
  *		const pattern = {
- *			classes: 'foobar'
+ *			name: 'p',
+ *			attributes: true
  *		};
  *
- *		// Match view element class using regular expression.
+ *		// Match view element which has matching attributes (String).
  *		const pattern = {
- *			classes: /foo.../
+ *			name: 'figure',
+ *			attributes: 'title' // Match title attribute (can be empty).
  *		};
  *
- *		// Multiple classes to match.
+ *		// Match view element which has matching attributes (RegExp).
  *		const pattern = {
- *			classes: [ 'baz', 'bar', /foo.../ ]
+ *			name: 'figure',
+ *			attributes: /^data-.*$/ // Match attributes starting with `data-` e.g. `data-foo` with any value (can be empty).
  *		};
  *
- *		// Match view element which has given styles.
+ *		// Match view element which has matching attributes (Object).
  *		const pattern = {
- *			styles: {
- *				position: 'absolute',
- *				color: /^\w*blue$/
+ *			name: 'figure',
+ *			attributes: {
+ *				title: 'foobar',           // Match `title` attribute with 'foobar' value.
+ *				alt: true,                 // Match `alt` attribute with any value (can be empty).
+ *				'data-type': /^(jpg|png)$/ // Match `data-type` attribute with `jpg` or `png` value.
+ *			}
+ *		};
+ *
+ *		// Match view element which has matching attributes (Array).
+ *		const pattern = {
+ *			name: 'figure',
+ *			attributes: [
+ *				'title',    // Match `title` attribute (can be empty).
+ *				/^data-*$/, // Match attributes starting with `data-` e.g. `data-foo` with any value (can be empty).
+ *			]
+ *		};
+ *
+ *		// Match view element which has matching attributes (key-value pairs).
+ *		const pattern = {
+ *			name: 'input',
+ *			attributes: [
+ *				{
+ *					key: 'type',                     // Match `type` as an attribute key.
+ *					value: /^(text|number|date)$/ }, // Match `text`, `number` or `date` values.
+ *				{
+ *					key: /^data-.*$/,                // Match attributes starting with `data-` e.g. `data-foo`.
+ *					value: true                      // Match any value (can be empty).
+ *				}
+ *			]
+ *		};
+ *
+ * Matching view element styles:
+ *
+ *		// Match view element with any style.
+ *		const pattern = {
+ *			name: 'p',
+ *			styles: true
+ *		};
+ *
+ *		// Match view element which has matching styles (String).
+ *		const pattern = {
+ *			name: 'p',
+ *			styles: 'color' // Match attributes with `color` style.
+ *		};
+ *
+ *		// Match view element which has matching styles (RegExp).
+ *		const pattern = {
+ *			name: 'p',
+ *			styles: /^border.*$/ // Match view element with any border style.
+ *		};
+ *
+ *		// Match view element which has matching styles (Object).
+ *		const pattern = {
+ *			name: 'p',
+ *			attributes: {
+ *				color: /rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)/, // Match `color` in RGB format only.
+ *				'font-weight': 600,                              // Match `font-weight` only if it's `600`.
+ *				'text-decoration': true                          // Match any text decoration.
+ *			}
+ *		};
+ *
+ *		// Match view element which has matching styles (Array).
+ *		const pattern = {
+ *			name: 'p',
+ *			attributes: [
+ *				'color',      // Match `color` with any value.
+ *				/^border.*$/, // Match all border properties.
+ *			]
+ *		};
+ *
+ *		// Match view element which has matching styles (key-value pairs).
+ *		const pattern = {
+ *			name: 'p',
+ *			attributes: [
+ *				{
+ *					key: 'color',                                    // Match `color` as an property key.
+ *					value: /rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)/, // Match RGB format only.
+ *				{
+ *					key: /^border.*$/, // Match any border style.
+ *					value: true        // Match any value.
+ *				}
+ *			]
+ *		};
+ *
+ * Matching view element classes:
+ *
+ *		// Match view element with any class.
+ *		const pattern = {
+ *			name: 'p',
+ *			classes: true
+ *		};
+ *
+ *		// Match view element which has matching class (String).
+ *		const pattern = {
+ *			name: 'p',
+ *			classes: 'highlighted' // Match `highlighted` class.
+ *		};
+ *
+ *		// Match view element which has matching classes (RegExp).
+ *		const pattern = {
+ *			name: 'figure',
+ *			classes: /^image-side-(left|right)$/ // Match `image-side-left` or `image-side-right` class.
+ *		};
+ *
+ *		// Match view element which has matching classes (Object).
+ *		const pattern = {
+ *			name: 'p',
+ *			classes: {
+ *				highlighted: true, // Match `highlighted` class.
+ *				marker: true       // Match `marker` class.
  *			}
  *		};
  *
- *		// Pattern with multiple properties.
+ *		// Match view element which has matching classes (Array).
+ *		const pattern = {
+ *			name: 'figure',
+ *			classes: [
+ *				'image',                    // Match `image` class.
+ *				/^image-side-(left|right)$/ // Match `image-side-left` or `image-side-right` class.
+ *			]
+ *		};
+ *
+ *		// Match view element which has matching classes (key-value pairs).
+ *		const pattern = {
+ *			name: 'figure',
+ *			classes: [
+ *				{
+ *					key: 'image', // Match `image` class.
+ *					value: true
+ *				{
+ *					key: /^image-side-(left|right)$/, // Match `image-side-left` or `image-side-right` class.
+ *					value: true
+ *				}
+ *			]
+ *		};
+ *
+ * Pattern can combine multiple properties allowing for more complex view element matching:
+ *
  *		const pattern = {
  *			name: 'span',
+ *			attributes: [ 'title' ],
  *			styles: {
  *				'font-weight': 'bold'
  *			},
@@ -444,3 +702,71 @@ function matchStyles( patterns, element ) {
  * @property {Object} [attributes] Object with key-value pairs representing attributes to match.
  * Each object key represents attribute name. Value can be given as `String` or `RegExp`.
  */
+
+/**
+ * The key-value matcher pattern is missing key or value. Both must be present.
+ * Refer the documentation: {@link module:engine/view/matcher~MatcherPattern}.
+ *
+ * @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/focusobserver.js

@@ -37,7 +37,10 @@ export default class FocusObserver extends DomEventObserver {
 			// overwrite new DOM selection with selection from the view.
 			// See https://github.com/ckeditor/ckeditor5-engine/issues/795 for more details.
 			// Long timeout is needed to solve #676 and https://github.com/ckeditor/ckeditor5-engine/issues/1157 issues.
-			this._renderTimeoutId = setTimeout( () => view.forceRender(), 50 );
+			//
+			// Using `view.change()` instead of `view.forceRender()` to prevent double rendering
+			// in a situation where `selectionchange` already caused selection change.
+			this._renderTimeoutId = setTimeout( () => view.change( () => {} ), 50 );
 		} );
 
 		document.on( 'blur', ( evt, data ) => {
@@ -46,8 +49,9 @@ export default class FocusObserver extends DomEventObserver {
 			if ( selectedEditable === null || selectedEditable === data.target ) {
 				document.isFocused = false;
 
-				// Re-render the document to update view elements.
-				view.forceRender();
+				// Re-render the document to update view elements
+				// (changing document.isFocused already marked view as changed since last rendering).
+				view.change( () => {} );
 			}
 		} );
 

package/src/view/observer/mouseobserver.js

@@ -21,7 +21,7 @@ export default class MouseObserver extends DomEventObserver {
 	constructor( view ) {
 		super( view );
 
-		this.domEventType = [ 'mousedown', 'mouseup' ];
+		this.domEventType = [ 'mousedown', 'mouseup', 'mouseover', 'mouseout' ];
 	}
 
 	onDomEvent( domEvent ) {

package/src/view/renderer.js

@@ -259,7 +259,15 @@ export default class Renderer {
 			return;
 		}
 
-		const actualDomChildren = this.domConverter.mapViewToDom( viewElement ).childNodes;
+		// 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`.
+		// This would produce incorrect element mappings.
+		//
+		// Converting live list to an array to make the list static.
+		const actualDomChildren = Array.from(
+			this.domConverter.mapViewToDom( viewElement ).childNodes
+		);
 		const expectedDomChildren = Array.from(
 			this.domConverter.viewChildrenToDom( viewElement, domElement.ownerDocument, { withChildren: false } )
 		);

package/src/view/selection.js

@@ -134,7 +134,7 @@ export default class Selection {
 	 * Returns true if selection instance is marked as `fake`.
 	 *
 	 * @see #setTo
-	 * @returns {Boolean}
+	 * @type {Boolean}
 	 */
 	get isFake() {
 		return this._isFake;
@@ -144,7 +144,7 @@ export default class Selection {
 	 * Returns fake selection label.
 	 *
 	 * @see #setTo
-	 * @returns {String}
+	 * @type {String}
 	 */
 	get fakeSelectionLabel() {
 		return this._fakeSelectionLabel;

package/src/view/styles/background.js

@@ -41,6 +41,8 @@ export function addBackgroundRules( stylesProcessor ) {
 
 		return ret;
 	} );
+
+	stylesProcessor.setStyleRelation( 'background', [ 'background-color' ] );
 }
 
 function normalizeBackground( value ) {