@ckeditor/ckeditor5-engine 44.2.1 → 44.3.0-alpha.1

package/src/view/matcher.d.ts

@@ -6,6 +6,7 @@
  * @module engine/view/matcher
  */
 import type Element from './element.js';
+import { type Consumables } from '../conversion/viewconsumable.js';
 /**
  * View matcher class.
  * Instance of this class can be used to find {@link module:engine/view/element~Element elements} that match given pattern.
@@ -61,16 +62,25 @@ export default class Matcher {
      * 	pattern: <pattern used to match found element>,
      * 	match: {
      * 		name: true,
-     * 		attributes: [ 'title', 'href' ],
-     * 		classes: [ 'foo' ],
-     * 		styles: [ 'color', 'position' ]
+     * 		attributes: [
+     * 			[ 'title' ],
+     * 			[ 'href' ],
+     * 			[ 'class', 'foo' ],
+     * 			[ 'style', 'color' ],
+     * 			[ 'style', 'position' ]
+     * 		]
      * 	}
      * }
      * ```
      *
+     * You could use the `match` field from the above returned object as an input for the
+     * {@link module:engine/conversion/viewconsumable~ViewConsumable#test `ViewConsumable#test()`} and
+     * {@link module:engine/conversion/viewconsumable~ViewConsumable#consume `ViewConsumable#consume()`} methods.
+     *
      * @see module:engine/view/matcher~Matcher#add
      * @see module:engine/view/matcher~Matcher#matchAll
      * @param element View element to match against stored patterns.
+     * @returns The match information about found element or `null`.
      */
     match(...element: Array<Element>): MatchResult | null;
     /**
@@ -91,7 +101,22 @@ export default class Matcher {
      * @returns Element name trying to match.
      */
     getElementName(): string | 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`.
+     *
+     * @returns Returns object with match information or null if element is not matching.
+     */
+    private _isElementMatching;
 }
+/**
+ * Returns true if the given `item` matches the pattern.
+ *
+ * @internal
+ * @param pattern A pattern representing a key/value we want to match.
+ * @param item An actual item key/value (e.g. `'src'`, `'background-color'`, `'ck-widget'`) we're testing against pattern.
+ */
+export declare function isPatternMatched(pattern: true | string | RegExp, item: string): unknown;
 /**
  * An entity that is a valid pattern recognized by a matcher. `MatcherPattern` is used by {@link ~Matcher} to recognize
  * if a view element fits in a group of view elements described by the pattern.
@@ -332,7 +357,7 @@ export default class Matcher {
  * 		const size = fontSize.match( /(\d+)/px );
  *
  * 		if ( size && Number( size[ 1 ] ) > 26 ) {
- * 			return { name: true, attributes: [ 'font-size' ] };
+ * 			return { name: true, styles: [ 'font-size' ] };
  * 		}
  * 	}
  *
@@ -347,7 +372,7 @@ export type MatcherPattern = string | RegExp | MatcherFunctionPattern | MatcherO
 /**
  * A function describing `MatcherPattern`. See {@link ~MatcherPattern} for examples and other options.
  */
-export type MatcherFunctionPattern = (element: Element) => Match | null;
+export type MatcherFunctionPattern = (element: Element) => Match | Consumables | null;
 /**
  * An object describing `MatcherPattern`. See {@link ~MatcherPattern} for examples and other options.
  */
@@ -356,7 +381,6 @@ export interface MatcherObjectPattern {
      * View element name to match.
      */
     name?: string | RegExp;
-    key?: string;
     /**
      * View element's classes to match.
      */
@@ -379,17 +403,10 @@ export interface Match {
      */
     name?: boolean;
     /**
-     * Array with matched attribute names.
-     */
-    attributes?: Array<string>;
-    /**
-     * Array with matched class names.
-     */
-    classes?: Array<string>;
-    /**
-     * Array with matched style names.
+     * Array of matching tuples: attribute name, and optional token for tokenized attributes.
+     * Note that there could be multiple entries for the same attribute with different tokens (class names or style properties).
      */
-    styles?: Array<string>;
+    attributes?: Array<[string, string?]>;
 }
 /**
  * The result of {@link ~Matcher#match}.
@@ -415,6 +432,11 @@ export type PropertyPatterns<ValuePattern = string | RegExp> = true | string | R
 export type AttributePatterns = PropertyPatterns;
 export type StylePatterns = PropertyPatterns;
 export type ClassPatterns = PropertyPatterns<never>;
+export type NormalizedPropertyPattern = [
+    true | string | RegExp,
+    true | string | RegExp,
+    (true | string | RegExp)?
+];
 /**
  * The key-value matcher pattern is missing key or value. Both must be present.
  * Refer the documentation: {@link module:engine/view/matcher~MatcherPattern}.

package/src/view/matcher.js

@@ -3,6 +3,7 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 import { logWarning } from '@ckeditor/ckeditor5-utils';
+import { normalizeConsumables } from '../conversion/viewconsumable.js';
 /**
  * View matcher class.
  * Instance of this class can be used to find {@link module:engine/view/element~Element elements} that match given pattern.
@@ -68,21 +69,30 @@ export default class Matcher {
      * 	pattern: <pattern used to match found element>,
      * 	match: {
      * 		name: true,
-     * 		attributes: [ 'title', 'href' ],
-     * 		classes: [ 'foo' ],
-     * 		styles: [ 'color', 'position' ]
+     * 		attributes: [
+     * 			[ 'title' ],
+     * 			[ 'href' ],
+     * 			[ 'class', 'foo' ],
+     * 			[ 'style', 'color' ],
+     * 			[ 'style', 'position' ]
+     * 		]
      * 	}
      * }
      * ```
      *
