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

package/src/view/matcher.js

@@ -12,53 +12,41 @@ export default class Matcher {
     /**
      * Creates new instance of Matcher.
      *
-     * @param {String|RegExp|Object|Function} [pattern] Match patterns. See {@link module:engine/view/matcher~Matcher#add add method} for
-     * more information.
+     * @param pattern Match patterns. See {@link module:engine/view/matcher~Matcher#add add method} for more information.
      */
     constructor(...pattern) {
-        /**
-         * @private
-         * @type {Array<Object|Function>}
-         */
         this._patterns = [];
         this.add(...pattern);
     }
     /**
      * Adds pattern or patterns to matcher instance.
      *
-     *		// String.
-     *		matcher.add( 'div' );
+     * ```ts
+     * // String.
+     * matcher.add( 'div' );
      *
-     *		// Regular expression.
-     *		matcher.add( /^\w/ );
+     * // Regular expression.
+     * matcher.add( /^\w/ );
      *
-     *		// Single class.
-     *		matcher.add( {
-     *			classes: 'foobar'
-     *		} );
+     * // Single class.
+     * matcher.add( {
+     * 	classes: 'foobar'
+     * } );
+     * ```
      *
      * See {@link module:engine/view/matcher~MatcherPattern} for more examples.
      *
      * Multiple patterns can be added in one call:
      *
-     * 		matcher.add( 'div', { classes: 'foobar' } );
+     * ```ts
+     * matcher.add( 'div', { classes: 'foobar' } );
+     * ```
      *
-     * @param {Object|String|RegExp|Function} pattern Object describing pattern details. If string or regular expression
+     * @param pattern Object describing pattern details. If string or regular expression
      * is provided it will be used to match element's name. Pattern can be also provided in a form
      * of a function - then this function will be called with each {@link module:engine/view/element~Element element} as a parameter.
      * Function's return value will be stored under `match` key of the object returned from
      * {@link module:engine/view/matcher~Matcher#match match} or {@link module:engine/view/matcher~Matcher#matchAll matchAll} methods.
-     * @param {String|RegExp} [pattern.name] Name or regular expression to match element's name.
-     * @param {Object} [pattern.attributes] Object with key-value pairs representing attributes to match. Each object key
-     * represents attribute name. Value under that key can be either:
-     * * `true` - then attribute is just required (can be empty),
-     * * a string - then attribute has to be equal, or
-     * * a regular expression - then attribute has to match the expression.
-     * @param {String|RegExp|Array} [pattern.classes] Class name or array of class names to match. Each name can be
-     * provided in a form of string or regular expression.
-     * @param {Object} [pattern.styles] Object with key-value pairs representing styles to match. Each object key
-     * represents style name. Value under that key can be either a string or a regular expression and it will be used
-     * to match style value.
      */
     add(...pattern) {
         for (let item of pattern) {
@@ -75,28 +63,22 @@ export default class Matcher {
      *
      * Example of returned object:
      *
-     *		{
-     *			element: <instance of found element>,
-     *			pattern: <pattern used to match found element>,
-     *			match: {
-     *				name: true,
-     *				attributes: [ 'title', 'href' ],
-     *				classes: [ 'foo' ],
-     *				styles: [ 'color', 'position' ]
-     *			}
-     *		}
+     * ```ts
+     * {
+     * 	element: <instance of found element>,
+     * 	pattern: <pattern used to match found element>,
+     * 	match: {
+     * 		name: true,
+     * 		attributes: [ 'title', 'href' ],
+     * 		classes: [ 'foo' ],
+     * 		styles: [ 'color', 'position' ]
+     * 	}
+     * }
+     * ```
      *
      * @see module:engine/view/matcher~Matcher#add
      * @see module:engine/view/matcher~Matcher#matchAll
-     * @param {...module:engine/view/element~Element} element View element to match against stored patterns.
-     * @returns {Object|null} result
-     * @returns {module:engine/view/element~Element} result.element Matched view element.
-     * @returns {Object|String|RegExp|Function} result.pattern Pattern that was used to find matched element.
-     * @returns {Object} result.match Object representing matched element parts.
-     * @returns {Boolean} [result.match.name] True if name of the element was matched.
-     * @returns {Array} [result.match.attributes] Array with matched attribute names.
-     * @returns {Array} [result.match.classes] Array with matched class names.
-     * @returns {Array} [result.match.styles] Array with matched style names.
+     * @param element View element to match against stored patterns.
      */
     match(...element) {
         for (const singleElement of element) {
@@ -119,8 +101,8 @@ export default class Matcher {
      *
      * @see module:engine/view/matcher~Matcher#add
      * @see module:engine/view/matcher~Matcher#match
-     * @param {...module:engine/view/element~Element} element View element to match against stored patterns.
-     * @returns {Array.<Object>|null} Array with match information about found elements or `null`. For more information
+     * @param element View element to match against stored patterns.
+     * @returns Array with match information about found elements or `null`. For more information
      * see {@link module:engine/view/matcher~Matcher#match match method} description.
      */
     matchAll(...element) {
@@ -143,7 +125,7 @@ export default class Matcher {
      * Returns the name of the element to match if there is exactly one pattern added to the matcher instance
      * and it matches element name defined by `string` (not `RegExp`). Otherwise, returns `null`.
      *
-     * @returns {String|null} Element name trying to match.
+     * @returns Element name trying to match.
      */
     getElementName() {
         if (this._patterns.length !== 1) {
@@ -154,12 +136,12 @@ export default class Matcher {
         return (typeof pattern != 'function' && name && !(name instanceof RegExp)) ? name : null;
     }
 }
-// Returns match information if {@link module:engine/view/element~Element element} is matching provided pattern.
-// If element cannot be matched to provided pattern - returns `null`.
-//
-// @param {module:engine/view/element~Element} element
-// @param {Object|String|RegExp|Function} pattern
-// @returns {Object|null} Returns object with match information or null if element is not matching.
+/**
+ * Returns match information if {@link module:engine/view/element~Element element} is matching provided pattern.
+ * If element cannot be matched to provided pattern - returns `null`.
+ *
+ * @returns Returns object with match information or null if element is not matching.
+ */
 function isElementMatching(element, pattern) {
     // If pattern is provided as function - return result of that function;
     if (typeof pattern == 'function') {
@@ -196,11 +178,11 @@ function isElementMatching(element, pattern) {
     }
     return match;
 }
-// Checks if name can be matched by provided pattern.
-//
-// @param {String|RegExp} pattern
-// @param {String} name
-// @returns {Boolean} Returns `true` if name can be matched, `false` otherwise.
+/**
+ * Checks if name can be matched by provided pattern.
+ *
+ * @returns Returns `true` if name can be matched, `false` otherwise.
+ */
 function matchName(pattern, name) {
     // If pattern is provided as RegExp - test against this regexp.
     if (pattern instanceof RegExp) {
@@ -208,56 +190,72 @@ function matchName(pattern, name) {
     }
     return pattern === name;
 }
-// Checks if an array of key/value pairs can be matched against provided patterns.
-//
-// 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.
+/**
+ * Checks if an array of key/value pairs can be matched against provided patterns.
+ *
+ * Patterns can be provided in a following ways:
+ * - a boolean value matches any attribute with any value (or no value):
+ *
+ * ```ts
+ * pattern: true
+ * ```
+ *
+ * - a RegExp expression or object matches any attribute name:
+ *
+ * ```ts
+ * 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:
+ *
+ * ```ts
+ * pattern: {
+ * 	required: true
+ * }
+ * ```
+ *
+ * 	- a string that is equal to attribute value:
+ *
+ * ```ts
+ * pattern: {
+ * 	rel: 'nofollow'
+ * }
+ * ```
+ *
+ * 	- a regular expression that matches attribute value,
+ *
+ * ```ts
+ * pattern: {
+ * 	src: /^https/
+ * }
+ * ```
+ *
+ * - an array with items, where the item is:
+ * 	- a string that is equal to attribute value:
+ *
+ * ```ts
+ * 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:
+ *
+ * ```ts
+ * pattern: [
+ * 	{ key: /^data-property-/, value: true },
+ * 	// or:
+ * 	{ key: /^data-property-/, value: 'foobar' },
+ * 	// or:
+ * 	{ key: /^data-property-/, value: /^foo/ }
+ * ]
+ * ```
+ *
+ * @param patterns Object with information about attributes to match.
+ * @param keys Attribute, style or class keys.
+ * @param valueGetter A function providing value for a given item key.
+ * @returns Returns array with matched attribute names or `null` if no attributes were matched.
+ */
 function matchPatterns(patterns, keys, valueGetter) {
     const normalizedPatterns = normalizePatterns(patterns);
     const normalizedItems = Array.from(keys);
@@ -277,53 +275,72 @@ function matchPatterns(patterns, keys, valueGetter) {
     }
     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.
+/**
+ * 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:
+ *
+ * ```ts
+ * true
+ * ```
+ *
+ * to
+ *
+ * ```ts
+ * [ [ true, true ] ]
+ * ```
+ *
+ * Textual pattern value:
+ *
+ * ```ts
+ * 'attribute-name-or-class-or-style'
+ * ```
+ *
+ * to
+ *
+ * ```ts
+ * [ [ 'attribute-name-or-class-or-style', true ] ]
+ * ```
+ *
+ * Regular expression:
+ *
+ * ```ts
+ * /^data-.*$/
+ * ```
+ *
+ * to
+ *
+ * ```ts
+ * [ [ /^data-.*$/, true ] ]
+ * ```
+ *
+ * Objects (plain or with `key` and `value` specified explicitly):
+ *
+ * ```ts
+ * {
+ * 	src: /^https:.*$/
+ * }
+ * ```
+ *
+ * or
+ *
+ * ```ts
+ * [ {
+ * 	key: 'src',
+ * 	value: /^https:.*$/
+ * } ]
+ * ```
+ *
+ * to:
+ *
+ * ```ts
+ * [ [ 'src', /^https:.*$/ ] ]
+ * ```
+ *
+ * @returns 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) => {
@@ -344,18 +361,20 @@ function normalizePatterns(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}
+/**
+ * @param patternKey A pattern representing a key we want to match.
+ * @param itemKey An actual item key (e.g. `'src'`, `'background-color'`, `'ck-widget'`) we're testing against pattern.
+ */
 function isKeyMatched(patternKey, itemKey) {
     return patternKey === true ||
         patternKey === itemKey ||
         patternKey instanceof RegExp && itemKey.match(patternKey);
 }
-// @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}
+/**
+ * @param patternValue A pattern representing a value we want to match.
+ * @param itemKey An item key, e.g. `background`, `href`, 'rel', etc.
+ * @param valueGetter A function used to provide a value for a given `itemKey`.
+ */
 function isValueMatched(patternValue, itemKey, valueGetter) {
     if (patternValue === true) {
         return true;
@@ -367,12 +386,14 @@ function isValueMatched(patternValue, itemKey, valueGetter) {
     return patternValue === itemValue ||
         patternValue instanceof RegExp && !!String(itemValue).match(patternValue);
 }
-// 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.
+/**
+ * Checks if attributes of provided element can be matched against provided patterns.
+ *
+ * @param 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  element Element which attributes will be tested.
+ * @returns 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
@@ -393,21 +414,25 @@ function matchAttributes(patterns, element) {
     }
     return matchPatterns(patterns, attributeKeys, key => element.getAttribute(key));
 }
-// Checks if classes of provided element can be matched against provided patterns.
-//
-// @param {Array.<String|RegExp>} patterns Array of strings or regular expressions to match against element's classes.
-// @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.
+/**
+ * Checks if classes of provided element can be matched against provided patterns.
+ *
+ * @param patterns Array of strings or regular expressions to match against element's classes.
+ * @param element Element which classes will be tested.
+ * @returns Returns array with matched class names or `null` if no classes were matched.
+ */
 function matchClasses(patterns, element) {
     // We don't need `getter` here because patterns for classes are always normalized to `[ className, true ]`.
     return matchPatterns(patterns, element.getClassNames(), /* istanbul ignore next */ () => { });
 }
-// Checks if styles of provided element can be matched against provided patterns.
-//
-// @param {Object} patterns Object with information about styles to match. Each key of the object will be
-// used as style name. Value of each key can be a string or regular expression to match against style value.
-// @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.
+/**
+ * Checks if styles of provided element can be matched against provided patterns.
+ *
+ * @param patterns Object with information about styles to match. Each key of the object will be
+ * used as style name. Value of each key can be a string or regular expression to match against style value.
+ * @param element Element which styles will be tested.
+ * @returns Returns array with matched style names or `null` if no styles were matched.
+ */
 function matchStyles(patterns, element) {
     return matchPatterns(patterns, element.getStyleNames(true), key => element.getStyle(key));
 }
@@ -415,7 +440,7 @@ function matchStyles(patterns, element) {
  * 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.
+ * @param pattern Pattern with missing properties.
  * @error matcher-pattern-missing-key-or-value
  */
 /**
@@ -423,28 +448,30 @@ function matchStyles(patterns, element) {
  *
  * 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.*$/
- * 		}
+ * ```ts
+ * // 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 updating/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.
+ * @param pattern Pattern with missing properties.
  * @error matcher-pattern-deprecated-attributes-style-key
  */
 /**
@@ -452,27 +479,29 @@ function matchStyles(patterns, element) {
  *
  * 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'
- * 		}
+ * ```ts
+ * // 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 updating/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.
+ * @param pattern Pattern with missing properties.
  * @error matcher-pattern-deprecated-attributes-class-key
  */