@ckeditor/ckeditor5-engine 45.2.1 → 46.0.0-alpha.1

package/src/model/range.d.ts

@@ -5,56 +5,56 @@
 /**
  * @module engine/model/range
  */
-import TypeCheckable from './typecheckable.js';
-import Position from './position.js';
-import TreeWalker, { type TreeWalkerOptions, type TreeWalkerValue } from './treewalker.js';
-import type Document from './document.js';
-import type DocumentFragment from './documentfragment.js';
-import type Element from './element.js';
-import type InsertOperation from './operation/insertoperation.js';
-import type Item from './item.js';
-import type MergeOperation from './operation/mergeoperation.js';
-import type MoveOperation from './operation/moveoperation.js';
-import type Operation from './operation/operation.js';
-import type SplitOperation from './operation/splitoperation.js';
+import { ModelTypeCheckable } from './typecheckable.js';
+import { ModelPosition } from './position.js';
+import { ModelTreeWalker, type ModelTreeWalkerOptions, type ModelTreeWalkerValue } from './treewalker.js';
+import { type ModelDocument } from './document.js';
+import { type ModelDocumentFragment } from './documentfragment.js';
+import { type ModelElement } from './element.js';
+import { type InsertOperation } from './operation/insertoperation.js';
+import { type ModelItem } from './item.js';
+import { type MergeOperation } from './operation/mergeoperation.js';
+import { type MoveOperation } from './operation/moveoperation.js';
+import { type Operation } from './operation/operation.js';
+import { type SplitOperation } from './operation/splitoperation.js';
 /**
  * Represents a range in the model tree.
  *
- * A range is defined by its {@link module:engine/model/range~Range#start} and {@link module:engine/model/range~Range#end}
+ * A range is defined by its {@link module:engine/model/range~ModelRange#start} and {@link module:engine/model/range~ModelRange#end}
  * positions.
  *
  * You can create range instances via its constructor or the `createRange*()` 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}.
  */
