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

package/src/conversion/viewconsumable.js

@@ -5,7 +5,7 @@
 /**
  * @module engine/conversion/viewconsumable
  */
-import { CKEditorError, toArray } from '@ckeditor/ckeditor5-utils';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * Class used for handling consumption of view {@link module:engine/view/element~Element elements},
  * {@link module:engine/view/text~Text text nodes} and {@link module:engine/view/documentfragment~DocumentFragment document fragments}.
@@ -41,6 +41,35 @@ export default class ViewConsumable {
          */
         this._consumables = new Map();
     }
+    /**
+     * Adds view {@link module:engine/view/element~Element element}, {@link module:engine/view/text~Text text node} or
+     * {@link module:engine/view/documentfragment~DocumentFragment document fragment} as ready to be consumed.
+     *
+     * ```ts
+     * viewConsumable.add( p, { name: true } ); // Adds element's name to consume.
+     * viewConsumable.add( p, { attributes: 'name' } ); // Adds element's attribute.
+     * viewConsumable.add( p, { classes: 'foobar' } ); // Adds element's class.
+     * viewConsumable.add( p, { styles: 'color' } ); // Adds element's style
+     * viewConsumable.add( p, { attributes: 'name', styles: 'color' } ); // Adds attribute and style.
+     * viewConsumable.add( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be provided.
+     * viewConsumable.add( textNode ); // Adds text node to consume.
+     * viewConsumable.add( docFragment ); // Adds document fragment to consume.
+     * ```
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `viewconsumable-invalid-attribute` when `class` or `style`
+     * attribute is provided - it should be handled separately by providing actual style/class.
+     *
+     * ```ts
+     * viewConsumable.add( p, { attributes: 'style' } ); // This call will throw an exception.
+     * viewConsumable.add( p, { styles: 'color' } ); // This is properly handled style.
+     * ```
+     *
+     * @param consumables Used only if first parameter is {@link module:engine/view/element~Element view element} instance.
+     * @param consumables.name If set to true element's name will be included.
+     * @param consumables.attributes Attribute name or array of attribute names.
+     * @param consumables.classes Class name or array of class names.
+     * @param consumables.styles Style name or array of style names.
+     */
     add(element, consumables) {
         let elementConsumables;
         // For text nodes and document fragments just mark them as consumable.
@@ -56,7 +85,7 @@ export default class ViewConsumable {
         else {
             elementConsumables = this._consumables.get(element);
         }
-        elementConsumables.add(consumables);
+        elementConsumables.add(consumables ? normalizeConsumables(consumables) : element._getConsumables());
     }
     /**
      * Tests if {@link module:engine/view/element~Element view element}, {@link module:engine/view/text~Text text node} or
@@ -100,7 +129,7 @@ export default class ViewConsumable {
             return elementConsumables;
         }
         // For elements test consumables object.
-        return elementConsumables.test(consumables);
+        return elementConsumables.test(normalizeConsumables(consumables));
     }
     /**
      * Consumes {@link module:engine/view/element~Element view element}, {@link module:engine/view/text~Text text node} or
@@ -134,18 +163,20 @@ export default class ViewConsumable {
      * otherwise returns `false`.
      */
     consume(element, consumables) {
-        if (this.test(element, consumables)) {
-            if (element.is('$text') || element.is('documentFragment')) {
-                // For text nodes and document fragments set value to false.
-                this._consumables.set(element, false);
-            }
-            else {
-                // For elements - consume consumables object.
-                this._consumables.get(element).consume(consumables);
+        if (element.is('$text') || element.is('documentFragment')) {
+            if (!this.test(element, consumables)) {
+                return false;
             }
+            // For text nodes and document fragments set value to false.
+            this._consumables.set(element, false);
             return true;
         }
-        return false;
+        // For elements - consume consumables object.
+        const elementConsumables = this._consumables.get(element);
+        if (elementConsumables === undefined) {
+            return false;
+        }
+        return elementConsumables.consume(normalizeConsumables(consumables));
     }
     /**
      * Reverts {@link module:engine/view/element~Element view element}, {@link module:engine/view/text~Text text node} or
@@ -187,40 +218,10 @@ export default class ViewConsumable {
             }
             else {
                 // For elements - revert items from consumables object.
-                elementConsumables.revert(consumables);
+                elementConsumables.revert(normalizeConsumables(consumables));
             }
         }
     }
-    /**
-     * Creates consumable object from {@link module:engine/view/element~Element view element}. Consumable object will include
-     * element's name and all its attributes, classes and styles.
-     */
-    static consumablesFromElement(element) {
-        const consumables = {
-            element,
-            name: true,
-            attributes: [],
-            classes: [],
-            styles: []
-        };
-        const attributes = element.getAttributeKeys();
-        for (const attribute of attributes) {
-            // Skip classes and styles - will be added separately.
-            if (attribute == 'style' || attribute == 'class') {
-                continue;
-            }
-            consumables.attributes.push(attribute);
-        }
-        const classes = element.getClassNames();
-        for (const className of classes) {
-            consumables.classes.push(className);
-        }
-        const styles = element.getStyleNames();
-        for (const style of styles) {
-            consumables.styles.push(style);
-        }
-        return consumables;
-    }
     /**
      * Creates {@link module:engine/conversion/viewconsumable~ViewConsumable ViewConsumable} instance from
      * {@link module:engine/view/node~Node node} or {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
@@ -236,22 +237,16 @@ export default class ViewConsumable {
         }
         if (from.is('$text')) {
             instance.add(from);
-            return instance;
-        }
-        // Add `from` itself, if it is an element.
-        if (from.is('element')) {
-            instance.add(from, ViewConsumable.consumablesFromElement(from));
         }
-        if (from.is('documentFragment')) {
+        else if (from.is('element') || from.is('documentFragment')) {
             instance.add(from);
-        }
-        for (const child of from.getChildren()) {
-            instance = ViewConsumable.createFrom(child, instance);
+            for (const child of from.getChildren()) {
+                ViewConsumable.createFrom(child, instance);
+            }
         }
         return instance;
     }
 }
-const CONSUMABLE_TYPES = ['attributes', 'classes', 'styles'];
 /**
  * This is a private helper-class for {@link module:engine/conversion/viewconsumable~ViewConsumable}.
  * It represents and manipulates consumable parts of a single {@link module:engine/view/element~Element}.
@@ -260,16 +255,21 @@ export class ViewElementConsumables {
     /**
      * Creates ViewElementConsumables instance.
      *
-     * @param from View node or document fragment from which `ViewElementConsumables` is being created.
+     * @param from View element from which `ViewElementConsumables` is being created.
      */
     constructor(from) {
-        this.element = from;
+        /**
+         * Flag indicating if name of the element can be consumed.
+         */
         this._canConsumeName = null;
-        this._consumables = {
-            attributes: new Map(),
-            styles: new Map(),
-            classes: new Map()
-        };
+        /**
+         * A map of element's consumables.
+         * * For plain attributes the value is a boolean indicating whether the attribute is available to consume.
+         * * For token based attributes (like class list and style) the value is a map of tokens to booleans
+         * indicating whether the token is available to consume on the given attribute.
+         */
+        this._attributes = new Map();
+        this.element = from;
     }
     /**
      * Adds consumable parts of the {@link module:engine/view/element~Element view element}.
@@ -283,31 +283,60 @@ export class ViewElementConsumables {
      * Attributes classes and styles:
      *
      * ```ts
-     * consumables.add( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     * consumables.add( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * consumables.add( { attributes: [ [ 'title' ], [ 'class', 'foo' ], [ 'style', 'color'] ] } );
+     * consumables.add( { attributes: [ [ 'title' ], [ 'name' ], [ 'class', 'foo' ], [ 'class', 'bar' ] ] } );
      * ```
      *
+     * Note: This method accepts only {@link module:engine/view/element~NormalizedConsumables}.
+     * You can use {@link module:engine/conversion/viewconsumable~normalizeConsumables} helper to convert from
+     * {@link module:engine/conversion/viewconsumable~Consumables} to `NormalizedConsumables`.
+     *
      * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `viewconsumable-invalid-attribute` when `class` or `style`
      * attribute is provided - it should be handled separately by providing `style` and `class` in consumables object.
      *
      * @param consumables Object describing which parts of the element can be consumed.
-     * @param consumables.name If set to `true` element's name will be added as consumable.
-     * @param consumables.attributes Attribute name or array of attribute names to add as consumable.
-     * @param consumables.classes Class name or array of class names to add as consumable.
-     * @param consumables.styles Style name or array of style names to add as consumable.
      */
     add(consumables) {
         if (consumables.name) {
             this._canConsumeName = true;
         }
-        for (const type of CONSUMABLE_TYPES) {
-            if (type in consumables) {
-                this._add(type, consumables[type]);
+        for (const [name, token] of consumables.attributes) {
+            if (token) {
+                let attributeTokens = this._attributes.get(name);
+                if (!attributeTokens || typeof attributeTokens == 'boolean') {
+                    attributeTokens = new Map();
+                    this._attributes.set(name, attributeTokens);
+                }
+                attributeTokens.set(token, true);
+            }
+            else if (name == 'style' || name == 'class') {
+                /**
+                 * Class and style attributes should be handled separately in
+                 * {@link module:engine/conversion/viewconsumable~ViewConsumable#add `ViewConsumable#add()`}.
+                 *
+                 * What you have done is trying to use:
+                 *
+                 * ```ts
+                 * consumables.add( { attributes: [ 'class', 'style' ] } );
+                 * ```
+                 *
+                 * While each class and style should be registered separately:
+                 *
+                 * ```ts
+                 * consumables.add( { classes: 'some-class', styles: 'font-weight' } );
+                 * ```
+                 *
+                 * @error viewconsumable-invalid-attribute
+                 */
+                throw new CKEditorError('viewconsumable-invalid-attribute', this);
+            }
+            else {
+                this._attributes.set(name, true);
             }
         }
     }
     /**
-     * Tests if parts of the {@link module:engine/view/node~Node view node} can be consumed.
+     * Tests if parts of the {@link module:engine/view/element~Element view element} can be consumed.
      *
      * Element's name can be tested:
      *
@@ -318,15 +347,11 @@ export class ViewElementConsumables {
      * Attributes classes and styles:
      *
      * ```ts
-     * consumables.test( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     * consumables.test( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * consumables.test( { attributes: [ [ 'title' ], [ 'class', 'foo' ], [ 'style', 'color' ] ] } );
+     * consumables.test( { attributes: [ [ 'title' ], [ 'name' ], [ 'class', 'foo' ], [ 'class', 'bar' ] ] } );
      * ```
      *
      * @param consumables Object describing which parts of the element should be tested.
-     * @param consumables.name If set to `true` element's name will be tested.
-     * @param consumables.attributes Attribute name or array of attribute names to test.
-     * @param consumables.classes Class name or array of class names to test.
-     * @param consumables.styles Style name or array of style names to test.
      * @returns `true` when all tested items can be consumed, `null` when even one of the items
      * was never marked for consumption and `false` when even one of the items was already consumed.
      */
@@ -335,11 +360,38 @@ export class ViewElementConsumables {
         if (consumables.name && !this._canConsumeName) {
             return this._canConsumeName;
         }
-        for (const type of CONSUMABLE_TYPES) {
-            if (type in consumables) {
-                const value = this._test(type, consumables[type]);
-                if (value !== true) {
-                    return value;
+        for (const [name, token] of consumables.attributes) {
+            const value = this._attributes.get(name);
+            // Return null if attribute is not found.
+            if (value === undefined) {
+                return null;
+            }
+            // Already consumed.
+            if (value === false) {
+                return false;
+            }
+            // Simple attribute is not consumed so continue to next attribute.
+            if (value === true) {
+                continue;
+            }
+            if (!token) {
+                // Tokenized attribute but token is not specified so check if all tokens are not consumed.
+                for (const tokenValue of value.values()) {
+                    // Already consumed token.
+                    if (!tokenValue) {
+                        return false;
+                    }
+                }
+            }
+            else {
+                const tokenValue = value.get(token);
+                // Return null if token is not found.
+                if (tokenValue === undefined) {
+                    return null;
+                }
+                // Already consumed.
+                if (!tokenValue) {
+                    return false;
                 }
             }
         }
@@ -347,8 +399,9 @@ export class ViewElementConsumables {
         return true;
     }
     /**
-     * Consumes parts of {@link module:engine/view/element~Element view element}. This function does not check if consumable item
-     * is already consumed - it consumes all consumable items provided.
+     * Tests if parts of the {@link module:engine/view/element~Element view element} can be consumed and consumes them if available.
+     * It returns `true` when all items included in method's call can be consumed, otherwise returns `false`.
+     *
      * Element's name can be consumed:
      *
      * ```ts
@@ -358,25 +411,44 @@ export class ViewElementConsumables {
      * Attributes classes and styles:
      *
      * ```ts
-     * consumables.consume( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     * consumables.consume( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * consumables.consume( { attributes: [ [ 'title' ], [ 'class', 'foo' ], [ 'style', 'color' ] ] } );
+     * consumables.consume( { attributes: [ [ 'title' ], [ 'name' ], [ 'class', 'foo' ], [ 'class', 'bar' ] ] } );
      * ```
      *
      * @param consumables Object describing which parts of the element should be consumed.
-     * @param consumables.name If set to `true` element's name will be consumed.
-     * @param consumables.attributes Attribute name or array of attribute names to consume.
-     * @param consumables.classes Class name or array of class names to consume.
-     * @param consumables.styles Style name or array of style names to consume.
+     * @returns `true` when all tested items can be consumed and `false` when even one of the items could not be consumed.
      */
     consume(consumables) {
+        if (!this.test(consumables)) {
+            return false;
+        }
         if (consumables.name) {
             this._canConsumeName = false;
         }
-        for (const type of CONSUMABLE_TYPES) {
-            if (type in consumables) {
-                this._consume(type, consumables[type]);
+        for (const [name, token] of consumables.attributes) {
+            // `value` must be set, because `this.test()` returned `true`.
+            const value = this._attributes.get(name);
+            // Plain (not tokenized) not-consumed attribute.
+            if (typeof value == 'boolean') {
+                // Use Element API to collect related attributes.
+                for (const [toConsume] of this.element._getConsumables(name, token).attributes) {
+                    this._attributes.set(toConsume, false);
+                }
+            }
+            else if (!token) {
+                // Tokenized attribute but token is not specified so consume all tokens.
+                for (const token of value.keys()) {
+                    value.set(token, false);
+                }
+            }
+            else {
+                // Use Element API to collect related attribute tokens.
+                for (const [, toConsume] of this.element._getConsumables(name, token).attributes) {
+                    value.set(toConsume, false);
+                }
             }
         }
+        return true;
     }
     /**
      * Revert already consumed parts of {@link module:engine/view/element~Element view Element}, so they can be consumed once again.
@@ -389,147 +461,77 @@ export class ViewElementConsumables {
      * Attributes classes and styles:
      *
      * ```ts
-     * consumables.revert( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     * consumables.revert( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * consumables.revert( { attributes: [ [ 'title' ], [ 'class', 'foo' ], [ 'style', 'color' ] ] } );
+     * consumables.revert( { attributes: [ [ 'title' ], [ 'name' ], [ 'class', 'foo' ], [ 'class', 'bar' ] ] } );
      * ```
      *
      * @param consumables Object describing which parts of the element should be reverted.
-     * @param consumables.name If set to `true` element's name will be reverted.
-     * @param consumables.attributes Attribute name or array of attribute names to revert.
-     * @param consumables.classes Class name or array of class names to revert.
-     * @param consumables.styles Style name or array of style names to revert.
      */
     revert(consumables) {
         if (consumables.name) {
             this._canConsumeName = true;
         }
-        for (const type of CONSUMABLE_TYPES) {
-            if (type in consumables) {
-                this._revert(type, consumables[type]);
-            }
-        }
-    }
-    /**
-     * Helper method that adds consumables of a given type: attribute, class or style.
-     *
-     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `viewconsumable-invalid-attribute` when `class` or `style`
-     * type is provided - it should be handled separately by providing actual style/class type.
-     *
-     * @param type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param item Consumable item or array of items.
-     */
-    _add(type, item) {
-        const items = toArray(item);
-        const consumables = this._consumables[type];
-        for (const name of items) {
-            if (type === 'attributes' && (name === 'class' || name === 'style')) {
-                /**
-                 * Class and style attributes should be handled separately in
-                 * {@link module:engine/conversion/viewconsumable~ViewConsumable#add `ViewConsumable#add()`}.
-                 *
-                 * What you have done is trying to use:
-                 *
-                 * ```ts
-                 * consumables.add( { attributes: [ 'class', 'style' ] } );
-                 * ```
-                 *
-                 * While each class and style should be registered separately:
-                 *
-                 * ```ts
-                 * consumables.add( { classes: 'some-class', styles: 'font-weight' } );
-                 * ```
-                 *
-                 * @error viewconsumable-invalid-attribute
-                 */
-                throw new CKEditorError('viewconsumable-invalid-attribute', this);
+        for (const [name, token] of consumables.attributes) {
+            const value = this._attributes.get(name);
+            // Plain consumed attribute.
+            if (value === false) {
+                this._attributes.set(name, true);
+                continue;
             }
-            consumables.set(name, true);
-            if (type === 'styles') {
-                for (const alsoName of this.element.document.stylesProcessor.getRelatedStyles(name)) {
-                    consumables.set(alsoName, true);
-                }
+            // Unknown attribute or not consumed.
+            if (value === undefined || value === true) {
+                continue;
             }
-        }
-    }
-    /**
-     * Helper method that tests consumables of a given type: attribute, class or style.
-     *
-     * @param type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param item Consumable item or array of items.
-     * @returns Returns `true` if all items can be consumed, `null` when one of the items cannot be
-     * consumed and `false` when one of the items is already consumed.
-     */
-    _test(type, item) {
-        const items = toArray(item);
-        const consumables = this._consumables[type];
-        for (const name of items) {
-            if (type === 'attributes' && (name === 'class' || name === 'style')) {
-                const consumableName = name == 'class' ? 'classes' : 'styles';
-                // Check all classes/styles if class/style attribute is tested.
-                const value = this._test(consumableName, [...this._consumables[consumableName].keys()]);
-                if (value !== true) {
-                    return value;
+            if (!token) {
+                // Tokenized attribute but token is not specified so revert all tokens.
+                for (const token of value.keys()) {
+                    value.set(token, true);
                 }
             }
             else {
-                const value = consumables.get(name);
-                // Return null if attribute is not found.
-                if (value === undefined) {
-                    return null;
-                }
-                if (!value) {
-                    return false;
+                const tokenValue = value.get(token);
+                if (tokenValue === false) {
+                    value.set(token, true);
                 }
+                // Note that revert of consumed related styles is not handled.
             }
         }
-        return true;
     }
-    /**
-     * Helper method that consumes items of a given type: attribute, class or style.
-     *
-     * @param type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param item Consumable item or array of items.
-     */
-    _consume(type, item) {
-        const items = toArray(item);
-        const consumables = this._consumables[type];
-        for (const name of items) {
-            if (type === 'attributes' && (name === 'class' || name === 'style')) {
-                const consumableName = name == 'class' ? 'classes' : 'styles';
-                // If class or style is provided for consumption - consume them all.
-                this._consume(consumableName, [...this._consumables[consumableName].keys()]);
-            }
-            else {
-                consumables.set(name, false);
-                if (type == 'styles') {
-                    for (const toConsume of this.element.document.stylesProcessor.getRelatedStyles(name)) {
-                        consumables.set(toConsume, false);
-                    }
-                }
-            }
-        }
+}
+/**
+ * Normalizes a {@link module:engine/conversion/viewconsumable~Consumables} or {@link module:engine/view/matcher~Match}
+ * to a {@link module:engine/view/element~NormalizedConsumables}.
+ */
+export function normalizeConsumables(consumables) {
+    const attributes = [];
+    if ('attributes' in consumables && consumables.attributes) {
+        normalizeConsumablePart(attributes, consumables.attributes);
     }
-    /**
-     * Helper method that reverts items of a given type: attribute, class or style.
-     *
-     * @param type Type of the consumable item: `attributes`, `classes` or , `styles`.
-     * @param item Consumable item or array of items.
-     */
-    _revert(type, item) {
-        const items = toArray(item);
-        const consumables = this._consumables[type];
-        for (const name of items) {
-            if (type === 'attributes' && (name === 'class' || name === 'style')) {
-                const consumableName = name == 'class' ? 'classes' : 'styles';
-                // If class or style is provided for reverting - revert them all.
-                this._revert(consumableName, [...this._consumables[consumableName].keys()]);
-            }
-            else {
-                const value = consumables.get(name);
-                if (value === false) {
-                    consumables.set(name, true);
-                }
-            }
+    if ('classes' in consumables && consumables.classes) {
+        normalizeConsumablePart(attributes, consumables.classes, 'class');
+    }
+    if ('styles' in consumables && consumables.styles) {
+        normalizeConsumablePart(attributes, consumables.styles, 'style');
+    }
+    return {
+        name: consumables.name || false,
+        attributes
+    };
+}
+/**
+ * Normalizes a list of consumable attributes to a common tuple format.
+ */
+function normalizeConsumablePart(attributes, items, prefix) {
+    if (typeof items == 'string') {
+        attributes.push(prefix ? [prefix, items] : [items]);
+        return;
+    }
+    for (const item of items) {
+        if (Array.isArray(item)) {
+            attributes.push(item);
+        }
+        else {
+            attributes.push(prefix ? [prefix, item] : [item]);
         }
     }
 }

package/src/view/attributeelement.d.ts

@@ -105,4 +105,18 @@ export default class AttributeElement extends Element {
      * @returns Clone of this element.
      */
     _clone(deep?: boolean): this;
+    /**
+     * Used by {@link module:engine/view/element~Element#_mergeAttributesFrom} to verify if the given element can be merged without
+     * conflicts into this element.
+     *
+     * @internal
+     */
+    _canMergeAttributesFrom(otherElement: AttributeElement): boolean;
+    /**
+     * Used by {@link module:engine/view/element~Element#_subtractAttributesOf} to verify if the given element attributes
+     * can be fully subtracted from this element.
+     *
+     * @internal
+     */
+    _canSubtractAttributesOf(otherElement: AttributeElement): boolean;
 }

package/src/view/attributeelement.js

@@ -135,6 +135,32 @@ class AttributeElement extends Element {
         cloned._id = this._id;
         return cloned;
     }
+    /**
+     * Used by {@link module:engine/view/element~Element#_mergeAttributesFrom} to verify if the given element can be merged without
+     * conflicts into this element.
+     *
+     * @internal
+     */
+    _canMergeAttributesFrom(otherElement) {
+        // Can't merge if any of elements have an id or a difference of priority.
+        if (this.id !== null || otherElement.id !== null || this.priority !== otherElement.priority) {
+            return false;
+        }
+        return super._canMergeAttributesFrom(otherElement);
+    }
+    /**
+     * Used by {@link module:engine/view/element~Element#_subtractAttributesOf} to verify if the given element attributes
+     * can be fully subtracted from this element.
+     *
+     * @internal
+     */
+    _canSubtractAttributesOf(otherElement) {
+        // Can't subtract if any of elements have an id or a difference of priority.
+        if (this.id !== null || otherElement.id !== null || this.priority !== otherElement.priority) {
+            return false;
+        }
+        return super._canSubtractAttributesOf(otherElement);
+    }
 }
 AttributeElement.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
 export default AttributeElement;