@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/batch.js

@@ -1,19 +1,21 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/model/batch
  */
-import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import { logWarning } from '@ckeditor/ckeditor5-utils';
 /**
  * A batch instance groups model changes ({@link module:engine/model/operation/operation~Operation operations}). All operations
  * grouped in a single batch can be reverted together, so you can also think about a batch as of a single undo step. If you want
  * to extend a given undo step, you can add more changes to the batch using {@link module:engine/model/model~Model#enqueueChange}:
  *
- *		model.enqueueChange( batch, writer => {
- *			writer.insertText( 'foo', paragraph, 'end' );
- *		} );
+ * ```ts
+ * model.enqueueChange( batch, writer => {
+ * 	writer.insertText( 'foo', paragraph, 'end' );
+ * } );
+ * ```
  *
  * @see module:engine/model/model~Model#enqueueChange
  * @see module:engine/model/model~Model#change
@@ -24,13 +26,8 @@ export default class Batch {
      *
      * @see module:engine/model/model~Model#enqueueChange
      * @see module:engine/model/model~Model#change
-     * @param {Object} [type] A set of flags that specify the type of the batch. Batch type can alter how some of the features work
+     * @param type A set of flags that specify the type of the batch. Batch type can alter how some of the features work
      * when encountering a given `Batch` instance (for example, when a feature listens to applied operations).
-     * @param {Boolean} [type.isUndoable=true] Whether a batch can be undone through undo feature.
-     * @param {Boolean} [type.isLocal=true] Whether a batch includes operations created locally (`true`) or operations created on
-     * other, remote editors (`false`).
-     * @param {Boolean} [type.isUndo=false] Whether a batch was created by the undo feature and undoes other operations.
-     * @param {Boolean} [type.isTyping=false] Whether a batch includes operations connected with a typing action.
      */
     constructor(type = {}) {
         if (typeof type === 'string') {
@@ -45,40 +42,10 @@ export default class Batch {
             logWarning('batch-constructor-deprecated-string-type');
         }
         const { isUndoable = true, isLocal = true, isUndo = false, isTyping = false } = type;
-        /**
-         * An array of operations that compose this batch.
-         *
-         * @readonly
-         * @type {Array.<module:engine/model/operation/operation~Operation>}
-         */
         this.operations = [];
-        /**
-         * Whether the batch can be undone through the undo feature.
-         *
-         * @readonly
-         * @type {Boolean}
-         */
         this.isUndoable = isUndoable;
-        /**
-         * Whether the batch includes operations created locally (`true`) or operations created on other, remote editors (`false`).
-         *
-         * @readonly
-         * @type {Boolean}
-         */
         this.isLocal = isLocal;
-        /**
-         * Whether the batch was created by the undo feature and undoes other operations.
-         *
-         * @readonly
-         * @type {Boolean}
-         */
         this.isUndo = isUndo;
-        /**
-         * Whether the batch includes operations connected with typing.
-         *
-         * @readonly
-         * @type {Boolean}
-         */
         this.isTyping = isTyping;
     }
     /**
@@ -92,7 +59,6 @@ export default class Batch {
      * changes.
      *
      * @deprecated
-     * @type {'default'}
      */
     get type() {
         /**
@@ -107,9 +73,6 @@ export default class Batch {
     /**
      * Returns the base version of this batch, which is equal to the base version of the first operation in the batch.
      * If there are no operations in the batch or neither operation has the base version set, it returns `null`.
-     *
-     * @readonly
-     * @type {Number|null}
      */
     get baseVersion() {
         for (const op of this.operations) {
@@ -122,8 +85,8 @@ export default class Batch {
     /**
      * Adds an operation to the batch instance.
      *
-     * @param {module:engine/model/operation/operation~Operation} operation An operation to add.
-     * @returns {module:engine/model/operation/operation~Operation} The added operation.
+     * @param operation An operation to add.
+     * @returns The added operation.
      */
     addOperation(operation) {
         operation.batch = this;

package/src/model/differ.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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
  */
 /**
@@ -19,33 +19,20 @@ export default class Differ {
     /**
      * Creates a `Differ` instance.
      *
-     * @param {module:engine/model/markercollection~MarkerCollection} markerCollection Model's marker collection.
+     * @param markerCollection Model's marker collection.
      */
     constructor(markerCollection) {
-        /**
-         * Reference to the model's marker collection.
-         *
-         * @private
-         * @type {module:engine/model/markercollection~MarkerCollection}
-         */
-        this._markerCollection = markerCollection;
         /**
          * A map that stores changes that happened in a given element.
          *
          * The keys of the map are references to the model elements.
          * The values of the map are arrays with changes that were done on this element.
-         *
-         * @private
-         * @type {Map}
          */
         this._changesInElement = new Map();
         /**
          * A map that stores "element's children snapshots". A snapshot is representing children of a given element before
          * the first change was applied on that element. Snapshot items are objects with two properties: `name`,
          * containing the element name (or `'$text'` for a text node) and `attributes` which is a map of the node's attributes.
-         *
-         * @private
-         * @type {Map}
          */
         this._elementSnapshots = new Map();
         /**
@@ -55,17 +42,11 @@ export default class Differ {
          * The values of the map are objects with the following properties:
          * - `oldMarkerData`,
          * - `newMarkerData`.
-         *
-         * @private
-         * @type {Map.<String, Object>}
          */
         this._changedMarkers = new Map();
         /**
          * Stores the number of changes that were processed. Used to order the changes chronologically. It is important
          * when changes are sorted.
-         *
-         * @private
-         * @type {Number}
          */
         this._changeCount = 0;
         /**
@@ -74,9 +55,6 @@ export default class Differ {
          * return the cached value instead of calculating it again.
          *
          * This property stores those changes that did not take place in graveyard root.
-         *
-         * @private
-         * @type {Array.<Object>|null}
          */
         this._cachedChanges = null;
         /**
@@ -85,24 +63,16 @@ export default class Differ {
          * return the cached value instead of calculating it again.
          *
          * This property stores all changes evaluated by `Differ`, including those that took place in the graveyard.
-         *
-         * @private
-         * @type {Array.<Object>|null}
          */
         this._cachedChangesWithGraveyard = null;
         /**
          * Set of model items that were marked to get refreshed in {@link #_refreshItem}.
-         *
-         * @private
-         * @type {Set.<module:engine/model/item~Item>}
          */
         this._refreshedItems = new Set();
+        this._markerCollection = markerCollection;
     }
     /**
      * Informs whether there are any changes buffered in `Differ`.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isEmpty() {
         return this._changesInElement.size == 0 && this._changedMarkers.size == 0;
@@ -113,7 +83,7 @@ export default class Differ {
      * Operation type is checked and it is checked which nodes it will affect. These nodes are then stored in `Differ`
      * in the state before the operation is executed.
      *
-     * @param {module:engine/model/operation/operation~Operation} operationToBuffer An operation to buffer.
+     * @param operationToBuffer An operation to buffer.
      */
     bufferOperation(operationToBuffer) {
         // Below we take an operation, check its type, then use its parameters in marking (private) methods.
@@ -211,9 +181,9 @@ export default class Differ {
     /**
      * Buffers a marker change.
      *
-     * @param {String} markerName The name of the marker that changed.
-     * @param {module:engine/model/markercollection~MarkerData} oldMarkerData Marker data before the change.
-     * @param {module:engine/model/markercollection~MarkerData} newMarkerData Marker data after the change.
+     * @param markerName The name of the marker that changed.
+     * @param oldMarkerData Marker data before the change.
+     * @param newMarkerData Marker data after the change.
      */
     bufferMarkerChange(markerName, oldMarkerData, newMarkerData) {
         const buffered = this._changedMarkers.get(markerName);
@@ -235,7 +205,7 @@ export default class Differ {
     /**
      * Returns all markers that should be removed as a result of buffered changes.
      *
-     * @returns {Array.<Object>} Markers to remove. Each array item is an object containing the `name` and `range` properties.
+     * @returns Markers to remove. Each array item is an object containing the `name` and `range` properties.
      */
     getMarkersToRemove() {
         const result = [];
@@ -249,7 +219,7 @@ export default class Differ {
     /**
      * Returns all markers which should be added as a result of buffered changes.
      *
-     * @returns {Array.<Object>} Markers to add. Each array item is an object containing the `name` and `range` properties.
+     * @returns Markers to add. Each array item is an object containing the `name` and `range` properties.
      */
     getMarkersToAdd() {
         const result = [];
@@ -262,8 +232,6 @@ export default class Differ {
     }
     /**
      * Returns all markers which changed.
-     *
-     * @returns {Array.<Object>}
      */
     getChangedMarkers() {
         return Array.from(this._changedMarkers).map(([name, change]) => ({
@@ -283,8 +251,6 @@ export default class Differ {
      * * attribute changes,
      * * changes of markers which were defined as `affectsData`,
      * * changes of markers' `affectsData` property.
-     *
-     * @returns {Boolean}
      */
     hasDataChanges() {
         if (this._changesInElement.size > 0) {
@@ -318,10 +284,10 @@ export default class Differ {
      * Because calculating the diff is a costly operation, the result is cached. If no new operation was buffered since the
      * previous {@link #getChanges} call, the next call will return the cached value.
      *
-     * @param {Object} options Additional options.
-     * @param {Boolean} [options.includeChangesInGraveyard=false] If set to `true`, also changes that happened
+     * @param options Additional options.
+     * @param options.includeChangesInGraveyard If set to `true`, also changes that happened
      * in the graveyard root will be returned. By default, changes in the graveyard root are not returned.
-     * @returns {Array.<module:engine/model/differ~DiffItem>} Diff between the old and the new model tree state.
+     * @returns Diff between the old and the new model tree state.
      */
     getChanges(options = {}) {
         // If there are cached changes, just return them instead of calculating changes again.
@@ -465,8 +431,6 @@ export default class Differ {
     }
     /**
      * Returns a set of model items that were marked to get refreshed.
-     *
-     * @return {Set.<module:engine/model/item~Item>}
      */
     getRefreshedItems() {
         return new Set(this._refreshedItems);
@@ -485,9 +449,8 @@ export default class Differ {
      * Marks the given `item` in differ to be "refreshed". It means that the item will be marked as removed and inserted
      * in the differ changes set, so it will be effectively re-converted when the differ changes are handled by a dispatcher.
      *
-     * @protected
      * @internal
-     * @param {module:engine/model/item~Item} item Item to refresh.
+     * @param item Item to refresh.
      */
     _refreshItem(item) {
         if (this._isInInsertedElement(item.parent)) {
@@ -506,11 +469,6 @@ export default class Differ {
     }
     /**
      * Saves and handles an insert change.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} parent
-     * @param {Number} offset
-     * @param {Number} howMany
      */
     _markInsert(parent, offset, howMany) {
         const changeItem = { type: 'insert', offset, howMany, count: this._changeCount++ };
@@ -518,11 +476,6 @@ export default class Differ {
     }
     /**
      * Saves and handles a remove change.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} parent
-     * @param {Number} offset
-     * @param {Number} howMany
      */
     _markRemove(parent, offset, howMany) {
         const changeItem = { type: 'remove', offset, howMany, count: this._changeCount++ };
@@ -531,9 +484,6 @@ export default class Differ {
     }
     /**
      * Saves and handles an attribute change.
-     *
-     * @private
-     * @param {module:engine/model/item~Item} item
      */
     _markAttribute(item) {
         const changeItem = { type: 'attribute', offset: item.startOffset, howMany: item.offsetSize, count: this._changeCount++ };
@@ -541,10 +491,6 @@ export default class Differ {
     }
     /**
      * Saves and handles a model change.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} parent
-     * @param {Object} changeItem
      */
     _markChange(parent, changeItem) {
         // First, make a snapshot of this parent's children (it will be made only if it was not made before).
@@ -566,10 +512,6 @@ export default class Differ {
     }
     /**
      * Gets an array of changes that have already been saved for a given element.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} element
-     * @returns {Array.<Object>}
      */
     _getChangesForElement(element) {
         let changes;
@@ -584,9 +526,6 @@ export default class Differ {
     }
     /**
      * Saves a children snapshot for a given element.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} element
      */
     _makeSnapshot(element) {
         if (!this._elementSnapshots.has(element)) {
@@ -597,9 +536,8 @@ export default class Differ {
      * For a given newly saved change, compares it with a change already done on the element and modifies the incoming
      * change and/or the old change.
      *
-     * @private
-     * @param {Object} inc Incoming (new) change.
-     * @param {Array.<Object>} changes An array containing all the changes done on that element.
+     * @param inc Incoming (new) change.
+     * @param changes An array containing all the changes done on that element.
      */
     _handleChange(inc, changes) {
         // We need a helper variable that will store how many nodes are to be still handled for this change item.
@@ -807,11 +745,10 @@ export default class Differ {
     /**
      * Returns an object with a single insert change description.
      *
-     * @private
-     * @param {module:engine/model/element~Element} parent The element in which the change happened.
-     * @param {Number} offset The offset at which change happened.
-     * @param {Object} elementSnapshot The snapshot of the removed element a character.
-     * @returns {Object} The diff item.
+     * @param parent The element in which the change happened.
+     * @param offset The offset at which change happened.
+     * @param elementSnapshot The snapshot of the removed element a character.
+     * @returns The diff item.
      */
     _getInsertDiff(parent, offset, elementSnapshot) {
         return {
@@ -826,11 +763,10 @@ export default class Differ {
     /**
      * Returns an object with a single remove change description.
      *
-     * @private
-     * @param {module:engine/model/element~Element} parent The element in which change happened.
-     * @param {Number} offset The offset at which change happened.
-     * @param {Object} elementSnapshot The snapshot of the removed element a character.
-     * @returns {Object} The diff item.
+     * @param parent The element in which change happened.
+     * @param offset The offset at which change happened.
+     * @param elementSnapshot The snapshot of the removed element a character.
+     * @returns The diff item.
      */
     _getRemoveDiff(parent, offset, elementSnapshot) {
         return {
@@ -845,11 +781,10 @@ export default class Differ {
     /**
      * Returns an array of objects where each one is a single attribute change description.
      *
-     * @private
-     * @param {module:engine/model/range~Range} range The range where the change happened.
-     * @param {Map} oldAttributes A map, map iterator or compatible object that contains attributes before the change.
-     * @param {Map} newAttributes A map, map iterator or compatible object that contains attributes after the change.
-     * @returns {Array.<Object>} An array containing one or more diff items.
+     * @param range The range where the change happened.
+     * @param oldAttributes A map, map iterator or compatible object that contains attributes before the change.
+     * @param newAttributes A map, map iterator or compatible object that contains attributes after the change.
+     * @returns An array containing one or more diff items.
      */
     _getAttributesDiff(range, oldAttributes, newAttributes) {
         // Results holder.
@@ -895,10 +830,6 @@ export default class Differ {
     }
     /**
      * Checks whether given element or any of its parents is an element that is buffered as an inserted element.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} element Element to check.
-     * @returns {Boolean}
      */
     _isInInsertedElement(element) {
         const parent = element.parent;
@@ -919,11 +850,6 @@ export default class Differ {
     /**
      * Removes deeply all buffered changes that are registered in elements from range specified by `parent`, `offset`
      * and `howMany`.
-     *
-     * @private
-     * @param {module:engine/model/element~Element} parent
-     * @param {Number} offset
-     * @param {Number} howMany
      */
     _removeAllNestedChanges(parent, offset, howMany) {
         const range = new Range(Position._createAt(parent, offset), Position._createAt(parent, offset + howMany));
@@ -936,8 +862,10 @@ export default class Differ {
         }
     }
 }
-// Returns an array that is a copy of passed child list with the exception that text nodes are split to one or more
-// objects, each representing one character and attributes set on that character.
+/**
+ * Returns an array that is a copy of passed child list with the exception that text nodes are split to one or more
+ * objects, each representing one character and attributes set on that character.
+ */
 function _getChildrenSnapshot(children) {
     const snapshot = [];
     for (const child of children) {
@@ -958,51 +886,53 @@ function _getChildrenSnapshot(children) {
     }
     return snapshot;
 }
-// Generates array of actions for given changes set.
-// It simulates what `diff` function does.
-// Generated actions are:
-// - 'e' for 'equal' - when item at that position did not change,
-// - 'i' for 'insert' - when item at that position was inserted,
-// - 'r' for 'remove' - when item at that position was removed,
-// - 'a' for 'attribute' - when item at that position has it attributes changed.
-//
-// Example (assume that uppercase letters have bold attribute, compare with function code):
-//
-// children before:	fooBAR
-// children after:	foxybAR
-//
-// changes: type: remove, offset: 1, howMany: 1
-//			type: insert, offset: 2, howMany: 2
-//			type: attribute, offset: 4, howMany: 1
-//
-// expected actions: equal (f), remove (o), equal (o), insert (x), insert (y), attribute (b), equal (A), equal (R)
-//
-// steps taken by th script:
-//
-// 1. change = "type: remove, offset: 1, howMany: 1"; offset = 0; oldChildrenHandled = 0
-//    1.1 between this change and the beginning is one not-changed node, fill with one equal action, one old child has been handled
-//    1.2 this change removes one node, add one remove action
-//    1.3 change last visited `offset` to 1
-//    1.4 since an old child has been removed, one more old child has been handled
-//    1.5 actions at this point are: equal, remove
-//
-// 2. change = "type: insert, offset: 2, howMany: 2"; offset = 1; oldChildrenHandled = 2
-//    2.1 between this change and previous change is one not-changed node, add equal action, another one old children has been handled
-//    2.2 this change inserts two nodes, add two insert actions
-//    2.3 change last visited offset to the end of the inserted range, that is 4
-//    2.4 actions at this point are: equal, remove, equal, insert, insert
-//
-// 3. change = "type: attribute, offset: 4, howMany: 1"; offset = 4, oldChildrenHandled = 3
-//    3.1 between this change and previous change are no not-changed nodes
-//    3.2 this change changes one node, add one attribute action
-//    3.3 change last visited `offset` to the end of change range, that is 5
-//    3.4 since an old child has been changed, one more old child has been handled
-//    3.5 actions at this point are: equal, remove, equal, insert, insert, attribute
-//
-// 4. after loop oldChildrenHandled = 4, oldChildrenLength = 6 (fooBAR is 6 characters)
-//    4.1 fill up with two equal actions
-//
-// The result actions are: equal, remove, equal, insert, insert, attribute, equal, equal.
+/**
+ * Generates array of actions for given changes set.
+ * It simulates what `diff` function does.
+ * Generated actions are:
+ * - 'e' for 'equal' - when item at that position did not change,
+ * - 'i' for 'insert' - when item at that position was inserted,
+ * - 'r' for 'remove' - when item at that position was removed,
+ * - 'a' for 'attribute' - when item at that position has it attributes changed.
+ *
+ * Example (assume that uppercase letters have bold attribute, compare with function code):
+ *
+ * children before:	fooBAR
+ * children after:	foxybAR
+ *
+ * changes: type: remove, offset: 1, howMany: 1
+ *			type: insert, offset: 2, howMany: 2
+ *			type: attribute, offset: 4, howMany: 1
+ *
+ * expected actions: equal (f), remove (o), equal (o), insert (x), insert (y), attribute (b), equal (A), equal (R)
+ *
+ * steps taken by th script:
+ *
+ * 1. change = "type: remove, offset: 1, howMany: 1"; offset = 0; oldChildrenHandled = 0
+ *    1.1 between this change and the beginning is one not-changed node, fill with one equal action, one old child has been handled
+ *    1.2 this change removes one node, add one remove action
+ *    1.3 change last visited `offset` to 1
+ *    1.4 since an old child has been removed, one more old child has been handled
+ *    1.5 actions at this point are: equal, remove
+ *
+ * 2. change = "type: insert, offset: 2, howMany: 2"; offset = 1; oldChildrenHandled = 2
+ *    2.1 between this change and previous change is one not-changed node, add equal action, another one old children has been handled
+ *    2.2 this change inserts two nodes, add two insert actions
+ *    2.3 change last visited offset to the end of the inserted range, that is 4
+ *    2.4 actions at this point are: equal, remove, equal, insert, insert
+ *
+ * 3. change = "type: attribute, offset: 4, howMany: 1"; offset = 4, oldChildrenHandled = 3
+ *    3.1 between this change and previous change are no not-changed nodes
+ *    3.2 this change changes one node, add one attribute action
+ *    3.3 change last visited `offset` to the end of change range, that is 5
+ *    3.4 since an old child has been changed, one more old child has been handled
+ *    3.5 actions at this point are: equal, remove, equal, insert, insert, attribute
+ *
+ * 4. after loop oldChildrenHandled = 4, oldChildrenLength = 6 (fooBAR is 6 characters)
+ *    4.1 fill up with two equal actions
+ *
+ * The result actions are: equal, remove, equal, insert, insert, attribute, equal, equal.
+ */
 function _generateActionsFromChanges(oldChildrenLength, changes) {
     const actions = [];
     let offset = 0;
@@ -1050,34 +980,11 @@ function _generateActionsFromChanges(oldChildrenLength, changes) {
     }
     return actions;
 }
-// Filter callback for Array.filter that filters out change entries that are in graveyard.
+/**
+ * Filter callback for Array.filter that filters out change entries that are in graveyard.
+ */
 function _changesInGraveyardFilter(entry) {
     const posInGy = 'position' in entry && entry.position.root.rootName == '$graveyard';
     const rangeInGy = 'range' in entry && entry.range.root.rootName == '$graveyard';
     return !posInGy && !rangeInGy;
 }
-/**
- * The type of diff item.
- *
- * @member {'attribute'} module:engine/model/differ~DiffItemAttribute#type
- */
-/**
- * The name of the changed attribute.
- *
- * @member {String} module:engine/model/differ~DiffItemAttribute#attributeKey
- */
-/**
- * An attribute previous value (before change).
- *
- * @member {String} module:engine/model/differ~DiffItemAttribute#attributeOldValue
- */
-/**
- * An attribute new value (after change).
- *
- * @member {String} module:engine/model/differ~DiffItemAttribute#attributeNewValue
- */
-/**
- * The range where the change happened.
- *
- * @member {module:engine/model/range~Range} module:engine/model/differ~DiffItemAttribute#range
- */