@ckeditor/ckeditor5-engine 45.2.1-alpha.9 → 46.0.0-alpha.0

package/src/model/position.js

@@ -5,37 +5,37 @@
 /**
  * @module engine/model/position
  */
-import TypeCheckable from './typecheckable.js';
-import TreeWalker from './treewalker.js';
+import { ModelTypeCheckable } from './typecheckable.js';
+import { ModelTreeWalker } from './treewalker.js';
 import { CKEditorError, compareArrays } from '@ckeditor/ckeditor5-utils';
 /**
  * Represents a position in the model tree.
  *
- * A position is represented by its {@link module:engine/model/position~Position#root} and
- * a {@link module:engine/model/position~Position#path} in that root.
+ * A position is represented by its {@link module:engine/model/position~ModelPosition#root} and
+ * a {@link module:engine/model/position~ModelPosition#path} in that root.
  *
  * You can create position instances via its constructor or the `createPosition*()` factory methods of
- * {@link module:engine/model/model~Model} and {@link module:engine/model/writer~Writer}.
+ * {@link module:engine/model/model~Model} and {@link module:engine/model/writer~ModelWriter}.
  *
  * **Note:** Position is based on offsets, not indexes. This means that a position between two text nodes
- * `foo` and `bar` has offset `3`, not `1`. See {@link module:engine/model/position~Position#path} for more information.
+ * `foo` and `bar` has offset `3`, not `1`. See {@link module:engine/model/position~ModelPosition#path} for more information.
  *
- * Since a position in the model is represented by a {@link module:engine/model/position~Position#root position root} and
- * {@link module:engine/model/position~Position#path position path} it is possible to create positions placed in non-existing places.
+ * Since a position in the model is represented by a {@link module:engine/model/position~ModelPosition#root position root} and
+ * {@link module:engine/model/position~ModelPosition#path position path} it is possible to create positions placed in non-existing places.
  * This requirement is important for operational transformation algorithms.
  *
  * Also, {@link module:engine/model/operation/operation~Operation operations}
- * kept in the {@link module:engine/model/document~Document#history document history}
+ * kept in the {@link module:engine/model/document~ModelDocument#history document history}
  * are storing positions (and ranges) which were correct when those operations were applied, but may not be correct
  * after the document has changed.
  *
- * When changes are applied to the model, it may also happen that {@link module:engine/model/position~Position#parent position parent}
+ * When changes are applied to the model, it may also happen that {@link module:engine/model/position~ModelPosition#parent position parent}
  * will change even if position path has not changed. Keep in mind, that if a position leads to non-existing element,
- * {@link module:engine/model/position~Position#parent} and some other properties and methods will throw errors.
+ * {@link module:engine/model/position~ModelPosition#parent} and some other properties and methods will throw errors.
  *
  * In most cases, position with wrong path is caused by an error in code, but it is sometimes needed, as described above.
  */
