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

package/src/model/textproxy.js

@@ -5,39 +5,39 @@
 /**
  * @module engine/model/textproxy
  */
-import TypeCheckable from './typecheckable.js';
+import { ModelTypeCheckable } from './typecheckable.js';
 import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 // @if CK_DEBUG_ENGINE // const { convertMapToStringifiedObject } = require( '../dev-utils/utils' );
 /**
- * `TextProxy` represents a part of {@link module:engine/model/text~Text text node}.
+ * `ModelTextProxy` represents a part of {@link module:engine/model/text~ModelText 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}
+ * Since {@link module:engine/model/position~ModelPosition positions} can be placed between characters of a text node,
+ * {@link module:engine/model/range~ModelRange ranges} may contain only parts of text nodes.
+ * When {@link module:engine/model/range~ModelRange#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.
+ * `ModelTextProxy` 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.
+ * `ModelTextProxy` has an API similar to {@link module:engine/model/text~ModelText 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:** Some `ModelTextProxy` instances may represent whole text node, not just a part of it.
+ * See {@link module:engine/model/textproxy~ModelTextProxy#isPartial}.
  *
- * **Note:** `TextProxy` is not an instance of {@link module:engine/model/node~Node node}. Keep this in mind when using it as a
+ * **Note:** `ModelTextProxy` is not an instance of {@link module:engine/model/node~ModelNode 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:** `ModelTextProxy` is a readonly interface. If you want to perform changes on model data represented by a `ModelTextProxy`
+ * use {@link module:engine/model/writer~ModelWriter 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
+ * **Note:** `ModelTextProxy` instances are created on the fly, basing on the current state of model. Because of this, it is
+ * highly unrecommended to store references to `ModelTextProxy` instances. `ModelTextProxy` instances are not refreshed when
+ * model changes, so they might get invalidated. Instead, consider creating {@link module:engine/model/liveposition~ModelLivePosition 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.
+ * `ModelTextProxy` instances are created by {@link module:engine/model/treewalker~ModelTreeWalker model tree walker}.
+ * You should not need to create an instance of this class by your own.
  */
