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

package/src/view/stylesmap.js

@@ -6,6 +6,8 @@
  * @module engine/view/stylesmap
  */
 import { get, isObject, merge, set, unset } from 'lodash-es';
+import { toArray } from '@ckeditor/ckeditor5-utils';
+import { isPatternMatched } from './matcher.js';
 /**
  * Styles map. Allows handling (adding, removing, retrieving) a set of style rules (usually, of an element).
  */
@@ -54,6 +56,7 @@ export default class StylesMap {
         for (const [key, value] of parsedStyles) {
             this._styleProcessor.toNormalizedForm(key, value, this._styles);
         }
+        return this;
     }
     /**
      * Checks if a given style is set.
@@ -133,15 +136,17 @@ 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) {
-        this._cachedStyleNames = null;
-        this._cachedExpandedStyleNames = null;
-        const path = toPath(name);
-        unset(this._styles, path);
-        delete this._styles[name];
-        this._cleanEmptyObjectsOnPath(path);
+    remove(names) {
+        for (const name of toArray(names)) {
+            this._cachedStyleNames = null;
+            this._cachedExpandedStyleNames = null;
+            const path = toPath(name);
+            unset(this._styles, path);
+            delete this._styles[name];
+            this._cleanEmptyObjectsOnPath(path);
+        }
     }
     /**
      * Returns a normalized style object or a single value.
@@ -304,6 +309,12 @@ export default class StylesMap {
         this._cachedStyleNames = this._cachedStyleNames || this.getStylesEntries().map(([key]) => key);
         return this._cachedStyleNames;
     }
+    /**
+     * Alias for {@link #getStyleNames}.
+     */
+    keys() {
+        return this.getStyleNames();
+    }
     /**
      * Removes all styles.
      */
@@ -312,6 +323,20 @@ export default class StylesMap {
         this._cachedStyleNames = null;
         this._cachedExpandedStyleNames = null;
     }
+    /**
+     * Returns `true` if both attributes have the same styles.
+     */
+    isSimilar(other) {
+        if (this.size !== other.size) {
+            return false;
+        }
+        for (const property of this.getStyleNames()) {
+            if (!other.has(property) || other.getAsString(property) !== this.getAsString(property)) {
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * Returns normalized styles entries for further processing.
      */
@@ -323,6 +348,117 @@ export default class StylesMap {
         }
         return parsed;
     }
+    /**
+     * Clones the attribute value.
+     *
+     * @internal
+     */
+    _clone() {
+        const clone = new this.constructor(this._styleProcessor);
+        clone.set(this.getNormalized());
+        return clone;
+    }
+    /**
+     * 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, valuePattern) {
+        const match = [];
+        for (const styleName of this.getStyleNames(true)) {
+            if (isPatternMatched(tokenPattern, styleName)) {
+                if (valuePattern === true) {
+                    match.push(styleName);
+                    continue;
+                }
+                // 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.
+                const value = this.getAsString(styleName);
+                if (isPatternMatched(valuePattern, value)) {
+                    match.push(styleName);
+                }
+            }
+        }
+        return match.length ? match : undefined;
+    }
+    /**
+     * Returns a list of consumables for the attribute. This includes related styles.
+     *
+     * Could be filtered by the given style name.
+     *
+     * @internal
+     */
+    _getConsumables(name) {
+        const result = [];
+        if (name) {
+            result.push(name);
+            for (const relatedName of this._styleProcessor.getRelatedStyles(name)) {
+                result.push(relatedName);
+            }
+        }
+        else {
+            for (const name of this.getStyleNames()) {
+                for (const relatedName of this._styleProcessor.getRelatedStyles(name)) {
+                    result.push(relatedName);
+                }
+                result.push(name);
+            }
+        }
+        return result;
+    }
+    /**
+     * 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) {
+        for (const key of other.getStyleNames()) {
+            if (this.has(key) && this.getAsString(key) !== other.getAsString(key)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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) {
+        for (const prop of other.getStyleNames()) {
+            if (!this.has(prop)) {
+                this.set(prop, other.getAsString(prop));
+            }
+        }
+    }
+    /**
+     * 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) {
+        for (const key of other.getStyleNames()) {
+            if (!this.has(key) || this.getAsString(key) !== other.getAsString(key)) {
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * Removes empty objects upon removing an entry from internal object.
      */

package/src/view/tokenlist.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @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
+ */
+/**
+ * @module engine/view/tokenlist
+ */
+import { type ArrayOrItem } from '@ckeditor/ckeditor5-utils';
+import type { ElementAttributeValue } from './element.js';
+/**
+ * Token list. Allows handling (adding, removing, retrieving) a set of tokens (for example class names).
+ */
+export default class TokenList implements ElementAttributeValue {
+    /**
+     * The set of tokens.
+     */
+    private _set;
+    /**
+     * Returns true if token list has no tokens set.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Number of tokens.
+     */
+    get size(): number;
+    /**
+     * Checks if a given token is set.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns all tokens.
+     */
+    keys(): Array<string>;
+    /**
+     * Resets the value to the given one.
+     */
+    setTo(value: string): this;
+    /**
+     * Sets a given token without affecting other tokens.
+     */
+    set(tokens: ArrayOrItem<string>): void;
+    /**
+     * Removes given token.
+     */
+    remove(tokens: ArrayOrItem<string>): void;
+    /**
+     * Removes all tokens.
+     */
+    clear(): void;
+    /**
+     * Returns a normalized tokens string.
+     */
+    toString(): string;
+    /**
+     * Returns `true` if both attributes have the same tokens.
+     */
+    isSimilar(other: TokenList): boolean;
+    /**
+     * Clones the attribute value.
+     *
+     * @internal
+     */
+    _clone(): this;
+    /**
+     * Used by the {@link module:engine/view/matcher~Matcher Matcher} to collect matching attribute tokens.
+     *
+     * @internal
+     * @param tokenPattern The matched token name pattern.
+     * @returns An array of matching tokens.
+     */
+    _getTokensMatch(tokenPattern: true | string | RegExp): Array<string> | undefined;
+    /**
+     * Returns a list of consumables for the attribute.
+     *
+     * Could be filtered by the given token 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 downcasting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other `AttributeElement`.
+     *
+     * @internal
+     */
+    _canMergeFrom(): 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: TokenList): 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: TokenList): boolean;
+}

