@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/model/element.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/element
+ */
+import Node, { type NodeAttributes } from './node.js';
+import type Item from './item.js';
+/**
+ * Model element. Type of {@link module:engine/model/node~Node node} that has a {@link module:engine/model/element~Element#name name} and
+ * {@link module:engine/model/element~Element#getChildren child nodes}.
+ *
+ * **Important**: see {@link module:engine/model/node~Node} to read about restrictions using `Element` and `Node` API.
+ */
+export default class Element extends Node {
+    /**
+     * 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~Writer#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?: NodeAttributes, children?: string | Item | Iterable<string | Item>);
+    /**
+     * Number of this element's children.
+     */
+    get childCount(): number;
+    /**
+     * Sum of {@link module:engine/model/node~Node#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.
+     */
+    getChild(index: number): Node | null;
+    /**
+     * Returns an iterator that iterates over all of this element's children.
+     */
+    getChildren(): IterableIterator<Node>;
+    /**
+     * 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: Node): number | null;
+    /**
+     * Returns the starting offset of given child. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#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: Node): 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~Element#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>): Node;
+    /**
+     * 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;
+    }): Element | 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): Element;
+    /**
+     * {@link module:engine/model/element~Element#_insertChild Inserts} one or more nodes at the end of this element.
+     *
+     * @see module:engine/model/writer~Writer#append
+     * @internal
+     * @param nodes Nodes to be inserted.
+     */
+    _appendChild(nodes: string | Item | Iterable<string | Item>): void;
+    /**
+     * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
+     * to this element.
+     *
+     * @see module:engine/model/writer~Writer#insert
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param items Items to be inserted.
+     */
+    _insertChild(index: number, items: string | Item | Iterable<string | Item>): void;
+    /**
+     * Removes one or more nodes starting at the given index and sets
+     * {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
+     *
+     * @see module:engine/model/writer~Writer#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<Node>;
+    /**
+     * 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): Element;
+}

package/src/model/element.js

@@ -0,0 +1,281 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/element
+ */
+import Node from './node.js';
+import NodeList from './nodelist.js';
+import Text from './text.js';
+import TextProxy from './textproxy.js';
+import { isIterable } from '@ckeditor/ckeditor5-utils';
+// @if CK_DEBUG_ENGINE // const { stringifyMap, convertMapToStringifiedObject, convertMapToTags } = require( '../dev-utils/utils' );
+/**
+ * Model element. Type of {@link module:engine/model/node~Node node} that has a {@link module:engine/model/element~Element#name name} and
+ * {@link module:engine/model/element~Element#getChildren child nodes}.
+ *
+ * **Important**: see {@link module:engine/model/node~Node} to read about restrictions using `Element` and `Node` API.
+ */
+export default class Element extends Node {
+    /**
+     * Creates a model element.
+     *
+     * **Note:** Constructor of this class shouldn't be used directly in the code.
+     * Use the {@link module:engine/model/writer~Writer#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, attrs, children) {
+        super(attrs);
+        /**
+         * List of children nodes.
+         */
+        this._children = new NodeList();
+        this.name = name;
+        if (children) {
+            this._insertChild(0, children);
+        }
+    }
+    /**
+     * Number of this element's children.
+     */
+    get childCount() {
+        return this._children.length;
+    }
+    /**
+     * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all of this element's children.
+     */
+    get maxOffset() {
+        return this._children.maxOffset;
+    }
+    /**
+     * Is `true` if there are no nodes inside this element, `false` otherwise.
+     */
+    get isEmpty() {
+        return this.childCount === 0;
+    }
+    /**
+     * Gets the child at the given index.
+     */
+    getChild(index) {
+        return this._children.getNode(index);
+    }
+    /**
+     * Returns an iterator that iterates over all of this element's children.
+     */
+    getChildren() {
+        return this._children[Symbol.iterator]();
+    }
+    /**
+     * 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) {
+        return this._children.getNodeIndex(node);
+    }
+    /**
+     * Returns the starting offset of given child. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#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) {
+        return this._children.getNodeStartOffset(node);
+    }
+    /**
+     * 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~Element#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) {
+        return this._children.offsetToIndex(offset);
+    }
+    /**
+     * 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) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
+        let node = this;
+        for (const index of relativePath) {
+            node = node.getChild(node.offsetToIndex(index));
+        }
+        return node;
+    }
+    /**
+     * 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, options = {}) {
+        let parent = options.includeSelf ? this : this.parent;
+        while (parent) {
+            if (parent.name === parentName) {
+                return parent;
+            }
+            parent = parent.parent;
+        }
+        return 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() {
+        const json = super.toJSON();
+        json.name = this.name;
+        if (this._children.length > 0) {
+            json.children = [];
+            for (const node of this._children) {
+                json.children.push(node.toJSON());
+            }
+        }
+        return json;
+    }
+    /**
+     * 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 = false) {
+        const children = deep ? Array.from(this._children).map(node => node._clone(true)) : undefined;
+        return new Element(this.name, this.getAttributes(), children);
+    }
+    /**
+     * {@link module:engine/model/element~Element#_insertChild Inserts} one or more nodes at the end of this element.
+     *
+     * @see module:engine/model/writer~Writer#append
+     * @internal
+     * @param nodes Nodes to be inserted.
+     */
+    _appendChild(nodes) {
+        this._insertChild(this.childCount, nodes);
+    }
+    /**
+     * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
+     * to this element.
+     *
+     * @see module:engine/model/writer~Writer#insert
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param items Items to be inserted.
+     */
+    _insertChild(index, items) {
+        const nodes = normalize(items);
+        for (const node of nodes) {
+            // If node that is being added to this element is already inside another element, first remove it from the old parent.
+            if (node.parent !== null) {
+                node._remove();
+            }
+            node.parent = this;
+        }
+        this._children._insertNodes(index, nodes);
+    }
+    /**
+     * Removes one or more nodes starting at the given index and sets
+     * {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
+     *
+     * @see module:engine/model/writer~Writer#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, howMany = 1) {
+        const nodes = this._children._removeNodes(index, howMany);
+        for (const node of nodes) {
+            node.parent = null;
+        }
+        return nodes;
+    }
+    /**
+     * 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) {
+        let children;
+        if (json.children) {
+            children = [];
+            for (const child of json.children) {
+                if (child.name) {
+                    // If child has name property, it is an Element.
+                    children.push(Element.fromJSON(child));
+                }
+                else {
+                    // Otherwise, it is a Text node.
+                    children.push(Text.fromJSON(child));
+                }
+            }
+        }
+        return new Element(json.name, json.attributes, children);
+    }
+}
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
+Element.prototype.is = function (type, name) {
+    if (!name) {
+        return type === 'element' || type === 'model:element' ||
+            // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+            type === 'node' || type === 'model:node';
+    }
+    return name === this.name && (type === 'element' || type === 'model:element');
+};
+/**
+ * Converts strings to Text and non-iterables to arrays.
+ */
+function normalize(nodes) {
+    // Separate condition because string is iterable.
+    if (typeof nodes == 'string') {
+        return [new Text(nodes)];
+    }
+    if (!isIterable(nodes)) {
+        nodes = [nodes];
+    }
+    // Array.from to enable .map() on non-arrays.
+    return Array.from(nodes)
+        .map(node => {
+        if (typeof node == 'string') {
+            return new Text(node);
+        }
+        if (node instanceof TextProxy) {
+            return new Text(node.data, node.getAttributes());
+        }
+        return node;
+    });
+}

package/src/model/history.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type Operation from './operation/operation.js';
+/**
+ * @module engine/model/history
+ */
+/**
+ * `History` keeps the track of all the operations applied to the {@link module:engine/model/document~Document document}.
+ */
+export default 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;
+}