@ckeditor/ckeditor5-engine 35.4.0 → 36.0.1

package/src/model/utils/insertcontent.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
  */
 /**
@@ -8,11 +8,11 @@
 import DocumentSelection from '../documentselection';
 import Element from '../element';
 import LivePosition from '../liveposition';
+import LiveRange from '../liverange';
 import Position from '../position';
 import Range from '../range';
 import Selection from '../selection';
 import { CKEditorError } from '@ckeditor/ckeditor5-utils';
-import { LiveRange } from '../../index';
 /**
  * Inserts content into the editor (specified selection) as one would expect the paste functionality to work.
  *
@@ -20,11 +20,13 @@ import { LiveRange } from '../../index';
  *
  * Some examples:
  *
- * 		<p>x^</p> + <p>y</p> => <p>x</p><p>y</p> => <p>xy[]</p>
- * 		<p>x^y</p> + <p>z</p> => <p>x</p>^<p>y</p> + <p>z</p> => <p>x</p><p>z</p><p>y</p> => <p>xz[]y</p>
- * 		<p>x^y</p> + <img /> => <p>x</p>^<p>y</p> + <img /> => <p>x</p><img /><p>y</p>
- * 		<p>x</p><p>^</p><p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p> (no merging)
- * 		<p>x</p>[<img />]<p>z</p> + <p>y</p> => <p>x</p>^<p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p>
+ * ```html
+ * <p>x^</p> + <p>y</p> => <p>x</p><p>y</p> => <p>xy[]</p>
+ * <p>x^y</p> + <p>z</p> => <p>x</p>^<p>y</p> + <p>z</p> => <p>x</p><p>z</p><p>y</p> => <p>xz[]y</p>
+ * <p>x^y</p> + <img /> => <p>x</p>^<p>y</p> + <img /> => <p>x</p><img /><p>y</p>
+ * <p>x</p><p>^</p><p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p> (no merging)
+ * <p>x</p>[<img />]<p>z</p> + <p>y</p> => <p>x</p>^<p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p>
+ * ```
  *
  * If an instance of {@link module:engine/model/selection~Selection} is passed as `selectable` it will be modified
  * to the insertion selection (equal to a range to be selected after insertion).
@@ -35,13 +37,11 @@ import { LiveRange } from '../../index';
  * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertContent}
  * method's behavior.
  *
- * @param {module:engine/model/model~Model} model The model in context of which the insertion
- * should be performed.
- * @param {module:engine/model/documentfragment~DocumentFragment|module:engine/model/item~Item} content The content to insert.
- * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
- * Selection into which the content should be inserted.
- * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
- * @returns {module:engine/model/range~Range} Range which contains all the performed changes. This is a range that, if removed,
+ * @param model The model in context of which the insertion should be performed.
+ * @param content The content to insert.
+ * @param selectable Selection into which the content should be inserted.
+ * @param placeOrOffset Sets place or offset of the selection.
+ * @returns Range which contains all the performed changes. This is a range that, if removed,
  * would return the model to the state before the insertion. If no changes were preformed by `insertContent`, returns a range collapsed
  * at the insertion position.
  */
