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

package/src/model/textproxy.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @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/model/textproxy
+ */
+import TypeCheckable from './typecheckable';
+import type DocumentFragment from './documentfragment';
+import type Element from './element';
+import type Node from './node';
+import type Text from './text';
+/**
+ * `TextProxy` represents a part of {@link module:engine/model/text~Text text node}.
+ *
+ * Since {@link module:engine/model/position~Position positions} can be placed between characters of a text node,
+ * {@link module:engine/model/range~Range ranges} may contain only parts of text nodes. When {@link module:engine/model/range~Range#getItems
+ * getting items}
+ * contained in such range, we need to represent a part of that text node, since returning the whole text node would be incorrect.
+ * `TextProxy` solves this issue.
+ *
+ * `TextProxy` has an API similar to {@link module:engine/model/text~Text Text} and allows to do most of the common tasks performed
+ * on model nodes.
+ *
+ * **Note:** Some `TextProxy` instances may represent whole text node, not just a part of it.
+ * See {@link module:engine/model/textproxy~TextProxy#isPartial}.
+ *
+ * **Note:** `TextProxy` is not an instance of {@link module:engine/model/node~Node node}. Keep this in mind when using it as a
+ * parameter of methods.
+ *
+ * **Note:** `TextProxy` is a readonly interface. If you want to perform changes on model data represented by a `TextProxy`
+ * use {@link module:engine/model/writer~Writer model writer API}.
+ *
+ * **Note:** `TextProxy` instances are created on the fly, basing on the current state of model. Because of this, it is
+ * highly unrecommended to store references to `TextProxy` instances. `TextProxy` instances are not refreshed when
+ * model changes, so they might get invalidated. Instead, consider creating {@link module:engine/model/liveposition~LivePosition live
+ * position}.
+ *
+ * `TextProxy` instances are created by {@link module:engine/model/treewalker~TreeWalker model tree walker}. You should not need to create
+ * an instance of this class by your own.
+ */
+export default class TextProxy extends TypeCheckable {
+    /**
+     * Text node which part is represented by this text proxy.
+     */
+    readonly textNode: Text;
+    /**
+     * Text data represented by this text proxy.
+     */
+    readonly data: string;
+    /**
+     * Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy starts.
+     */
+    readonly offsetInText: number;
+    /**
+     * Creates a text proxy.
+     *
+     * @internal
+     * @param textNode Text node which part is represented by this text proxy.
+     * @param offsetInText Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy
+     * starts.
+     * @param length Text proxy length, that is how many text node's characters, starting from `offsetInText` it represents.
+     */
+    constructor(textNode: Text, offsetInText: number, length: number);
+    /**
+     * Offset at which this text proxy starts in it's parent.
+     *
+     * @see module:engine/model/node~Node#startOffset
+     */
+    get startOffset(): number | null;
+    /**
+     * Offset size of this text proxy. Equal to the number of characters represented by the text proxy.
+     *
+     * @see module:engine/model/node~Node#offsetSize
+     */
+    get offsetSize(): number;
+    /**
+     * Offset at which this text proxy ends in it's parent.
+     *
+     * @see module:engine/model/node~Node#endOffset
+     */
+    get endOffset(): number | null;
+    /**
+     * Flag indicating whether `TextProxy` instance covers only part of the original {@link module:engine/model/text~Text text node}
+     * (`true`) or the whole text node (`false`).
+     *
+     * This is `false` when text proxy starts at the very beginning of {@link module:engine/model/textproxy~TextProxy#textNode textNode}
+     * ({@link module:engine/model/textproxy~TextProxy#offsetInText offsetInText} equals `0`) and text proxy sizes is equal to
+     * text node size.
+     */
+    get isPartial(): boolean;
+    /**
+     * Parent of this text proxy, which is same as parent of text node represented by this text proxy.
+     */
+    get parent(): Element | DocumentFragment | null;
+    /**
+     * Root of this text proxy, which is same as root of text node represented by this text proxy.
+     */
+    get root(): Node | DocumentFragment;
+    /**
+     * Gets path to this text proxy.
+     *
+     * @see module:engine/model/node~Node#getPath
+     */
+    getPath(): Array<number>;
+    /**
+     * Returns ancestors array of this text proxy.
+     *
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` this text proxy will be also included in parent's array.
+     * @param options.parentFirst When set to `true`, array will be sorted from text proxy parent to root element,
+     * otherwise root element will be the first item in the array.
+     * @returns Array with ancestors.
+     */
+    getAncestors(options?: {
+        includeSelf?: boolean;
+        parentFirst?: boolean;
+    }): Array<TextProxy | Element | DocumentFragment>;
+    /**
+     * Checks if this text proxy has an attribute for given key.
+     *
+     * @param key Key of attribute to check.
+     * @returns `true` if attribute with given key is set on text proxy, `false` otherwise.
+     */
+    hasAttribute(key: string): boolean;
+    /**
+     * Gets an attribute value for given key or `undefined` if that attribute is not set on text proxy.
+     *
+     * @param key Key of attribute to look for.
+     * @returns Attribute value or `undefined`.
+     */
+    getAttribute(key: string): unknown;
+    /**
+     * Returns iterator that iterates over this node's attributes. Attributes are returned as arrays containing two
+     * items. First one is attribute key and second is attribute value.
+     *
+     * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
+     */
+    getAttributes(): IterableIterator<[string, unknown]>;
+    /**
+     * Returns iterator that iterates over this node's attribute keys.
+     */
+    getAttributeKeys(): IterableIterator<string>;
+}

