@ckeditor/ckeditor5-engine 39.0.1 → 40.0.0

package/src/model/text.d.ts

@@ -1,66 +1,66 @@
-/**
- * @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/text
- */
-import Node, { type NodeAttributes } from './node';
-/**
- * Model text node. Type of {@link module:engine/model/node~Node node} that contains {@link module:engine/model/text~Text#data text data}.
- *
- * **Important:** see {@link module:engine/model/node~Node} to read about restrictions using `Text` and `Node` API.
- *
- * **Note:** keep in mind that `Text` instances might indirectly got removed from model tree when model is changed.
- * This happens when {@link module:engine/model/writer~Writer model writer} is used to change model and the text node is merged with
- * another text node. Then, both text nodes are removed and a new text node is inserted into the model. Because of
- * this behavior, keeping references to `Text` is not recommended. Instead, consider creating
- * {@link module:engine/model/liveposition~LivePosition live position} placed before the text node.
- */
-export default class Text extends Node {
-    /**
-     * Text data contained in this text node.
-     *
-     * @internal
-     */
-    _data: string;
-    /**
-     * Creates a text node.
-     *
-     * **Note:** Constructor of this class shouldn't be used directly in the code.
-     * Use the {@link module:engine/model/writer~Writer#createText} method instead.
-     *
-     * @internal
-     * @param data Node's text.
-     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
-     */
-    constructor(data?: string, attrs?: NodeAttributes);
-    /**
-     * @inheritDoc
-     */
-    get offsetSize(): number;
-    /**
-     * Returns a text data contained in the node.
-     */
-    get data(): string;
-    /**
-     * Converts `Text` instance to plain object and returns it.
-     *
-     * @returns`Text` instance converted to plain object.
-     */
-    toJSON(): unknown;
-    /**
-     * Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
-     *
-     * @internal
-     * @returns `Text` instance created using given plain object.
-     */
-    _clone(): Text;
-    /**
-     * Creates a `Text` instance from given plain object (i.e. parsed JSON string).
-     *
-     * @param json Plain object to be converted to `Text`.
-     * @returns `Text` instance created using given plain object.
-     */
-    static fromJSON(json: any): Text;
-}
+/**
+ * @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/text
+ */
+import Node, { type NodeAttributes } from './node';
+/**
+ * Model text node. Type of {@link module:engine/model/node~Node node} that contains {@link module:engine/model/text~Text#data text data}.
+ *
+ * **Important:** see {@link module:engine/model/node~Node} to read about restrictions using `Text` and `Node` API.
+ *
+ * **Note:** keep in mind that `Text` instances might indirectly got removed from model tree when model is changed.
+ * This happens when {@link module:engine/model/writer~Writer model writer} is used to change model and the text node is merged with
+ * another text node. Then, both text nodes are removed and a new text node is inserted into the model. Because of
+ * this behavior, keeping references to `Text` is not recommended. Instead, consider creating
+ * {@link module:engine/model/liveposition~LivePosition live position} placed before the text node.
+ */
+export default class Text extends Node {
+    /**
+     * Text data contained in this text node.
+     *
+     * @internal
+     */
+    _data: string;
+    /**
+     * Creates a text node.
+     *
+     * **Note:** Constructor of this class shouldn't be used directly in the code.
+     * Use the {@link module:engine/model/writer~Writer#createText} method instead.
+     *
+     * @internal
+     * @param data Node's text.
+     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    constructor(data?: string, attrs?: NodeAttributes);
+    /**
+     * @inheritDoc
+     */
+    get offsetSize(): number;
+    /**
+     * Returns a text data contained in the node.
+     */
+    get data(): string;
+    /**
+     * Converts `Text` instance to plain object and returns it.
+     *
+     * @returns`Text` instance converted to plain object.
+     */
+    toJSON(): unknown;
+    /**
+     * Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
+     *
+     * @internal
+     * @returns `Text` instance created using given plain object.
+     */
+    _clone(): Text;
+    /**
+     * Creates a `Text` instance from given plain object (i.e. parsed JSON string).
+     *
+     * @param json Plain object to be converted to `Text`.
+     * @returns `Text` instance created using given plain object.
+     */
+    static fromJSON(json: any): Text;
+}

package/src/model/text.js

