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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "44.2.1",
+  "version": "44.3.0-alpha.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -24,7 +24,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "44.2.1",
+    "@ckeditor/ckeditor5-utils": "44.3.0-alpha.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
@@ -42,7 +42,6 @@
     "src/**/*.js",
     "src/**/*.d.ts",
     "theme",
-    "ckeditor5-metadata.json",
     "CHANGELOG.md"
   ],
   "types": "src/index.d.ts",
@@ -63,7 +62,6 @@
       "default": "./src/*"
     },
     "./theme/*": "./theme/*",
-    "./ckeditor5-metadata.json": "./ckeditor5-metadata.json",
     "./package.json": "./package.json"
   }
 }

package/src/conversion/downcasthelpers.js

@@ -1353,57 +1353,29 @@ function changeAttribute(attributeCreator) {
         }
         // First remove the old attribute if there was one.
         if (data.attributeOldValue !== null && oldAttribute) {
-            if (oldAttribute.key == 'class') {
-                const classes = typeof oldAttribute.value == 'string' ? oldAttribute.value.split(/\s+/) : oldAttribute.value;
-                for (const className of classes) {
-                    viewWriter.removeClass(className, viewElement);
-                }
-            }
-            else if (oldAttribute.key == 'style') {
+            let value = oldAttribute.value;
+            if (oldAttribute.key == 'style') {
                 if (typeof oldAttribute.value == 'string') {
-                    const styles = new StylesMap(viewWriter.document.stylesProcessor);
-                    styles.setTo(oldAttribute.value);
-                    for (const [key] of styles.getStylesEntries()) {
-                        viewWriter.removeStyle(key, viewElement);
-                    }
+                    value = new StylesMap(viewWriter.document.stylesProcessor)
+                        .setTo(oldAttribute.value)
+                        .getStylesEntries()
+                        .map(([key]) => key);
                 }
                 else {
-                    const keys = Object.keys(oldAttribute.value);
-                    for (const key of keys) {
-                        viewWriter.removeStyle(key, viewElement);
-                    }
+                    value = Object.keys(oldAttribute.value);
                 }
             }
-            else {
-                viewWriter.removeAttribute(oldAttribute.key, viewElement);
-            }
+            viewWriter.removeAttribute(oldAttribute.key, value, viewElement);
         }
         // Then set the new attribute.
         if (data.attributeNewValue !== null && newAttribute) {
-            if (newAttribute.key == 'class') {
-                const classes = typeof newAttribute.value == 'string' ? newAttribute.value.split(/\s+/) : newAttribute.value;
-                for (const className of classes) {
-                    viewWriter.addClass(className, viewElement);
-                }
-            }
-            else if (newAttribute.key == 'style') {
-                if (typeof newAttribute.value == 'string') {
-                    const styles = new StylesMap(viewWriter.document.stylesProcessor);
-                    styles.setTo(newAttribute.value);
-                    for (const [key, value] of styles.getStylesEntries()) {
-                        viewWriter.setStyle(key, value, viewElement);
-                    }
-                }
-                else {
-                    const keys = Object.keys(newAttribute.value);
-                    for (const key of keys) {
-                        viewWriter.setStyle(key, newAttribute.value[key], viewElement);
-                    }
-                }
-            }
-            else {
-                viewWriter.setAttribute(newAttribute.key, newAttribute.value, viewElement);
+            let value = newAttribute.value;
+            if (newAttribute.key == 'style' && typeof newAttribute.value == 'string') {
+                value = Object.fromEntries(new StylesMap(viewWriter.document.stylesProcessor)
+                    .setTo(newAttribute.value)
+                    .getStylesEntries());
             }
+            viewWriter.setAttribute(newAttribute.key, value, false, viewElement);
         }
     };
 }

package/src/conversion/viewconsumable.d.ts

@@ -2,7 +2,7 @@
  * @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 Element from '../view/element.js';
+import type { default as Element, NormalizedConsumables } from '../view/element.js';
 import type Node from '../view/node.js';
 import type Text from '../view/text.js';
 import type DocumentFragment from '../view/documentfragment.js';
