@ckeditor/ckeditor5-engine 35.4.0 → 36.0.1

package/src/model/utils/selection-post-fixer.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
  */
 /**
@@ -30,23 +30,25 @@ import Range from '../range';
  * See as an example a selection that starts in a P1 element and ends inside the text of a TD element
  * (`[` and `]` are range boundaries and `(l)` denotes an element defined as `isLimit=true`):
  *
- *		root
- *		 |- element P1
- *		 |   |- "foo"                                      root
- *		 |- element TABLE (l)                   P1         TABLE             P2
- *		 |   |- element TR (l)                 f o[o     TR      TR         b a r
- *		 |   |   |- element TD (l)                       TD      TD
- *		 |   |       |- "aaa"                          a]a a    b b b
- *		 |   |- element TR (l)
- *		 |   |   |- element TD (l)                           ||
- *		 |   |       |- "bbb"                                ||
- *		 |- element P2                                       VV
- *		 |   |- "bar"
- *		                                                   root
- *		                                        P1         TABLE]            P2
- *		                                       f o[o     TR      TR         b a r
- *		                                                 TD      TD
- *		                                               a a a    b b b
+ * ```
+ * root
+ *  |- element P1
+ *  |   |- "foo"                                      root
+ *  |- element TABLE (l)                   P1         TABLE             P2
+ *  |   |- element TR (l)                 f o[o     TR      TR         b a r
+ *  |   |   |- element TD (l)                       TD      TD
+ *  |   |       |- "aaa"                          a]a a    b b b
+ *  |   |- element TR (l)
+ *  |   |   |- element TD (l)                           ||
+ *  |   |       |- "bbb"                                ||
+ *  |- element P2                                       VV
+ *  |   |- "bar"
+ *                                                    root
+ *                                         P1         TABLE]            P2
+ *                                        f o[o     TR      TR         b a r
+ *                                                  TD      TD
+ *                                                a a a    b b b
+ * ```
  *
  * In the example above, the TABLE, TR and TD are defined as `isLimit=true` in the schema. The range which is not contained within
  * a single limit element must be expanded to select the outermost limit element. The range end is inside the text node of the TD element.
@@ -55,16 +57,13 @@ import Range from '../range';
  *
  * **Note** If the selection contains multiple ranges, the method returns a minimal set of ranges that are not intersecting after expanding
  * them to select `isLimit=true` elements.
- *
- * @param {module:engine/model/model~Model} model
  */
 export function injectSelectionPostFixer(model) {
     model.document.registerPostFixer(writer => selectionPostFixer(writer, model));
 }
-// The selection post-fixer.
-//
-// @param {module:engine/model/writer~Writer} writer
-// @param {module:engine/model/model~Model} model
+/**
+ * The selection post-fixer.
+ */
 function selectionPostFixer(writer, model) {
     const selection = model.document.selection;
     const schema = model.schema;
@@ -95,24 +94,25 @@ function selectionPostFixer(writer, model) {
     }
     return false;
 }
-// Tries fixing a range if it's incorrect.
-//
-// @param {module:engine/model/range~Range} range
-// @param {module:engine/model/schema~Schema} schema
-// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+/**
+ * Tries fixing a range if it's incorrect.
+ *
+ * @returns Returns fixed range or null if range is valid.
+ */
 function tryFixingRange(range, schema) {
     if (range.isCollapsed) {
         return tryFixingCollapsedRange(range, schema);
     }
     return tryFixingNonCollapsedRage(range, schema);
 }
-// Tries to fix collapsed ranges.
-//
-// * Fixes situation when a range is in a place where $text is not allowed
-//
-// @param {module:engine/model/range~Range} range Collapsed range to fix.
-// @param {module:engine/model/schema~Schema} schema
-// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+/**
+ * Tries to fix collapsed ranges.
+ *
+ * * Fixes situation when a range is in a place where $text is not allowed
+ *
+ * @param range Collapsed range to fix.
+ * @returns Returns fixed range or null if range is valid.
+ */
 function tryFixingCollapsedRange(range, schema) {
     const originalPosition = range.start;
     const nearestSelectionRange = schema.getNearestSelectionRange(originalPosition);
@@ -137,11 +137,12 @@ function tryFixingCollapsedRange(range, schema) {
     }
     return new Range(fixedPosition);
 }
-// Tries to fix an expanded range.
-//
-// @param {module:engine/model/range~Range} range Expanded range to fix.
-// @param {module:engine/model/schema~Schema} schema
-// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+/**
+ * Tries to fix an expanded range.
+ *
+ * @param range Expanded range to fix.
+ * @returns Returns fixed range or null if range is valid.
+ */
 function tryFixingNonCollapsedRage(range, schema) {
     const { start, end } = range;
     const isTextAllowedOnStart = schema.checkChild(start, '$text');
@@ -195,11 +196,9 @@ function tryFixingNonCollapsedRage(range, schema) {
     // Range was not fixed at this point so it is valid - ie it was placed around limit element already.
     return null;
 }
-// Finds the outer-most ancestor.
-//
-// @param {module:engine/model/node~Node} startingNode
-// @param {module:engine/model/schema~Schema} schema
-// @returns {module:engine/model/node~Node}
+/**
+ * Finds the outer-most ancestor.
+ */
 function findOutermostLimitAncestor(startingNode, schema) {
     let isLimitNode = startingNode;
     let parent = isLimitNode;
@@ -210,12 +209,9 @@ function findOutermostLimitAncestor(startingNode, schema) {
     }
     return isLimitNode;
 }
-// Checks whether any of range boundaries is placed around non-limit elements.
-//
-// @param {module:engine/model/position~Position} start
-// @param {module:engine/model/position~Position} end
-// @param {module:engine/model/schema~Schema} schema
-// @returns {Boolean}
+/**
+ * Checks whether any of range boundaries is placed around non-limit elements.
+ */
 function checkSelectionOnNonLimitElements(start, end, schema) {
     const startIsOnBlock = (start.nodeAfter && !schema.isLimit(start.nodeAfter)) || schema.checkChild(start, '$text');
     const endIsOnBlock = (end.nodeBefore && !schema.isLimit(end.nodeBefore)) || schema.checkChild(end, '$text');
@@ -225,8 +221,8 @@ function checkSelectionOnNonLimitElements(start, end, schema) {
 /**
  * Returns a minimal non-intersecting array of ranges without duplicates.
  *
- * @param {Array.<module:engine/model/range~Range>} Ranges to merge.
- * @returns {Array.<module:engine/model/range~Range>} Array of unique and nonIntersecting ranges.
+ * @param ranges Ranges to merge.
+ * @returns Array of unique and non-intersecting ranges.
  */
 export function mergeIntersectingRanges(ranges) {
     const rangesToMerge = [...ranges];
@@ -254,11 +250,9 @@ export function mergeIntersectingRanges(ranges) {
     const nonIntersectingRanges = rangesToMerge.filter((_, index) => !rangeIndexesToRemove.has(index));
     return nonIntersectingRanges;
 }
-// Checks if node exists and if it's a selectable.
-//
-// @param {module:engine/model/node~Node} node
-// @param {module:engine/model/schema~Schema} schema
-// @returns {Boolean}
+/**
+ * Checks if node exists and if it's a selectable.
+ */
 function isSelectable(node, schema) {
     return node && schema.isSelectable(node);
 }