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

package/src/conversion/upcastdispatcher.js

@@ -34,73 +34,74 @@ import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * The third parameter of the callback is an instance of {@link module:engine/conversion/upcastdispatcher~UpcastConversionApi}
  * which provides additional tools for converters.
  *
- * You can read more about conversion in the {@glink framework/guides/deep-dive/conversion/upcast Upcast conversion} guide.
+ * You can read more about conversion in the {@glink framework/deep-dive/conversion/upcast Upcast conversion} guide.
  *
  * Examples of event-based converters:
  *
- *		// A converter for links (<a>).
- *		editor.data.upcastDispatcher.on( 'element:a', ( evt, data, conversionApi ) => {
- *			if ( conversionApi.consumable.consume( data.viewItem, { name: true, attributes: [ 'href' ] } ) ) {
- *				// The <a> element is inline and is represented by an attribute in the model.
- *				// This is why you need to convert only children.
- *				const { modelRange } = conversionApi.convertChildren( data.viewItem, data.modelCursor );
+ * ```ts
+ * // A converter for links (<a>).
+ * editor.data.upcastDispatcher.on( 'element:a', ( evt, data, conversionApi ) => {
+ * 	if ( conversionApi.consumable.consume( data.viewItem, { name: true, attributes: [ 'href' ] } ) ) {
+ * 		// The <a> element is inline and is represented by an attribute in the model.
+ * 		// This is why you need to convert only children.
+ * 		const { modelRange } = conversionApi.convertChildren( data.viewItem, data.modelCursor );
  *
- *				for ( let item of modelRange.getItems() ) {
- *					if ( conversionApi.schema.checkAttribute( item, 'linkHref' ) ) {
- *						conversionApi.writer.setAttribute( 'linkHref', data.viewItem.getAttribute( 'href' ), item );
- *					}
- *				}
- *			}
- *		} );
+ * 		for ( let item of modelRange.getItems() ) {
+ * 			if ( conversionApi.schema.checkAttribute( item, 'linkHref' ) ) {
+ * 				conversionApi.writer.setAttribute( 'linkHref', data.viewItem.getAttribute( 'href' ), item );
+ * 			}
+ * 		}
+ * 	}
+ * } );
  *
- *		// Convert <p> element's font-size style.
- *		// Note: You should use a low-priority observer in order to ensure that
- *		// it is executed after the element-to-element converter.
- *		editor.data.upcastDispatcher.on( 'element:p', ( evt, data, conversionApi ) => {
- *			const { consumable, schema, writer } = conversionApi;
+ * // Convert <p> element's font-size style.
+ * // Note: You should use a low-priority observer in order to ensure that
+ * // it is executed after the element-to-element converter.
+ * editor.data.upcastDispatcher.on( 'element:p', ( evt, data, conversionApi ) => {
+ * 	const { consumable, schema, writer } = conversionApi;
  *
- *			if ( !consumable.consume( data.viewItem, { style: 'font-size' } ) ) {
- *				return;
- *			}
+ * 	if ( !consumable.consume( data.viewItem, { style: 'font-size' } ) ) {
+ * 		return;
+ * 	}
  *
- *			const fontSize = data.viewItem.getStyle( 'font-size' );
+ * 	const fontSize = data.viewItem.getStyle( 'font-size' );
  *
- *			// Do not go for the model element after data.modelCursor because it might happen
- *			// that a single view element was converted to multiple model elements. Get all of them.
- *			for ( const item of data.modelRange.getItems( { shallow: true } ) ) {
- *				if ( schema.checkAttribute( item, 'fontSize' ) ) {
- *					writer.setAttribute( 'fontSize', fontSize, item );
- *				}
- *			}
- *		}, { priority: 'low' } );
+ * 	// Do not go for the model element after data.modelCursor because it might happen
+ * 	// that a single view element was converted to multiple model elements. Get all of them.
+ * 	for ( const item of data.modelRange.getItems( { shallow: true } ) ) {
+ * 		if ( schema.checkAttribute( item, 'fontSize' ) ) {
+ * 			writer.setAttribute( 'fontSize', fontSize, item );
+ * 		}
+ * 	}
+ * }, { priority: 'low' } );
  *
- *		// Convert all elements which have no custom converter into a paragraph (autoparagraphing).
- *		editor.data.upcastDispatcher.on( 'element', ( evt, data, conversionApi ) => {
- *			// Check if an element can be converted.
- *			if ( !conversionApi.consumable.test( data.viewItem, { name: data.viewItem.name } ) ) {
- *				// When an element is already consumed by higher priority converters, do nothing.
- *				return;
- *			}
+ * // Convert all elements which have no custom converter into a paragraph (autoparagraphing).
+ * editor.data.upcastDispatcher.on( 'element', ( evt, data, conversionApi ) => {
+ * 	// Check if an element can be converted.
+ * 	if ( !conversionApi.consumable.test( data.viewItem, { name: data.viewItem.name } ) ) {
+ * 		// When an element is already consumed by higher priority converters, do nothing.
+ * 		return;
+ * 	}
  *
- *			const paragraph = conversionApi.writer.createElement( 'paragraph' );
+ * 	const paragraph = conversionApi.writer.createElement( 'paragraph' );
  *
- *			// Try to safely insert a paragraph at the model cursor - it will find an allowed parent for the current element.
- *			if ( !conversionApi.safeInsert( paragraph, data.modelCursor ) ) {
- *				// When an element was not inserted, it means that you cannot insert a paragraph at this position.
- *				return;
- *			}
+ * 	// Try to safely insert a paragraph at the model cursor - it will find an allowed parent for the current element.
+ * 	if ( !conversionApi.safeInsert( paragraph, data.modelCursor ) ) {
+ * 		// When an element was not inserted, it means that you cannot insert a paragraph at this position.
+ * 		return;
+ * 	}
  *
- *			// Consume the inserted element.
- *			conversionApi.consumable.consume( data.viewItem, { name: data.viewItem.name } ) );
+ * 	// Consume the inserted element.
+ * 	conversionApi.consumable.consume( data.viewItem, { name: data.viewItem.name } ) );
  *
- *			// Convert the children to a paragraph.
- *			const { modelRange } = conversionApi.convertChildren( data.viewItem,  paragraph ) );
+ * 	// Convert the children to a paragraph.
+ * 	const { modelRange } = conversionApi.convertChildren( data.viewItem,  paragraph ) );
  *
- *			// Update `modelRange` and `modelCursor` in the `data` as a conversion result.
- *			conversionApi.updateConversionResult( paragraph, data );
- *		}, { priority: 'low' } );
+ * 	// Update `modelRange` and `modelCursor` in the `data` as a conversion result.
+ * 	conversionApi.updateConversionResult( paragraph, data );
+ * }, { priority: 'low' } );
+ * ```
  *
- * @mixes module:utils/emittermixin~EmitterMixin
  * @fires viewCleanup
  * @fires element
  * @fires text
@@ -111,7 +112,7 @@ export default class UpcastDispatcher extends EmitterMixin() {
      * Creates an upcast dispatcher that operates using the passed API.
      *
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi
-     * @param {Object} [conversionApi] Additional properties for an interface that will be passed to events fired
+     * @param conversionApi Additional properties for an interface that will be passed to events fired
      * by the upcast dispatcher.
      */
     constructor(conversionApi) {
@@ -120,43 +121,26 @@ export default class UpcastDispatcher extends EmitterMixin() {
          * The list of elements that were created during splitting.
          *
          * After the conversion process, the list is cleared.
-         *
-         * @private
-         * @type {Map.<module:engine/model/element~Element,Array.<module:engine/model/element~Element>>}
          */
         this._splitParts = new Map();
         /**
          * The list of cursor parent elements that were created during splitting.
          *
          * After the conversion process the list is cleared.
-         *
-         * @private
-         * @type {Map.<module:engine/model/element~Element,Array.<module:engine/model/element~Element>>}
          */
         this._cursorParents = new Map();
         /**
          * The position in the temporary structure where the converted content is inserted. The structure reflects the context of
          * the target position where the content will be inserted. This property is built based on the context parameter of the
          * convert method.
-         *
-         * @private
-         * @type {module:engine/model/position~Position|null}
          */
         this._modelCursor = null;
         /**
          * The list of elements that were created during the splitting but should not get removed on conversion end even if they are empty.
          *
          * The list is cleared after the conversion process.
-         *
-         * @private
-         * @type {Set.<module:engine/model/element~Element>}
          */
         this._emptyElementsToKeep = new Set();
-        /**
-         * An interface passed by the dispatcher to the event callbacks.
-         *
-         * @member {module:engine/conversion/upcastdispatcher~UpcastConversionApi}
-         */
         this.conversionApi = {
             ...conversionApi,
             consumable: null,
@@ -164,10 +148,10 @@ export default class UpcastDispatcher extends EmitterMixin() {
             store: null,
             convertItem: (viewItem, modelCursor) => this._convertItem(viewItem, modelCursor),
             convertChildren: (viewElement, positionOrElement) => this._convertChildren(viewElement, positionOrElement),
-            safeInsert: (modelElement, position) => this._safeInsert(modelElement, position),
+            safeInsert: (modelNode, position) => this._safeInsert(modelNode, position),
             updateConversionResult: (modelElement, data) => this._updateConversionResult(modelElement, data),
             // Advanced API - use only if custom position handling is needed.
-            splitToAllowedParent: (modelElement, modelCursor) => this._splitToAllowedParent(modelElement, modelCursor),
+            splitToAllowedParent: (modelNode, modelCursor) => this._splitToAllowedParent(modelNode, modelCursor),
             getSplitParts: modelElement => this._getSplitParts(modelElement),
             keepEmptyElement: modelElement => this._keepEmptyElement(modelElement)
         };
@@ -178,11 +162,10 @@ export default class UpcastDispatcher extends EmitterMixin() {
      * @fires element
      * @fires text
      * @fires documentFragment
-     * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element} viewElement
-     * The part of the view to be converted.
-     * @param {module:engine/model/writer~Writer} writer An instance of the model writer.
-     * @param {module:engine/model/schema~SchemaContextDefinition} [context=['$root']] Elements will be converted according to this context.
-     * @returns {module:engine/model/documentfragment~DocumentFragment} Model data that is the result of the conversion process
+     * @param viewElement The part of the view to be converted.
+     * @param writer An instance of the model writer.
+     * @param context Elements will be converted according to this context.
+     * @returns Model data that is the result of the conversion process
      * wrapped in `DocumentFragment`. Converted marker elements will be set as the document fragment's
      * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
      */
@@ -226,7 +209,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
         return documentFragment;
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#convertItem
      */
     _convertItem(viewItem, modelCursor) {
@@ -254,7 +236,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
         return { modelRange: data.modelRange, modelCursor: data.modelCursor };
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#convertChildren
      */
     _convertChildren(viewItem, elementOrModelCursor) {
@@ -271,24 +252,22 @@ export default class UpcastDispatcher extends EmitterMixin() {
         return { modelRange, modelCursor: nextModelCursor };
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#safeInsert
      */
-    _safeInsert(modelElement, position) {
+    _safeInsert(modelNode, position) {
         // Find allowed parent for element that we are going to insert.
         // If current parent does not allow to insert element but one of the ancestors does
         // then split nodes to allowed parent.
-        const splitResult = this._splitToAllowedParent(modelElement, position);
+        const splitResult = this._splitToAllowedParent(modelNode, position);
         // When there is no split result it means that we can't insert element to model tree, so let's skip it.
         if (!splitResult) {
             return false;
         }
         // Insert element on allowed position.
-        this.conversionApi.writer.insert(modelElement, splitResult.position);
+        this.conversionApi.writer.insert(modelNode, splitResult.position);
         return true;
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#updateConversionResult
      */
     _updateConversionResult(modelElement, data) {
@@ -313,7 +292,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
         }
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#splitToAllowedParent
      */
     _splitToAllowedParent(node, modelCursor) {
@@ -378,10 +356,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
      * Registers that a `splitPart` element is a split part of the `originalPart` element.
      *
      * The data set by this method is used by {@link #_getSplitParts} and {@link #_removeEmptyElements}.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} originalPart
-     * @param {module:engine/model/element~Element} splitPart
      */
     _registerSplitPair(originalPart, splitPart) {
         if (!this._splitParts.has(originalPart)) {
@@ -392,7 +366,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
         list.push(splitPart);
     }
     /**
-     * @private
      * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#getSplitParts
      */
     _getSplitParts(element) {
@@ -407,8 +380,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
     }
     /**
      * Mark an element that were created during the splitting to not get removed on conversion end even if it is empty.
-     *
-     * @private
      */
     _keepEmptyElement(element) {
         this._emptyElementsToKeep.add(element);
@@ -418,8 +389,6 @@ export default class UpcastDispatcher extends EmitterMixin() {
      *
      * This method works recursively to re-check empty elements again after at least one element was removed in the initial call,
      * as some elements might have become empty after other empty elements were removed from them.
-     *
-     * @private
      */
     _removeEmptyElements() {
         let anyRemoved = false;
@@ -435,11 +404,13 @@ export default class UpcastDispatcher extends EmitterMixin() {
         }
     }
 }
-// Traverses given model item and searches elements which marks marker range. Found element is removed from
-// DocumentFragment but path of this element is stored in a Map which is then returned.
-//
-// @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/node~Node} modelItem Fragment of model.
-// @returns {Map<String, module:engine/model/range~Range>} List of static markers.
+/**
+ * Traverses given model item and searches elements which marks marker range. Found element is removed from
+ * DocumentFragment but path of this element is stored in a Map which is then returned.
+ *
+ * @param modelItem Fragment of model.
+ * @returns List of static markers.
+ */
 function extractMarkersFromModelFragment(modelItem, writer) {
     const markerElements = new Set();
     const markers = new Map();
@@ -469,7 +440,9 @@ function extractMarkersFromModelFragment(modelItem, writer) {
     }
     return markers;
 }
-// Creates model fragment according to given context and returns position in the bottom (the deepest) element.
+/**
+ * Creates model fragment according to given context and returns position in the bottom (the deepest) element.
+ */
 function createContextTree(contextDefinition, writer) {
     let position;
     for (const item of new SchemaContext(contextDefinition)) {