package/src/model/treewalker.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @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
+ */
+import { default as Position } from './position';
+import type Item from './item';
+import type Range from './range';
+/**
+ * Position iterator class. It allows to iterate forward and backward over the document.
+ */
+export default class TreeWalker implements Iterable<TreeWalkerValue> {
+    /**
+     * Walking direction. Defaults `'forward'`.
+     */
+    readonly direction: TreeWalkerDirection;
+    /**
+     * Iterator boundaries.
+     *
+     * When the iterator is walking `'forward'` on the end of boundary or is walking `'backward'`
+     * on the start of boundary, then `{ done: true }` is returned.
+     *
+     * If boundaries are not defined they are set before first and after last child of the root node.
+     */
+    readonly boundaries: Range | null;
+    /**
+     * Flag indicating whether all consecutive characters with the same attributes should be
+     * returned as one {@link module:engine/model/textproxy~TextProxy} (`true`) or one by one (`false`).
+     */
+    readonly singleCharacters: boolean;
+    /**
+     * Flag indicating whether iterator should enter elements or not. If the iterator is shallow child nodes of any
+     * iterated node will not be returned along with `elementEnd` tag.
+     */
+    readonly shallow: boolean;
+    /**
+     * Flag indicating whether iterator should ignore `elementEnd` tags. If the option is true walker will not
+     * return a parent node of the start position. If this option is `true` each {@link module:engine/model/element~Element} will
+     * be returned once, while if the option is `false` they might be returned twice:
+     * for `'elementStart'` and `'elementEnd'`.
+     */
+    readonly ignoreElementEnd: boolean;
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    private _position;
+    /**
+     * Start boundary cached for optimization purposes.
+     */
+    private _boundaryStartParent;
+    /**
+     * End boundary cached for optimization purposes.
+     */
+    private _boundaryEndParent;
+    /**
+     * Parent of the most recently visited node. Cached for optimization purposes.
+     */
+    private _visitedParent;
+    /**
+     * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
+     *
+     * @param options Object with configuration.
+     */
+    constructor(options: TreeWalkerOptions);
+    /**
+     * Iterable interface.
+     *
+     * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
+     */
+    [Symbol.iterator](): IterableIterator<TreeWalkerValue>;
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    get position(): Position;
+    /**
+     * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
+     *
+     * For example:
+     *
+     * ```ts
+     * walker.skip( value => value.type == 'text' ); // <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>
+     * walker.skip( () => true ); // Move the position to the end: <paragraph>[]foo</paragraph> -> <paragraph>foo</paragraph>[]
+     * walker.skip( () => false ); // Do not move the position.
+     * ```
+     *
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * return `true` if the value should be skipped or `false` if not.
+     */
+    skip(skip: (value: TreeWalkerValue) => boolean): void;
+    /**
+     * Gets the next tree walker's value.
+     */
+    next(): IteratorResult<TreeWalkerValue>;
+    /**
+     * Makes a step forward in model. Moves the {@link #position} to the next position and returns the encountered value.
+     */
+    private _next;
+    /**
+     * Makes a step backward in model. Moves the {@link #position} to the previous position and returns the encountered value.
+     */
+    private _previous;
+}
+/**
+ * Type of the step made by {@link module:engine/model/treewalker~TreeWalker}.
+ * Possible values: `'elementStart'` if walker is at the beginning of a node, `'elementEnd'` if walker is at the end of node,
+ * or `'text'` if walker traversed over text.
+ */
+export type TreeWalkerValueType = 'elementStart' | 'elementEnd' | 'text';
+/**
+ * Object returned by {@link module:engine/model/treewalker~TreeWalker} when traversing tree model.
+ */
+export interface TreeWalkerValue {
+    type: TreeWalkerValueType;
+    /**
+     * Item between old and new positions of {@link module:engine/model/treewalker~TreeWalker}.
+     */
+    item: Item;
+    /**
+     * Previous position of the iterator.
+     * * Forward iteration: For `'elementEnd'` it is the last position inside the element. For all other types it is the
+     * position before the item.
+     * * Backward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
+     * the position after item.
+     */
+    previousPosition: Position;
+    /**
+     * Next position of the iterator.
+     * * Forward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
+     * the position after the item.
+     * * Backward iteration: For `'elementEnd'` it is last position inside element. For all other types it is the position
+     * before the item.
+     */
+    nextPosition: Position;
+    /**
+     * Length of the item. For `'elementStart'` it is 1. For `'text'` it is the length of the text. For `'elementEnd'` it is `undefined`.
+     */
+    length?: number;
+}
+/**
+ * Tree walking direction.
+ */
+export type TreeWalkerDirection = 'forward' | 'backward';
+/**
+ * The configuration of TreeWalker.
+ *
+ * All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
+ */
+export interface TreeWalkerOptions {
+    /**
+     * Walking direction.
+     *
+     * @default 'forward'
+     */
+    direction?: TreeWalkerDirection;
+    /**
+     * Range to define boundaries of the iterator.
+     */
+    boundaries?: Range | null;
+    /**
+     * Starting position.
+     */
+    startPosition?: Position;
+    /**
+     * Flag indicating whether all consecutive characters with the same attributes
+     * should be returned one by one as multiple {@link module:engine/model/textproxy~TextProxy} (`true`) objects or as one
+     * {@link module:engine/model/textproxy~TextProxy} (`false`).
+     */
+    singleCharacters?: boolean;
+    /**
+     * Flag indicating whether iterator should enter elements or not. If the
+     * iterator is shallow child nodes of any iterated node will not be returned along with `elementEnd` tag.
+     */
+    shallow?: boolean;
+    /**
+     * Flag indicating whether iterator should ignore `elementEnd` tags.
+     * If the option is true walker will not return a parent node of start position. If this option is `true`
+     * each {@link module:engine/model/element~Element} will be returned once, while if the option is `false` they might be returned
+     * twice: for `'elementStart'` and `'elementEnd'`.
+     */
+    ignoreElementEnd?: boolean;
+}

