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

package/src/view/position.d.ts

@@ -0,0 +1,189 @@
+/**
+ * @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/position
+ */
+import TypeCheckable from './typecheckable';
+import EditableElement from './editableelement';
+import '@ckeditor/ckeditor5-utils/src/version';
+import type DocumentFragment from './documentfragment';
+import type Item from './item';
+import type Node from './node';
+import { default as TreeWalker, type TreeWalkerValue, type TreeWalkerOptions } from './treewalker';
+/**
+ * Position in the view tree. Position is represented by its parent node and an offset in this parent.
+ *
+ * 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 Position extends TypeCheckable {
+    /**
+     * Position parent.
+     */
+    readonly parent: Node | DocumentFragment;
+    /**
+     * Position offset.
+     */
+    offset: number;
+    /**
+     * Creates a position.
+     *
+     * @param parent Position parent.
+     * @param offset Position offset.
+     */
+    constructor(parent: Node | DocumentFragment, offset: number);
+    /**
+     * Node directly after the position. Equals `null` when there is no node after position or position is located
+     * inside text node.
+     */
+    get nodeAfter(): Node | null;
+    /**
+     * Node directly before the position. Equals `null` when there is no node before position or position is located
+     * inside text node.
+     */
+    get nodeBefore(): Node | null;
+    /**
+     * Is `true` if position is at the beginning of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
+     */
+    get isAtStart(): boolean;
+    /**
+     * Is `true` if position is at the end of its {@link module:engine/view/position~Position#parent parent}, `false` otherwise.
+     */
+    get isAtEnd(): boolean;
+    /**
+     * Position's root, that is the root of the position's parent element.
+     */
+    get root(): Node | DocumentFragment;
+    /**
+     * {@link module:engine/view/editableelement~EditableElement EditableElement} instance that contains this position, or `null` if
+     * position is not inside an editable element.
+     */
+    get editableElement(): EditableElement | null;
+    /**
+     * Returns a new instance of Position with offset incremented by `shift` value.
+     *
+     * @param shift How position offset should get changed. Accepts negative values.
+     * @returns Shifted position.
+     */
+    getShiftedBy(shift: number): Position;
+    /**
+     * Gets the farthest position which matches the callback using
+     * {@link module:engine/view/treewalker~TreeWalker TreeWalker}.
+     *
+     * For example:
+     *
+     * ```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 skip Callback function. Gets {@link module:engine/view/treewalker~TreeWalkerValue} and should
+     * return `true` if the value should be skipped or `false` if not.
+     * @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: (value: TreeWalkerValue) => boolean, options?: TreeWalkerOptions): Position;
+    /**
+     * Returns ancestors array of this position, that is this position's parent and it's ancestors.
+     *
+     * @returns Array with ancestors.
+     */
+    getAncestors(): Array<Node | DocumentFragment>;
+    /**
+     * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
+     * which is a common ancestor of both positions.
+     */
+    getCommonAncestor(position: Position): Node | DocumentFragment | null;
+    /**
+     * Checks whether this position equals given position.
+     *
+     * @param otherPosition Position to compare with.
+     * @returns True if positions are same.
+     */
+    isEqual(otherPosition: Position): boolean;
+    /**
+     * Checks whether this position is located before given position. When method returns `false` it does not mean that
+     * this position is after give one. Two positions may be located inside separate roots and in that situation this
+     * method will still return `false`.
+     *
+     * @see module:engine/view/position~Position#isAfter
+     * @see module:engine/view/position~Position#compareWith
+     * @param otherPosition Position to compare with.
+     * @returns Returns `true` if this position is before given position.
+     */
+    isBefore(otherPosition: Position): boolean;
+    /**
+     * Checks whether this position is located after given position. When method returns `false` it does not mean that
+     * this position is before give one. Two positions may be located inside separate roots and in that situation this
+     * method will still return `false`.
+     *
+     * @see module:engine/view/position~Position#isBefore
+     * @see module:engine/view/position~Position#compareWith
+     * @param otherPosition Position to compare with.
+     * @returns Returns `true` if this position is after given position.
+     */
+    isAfter(otherPosition: Position): boolean;
+    /**
+     * 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 otherPosition Position to compare with.
+     */
+    compareWith(otherPosition: Position): PositionRelation;
+    /**
+     * Creates a {@link module:engine/view/treewalker~TreeWalker TreeWalker} instance with this positions as a start position.
+     *
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}
+     */
+    getWalker(options?: TreeWalkerOptions): TreeWalker;
+    /**
+     * Clones this position.
+     */
+    clone(): Position;
+    /**
+     * Creates position at the given location. The location can be specified as:
+     *
+     * * a {@link module:engine/view/position~Position position},
+     * * parent element and offset (offset defaults to `0`),
+     * * parent element and `'end'` (sets position at the end of that element),
+     * * {@link module:engine/view/item~Item view item} and `'before'` or `'after'` (sets position before or after given view item).
+     *
+     * This method is a shortcut to other constructors such as:
+     *
+     * * {@link module:engine/view/position~Position._createBefore},
+     * * {@link module:engine/view/position~Position._createAfter}.
+     *
+     * @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: Item | Position, offset?: PositionOffset): Position;
+    /**
+     * Creates a new position after given view item.
+     *
+     * @internal
+     * @param item View item after which the position should be located.
+     */
+    static _createAfter(item: Item): Position;
+    /**
+     * Creates a new position before given view item.
+     *
+     * @internal
+     * @param item View item before which the position should be located.
+     */
+    static _createBefore(item: Item): Position;
+}
+/**
+ * A flag indicating whether this position is `'before'` or `'after'` or `'same'` as given position.
+ * If positions are in different roots `'different'` flag is returned.
+ */
+export type PositionRelation = 'before' | 'after' | 'same' | 'different';
+/**
+ * Offset or one of the flags.
+ */
+export type PositionOffset = number | 'before' | 'after' | 'end';

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~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';
 };