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

package/dist/model/element.d.ts

@@ -1,187 +1,187 @@
 /**
- * @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/element
- */
-import { ModelNode, type ModelNodeAttributes } from './node.js';
-import { type ModelItem } from './item.js';
+* @module engine/model/element
+*/
+import { ModelNode, type ModelNodeAttributes } from "./node.js";
+import { type ModelItem } from "./item.js";
 /**
- * Model element. Type of {@link module:engine/model/node~ModelNode node} that has a
- * {@link module:engine/model/element~ModelElement#name name} and {@link module:engine/model/element~ModelElement#getChildren child nodes}.
- *
- * **Important**: see {@link module:engine/model/node~ModelNode} to read about restrictions using `Element` and `Node` API.
- */
+* Model element. Type of {@link module:engine/model/node~ModelNode node} that has a
+* {@link module:engine/model/element~ModelElement#name name} and {@link module:engine/model/element~ModelElement#getChildren child nodes}.
+*
+* **Important**: see {@link module:engine/model/node~ModelNode} to read about restrictions using `Element` and `Node` API.
+*/
 export declare class ModelElement extends ModelNode {
-    /**
-     * Element name.
-     */
-    readonly name: string;
-    /**
-     * List of children nodes.
-     */
-    private readonly _children;
-    /**
-     * Creates a model element.
-     *
-     * **Note:** Constructor of this class shouldn't be used directly in the code.
-     * Use the {@link module:engine/model/writer~ModelWriter#createElement} method instead.
-     *
-     * @internal
-     * @param name Element's name.
-     * @param attrs Element's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
-     * @param children One or more nodes to be inserted as children of created element.
-     */
-    constructor(name: string, attrs?: ModelNodeAttributes, children?: string | ModelItem | Iterable<string | ModelItem>);
-    /**
-     * Number of this element's children.
-     */
-    get childCount(): number;
-    /**
-     * Sum of {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all of this element's children.
-     */
-    get maxOffset(): number;
-    /**
-     * Is `true` if there are no nodes inside this element, `false` otherwise.
-     */
-    get isEmpty(): boolean;
-    /**
-     * Gets the child at the given index. Returns `null` if incorrect index was passed.
-     *
-     * @param index Index in this element.
-     * @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 element.
-     * @returns Child node.
-     */
-    getChildAtOffset(offset: number): ModelNode | null;
-    /**
-     * Returns an iterator that iterates over all of this element's children.
-     */
-    getChildren(): IterableIterator<ModelNode>;
-    /**
-     * Returns an index of the given child node. Returns `null` if given node is not a child of this element.
-     *
-     * @param node Child node to look for.
-     * @returns Child node's index in this element.
-     */
-    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 element.
-     *
-     * @param node Child node to look for.
-     * @returns Child node's starting offset.
-     */
-    getChildStartOffset(node: ModelNode): number | null;
-    /**
-     * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
-     * too high, returns {@link module:engine/model/element~ModelElement#getChildIndex index after last child}.
-     *
-     * ```ts
-     * const textNode = new Text( 'foo' );
-     * const pElement = new Element( 'p' );
-     * const divElement = new Element( [ textNode, pElement ] );
-     * divElement.offsetToIndex( -1 ); // Returns 0, because offset is too low.
-     * divElement.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
-     * divElement.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
-     * divElement.offsetToIndex( 2 ); // Returns 0.
-     * divElement.offsetToIndex( 3 ); // Returns 1.
-     * divElement.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
-     * ```
-     */
-    offsetToIndex(offset: number): 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;
-    /**
-     * Returns the parent element of the given name. Returns null if the element is not inside the desired parent.
-     *
-     * @param parentName The name of the parent element to find.
-     * @param options Options object.
-     * @param options.includeSelf When set to `true` this node will be also included while searching.
-     */
-    findAncestor(parentName: string, options?: {
-        includeSelf?: boolean;
-    }): ModelElement | null;
-    /**
-     * Converts `Element` instance to plain object and returns it. Takes care of converting all of this element's children.
-     *
-     * @returns `Element` instance converted to plain object.
-     */
-    toJSON(): unknown;
-    /**
-     * Creates a copy of this element and returns it. Created element has the same name and attributes as the original element.
-     * If clone is deep, the original element's children are also cloned. If not, then empty element is returned.
-     *
-     * @internal
-     * @param deep If set to `true` clones element and all its children recursively. When set to `false`,
-     * element will be cloned without any child.
-     */
-    _clone(deep?: boolean): ModelElement;
-    /**
-     * {@link module:engine/model/element~ModelElement#_insertChild Inserts} one or more nodes at the end of this element.
-     *
-     * @see module:engine/model/writer~ModelWriter#append
-     * @internal
-     * @param nodes Nodes to be inserted.
-     */
-    _appendChild(nodes: 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 element.
-     *
-     * @see module:engine/model/writer~ModelWriter#insert
-     * @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`.
-     *
-     * @see module:engine/model/writer~ModelWriter#remove
-     * @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;
-    /**
-     * Creates an `Element` instance from given plain object (i.e. parsed JSON string).
-     * Converts `Element` children to proper nodes.
-     *
-     * @param json Plain object to be converted to `Element`.
-     * @returns `Element` instance created using given plain object.
-     */
-    static fromJSON(json: any): ModelElement;
+	/**
+	* Element name.
+	*/
+	readonly name: string;
+	/**
+	* List of children nodes.
+	*/
+	private readonly _children;
+	/**
+	* Creates a model element.
+	*
+	* **Note:** Constructor of this class shouldn't be used directly in the code.
+	* Use the {@link module:engine/model/writer~ModelWriter#createElement} method instead.
+	*
+	* @internal
+	* @param name Element's name.
+	* @param attrs Element's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+	* @param children One or more nodes to be inserted as children of created element.
+	*/
+	constructor(name: string, attrs?: ModelNodeAttributes, children?: string | ModelItem | Iterable<string | ModelItem>);
+	/**
+	* Number of this element's children.
+	*/
+	get childCount(): number;
+	/**
+	* Sum of {@link module:engine/model/node~ModelNode#offsetSize offset sizes} of all of this element's children.
+	*/
+	get maxOffset(): number;
+	/**
+	* Is `true` if there are no nodes inside this element, `false` otherwise.
+	*/
+	get isEmpty(): boolean;
+	/**
+	* Gets the child at the given index. Returns `null` if incorrect index was passed.
+	*
+	* @param index Index in this element.
+	* @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 element.
+	* @returns Child node.
+	*/
+	getChildAtOffset(offset: number): ModelNode | null;
+	/**
+	* Returns an iterator that iterates over all of this element's children.
+	*/
+	getChildren(): IterableIterator<ModelNode>;
+	/**
+	* Returns an index of the given child node. Returns `null` if given node is not a child of this element.
+	*
+	* @param node Child node to look for.
+	* @returns Child node's index in this element.
+	*/
+	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 element.
+	*
+	* @param node Child node to look for.
+	* @returns Child node's starting offset.
+	*/
+	getChildStartOffset(node: ModelNode): number | null;
+	/**
+	* Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
+	* too high, returns {@link module:engine/model/element~ModelElement#getChildIndex index after last child}.
+	*
+	* ```ts
+	* const textNode = new Text( 'foo' );
+	* const pElement = new Element( 'p' );
+	* const divElement = new Element( [ textNode, pElement ] );
+	* divElement.offsetToIndex( -1 ); // Returns 0, because offset is too low.
+	* divElement.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
+	* divElement.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
+	* divElement.offsetToIndex( 2 ); // Returns 0.
+	* divElement.offsetToIndex( 3 ); // Returns 1.
+	* divElement.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
+	* ```
+	*/
+	offsetToIndex(offset: number): 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;
+	/**
+	* Returns the parent element of the given name. Returns null if the element is not inside the desired parent.
+	*
+	* @param parentName The name of the parent element to find.
+	* @param options Options object.
+	* @param options.includeSelf When set to `true` this node will be also included while searching.
+	*/
+	findAncestor(parentName: string, options?: {
+		includeSelf?: boolean;
+	}): ModelElement | null;
+	/**
+	* Converts `Element` instance to plain object and returns it. Takes care of converting all of this element's children.
+	*
+	* @returns `Element` instance converted to plain object.
+	*/
+	override toJSON(): unknown;
+	/**
+	* Creates a copy of this element and returns it. Created element has the same name and attributes as the original element.
+	* If clone is deep, the original element's children are also cloned. If not, then empty element is returned.
+	*
+	* @internal
+	* @param deep If set to `true` clones element and all its children recursively. When set to `false`,
+	* element will be cloned without any child.
+	*/
+	override _clone(deep?: boolean): ModelElement;
+	/**
+	* {@link module:engine/model/element~ModelElement#_insertChild Inserts} one or more nodes at the end of this element.
+	*
+	* @see module:engine/model/writer~ModelWriter#append
+	* @internal
+	* @param nodes Nodes to be inserted.
+	*/
+	_appendChild(nodes: 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 element.
+	*
+	* @see module:engine/model/writer~ModelWriter#insert
+	* @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`.
+	*
+	* @see module:engine/model/writer~ModelWriter#remove
+	* @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;
+	/**
+	* Creates an `Element` instance from given plain object (i.e. parsed JSON string).
+	* Converts `Element` children to proper nodes.
+	*
+	* @param json Plain object to be converted to `Element`.
+	* @returns `Element` instance created using given plain object.
+	*/
+	static fromJSON(json: any): ModelElement;
 }

package/dist/model/history.d.ts

@@ -1,114 +1,114 @@
 /**
- * @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/history
- */
-import { type Operation } from './operation/operation.js';
+* @module engine/model/history
+*/
+import { type Operation } from "./operation/operation.js";
 /**
- * `History` keeps the track of all the operations applied to the {@link module:engine/model/document~ModelDocument document}.
- */
+* `History` keeps the track of all the operations applied to the {@link module:engine/model/document~ModelDocument document}.
+*/
 export declare class History {
-    /**
-     * Operations added to the history.
-     */
-    private _operations;
-    /**
-     * Holds an information which {@link module:engine/model/operation/operation~Operation operation} undoes which
-     * {@link module:engine/model/operation/operation~Operation operation}.
-     *
-     * Keys of the map are "undoing operations", that is operations that undone some other operations. For each key, the
-     * value is an operation that has been undone by the "undoing operation".
-     */
-    private _undoPairs;
-    /**
-     * Holds all undone operations.
-     */
-    private _undoneOperations;
-    /**
-     * A map that allows retrieving the operations fast based on the given base version.
-     */
-    private _baseVersionToOperationIndex;
-    /**
-     * The history version.
-     */
-    private _version;
-    /**
-     * The gap pairs kept in the <from,to> format.
-     *
-     * Anytime the `history.version` is set to a version larger than `history.version + 1`,
-     * a new <lastHistoryVersion, newHistoryVersion> entry is added to the map.
-     */
-    private _gaps;
-    /**
-     * The version of the last operation in the history.
-     *
-     * The history version is incremented automatically when a new operation is added to the history.
-     * Setting the version manually should be done only in rare circumstances when a gap is planned
-     * between history versions. When doing so, a gap will be created and the history will accept adding
-     * an operation with base version equal to the new history version.
-     */
-    get version(): number;
-    set version(version: number);
-    /**
-     * The last history operation.
-     */
-    get lastOperation(): Operation | undefined;
-    /**
-     * Adds an operation to the history and increments the history version.
-     *
-     * The operation's base version should be equal to the history version. Otherwise an error is thrown.
-     */
-    addOperation(operation: Operation): void;
-    /**
-     * Returns operations from the given range of operation base versions that were added to the history.
-     *
-     * Note that there may be gaps in operations base versions.
-     *
-     * @param fromBaseVersion Base version from which operations should be returned (inclusive).
-     * @param toBaseVersion Base version up to which operations should be returned (exclusive).
-     * @returns History operations for the given range, in chronological order.
-     */
-    getOperations(fromBaseVersion?: number, toBaseVersion?: number): Array<Operation>;
-    /**
-     * Returns operation from the history that bases on given `baseVersion`.
-     *
-     * @param baseVersion Base version of the operation to get.
-     * @returns Operation with given base version or `undefined` if there is no such operation in history.
-     */
-    getOperation(baseVersion: number): Operation | undefined;
-    /**
-     * Marks in history that one operation is an operation that is undoing the other operation. By marking operation this way,
-     * history is keeping more context information about operations, which helps in operational transformation.
-     *
-     * @param undoneOperation Operation which is undone by `undoingOperation`.
-     * @param undoingOperation Operation which undoes `undoneOperation`.
-     */
-    setOperationAsUndone(undoneOperation: Operation, undoingOperation: Operation): void;
-    /**
-     * Checks whether given `operation` is undoing any other operation.
-     *
-     * @param operation Operation to check.
-     * @returns `true` if given `operation` is undoing any other operation, `false` otherwise.
-     */
-    isUndoingOperation(operation: Operation): boolean;
-    /**
-     * Checks whether given `operation` has been undone by any other operation.
-     *
-     * @param operation Operation to check.
-     * @returns `true` if given `operation` has been undone any other operation, `false` otherwise.
-     */
-    isUndoneOperation(operation: Operation): boolean;
-    /**
-     * For given `undoingOperation`, returns the operation which has been undone by it.
-     *
-     * @returns Operation that has been undone by given `undoingOperation` or `undefined`
-     * if given `undoingOperation` is not undoing any other operation.
-     */
-    getUndoneOperation(undoingOperation: Operation): Operation | undefined;
-    /**
-     * Resets the history of operations.
-     */
-    reset(): void;
+	/**
+	* Operations added to the history.
+	*/
+	private _operations;
+	/**
+	* Holds an information which {@link module:engine/model/operation/operation~Operation operation} undoes which
+	* {@link module:engine/model/operation/operation~Operation operation}.
+	*
+	* Keys of the map are "undoing operations", that is operations that undone some other operations. For each key, the
+	* value is an operation that has been undone by the "undoing operation".
+	*/
+	private _undoPairs;
+	/**
+	* Holds all undone operations.
+	*/
+	private _undoneOperations;
+	/**
+	* A map that allows retrieving the operations fast based on the given base version.
+	*/
+	private _baseVersionToOperationIndex;
+	/**
+	* The history version.
+	*/
+	private _version;
+	/**
+	* The gap pairs kept in the <from,to> format.
+	*
+	* Anytime the `history.version` is set to a version larger than `history.version + 1`,
+	* a new <lastHistoryVersion, newHistoryVersion> entry is added to the map.
+	*/
+	private _gaps;
+	/**
+	* The version of the last operation in the history.
+	*
+	* The history version is incremented automatically when a new operation is added to the history.
+	* Setting the version manually should be done only in rare circumstances when a gap is planned
+	* between history versions. When doing so, a gap will be created and the history will accept adding
+	* an operation with base version equal to the new history version.
+	*/
+	get version(): number;
+	set version(version: number);
+	/**
+	* The last history operation.
+	*/
+	get lastOperation(): Operation | undefined;
+	/**
+	* Adds an operation to the history and increments the history version.
+	*
+	* The operation's base version should be equal to the history version. Otherwise an error is thrown.
+	*/
+	addOperation(operation: Operation): void;
+	/**
+	* Returns operations from the given range of operation base versions that were added to the history.
+	*
+	* Note that there may be gaps in operations base versions.
+	*
+	* @param fromBaseVersion Base version from which operations should be returned (inclusive).
+	* @param toBaseVersion Base version up to which operations should be returned (exclusive).
+	* @returns History operations for the given range, in chronological order.
+	*/
+	getOperations(fromBaseVersion?: number, toBaseVersion?: number): Array<Operation>;
+	/**
+	* Returns operation from the history that bases on given `baseVersion`.
+	*
+	* @param baseVersion Base version of the operation to get.
+	* @returns Operation with given base version or `undefined` if there is no such operation in history.
+	*/
+	getOperation(baseVersion: number): Operation | undefined;
+	/**
+	* Marks in history that one operation is an operation that is undoing the other operation. By marking operation this way,
+	* history is keeping more context information about operations, which helps in operational transformation.
+	*
+	* @param undoneOperation Operation which is undone by `undoingOperation`.
+	* @param undoingOperation Operation which undoes `undoneOperation`.
+	*/
+	setOperationAsUndone(undoneOperation: Operation, undoingOperation: Operation): void;
+	/**
+	* Checks whether given `operation` is undoing any other operation.
+	*
+	* @param operation Operation to check.
+	* @returns `true` if given `operation` is undoing any other operation, `false` otherwise.
+	*/
+	isUndoingOperation(operation: Operation): boolean;
+	/**
+	* Checks whether given `operation` has been undone by any other operation.
+	*
+	* @param operation Operation to check.
+	* @returns `true` if given `operation` has been undone any other operation, `false` otherwise.
+	*/
+	isUndoneOperation(operation: Operation): boolean;
+	/**
+	* For given `undoingOperation`, returns the operation which has been undone by it.
+	*
+	* @returns Operation that has been undone by given `undoingOperation` or `undefined`
+	* if given `undoingOperation` is not undoing any other operation.
+	*/
+	getUndoneOperation(undoingOperation: Operation): Operation | undefined;
+	/**
+	* Resets the history of operations.
+	*/
+	reset(): void;
 }

package/dist/model/item.d.ts

@@ -1,13 +1,13 @@
 /**
- * @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/item
- */
-import { type ModelNode } from './node.js';
-import { type ModelTextProxy } from './textproxy.js';
+* @module engine/model/item
+*/
+import { type ModelNode } from "./node.js";
+import { type ModelTextProxy } from "./textproxy.js";
 /**
- * Item is a {@link module:engine/model/node~ModelNode} or {@link module:engine/model/textproxy~ModelTextProxy}.
- */
+* Item is a {@link module:engine/model/node~ModelNode} or {@link module:engine/model/textproxy~ModelTextProxy}.
+*/
 export type ModelItem = ModelNode | ModelTextProxy;