@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

package/src/conversion/viewconsumable.js

@@ -17,61 +17,31 @@ import { isArray } from 'lodash-es';
  * To consume items use {@link module:engine/conversion/viewconsumable~ViewConsumable#consume consume method}.
  * To revert already consumed items use {@link module:engine/conversion/viewconsumable~ViewConsumable#revert revert method}.
  *
- *		viewConsumable.add( element, { name: true } ); // Adds element's name as ready to be consumed.
- *		viewConsumable.add( textNode ); // Adds text node for consumption.
- *		viewConsumable.add( docFragment ); // Adds document fragment for consumption.
- *		viewConsumable.test( element, { name: true }  ); // Tests if element's name can be consumed.
- *		viewConsumable.test( textNode ); // Tests if text node can be consumed.
- *		viewConsumable.test( docFragment ); // Tests if document fragment can be consumed.
- *		viewConsumable.consume( element, { name: true }  ); // Consume element's name.
- *		viewConsumable.consume( textNode ); // Consume text node.
- *		viewConsumable.consume( docFragment ); // Consume document fragment.
- *		viewConsumable.revert( element, { name: true }  ); // Revert already consumed element's name.
- *		viewConsumable.revert( textNode ); // Revert already consumed text node.
- *		viewConsumable.revert( docFragment ); // Revert already consumed document fragment.
+ * ```ts
+ * viewConsumable.add( element, { name: true } ); // Adds element's name as ready to be consumed.
+ * viewConsumable.add( textNode ); // Adds text node for consumption.
+ * viewConsumable.add( docFragment ); // Adds document fragment for consumption.
+ * viewConsumable.test( element, { name: true }  ); // Tests if element's name can be consumed.
+ * viewConsumable.test( textNode ); // Tests if text node can be consumed.
+ * viewConsumable.test( docFragment ); // Tests if document fragment can be consumed.
+ * viewConsumable.consume( element, { name: true }  ); // Consume element's name.
+ * viewConsumable.consume( textNode ); // Consume text node.
+ * viewConsumable.consume( docFragment ); // Consume document fragment.
+ * viewConsumable.revert( element, { name: true }  ); // Revert already consumed element's name.
+ * viewConsumable.revert( textNode ); // Revert already consumed text node.
+ * viewConsumable.revert( docFragment ); // Revert already consumed document fragment.
+ * ```
  */
 export default class ViewConsumable {
-    /**
-     * Creates new ViewConsumable.
-     */
     constructor() {
         /**
          * Map of consumable elements. If {@link module:engine/view/element~Element element} is used as a key,
          * {@link module:engine/conversion/viewconsumable~ViewElementConsumables ViewElementConsumables} instance is stored as value.
          * For {@link module:engine/view/text~Text text nodes} and
          * {@link module:engine/view/documentfragment~DocumentFragment document fragments} boolean value is stored as value.
-         *
-         * @protected
-         * @member {Map.<module:engine/conversion/viewconsumable~ViewElementConsumables|Boolean>}
-        */
+         */
         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.
-     *
-     *		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.
-     *
-     *		viewConsumable.add( p, { attributes: 'style' } ); // This call will throw an exception.
-     *		viewConsumable.add( p, { styles: 'color' } ); // This is properly handled style.
-     *
-     * @param {module:engine/view/element~Element|module:engine/view/text~Text|module:engine/view/documentfragment~DocumentFragment} element
-     * @param {Object} [consumables] Used only if first parameter is {@link module:engine/view/element~Element view element} instance.
-     * @param {Boolean} consumables.name If set to true element's name will be included.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names.
-     * @param {String|Array.<String>} 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.
@@ -95,27 +65,30 @@ export default class ViewConsumable {
      * It returns `true` when all items included in method's call can be consumed. Returns `false` when
      * first already consumed item is found and `null` when first non-consumable item is found.
      *
-     *		viewConsumable.test( p, { name: true } ); // Tests element's name.
-     *		viewConsumable.test( p, { attributes: 'name' } ); // Tests attribute.
-     *		viewConsumable.test( p, { classes: 'foobar' } ); // Tests class.
-     *		viewConsumable.test( p, { styles: 'color' } ); // Tests style.
-     *		viewConsumable.test( p, { attributes: 'name', styles: 'color' } ); // Tests attribute and style.
-     *		viewConsumable.test( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be tested.
-     *		viewConsumable.test( textNode ); // Tests text node.
-     *		viewConsumable.test( docFragment ); // Tests document fragment.
+     * ```ts
+     * viewConsumable.test( p, { name: true } ); // Tests element's name.
+     * viewConsumable.test( p, { attributes: 'name' } ); // Tests attribute.
+     * viewConsumable.test( p, { classes: 'foobar' } ); // Tests class.
+     * viewConsumable.test( p, { styles: 'color' } ); // Tests style.
+     * viewConsumable.test( p, { attributes: 'name', styles: 'color' } ); // Tests attribute and style.
+     * viewConsumable.test( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be tested.
+     * viewConsumable.test( textNode ); // Tests text node.
+     * viewConsumable.test( docFragment ); // Tests document fragment.
+     * ```
      *
      * Testing classes and styles as attribute will test if all added classes/styles can be consumed.
      *
-     *		viewConsumable.test( p, { attributes: 'class' } ); // Tests if all added classes can be consumed.
-     *		viewConsumable.test( p, { attributes: 'style' } ); // Tests if all added styles can be consumed.
-     *
-     * @param {module:engine/view/element~Element|module:engine/view/text~Text|module:engine/view/documentfragment~DocumentFragment} element
-     * @param {Object} [consumables] Used only if first parameter is {@link module:engine/view/element~Element view element} instance.
-     * @param {Boolean} consumables.name If set to true element's name will be included.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names.
-     * @returns {Boolean|null} Returns `true` when all items included in method's call can be consumed. Returns `false`
+     * ```ts
+     * viewConsumable.test( p, { attributes: 'class' } ); // Tests if all added classes can be consumed.
+     * viewConsumable.test( p, { attributes: 'style' } ); // Tests if all added styles can be consumed.
+     * ```
+     *
+     * @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.
+     * @returns Returns `true` when all items included in method's call can be consumed. Returns `false`
      * when first already consumed item is found and `null` when first non-consumable item is found.
      */
     test(element, consumables) {
@@ -135,27 +108,30 @@ export default class ViewConsumable {
      * {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
      * It returns `true` when all items included in method's call can be consumed, otherwise returns `false`.
      *
-     *		viewConsumable.consume( p, { name: true } ); // Consumes element's name.
-     *		viewConsumable.consume( p, { attributes: 'name' } ); // Consumes element's attribute.
-     *		viewConsumable.consume( p, { classes: 'foobar' } ); // Consumes element's class.
-     *		viewConsumable.consume( p, { styles: 'color' } ); // Consumes element's style.
-     *		viewConsumable.consume( p, { attributes: 'name', styles: 'color' } ); // Consumes attribute and style.
-     *		viewConsumable.consume( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be consumed.
-     *		viewConsumable.consume( textNode ); // Consumes text node.
-     *		viewConsumable.consume( docFragment ); // Consumes document fragment.
+     * ```ts
+     * viewConsumable.consume( p, { name: true } ); // Consumes element's name.
+     * viewConsumable.consume( p, { attributes: 'name' } ); // Consumes element's attribute.
+     * viewConsumable.consume( p, { classes: 'foobar' } ); // Consumes element's class.
+     * viewConsumable.consume( p, { styles: 'color' } ); // Consumes element's style.
+     * viewConsumable.consume( p, { attributes: 'name', styles: 'color' } ); // Consumes attribute and style.
+     * viewConsumable.consume( p, { classes: [ 'baz', 'bar' ] } ); // Multiple consumables can be consumed.
+     * viewConsumable.consume( textNode ); // Consumes text node.
+     * viewConsumable.consume( docFragment ); // Consumes document fragment.
+     * ```
      *
      * Consuming classes and styles as attribute will test if all added classes/styles can be consumed.
      *
-     *		viewConsumable.consume( p, { attributes: 'class' } ); // Consume only if all added classes can be consumed.
-     *		viewConsumable.consume( p, { attributes: 'style' } ); // Consume only if all added styles can be consumed.
-     *
-     * @param {module:engine/view/element~Element|module:engine/view/text~Text|module:engine/view/documentfragment~DocumentFragment} element
-     * @param {Object} [consumables] Used only if first parameter is {@link module:engine/view/element~Element view element} instance.
-     * @param {Boolean} consumables.name If set to true element's name will be included.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names.
-     * @returns {Boolean} Returns `true` when all items included in method's call can be consumed,
+     * ```ts
+     * viewConsumable.consume( p, { attributes: 'class' } ); // Consume only if all added classes can be consumed.
+     * viewConsumable.consume( p, { attributes: 'style' } ); // Consume only if all added styles can be consumed.
+     * ```
+     *
+     * @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.
+     * @returns Returns `true` when all items included in method's call can be consumed,
      * otherwise returns `false`.
      */
     consume(element, consumables) {
@@ -178,27 +154,30 @@ export default class ViewConsumable {
      * Method does not revert items that were never previously added for consumption, even if they are included in
      * method's call.
      *
-     *		viewConsumable.revert( p, { name: true } ); // Reverts element's name.
-     *		viewConsumable.revert( p, { attributes: 'name' } ); // Reverts element's attribute.
-     *		viewConsumable.revert( p, { classes: 'foobar' } ); // Reverts element's class.
-     *		viewConsumable.revert( p, { styles: 'color' } ); // Reverts element's style.
-     *		viewConsumable.revert( p, { attributes: 'name', styles: 'color' } ); // Reverts attribute and style.
-     *		viewConsumable.revert( p, { classes: [ 'baz', 'bar' ] } ); // Multiple names can be reverted.
-     *		viewConsumable.revert( textNode ); // Reverts text node.
-     *		viewConsumable.revert( docFragment ); // Reverts document fragment.
+     * ```ts
+     * viewConsumable.revert( p, { name: true } ); // Reverts element's name.
+     * viewConsumable.revert( p, { attributes: 'name' } ); // Reverts element's attribute.
+     * viewConsumable.revert( p, { classes: 'foobar' } ); // Reverts element's class.
+     * viewConsumable.revert( p, { styles: 'color' } ); // Reverts element's style.
+     * viewConsumable.revert( p, { attributes: 'name', styles: 'color' } ); // Reverts attribute and style.
+     * viewConsumable.revert( p, { classes: [ 'baz', 'bar' ] } ); // Multiple names can be reverted.
+     * viewConsumable.revert( textNode ); // Reverts text node.
+     * viewConsumable.revert( docFragment ); // Reverts document fragment.
+     * ```
      *
      * Reverting classes and styles as attribute will revert all classes/styles that were previously added for
      * consumption.
      *
-     *		viewConsumable.revert( p, { attributes: 'class' } ); // Reverts all classes added for consumption.
-     *		viewConsumable.revert( p, { attributes: 'style' } ); // Reverts all styles added for consumption.
+     * ```ts
+     * viewConsumable.revert( p, { attributes: 'class' } ); // Reverts all classes added for consumption.
+     * viewConsumable.revert( p, { attributes: 'style' } ); // Reverts all styles added for consumption.
+     * ```
      *
-     * @param {module:engine/view/element~Element|module:engine/view/text~Text|module:engine/view/documentfragment~DocumentFragment} element
-     * @param {Object} [consumables] Used only if first parameter is {@link module:engine/view/element~Element view element} instance.
-     * @param {Boolean} consumables.name If set to true element's name will be included.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names.
+     * @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.
      */
     revert(element, consumables) {
         const elementConsumables = this._consumables.get(element);
@@ -216,10 +195,6 @@ export default class ViewConsumable {
     /**
      * 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
-     * @param {module:engine/view/element~Element} element
-     * @returns {Object} consumables
      */
     static consumablesFromElement(element) {
         const consumables = {
@@ -252,10 +227,8 @@ export default class ViewConsumable {
      * {@link module:engine/view/node~Node node} or {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
      * Instance will contain all elements, child nodes, attributes, styles and classes added for consumption.
      *
-     * @static
-     * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} from View node or document fragment
-     * from which `ViewConsumable` will be created.
-     * @param {module:engine/conversion/viewconsumable~ViewConsumable} [instance] If provided, given `ViewConsumable` instance will be used
+     * @param from View node or document fragment from which `ViewConsumable` will be created.
+     * @param instance If provided, given `ViewConsumable` instance will be used
      * to add all consumables. It will be returned instead of a new instance.
      */
     static createFrom(from, instance) {
@@ -283,35 +256,16 @@ 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}.
- *
- * @private
  */
-class ViewElementConsumables {
+export class ViewElementConsumables {
     /**
      * Creates ViewElementConsumables instance.
      *
-     * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} from View node or document fragment
-     * from which `ViewElementConsumables` is being created.
+     * @param from View node or document fragment from which `ViewElementConsumables` is being created.
      */
     constructor(from) {
-        /**
-         * @readonly
-         * @member {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment}
-         */
         this.element = from;
-        /**
-         * Flag indicating if name of the element can be consumed.
-         *
-         * @private
-         * @member {Boolean}
-         */
         this._canConsumeName = null;
-        /**
-         * Contains maps of element's consumables: attributes, classes and styles.
-         *
-         * @private
-         * @member {Object}
-         */
         this._consumables = {
             attributes: new Map(),
             styles: new Map(),
@@ -323,21 +277,25 @@ class ViewElementConsumables {
      * 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):
      *
-     *		consumables.add( { name: true } );
+     * ```ts
+     * consumables.add( { name: true } );
+     * ```
      *
      * Attributes classes and styles:
      *
-     *		consumables.add( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     *		consumables.add( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```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 {Object} consumables Object describing which parts of the element can be consumed.
-     * @param {Boolean} consumables.name If set to `true` element's name will be added as consumable.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names to add as consumable.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names to add as consumable.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names to add as consumable.
+     * @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) {
@@ -354,19 +312,23 @@ class ViewElementConsumables {
      *
      * Element's name can be tested:
      *
-     *		consumables.test( { name: true } );
+     * ```ts
+     * consumables.test( { name: true } );
+     * ```
      *
      * Attributes classes and styles:
      *
-     *		consumables.test( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     *		consumables.test( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
-     *
-     * @param {Object} consumables Object describing which parts of the element should be tested.
-     * @param {Boolean} consumables.name If set to `true` element's name will be tested.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names to test.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names to test.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names to test.
-     * @returns {Boolean|null} `true` when all tested items can be consumed, `null` when even one of the items
+     * ```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) {
@@ -390,18 +352,22 @@ class ViewElementConsumables {
      * is already consumed - it consumes all consumable items provided.
      * Element's name can be consumed:
      *
-     *		consumables.consume( { name: true } );
+     * ```ts
+     * consumables.consume( { name: true } );
+     * ```
      *
      * Attributes classes and styles:
      *
-     *		consumables.consume( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     *		consumables.consume( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```ts
+     * consumables.consume( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.consume( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```
      *
-     * @param {Object} consumables Object describing which parts of the element should be consumed.
-     * @param {Boolean} consumables.name If set to `true` element's name will be consumed.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names to consume.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names to consume.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names to consume.
+     * @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) {
         if (consumables.name) {
@@ -417,18 +383,22 @@ class ViewElementConsumables {
      * 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:
      *
-     *		consumables.revert( { name: true } );
+     * ```ts
+     * consumables.revert( { name: true } );
+     * ```
      *
      * Attributes classes and styles:
      *
-     *		consumables.revert( { attributes: 'title', classes: 'foo', styles: 'color' } );
-     *		consumables.revert( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```ts
+     * consumables.revert( { attributes: 'title', classes: 'foo', styles: 'color' } );
+     * consumables.revert( { attributes: [ 'title', 'name' ], classes: [ 'foo', 'bar' ] );
+     * ```
      *
-     * @param {Object} consumables Object describing which parts of the element should be reverted.
-     * @param {Boolean} consumables.name If set to `true` element's name will be reverted.
-     * @param {String|Array.<String>} consumables.attributes Attribute name or array of attribute names to revert.
-     * @param {String|Array.<String>} consumables.classes Class name or array of class names to revert.
-     * @param {String|Array.<String>} consumables.styles Style name or array of style names to revert.
+     * @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) {
@@ -446,9 +416,8 @@ class ViewElementConsumables {
      * 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.
      *
-     * @private
-     * @param {String} type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param {String|Array.<String>} item Consumable item or array of items.
+     * @param type Type of the consumable item: `attributes`, `classes` or `styles`.
+     * @param item Consumable item or array of items.
      */
     _add(type, item) {
         const items = isArray(item) ? item : [item];
@@ -482,10 +451,9 @@ class ViewElementConsumables {
     /**
      * Helper method that tests consumables of a given type: attribute, class or style.
      *
-     * @private
-     * @param {String} type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param {String|Array.<String>} item Consumable item or array of items.
-     * @returns {Boolean|null} Returns `true` if all items can be consumed, `null` when one of the items cannot be
+     * @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) {
@@ -516,9 +484,8 @@ class ViewElementConsumables {
     /**
      * Helper method that consumes items of a given type: attribute, class or style.
      *
-     * @private
-     * @param {String} type Type of the consumable item: `attributes`, `classes` or `styles`.
-     * @param {String|Array.<String>} item Consumable item or array of items.
+     * @param type Type of the consumable item: `attributes`, `classes` or `styles`.
+     * @param item Consumable item or array of items.
      */
     _consume(type, item) {
         const items = isArray(item) ? item : [item];
@@ -542,9 +509,8 @@ class ViewElementConsumables {
     /**
      * Helper method that reverts items of a given type: attribute, class or style.
      *
-     * @private
-     * @param {String} type Type of the consumable item: `attributes`, `classes` or , `styles`.
-     * @param {String|Array.<String>} item Consumable item or array of items.
+     * @param type Type of the consumable item: `attributes`, `classes` or , `styles`.
+     * @param item Consumable item or array of items.
      */
     _revert(type, item) {
         const items = isArray(item) ? item : [item];

package/src/dataprocessor/basichtmlwriter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/dataprocessor/basichtmlwriter
+ */
+import type HtmlWriter from './htmlwriter';
+/**
+ * Basic HTML writer. It uses the native `innerHTML` property for basic conversion
+ * from a document fragment to an HTML string.
+ */
+export default class BasicHtmlWriter implements HtmlWriter {
+    /**
+     * Returns an HTML string created from the document fragment.
+     */
+    getHtml(fragment: DocumentFragment): string;
+}

package/src/dataprocessor/basichtmlwriter.js

@@ -2,22 +2,13 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-/**
- * @module engine/dataprocessor/basichtmlwriter
- */
-/* globals document */
 /**
  * Basic HTML writer. It uses the native `innerHTML` property for basic conversion
  * from a document fragment to an HTML string.
- *
- * @implements module:engine/dataprocessor/htmlwriter~HtmlWriter
  */
 export default class BasicHtmlWriter {
     /**
      * Returns an HTML string created from the document fragment.
-     *
-     * @param {DocumentFragment} fragment
-     * @returns {String}
      */
     getHtml(fragment) {
         const doc = document.implementation.createHTMLDocument('');

package/src/dataprocessor/dataprocessor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/dataprocessor/dataprocessor
+ */
+import type ViewDocumentFragment from '../view/documentfragment';
+import type { MatcherPattern } from '../view/matcher';
+/**
+ * The data processor interface. It should be implemented by actual data processors.
+ *
+ * Each data processor implements a certain format of the data. For example, {@glink features/markdown Markdown data processor}
+ * will convert the data (a Markdown string) to a {@link module:engine/view/documentfragment~DocumentFragment document fragment} and back.
+ *
+ * **Note:** While the CKEditor 5 architecture supports changing the data format, in most scenarios we do recommend sticking to
+ * the default format which is HTML (supported by the {@link module:engine/dataprocessor/htmldataprocessor~HtmlDataProcessor}).
+ * HTML remains [the best standard for rich-text data](https://medium.com/content-uneditable/a-standard-for-rich-text-data-4b3a507af552).
+ *
+ * And please do remember – using Markdown [does not automatically make your
+ * application/website secure](https://github.com/ckeditor/ckeditor5-markdown-gfm/issues/16#issuecomment-375752994).
+ */
+export default interface DataProcessor {
+    /**
+     * Converts a {@link module:engine/view/documentfragment~DocumentFragment document fragment} to data.
+     *
+     * @param viewFragment The document fragment to be processed.
+     */
+    toData(viewFragment: ViewDocumentFragment): string;
+    /**
+     * Converts the data to a {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
+     *
+     * @param data The data to be processed.
+     */
+    toView(data: string): ViewDocumentFragment;
+    /**
+     * Registers a {@link module:engine/view/matcher~MatcherPattern} for view elements whose content should be treated as raw data
+     * and its content should be converted to a
+     * {@link module:engine/view/element~Element#getCustomProperty custom property of a view element} called `"$rawContent"` while
+     * converting {@link #toView to view}.
+     *
+     * @param pattern Pattern matching all view elements whose content should be treated as plain text.
+     */
+    registerRawContentMatcher(pattern: MatcherPattern): void;
+    /**
+     * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+     * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
+     *
+     * This mode allows for more precise handling of block fillers (so they do not leak into the editor content) but bloats the
+     * editor data with additional markup.
+     *
+     * This mode may be required by some features and will be turned on by them automatically.
+     *
+     * @param type Whether to use the default or marked `&nbsp;` block fillers.
+     */
+    useFillerType(type: 'default' | 'marked'): void;
+    /**
+     * If `false`, comment nodes will be converted to `$comment`. Otherwise comment nodes are ignored.
+     */
+    skipComments?: boolean;
+}