@ckeditor/ckeditor5-engine 48.2.0 → 48.3.0-alpha.0

package/dist/model/documentfragment.d.ts

@@ -1,219 +1,219 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module engine/model/documentfragment
- */
-import { ModelTypeCheckable } from './typecheckable.js';
-import { type ModelItem } from './item.js';
-import { type ModelNode } from './node.js';
-import { type ModelRange } from './range.js';
+* @module engine/model/documentfragment
+*/
+import { ModelTypeCheckable } from "./typecheckable.js";
+import { type ModelItem } from "./item.js";
+import { type ModelNode } from "./node.js";
+import { type ModelRange } from "./range.js";
 /**
- * ModelDocumentFragment represents a part of model which does not have a common root but its top-level nodes
- * can be seen as siblings. In other words, it is a detached part of model tree, without a root.
- *
- * ModelDocumentFragment has own {@link module:engine/model/markercollection~MarkerCollection}. Markers from this collection
- * will be set to the {@link module:engine/model/model~Model#markers model markers} by a
- * {@link module:engine/model/writer~ModelWriter#insert} function.
- */
+* ModelDocumentFragment represents a part of model which does not have a common root but its top-level nodes
+* can be seen as siblings. In other words, it is a detached part of model tree, without a root.
+*
+* ModelDocumentFragment has own {@link module:engine/model/markercollection~MarkerCollection}. Markers from this collection
+* will be set to the {@link module:engine/model/model~Model#markers model markers} by a
+* {@link module:engine/model/writer~ModelWriter#insert} function.
+*/
 export declare class ModelDocumentFragment extends ModelTypeCheckable implements Iterable<ModelNode> {
-    /**
-     * ModelDocumentFragment static markers map. This is a list of names and {@link module:engine/model/range~ModelRange ranges}
-     * which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
-     * when ModelDocumentFragment will be inserted to the document.
-     */
-    readonly markers: Map<string, ModelRange>;
-    /**
-     * Artificial element name. Returns `undefined`. Added for compatibility reasons.
-     */
-    name?: undefined;
-    /**
-     * Artificial root name. Returns `undefined`. Added for compatibility reasons.
-     */
-    rootName?: undefined;
-    /**
-     * List of nodes contained inside the document fragment.
-     */
-    private readonly _children;
-    /**
-     * Creates an empty `ModelDocumentFragment`.
-     *
-     * **Note:** Constructor of this class shouldn't be used directly in the code.
-     * Use the {@link module:engine/model/writer~ModelWriter#createDocumentFragment} method instead.
-     *
-     * @internal
-     * @param children Nodes to be contained inside the `ModelDocumentFragment`.
-     */
-    constructor(children?: ModelNode | Iterable<ModelNode>);
-    /**
-     * Returns an iterator that iterates over all nodes contained inside this document fragment.
-     */
-    [Symbol.iterator](): IterableIterator<ModelNode>;
-    /**
-     * Number of this document fragment's children.
-     */
-    get childCount(): number;
-    /**
-     * Sum of {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all of this document fragment's children.
-     */
-    get maxOffset(): number;
-    /**
-     * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
-     */
-    get isEmpty(): boolean;
-    /**
-     * Artificial next sibling. Returns `null`. Added for compatibility reasons.
-     */
-    get nextSibling(): null;
-    /**
-     * Artificial previous sibling. Returns `null`. Added for compatibility reasons.
-     */
-    get previousSibling(): null;
-    /**
-     * Artificial root of `ModelDocumentFragment`. Returns itself. Added for compatibility reasons.
-     */
-    get root(): ModelDocumentFragment;
-    /**
-     * Artificial parent of `ModelDocumentFragment`. Returns `null`. Added for compatibility reasons.
-     */
-    get parent(): null;
-    /**
-     * Artificial owner of `ModelDocumentFragment`. Returns `null`. Added for compatibility reasons.
-     */
-    get document(): null;
-    /**
-     * Returns `false` as `ModelDocumentFragment` by definition is not attached to a document. Added for compatibility reasons.
-     */
-    isAttached(): false;
-    /**
-     * Returns empty array. Added for compatibility reasons.
-     */
-    getAncestors(): Array<never>;
-    /**
-     * Gets the child at the given index. Returns `null` if incorrect index was passed.
-     *
-     * @param index Index in this document fragment.
-     * @returns Child node.
-     */
-    getChild(index: number): ModelNode | null;
-    /**
-     * Gets the child at the given offset. Returns `null` if incorrect index was passed.
-     *
-     * @param offset Offset in this document fragment.
-     * @returns Child node.
-     */
-    getChildAtOffset(offset: number): ModelNode | null;
-    /**
-     * Returns an iterator that iterates over all of this document fragment's children.
-     */
-    getChildren(): IterableIterator<ModelNode>;
-    /**
-     * Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
-     *
-     * @param node Child node to look for.
-     * @returns Child node's index.
-     */
-    getChildIndex(node: ModelNode): number | null;
-    /**
-     * Returns the starting offset of given child. Starting offset is equal to the sum of
-     * {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all node's siblings that are before it. Returns `null` if
-     * given node is not a child of this document fragment.
-     *
-     * @param node Child node to look for.
-     * @returns Child node's starting offset.
-     */
-    getChildStartOffset(node: ModelNode): number | null;
-    /**
-     * Returns path to a `ModelDocumentFragment`, which is an empty array. Added for compatibility reasons.
-     */
-    getPath(): Array<number>;
-    /**
-     * Returns a descendant node by its path relative to this element.
-     *
-     * ```ts
-     * // <this>a<b>c</b></this>
-     * this.getNodeByPath( [ 0 ] );     // -> "a"
-     * this.getNodeByPath( [ 1 ] );     // -> <b>
-     * this.getNodeByPath( [ 1, 0 ] );  // -> "c"
-     * ```
-     *
-     * @param relativePath Path of the node to find, relative to this element.
-     */
-    getNodeByPath(relativePath: Array<number>): ModelNode | ModelDocumentFragment;
-    /**
-     * Converts offset "position" to index "position".
-     *
-     * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
-     * too high, returns index after last child.
-     *
-     * ```ts
-     * const textNode = new Text( 'foo' );
-     * const pElement = new Element( 'p' );
-     * const docFrag = new ModelDocumentFragment( [ textNode, pElement ] );
-     * docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
-     * docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
-     * docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
-     * docFrag.offsetToIndex( 2 ); // Returns 0.
-     * docFrag.offsetToIndex( 3 ); // Returns 1.
-     * docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
-     * ```
-     *
-     * @param offset Offset to look for.
-     * @returns Index of a node that occupies given offset.
-     */
-    offsetToIndex(offset: number): number;
-    /**
-     * Converts `ModelDocumentFragment` instance to plain object and returns it.
-     * Takes care of converting all of this document fragment's children.
-     *
-     * @returns `ModelDocumentFragment` instance converted to plain object.
-     */
-    toJSON(): unknown;
-    /**
-     * Creates a `ModelDocumentFragment` instance from given plain object (i.e. parsed JSON string).
-     * Converts `ModelDocumentFragment` children to proper nodes.
-     *
-     * @param json Plain object to be converted to `ModelDocumentFragment`.
-     * @returns `ModelDocumentFragment` instance created using given plain object.
-     */
-    static fromJSON(json: any): ModelDocumentFragment;
-    /**
-     * {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
-     *
-     * @internal
-     * @param items Items to be inserted.
-     */
-    _appendChild(items: string | ModelItem | Iterable<string | ModelItem>): void;
-    /**
-     * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~ModelNode#parent parent} of these nodes
-     * to this document fragment.
-     *
-     * @internal
-     * @param index Index at which nodes should be inserted.
-     * @param items Items to be inserted.
-     */
-    _insertChild(index: number, items: string | ModelItem | Iterable<string | ModelItem>): void;
-    /**
-     * Removes one or more nodes starting at the given index
-     * and sets {@link module:engine/model/node~ModelNode#parent parent} of these nodes to `null`.
-     *
-     * @internal
-     * @param index Index of the first node to remove.
-     * @param howMany Number of nodes to remove.
-     * @returns Array containing removed nodes.
-     */
-    _removeChildren(index: number, howMany?: number): Array<ModelNode>;
-    /**
-     * Removes children nodes provided as an array and sets
-     * the {@link module:engine/model/node~ModelNode#parent parent} of these nodes to `null`.
-     *
-     * These nodes do not need to be direct siblings.
-     *
-     * This method is faster than removing nodes one by one, as it recalculates offsets only once.
-     *
-     * @internal
-     * @param nodes Array of nodes.
-     */
-    _removeChildrenArray(nodes: Array<ModelNode>): void;
+	/**
+	* ModelDocumentFragment static markers map. This is a list of names and {@link module:engine/model/range~ModelRange ranges}
+	* which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
+	* when ModelDocumentFragment will be inserted to the document.
+	*/
+	readonly markers: Map<string, ModelRange>;
+	/**
+	* Artificial element name. Returns `undefined`. Added for compatibility reasons.
+	*/
+	name?: undefined;
+	/**
+	* Artificial root name. Returns `undefined`. Added for compatibility reasons.
+	*/
+	rootName?: undefined;
+	/**
+	* List of nodes contained inside the document fragment.
+	*/
+	private readonly _children;
+	/**
+	* Creates an empty `ModelDocumentFragment`.
+	*
+	* **Note:** Constructor of this class shouldn't be used directly in the code.
+	* Use the {@link module:engine/model/writer~ModelWriter#createDocumentFragment} method instead.
+	*
+	* @internal
+	* @param children Nodes to be contained inside the `ModelDocumentFragment`.
+	*/
+	constructor(children?: ModelNode | Iterable<ModelNode>);
+	/**
+	* Returns an iterator that iterates over all nodes contained inside this document fragment.
+	*/
+	[Symbol.iterator](): IterableIterator<ModelNode>;
+	/**
+	* Number of this document fragment's children.
+	*/
+	get childCount(): number;
+	/**
+	* Sum of {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all of this document fragment's children.
+	*/
+	get maxOffset(): number;
+	/**
+	* Is `true` if there are no nodes inside this document fragment, `false` otherwise.
+	*/
+	get isEmpty(): boolean;
+	/**
+	* Artificial next sibling. Returns `null`. Added for compatibility reasons.
+	*/
+	get nextSibling(): null;
+	/**
+	* Artificial previous sibling. Returns `null`. Added for compatibility reasons.
+	*/
+	get previousSibling(): null;
+	/**
+	* Artificial root of `ModelDocumentFragment`. Returns itself. Added for compatibility reasons.
+	*/
+	get root(): ModelDocumentFragment;
+	/**
+	* Artificial parent of `ModelDocumentFragment`. Returns `null`. Added for compatibility reasons.
+	*/
+	get parent(): null;
+	/**
+	* Artificial owner of `ModelDocumentFragment`. Returns `null`. Added for compatibility reasons.
+	*/
+	get document(): null;
+	/**
+	* Returns `false` as `ModelDocumentFragment` by definition is not attached to a document. Added for compatibility reasons.
+	*/
+	isAttached(): false;
+	/**
+	* Returns empty array. Added for compatibility reasons.
+	*/
+	getAncestors(): Array<never>;
+	/**
+	* Gets the child at the given index. Returns `null` if incorrect index was passed.
+	*
+	* @param index Index in this document fragment.
+	* @returns Child node.
+	*/
+	getChild(index: number): ModelNode | null;
+	/**
+	* Gets the child at the given offset. Returns `null` if incorrect index was passed.
+	*
+	* @param offset Offset in this document fragment.
+	* @returns Child node.
+	*/
+	getChildAtOffset(offset: number): ModelNode | null;
+	/**
+	* Returns an iterator that iterates over all of this document fragment's children.
+	*/
+	getChildren(): IterableIterator<ModelNode>;
+	/**
+	* Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
+	*
+	* @param node Child node to look for.
+	* @returns Child node's index.
+	*/
+	getChildIndex(node: ModelNode): number | null;
+	/**
+	* Returns the starting offset of given child. Starting offset is equal to the sum of
+	* {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all node's siblings that are before it. Returns `null` if
+	* given node is not a child of this document fragment.
+	*
+	* @param node Child node to look for.
+	* @returns Child node's starting offset.
+	*/
+	getChildStartOffset(node: ModelNode): number | null;
+	/**
+	* Returns path to a `ModelDocumentFragment`, which is an empty array. Added for compatibility reasons.
+	*/
+	getPath(): Array<number>;
+	/**
+	* Returns a descendant node by its path relative to this element.
+	*
+	* ```ts
+	* // <this>a<b>c</b></this>
+	* this.getNodeByPath( [ 0 ] );     // -> "a"
+	* this.getNodeByPath( [ 1 ] );     // -> <b>
+	* this.getNodeByPath( [ 1, 0 ] );  // -> "c"
+	* ```
+	*
+	* @param relativePath Path of the node to find, relative to this element.
+	*/
+	getNodeByPath(relativePath: Array<number>): ModelNode | ModelDocumentFragment;
+	/**
+	* Converts offset "position" to index "position".
+	*
+	* Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
+	* too high, returns index after last child.
+	*
+	* ```ts
+	* const textNode = new Text( 'foo' );
+	* const pElement = new Element( 'p' );
+	* const docFrag = new ModelDocumentFragment( [ textNode, pElement ] );
+	* docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
+	* docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
+	* docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
+	* docFrag.offsetToIndex( 2 ); // Returns 0.
+	* docFrag.offsetToIndex( 3 ); // Returns 1.
+	* docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
+	* ```
+	*
+	* @param offset Offset to look for.
+	* @returns Index of a node that occupies given offset.
+	*/
+	offsetToIndex(offset: number): number;
+	/**
+	* Converts `ModelDocumentFragment` instance to plain object and returns it.
+	* Takes care of converting all of this document fragment's children.
+	*
+	* @returns `ModelDocumentFragment` instance converted to plain object.
+	*/
+	toJSON(): unknown;
+	/**
+	* Creates a `ModelDocumentFragment` instance from given plain object (i.e. parsed JSON string).
+	* Converts `ModelDocumentFragment` children to proper nodes.
+	*
+	* @param json Plain object to be converted to `ModelDocumentFragment`.
+	* @returns `ModelDocumentFragment` instance created using given plain object.
+	*/
+	static fromJSON(json: any): ModelDocumentFragment;
+	/**
+	* {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
+	*
+	* @internal
+	* @param items Items to be inserted.
+	*/
+	_appendChild(items: string | ModelItem | Iterable<string | ModelItem>): void;
+	/**
+	* Inserts one or more nodes at the given index and sets {@link module:engine/model/node~ModelNode#parent parent} of these nodes
+	* to this document fragment.
+	*
+	* @internal
+	* @param index Index at which nodes should be inserted.
+	* @param items Items to be inserted.
+	*/
+	_insertChild(index: number, items: string | ModelItem | Iterable<string | ModelItem>): void;
+	/**
+	* Removes one or more nodes starting at the given index
+	* and sets {@link module:engine/model/node~ModelNode#parent parent} of these nodes to `null`.
+	*
+	* @internal
+	* @param index Index of the first node to remove.
+	* @param howMany Number of nodes to remove.
+	* @returns Array containing removed nodes.
+	*/
+	_removeChildren(index: number, howMany?: number): Array<ModelNode>;
+	/**
+	* Removes children nodes provided as an array and sets
+	* the {@link module:engine/model/node~ModelNode#parent parent} of these nodes to `null`.
+	*
+	* These nodes do not need to be direct siblings.
+	*
+	* This method is faster than removing nodes one by one, as it recalculates offsets only once.
+	*
+	* @internal
+	* @param nodes Array of nodes.
+	*/
+	_removeChildrenArray(nodes: Array<ModelNode>): void;
 }