@@ -1,85 +1,85 @@
-/**
- * @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/text
- */
-import Node from './node';
-// @if CK_DEBUG_ENGINE // const { convertMapToStringifiedObject } = require( '../dev-utils/utils' );
-/**
- * Model text node. Type of {@link module:engine/model/node~Node node} that contains {@link module:engine/model/text~Text#data text data}.
- *
- * **Important:** see {@link module:engine/model/node~Node} to read about restrictions using `Text` and `Node` API.
- *
- * **Note:** keep in mind that `Text` instances might indirectly got removed from model tree when model is changed.
- * This happens when {@link module:engine/model/writer~Writer model writer} is used to change model and the text node is merged with
- * another text node. Then, both text nodes are removed and a new text node is inserted into the model. Because of
- * this behavior, keeping references to `Text` is not recommended. Instead, consider creating
- * {@link module:engine/model/liveposition~LivePosition live position} placed before the text node.
- */
-export default class Text extends Node {
-    /**
-     * Creates a text node.
-     *
-     * **Note:** Constructor of this class shouldn't be used directly in the code.
-     * Use the {@link module:engine/model/writer~Writer#createText} method instead.
-     *
-     * @internal
-     * @param data Node's text.
-     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
-     */
-    constructor(data, attrs) {
-        super(attrs);
-        this._data = data || '';
-    }
-    /**
-     * @inheritDoc
-     */
-    get offsetSize() {
-        return this.data.length;
-    }
-    /**
-     * Returns a text data contained in the node.
-     */
-    get data() {
-        return this._data;
-    }
-    /**
-     * Converts `Text` instance to plain object and returns it.
-     *
-     * @returns`Text` instance converted to plain object.
-     */
-    toJSON() {
-        const json = super.toJSON();
-        json.data = this.data;
-        return json;
-    }
-    /**
-     * Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
-     *
-     * @internal
-     * @returns `Text` instance created using given plain object.
-     */
-    _clone() {
-        return new Text(this.data, this.getAttributes());
-    }
-    /**
-     * Creates a `Text` instance from given plain object (i.e. parsed JSON string).
-     *
-     * @param json Plain object to be converted to `Text`.
-     * @returns `Text` instance created using given plain object.
-     */
-    static fromJSON(json) {
-        return new Text(json.data, json.attributes);
-    }
-}
-// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
-// Proper overload would interfere with that.
-Text.prototype.is = function (type) {
-    return type === '$text' || type === 'model:$text' ||
-        // This are legacy values kept for backward compatibility.
-        type === 'text' || type === 'model:text' ||
-        // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
-        type === 'node' || type === 'model:node';
-};
+/**
+ * @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/text
+ */
+import Node from './node';
+// @if CK_DEBUG_ENGINE // const { convertMapToStringifiedObject } = require( '../dev-utils/utils' );
+/**
+ * Model text node. Type of {@link module:engine/model/node~Node node} that contains {@link module:engine/model/text~Text#data text data}.
+ *
+ * **Important:** see {@link module:engine/model/node~Node} to read about restrictions using `Text` and `Node` API.
+ *
+ * **Note:** keep in mind that `Text` instances might indirectly got removed from model tree when model is changed.
+ * This happens when {@link module:engine/model/writer~Writer model writer} is used to change model and the text node is merged with
+ * another text node. Then, both text nodes are removed and a new text node is inserted into the model. Because of
+ * this behavior, keeping references to `Text` is not recommended. Instead, consider creating
+ * {@link module:engine/model/liveposition~LivePosition live position} placed before the text node.
+ */
+export default class Text extends Node {
+    /**
+     * Creates a text node.
+     *
+     * **Note:** Constructor of this class shouldn't be used directly in the code.
+     * Use the {@link module:engine/model/writer~Writer#createText} method instead.
+     *
+     * @internal
+     * @param data Node's text.
+     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    constructor(data, attrs) {
+        super(attrs);
+        this._data = data || '';
+    }
+    /**
+     * @inheritDoc
+     */
+    get offsetSize() {
+        return this.data.length;
+    }
+    /**
+     * Returns a text data contained in the node.
+     */
+    get data() {
+        return this._data;
+    }
+    /**
+     * Converts `Text` instance to plain object and returns it.
+     *
+     * @returns`Text` instance converted to plain object.
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.data = this.data;
+        return json;
+    }
+    /**
+     * Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
+     *
+     * @internal
+     * @returns `Text` instance created using given plain object.
+     */
+    _clone() {
+        return new Text(this.data, this.getAttributes());
+    }
+    /**
+     * Creates a `Text` instance from given plain object (i.e. parsed JSON string).
+     *
+     * @param json Plain object to be converted to `Text`.
+     * @returns `Text` instance created using given plain object.
+     */
+    static fromJSON(json) {
+        return new Text(json.data, json.attributes);
+    }
+}
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
+Text.prototype.is = function (type) {
+    return type === '$text' || type === 'model:$text' ||
+        // This are legacy values kept for backward compatibility.
+        type === 'text' || type === 'model:text' ||
+        // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        type === 'node' || type === 'model:node';
+};

package/src/model/textproxy.d.ts

@@ -1,144 +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>;
-}
+/**
+ * @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>;
+}