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

package/src/conversion/modelconsumable.js

@@ -36,65 +36,61 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  *
  * Consuming multiple values in a single callback:
  *
- *		// Converter for custom `imageBlock` element that might have a `caption` element inside which changes
- *		// how the image is displayed in the view:
- *		//
- *		// Model:
- *		//
- *		// [imageBlock]
- *		//   └─ [caption]
- *		//       └─ foo
- *		//
- *		// View:
- *		//
- *		// <figure>
- *		//   ├─ <img />
- *		//   └─ <caption>
- *		//       └─ foo
- *		modelConversionDispatcher.on( 'insert:imageBlock', ( evt, data, conversionApi ) => {
- *			// First, consume the `imageBlock` element.
- *			conversionApi.consumable.consume( data.item, 'insert' );
+ * ```ts
+ * // Converter for custom `imageBlock` element that might have a `caption` element inside which changes
+ * // how the image is displayed in the view:
+ * //
+ * // Model:
+ * //
+ * // [imageBlock]
+ * //   └─ [caption]
+ * //       └─ foo
+ * //
+ * // View:
+ * //
+ * // <figure>
+ * //   ├─ <img />
+ * //   └─ <caption>
+ * //       └─ foo
+ * modelConversionDispatcher.on( 'insert:imageBlock', ( evt, data, conversionApi ) => {
+ * 	// First, consume the `imageBlock` element.
+ * 	conversionApi.consumable.consume( data.item, 'insert' );
  *
- *			// Just create normal image element for the view.
- *			// Maybe it will be "decorated" later.
- *			const viewImage = new ViewElement( 'img' );
- *			const insertPosition = conversionApi.mapper.toViewPosition( data.range.start );
- *			const viewWriter = conversionApi.writer;
+ * 	// Just create normal image element for the view.
+ * 	// Maybe it will be "decorated" later.
+ * 	const viewImage = new ViewElement( 'img' );
+ * 	const insertPosition = conversionApi.mapper.toViewPosition( data.range.start );
+ * 	const viewWriter = conversionApi.writer;
  *
- *			// Check if the `imageBlock` element has children.
- *			if ( data.item.childCount > 0 ) {
- *				const modelCaption = data.item.getChild( 0 );
+ * 	// Check if the `imageBlock` element has children.
+ * 	if ( data.item.childCount > 0 ) {
+ * 		const modelCaption = data.item.getChild( 0 );
  *
- *				// `modelCaption` insertion change is consumed from consumable values.
- *				// It will not be converted by other converters, but it's children (probably some text) will be.
- *				// Through mapping, converters for text will know where to insert contents of `modelCaption`.
- *				if ( conversionApi.consumable.consume( modelCaption, 'insert' ) ) {
- *					const viewCaption = new ViewElement( 'figcaption' );
+ * 		// `modelCaption` insertion change is consumed from consumable values.
+ * 		// It will not be converted by other converters, but it's children (probably some text) will be.
+ * 		// Through mapping, converters for text will know where to insert contents of `modelCaption`.
+ * 		if ( conversionApi.consumable.consume( modelCaption, 'insert' ) ) {
+ * 			const viewCaption = new ViewElement( 'figcaption' );
  *
- *					const viewImageHolder = new ViewElement( 'figure', null, [ viewImage, viewCaption ] );
+ * 			const viewImageHolder = new ViewElement( 'figure', null, [ viewImage, viewCaption ] );
  *
- *					conversionApi.mapper.bindElements( modelCaption, viewCaption );
- *					conversionApi.mapper.bindElements( data.item, viewImageHolder );
- *					viewWriter.insert( insertPosition, viewImageHolder );
- *				}
- *			} else {
- *				conversionApi.mapper.bindElements( data.item, viewImage );
- *				viewWriter.insert( insertPosition, viewImage );
- *			}
+ * 			conversionApi.mapper.bindElements( modelCaption, viewCaption );
+ * 			conversionApi.mapper.bindElements( data.item, viewImageHolder );
+ * 			viewWriter.insert( insertPosition, viewImageHolder );
+ * 		}
+ * 	} else {
+ * 		conversionApi.mapper.bindElements( data.item, viewImage );
+ * 		viewWriter.insert( insertPosition, viewImage );
+ * 	}
  *
- *			evt.stop();
- *		} );
+ * 	evt.stop();
+ * } );
+ * ```
  */
 export default class ModelConsumable {
-    /**
-     * Creates an empty consumables list.
-     */
     constructor() {
         /**
          * Contains list of consumable values.
-         *
-         * @private
-         * @member {Map} module:engine/conversion/modelconsumable~ModelConsumable#_consumable
          */
         this._consumable = new Map();
         /**
@@ -104,24 +100,22 @@ export default class ModelConsumable {
          * is given a unique `Symbol` which is then registered as consumable. This process is transparent for the `ModelConsumable`
          * API user because whenever `TextProxy` is added, tested, consumed or reverted, the internal mechanisms of
          * `ModelConsumable` translate `TextProxy` to that unique `Symbol`.
-         *
-         * @private
-         * @member {Map} module:engine/conversion/modelconsumable~ModelConsumable#_textProxyRegistry
          */
         this._textProxyRegistry = new Map();
     }
     /**
      * Adds a consumable value to the consumables list and links it with a given model item.
      *
-     *		modelConsumable.add( modelElement, 'insert' ); // Add `modelElement` insertion change to consumable values.
-     *		modelConsumable.add( modelElement, 'addAttribute:bold' ); // Add `bold` attribute insertion on `modelElement` change.
-     *		modelConsumable.add( modelElement, 'removeAttribute:bold' ); // Add `bold` attribute removal on `modelElement` change.
-     *		modelConsumable.add( modelSelection, 'selection' ); // Add `modelSelection` to consumable values.
-     *		modelConsumable.add( modelRange, 'range' ); // Add `modelRange` to consumable values.
+     * ```ts
+     * modelConsumable.add( modelElement, 'insert' ); // Add `modelElement` insertion change to consumable values.
+     * modelConsumable.add( modelElement, 'addAttribute:bold' ); // Add `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.add( modelElement, 'removeAttribute:bold' ); // Add `bold` attribute removal on `modelElement` change.
+     * modelConsumable.add( modelSelection, 'selection' ); // Add `modelSelection` to consumable values.
+     * modelConsumable.add( modelRange, 'range' ); // Add `modelRange` to consumable values.
+     * ```
      *
-     * @param {module:engine/model/item~Item|module:engine/model/selection~Selection|module:engine/model/range~Range} item
-     * Model item, range or selection that has the consumable.
-     * @param {String} type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * @param item Model item, range or selection that has the consumable.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
      * Second colon and everything after will be cut. Passing event name is a safe and good practice.
      */
     add(item, type) {
@@ -137,17 +131,18 @@ export default class ModelConsumable {
     /**
      * Removes a given consumable value from a given model item.
      *
-     *		modelConsumable.consume( modelElement, 'insert' ); // Remove `modelElement` insertion change from consumable values.
-     *		modelConsumable.consume( modelElement, 'addAttribute:bold' ); // Remove `bold` attribute insertion on `modelElement` change.
-     *		modelConsumable.consume( modelElement, 'removeAttribute:bold' ); // Remove `bold` attribute removal on `modelElement` change.
-     *		modelConsumable.consume( modelSelection, 'selection' ); // Remove `modelSelection` from consumable values.
-     *		modelConsumable.consume( modelRange, 'range' ); // Remove 'modelRange' from consumable values.
+     * ```ts
+     * modelConsumable.consume( modelElement, 'insert' ); // Remove `modelElement` insertion change from consumable values.
+     * modelConsumable.consume( modelElement, 'addAttribute:bold' ); // Remove `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.consume( modelElement, 'removeAttribute:bold' ); // Remove `bold` attribute removal on `modelElement` change.
+     * modelConsumable.consume( modelSelection, 'selection' ); // Remove `modelSelection` from consumable values.
+     * modelConsumable.consume( modelRange, 'range' ); // Remove 'modelRange' from consumable values.
+     * ```
      *
-     * @param {module:engine/model/item~Item|module:engine/model/selection~Selection|module:engine/model/range~Range} item
-     * Model item, range or selection from which consumable will be consumed.
-     * @param {String} type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * @param item Model item, range or selection from which consumable will be consumed.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
      * Second colon and everything after will be cut. Passing event name is a safe and good practice.
-     * @returns {Boolean} `true` if consumable value was available and was consumed, `false` otherwise.
+     * @returns `true` if consumable value was available and was consumed, `false` otherwise.
      */
     consume(item, type) {
         type = _normalizeConsumableType(type);
@@ -165,17 +160,18 @@ export default class ModelConsumable {
     /**
      * Tests whether there is a consumable value of a given type connected with a given model item.
      *
-     *		modelConsumable.test( modelElement, 'insert' ); // Check for `modelElement` insertion change.
-     *		modelConsumable.test( modelElement, 'addAttribute:bold' ); // Check for `bold` attribute insertion on `modelElement` change.
-     *		modelConsumable.test( modelElement, 'removeAttribute:bold' ); // Check for `bold` attribute removal on `modelElement` change.
-     *		modelConsumable.test( modelSelection, 'selection' ); // Check if `modelSelection` is consumable.
-     *		modelConsumable.test( modelRange, 'range' ); // Check if `modelRange` is consumable.
+     * ```ts
+     * modelConsumable.test( modelElement, 'insert' ); // Check for `modelElement` insertion change.
+     * modelConsumable.test( modelElement, 'addAttribute:bold' ); // Check for `bold` attribute insertion on `modelElement` change.
+     * modelConsumable.test( modelElement, 'removeAttribute:bold' ); // Check for `bold` attribute removal on `modelElement` change.
+     * modelConsumable.test( modelSelection, 'selection' ); // Check if `modelSelection` is consumable.
+     * modelConsumable.test( modelRange, 'range' ); // Check if `modelRange` is consumable.
+     * ```
      *
-     * @param {module:engine/model/item~Item|module:engine/model/selection~Selection|module:engine/model/range~Range} item
-     * Model item, range or selection to be tested.
-     * @param {String} type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
+     * @param item Model item, range or selection to be tested.
+     * @param type Consumable type. Will be normalized to a proper form, that is either `<word>` or `<part>:<part>`.
      * Second colon and everything after will be cut. Passing event name is a safe and good practice.
-     * @returns {null|Boolean} `null` if such consumable was never added, `false` if the consumable values was
+     * @returns `null` if such consumable was never added, `false` if the consumable values was
      * already consumed or `true` if it was added and not consumed yet.
      */
     test(item, type) {
@@ -196,16 +192,17 @@ export default class ModelConsumable {
     /**
      * Reverts consuming of a consumable value.
      *
-     *		modelConsumable.revert( modelElement, 'insert' ); // Revert consuming `modelElement` insertion change.
-     *		modelConsumable.revert( modelElement, 'addAttribute:bold' ); // Revert consuming `bold` attribute insert from `modelElement`.
-     *		modelConsumable.revert( modelElement, 'removeAttribute:bold' ); // Revert consuming `bold` attribute remove from `modelElement`.
-     *		modelConsumable.revert( modelSelection, 'selection' ); // Revert consuming `modelSelection`.
-     *		modelConsumable.revert( modelRange, 'range' ); // Revert consuming `modelRange`.
+     * ```ts
+     * modelConsumable.revert( modelElement, 'insert' ); // Revert consuming `modelElement` insertion change.
+     * modelConsumable.revert( modelElement, 'addAttribute:bold' ); // Revert consuming `bold` attribute insert from `modelElement`.
+     * modelConsumable.revert( modelElement, 'removeAttribute:bold' ); // Revert consuming `bold` attribute remove from `modelElement`.
+     * modelConsumable.revert( modelSelection, 'selection' ); // Revert consuming `modelSelection`.
+     * modelConsumable.revert( modelRange, 'range' ); // Revert consuming `modelRange`.
+     * ```
      *
-     * @param {module:engine/model/item~Item|module:engine/model/selection~Selection|module:engine/model/range~Range} item
-     * Model item, range or selection to be reverted.
-     * @param {String} type Consumable type.
-     * @returns {null|Boolean} `true` if consumable has been reversed, `false` otherwise. `null` if the consumable has
+     * @param item Model item, range or selection to be reverted.
+     * @param type Consumable type.
+     * @returns `true` if consumable has been reversed, `false` otherwise. `null` if the consumable has
      * never been added.
      */
     revert(item, type) {
@@ -226,7 +223,7 @@ export default class ModelConsumable {
     /**
      * Verifies if all events from the specified group were consumed.
      *
-     * @param {String} eventGroup The events group to verify.
+     * @param eventGroup The events group to verify.
      */
     verifyAllConsumed(eventGroup) {
         const items = [];
@@ -268,9 +265,8 @@ export default class ModelConsumable {
      * Used internally to correctly consume `TextProxy` instances.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/textproxy~TextProxy} textProxy `TextProxy` instance to get a symbol for.
-     * @returns {Symbol} Symbol representing all equal instances of `TextProxy`.
+     * @param textProxy `TextProxy` instance to get a symbol for.
+     * @returns Symbol representing all equal instances of `TextProxy`.
      */
     _getSymbolForTextProxy(textProxy) {
         let symbol = null;
@@ -291,9 +287,8 @@ export default class ModelConsumable {
      *
      * Used internally to correctly consume `TextProxy` instances.
      *
-     * @private
-     * @param {module:engine/model/textproxy~TextProxy} textProxy Text proxy instance.
-     * @returns {Symbol} Symbol generated for given `TextProxy`.
+     * @param textProxy Text proxy instance.
+     * @returns Symbol generated for given `TextProxy`.
      */
     _addSymbolForTextProxy(textProxy) {
         const start = textProxy.startOffset;
@@ -316,12 +311,14 @@ export default class ModelConsumable {
         return symbol;
     }
 }
-// Returns a normalized consumable type name from the given string. A normalized consumable type name is a string that has
-// at most one colon, for example: `insert` or `addMarker:highlight`. If a string to normalize has more "parts" (more colons),
-// the further parts are dropped, for example: `addattribute:bold:$text` -> `addattributes:bold`.
-//
-// @param {String} type Consumable type.
-// @returns {String} Normalized consumable type.
+/**
+ * Returns a normalized consumable type name from the given string. A normalized consumable type name is a string that has
+ * at most one colon, for example: `insert` or `addMarker:highlight`. If a string to normalize has more "parts" (more colons),
+ * the further parts are dropped, for example: `addattribute:bold:$text` -> `addattributes:bold`.
+ *
+ * @param type Consumable type.
+ * @returns Normalized consumable type.
+ */
 function _normalizeConsumableType(type) {
     const parts = type.split(':');
     // For inserts allow passing event name, it's stored in the context of a specified element so the element name is not needed.