-export default class Range extends TypeCheckable implements Iterable<TreeWalkerValue> {
+export declare class ModelRange extends ModelTypeCheckable implements Iterable<ModelTreeWalkerValue> {
     /**
      * Start position.
      */
-    readonly start: Position;
+    readonly start: ModelPosition;
     /**
      * End position.
      */
-    readonly end: Position;
+    readonly end: ModelPosition;
     /**
      * Creates a range spanning from `start` position to `end` position.
      *
      * @param start The start position.
      * @param end The end position. If not set, the range will be collapsed at the `start` position.
      */
-    constructor(start: Position, end?: Position | null);
+    constructor(start: ModelPosition, end?: ModelPosition | null);
     /**
      * Iterable interface.
      *
-     * Iterates over all {@link module:engine/model/item~Item items} that are in this range and returns
-     * them together with additional information like length or {@link module:engine/model/position~Position positions},
-     * grouped as {@link module:engine/model/treewalker~TreeWalkerValue}.
-     * It iterates over all {@link module:engine/model/textproxy~TextProxy text contents} that are inside the range
-     * and all the {@link module:engine/model/element~Element}s that are entered into when iterating over this range.
+     * Iterates over all {@link module:engine/model/item~ModelItem items} that are in this range and returns
+     * them together with additional information like length or {@link module:engine/model/position~ModelPosition positions},
+     * grouped as {@link module:engine/model/treewalker~ModelTreeWalkerValue}.
+     * It iterates over all {@link module:engine/model/textproxy~ModelTextProxy text contents} that are inside the range
+     * and all the {@link module:engine/model/element~ModelElement}s that are entered into when iterating over this range.
      *
-     * This iterator uses {@link module:engine/model/treewalker~TreeWalker} with `boundaries` set to this range
+     * This iterator uses {@link module:engine/model/treewalker~ModelTreeWalker} with `boundaries` set to this range
      * and `ignoreElementEnd` option set to `true`.
      */
-    [Symbol.iterator](): IterableIterator<TreeWalkerValue>;
+    [Symbol.iterator](): IterableIterator<ModelTreeWalkerValue>;
     /**
      * Describes whether the range is collapsed, that is if {@link #start} and
      * {@link #end} positions are equal.
@@ -62,52 +62,52 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
     get isCollapsed(): boolean;
     /**
      * Describes whether this range is flat, that is if {@link #start} position and
-     * {@link #end} position are in the same {@link module:engine/model/position~Position#parent}.
+     * {@link #end} position are in the same {@link module:engine/model/position~ModelPosition#parent}.
      */
     get isFlat(): boolean;
     /**
      * Range root element.
      */
-    get root(): Element | DocumentFragment;
+    get root(): ModelElement | ModelDocumentFragment;
     /**
-     * Checks whether this range contains given {@link module:engine/model/position~Position position}.
+     * Checks whether this range contains given {@link module:engine/model/position~ModelPosition position}.
      *
      * @param position Position to check.
-     * @returns `true` if given {@link module:engine/model/position~Position position} is contained
+     * @returns `true` if given {@link module:engine/model/position~ModelPosition position} is contained
      * in this range,`false` otherwise.
      */
-    containsPosition(position: Position): boolean;
+    containsPosition(position: ModelPosition): boolean;
     /**
-     * Checks whether this range contains given {@link ~Range range}.
+     * Checks whether this range contains given {@link ~ModelRange range}.
      *
      * @param otherRange Range to check.
      * @param loose Whether the check is loose or strict. If the check is strict (`false`), compared range cannot
      * start or end at the same position as this range boundaries. If the check is loose (`true`), compared range can start, end or
      * even be equal to this range. Note that collapsed ranges are always compared in strict mode.
-     * @returns {Boolean} `true` if given {@link ~Range range} boundaries are contained by this range, `false` otherwise.
+     * @returns {Boolean} `true` if given {@link ~ModelRange range} boundaries are contained by this range, `false` otherwise.
      */
-    containsRange(otherRange: Range, loose?: boolean): boolean;
+    containsRange(otherRange: ModelRange, loose?: boolean): boolean;
     /**
-     * Checks whether given {@link module:engine/model/item~Item} is inside this range.
+     * Checks whether given {@link module:engine/model/item~ModelItem} is inside this range.
      */
-    containsItem(item: Item): boolean;
+    containsItem(item: ModelItem): boolean;
     /**
      * Two ranges are equal if their {@link #start} and {@link #end} positions are equal.
      *
      * @param otherRange Range to compare with.
      * @returns `true` if ranges are equal, `false` otherwise.
      */
-    isEqual(otherRange: Range): boolean;
+    isEqual(otherRange: ModelRange): boolean;
     /**
      * Checks and returns whether this range intersects with given range.
      *
      * @param otherRange Range to compare with.
      * @returns `true` if ranges intersect, `false` otherwise.
      */
-    isIntersecting(otherRange: Range): boolean;
+    isIntersecting(otherRange: ModelRange): boolean;
     /**
-     * Computes which part(s) of this {@link ~Range range} is not a part of given {@link ~Range range}.
-     * Returned array contains zero, one or two {@link ~Range ranges}.
+     * Computes which part(s) of this {@link ~ModelRange range} is not a part of given {@link ~ModelRange range}.
+     * Returned array contains zero, one or two {@link ~ModelRange ranges}.
      *
      * Examples:
      *
@@ -132,9 +132,9 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param otherRange Range to differentiate against.
      * @returns The difference between ranges.
      */
-    getDifference(otherRange: Range): Array<Range>;
+    getDifference(otherRange: ModelRange): Array<ModelRange>;
     /**
-     * Returns an intersection of this {@link ~Range range} and given {@link ~Range range}.
+     * Returns an intersection of this {@link ~ModelRange range} and given {@link ~ModelRange range}.
      * Intersection is a common part of both of those ranges. If ranges has no common part, returns `null`.
      *
      * Examples:
@@ -154,9 +154,9 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param otherRange Range to check for intersection.
      * @returns A common part of given ranges or `null` if ranges have no common part.
      */
-    getIntersection(otherRange: Range): Range | null;
+    getIntersection(otherRange: ModelRange): ModelRange | null;
     /**
-     * Returns a range created by joining this {@link ~Range range} with the given {@link ~Range range}.
+     * Returns a range created by joining this {@link ~ModelRange range} with the given {@link ~ModelRange range}.
      * If ranges have no common part, returns `null`.
      *
      * Examples:
@@ -182,10 +182,10 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param otherRange Range to be joined.
      * @param loose Whether the intersection check is loose or strict. If the check is strict (`false`),
      * ranges are tested for intersection or whether start/end positions are equal. If the check is loose (`true`),
-     * compared range is also checked if it's {@link module:engine/model/position~Position#isTouching touching} current range.
+     * compared range is also checked if it's {@link module:engine/model/position~ModelPosition#isTouching touching} current range.
      * @returns A sum of given ranges or `null` if ranges have no common part.
      */
-    getJoined(otherRange: Range, loose?: boolean): Range | null;
+    getJoined(otherRange: ModelRange, loose?: boolean): ModelRange | null;
     /**
      * Computes and returns the smallest set of {@link #isFlat flat} ranges, that covers this range in whole.
      *
@@ -221,7 +221,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * ( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se"
      * ```
      *
-     * **Note:** if an {@link module:engine/model/element~Element element} is not wholly contained in this range, it won't be returned
+     * **Note:** if an {@link module:engine/model/element~ModelElement element} is not wholly contained in this range, it won't be returned
      * in any of the returned flat ranges. See in the example how `H` elements at the beginning and at the end of the range
      * were omitted. Only their parts that were wholly in the range were returned.
      *
@@ -229,9 +229,9 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      *
      * @returns Array of flat ranges covering this range.
      */
-    getMinimalFlatRanges(): Array<Range>;
+    getMinimalFlatRanges(): Array<ModelRange>;
     /**
-     * Creates a {@link module:engine/model/treewalker~TreeWalker TreeWalker} instance with this range as a boundary.
+     * Creates a {@link module:engine/model/treewalker~ModelTreeWalker TreeWalker} instance with this range as a boundary.
      *
      * For example, to iterate over all items in the entire document root:
      *
@@ -245,36 +245,36 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * }
      * ```
      *
-     * @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}.
      */
-    getWalker(options?: TreeWalkerOptions): TreeWalker;
+    getWalker(options?: ModelTreeWalkerOptions): ModelTreeWalker;
     /**
-     * Returns an iterator that iterates over all {@link module:engine/model/item~Item items} that are in this range and returns
+     * Returns an iterator that iterates over all {@link module:engine/model/item~ModelItem items} that are in this range and returns
      * them.
      *
-     * This method uses {@link module:engine/model/treewalker~TreeWalker} with `boundaries` set to this range and `ignoreElementEnd` option
-     * set to `true`. However it returns only {@link module:engine/model/item~Item model items},
-     * not {@link module:engine/model/treewalker~TreeWalkerValue}.
+     * This method uses {@link module:engine/model/treewalker~ModelTreeWalker} with `boundaries` set to this range and
+     * `ignoreElementEnd` option set to `true`. However it returns only {@link module:engine/model/item~ModelItem model items},
+     * not {@link module:engine/model/treewalker~ModelTreeWalkerValue}.
      *
-     * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~TreeWalker} for
+     * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~ModelTreeWalker} for
      * a full list of available options.
      *
-     * @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}.
      */
-    getItems(options?: TreeWalkerOptions): IterableIterator<Item>;
+    getItems(options?: ModelTreeWalkerOptions): IterableIterator<ModelItem>;
     /**
-     * Returns an iterator that iterates over all {@link module:engine/model/position~Position positions} that are boundaries or
+     * Returns an iterator that iterates over all {@link module:engine/model/position~ModelPosition positions} that are boundaries or
      * contained in this range.
      *
-     * This method uses {@link module:engine/model/treewalker~TreeWalker} with `boundaries` set to this range. However it returns only
-     * {@link module:engine/model/position~Position positions}, not {@link module:engine/model/treewalker~TreeWalkerValue}.
+     * This method uses {@link module:engine/model/treewalker~ModelTreeWalker} with `boundaries` set to this range. However it returns only
+     * {@link module:engine/model/position~ModelPosition positions}, not {@link module:engine/model/treewalker~ModelTreeWalkerValue}.
      *
-     * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~TreeWalker} for
+     * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~ModelTreeWalker} for
      * a full list of available options.
      *
-     * @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}.
      */
-    getPositions(options?: TreeWalkerOptions): IterableIterator<Position>;
+    getPositions(options?: ModelTreeWalkerOptions): IterableIterator<ModelPosition>;
     /**
      * Returns a range that is a result of transforming this range by given `operation`.
      *
@@ -285,26 +285,26 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param operation Operation to transform range by.
      * @returns Range which is the result of transformation.
      */
-    getTransformedByOperation(operation: Operation): Array<Range>;
+    getTransformedByOperation(operation: Operation): Array<ModelRange>;
     /**
      * Returns a range that is a result of transforming this range by multiple `operations`.
      *
-     * @see ~Range#getTransformedByOperation
+     * @see ~ModelRange#getTransformedByOperation
      * @param operations Operations to transform the range by.
      * @returns Range which is the result of transformation.
      */
-    getTransformedByOperations(operations: Iterable<Operation>): Array<Range>;
+    getTransformedByOperations(operations: Iterable<Operation>): Array<ModelRange>;
     /**
-     * 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 the range's both ends (in which the entire range is contained).
      */
-    getCommonAncestor(): Element | DocumentFragment | null;
+    getCommonAncestor(): ModelElement | ModelDocumentFragment | null;
     /**
-     * Returns an {@link module:engine/model/element~Element Element} contained by the range.
+     * Returns an {@link module:engine/model/element~ModelElement Element} contained by the range.
      * The element will be returned when it is the **only** node within the range and **fully–contained**
      * at the same time.
      */
-    getContainedElement(): Element | null;
+    getContainedElement(): ModelElement | null;
     /**
      * Converts `Range` to plain object and returns it.
      *
@@ -322,7 +322,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      *
      * @internal
      */
-    _getTransformedByInsertOperation(operation: InsertOperation, spread?: boolean): Array<Range>;
+    _getTransformedByInsertOperation(operation: InsertOperation, spread?: boolean): Array<ModelRange>;
     /**
      * Returns a result of transforming a copy of this range by move operation.
      *
@@ -330,7 +330,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      *
      * @internal
      */
-    _getTransformedByMoveOperation(operation: MoveOperation, spread?: boolean): Array<Range>;
+    _getTransformedByMoveOperation(operation: MoveOperation, spread?: boolean): Array<ModelRange>;
     /**
      * Returns a result of transforming a copy of this range by split operation.
      *
@@ -338,7 +338,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      *
      * @internal
      */
-    _getTransformedBySplitOperation(operation: SplitOperation): Range;
+    _getTransformedBySplitOperation(operation: SplitOperation): ModelRange;
     /**
      * Returns a result of transforming a copy of this range by merge operation.
      *
@@ -346,11 +346,11 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      *
      * @internal
      */
-    _getTransformedByMergeOperation(operation: MergeOperation): Range;
+    _getTransformedByMergeOperation(operation: MergeOperation): ModelRange;
     /**
-     * Returns an array containing one or two {@link ~Range ranges} that are a result of transforming this
-     * {@link ~Range range} by inserting `howMany` nodes at `insertPosition`. Two {@link ~Range ranges} are
-     * returned if the insertion was inside this {@link ~Range range} and `spread` is set to `true`.
+     * Returns an array containing one or two {@link ~ModelRange ranges} that are a result of transforming this
+     * {@link ~ModelRange range} by inserting `howMany` nodes at `insertPosition`. Two {@link ~ModelRange ranges} are
+     * returned if the insertion was inside this {@link ~ModelRange range} and `spread` is set to `true`.
      *
      * Examples:
      *
@@ -379,10 +379,10 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * was inside the range. Defaults to `false`.
      * @returns Result of the transformation.
      */
-    _getTransformedByInsertion(insertPosition: Position, howMany: number, spread?: boolean): Array<Range>;
+    _getTransformedByInsertion(insertPosition: ModelPosition, howMany: number, spread?: boolean): Array<ModelRange>;
     /**
-     * Returns an array containing {@link ~Range ranges} that are a result of transforming this
-     * {@link ~Range range} by moving `howMany` nodes from `sourcePosition` to `targetPosition`.
+     * Returns an array containing {@link ~ModelRange ranges} that are a result of transforming this
+     * {@link ~ModelRange range} by moving `howMany` nodes from `sourcePosition` to `targetPosition`.
      *
      * @internal
      * @param sourcePosition Position from which nodes are moved.
@@ -391,7 +391,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param spread Whether the range should be spread if the move points inside the range.
      * @returns  Result of the transformation.
      */
-    _getTransformedByMove(sourcePosition: Position, targetPosition: Position, howMany: number, spread?: boolean): Array<Range>;
+    _getTransformedByMove(sourcePosition: ModelPosition, targetPosition: ModelPosition, howMany: number, spread?: boolean): Array<ModelRange>;
     /**
      * Returns a copy of this range that is transformed by deletion of `howMany` nodes from `deletePosition`.
      *
@@ -404,30 +404,30 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param howMany How many nodes are removed.
      * @returns Result of the transformation.
      */
-    _getTransformedByDeletion(deletePosition: Position, howMany: number): Range | null;
+    _getTransformedByDeletion(deletePosition: ModelPosition, howMany: number): ModelRange | null;
     /**
-     * Creates a new range, spreading from specified {@link module:engine/model/position~Position position} to a position moved by
+     * Creates a new range, spreading from specified {@link module:engine/model/position~ModelPosition position} to a position moved by
      * given `shift`. If `shift` is a negative value, shifted position is treated as the beginning of the range.
      *
      * @internal
      * @param position Beginning of the range.
      * @param shift How long the range should be.
      */
-    static _createFromPositionAndShift(position: Position, shift: number): Range;
+    static _createFromPositionAndShift(position: ModelPosition, shift: number): ModelRange;
     /**
-     * Creates a range inside an {@link module:engine/model/element~Element element} which starts before the first child of
+     * Creates a range inside an {@link module:engine/model/element~ModelElement element} which starts before the first child of
      * that element and ends after the last child of that element.
      *
      * @internal
      * @param element Element which is a parent for the range.
      */
-    static _createIn(element: Element | DocumentFragment): Range;
+    static _createIn(element: ModelElement | ModelDocumentFragment): ModelRange;
     /**
-     * Creates a range that starts before given {@link module:engine/model/item~Item model item} and ends after it.
+     * Creates a range that starts before given {@link module:engine/model/item~ModelItem model item} and ends after it.
      *
      * @internal
      */
-    static _createOn(item: Item): Range;
+    static _createOn(item: ModelItem): ModelRange;
     /**
      * Combines all ranges from the passed array into a one range. At least one range has to be passed.
      * Passed ranges must not have common parts.
@@ -446,7 +446,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param ranges Ranges to combine.
      * @returns Combined range.
      */
-    static _createFromRanges(ranges: Array<Range>): Range;
+    static _createFromRanges(ranges: Array<ModelRange>): ModelRange;
     /**
      * Creates a `Range` instance from given plain object (i.e. parsed JSON string).
      *
@@ -454,5 +454,5 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * @param doc Document object that will be range owner.
      * @returns `Range` instance created using given plain object.
      */
-    static fromJSON(json: any, doc: Document): Range;
+    static fromJSON(json: any, doc: ModelDocument): ModelRange;
 }