@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/model/nodelist.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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/nodelist
+ */
+import Node from './node.js';
+/**
+ * Provides an interface to operate on a list of {@link module:engine/model/node~Node nodes}. `NodeList` is used internally
+ * in classes like {@link module:engine/model/element~Element Element}
+ * or {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment}.
+ */
+export default class NodeList implements Iterable<Node> {
+    /**
+     * Nodes contained in this node list.
+     */
+    private _nodes;
+    /**
+     * Creates an empty node list.
+     *
+     * @internal
+     * @param nodes Nodes contained in this node list.
+     */
+    constructor(nodes?: Iterable<Node>);
+    /**
+     * Iterable interface.
+     *
+     * Iterates over all nodes contained inside this node list.
+     */
+    [Symbol.iterator](): IterableIterator<Node>;
+    /**
+     * Number of nodes contained inside this node list.
+     */
+    get length(): number;
+    /**
+     * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes contained inside this node list.
+     */
+    get maxOffset(): number;
+    /**
+     * Gets the node at the given index. Returns `null` if incorrect index was passed.
+     */
+    getNode(index: number): Node | null;
+    /**
+     * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+     */
+    getNodeIndex(node: Node): number | null;
+    /**
+     * Returns the starting offset of given node. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+     */
+    getNodeStartOffset(node: Node): number | null;
+    /**
+     * Converts index to offset in node list.
+     *
+     * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+     */
+    indexToOffset(index: number): number;
+    /**
+     * Converts offset in node list to index.
+     *
+     * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+     */
+    offsetToIndex(offset: number): number;
+    /**
+     * Inserts given nodes at given index.
+     *
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param nodes Nodes to be inserted.
+     */
+    _insertNodes(index: number, nodes: Iterable<Node>): void;
+    /**
+     * Removes one or more nodes starting at the given index.
+     *
+     * @internal
+     * @param indexStart Index of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns Array containing removed nodes.
+     */
+    _removeNodes(indexStart: number, howMany?: number): Array<Node>;
+    /**
+     * Converts `NodeList` instance to an array containing nodes that were inserted in the node list. Nodes
+     * are also converted to their plain object representation.
+     *
+     * @returns `NodeList` instance converted to `Array`.
+     */
+    toJSON(): unknown;
+}

package/src/model/nodelist.js

