@ckeditor/ckeditor5-engine 43.2.0 → 43.3.0-alpha.0

package/dist/model/documentfragment.d.ts

@@ -97,10 +97,17 @@ export default class DocumentFragment extends TypeCheckable implements Iterable<
     /**
      * Gets the child at the given index. Returns `null` if incorrect index was passed.
      *
-     * @param index Index of child.
+     * @param index Index in this document fragment.
      * @returns Child node.
      */
     getChild(index: number): Node | null;
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this document fragment.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset: number): Node | null;
     /**
      * Returns an iterator that iterates over all of this document fragment's children.
      */

package/dist/model/element.d.ts

@@ -51,9 +51,19 @@ export default class Element extends Node {
      */
     get isEmpty(): boolean;
     /**
-     * Gets the child at the given index.
+     * Gets the child at the given index. Returns `null` if incorrect index was passed.
+     *
+     * @param index Index in this element.
+     * @returns Child node.
      */
     getChild(index: number): Node | null;
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this element.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset: number): Node | null;
     /**
      * Returns an iterator that iterates over all of this element's children.
      */

package/dist/model/node.d.ts

@@ -56,6 +56,18 @@ export default abstract class Node extends TypeCheckable {
      * Attributes set on this node.
      */
     private _attrs;
+    /**
+     * Index of this node in its parent or `null` if the node has no parent.
+     *
+     * @internal
+     */
+    _index: number | null;
+    /**
+     * Offset at which this node starts in its parent or `null` if the node has no parent.
+     *
+     * @internal
+     */
+    _startOffset: number | null;
     /**
      * Creates a model node.
      *
@@ -70,28 +82,24 @@ export default abstract class Node extends TypeCheckable {
     get document(): Document | null;
     /**
      * Index of this node in its parent or `null` if the node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get index(): number | null;
     /**
      * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
      * of all its previous siblings. Equals to `null` if node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get startOffset(): number | null;
     /**
-     * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
-     * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
-     * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
-     * than one entity, i.e. {@link module:engine/model/text~Text text node}.
+     * Offset size of this node.
+     *
+     * Represents how much "offset space" is occupied by the node in its parent. It is important for
+     * {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position can be placed between
+     * that node start and end. `offsetSize` greater than `1` is for nodes that represents more than one entity, i.e.
+     * a {@link module:engine/model/text~Text text node}.
      */
     get offsetSize(): number;
     /**
-     * Offset at which this node ends in it's parent. It is equal to the sum of this node's
+     * Offset at which this node ends in its parent. It is equal to the sum of this node's
      * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
      * Equals to `null` if the node has no parent.
      */
@@ -208,7 +216,7 @@ export default abstract class Node extends TypeCheckable {
      */
     _clone(_deep?: boolean): Node;
     /**
-     * Removes this node from it's parent.
+     * Removes this node from its parent.
      *
      * @internal
      * @see module:engine/model/writer~Writer#remove
@@ -248,11 +256,6 @@ export default abstract class Node extends TypeCheckable {
      */
     _clearAttributes(): void;
 }
-/**
- * The node's parent does not contain this node.
- *
- * @error model-node-not-found-in-parent
- */
 /**
  * Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
  */

package/dist/model/nodelist.d.ts

@@ -21,7 +21,15 @@ export default class NodeList implements Iterable<Node> {
      */
     private _nodes;
     /**
-     * Creates an empty node list.
+     * This array maps numbers (offsets) to node that is placed at that offset.
+     *
+     * This array is similar to `_nodes` with the difference that one node may occupy multiple consecutive items in the array.
+     *
+     * This array is needed to quickly retrieve a node that is placed at given offset.
+     */
+    private _offsetToNode;
+    /**
+     * Creates a node list.
      *
      * @internal
      * @param nodes Nodes contained in this node list.
@@ -46,26 +54,33 @@ export default class NodeList implements Iterable<Node> {
      */
     getNode(index: number): Node | null;
     /**
-     * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+     * Gets the node at the given offset. Returns `null` if incorrect offset was passed.
+     */
+    getNodeAtOffset(offset: number): Node | null;
+    /**
+     * Returns an index of the given node or `null` if given node does not have a parent.
+     *
+     * This is an alias to {@link module:engine/model/node~Node#index}.
      */
     getNodeIndex(node: Node): number | null;
     /**
-     * Returns the starting offset of given node. Starting offset is equal to the sum of
-     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+     * Returns the offset at which given node is placed in its parent or `null` if given node does not have a parent.
+     *
+     * This is an alias to {@link module:engine/model/node~Node#startOffset}.
      */
     getNodeStartOffset(node: Node): number | null;
     /**
      * Converts index to offset in node list.
      *
-     * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
-     * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `model-nodelist-index-out-of-bounds` if given index is less
+     * than `0` or more than {@link #length}.
      */
     indexToOffset(index: number): number;
     /**
      * Converts offset in node list to index.
      *
-     * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
-     * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `model-nodelist-offset-out-of-bounds` if given offset is less
+     * than `0` or more than {@link #maxOffset}.
      */
     offsetToIndex(offset: number): number;
     /**

package/dist/model/position.d.ts

@@ -128,11 +128,11 @@ export default class Position extends TypeCheckable {
      */
     get textNode(): Text | null;
     /**
-     * Node directly after this position or `null` if this position is in text node.
+     * Node directly after this position. Returns `null` if this position is at the end of its parent, or if it is in a text node.
      */
     get nodeAfter(): Node | null;
     /**
-     * Node directly before this position or `null` if this position is in text node.
+     * Node directly before this position. Returns `null` if this position is at the start of its parent, or if it is in a text node.
      */
     get nodeBefore(): Node | null;
     /**
@@ -143,6 +143,10 @@ export default class Position extends TypeCheckable {
      * Is `true` if position is at the end of its {@link module:engine/model/position~Position#parent parent}, `false` otherwise.
      */
     get isAtEnd(): boolean;
+    /**
+     * Checks whether the position is valid in current model tree, that is whether it points to an existing place in the model.
+     */
+    isValid(): boolean;
     /**
      * Checks whether this position is before or after given position.
      *
@@ -500,6 +504,7 @@ export type PositionStickiness = 'toNone' | 'toNext' | 'toPrevious';
  * * {@link module:engine/model/position~getNodeAfterPosition}
  * * {@link module:engine/model/position~getNodeBeforePosition}
  *
+ * @param position
  * @param positionParent The parent of the given position.
  */
 export declare function getTextNodeAtPosition(position: Position, positionParent: Element | DocumentFragment): Text | null;
@@ -522,6 +527,7 @@ export declare function getTextNodeAtPosition(position: Position, positionParent
  * * {@link module:engine/model/position~getTextNodeAtPosition}
  * * {@link module:engine/model/position~getNodeBeforePosition}
  *
+ * @param position Position to check.
  * @param positionParent The parent of the given position.
  * @param textNode Text node at the given position.
  */
@@ -536,6 +542,7 @@ export declare function getNodeAfterPosition(position: Position, positionParent:
  * * {@link module:engine/model/position~getTextNodeAtPosition}
  * * {@link module:engine/model/position~getNodeAfterPosition}
  *
+ * @param position Position to check.
  * @param positionParent The parent of the given position.
  * @param textNode Text node at the given position.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "43.2.0",
+  "version": "43.3.0-alpha.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -24,7 +24,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "43.2.0",
+    "@ckeditor/ckeditor5-utils": "43.3.0-alpha.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",

package/src/model/document.js

@@ -319,7 +319,8 @@ export default class Document extends /* #__PURE__ */ EmitterMixin() {
      * @returns `true` if `range` is valid, `false` otherwise.
      */
     _validateSelectionRange(range) {
-        return validateTextNodePosition(range.start) && validateTextNodePosition(range.end);
+        return range.start.isValid() && range.end.isValid() &&
+            validateTextNodePosition(range.start) && validateTextNodePosition(range.end);
     }
     /**
      * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.

package/src/model/documentfragment.d.ts

@@ -93,10 +93,17 @@ export default class DocumentFragment extends TypeCheckable implements Iterable<
     /**
      * Gets the child at the given index. Returns `null` if incorrect index was passed.
      *
-     * @param index Index of child.
+     * @param index Index in this document fragment.
      * @returns Child node.
      */
     getChild(index: number): Node | null;
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this document fragment.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset: number): Node | null;
     /**
      * Returns an iterator that iterates over all of this document fragment's children.
      */

package/src/model/documentfragment.js

@@ -115,12 +115,21 @@ export default class DocumentFragment extends TypeCheckable {
     /**
      * Gets the child at the given index. Returns `null` if incorrect index was passed.
      *
-     * @param index Index of child.
+     * @param index Index in this document fragment.
      * @returns Child node.
      */
     getChild(index) {
         return this._children.getNode(index);
     }
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this document fragment.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset) {
+        return this._children.getNodeAtOffset(offset);
+    }
     /**
      * Returns an iterator that iterates over all of this document fragment's children.
      */
@@ -168,8 +177,8 @@ export default class DocumentFragment extends TypeCheckable {
     getNodeByPath(relativePath) {
         // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
         let node = this;
-        for (const index of relativePath) {
-            node = node.getChild(node.offsetToIndex(index));
+        for (const offset of relativePath) {
+            node = node.getChildAtOffset(offset);
         }
         return node;
     }

package/src/model/element.d.ts

@@ -47,9 +47,19 @@ export default class Element extends Node {
      */
     get isEmpty(): boolean;
     /**
-     * Gets the child at the given index.
+     * Gets the child at the given index. Returns `null` if incorrect index was passed.
+     *
+     * @param index Index in this element.
+     * @returns Child node.
      */
     getChild(index: number): Node | null;
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this element.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset: number): Node | null;
     /**
      * Returns an iterator that iterates over all of this element's children.
      */

package/src/model/element.js

@@ -59,11 +59,23 @@ export default class Element extends Node {
         return this.childCount === 0;
     }
     /**
-     * Gets the child at the given index.
+     * Gets the child at the given index. Returns `null` if incorrect index was passed.
+     *
+     * @param index Index in this element.
+     * @returns Child node.
      */
     getChild(index) {
         return this._children.getNode(index);
     }
+    /**
+     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
+     *
+     * @param offset Offset in this element.
+     * @returns Child node.
+     */
+    getChildAtOffset(offset) {
+        return this._children.getNodeAtOffset(offset);
+    }
     /**
      * Returns an iterator that iterates over all of this element's children.
      */
@@ -124,8 +136,8 @@ export default class Element extends Node {
     getNodeByPath(relativePath) {
         // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
         let node = this;
-        for (const index of relativePath) {
-            node = node.getChild(node.offsetToIndex(index));
+        for (const offset of relativePath) {
+            node = node.getChildAtOffset(offset);
         }
         return node;
     }

package/src/model/node.d.ts

@@ -52,6 +52,18 @@ export default abstract class Node extends TypeCheckable {
      * Attributes set on this node.
      */
     private _attrs;
+    /**
+     * Index of this node in its parent or `null` if the node has no parent.
+     *
+     * @internal
+     */
+    _index: number | null;
+    /**
+     * Offset at which this node starts in its parent or `null` if the node has no parent.
+     *
+     * @internal
+     */
+    _startOffset: number | null;
     /**
      * Creates a model node.
      *
@@ -66,28 +78,24 @@ export default abstract class Node extends TypeCheckable {
     get document(): Document | null;
     /**
      * Index of this node in its parent or `null` if the node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get index(): number | null;
     /**
      * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
      * of all its previous siblings. Equals to `null` if node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get startOffset(): number | null;
     /**
-     * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
-     * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
-     * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
-     * than one entity, i.e. {@link module:engine/model/text~Text text node}.
+     * Offset size of this node.
+     *
+     * Represents how much "offset space" is occupied by the node in its parent. It is important for
+     * {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position can be placed between
+     * that node start and end. `offsetSize` greater than `1` is for nodes that represents more than one entity, i.e.
+     * a {@link module:engine/model/text~Text text node}.
      */
     get offsetSize(): number;
     /**
-     * Offset at which this node ends in it's parent. It is equal to the sum of this node's
+     * Offset at which this node ends in its parent. It is equal to the sum of this node's
      * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
      * Equals to `null` if the node has no parent.
      */
@@ -204,7 +212,7 @@ export default abstract class Node extends TypeCheckable {
      */
     _clone(_deep?: boolean): Node;
     /**
-     * Removes this node from it's parent.
+     * Removes this node from its parent.
      *
      * @internal
      * @see module:engine/model/writer~Writer#remove
@@ -244,11 +252,6 @@ export default abstract class Node extends TypeCheckable {
      */
     _clearAttributes(): void;
 }
-/**
- * The node's parent does not contain this node.
- *
- * @error model-node-not-found-in-parent
- */
 /**
  * Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
  */

package/src/model/node.js

@@ -7,7 +7,7 @@
  * @module engine/model/node
  */
 import TypeCheckable from './typecheckable.js';
-import { CKEditorError, compareArrays, toMap } from '@ckeditor/ckeditor5-utils';
+import { compareArrays, toMap } from '@ckeditor/ckeditor5-utils';
 /**
  * Model node. Most basic structure of model tree.
  *
@@ -52,6 +52,18 @@ export default class Node extends TypeCheckable {
          * Equals to `null` if the node has no parent.
          */
         this.parent = null;
+        /**
+         * Index of this node in its parent or `null` if the node has no parent.
+         *
+         * @internal
+         */
+        this._index = null;
+        /**
+         * Offset at which this node starts in its parent or `null` if the node has no parent.
+         *
+         * @internal
+         */
+        this._startOffset = null;
         this._attrs = toMap(attrs);
     }
     /**
@@ -62,53 +74,35 @@ export default class Node extends TypeCheckable {
     }
     /**
      * Index of this node in its parent or `null` if the node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get index() {
-        let pos;
-        if (!this.parent) {
-            return null;
-        }
-        if ((pos = this.parent.getChildIndex(this)) === null) {
-            throw new CKEditorError('model-node-not-found-in-parent', this);
-        }
-        return pos;
+        return this._index;
     }
     /**
      * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
      * of all its previous siblings. Equals to `null` if node has no parent.
-     *
-     * Accessing this property throws an error if this node's parent element does not contain it.
-     * This means that model tree got broken.
      */
     get startOffset() {
-        let pos;
-        if (!this.parent) {
-            return null;
-        }
-        if ((pos = this.parent.getChildStartOffset(this)) === null) {
-            throw new CKEditorError('model-node-not-found-in-parent', this);
-        }
-        return pos;
+        return this._startOffset;
     }
     /**
-     * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
-     * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
-     * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
-     * than one entity, i.e. {@link module:engine/model/text~Text text node}.
+     * Offset size of this node.
+     *
+     * Represents how much "offset space" is occupied by the node in its parent. It is important for
+     * {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position can be placed between
+     * that node start and end. `offsetSize` greater than `1` is for nodes that represents more than one entity, i.e.
+     * a {@link module:engine/model/text~Text text node}.
      */
     get offsetSize() {
         return 1;
     }
     /**
-     * Offset at which this node ends in it's parent. It is equal to the sum of this node's
+     * Offset at which this node ends in its parent. It is equal to the sum of this node's
      * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
      * Equals to `null` if the node has no parent.
      */
     get endOffset() {
-        if (!this.parent) {
+        if (this.startOffset === null) {
             return null;
         }
         return this.startOffset + this.offsetSize;
@@ -316,7 +310,7 @@ export default class Node extends TypeCheckable {
         return new this.constructor(this._attrs);
     }
     /**
-     * Removes this node from it's parent.
+     * Removes this node from its parent.
      *
      * @internal
      * @see module:engine/model/writer~Writer#remove

package/src/model/nodelist.d.ts

@@ -17,7 +17,15 @@ export default class NodeList implements Iterable<Node> {
      */
     private _nodes;
     /**
-     * Creates an empty node list.
+     * This array maps numbers (offsets) to node that is placed at that offset.
+     *
+     * This array is similar to `_nodes` with the difference that one node may occupy multiple consecutive items in the array.
+     *
+     * This array is needed to quickly retrieve a node that is placed at given offset.
+     */
+    private _offsetToNode;
+    /**
+     * Creates a node list.
      *
      * @internal
      * @param nodes Nodes contained in this node list.
@@ -42,26 +50,33 @@ export default class NodeList implements Iterable<Node> {
      */
     getNode(index: number): Node | null;
     /**
-     * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+     * Gets the node at the given offset. Returns `null` if incorrect offset was passed.
+     */
+    getNodeAtOffset(offset: number): Node | null;
+    /**
+     * Returns an index of the given node or `null` if given node does not have a parent.
+     *
+     * This is an alias to {@link module:engine/model/node~Node#index}.
      */
     getNodeIndex(node: Node): number | null;
     /**
-     * Returns the starting offset of given node. Starting offset is equal to the sum of
-     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+     * Returns the offset at which given node is placed in its parent or `null` if given node does not have a parent.
+     *
+     * This is an alias to {@link module:engine/model/node~Node#startOffset}.
      */
     getNodeStartOffset(node: Node): number | null;
     /**
      * Converts index to offset in node list.
      *
-     * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
-     * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `model-nodelist-index-out-of-bounds` if given index is less
+     * than `0` or more than {@link #length}.
      */
     indexToOffset(index: number): number;
     /**
      * Converts offset in node list to index.
      *
-     * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
-     * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `model-nodelist-offset-out-of-bounds` if given offset is less
+     * than `0` or more than {@link #maxOffset}.
      */
     offsetToIndex(offset: number): number;
     /**