+     * You could use the `match` field from the above returned object as an input for the
+     * {@link module:engine/conversion/viewconsumable~ViewConsumable#test `ViewConsumable#test()`} and
+     * {@link module:engine/conversion/viewconsumable~ViewConsumable#consume `ViewConsumable#consume()`} methods.
+     *
      * @see module:engine/view/matcher~Matcher#add
      * @see module:engine/view/matcher~Matcher#matchAll
      * @param element View element to match against stored patterns.
+     * @returns The match information about found element or `null`.
      */
     match(...element) {
         for (const singleElement of element) {
             for (const pattern of this._patterns) {
-                const match = isElementMatching(singleElement, pattern);
+                const match = this._isElementMatching(singleElement, pattern);
                 if (match) {
                     return {
                         element: singleElement,
@@ -108,7 +118,7 @@ export default class Matcher {
         const results = [];
         for (const singleElement of element) {
             for (const pattern of this._patterns) {
-                const match = isElementMatching(singleElement, pattern);
+                const match = this._isElementMatching(singleElement, pattern);
                 if (match) {
                     results.push({
                         element: singleElement,
@@ -134,48 +144,61 @@ export default class Matcher {
         const name = pattern.name;
         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`.
- *
- * @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') {
-        return pattern(element);
-    }
-    const match = {};
-    // Check element's name.
-    if (pattern.name) {
-        match.name = matchName(pattern.name, element.name);
-        if (!match.name) {
-            return 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`.
+     *
+     * @returns Returns object with match information or null if element is not matching.
+     */
+    _isElementMatching(element, pattern) {
+        // If pattern is provided as function - return result of that function;
+        if (typeof pattern == 'function') {
+            const match = pattern(element);
+            // In some places we use Matcher with callback pattern that returns boolean.
+            if (!match || typeof match != 'object') {
+                return match;
+            }
+            return normalizeConsumables(match);
         }
-    }
-    // Check element's attributes.
-    if (pattern.attributes) {
-        match.attributes = matchAttributes(pattern.attributes, element);
-        if (!match.attributes) {
+        const match = {};
+        // Check element's name.
+        if (pattern.name) {
+            match.name = matchName(pattern.name, element.name);
+            if (!match.name) {
+                return null;
+            }
+        }
+        const attributesMatch = [];
+        // Check element's attributes.
+        if (pattern.attributes && !matchAttributes(pattern.attributes, element, attributesMatch)) {
             return null;
         }
-    }
-    // Check element's classes.
-    if (pattern.classes) {
-        match.classes = matchClasses(pattern.classes, element);
-        if (!match.classes) {
+        // Check element's classes.
+        if (pattern.classes && !matchClasses(pattern.classes, element, attributesMatch)) {
             return null;
         }
-    }
-    // Check element's styles.
-    if (pattern.styles) {
-        match.styles = matchStyles(pattern.styles, element);
-        if (!match.styles) {
+        // Check element's styles.
+        if (pattern.styles && !matchStyles(pattern.styles, element, attributesMatch)) {
             return null;
         }
+        // Note the `attributesMatch` array is populated by the above calls.
+        if (attributesMatch.length) {
+            match.attributes = attributesMatch;
+        }
+        return match;
     }
-    return match;
+}
+/**
+ * Returns true if the given `item` matches the pattern.
+ *
+ * @internal
+ * @param pattern A pattern representing a key/value we want to match.
+ * @param item An actual item key/value (e.g. `'src'`, `'background-color'`, `'ck-widget'`) we're testing against pattern.
+ */
+export function isPatternMatched(pattern, item) {
+    return pattern === true ||
+        pattern === item ||
+        pattern instanceof RegExp && !!String(item).match(pattern);
 }
 /**
  * Checks if name can be matched by provided pattern.
@@ -190,92 +213,8 @@ 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):
- *
- * ```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);
-    const match = [];
-    normalizedPatterns.forEach(([patternKey, patternValue]) => {
-        normalizedItems.forEach(itemKey => {
-            if (isKeyMatched(patternKey, itemKey) &&
-                isValueMatched(patternValue, itemKey, valueGetter)) {
-                match.push(itemKey);
-            }
-        });
-    });
-    // 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 undefined;
-    }
-    return match;
-}
-/**
- * Bring all the possible pattern forms to an array of arrays where first item is a key and second is a value.
+ * Bring all the possible pattern forms to an array of tuples where first item is a key, second is a value,
+ * and third optional is a token value.
  *
  * Examples:
  *
@@ -340,67 +279,53 @@ function matchPatterns(patterns, keys, valueGetter) {
  *
  * @returns Returns an array of objects or null if provided patterns were not in an expected form.
  */
-function normalizePatterns(patterns) {
+function normalizePatterns(patterns, prefix) {
     if (Array.isArray(patterns)) {
         return patterns.map(pattern => {
             if (typeof pattern !== 'object' || pattern instanceof RegExp) {
-                return [pattern, true];
+                return prefix ?
+                    [prefix, pattern, true] :
+                    [pattern, true];
             }
             if (pattern.key === undefined || pattern.value === undefined) {
                 // Documented at the end of matcher.js.
                 logWarning('matcher-pattern-missing-key-or-value', pattern);
             }
-            return [pattern.key, pattern.value];
+            return prefix ?
+                [prefix, pattern.key, pattern.value] :
+                [pattern.key, pattern.value];
         });
     }
     if (typeof patterns !== 'object' || patterns instanceof RegExp) {
-        return [[patterns, true]];
+        return [
+            prefix ?
+                [prefix, patterns, true] :
+                [patterns, true]
+        ];
     }
-    // Below we do what Object.entries() does, but faster.
+    // Below we do what Object.entries() does, but faster
     const normalizedPatterns = [];
     for (const key in patterns) {
         // Replace with Object.hasOwn() when we upgrade to es2022.
         if (Object.prototype.hasOwnProperty.call(patterns, key)) {
-            normalizedPatterns.push([key, patterns[key]]);
+            normalizedPatterns.push(prefix ?
+                [prefix, key, patterns[key]] :
+                [key, patterns[key]]);
         }
     }
     return normalizedPatterns;
 }
-/**
- * @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 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;
-    }
-    const itemValue = valueGetter(itemKey);
-    // 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.
  *
  * @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.
+ * @param match An array to populate with matching tuples.
  * @returns Returns array with matched attribute names or `null` if no attributes were matched.
  */
-function matchAttributes(patterns, element) {
-    const attributeKeys = new Set(element.getAttributeKeys());
+function matchAttributes(patterns, element, match) {
+    let excludeAttributes;
     // `style` and `class` attribute keys are deprecated. Only allow them in object pattern
     // for backward compatibility.
     if (typeof patterns === 'object' && !(patterns instanceof RegExp) && !Array.isArray(patterns)) {
@@ -414,21 +339,20 @@ function matchAttributes(patterns, element) {
         }
     }
     else {
-        attributeKeys.delete('style');
-        attributeKeys.delete('class');
+        excludeAttributes = ['class', 'style'];
     }
-    return matchPatterns(patterns, attributeKeys, key => element.getAttribute(key));
+    return element._collectAttributesMatch(normalizePatterns(patterns), match, excludeAttributes);
 }
 /**
  * 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.
+ * @param match An array to populate with matching tuples.
  * @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 -- @preserve */ () => { });
+function matchClasses(patterns, element, match) {
+    return element._collectAttributesMatch(normalizePatterns(patterns, 'class'), match);
 }
 /**
  * Checks if styles of provided element can be matched against provided patterns.
@@ -436,10 +360,11 @@ function matchClasses(patterns, element) {
  * @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.
+ * @param match An array to populate with matching tuples.
  * @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));
+function matchStyles(patterns, element, match) {
+    return element._collectAttributesMatch(normalizePatterns(patterns, 'style'), match);
 }
 /**
  * The key-value matcher pattern is missing key or value. Both must be present.

package/src/view/stylesmap.d.ts

@@ -2,10 +2,12 @@
  * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
+import type { ElementAttributeValue } from './element.js';
+import { type ArrayOrItem } from '@ckeditor/ckeditor5-utils';
 /**
  * Styles map. Allows handling (adding, removing, retrieving) a set of style rules (usually, of an element).
  */
-export default class StylesMap {
+export default class StylesMap implements ElementAttributeValue {
     /**
      * Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and
      * value access model using lodash's get, set, unset, etc methods.
@@ -44,7 +46,7 @@ export default class StylesMap {
      * styles.setTo( 'border:1px solid blue;margin-top:1px;' );
      * ```
      */
-    setTo(inlineStyle: string): void;
+    setTo(inlineStyle: string): this;
     /**
      * Checks if a given style is set.
      *
@@ -181,9 +183,9 @@ export default class StylesMap {
      * styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
      * ```
      *
-     * @param name Style name.
+     * @param names Style name or an array of names.
      */
-    remove(name: string): void;
+    remove(names: ArrayOrItem<string>): void;
     /**
      * Returns a normalized style object or a single value.
      *
@@ -210,7 +212,7 @@ export default class StylesMap {
      *
      * @param name Style name.
      */
-    getNormalized(name?: string): StyleValue;
+    getNormalized(name?: string): StyleValue | undefined;
     /**
      * Returns a normalized style string. Styles are sorted by name.
      *
@@ -311,14 +313,74 @@ export default class StylesMap {
      * @param expand Expand shorthand style properties and all return equivalent style representations.
      */
     getStyleNames(expand?: boolean): Array<string>;
+    /**
+     * Alias for {@link #getStyleNames}.
+     */
+    keys(): Array<string>;
     /**
      * Removes all styles.
      */
     clear(): void;
+    /**
+     * Returns `true` if both attributes have the same styles.
+     */
+    isSimilar(other: StylesMap): boolean;
     /**
      * Returns normalized styles entries for further processing.
      */
     getStylesEntries(): Array<PropertyDescriptor>;
+    /**
+     * Clones the attribute value.
+     *
+     * @internal
+     */
+    _clone(): this;
+    /**
+     * Used by the {@link module:engine/view/matcher~Matcher Matcher} to collect matching styles.
+     *
+     * @internal
+     * @param tokenPattern The matched style name pattern.
+     * @param valuePattern The matched style value pattern.
+     * @returns An array of matching tokens (style names).
+     */
+    _getTokensMatch(tokenPattern: true | string | RegExp, valuePattern: true | string | RegExp): Array<string> | undefined;
+    /**
+     * Returns a list of consumables for the attribute. This includes related styles.
+     *
+     * Could be filtered by the given style name.
+     *
+     * @internal
+     */
+    _getConsumables(name?: string): Array<string>;
+    /**
+     * Used by {@link module:engine/view/element~Element#_canMergeAttributesFrom} to verify if the given attribute can be merged without
+     * conflicts into the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     *
+     * @internal
+     */
+    _canMergeFrom(other: StylesMap): boolean;
+    /**
+     * Used by {@link module:engine/view/element~Element#_mergeAttributesFrom} to merge a given attribute into the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     *
+     * @internal
+     */
+    _mergeFrom(other: StylesMap): void;
+    /**
+     * Used by {@link module:engine/view/element~Element#_canSubtractAttributesOf} to verify if the given attribute can be fully
+     * subtracted from the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to unwrap the AttributeElement.
+     *
+     * @internal
+     */
+    _isMatching(other: StylesMap): boolean;
     /**
      * Removes empty objects upon removing an entry from internal object.
      */
@@ -377,7 +439,7 @@ export declare class StylesProcessor {
      * @param name Name of style property.
      * @param styles Object holding normalized styles.
      */
-    getNormalized(name: string | undefined, styles: Styles): StyleValue;
+    getNormalized(name: string | undefined, styles: Styles): StyleValue | undefined;
     /**
      * Returns a reduced form of style property form normalized object.
      *