@@ -0,0 +1,170 @@
+/**
+ * @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/nodelist
+ */
+import Node from './node.js';
+import { CKEditorError, spliceArray } from '@ckeditor/ckeditor5-utils';
+/**
+ * Provides an interface to operate on a list of {@link module:engine/model/node~Node nodes}. `NodeList` is used internally
+ * in classes like {@link module:engine/model/element~Element Element}
+ * or {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment}.
+ */
+export default class NodeList {
+    /**
+     * Creates an empty node list.
+     *
+     * @internal
+     * @param nodes Nodes contained in this node list.
+     */
+    constructor(nodes) {
+        /**
+         * Nodes contained in this node list.
+         */
+        this._nodes = [];
+        if (nodes) {
+            this._insertNodes(0, nodes);
+        }
+    }
+    /**
+     * Iterable interface.
+     *
+     * Iterates over all nodes contained inside this node list.
+     */
+    [Symbol.iterator]() {
+        return this._nodes[Symbol.iterator]();
+    }
+    /**
+     * Number of nodes contained inside this node list.
+     */
+    get length() {
+        return this._nodes.length;
+    }
+    /**
+     * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes contained inside this node list.
+     */
+    get maxOffset() {
+        return this._nodes.reduce((sum, node) => sum + node.offsetSize, 0);
+    }
+    /**
+     * Gets the node at the given index. Returns `null` if incorrect index was passed.
+     */
+    getNode(index) {
+        return this._nodes[index] || null;
+    }
+    /**
+     * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+     */
+    getNodeIndex(node) {
+        const index = this._nodes.indexOf(node);
+        return index == -1 ? null : index;
+    }
+    /**
+     * Returns the starting offset of given node. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+     */
+    getNodeStartOffset(node) {
+        const index = this.getNodeIndex(node);
+        if (index === null) {
+            return null;
+        }
+        let sum = 0;
+        for (let i = 0; i < index; i++) {
+            sum += this._nodes[i].offsetSize;
+        }
+        return sum;
+    }
+    /**
+     * Converts index to offset in node list.
+     *
+     * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+     */
+    indexToOffset(index) {
+        if (index == this._nodes.length) {
+            return this.maxOffset;
+        }
+        const node = this._nodes[index];
+        if (!node) {
+            /**
+             * Given index cannot be found in the node list.
+             *
+             * @error model-nodelist-index-out-of-bounds
+             */
+            throw new CKEditorError('model-nodelist-index-out-of-bounds', this);
+        }
+        return this.getNodeStartOffset(node);
+    }
+    /**
+     * Converts offset in node list to index.
+     *
+     * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+     */
+    offsetToIndex(offset) {
+        let totalOffset = 0;
+        for (const node of this._nodes) {
+            if (offset >= totalOffset && offset < totalOffset + node.offsetSize) {
+                return this.getNodeIndex(node);
+            }
+            totalOffset += node.offsetSize;
+        }
+        if (totalOffset != offset) {
+            /**
+             * Given offset cannot be found in the node list.
+             *
+             * @error model-nodelist-offset-out-of-bounds
+             * @param offset
+             * @param nodeList Stringified node list.
+             */
+            throw new CKEditorError('model-nodelist-offset-out-of-bounds', this, {
+                offset,
+                nodeList: this
+            });
+        }
+        return this.length;
+    }
+    /**
+     * Inserts given nodes at given index.
+     *
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param nodes Nodes to be inserted.
+     */
+    _insertNodes(index, nodes) {
+        // Validation.
+        for (const node of nodes) {
+            if (!(node instanceof Node)) {
+                /**
+                 * Trying to insert an object which is not a Node instance.
+                 *
+                 * @error model-nodelist-insertnodes-not-node
+                 */
+                throw new CKEditorError('model-nodelist-insertnodes-not-node', this);
+            }
+        }
+        this._nodes = spliceArray(this._nodes, Array.from(nodes), index, 0);
+    }
+    /**
+     * Removes one or more nodes starting at the given index.
+     *
+     * @internal
+     * @param indexStart Index of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns Array containing removed nodes.
+     */
+    _removeNodes(indexStart, howMany = 1) {
+        return this._nodes.splice(indexStart, howMany);
+    }
+    /**
+     * Converts `NodeList` instance to an array containing nodes that were inserted in the node list. Nodes
+     * are also converted to their plain object representation.
+     *
+     * @returns `NodeList` instance converted to `Array`.
+     */
+    toJSON() {
+        return this._nodes.map(node => node.toJSON());
+    }
+}