package/src/view/tokenlist.js

@@ -0,0 +1,196 @@
+/**
+ * @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
+ */
+/**
+ * @module engine/view/tokenlist
+ */
+import { toArray } from '@ckeditor/ckeditor5-utils';
+/**
+ * Token list. Allows handling (adding, removing, retrieving) a set of tokens (for example class names).
+ */
+export default class TokenList {
+    constructor() {
+        /**
+         * The set of tokens.
+         */
+        this._set = new Set();
+    }
+    /**
+     * Returns true if token list has no tokens set.
+     */
+    get isEmpty() {
+        return this._set.size == 0;
+    }
+    /**
+     * Number of tokens.
+     */
+    get size() {
+        return this._set.size;
+    }
+    /**
+     * Checks if a given token is set.
+     */
+    has(name) {
+        return this._set.has(name);
+    }
+    /**
+     * Returns all tokens.
+     */
+    keys() {
+        return Array.from(this._set.keys());
+    }
+    /**
+     * Resets the value to the given one.
+     */
+    setTo(value) {
+        this.clear();
+        for (const token of value.split(/\s+/)) {
+            if (token) {
+                this._set.add(token);
+            }
+        }
+        return this;
+    }
+    /**
+     * Sets a given token without affecting other tokens.
+     */
+    set(tokens) {
+        for (const token of toArray(tokens)) {
+            if (token) {
+                this._set.add(token);
+            }
+        }
+    }
+    /**
+     * Removes given token.
+     */
+    remove(tokens) {
+        for (const token of toArray(tokens)) {
+            this._set.delete(token);
+        }
+    }
+    /**
+     * Removes all tokens.
+     */
+    clear() {
+        this._set.clear();
+    }
+    /**
+     * Returns a normalized tokens string.
+     */
+    toString() {
+        return Array.from(this._set).join(' ');
+    }
+    /**
+     * Returns `true` if both attributes have the same tokens.
+     */
+    isSimilar(other) {
+        if (this.size !== other.size) {
+            return false;
+        }
+        for (const token of this.keys()) {
+            if (!other.has(token)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Clones the attribute value.
+     *
+     * @internal
+     */
+    _clone() {
+        const clone = new this.constructor();
+        clone._set = new Set(this._set);
+        return clone;
+    }
+    /**
+     * Used by the {@link module:engine/view/matcher~Matcher Matcher} to collect matching attribute tokens.
+     *
+     * @internal
+     * @param tokenPattern The matched token name pattern.
+     * @returns An array of matching tokens.
+     */
+    _getTokensMatch(tokenPattern) {
+        const match = [];
+        if (tokenPattern === true) {
+            for (const token of this._set.keys()) {
+                match.push(token);
+            }
+            return match;
+        }
+        if (typeof tokenPattern == 'string') {
+            for (const token of tokenPattern.split(/\s+/)) {
+                if (this._set.has(token)) {
+                    match.push(token);
+                }
+                else {
+                    return undefined;
+                }
+            }
+            return match;
+        }
+        for (const token of this._set.keys()) {
+            if (token.match(tokenPattern)) {
+                match.push(token);
+            }
+        }
+        return match.length ? match : undefined;
+    }
+    /**
+     * Returns a list of consumables for the attribute.
+     *
+     * Could be filtered by the given token name.
+     *
+     * @internal
+     */
+    _getConsumables(name) {
+        return name ? [name] : this.keys();
+    }
+    /**
+     * 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 downcasting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other `AttributeElement`.
+     *
+     * @internal
+     */
+    _canMergeFrom() {
+        return true;
+    }
+    /**
+     * 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) {
+        for (const token of other._set.keys()) {
+            if (!this._set.has(token)) {
+                this._set.add(token);
+            }
+        }
+    }
+    /**
+     * 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) {
+        for (const name of other._set.keys()) {
+            if (!this._set.has(name)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}