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

package/src/conversion/downcastdispatcher.js

@@ -73,53 +73,44 @@ import { EmitterMixin } from '@ckeditor/ckeditor5-utils';
  *
  * You can read more about conversion in the following guide:
  *
- * * {@glink framework/guides/deep-dive/conversion/downcast Downcast conversion}
+ * * {@glink framework/deep-dive/conversion/downcast Downcast conversion}
  *
  * An example of a custom converter for the downcast dispatcher:
  *
- *		// You will convert inserting a "paragraph" model element into the model.
- *		downcastDispatcher.on( 'insert:paragraph', ( evt, data, conversionApi ) => {
- *			// Remember to check whether the change has not been consumed yet and consume it.
- *			if ( !conversionApi.consumable.consume( data.item, 'insert' ) ) {
- *				return;
- *			}
+ * ```ts
+ * // You will convert inserting a "paragraph" model element into the model.
+ * downcastDispatcher.on( 'insert:paragraph', ( evt, data, conversionApi ) => {
+ * 	// Remember to check whether the change has not been consumed yet and consume it.
+ * 	if ( !conversionApi.consumable.consume( data.item, 'insert' ) ) {
+ * 		return;
+ * 	}
  *
- *			// Translate the position in the model to a position in the view.
- *			const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
+ * 	// Translate the position in the model to a position in the view.
+ * 	const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
  *
- *			// Create a <p> element that will be inserted into the view at the `viewPosition`.
- *			const viewElement = conversionApi.writer.createContainerElement( 'p' );
+ * 	// Create a <p> element that will be inserted into the view at the `viewPosition`.
+ * 	const viewElement = conversionApi.writer.createContainerElement( 'p' );
  *
- *			// Bind the newly created view element to the model element so positions will map accordingly in the future.
- *			conversionApi.mapper.bindElements( data.item, viewElement );
+ * 	// Bind the newly created view element to the model element so positions will map accordingly in the future.
+ * 	conversionApi.mapper.bindElements( data.item, viewElement );
  *
- *			// Add the newly created view element to the view.
- *			conversionApi.writer.insert( viewPosition, viewElement );
- *		} );
+ * 	// Add the newly created view element to the view.
+ * 	conversionApi.writer.insert( viewPosition, viewElement );
+ * } );
+ * ```
  */
 export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Creates a downcast dispatcher instance.
      *
      * @see module:engine/conversion/downcastdispatcher~DowncastConversionApi
-     * @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 downcast dispatcher.
      */
     constructor(conversionApi) {
         super();
-        /**
-         * A template for an interface passed by the dispatcher to the event callbacks.
-         *
-         * @protected
-         * @member {module:engine/conversion/downcastdispatcher~DowncastConversionApi}
-         */
         this._conversionApi = { dispatcher: this, ...conversionApi };
-        /**
-         * A map of already fired events for a given `ModelConsumable`.
-         *
-         * @private
-         * @member {WeakMap.<module:engine/conversion/downcastdispatcher~DowncastConversionApi,Map>}
-         */
         this._firedEventsMap = new WeakMap();
     }
     /**
@@ -132,9 +123,9 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * @fires addMarker
      * @fires removeMarker
      * @fires reduceChanges
-     * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
-     * @param {module:engine/model/markercollection~MarkerCollection} markers Markers related to the model fragment to convert.
-     * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
+     * @param differ The differ object with buffered changes.
+     * @param markers Markers related to the model fragment to convert.
+     * @param writer The view writer that should be used to modify the view document.
      */
     convertChanges(differ, markers, writer) {
         const conversionApi = this._createConversionApi(writer, differ.getRefreshedItems());
@@ -180,10 +171,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * @fires insert
      * @fires attribute
      * @fires addMarker
-     * @param {module:engine/model/range~Range} range The inserted range.
-     * @param {Map<String,module:engine/model/range~Range>} markers The map of markers that should be down-casted.
-     * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
-     * @param {Object} [options] Optional options object passed to `convertionApi.options`.
+     * @param range The inserted range.
+     * @param markers The map of markers that should be down-casted.
+     * @param writer The view writer that should be used to modify the view document.
+     * @param options Optional options object passed to `convertionApi.options`.
      */
     convert(range, markers, writer, options = {}) {
         const conversionApi = this._createConversionApi(writer, undefined, options);
@@ -202,9 +193,9 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * @fires selection
      * @fires addMarker
      * @fires attribute
-     * @param {module:engine/model/selection~Selection} selection The selection to convert.
-     * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with the converted model.
-     * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
+     * @param selection The selection to convert.
+     * @param markers Markers connected with the converted model.
+     * @param writer View writer that should be used to modify the view document.
      */
     convertSelection(selection, markers, writer) {
         const markersAtSelection = Array.from(markers.getMarkersAtPosition(selection.getFirstPosition()));
@@ -248,13 +239,11 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * For each node in the range, {@link #event:insert `insert` event is fired}. For each attribute on each node,
      * {@link #event:attribute `attribute` event is fired}.
      *
-     * @protected
      * @fires insert
      * @fires attribute
-     * @param {module:engine/model/range~Range} range The inserted range.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
-     * @param {Object} [options]
-     * @param {Boolean} [options.doNotAddConsumables=false] Whether the ModelConsumable should not get populated
+     * @param range The inserted range.
+     * @param conversionApi The conversion API object.
+     * @param options.doNotAddConsumables Whether the ModelConsumable should not get populated
      * for items in the provided range.
      */
     _convertInsert(range, conversionApi, options = {}) {
@@ -270,11 +259,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Fires conversion of a single node removal. Fires {@link #event:remove remove event} with provided data.
      *
-     * @protected
-     * @param {module:engine/model/position~Position} position Position from which node was removed.
-     * @param {Number} length Offset size of removed node.
-     * @param {String} name Name of removed node.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param position Position from which node was removed.
+     * @param length Offset size of removed node.
+     * @param name Name of removed node.
+     * @param conversionApi The conversion API object.
      */
     _convertRemove(position, length, name, conversionApi) {
         this.fire(`remove:${name}`, { position, length }, conversionApi);
@@ -284,13 +272,12 @@ export default class DowncastDispatcher extends EmitterMixin() {
      *
      * For each node in the given `range`, {@link #event:attribute attribute event} is fired with the passed data.
      *
-     * @protected
      * @fires attribute
-     * @param {module:engine/model/range~Range} range Changed range.
-     * @param {String} key Key of the attribute that has changed.
-     * @param {*} oldValue Attribute value before the change or `null` if the attribute has not been set before.
-     * @param {*} newValue New attribute value or `null` if the attribute has been removed.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param range Changed range.
+     * @param key Key of the attribute that has changed.
+     * @param oldValue Attribute value before the change or `null` if the attribute has not been set before.
+     * @param newValue New attribute value or `null` if the attribute has been removed.
+     * @param conversionApi The conversion API object.
      */
     _convertAttribute(range, key, oldValue, newValue, conversionApi) {
         // Create a list with attributes to consume.
@@ -314,11 +301,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * For each node in the range on its depth (without children), {@link #event:insert `insert` event} is fired.
      * For each attribute on each node, {@link #event:attribute `attribute` event} is fired.
      *
-     * @protected
      * @fires insert
      * @fires attribute
-     * @param {module:engine/model/range~Range} range The range to reinsert.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param range The range to reinsert.
+     * @param conversionApi The conversion API object.
      */
     _convertReinsert(range, conversionApi) {
         // Convert the elements - without converting children.
@@ -334,11 +320,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * Converts the added marker. Fires the {@link #event:addMarker `addMarker`} event for each item
      * in the marker's range. If the range is collapsed, a single event is dispatched. See the event description for more details.
      *
-     * @protected
      * @fires addMarker
-     * @param {String} markerName Marker name.
-     * @param {module:engine/model/range~Range} markerRange The marker range.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param markerName Marker name.
+     * @param markerRange The marker range.
+     * @param conversionApi The conversion API object.
      */
     _convertMarkerAdd(markerName, markerRange, conversionApi) {
         // Do not convert if range is in graveyard.
@@ -375,11 +360,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Fires the conversion of the marker removal. Fires the {@link #event:removeMarker `removeMarker`} event with the provided data.
      *
-     * @protected
      * @fires removeMarker
-     * @param {String} markerName Marker name.
-     * @param {module:engine/model/range~Range} markerRange The marker range.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param markerName Marker name.
+     * @param markerRange The marker range.
+     * @param conversionApi The conversion API object.
      */
     _convertMarkerRemove(markerName, markerRange, conversionApi) {
         // Do not convert if range is in graveyard.
@@ -395,10 +379,7 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * reconversion. The {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToStructure
      * `DowncastHelpers.elementToStructure()`} is using this event to trigger reconversion.
      *
-     * @private
      * @fires reduceChanges
-     * @param {Iterable.<module:engine/model/differ~DiffItem>} changes
-     * @returns {Iterable.<module:engine/model/differ~DiffItem>}
      */
     _reduceChanges(changes) {
         const data = { changes };
@@ -409,10 +390,9 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * Populates provided {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume from a given range,
      * assuming that the range has just been inserted to the model.
      *
-     * @private
-     * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable The consumable.
-     * @param {Iterable.<module:engine/model/treewalker~TreeWalkerValue>} walkerValues The walker values for the inserted range.
-     * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
+     * @param consumable The consumable.
+     * @param walkerValues The walker values for the inserted range.
+     * @returns The values to consume.
      */
     _addConsumablesForInsert(consumable, walkerValues) {
         for (const value of walkerValues) {
@@ -430,11 +410,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Populates provided {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume for a given range.
      *
-     * @private
-     * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable The consumable.
-     * @param {module:engine/model/range~Range} range The affected range.
-     * @param {String} type Consumable type.
-     * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
+     * @param consumable The consumable.
+     * @param range The affected range.
+     * @param type Consumable type.
+     * @returns The values to consume.
      */
     _addConsumablesForRange(consumable, range, type) {
         for (const item of range.getItems()) {
@@ -445,11 +424,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Populates provided {@link module:engine/conversion/modelconsumable~ModelConsumable} with selection consumable values.
      *
-     * @private
-     * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable The consumable.
-     * @param {module:engine/model/selection~Selection} selection The selection to create the consumable from.
-     * @param {Iterable.<module:engine/model/markercollection~Marker>} markers Markers that contain the selection.
-     * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
+     * @param consumable The consumable.
+     * @param selection The selection to create the consumable from.
+     * @param markers Markers that contain the selection.
+     * @returns The values to consume.
      */
     _addConsumablesForSelection(consumable, selection, markers) {
         consumable.add(selection, 'selection');
@@ -464,12 +442,11 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Tests whether given event wasn't already fired and if so, fires it.
      *
-     * @private
      * @fires insert
      * @fires attribute
-     * @param {String} type Event type.
-     * @param {Object} data Event data.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param type Event type.
+     * @param data Event data.
+     * @param conversionApi The conversion API object.
      */
     _testAndFire(type, data, conversionApi) {
         const eventName = getEventName(type, data);
@@ -490,9 +467,8 @@ export default class DowncastDispatcher extends EmitterMixin() {
     /**
      * Fires not already fired events for setting attributes on just inserted item.
      *
-     * @private
-     * @param {module:engine/model/item~Item} item The model item to convert attributes for.
-     * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
+     * @param item The model item to convert attributes for.
+     * @param conversionApi The conversion API object.
      */
     _testAndFireAddAttributes(item, conversionApi) {
         const data = {
@@ -510,12 +486,11 @@ export default class DowncastDispatcher extends EmitterMixin() {
      * Builds an instance of the {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi} from a template and a given
      * {@link module:engine/view/downcastwriter~DowncastWriter `DowncastWriter`} and options object.
      *
-     * @private
-     * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
-     * @param {Set.<module:engine/model/element~Element>} [refreshedItems] A set of model elements that should not reuse their
+     * @param writer View writer that should be used to modify the view document.
+     * @param refreshedItems A set of model elements that should not reuse their
      * previous view representations.
-     * @param {Object} [options] Optional options passed to `convertionApi.options`.
-     * @return {module:engine/conversion/downcastdispatcher~DowncastConversionApi} The conversion API object.
+     * @param options Optional options passed to `convertionApi.options`.
+     * @return The conversion API object.
      */
     _createConversionApi(writer, refreshedItems = new Set(), options = {}) {
         const conversionApi = {
@@ -532,13 +507,10 @@ export default class DowncastDispatcher extends EmitterMixin() {
         return conversionApi;
     }
 }
-// Helper function, checks whether change of `marker` at `modelPosition` should be converted. Marker changes are not
-// converted if they happen inside an element with custom conversion method.
-//
-// @param {module:engine/model/position~Position} modelPosition
-// @param {module:engine/model/markercollection~Marker} marker
-// @param {module:engine/conversion/mapper~Mapper} mapper
-// @returns {Boolean}
+/**
+ * Helper function, checks whether change of `marker` at `modelPosition` should be converted. Marker changes are not
+ * converted if they happen inside an element with custom conversion method.
+ */
 function shouldMarkerChangeBeConverted(modelPosition, marker, mapper) {
     const range = marker.getRange();
     const ancestors = Array.from(modelPosition.getAncestors());
@@ -564,53 +536,3 @@ function walkerValueToEventData(value) {
         range: itemRange
     };
 }
-/**
- * The {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} instance.
- *
- * @member {module:engine/conversion/downcastdispatcher~DowncastDispatcher} #dispatcher
- */
-/**
- * Stores the information about what parts of a processed model item are still waiting to be handled. After a piece of a model item was
- * converted, an appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
- *
- * @member {module:engine/conversion/modelconsumable~ModelConsumable} #consumable
- */
-/**
- * The {@link module:engine/conversion/mapper~Mapper} instance.
- *
- * @member {module:engine/conversion/mapper~Mapper} #mapper
- */
-/**
- * The {@link module:engine/model/schema~Schema} instance set for the model that is downcast.
- *
- * @member {module:engine/model/schema~Schema} #schema
- */
-/**
- * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate the data during conversion.
- *
- * @member {module:engine/view/downcastwriter~DowncastWriter} #writer
- */
-/**
- * Triggers conversion of a specified item.
- * This conversion is triggered within (as a separate process of) the parent conversion.
- *
- * @method #convertItem
- * @param {module:engine/model/item~Item} item The model item to trigger nested insert conversion on.
- */
-/**
- * Triggers conversion of children of a specified element.
- *
- * @method #convertChildren
- * @param {module:engine/model/element~Element} element The model element to trigger children insert conversion on.
- */
-/**
- * Triggers conversion of attributes of a specified item.
- *
- * @method #convertAttributes
- * @param {module:engine/model/item~Item} item The model item to trigger attribute conversion on.
- */
-/**
- * An object with an additional configuration which can be used during the conversion process. Available only for data downcast conversion.
- *
- * @member {Object} #options
- */