package/src/model/operation/attributeoperation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @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/operation/attributeoperation
+ */
+import Operation from './operation.js';
+import Range from '../range.js';
+import type Document from '../document.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Operation to change nodes' attribute.
+ *
+ * Using this class you can add, remove or change value of the attribute.
+ */
+export default class AttributeOperation extends Operation {
+    /**
+     * Range on which operation should be applied.
+     *
+     * @readonly
+     */
+    range: Range;
+    /**
+     * Key of an attribute to change or remove.
+     *
+     * @readonly
+     */
+    key: string;
+    /**
+     * Old value of the attribute with given key or `null`, if attribute was not set before.
+     *
+     * @readonly
+     */
+    oldValue: unknown;
+    /**
+     * New value of the attribute with given key or `null`, if operation should remove attribute.
+     *
+     * @readonly
+     */
+    newValue: unknown;
+    /**
+     * Creates an operation that changes, removes or adds attributes.
+     *
+     * If only `newValue` is set, attribute will be added on a node. Note that all nodes in operation's range must not
+     * have an attribute with the same key as the added attribute.
+     *
+     * If only `oldValue` is set, then attribute with given key will be removed. Note that all nodes in operation's range
+     * must have an attribute with that key added.
+     *
+     * If both `newValue` and `oldValue` are set, then the operation will change the attribute value. Note that all nodes in
+     * operation's ranges must already have an attribute with given key and `oldValue` as value
+     *
+     * @param range Range on which the operation should be applied. Must be a flat range.
+     * @param key Key of an attribute to change or remove.
+     * @param oldValue Old value of the attribute with given key or `null`, if attribute was not set before.
+     * @param newValue New value of the attribute with given key or `null`, if operation should remove attribute.
+     * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation
+     * can be applied or `null` if the operation operates on detached (non-document) tree.
+     */
+    constructor(range: Range, key: string, oldValue: unknown, newValue: unknown, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'addAttribute' | 'removeAttribute' | 'changeAttribute';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): AttributeOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `AttributeOperation` object from deserialized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): AttributeOperation;
+}

package/src/model/operation/attributeoperation.js