-export default class TextProxy extends TypeCheckable {
+export class ModelTextProxy extends ModelTypeCheckable {
     /**
      * Text node which part is represented by this text proxy.
      */
@@ -47,7 +47,7 @@ export default class TextProxy extends TypeCheckable {
      */
     data;
     /**
-     * Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy starts.
+     * Offset in {@link module:engine/model/textproxy~ModelTextProxy#textNode text node} from which the text proxy starts.
      */
     offsetInText;
     /**
@@ -55,7 +55,7 @@ export default class TextProxy extends TypeCheckable {
      *
      * @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
+     * @param offsetInText Offset in {@link module:engine/model/textproxy~ModelTextProxy#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.
      */
@@ -84,7 +84,7 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Offset at which this text proxy starts in it's parent.
      *
-     * @see module:engine/model/node~Node#startOffset
+     * @see module:engine/model/node~ModelNode#startOffset
      */
     get startOffset() {
         return this.textNode.startOffset !== null ? this.textNode.startOffset + this.offsetInText : null;
@@ -92,7 +92,7 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Offset size of this text proxy. Equal to the number of characters represented by the text proxy.
      *
-     * @see module:engine/model/node~Node#offsetSize
+     * @see module:engine/model/node~ModelNode#offsetSize
      */
     get offsetSize() {
         return this.data.length;
@@ -100,17 +100,18 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Offset at which this text proxy ends in it's parent.
      *
-     * @see module:engine/model/node~Node#endOffset
+     * @see module:engine/model/node~ModelNode#endOffset
      */
     get endOffset() {
         return this.startOffset !== null ? this.startOffset + this.offsetSize : 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`).
+     * Flag indicating whether `ModelTextProxy` instance covers only part of the original
+     * {@link module:engine/model/text~ModelText 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
+     * This is `false` when text proxy starts at the very beginning of
+     * {@link module:engine/model/textproxy~ModelTextProxy#textNode textNode}
+     * ({@link module:engine/model/textproxy~ModelTextProxy#offsetInText offsetInText} equals `0`) and text proxy sizes is equal to
      * text node size.
      */
     get isPartial() {
@@ -131,7 +132,7 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Gets path to this text proxy.
      *
-     * @see module:engine/model/node~Node#getPath
+     * @see module:engine/model/node~ModelNode#getPath
      */
     getPath() {
         const path = this.textNode.getPath();
@@ -194,7 +195,7 @@ export default class TextProxy extends TypeCheckable {
 }
 // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
 // Proper overload would interfere with that.
-TextProxy.prototype.is = function (type) {
+ModelTextProxy.prototype.is = function (type) {
     return type === '$textProxy' || type === 'model:$textProxy' ||
         // This are legacy values kept for backward compatibility.
         type === 'textProxy' || type === 'model:textProxy';

package/src/model/treewalker.d.ts

@@ -2,17 +2,17 @@
  * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
-import { default as Position } from './position.js';
-import type Item from './item.js';
-import type Range from './range.js';
+import { ModelPosition } from './position.js';
+import { type ModelItem } from './item.js';
+import { type ModelRange } from './range.js';
 /**
  * Position iterator class. It allows to iterate forward and backward over the document.
  */
-export default class TreeWalker implements Iterable<TreeWalkerValue> {
+export declare class ModelTreeWalker implements Iterable<ModelTreeWalkerValue> {
     /**
      * Walking direction. Defaults `'forward'`.
      */
-    readonly direction: TreeWalkerDirection;
+    readonly direction: ModelTreeWalkerDirection;
     /**
      * Iterator boundaries.
      *
@@ -21,10 +21,10 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
      *
      * If boundaries are not defined they are set before first and after last child of the root node.
      */
-    readonly boundaries: Range | null;
+    readonly boundaries: ModelRange | 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`).
+     * returned as one {@link module:engine/model/textproxy~ModelTextProxy} (`true`) or one by one (`false`).
      */
     readonly singleCharacters: boolean;
     /**
@@ -34,14 +34,14 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
     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
+     * return a parent node of the start position. If this option is `true` each {@link module:engine/model/element~ModelElement} 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
+     * {@link module:engine/model/liveposition~ModelLivePosition 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.
      */
@@ -63,20 +63,20 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
      *
      * @param options Object with configuration.
      */
-    constructor(options: TreeWalkerOptions);
+    constructor(options: ModelTreeWalkerOptions);
     /**
      * Iterable interface.
      *
-     * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
+     * @returns {Iterable.<module:engine/model/treewalker~ModelTreeWalkerValue>}
      */
-    [Symbol.iterator](): IterableIterator<TreeWalkerValue>;
+    [Symbol.iterator](): IterableIterator<ModelTreeWalkerValue>;
     /**
      * 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
+     * {@link module:engine/model/liveposition~ModelLivePosition 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;
+    get position(): ModelPosition;
     /**
      * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
      *
@@ -88,17 +88,17 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
      * walker.skip( () => false ); // Do not move the position.
      * ```
      *
-     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~ModelTreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
      */
-    skip(skip: (value: TreeWalkerValue) => boolean): void;
+    skip(skip: (value: ModelTreeWalkerValue) => boolean): void;
     /**
      * Moves tree walker {@link #position} to provided `position`. Tree walker will
      * continue traversing from that position.
      *
-     * Note: in contrary to {@link ~TreeWalker#skip}, this method does not iterate over the nodes along the way.
+     * Note: in contrary to {@link ~ModelTreeWalker#skip}, this method does not iterate over the nodes along the way.
      * It simply sets the current tree walker position to a new one.
-     * From the performance standpoint, it is better to use {@link ~TreeWalker#jumpTo} rather than {@link ~TreeWalker#skip}.
+     * From the performance standpoint, it is better to use {@link ~ModelTreeWalker#jumpTo} rather than {@link ~ModelTreeWalker#skip}.
      *
      * If the provided position is before the start boundary, the position will be
      * set to the start boundary. If the provided position is after the end boundary,
@@ -107,11 +107,11 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
      *
      * @param position Position to jump to.
      */
-    jumpTo(position: Position): void;
+    jumpTo(position: ModelPosition): void;
     /**
      * Gets the next tree walker's value.
      */
-    next(): IteratorResult<TreeWalkerValue>;
+    next(): IteratorResult<ModelTreeWalkerValue>;
     /**
      * Makes a step forward in model. Moves the {@link #position} to the next position and returns the encountered value.
      */
@@ -122,20 +122,20 @@ export default class TreeWalker implements Iterable<TreeWalkerValue> {
     private _previous;
 }
 /**
- * Type of the step made by {@link module:engine/model/treewalker~TreeWalker}.
+ * Type of the step made by {@link module:engine/model/treewalker~ModelTreeWalker}.
  * 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';
+export type ModelTreeWalkerValueType = 'elementStart' | 'elementEnd' | 'text';
 /**
- * Object returned by {@link module:engine/model/treewalker~TreeWalker} when traversing tree model.
+ * Object returned by {@link module:engine/model/treewalker~ModelTreeWalker} when traversing tree model.
  */
-export interface TreeWalkerValue {
-    type: TreeWalkerValueType;
+export interface ModelTreeWalkerValue {
+    type: ModelTreeWalkerValueType;
     /**
-     * Item between old and new positions of {@link module:engine/model/treewalker~TreeWalker}.
+     * Item between old and new positions of {@link module:engine/model/treewalker~ModelTreeWalker}.
      */
-    item: Item;
+    item: ModelItem;
     /**
      * Previous position of the iterator.
      * * Forward iteration: For `'elementEnd'` it is the last position inside the element. For all other types it is the
@@ -143,7 +143,7 @@ export interface TreeWalkerValue {
      * * Backward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
      * the position after item.
      */
-    previousPosition: Position;
+    previousPosition: ModelPosition;
     /**
      * Next position of the iterator.
      * * Forward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
@@ -151,7 +151,7 @@ export interface TreeWalkerValue {
      * * Backward iteration: For `'elementEnd'` it is last position inside element. For all other types it is the position
      * before the item.
      */
-    nextPosition: Position;
+    nextPosition: ModelPosition;
     /**
      * Length of the item. For `'elementStart'` it is 1. For `'text'` it is the length of the text. For `'elementEnd'` it is `undefined`.
      */
@@ -160,31 +160,31 @@ export interface TreeWalkerValue {
 /**
  * Tree walking direction.
  */
-export type TreeWalkerDirection = 'forward' | 'backward';
+export type ModelTreeWalkerDirection = 'forward' | 'backward';
 /**
  * The configuration of TreeWalker.
  *
  * All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
  */
-export interface TreeWalkerOptions {
+export interface ModelTreeWalkerOptions {
     /**
      * Walking direction.
      *
      * @default 'forward'
      */
-    direction?: TreeWalkerDirection;
+    direction?: ModelTreeWalkerDirection;
     /**
      * Range to define boundaries of the iterator.
      */
-    boundaries?: Range | null;
+    boundaries?: ModelRange | null;
     /**
      * Starting position.
      */
-    startPosition?: Position;
+    startPosition?: ModelPosition;
     /**
      * 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`).
+     * should be returned one by one as multiple {@link module:engine/model/textproxy~ModelTextProxy} (`true`) objects or as one
+     * {@link module:engine/model/textproxy~ModelTextProxy} (`false`).
      */
     singleCharacters?: boolean;
     /**
@@ -195,7 +195,7 @@ export interface TreeWalkerOptions {
     /**
      * 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
+     * each {@link module:engine/model/element~ModelElement} 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

@@ -2,13 +2,13 @@
  * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
-import { default as Position, getTextNodeAtPosition, getNodeAfterPosition, getNodeBeforePosition } from './position.js';
-import TextProxy from './textproxy.js';
+import { ModelPosition, getTextNodeAtPosition, getNodeAfterPosition, getNodeBeforePosition } from './position.js';
+import { ModelTextProxy } from './textproxy.js';
 import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * Position iterator class. It allows to iterate forward and backward over the document.
  */
-export default class TreeWalker {
+export class ModelTreeWalker {
     /**
      * Walking direction. Defaults `'forward'`.
      */
@@ -24,7 +24,7 @@ export default class TreeWalker {
     boundaries;
     /**
      * 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`).
+     * returned as one {@link module:engine/model/textproxy~ModelTextProxy} (`true`) or one by one (`false`).
      */
     singleCharacters;
     /**
@@ -34,14 +34,14 @@ export default class TreeWalker {
     shallow;
     /**
      * 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
+     * return a parent node of the start position. If this option is `true` each {@link module:engine/model/element~ModelElement} will
      * be returned once, while if the option is `false` they might be returned twice:
      * for `'elementStart'` and `'elementEnd'`.
      */
     ignoreElementEnd;
     /**
      * 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
+     * {@link module:engine/model/liveposition~ModelLivePosition 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.
      */
@@ -87,7 +87,7 @@ export default class TreeWalker {
             this._position = options.startPosition.clone();
         }
         else {
-            this._position = Position._createAt(this.boundaries[this.direction == 'backward' ? 'end' : 'start']);
+            this._position = ModelPosition._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';
@@ -101,14 +101,14 @@ export default class TreeWalker {
     /**
      * Iterable interface.
      *
-     * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
+     * @returns {Iterable.<module:engine/model/treewalker~ModelTreeWalkerValue>}
      */
     [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
+     * {@link module:engine/model/liveposition~ModelLivePosition 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.
      */
@@ -126,7 +126,7 @@ export default class TreeWalker {
      * walker.skip( () => false ); // Do not move the position.
      * ```
      *
-     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~ModelTreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
      */
     skip(skip) {
@@ -145,9 +145,9 @@ export default class TreeWalker {
      * Moves tree walker {@link #position} to provided `position`. Tree walker will
      * continue traversing from that position.
      *
-     * Note: in contrary to {@link ~TreeWalker#skip}, this method does not iterate over the nodes along the way.
+     * Note: in contrary to {@link ~ModelTreeWalker#skip}, this method does not iterate over the nodes along the way.
      * It simply sets the current tree walker position to a new one.
-     * From the performance standpoint, it is better to use {@link ~TreeWalker#jumpTo} rather than {@link ~TreeWalker#skip}.
+     * From the performance standpoint, it is better to use {@link ~ModelTreeWalker#jumpTo} rather than {@link ~ModelTreeWalker#skip}.
      *
      * If the provided position is before the start boundary, the position will be
      * set to the start boundary. If the provided position is after the end boundary,
@@ -225,7 +225,7 @@ export default class TreeWalker {
                 charactersCount = offset - position.offset;
             }
             const offsetInTextNode = position.offset - node.startOffset;
-            const item = new TextProxy(node, offsetInTextNode, charactersCount);
+            const item = new ModelTextProxy(node, offsetInTextNode, charactersCount);
             position.offset += charactersCount;
             this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);
@@ -287,7 +287,7 @@ export default class TreeWalker {
                 charactersCount = position.offset - offset;
             }
             const offsetInTextNode = position.offset - node.startOffset;
-            const item = new TextProxy(node, offsetInTextNode - charactersCount, charactersCount);
+            const item = new ModelTextProxy(node, offsetInTextNode - charactersCount, charactersCount);
             position.offset -= charactersCount;
             this._position = position;
             return formatReturnValue('text', item, previousPosition, position, charactersCount);