package/src/model/treewalker.js

@@ -40,10 +40,10 @@ export default class TreeWalker {
         this.direction = direction;
         this.boundaries = options.boundaries || null;
         if (options.startPosition) {
-            this.position = options.startPosition.clone();
+            this._position = options.startPosition.clone();
         }
         else {
-            this.position = Position._createAt(this.boundaries[this.direction == 'backward' ? 'end' : 'start']);
+            this._position = Position._createAt(this.boundaries[this.direction == 'backward' ? 'end' : 'start']);
         }
         // Reset position stickiness in case it was set to other value, as the stickiness is kept after cloning.
         this.position.stickiness = 'toNone';
@@ -62,6 +62,15 @@ export default class TreeWalker {
     [Symbol.iterator]() {
         return this;
     }
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    get position() {
+        return this._position;
+    }
     /**
      * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
      *
@@ -84,7 +93,7 @@ export default class TreeWalker {
             ({ done, value } = this.next());
         } while (!done && skip(value));
         if (!done) {
-            this.position = prevPosition;
+            this._position = prevPosition;
             this._visitedParent = prevVisitedParent;
         }
     }
@@ -127,7 +136,7 @@ export default class TreeWalker {
             else {
                 position.offset++;
             }
-            this.position = position;
+            this._position = position;
             return formatReturnValue('elementStart', node, previousPosition, position, 1);
         }
         else if (node instanceof Text) {
@@ -145,14 +154,14 @@ export default class TreeWalker {
             const offsetInTextNode = position.offset - node.startOffset;
             const item = new TextProxy(node, offsetInTextNode, charactersCount);
             position.offset += charactersCount;
-            this.position = position;
+            this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
         else {
             // `node` is not set, we reached the end of current `parent`.
             position.path.pop();
             position.offset++;
-            this.position = position;
+            this._position = position;
             this._visitedParent = parent.parent;
             if (this.ignoreElementEnd) {
                 return this._next();
@@ -186,7 +195,7 @@ export default class TreeWalker {
             position.offset--;
             if (!this.shallow) {
                 position.path.push(node.maxOffset);
-                this.position = position;
+                this._position = position;
                 this._visitedParent = node;
                 if (this.ignoreElementEnd) {
                     return this._previous();
@@ -196,7 +205,7 @@ export default class TreeWalker {
                 }
             }
             else {
-                this.position = position;
+                this._position = position;
                 return formatReturnValue('elementStart', node, previousPosition, position, 1);
             }
         }
@@ -215,13 +224,13 @@ export default class TreeWalker {
             const offsetInTextNode = position.offset - node.startOffset;
             const item = new TextProxy(node, offsetInTextNode - charactersCount, charactersCount);
             position.offset -= charactersCount;
-            this.position = position;
+            this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);
         }
         else {
             // `node` is not set, we reached the beginning of current `parent`.
             position.path.pop();
-            this.position = position;
+            this._position = position;
             this._visitedParent = parent.parent;
             return formatReturnValue('elementStart', parent, previousPosition, position, 1);
         }