@@ -0,0 +1,148 @@
+/**
+ * @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/operation/attributeoperation
+ */
+import Operation from './operation.js';
+import { _setAttribute } from './utils.js';
+import Range from '../range.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+import { isEqual } from 'lodash-es';
+/**
+ * Operation to change nodes' attribute.
+ *
+ * Using this class you can add, remove or change value of the attribute.
+ */
+export default class AttributeOperation extends Operation {
+    /**
+     * Creates an operation that changes, removes or adds attributes.
+     *
+     * If only `newValue` is set, attribute will be added on a node. Note that all nodes in operation's range must not
+     * have an attribute with the same key as the added attribute.
+     *
+     * If only `oldValue` is set, then attribute with given key will be removed. Note that all nodes in operation's range
+     * must have an attribute with that key added.
+     *
+     * If both `newValue` and `oldValue` are set, then the operation will change the attribute value. Note that all nodes in
+     * operation's ranges must already have an attribute with given key and `oldValue` as value
+     *
+     * @param range Range on which the operation should be applied. Must be a flat range.
+     * @param key Key of an attribute to change or remove.
+     * @param oldValue Old value of the attribute with given key or `null`, if attribute was not set before.
+     * @param newValue New value of the attribute with given key or `null`, if operation should remove attribute.
+     * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation
+     * can be applied or `null` if the operation operates on detached (non-document) tree.
+     */
+    constructor(range, key, oldValue, newValue, baseVersion) {
+        super(baseVersion);
+        this.range = range.clone();
+        this.key = key;
+        this.oldValue = oldValue === undefined ? null : oldValue;
+        this.newValue = newValue === undefined ? null : newValue;
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        if (this.oldValue === null) {
+            return 'addAttribute';
+        }
+        else if (this.newValue === null) {
+            return 'removeAttribute';
+        }
+        else {
+            return 'changeAttribute';
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        return this.range.clone();
+    }
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone() {
+        return new AttributeOperation(this.range, this.key, this.oldValue, this.newValue, this.baseVersion);
+    }
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed() {
+        return new AttributeOperation(this.range, this.key, this.newValue, this.oldValue, this.baseVersion + 1);
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.range = this.range.toJSON();
+        return json;
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate() {
+        if (!this.range.isFlat) {
+            /**
+             * The range to change is not flat.
+             *
+             * @error attribute-operation-range-not-flat
+             */
+            throw new CKEditorError('attribute-operation-range-not-flat', this);
+        }
+        for (const item of this.range.getItems({ shallow: true })) {
+            if (this.oldValue !== null && !isEqual(item.getAttribute(this.key), this.oldValue)) {
+                /**
+                 * Changed node has different attribute value than operation's old attribute value.
+                 *
+                 * @error attribute-operation-wrong-old-value
+                 * @param item
+                 * @param key
+                 * @param value
+                 */
+                throw new CKEditorError('attribute-operation-wrong-old-value', this, { item, key: this.key, value: this.oldValue });
+            }
+            if (this.oldValue === null && this.newValue !== null && item.hasAttribute(this.key)) {
+                /**
+                 * The attribute with given key already exists for the given node.
+                 *
+                 * @error attribute-operation-attribute-exists
+                 * @param node
+                 * @param key
+                 */
+                throw new CKEditorError('attribute-operation-attribute-exists', this, { node: item, key: this.key });
+            }
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        // If value to set is same as old value, don't do anything.
+        if (!isEqual(this.oldValue, this.newValue)) {
+            // Execution.
+            _setAttribute(this.range, this.key, this.newValue);
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'AttributeOperation';
+    }
+    /**
+     * Creates `AttributeOperation` object from deserialized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json, document) {
+        return new AttributeOperation(Range.fromJSON(json.range, document), json.key, json.oldValue, json.newValue, json.baseVersion);
+    }
+}

package/src/model/operation/detachoperation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @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/operation/detachoperation
+ */
+import Operation from './operation.js';
+import type Position from '../position.js';
+import type { Selectable } from '../selection.js';
+/**
+ * Operation to permanently remove node from detached root.
+ * Note this operation is only a local operation and won't be send to the other clients.
+ */
+export default class DetachOperation extends Operation {
+    /**
+     * Position before the first {@link module:engine/model/item~Item model item} to detach.
+     */
+    sourcePosition: Position;
+    /**
+     * Offset size of moved range.
+     */
+    howMany: number;
+    clone: never;
+    getReversed: never;
+    /**
+     * Creates an insert operation.
+     *
+     * @param sourcePosition Position before the first {@link module:engine/model/item~Item model item} to move.
+     * @param howMany Offset size of moved range. Moved range will start from `sourcePosition` and end at
+     * `sourcePosition` with offset shifted by `howMany`.
+     */
+    constructor(sourcePosition: Position, howMany: number);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'detach';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+}

package/src/model/operation/detachoperation.js

@@ -0,0 +1,77 @@
+/**
+ * @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/operation/detachoperation
+ */
+import Operation from './operation.js';
+import Range from '../range.js';
+import { _remove } from './utils.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+// @if CK_DEBUG_ENGINE // const ModelRange = require( '../range' ).default;
+/**
+ * Operation to permanently remove node from detached root.
+ * Note this operation is only a local operation and won't be send to the other clients.
+ */
+export default class DetachOperation extends Operation {
+    /**
+     * Creates an insert operation.
+     *
+     * @param sourcePosition Position before the first {@link module:engine/model/item~Item model item} to move.
+     * @param howMany Offset size of moved range. Moved range will start from `sourcePosition` and end at
+     * `sourcePosition` with offset shifted by `howMany`.
+     */
+    constructor(sourcePosition, howMany) {
+        super(null);
+        this.sourcePosition = sourcePosition.clone();
+        this.howMany = howMany;
+    }
+    /**
+     * @inheritDoc
+     */
+    get type() {
+        return 'detach';
+    }
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable() {
+        return null;
+    }
+    /**
+     * @inheritDoc
+     */
+    toJSON() {
+        const json = super.toJSON();
+        json.sourcePosition = this.sourcePosition.toJSON();
+        return json;
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate() {
+        if (this.sourcePosition.root.document) {
+            /**
+             * Cannot detach document node.
+             *
+             * @error detach-operation-on-document-node
+             */
+            throw new CKEditorError('detach-operation-on-document-node', this);
+        }
+    }
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute() {
+        _remove(Range._createFromPositionAndShift(this.sourcePosition, this.howMany));
+    }
+    /**
+     * @inheritDoc
+     */
+    static get className() {
+        return 'DetachOperation';
+    }
+}