-export default class Position extends TypeCheckable {
+export class ModelPosition extends ModelTypeCheckable {
     /**
      * Root of the position path.
      */
@@ -43,9 +43,9 @@ export default class Position extends TypeCheckable {
     /**
      * Position of the node in the tree. **Path contains offsets, not indexes.**
      *
-     * Position can be placed before, after or in a {@link module:engine/model/node~Node node} if that node has
-     * {@link module:engine/model/node~Node#offsetSize} greater than `1`. Items in position path are
-     * {@link module:engine/model/node~Node#startOffset starting offsets} of position ancestors, starting from direct root children,
+     * Position can be placed before, after or in a {@link module:engine/model/node~ModelNode node} if that node has
+     * {@link module:engine/model/node~ModelNode#offsetSize} greater than `1`. Items in position path are
+     * {@link module:engine/model/node~ModelNode#startOffset starting offsets} of position ancestors, starting from direct root children,
      * down to the position offset in it's parent.
      *
      * ```
@@ -58,7 +58,7 @@ export default class Position extends TypeCheckable {
      *        |- bar    before: [ 1, 1, 0 ]   after: [ 1, 1, 3 ]
      * ```
      *
-     * `foo` and `bar` are representing {@link module:engine/model/text~Text text nodes}. Since text nodes has offset size
+     * `foo` and `bar` are representing {@link module:engine/model/text~ModelText text nodes}. Since text nodes has offset size
      * greater than `1` you can place position offset between their start and end:
      *
      * ```
@@ -73,15 +73,15 @@ export default class Position extends TypeCheckable {
      */
     path;
     /**
-     * Position stickiness. See {@link module:engine/model/position~PositionStickiness}.
+     * Position stickiness. See {@link module:engine/model/position~ModelPositionStickiness}.
      */
     stickiness;
     /**
      * Creates a position.
      *
      * @param root Root of the position.
-     * @param path Position path. See {@link module:engine/model/position~Position#path}.
-     * @param stickiness Position stickiness. See {@link module:engine/model/position~PositionStickiness}.
+     * @param path Position path. See {@link module:engine/model/position~ModelPosition#path}.
+     * @param stickiness Position stickiness. See {@link module:engine/model/position~ModelPositionStickiness}.
      */
     constructor(root, path, stickiness = 'toNone') {
         super();
@@ -117,8 +117,8 @@ export default class Position extends TypeCheckable {
         this.stickiness = stickiness;
     }
     /**
-     * Offset at which this position is located in its {@link module:engine/model/position~Position#parent parent}. It is equal
-     * to the last item in position {@link module:engine/model/position~Position#path path}.
+     * Offset at which this position is located in its {@link module:engine/model/position~ModelPosition#parent parent}. It is equal
+     * to the last item in position {@link module:engine/model/position~ModelPosition#path path}.
      *
      * @type {Number}
      */
@@ -132,7 +132,7 @@ export default class Position extends TypeCheckable {
      * Parent element of this position.
      *
      * Keep in mind that `parent` value is calculated when the property is accessed.
-     * If {@link module:engine/model/position~Position#path position path}
+     * If {@link module:engine/model/position~ModelPosition#path position path}
      * leads to a non-existing element, `parent` property will throw error.
      *
      * Also it is a good idea to cache `parent` property if it is used frequently in an algorithm (i.e. in a long loop).
@@ -147,15 +147,16 @@ export default class Position extends TypeCheckable {
                  * a correct place in the tree and hence, some of its methods and getters cannot work correctly.
                  *
                  * **Note**: Unlike DOM and view positions, in the model, the
-                 * {@link module:engine/model/position~Position#parent position's parent} is always an element or a document fragment.
-                 * The last offset in the {@link module:engine/model/position~Position#path position's path} is the point in this element
+                 * {@link module:engine/model/position~ModelPosition#parent position's parent} is always an element or a document fragment.
+                 * The last offset in the
+                 * {@link module:engine/model/position~ModelPosition#path position's path} is the point in this element
                  * where this position points.
                  *
                  * Read more about model positions and offsets in
                  * the {@glink framework/architecture/editing-engine#indexes-and-offsets Editing engine architecture} guide.
                  *
                  * @error model-position-path-incorrect
-                 * @param {module:engine/model/position~Position} position The incorrect position.
+                 * @param {module:engine/model/position~ModelPosition} position The incorrect position.
                  */
                 throw new CKEditorError('model-position-path-incorrect', this, { position: this });
             }
@@ -166,15 +167,15 @@ export default class Position extends TypeCheckable {
         return parent;
     }
     /**
-     * Position {@link module:engine/model/position~Position#offset offset} converted to an index in position's parent node. It is
-     * equal to the {@link module:engine/model/node~Node#index index} of a node after this position. If position is placed
+     * Position {@link module:engine/model/position~ModelPosition#offset offset} converted to an index in position's parent node. It is
+     * equal to the {@link module:engine/model/node~ModelNode#index index} of a node after this position. If position is placed
      * in text node, position index is equal to the index of that text node.
      */
     get index() {
         return this.parent.offsetToIndex(this.offset);
     }
     /**
-     * Returns {@link module:engine/model/text~Text text node} instance in which this position is placed or `null` if this
+     * Returns {@link module:engine/model/text~ModelText text node} instance in which this position is placed or `null` if this
      * position is not in a text node.
      */
     get textNode() {
@@ -197,13 +198,13 @@ export default class Position extends TypeCheckable {
         return getNodeBeforePosition(this, parent, getTextNodeAtPosition(this, parent));
     }
     /**
-     * Is `true` if position is at the beginning of its {@link module:engine/model/position~Position#parent parent}, `false` otherwise.
+     * Is `true` if position is at the beginning of its {@link module:engine/model/position~ModelPosition#parent parent}, `false` otherwise.
      */
     get isAtStart() {
         return this.offset === 0;
     }
     /**
-     * Is `true` if position is at the end of its {@link module:engine/model/position~Position#parent parent}, `false` otherwise.
+     * Is `true` if position is at the end of its {@link module:engine/model/position~ModelPosition#parent parent}, `false` otherwise.
      */
     get isAtEnd() {
         return this.offset == this.parent.maxOffset;
@@ -247,7 +248,7 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Gets the farthest position which matches the callback using
-     * {@link module:engine/model/treewalker~TreeWalker TreeWalker}.
+     * {@link module:engine/model/treewalker~ModelTreeWalker TreeWalker}.
      *
      * For example:
      *
@@ -262,21 +263,21 @@ export default class Position extends TypeCheckable {
      * // Do not move the position.
      * ```
      *
-     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~ModelTreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
-     * @param options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
+     * @param options Object with configuration options. See {@link module:engine/model/treewalker~ModelTreeWalker}.
      *
      * @returns The position after the last item which matches the `skip` callback test.
      */
     getLastMatchingPosition(skip, options = {}) {
         options.startPosition = this;
-        const treeWalker = new TreeWalker(options);
+        const treeWalker = new ModelTreeWalker(options);
         treeWalker.skip(skip);
         return treeWalker.position;
     }
     /**
-     * Returns a path to this position's parent. Parent path is equal to position {@link module:engine/model/position~Position#path path}
-     * but without the last item.
+     * Returns a path to this position's parent. Parent path is equal to position
+     * {@link module:engine/model/position~ModelPosition#path path} but without the last item.
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
@@ -331,7 +332,7 @@ export default class Position extends TypeCheckable {
         return this.path.slice(0, diffAt);
     }
     /**
-     * Returns an {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
+     * Returns an {@link module:engine/model/element~ModelElement} or {@link module:engine/model/documentfragment~ModelDocumentFragment}
      * which is a common ancestor of both positions. The {@link #root roots} of these two positions must be identical.
      *
      * @param position The second position.
@@ -365,7 +366,7 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @see module:engine/model/position~Position#isBefore
+     * @see module:engine/model/position~ModelPosition#isBefore
      * @param  otherPosition Position to compare with.
      * @returns True if this position is after given position.
      */
@@ -496,7 +497,7 @@ export default class Position extends TypeCheckable {
      *
      * The new position's parameters are updated accordingly to the effect of the `operation`.
      *
-     * For example, if `n` nodes are inserted before the position, the returned position {@link ~Position#offset} will be
+     * For example, if `n` nodes are inserted before the position, the returned position {@link ~ModelPosition#offset} will be
      * increased by `n`. If the position was in a merged element, it will be accordingly moved to the new element, etc.
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
@@ -522,7 +523,7 @@ export default class Position extends TypeCheckable {
                 result = this._getTransformedByMergeOperation(operation);
                 break;
             default:
-                result = Position._createAt(this);
+                result = ModelPosition._createAt(this);
                 break;
         }
         return result;
@@ -581,7 +582,7 @@ export default class Position extends TypeCheckable {
             }
         }
         else if (this.isEqual(operation.deletionPosition)) {
-            pos = Position._createAt(operation.deletionPosition);
+            pos = ModelPosition._createAt(operation.deletionPosition);
         }
         else {
             pos = this._getTransformedByMove(operation.deletionPosition, operation.graveyardPosition, 1);
@@ -598,7 +599,7 @@ export default class Position extends TypeCheckable {
      * @returns Transformed position or `null`.
      */
     _getTransformedByDeletion(deletePosition, howMany) {
-        const transformed = Position._createAt(this);
+        const transformed = ModelPosition._createAt(this);
         // This position can't be affected if deletion was in a different root.
         if (this.root != deletePosition.root) {
             return transformed;
@@ -644,7 +645,7 @@ export default class Position extends TypeCheckable {
      * @returns Transformed position.
      */
     _getTransformedByInsertion(insertPosition, howMany) {
-        const transformed = Position._createAt(this);
+        const transformed = ModelPosition._createAt(this);
         // This position can't be affected if insertion was in a different root.
         if (this.root != insertPosition.root) {
             return transformed;
@@ -682,7 +683,7 @@ export default class Position extends TypeCheckable {
         targetPosition = targetPosition._getTransformedByDeletion(sourcePosition, howMany);
         if (sourcePosition.isEqual(targetPosition)) {
             // If `targetPosition` is equal to `sourcePosition` this isn't really any move. Just return position as it is.
-            return Position._createAt(this);
+            return ModelPosition._createAt(this);
         }
         // Moving a range removes nodes from their original position. We acknowledge this by proper transformation.
         const transformed = this._getTransformedByDeletion(sourcePosition, howMany);
@@ -733,7 +734,7 @@ export default class Position extends TypeCheckable {
     _getCombined(source, target) {
         const i = source.path.length - 1;
         // The first part of a path to combined position is a path to the place where nodes were moved.
-        const combined = Position._createAt(target);
+        const combined = ModelPosition._createAt(target);
         combined.stickiness = this.stickiness;
         // Then we have to update the rest of the path.
         // Fix the offset because this position might be after `from` position and we have to reflect that.
@@ -762,23 +763,24 @@ export default class Position extends TypeCheckable {
     /**
      * Creates position at the given location. The location can be specified as:
      *
-     * * a {@link module:engine/model/position~Position position},
+     * * a {@link module:engine/model/position~ModelPosition position},
      * * parent element and offset (offset defaults to `0`),
      * * parent element and `'end'` (sets position at the end of that element),
-     * * {@link module:engine/model/item~Item model item} and `'before'` or `'after'` (sets position before or after given model item).
+     * * {@link module:engine/model/item~ModelItem model item} and `'before'` or `'after'` (sets position before or after given model item).
      *
      * This method is a shortcut to other factory methods such as:
      *
-     * * {@link module:engine/model/position~Position._createBefore},
-     * * {@link module:engine/model/position~Position._createAfter}.
+     * * {@link module:engine/model/position~ModelPosition._createBefore},
+     * * {@link module:engine/model/position~ModelPosition._createAfter}.
      *
      * @internal
-     * @param offset Offset or one of the flags. Used only when the first parameter is a {@link module:engine/model/item~Item model item}.
-     * @param stickiness Position stickiness. Used only when the first parameter is a {@link module:engine/model/item~Item model item}.
+     * @param offset Offset or one of the flags. Used only when the first parameter
+     * is a {@link module:engine/model/item~ModelItem model item}.
+     * @param stickiness Position stickiness. Used only when the first parameter is a {@link module:engine/model/item~ModelItem model item}.
      */
     static _createAt(itemOrPosition, offset, stickiness = 'toNone') {
         if (itemOrPosition.is('model:position')) {
-            return new Position(itemOrPosition.root, itemOrPosition.path, itemOrPosition.stickiness);
+            return new ModelPosition(itemOrPosition.root, itemOrPosition.path, itemOrPosition.stickiness);
         }
         else {
             const node = itemOrPosition;
@@ -814,7 +816,7 @@ export default class Position extends TypeCheckable {
         }
     }
     /**
-     * Creates a new position, after given {@link module:engine/model/item~Item model item}.
+     * Creates a new position, after given {@link module:engine/model/item~ModelItem model item}.
      *
      * @internal
      * @param item Item after which the position should be placed.
@@ -826,14 +828,14 @@ export default class Position extends TypeCheckable {
              * You cannot make a position after a root element.
              *
              * @error model-position-after-root
-             * @param {module:engine/model/rootelement~RootElement} root The root element..
+             * @param {module:engine/model/rootelement~ModelRootElement} root The root element..
              */
             throw new CKEditorError('model-position-after-root', [this, item], { root: item });
         }
         return this._createAt(item.parent, item.endOffset, stickiness);
     }
     /**
-     * Creates a new position, before the given {@link module:engine/model/item~Item model item}.
+     * Creates a new position, before the given {@link module:engine/model/item~ModelItem model item}.
      *
      * @internal
      * @param item Item before which the position should be placed.
@@ -845,7 +847,7 @@ export default class Position extends TypeCheckable {
              * You cannot make a position before a root element.
              *
              * @error model-position-before-root
-             * @param {module:engine/model/rootelement~RootElement} root The root element..
+             * @param {module:engine/model/rootelement~ModelRootElement} root The root element..
              */
             throw new CKEditorError('model-position-before-root', item, { root: item });
         }
@@ -860,7 +862,7 @@ export default class Position extends TypeCheckable {
      */
     static fromJSON(json, doc) {
         if (json.root === '$graveyard') {
-            const pos = new Position(doc.graveyard, json.path);
+            const pos = new ModelPosition(doc.graveyard, json.path);
             pos.stickiness = json.stickiness;
             return pos;
         }
@@ -873,12 +875,12 @@ export default class Position extends TypeCheckable {
              */
             throw new CKEditorError('model-position-fromjson-no-root', doc, { rootName: json.root });
         }
-        return new Position(doc.getRoot(json.root), json.path, json.stickiness);
+        return new ModelPosition(doc.getRoot(json.root), json.path, json.stickiness);
     }
 }
 // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
 // Proper overload would interfere with that.
-Position.prototype.is = function (type) {
+ModelPosition.prototype.is = function (type) {
     return type === 'position' || type === 'model:position';
 };
 /**
@@ -886,8 +888,8 @@ Position.prototype.is = function (type) {
  *
  * This is a helper function optimized to reuse the position parent instance for performance reasons.
  *
- * Normally, you should use {@link module:engine/model/position~Position#textNode `Position#textNode`}.
- * If you start hitting performance issues with {@link module:engine/model/position~Position#parent `Position#parent`}
+ * Normally, you should use {@link module:engine/model/position~ModelPosition#textNode `Position#textNode`}.
+ * If you start hitting performance issues with {@link module:engine/model/position~ModelPosition#parent `Position#parent`}
  * check if your algorithm does not access it multiple times (which can happen directly or indirectly via other position properties).
  *
  * See https://github.com/ckeditor/ckeditor5/issues/6579.
@@ -899,6 +901,7 @@ Position.prototype.is = function (type) {
  *
  * @param position
  * @param positionParent The parent of the given position.
+ * @internal
  */
 export function getTextNodeAtPosition(position, positionParent) {
     const node = positionParent.getChildAtOffset(position.offset);
@@ -913,9 +916,9 @@ export function getTextNodeAtPosition(position, positionParent) {
  * This is a helper function optimized to reuse the position parent instance and the calculation of the text node at the
  * specific position for performance reasons.
  *
- * Normally, you should use {@link module:engine/model/position~Position#nodeAfter `Position#nodeAfter`}.
- * If you start hitting performance issues with {@link module:engine/model/position~Position#parent `Position#parent`} and/or
- * {@link module:engine/model/position~Position#textNode `Position#textNode`}
+ * Normally, you should use {@link module:engine/model/position~ModelPosition#nodeAfter `Position#nodeAfter`}.
+ * If you start hitting performance issues with {@link module:engine/model/position~ModelPosition#parent `Position#parent`} and/or
+ * {@link module:engine/model/position~ModelPosition#textNode `Position#textNode`}
  * check if your algorithm does not access those properties multiple times
  * (which can happen directly or indirectly via other position properties).
  *
@@ -929,6 +932,7 @@ export function getTextNodeAtPosition(position, positionParent) {
  * @param position Position to check.
  * @param positionParent The parent of the given position.
  * @param textNode Text node at the given position.
+ * @internal
  */
 export function getNodeAfterPosition(position, positionParent, textNode) {
     if (textNode !== null) {
@@ -949,6 +953,7 @@ export function getNodeAfterPosition(position, positionParent, textNode) {
  * @param position Position to check.
  * @param positionParent The parent of the given position.
  * @param textNode Text node at the given position.
+ * @internal
  */
 export function getNodeBeforePosition(position, positionParent, textNode) {
     if (textNode !== null) {