@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.0

package/src/view/position.js

@@ -24,33 +24,17 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a position.
      *
-     * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} parent Position parent.
-     * @param {Number} offset Position offset.
+     * @param parent Position parent.
+     * @param offset Position offset.
      */
     constructor(parent, offset) {
         super();
-        /**
-         * Position parent.
-         *
-         * @readonly
-         * @member {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment}
-         * module:engine/view/position~Position#parent
-         */
         this.parent = parent;
-        /**
-         * Position offset.
-         *
-         * @readonly
-         * @member {Number} module:engine/view/position~Position#offset
-         */
         this.offset = offset;
     }
     /**
      * Node directly after the position. Equals `null` when there is no node after position or position is located
      * inside text node.
-     *
-     * @readonly
-     * @type {module:engine/view/node~Node|null}
      */
     get nodeAfter() {
         if (this.parent.is('$text')) {
@@ -61,9 +45,6 @@ export default class Position extends TypeCheckable {
     /**
      * Node directly before the position. Equals `null` when there is no node before position or position is located
      * inside text node.
-     *
-     * @readonly
-     * @type {module:engine/view/node~Node|null}
      */
     get nodeBefore() {
         if (this.parent.is('$text')) {
@@ -73,18 +54,12 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Is `true` if position is at the beginning of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isAtStart() {
         return this.offset === 0;
     }
     /**
      * Is `true` if position is at the end of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isAtEnd() {
         const endOffset = this.parent.is('$text') ? this.parent.data.length : this.parent.childCount;
@@ -92,9 +67,6 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Position's root, that is the root of the position's parent element.
-     *
-     * @readonly
-     * @type {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment}
      */
     get root() {
         return this.parent.root;
@@ -102,8 +74,6 @@ export default class Position extends TypeCheckable {
     /**
      * {@link module:engine/view/editableelement~EditableElement EditableElement} instance that contains this position, or `null` if
      * position is not inside an editable element.
-     *
-     * @type {module:engine/view/editableelement~EditableElement|null}
      */
     get editableElement() {
         let editable = this.parent;
@@ -120,8 +90,8 @@ export default class Position extends TypeCheckable {
     /**
      * Returns a new instance of Position with offset incremented by `shift` value.
      *
-     * @param {Number} shift How position offset should get changed. Accepts negative values.
-     * @returns {module:engine/view/position~Position} Shifted position.
+     * @param shift How position offset should get changed. Accepts negative values.
+     * @returns Shifted position.
      */
     getShiftedBy(shift) {
         const shifted = Position._createAt(this);
@@ -135,15 +105,16 @@ export default class Position extends TypeCheckable {
      *
      * For example:
      *
-     * 		getLastMatchingPosition( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
-     * 		getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } ); // <p>foo[]</p> -> <p>{}foo</p>
-     * 		getLastMatchingPosition( value => false ); // Do not move the position.
+     * ```ts
+     * getLastMatchingPosition( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
+     * getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } ); // <p>foo[]</p> -> <p>{}foo</p>
+     * getLastMatchingPosition( value => false ); // Do not move the position.
+     * ```
      *
-     * @param {Function} skip Callback function. Gets {@link module:engine/view/treewalker~type TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/view/treewalker~type TreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
-     * @param {Object} options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
-     *
-     * @returns {module:engine/view/position~Position} The position after the last item which matches the `skip` callback test.
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
+     * @returns The position after the last item which matches the `skip` callback test.
      */
     getLastMatchingPosition(skip, options = {}) {
         options.startPosition = this;
@@ -154,7 +125,7 @@ export default class Position extends TypeCheckable {
     /**
      * Returns ancestors array of this position, that is this position's parent and it's ancestors.
      *
-     * @returns {Array} Array with ancestors.
+     * @returns Array with ancestors.
      */
     getAncestors() {
         if (this.parent.is('documentFragment')) {
@@ -167,9 +138,6 @@ export default class Position extends TypeCheckable {
     /**
      * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
      * which is a common ancestor of both positions.
-     *
-     * @param {module:engine/view/position~Position} position
-     * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null}
      */
     getCommonAncestor(position) {
         const ancestorsA = this.getAncestors();
@@ -183,8 +151,8 @@ export default class Position extends TypeCheckable {
     /**
      * Checks whether this position equals given position.
      *
-     * @param {module:engine/view/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} True if positions are same.
+     * @param otherPosition Position to compare with.
+     * @returns True if positions are same.
      */
     isEqual(otherPosition) {
         return (this.parent == otherPosition.parent && this.offset == otherPosition.offset);
@@ -196,8 +164,8 @@ export default class Position extends TypeCheckable {
      *
      * @see module:engine/view/position~Position#isAfter
      * @see module:engine/view/position~Position#compareWith
-     * @param {module:engine/view/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} Returns `true` if this position is before given position.
+     * @param otherPosition Position to compare with.
+     * @returns Returns `true` if this position is before given position.
      */
     isBefore(otherPosition) {
         return this.compareWith(otherPosition) == 'before';
@@ -209,8 +177,8 @@ export default class Position extends TypeCheckable {
      *
      * @see module:engine/view/position~Position#isBefore
      * @see module:engine/view/position~Position#compareWith
-     * @param {module:engine/view/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} Returns `true` if this position is after given position.
+     * @param otherPosition Position to compare with.
+     * @returns Returns `true` if this position is after given position.
      */
     isAfter(otherPosition) {
         return this.compareWith(otherPosition) == 'after';
@@ -219,8 +187,7 @@ export default class Position extends TypeCheckable {
      * Checks whether this position is before, after or in same position that other position. Two positions may be also
      * different when they are located in separate roots.
      *
-     * @param {module:engine/view/position~Position} otherPosition Position to compare with.
-     * @returns {module:engine/view/position~PositionRelation}
+     * @param otherPosition Position to compare with.
      */
     compareWith(otherPosition) {
         if (this.root !== otherPosition.root) {
@@ -242,6 +209,10 @@ export default class Position extends TypeCheckable {
                 return 'before';
             case 'extension':
                 return 'after';
+            /* istanbul ignore next */
+            case 'same':
+                // Already covered by `this.isEqual` above. Added so TypeScript can infer `result` as number in `default` case.
+                return 'same';
             default:
                 return thisPath[result] < otherPath[result] ? 'before' : 'after';
         }
@@ -249,16 +220,15 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a {@link module:engine/view/treewalker~TreeWalker TreeWalker} instance with this positions as a start position.
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}
-     * @param {module:engine/view/range~Range} [options.boundaries=null] Range to define boundaries of the iterator.
-     * @param {Boolean} [options.singleCharacters=false]
-     * @param {Boolean} [options.shallow=false]
-     * @param {Boolean} [options.ignoreElementEnd=false]
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}
      */
     getWalker(options = {}) {
         options.startPosition = this;
         return new TreeWalker(options);
     }
+    /**
+     * Clones this position.
+     */
     clone() {
         return new Position(this.parent, this.offset);
     }
@@ -275,10 +245,8 @@ export default class Position extends TypeCheckable {
      * * {@link module:engine/view/position~Position._createBefore},
      * * {@link module:engine/view/position~Position._createAfter}.
      *
-     * @protected
-     * @param {module:engine/view/item~Item|module:engine/view/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
-     * first parameter is a {@link module:engine/view/item~Item view item}.
+     * @internal
+     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/view/item~Item view item}.
      */
     static _createAt(itemOrPosition, offset) {
         if (itemOrPosition instanceof Position) {
@@ -310,9 +278,8 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a new position after given view item.
      *
-     * @protected
-     * @param {module:engine/view/item~Item} item View item after which the position should be located.
-     * @returns {module:engine/view/position~Position}
+     * @internal
+     * @param item View item after which the position should be located.
      */
     static _createAfter(item) {
         // TextProxy is not a instance of Node so we need do handle it in specific way.
@@ -333,9 +300,8 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a new position before given view item.
      *
-     * @protected
-     * @param {module:engine/view/item~Item} item View item before which the position should be located.
-     * @returns {module:engine/view/position~Position}
+     * @internal
+     * @param item View item before which the position should be located.
      */
     static _createBefore(item) {
         // TextProxy is not a instance of Node so we need do handle it in specific way.
@@ -354,21 +320,8 @@ export default class Position extends TypeCheckable {
         return new Position(item.parent, item.index);
     }
 }
-/**
- * Checks whether this object is of the given type.
- *
- *		position.is( 'position' ); // -> true
- *		position.is( 'view:position' ); // -> true
- *
- *		position.is( 'model:position' ); // -> false
- *		position.is( 'element' ); // -> false
- *		position.is( 'range' ); // -> false
- *
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Position.prototype.is = function (type) {
     return type === 'position' || type === 'view:position';
 };

package/src/view/range.d.ts

@@ -0,0 +1,279 @@
+/**
+ * @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
+ */
+/**
+ * @module engine/view/range
+ */
+import TypeCheckable from './typecheckable';
+import Position from './position';
+import type DocumentFragment from './documentfragment';
+import type Element from './element';
+import type Item from './item';
+import type Node from './node';
+import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker';
+/**
+ * Range in the view tree. A range is represented by its start and end {@link module:engine/view/position~Position positions}.
+ *
+ * In order to create a new position instance use the `createPosition*()` factory methods available in:
+ *
+ * * {@link module:engine/view/view~View}
+ * * {@link module:engine/view/downcastwriter~DowncastWriter}
+ * * {@link module:engine/view/upcastwriter~UpcastWriter}
+ */
+export default class Range extends TypeCheckable implements Iterable<TreeWalkerValue> {
+    /**
+     * Start position.
+     */
+    readonly start: Position;
+    /**
+     * End position.
+     */
+    readonly end: Position;
+    /**
+     * Creates a range spanning from `start` position to `end` position.
+     *
+     * **Note:** Constructor creates it's own {@link module:engine/view/position~Position} instances basing on passed values.
+     *
+     * @param start Start position.
+     * @param end End position. If not set, range will be collapsed at the `start` position.
+     */
+    constructor(start: Position, end?: Position | null);
+    /**
+     * Iterable interface.
+     *
+     * Iterates over all {@link module:engine/view/item~Item view items} that are in this range and returns
+     * them together with additional information like length or {@link module:engine/view/position~Position positions},
+     * grouped as {@link module:engine/view/treewalker~TreeWalkerValue}.
+     *
+     * This iterator uses {@link module:engine/view/treewalker~TreeWalker TreeWalker} with `boundaries` set to this range and
+     * `ignoreElementEnd` option
+     * set to `true`.
+     */
+    [Symbol.iterator](): IterableIterator<TreeWalkerValue>;
+    /**
+     * Returns whether the range is collapsed, that is it start and end positions are equal.
+     */
+    get isCollapsed(): boolean;
+    /**
+     * Returns whether this range is flat, that is if {@link module:engine/view/range~Range#start start} position and
+     * {@link module:engine/view/range~Range#end end} position are in the same {@link module:engine/view/position~Position#parent parent}.
+     */
+    get isFlat(): boolean;
+    /**
+     * Range root element.
+     */
+    get root(): Node | DocumentFragment;
+    /**
+     * Creates a maximal range that has the same content as this range but is expanded in both ways (at the beginning
+     * and at the end).
+     *
+     * For example:
+     *
+     * ```html
+     * <p>Foo</p><p><b>{Bar}</b></p> -> <p>Foo</p>[<p><b>Bar</b>]</p>
+     * <p><b>foo</b>{bar}<span></span></p> -> <p><b>foo[</b>bar<span></span>]</p>
+     * ```
+     *
+     * Note that in the sample above:
+     *
+     * - `<p>` have type of {@link module:engine/view/containerelement~ContainerElement},
+     * - `<b>` have type of {@link module:engine/view/attributeelement~AttributeElement},
+     * - `<span>` have type of {@link module:engine/view/uielement~UIElement}.
+     *
+     * @returns Enlarged range.
+     */
+    getEnlarged(): Range;
+    /**
+     * Creates a minimum range that has the same content as this range but is trimmed in both ways (at the beginning
+     * and at the end).
+     *
+     * For example:
+     *
+     * ```html
+     * <p>Foo</p>[<p><b>Bar</b>]</p> -> <p>Foo</p><p><b>{Bar}</b></p>
+     * <p><b>foo[</b>bar<span></span>]</p> -> <p><b>foo</b>{bar}<span></span></p>
+     * ```
+     *
+     * Note that in the sample above:
+     *
+     * - `<p>` have type of {@link module:engine/view/containerelement~ContainerElement},
+     * - `<b>` have type of {@link module:engine/view/attributeelement~AttributeElement},
+     * - `<span>` have type of {@link module:engine/view/uielement~UIElement}.
+     *
+     * @returns Shrunk range.
+     */
+    getTrimmed(): Range;
+    /**
+     * Two ranges are equal if their start and end positions are equal.
+     *
+     * @param otherRange Range to compare with.
+     * @returns `true` if ranges are equal, `false` otherwise
+     */
+    isEqual(otherRange: Range): boolean;
+    /**
+     * Checks whether this range contains given {@link module:engine/view/position~Position position}.
+     *
+     * @param position Position to check.
+     * @returns `true` if given {@link module:engine/view/position~Position position} is contained in this range, `false` otherwise.
+     */
+    containsPosition(position: Position): boolean;
+    /**
+     * Checks whether this range contains given {@link module:engine/view/range~Range 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 `true` if given {@link module:engine/view/range~Range range} boundaries are contained by this range, `false`
+     * otherwise.
+     */
+    containsRange(otherRange: Range, loose?: boolean): boolean;
+    /**
+     * Computes which part(s) of this {@link module:engine/view/range~Range range} is not a part of given
+     * {@link module:engine/view/range~Range range}.
+     * Returned array contains zero, one or two {@link module:engine/view/range~Range ranges}.
+     *
+     * Examples:
+     *
+     * ```ts
+     * let foo = downcastWriter.createText( 'foo' );
+     * let img = downcastWriter.createContainerElement( 'img' );
+     * let bar = downcastWriter.createText( 'bar' );
+     * let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
+     *
+     * let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
+     * let otherRange = view.createRange( // "oo", img, "ba" are in range.
+     * 	view.createPositionAt( foo, 1 ),
+     * 	view.createPositionAt( bar, 2 )
+     * );
+     * let transformed = range.getDifference( otherRange );
+     * // transformed array has no ranges because `otherRange` contains `range`
+     *
+     * otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has one range: from ( p, 2 ) to ( bar, 1 )
+     *
+     * otherRange = view.createRange( view.createPositionAt( p, 1 ), view.createPositionAt( p, 2 ) ); // img is in range.
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has two ranges: from ( foo, 1 ) to ( p, 1 ) and from ( p, 2 ) to ( bar, 1 )
+     * ```
+     *
+     * @param otherRange Range to differentiate against.
+     * @returns The difference between ranges.
+     */
+    getDifference(otherRange: Range): Array<Range>;
+    /**
+     * Returns an intersection of this {@link module:engine/view/range~Range range} and given {@link module:engine/view/range~Range range}.
+     * Intersection is a common part of both of those ranges. If ranges has no common part, returns `null`.
+     *
+     * Examples:
+     *
+     * ```ts
+     * let foo = downcastWriter.createText( 'foo' );
+     * let img = downcastWriter.createContainerElement( 'img' );
+     * let bar = downcastWriter.createText( 'bar' );
+     * let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
+     *
+     * let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
+     * let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
+     * let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ).
+     *
+     * otherRange = view.createRange( view.createPositionAt( bar, 1 ), view.createPositionAt( bar, 3 ); "ar" is in range.
+     * transformed = range.getIntersection( otherRange ); // null - no common part.
+     * ```
+     *
+     * @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;
+    /**
+     * Creates a {@link module:engine/view/treewalker~TreeWalker TreeWalker} instance with this range as a boundary.
+     *
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
+     */
+    getWalker(options?: TreeWalkerOptions): TreeWalker;
+    /**
+     * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
+     * which is a common ancestor of range's both ends (in which the entire range is contained).
+     */
+    getCommonAncestor(): Node | DocumentFragment | null;
+    /**
+     * Returns an {@link module:engine/view/element~Element 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;
+    /**
+     * Clones this range.
+     */
+    clone(): Range;
+    /**
+     * Returns an iterator that iterates over all {@link module:engine/view/item~Item view items} that are in this range and returns
+     * them.
+     *
+     * This method uses {@link module:engine/view/treewalker~TreeWalker} with `boundaries` set to this range and `ignoreElementEnd` option
+     * set to `true`. However it returns only {@link module:engine/view/item~Item items},
+     * not {@link module:engine/view/treewalker~TreeWalkerValue}.
+     *
+     * You may specify additional options for the tree walker. See {@link module:engine/view/treewalker~TreeWalker} for
+     * a full list of available options.
+     *
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
+     */
+    getItems(options?: TreeWalkerOptions): IterableIterator<Item>;
+    /**
+     * Returns an iterator that iterates over all {@link module:engine/view/position~Position positions} that are boundaries or
+     * contained in this range.
+     *
+     * This method uses {@link module:engine/view/treewalker~TreeWalker} with `boundaries` set to this range. However it returns only
+     * {@link module:engine/view/position~Position positions}, not {@link module:engine/view/treewalker~TreeWalkerValue}.
+     *
+     * You may specify additional options for the tree walker. See {@link module:engine/view/treewalker~TreeWalker} for
+     * a full list of available options.
+     *
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
+     */
+    getPositions(options?: TreeWalkerOptions): IterableIterator<Position>;
+    /**
+     * Checks and returns whether this range intersects with the given range.
+     *
+     * @param otherRange Range to compare with.
+     * @returns True if ranges intersect.
+     */
+    isIntersecting(otherRange: Range): boolean;
+    /**
+     * Creates a range from the given parents and offsets.
+     *
+     * @internal
+     * @param startElement Start position parent element.
+     * @param startOffset Start position offset.
+     * @param endElement End position parent element.
+     * @param endOffset End position offset.
+     * @returns Created range.
+     */
+    static _createFromParentsAndOffsets(startElement: Element | DocumentFragment, startOffset: number, endElement: Element | DocumentFragment, endOffset: number): Range;
+    /**
+     * Creates a new range, spreading from specified {@link module:engine/view/position~Position 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;
+    /**
+     * Creates a range inside an {@link module:engine/view/element~Element 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;
+    /**
+     * Creates a range that starts before given {@link module:engine/view/item~Item view item} and ends after it.
+     *
+     * @internal
+     */
+    static _createOn(item: Item): Range;
+}