@@ -194,108 +194,46 @@ export default function insertContent(model, content, selectable, placeOrOffset)
 }
 /**
  * Utility class for performing content insertion.
- *
- * @private
  */
 class Insertion {
     constructor(model, writer, position) {
-        /**
-         * The model in context of which the insertion should be performed.
-         *
-         * @member {module:engine/model~Model} #model
-         */
-        this.model = model;
-        /**
-         * Batch to which operations will be added.
-         *
-         * @member {module:engine/controller/writer~Batch} #writer
-         */
-        this.writer = writer;
-        /**
-         * The position at which (or near which) the next node will be inserted.
-         *
-         * @member {module:engine/model/position~Position} #position
-         */
-        this.position = position;
-        /**
-         * Elements with which the inserted elements can be merged.
-         *
-         *		<p>x^</p><p>y</p> + <p>z</p> (can merge to <p>x</p>)
-         *		<p>x</p><p>^y</p> + <p>z</p> (can merge to <p>y</p>)
-         *		<p>x^y</p> + <p>z</p> (can merge to <p>xy</p> which will be split during the action,
-         *								so both its pieces will be added to this set)
-         *
-         *
-         * @member {Set} #canMergeWith
-         */
-        this.canMergeWith = new Set([this.position.parent]);
-        /**
-         * Schema of the model.
-         *
-         * @member {module:engine/model/schema~Schema} #schema
-         */
-        this.schema = model.schema;
-        /**
-         * The temporary DocumentFragment used for grouping multiple nodes for single insert operation.
-         *
-         * @private
-         * @type {module:engine/model/documentfragment~DocumentFragment}
-         */
-        this._documentFragment = writer.createDocumentFragment();
-        /**
-         * The current position in the temporary DocumentFragment.
-         *
-         * @private
-         * @type {module:engine/model/position~Position}
-         */
-        this._documentFragmentPosition = writer.createPositionAt(this._documentFragment, 0);
         /**
          * The reference to the first inserted node.
-         *
-         * @private
-         * @type {module:engine/model/node~Node}
          */
         this._firstNode = null;
         /**
          * The reference to the last inserted node.
-         *
-         * @private
-         * @type {module:engine/model/node~Node}
          */
         this._lastNode = null;
         /**
          * The reference to the last auto paragraph node.
-         *
-         * @private
-         * @type {module:engine/model/node~Node}
          */
         this._lastAutoParagraph = null;
         /**
          * The array of nodes that should be cleaned of not allowed attributes.
-         *
-         * @private
-         * @type {Array.<module:engine/model/node~Node>}
          */
         this._filterAttributesOf = [];
         /**
          * Beginning of the affected range. See {@link module:engine/model/utils/insertcontent~Insertion#getAffectedRange}.
-         *
-         * @private
-         * @member {module:engine/model/liveposition~LivePosition|null} #_affectedStart
          */
         this._affectedStart = null;
         /**
          * End of the affected range. See {@link module:engine/model/utils/insertcontent~Insertion#getAffectedRange}.
-         *
-         * @private
-         * @member {module:engine/model/liveposition~LivePosition|null} #_affectedEnd
          */
         this._affectedEnd = null;
+        this._nodeToSelect = null;
+        this.model = model;
+        this.writer = writer;
+        this.position = position;
+        this.canMergeWith = new Set([this.position.parent]);
+        this.schema = model.schema;
+        this._documentFragment = writer.createDocumentFragment();
+        this._documentFragmentPosition = writer.createPositionAt(this._documentFragment, 0);
     }
     /**
      * Handles insertion of a set of nodes.
      *
-     * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes to insert.
+     * @param nodes Nodes to insert.
      */
     handleNodes(nodes) {
         for (const node of Array.from(nodes)) {
@@ -317,8 +255,7 @@ class Insertion {
     /**
      * Updates the last node after the auto paragraphing.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The last auto paragraphing node.
+     * @param node The last auto paragraphing node.
      */
     _updateLastNodeFromAutoParagraph(node) {
         const positionAfterLastNode = this.writer.createPositionAfter(this._lastNode);
@@ -340,8 +277,6 @@ class Insertion {
     /**
      * Returns range to be selected after insertion.
      * Returns `null` if there is no valid range to select after insertion.
-     *
-     * @returns {module:engine/model/range~Range|null}
      */
     getSelectionRange() {
         if (this._nodeToSelect) {
@@ -352,8 +287,6 @@ class Insertion {
     /**
      * Returns a range which contains all the performed changes. This is a range that, if removed, would return the model to the state
      * before the insertion. Returns `null` if no changes were done.
-     *
-     * @returns {module:engine/model/range~Range|null}
      */
     getAffectedRange() {
         if (!this._affectedStart) {
@@ -374,9 +307,6 @@ class Insertion {
     }
     /**
      * Handles insertion of a single node.
-     *
-     * @private
-     * @param {module:engine/model/node~Node} node
      */
     _handleNode(node) {
         // Let's handle object in a special way.
@@ -409,8 +339,6 @@ class Insertion {
     }
     /**
      * Inserts the temporary DocumentFragment into the model.
-     *
-     * @private
      */
     _insertPartialFragment() {
         if (this._documentFragment.isEmpty) {
@@ -437,8 +365,7 @@ class Insertion {
         livePosition.detach();
     }
     /**
-     * @private
-     * @param {module:engine/model/element~Element} node The object element.
+     * @param node The object element.
      */
     _handleObject(node) {
         // Try finding it a place in the tree.
@@ -451,8 +378,7 @@ class Insertion {
         }
     }
     /**
-     * @private
-     * @param {module:engine/model/node~Node} node The disallowed node which needs to be handled.
+     * @param node The disallowed node which needs to be handled.
      */
     _handleDisallowedNode(node) {
         // If the node is an element, try inserting its children (strip the parent).
@@ -467,8 +393,7 @@ class Insertion {
     /**
      * Append a node to the temporary DocumentFragment.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The node to insert.
+     * @param node The node to insert.
      */
     _appendToFragment(node) {
         /* istanbul ignore if */
@@ -479,8 +404,8 @@ class Insertion {
              * Given node cannot be inserted on the given position.
              *
              * @error insertcontent-wrong-position
-             * @param {module:engine/model/node~Node} node Node to insert.
-             * @param {module:engine/model/position~Position} position Position to insert the node at.
+             * @param node Node to insert.
+             * @param position Position to insert the node at.
              */
             throw new CKEditorError('insertcontent-wrong-position', this, { node, position: this.position });
         }
@@ -501,9 +426,6 @@ class Insertion {
      *
      * This method is used before inserting a node or splitting a parent node. `_affectedStart` and `_affectedEnd` are also changed
      * during merging, but the logic there is more complicated so it is left out of this function.
-     *
-     * @private
-     * @param {module:engine/model/position~Position} position
      */
     _setAffectedBoundaries(position) {
         // Set affected boundaries stickiness so that those position will "expand" when something is inserted in between them:
@@ -528,8 +450,6 @@ class Insertion {
      *
      * After the content was inserted we may try to merge it with its siblings.
      * This should happen only if the selection was in those elements initially.
-     *
-     * @private
      */
     _mergeOnLeft() {
         const node = this._firstNode;
@@ -596,8 +516,6 @@ class Insertion {
      *
      * After the content was inserted we may try to merge it with its siblings.
      * This should happen only if the selection was in those elements initially.
-     *
-     * @private
      */
     _mergeOnRight() {
         const node = this._lastNode;
@@ -666,9 +584,7 @@ class Insertion {
     /**
      * Checks whether specified node can be merged with previous sibling element.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The node which could potentially be merged.
-     * @returns {Boolean}
+     * @param node The node which could potentially be merged.
      */
     _canMergeLeft(node) {
         const previousSibling = node.previousSibling;
@@ -679,9 +595,7 @@ class Insertion {
     /**
      * Checks whether specified node can be merged with next sibling element.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The node which could potentially be merged.
-     * @returns {Boolean}
+     * @param node The node which could potentially be merged.
      */
     _canMergeRight(node) {
         const nextSibling = node.nextSibling;
@@ -692,8 +606,7 @@ class Insertion {
     /**
      * Tries wrapping the node in a new paragraph and inserting it this way.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The node which needs to be autoparagraphed.
+     * @param node The node which needs to be autoparagraphed.
      */
     _tryAutoparagraphing(node) {
         const paragraph = this.writer.createElement('paragraph');
@@ -709,9 +622,7 @@ class Insertion {
      * Checks if a node can be inserted in the given position or it would be accepted if a paragraph would be inserted.
      * It also handles inserting the paragraph.
      *
-     * @private
-     * @param {module:engine/model/node~Node} node The node.
-     * @returns {Boolean} Whether an allowed position was found.
+     * @returns Whether an allowed position was found.
      * `false` is returned if the node isn't allowed at the current position or in auto paragraph, `true` if was.
      */
     _checkAndAutoParagraphToAllowedPosition(node) {
@@ -735,9 +646,7 @@ class Insertion {
         return true;
     }
     /**
-     * @private
-     * @param {module:engine/model/node~Node} node
-     * @returns {Boolean} Whether an allowed position was found.
+     * @returns Whether an allowed position was found.
      * `false` is returned if the node isn't allowed at any position up in the tree, `true` if was.
      */
     _checkAndSplitToAllowedPosition(node) {
@@ -786,10 +695,8 @@ class Insertion {
     /**
      * Gets the element in which the given node is allowed. It checks the passed element and all its ancestors.
      *
-     * @private
-     * @param {module:engine/model/element~Element} contextElement The element in which context the node should be checked.
-     * @param {module:engine/model/node~Node} childNode The node to check.
-     * @returns {module:engine/model/element~Element|null}
+     * @param contextElement The element in which context the node should be checked.
+     * @param childNode The node to check.
      */
     _getAllowedIn(contextElement, childNode) {
         if (this.schema.checkChild(contextElement, childNode)) {

package/src/model/utils/insertobject.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
  */
 /**
@@ -18,28 +18,25 @@ import { CKEditorError, first } from '@ckeditor/ckeditor5-utils';
  *
  * **Note**: For more documentation and examples, see {@link module:engine/model/model~Model#insertObject}.
  *
- * @param {module:engine/model/model~Model} model The model in context of which the insertion
- * should be performed.
- * @param {module:engine/model/element~Element} object An object to be inserted into the model document.
- * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
- * A selectable where the content should be inserted. If not specified, the current
+ * @param model The model in context of which the insertion should be performed.
+ * @param object An object to be inserted into the model document.
+ * @param selectable A selectable where the content should be inserted. If not specified, the current
  * {@link module:engine/model/document~Document#selection document selection} will be used instead.
- * @param {Number|'before'|'end'|'after'|'on'|'in'} placeOrOffset Specifies the exact place or offset for the insertion to take place,
- * relative to `selectable`.
- * @param {Object} [options] Additional options.
- * @param {'auto'|'before'|'after'} [options.findOptimalPosition] An option that, when set, adjusts the insertion position (relative to
+ * @param placeOrOffset Specifies the exact place or offset for the insertion to take place, relative to `selectable`.
+ * @param options Additional options.
+ * @param options.findOptimalPosition An option that, when set, adjusts the insertion position (relative to
  * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
  * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
  * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
  * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
  *
  * Note that this option works only for block objects. Inline objects are inserted into text and do not split blocks.
- * @param {'on'|'after'} [options.setSelection] An option that, when set, moves the
+ * @param options.setSelection An option that, when set, moves the
  * {@link module:engine/model/document~Document#selection document selection} after inserting the object.
  * * When `'on'`, the document selection will be set on the inserted object.
  * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
  * such text node, a paragraph will be created and the document selection will be moved inside it.
- * @returns {module:engine/model/range~Range} A range which contains all the performed changes. This is a range that, if removed,
+ * @returns A range which contains all the performed changes. This is a range that, if removed,
  * would return the model to the state before the insertion. If no changes were preformed by `insertObject()`, returns a range collapsed
  * at the insertion position.
  */
@@ -106,15 +103,16 @@ export default function insertObject(model, object, selectable, placeOrOffset, o
         return affectedRange;
     });
 }
-// Updates document selection based on given `place` parameter in relation to `contextElement` element.
-//
-// @private
-// @param {module:engine/model/writer~Writer} writer An instance of the model writer.
-// @param {module:engine/model/element~Element} contextElement An element to set the attributes on.
-// @param {'on'|'after'} place The place where selection should be set in relation to the `contextElement` element.
-// Value `on` will set selection on the passed `contextElement`. Value `after` will set selection after `contextElement`.
-// @param {Object} attributes Attributes keys and values to set on a paragraph that this function can create when
-// `place` parameter is equal to `after` but there is no element with `$text` node to set selection in.
+/**
+ * Updates document selection based on given `place` parameter in relation to `contextElement` element.
+ *
+ * @param writer An instance of the model writer.
+ * @param contextElement An element to set the attributes on.
+ * @param place The place where selection should be set in relation to the `contextElement` element.
+ * Value `on` will set selection on the passed `contextElement`. Value `after` will set selection after `contextElement`.
+ * @param attributes Attributes keys and values to set on a paragraph that this function can create when
+ * `place` parameter is equal to `after` but there is no element with `$text` node to set selection in.
+ */
 function updateSelection(writer, contextElement, place, paragraphAttributes) {
     const model = writer.model;
     if (place == 'on') {

package/src/model/utils/modifyselection.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
  */
 /**
@@ -38,14 +38,11 @@ const wordBoundaryCharacters = ' ,.?!:;"-()';
  * which change the {@link module:engine/model/model~Model#modifySelection}
  * method's behavior.
  *
- * @param {module:engine/model/model~Model} model The model in context of which
- * the selection modification should be performed.
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * The selection to modify.
- * @param {Object} [options]
- * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
- * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
- * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
+ * @param model The model in context of which the selection modification should be performed.
+ * @param selection The selection to modify.
+ * @param options.direction The direction in which the selection should be modified. Default 'forward'.
+ * @param options.unit The unit by which selection should be modified. Default 'character'.
+ * @param options.treatEmojiAsSingleUnit Whether multi-characer emoji sequences should be handled as single unit.
  */
 export default function modifySelection(model, selection, options = {}) {
     const schema = model.schema;
@@ -78,9 +75,9 @@ export default function modifySelection(model, selection, options = {}) {
         }
     }
 }
-// Checks whether the selection can be extended to the the walker's next value (next position).
-// @param {{ walker, unit, isForward, schema, treatEmojiAsSingleUnit }} data
-// @param {module:engine/view/treewalker~TreeWalkerValue} value
+/**
+ * Checks whether the selection can be extended to the the walker's next value (next position).
+ */
 function tryExtendingTo(data, value) {
     const { isForward, walker, unit, schema, treatEmojiAsSingleUnit } = data;
     const { type, item, nextPosition } = value;
@@ -117,12 +114,10 @@ function tryExtendingTo(data, value) {
         }
     }
 }
-// Finds a correct position by walking in a text node and checking whether selection can be extended to given position
-// or should be extended further.
-//
-// @param {module:engine/model/treewalker~TreeWalker} walker
-// @param {String} unit The unit by which selection should be modified.
-// @param {Boolean} treatEmojiAsSingleUnit
+/**
+ * Finds a correct position by walking in a text node and checking whether selection can be extended to given position
+ * or should be extended further.
+ */
 function getCorrectPosition(walker, unit, treatEmojiAsSingleUnit) {
     const textNode = walker.position.textNode;
     if (textNode) {
@@ -137,11 +132,10 @@ function getCorrectPosition(walker, unit, treatEmojiAsSingleUnit) {
     }
     return walker.position;
 }
-// Finds a correct position of a word break by walking in a text node and checking whether selection can be extended to given position
-// or should be extended further.
-//
-// @param {module:engine/model/treewalker~TreeWalker} walker
-// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+/**
+ * Finds a correct position of a word break by walking in a text node and checking whether selection can be extended to given position
+ * or should be extended further.
+ */
 function getCorrectWordBreakPosition(walker, isForward) {
     let textNode = walker.position.textNode;
     if (!textNode) {
@@ -176,21 +170,17 @@ function getSearchRange(start, isForward) {
         return new Range(searchEnd, start);
     }
 }
-// Checks if selection is on word boundary.
-//
-// @param {String} data The text node value to investigate.
-// @param {Number} offset Position offset.
-// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+/**
+ * Checks if selection is on word boundary.
+ */
 function isAtWordBoundary(data, offset, isForward) {
     // The offset to check depends on direction.
     const offsetToCheck = offset + (isForward ? 0 : -1);
     return wordBoundaryCharacters.includes(data.charAt(offsetToCheck));
 }
-// Checks if selection is on node boundary.
-//
-// @param {module:engine/model/text~Text} textNode The text node to investigate.
-// @param {Number} offset Position offset.
-// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+/**
+ * Checks if selection is on node boundary.
+ */
 function isAtNodeBoundary(textNode, offset, isForward) {
     return offset === (isForward ? textNode.offsetSize : 0);
 }