@@ -41,29 +41,18 @@ export default class ViewConsumable {
      */
     private _consumables;
     /**
-     * Adds {@link module:engine/view/text~Text text node} or
+     * 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( textNode ); // Adds text node to consume.
-     * viewConsumable.add( docFragment ); // Adds document fragment to consume.
-     * ```
-     *
-     * See also: {@link #add:ELEMENT `add( element, consumables )`}.
-     *
-     * @label TEXT_OR_FRAGMENT
-     */
-    add(textOrDocumentFragment: Text | DocumentFragment): void;
-    /**
-     * Adds {@link module:engine/view/element~Element view element} 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`
@@ -74,16 +63,13 @@ export default class ViewConsumable {
      * viewConsumable.add( p, { styles: 'color' } ); // This is properly handled style.
      * ```
      *
-     * See also: {@link #add:TEXT_OR_FRAGMENT `add( textOrDocumentFragment )`}.
-     *
-     * @label ELEMENT
      * @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: Element, consumables: Consumables): void;
+    add(element: Text | Element | DocumentFragment, consumables?: Consumables | NormalizedConsumables): void;
     /**
      * Tests if {@link module:engine/view/element~Element view element}, {@link module:engine/view/text~Text text node} or
      * {@link module:engine/view/documentfragment~DocumentFragment document fragment} can be consumed.
@@ -180,14 +166,7 @@ export default class ViewConsumable {
      * @param consumables.classes Class name or array of class names.
      * @param consumables.styles Style name or array of style names.
      */
-    revert(element: Node, consumables: Consumables): void;
-    /**
-     * 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: Element): Consumables & {
-        element: Element;
-    };
+    revert(element: Node, consumables: Consumables | Match): void;
     /**
      * 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}.
@@ -199,9 +178,33 @@ export default class ViewConsumable {
      */
     static createFrom(from: Node | DocumentFragment, instance?: ViewConsumable): ViewConsumable;
 }
+/**
+ * Object describing all features of a view element that could be consumed and converted individually.
+ * This is a non-normalized form of {@link module:engine/view/element~NormalizedConsumables} generated from the view Element.
+ *
+ * Example element:
+ *
+ * ```html
+ * <a class="foo bar" style="color: red; margin: 5px" href="https://ckeditor.com" rel="nofollow noreferrer" target="_blank">
+ * ```
+ *
+ * The `Consumables` would include:
+ *
+ * ```json
+ * {
+ * 	name: true,
+ * 	classes: [ "foo", "bar" ],
+ * 	styles: [ "color", "margin" ]
+ * }
+ * ```
+ *
+ * You could convert a `Consumable` into a {@link module:engine/view/element~NormalizedConsumables}
+ * using the {@link module:engine/conversion/viewconsumable~normalizeConsumables} helper.
+ */
 export interface Consumables {
     /**
-     * If set to true element's name will be included.
+     * If set to `true` element's name will be included in a consumable.
+     * Depending on the usage context it would be added as consumable, tested for being available for consume or consumed.
      */
     name?: boolean;
     /**
@@ -222,21 +225,24 @@ export interface Consumables {
  * It represents and manipulates consumable parts of a single {@link module:engine/view/element~Element}.
  */
 export declare class ViewElementConsumables {
-    readonly element: Node | DocumentFragment;
+    readonly element: Element;
     /**
      * Flag indicating if name of the element can be consumed.
      */
     private _canConsumeName;
     /**
-     * Contains maps of element's consumables: attributes, classes and styles.
+     * 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.
      */
-    private readonly _consumables;
+    private readonly _attributes;
     /**
      * 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: Node | DocumentFragment);
+    constructor(from: Element);
     /**
      * Adds consumable parts of the {@link module:engine/view/element~Element view element}.
      * Element's name itself can be marked to be consumed (when element's name is consumed its attributes, classes and
@@ -249,22 +255,22 @@ export declare 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: Consumables): void;
+    add(consumables: NormalizedConsumables): void;
     /**
-     * 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:
      *
@@ -275,22 +281,19 @@ export declare 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.
      */
-    test(consumables: Consumables | Match): boolean | null;
+    test(consumables: NormalizedConsumables): boolean | null;
     /**
-     * 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
@@ -300,17 +303,14 @@ export declare 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: Consumables | Match): void;
+    consume(consumables: NormalizedConsumables): boolean;
     /**
      * Revert already consumed parts of {@link module:engine/view/element~Element view Element}, so they can be consumed once again.
      * Element's name can be reverted:
@@ -322,48 +322,16 @@ export declare 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: Consumables): void;
-    /**
-     * 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.
-     */
-    private _add;
-    /**
-     * 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.
-     */
-    private _test;
-    /**
-     * 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.
-     */
-    private _consume;
-    /**
-     * 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.
-     */
-    private _revert;
+    revert(consumables: NormalizedConsumables): void;
 }
+/**
+ * Normalizes a {@link module:engine/conversion/viewconsumable~Consumables} or {@link module:engine/view/matcher~Match}
+ * to a {@link module:engine/view/element~NormalizedConsumables}.
+ */
+export declare function normalizeConsumables(consumables: Consumables | Match): NormalizedConsumables;