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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "37.0.0-alpha.0",
+  "version": "37.0.0-alpha.2",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,30 +23,30 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.2",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-cloud-services": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-essentials": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-link": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-mention": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.0",
-    "@ckeditor/ckeditor5-widget": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-clipboard": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-cloud-services": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-essentials": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-link": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-mention": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-undo": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-widget": "^37.0.0-alpha.2",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -73,7 +73,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc -p ./tsconfig.release.json",
+    "build": "tsc -p ./tsconfig.json",
     "postversion": "npm run build"
   },
   "types": "src/index.d.ts"

package/src/controller/datacontroller.d.ts

@@ -132,7 +132,7 @@ export default class DataController extends DataController_base {
      * converted by the {@link #upcastDispatcher view-to-model converters}.
      * Initial data can be only set to a document whose {@link module:engine/model/document~Document#version} is equal 0.
      *
-     * **Note** This method is {@link module:utils/observablemixin~ObservableMixin#decorate decorated} which is
+     * **Note** This method is {@link module:utils/observablemixin~Observable#decorate decorated} which is
      * used by e.g. collaborative editing plugin that syncs remote data on init.
      *
      * When data is passed as a string, it is initialized on the default `main` root:
@@ -255,21 +255,21 @@ export default class DataController extends DataController_base {
 /**
  * Event fired once the data initialization has finished.
  *
- * @eventName ready
+ * @eventName ~DataController#ready
  */
 export type DataControllerReadyEvent = {
     name: 'ready';
     args: [];
 };
 /**
- * An event fired after the {@link #init `init()` method} was run. It can be {@link #listenTo listened to} in order to adjust or modify
- * the initialization flow. However, if the `init` event is stopped or prevented, the {@link #event:ready `ready` event}
- * should be fired manually.
+ * An event fired after the {@link ~DataController#init `init()` method} was run. It can be {@link ~DataController#listenTo listened to} in
+ * order to adjust or modify the initialization flow. However, if the `init` event is stopped or prevented,
+ * the {@link ~DataController#event:ready `ready` event} should be fired manually.
  *
- * The `init` event is fired by the decorated {@link #init} method.
- * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
+ * The `init` event is fired by the decorated {@link ~DataController#init} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
  *
- * @eventName init
+ * @eventName ~DataController#init
  */
 export type DataControllerInitEvent = {
     name: 'init';
@@ -277,12 +277,12 @@ export type DataControllerInitEvent = {
     return: ReturnType<DataController['init']>;
 };
 /**
- * An event fired after {@link #set set() method} has been run.
+ * An event fired after {@link ~DataController#set set() method} has been run.
  *
- * The `set` event is fired by the decorated {@link #set} method.
- * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
+ * The `set` event is fired by the decorated {@link ~DataController#set} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
  *
- * @eventName set
+ * @eventName ~DataController#set
  */
 export type DataControllerSetEvent = {
     name: 'set';
@@ -290,12 +290,12 @@ export type DataControllerSetEvent = {
     return: ReturnType<DataController['set']>;
 };
 /**
- * Event fired after the {@link #get get() method} has been run.
+ * Event fired after the {@link ~DataController#get get() method} has been run.
  *
- * The `get` event is fired by the decorated {@link #get} method.
- * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
+ * The `get` event is fired by the decorated {@link ~DataController#get} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
  *
- * @eventName get
+ * @eventName ~DataController#get
  */
 export type DataControllerGetEvent = {
     name: 'get';
@@ -303,12 +303,12 @@ export type DataControllerGetEvent = {
     return: ReturnType<DataController['get']>;
 };
 /**
- * Event fired after the {@link #toView toView() method} has been run.
+ * Event fired after the {@link ~DataController#toView toView() method} has been run.
  *
- * The `toView` event is fired by the decorated {@link #toView} method.
- * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
+ * The `toView` event is fired by the decorated {@link ~DataController#toView} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
  *
- * @eventName toView
+ * @eventName ~DataController#toView
  */
 export type DataControllerToViewEvent = {
     name: 'toView';
@@ -316,12 +316,12 @@ export type DataControllerToViewEvent = {
     return: ReturnType<DataController['toView']>;
 };
 /**
- * Event fired after the {@link #toModel toModel() method} has been run.
+ * Event fired after the {@link ~DataController#toModel toModel() method} has been run.
  *
- * The `toModel` event is fired by the decorated {@link #toModel} method.
- * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
+ * The `toModel` event is fired by the decorated {@link ~DataController#toModel} method.
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
  *
- * @eventName toModel
+ * @eventName ~DataController#toModel
  */
 export type DataControllerToModelEvent = {
     name: 'toModel';

package/src/controller/datacontroller.js

@@ -100,9 +100,10 @@ export default class DataController extends EmitterMixin() {
         const { rootName = 'main', trim = 'empty' } = options;
         if (!this._checkIfRootsExists([rootName])) {
             /**
-             * Cannot get data from a non-existing root. This error is thrown when {@link #get DataController#get() method}
+             * Cannot get data from a non-existing root. This error is thrown when
+             * {@link module:engine/controller/datacontroller~DataController#get `DataController#get()` method}
              * is called with a non-existent root name. For example, if there is an editor instance with only `main` root,
-             * calling {@link #get} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#get} like:
              *
              * ```ts
              * data.get( { rootName: 'root2' } );
@@ -172,7 +173,7 @@ export default class DataController extends EmitterMixin() {
      * converted by the {@link #upcastDispatcher view-to-model converters}.
      * Initial data can be only set to a document whose {@link module:engine/model/document~Document#version} is equal 0.
      *
-     * **Note** This method is {@link module:utils/observablemixin~ObservableMixin#decorate decorated} which is
+     * **Note** This method is {@link module:utils/observablemixin~Observable#decorate decorated} which is
      * used by e.g. collaborative editing plugin that syncs remote data on init.
      *
      * When data is passed as a string, it is initialized on the default `main` root:
@@ -212,9 +213,10 @@ export default class DataController extends EmitterMixin() {
         }
         if (!this._checkIfRootsExists(Object.keys(initialData))) {
             /**
-             * Cannot init data on a non-existent root. This error is thrown when {@link #init DataController#init() method}
+             * Cannot init data on a non-existent root. This error is thrown when
+             * {@link module:engine/controller/datacontroller~DataController#init DataController#init() method}
              * is called with non-existent root name. For example, if there is an editor instance with only `main` root,
-             * calling {@link #init} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#init} like:
              *
              * ```ts
              * data.init( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );
@@ -280,9 +282,10 @@ export default class DataController extends EmitterMixin() {
         }
         if (!this._checkIfRootsExists(Object.keys(newData))) {
             /**
-             * Cannot set data on a non-existent root. This error is thrown when the {@link #set DataController#set() method}
+             * Cannot set data on a non-existent root. This error is thrown when the
+             * {@link module:engine/controller/datacontroller~DataController#set DataController#set() method}
              * is called with non-existent root name. For example, if there is an editor instance with only the default `main` root,
-             * calling {@link #set} like:
+             * calling {@link module:engine/controller/datacontroller~DataController#set} like:
              *
              * ```ts
              * data.set( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );

package/src/conversion/downcastdispatcher.d.ts

@@ -309,7 +309,7 @@ export default class DowncastDispatcher extends DowncastDispatcher_base {
 }
 /**
  * Fired to enable reducing (transforming) changes buffered in the {@link module:engine/model/differ~Differ `Differ`} before
- * {@link #convertChanges `convertChanges()`} will fire any conversion events.
+ * {@link ~DowncastDispatcher#convertChanges `convertChanges()`} will fire any conversion events.
  *
  * For instance, a feature can replace selected {@link module:engine/model/differ~DiffItem `DiffItem`}s with a `reinsert` entry
  * to trigger reconversion of an element when e.g. its attribute has changes.
@@ -317,7 +317,7 @@ export default class DowncastDispatcher extends DowncastDispatcher_base {
      * `DowncastHelpers.elementToStructure()`} helper is using this event to trigger reconversion of an element when the element,
  * its attributes or direct children changed.
  *
- * @eventName reduceChanges
+ * @eventName ~DowncastDispatcher#reduceChanges
  */
 export type DowncastReduceChangesEvent = {
     name: 'reduceChanges';
@@ -373,7 +373,7 @@ export type DowncastEvent<TName extends keyof EventMap<TItem>, TItem = Item> = {
  *
  * This way, the listeners can either listen to a general `insert` event or specific event (for example `insert:paragraph`).
  *
- * @eventName insert
+ * @eventName ~DowncastDispatcher#insert
  * @param {Object} data Additional information about the change.
  * @param {module:engine/model/item~Item} data.item The inserted item.
  * @param {module:engine/model/range~Range} data.range Range spanning over inserted item.
@@ -390,7 +390,7 @@ export type DowncastInsertEvent<TItem extends Item = Item> = DowncastEvent<'inse
  *
  * This way, listeners can either listen to a general `remove` event or specific event (for example `remove:paragraph`).
  *
- * @eventName remove
+ * @eventName ~DowncastDispatcher#remove
  * @param {Object} data Additional information about the change.
  * @param {module:engine/model/position~Position} data.position Position from which the node has been removed.
  * @param {Number} data.length Offset size of the removed node.
@@ -412,7 +412,7 @@ export type DowncastRemoveEvent = DowncastEvent<'remove'>;
  *
  * This way listeners can either listen to a general `attribute:bold` event or specific event (for example `attribute:src:imageBlock`).
  *
- * @eventName attribute
+ * @eventName ~DowncastDispatcher#attribute
  * @param {Object} data Additional information about the change.
  * @param {module:engine/model/item~Item|module:engine/model/documentselection~DocumentSelection} data.item Changed item
  * or converted selection.
@@ -427,7 +427,7 @@ export type DowncastAttributeEvent<TItem = Item | Selection | DocumentSelection>
 /**
  * Fired for {@link module:engine/model/selection~Selection selection} changes.
  *
- * @eventName selection
+ * @eventName ~DowncastDispatcher#selection
  * @param {module:engine/model/selection~Selection} selection Selection that is converted.
  * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface
  * to be used by callback, passed in `DowncastDispatcher` constructor.
@@ -456,7 +456,7 @@ export type DowncastSelectionEvent = DowncastEvent<'selection'>;
  * * there is only one event,
  * * `conversionApi.consumable` includes the selection instance with the event name.
  *
- * @eventName addMarker
+ * @eventName ~DowncastDispatcher#addMarker
  * @param {Object} data Additional information about the change.
  * @param {module:engine/model/item~Item|module:engine/model/selection~Selection} data.item Item inside the new marker or
  * the selection that is being converted.
@@ -476,7 +476,7 @@ export type DowncastAddMarkerEvent = DowncastEvent<'addMarker'>;
  * if markers are named `foo:abc`, `foo:bar`, then it is possible to listen to `removeMarker:foo` or `removeMarker:foo:abc` and
  * `removeMarker:foo:bar` events.
  *
- * @eventName removeMarker
+ * @eventName ~DowncastDispatcher#removeMarker
  * @param {Object} data Additional information about the change.
  * @param {module:engine/model/range~Range} data.markerRange Marker range.
  * @param {String} data.markerName Marker name.

package/src/conversion/mapper.d.ts

@@ -151,6 +151,7 @@ export default class Mapper extends Mapper_base {
      *
      * **Note:** {@link module:engine/view/uielement~UIElement} does not have corresponding element in model.
      *
+     * @label ELEMENT
      * @param viewElement View element.
      * @returns Corresponding model element or `undefined` if not found.
      */
@@ -158,6 +159,7 @@ export default class Mapper extends Mapper_base {
     /**
      * Gets the corresponding model document fragment.
      *
+     * @label DOCUMENT_FRAGMENT
      * @param viewDocumentFragment View document fragment.
      * @returns Corresponding model document fragment or `undefined` if not found.
      */
@@ -165,6 +167,7 @@ export default class Mapper extends Mapper_base {
     /**
      * Gets the corresponding view element.
      *
+     * @label ELEMENT
      * @param modelElement Model element.
      * @returns Corresponding view element or `undefined` if not found.
      */
@@ -172,6 +175,7 @@ export default class Mapper extends Mapper_base {
     /**
      * Gets the corresponding view document fragment.
      *
+     * @label DOCUMENT_FRAGMENT
      * @param modelDocumentFragment Model document fragment.
      * @returns Corresponding view document fragment or `undefined` if not found.
      */
@@ -412,7 +416,7 @@ export default class Mapper extends Mapper_base {
  * mapping between the given model and view elements is unsolvable by using just elements mapping and default algorithm.
  * Also, the condition that checks if a special case scenario happened should be as simple as possible.
  *
- * @eventName modelToViewPosition
+ * @eventName ~Mapper#modelToViewPosition
  */
 export type MapperModelToViewPositionEvent = {
     name: 'modelToViewPosition';
@@ -471,7 +475,7 @@ export type MapperModelToViewPositionEventData = {
  * mapping between the given model and view elements is unsolvable by using just elements mapping and default algorithm.
  * Also, the condition that checks if special case scenario happened should be as simple as possible.
  *
- * @eventName viewToModelPosition
+ * @eventName ~Mapper#viewToModelPosition
  */
 export type MapperViewToModelPositionEvent = {
     name: 'viewToModelPosition';

package/src/conversion/upcastdispatcher.d.ts

@@ -213,7 +213,7 @@ export default class UpcastDispatcher extends UpcastDispatcher_base {
 /**
  * Fired before the first conversion event, at the beginning of the upcast (view-to-model conversion) process.
  *
- * @eventName viewCleanup
+ * @eventName ~UpcastDispatcher#viewCleanup
  * @param viewItem A part of the view to be converted.
  */
 export type UpcastViewCleanupEvent = {
@@ -230,7 +230,7 @@ type UpcastEvent<TName extends string, TItem extends ViewItem | ViewDocumentFrag
  * **Note:** Keep in mind that this object is shared by reference between all conversion callbacks that will be called.
  * This means that callbacks can override values if needed, and these values will be available in other callbacks.
  */
-export type UpcastConversionData<TItem extends ViewItem | ViewDocumentFragment = ViewItem | ViewDocumentFragment> = {
+export interface UpcastConversionData<TItem extends ViewItem | ViewDocumentFragment = ViewItem | ViewDocumentFragment> {
     /**
      * The converted item.
      */
@@ -245,7 +245,7 @@ export type UpcastConversionData<TItem extends ViewItem | ViewDocumentFragment =
      * the converted element should be reflected by setting or modifying this property.
      */
     modelRange: ModelRange | null;
-};
+}
 /**
  * Fired when an {@link module:engine/view/element~Element} is converted.
  *
@@ -253,7 +253,7 @@ export type UpcastConversionData<TItem extends ViewItem | ViewDocumentFragment =
  * `element:<elementName>` where `elementName` is the name of the converted element. This way listeners may listen to
  * a conversion of all or just specific elements.
  *
- * @eventName element
+ * @eventName ~UpcastDispatcher#element
  * @param data The conversion data. Keep in mind that this object is shared by reference between all callbacks
  * that will be called. This means that callbacks can override values if needed, and these values
  * will be available in other callbacks.
@@ -263,15 +263,15 @@ export type UpcastElementEvent = UpcastEvent<'element', ViewElement>;
 /**
  * Fired when a {@link module:engine/view/text~Text} is converted.
  *
- * @eventName text
- * @see #event:element
+ * @eventName ~UpcastDispatcher#text
+ * @see ~UpcastDispatcher#event:element
  */
 export type UpcastTextEvent = UpcastEvent<'text', ViewText>;
 /**
  * Fired when a {@link module:engine/view/documentfragment~DocumentFragment} is converted.
  *
- * @eventName documentFragment
- * @see #event:element
+ * @eventName ~UpcastDispatcher#documentFragment
+ * @see ~UpcastDispatcher#event:element
  */
 export type UpcastDocumentFragmentEvent = UpcastEvent<'documentFragment', ViewDocumentFragment>;
 /**

package/src/conversion/viewconsumable.d.ts

@@ -40,7 +40,49 @@ export default class ViewConsumable {
      * {@link module:engine/view/documentfragment~DocumentFragment document fragments} boolean value is stored as value.
      */
     private _consumables;
-    add(element: Text | DocumentFragment): void;
+    /**
+     * Adds {@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.
+     * ```
+     *
+     * 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.
+     * ```
+     *
+     * 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;
     /**
      * Tests if {@link module:engine/view/element~Element view element}, {@link module:engine/view/text~Text text node} or
@@ -175,3 +217,153 @@ export interface Consumables {
      */
     styles?: string | Array<string>;
 }
+/**
+ * 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}.
+ */
+export declare class ViewElementConsumables {
+    readonly element: Node | DocumentFragment;
+    /**
+     * Flag indicating if name of the element can be consumed.
+     */
+    private _canConsumeName;
+    /**
+     * Contains maps of element's consumables: attributes, classes and styles.
+     */
+    private readonly _consumables;
+    /**
+     * Creates ViewElementConsumables instance.
+     *
+     * @param from View node or document fragment from which `ViewElementConsumables` is being created.
+     */
+    constructor(from: Node | DocumentFragment);
+    /**
+     * 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
+     * styles still could be consumed):
+     *
+     * ```ts
+     * consumables.add( { name: true } );
+     * ```
+     *
+     * Attributes classes and styles:
+     *
+     * ```ts
+     * consumables.add( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.add( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```
+     *
+     * 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;
+    /**
+     * Tests if parts of the {@link module:engine/view/node~Node view node} can be consumed.
+     *
+     * Element's name can be tested:
+     *
+     * ```ts
+     * consumables.test( { name: true } );
+     * ```
+     *
+     * Attributes classes and styles:
+     *
+     * ```ts
+     * consumables.test( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.test( { attributes: [ 'title', 'name' ], classes: [ 'foo', '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;
+    /**
+     * 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.
+     * Element's name can be consumed:
+     *
+     * ```ts
+     * consumables.consume( { name: true } );
+     * ```
+     *
+     * Attributes classes and styles:
+     *
+     * ```ts
+     * consumables.consume( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.consume( { attributes: [ 'title', 'name' ], classes: [ 'foo', '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.
+     */
+    consume(consumables: Consumables | Match): void;
+    /**
+     * 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:
+     *
+     * ```ts
+     * consumables.revert( { name: true } );
+     * ```
+     *
+     * Attributes classes and styles:
+     *
+     * ```ts
+     * consumables.revert( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.revert( { attributes: [ 'title', 'name' ], classes: [ 'foo', '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;
+}

package/src/conversion/viewconsumable.js

@@ -42,35 +42,6 @@ export default class ViewConsumable {
          */
         this._consumables = new Map();
     }
-    /**
-     * Adds {@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} 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.
@@ -286,7 +257,7 @@ 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}.
  */
-class ViewElementConsumables {
+export class ViewElementConsumables {
     /**
      * Creates ViewElementConsumables instance.
      *