@ckeditor/ckeditor5-engine 41.2.0 → 41.3.0-alpha.0

package/dist/types/model/node.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @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/node
+ */
+import TypeCheckable from './typecheckable.js';
+import type Document from './document.js';
+import type DocumentFragment from './documentfragment.js';
+import type Element from './element.js';
+/**
+ * Model node. Most basic structure of model tree.
+ *
+ * This is an abstract class that is a base for other classes representing different nodes in model.
+ *
+ * **Note:** If a node is detached from the model tree, you can manipulate it using it's API.
+ * However, it is **very important** that nodes already attached to model tree should be only changed through
+ * {@link module:engine/model/writer~Writer Writer API}.
+ *
+ * Changes done by `Node` methods, like {@link module:engine/model/element~Element#_insertChild _insertChild} or
+ * {@link module:engine/model/node~Node#_setAttribute _setAttribute}
+ * do not generate {@link module:engine/model/operation/operation~Operation operations}
+ * which are essential for correct editor work if you modify nodes in {@link module:engine/model/document~Document document} root.
+ *
+ * The flow of working on `Node` (and classes that inherits from it) is as such:
+ * 1. You can create a `Node` instance, modify it using it's API.
+ * 2. Add `Node` to the model using `Batch` API.
+ * 3. Change `Node` that was already added to the model using `Batch` API.
+ *
+ * Similarly, you cannot use `Batch` API on a node that has not been added to the model tree, with the exception
+ * of {@link module:engine/model/writer~Writer#insert inserting} that node to the model tree.
+ *
+ * Be aware that using {@link module:engine/model/writer~Writer#remove remove from Batch API} does not allow to use `Node` API because
+ * the information about `Node` is still kept in model document.
+ *
+ * In case of {@link module:engine/model/element~Element element node}, adding and removing children also counts as changing a node and
+ * follows same rules.
+ */
+export default abstract class Node extends TypeCheckable {
+    /**
+     * Parent of this node. It could be {@link module:engine/model/element~Element}
+     * or {@link module:engine/model/documentfragment~DocumentFragment}.
+     * Equals to `null` if the node has no parent.
+     */
+    readonly parent: Element | DocumentFragment | null;
+    /**
+     * Unique root name used to identify this root element by {@link module:engine/model/document~Document}.
+     */
+    readonly rootName: string | undefined;
+    /**
+     * Attributes set on this node.
+     */
+    private _attrs;
+    /**
+     * Creates a model node.
+     *
+     * This is an abstract class, so this constructor should not be used directly.
+     *
+     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    constructor(attrs?: NodeAttributes);
+    /**
+     * {@link module:engine/model/document~Document Document} that owns this root element.
+     */
+    get document(): Document | null;
+    /**
+     * Index of this node in its parent or `null` if the node has no parent.
+     *
+     * Accessing this property throws an error if this node's parent element does not contain it.
+     * This means that model tree got broken.
+     */
+    get index(): number | null;
+    /**
+     * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
+     * of all its previous siblings. Equals to `null` if node has no parent.
+     *
+     * Accessing this property throws an error if this node's parent element does not contain it.
+     * This means that model tree got broken.
+     */
+    get startOffset(): number | null;
+    /**
+     * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
+     * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
+     * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
+     * than one entity, i.e. {@link module:engine/model/text~Text text node}.
+     */
+    get offsetSize(): number;
+    /**
+     * Offset at which this node ends in it's parent. It is equal to the sum of this node's
+     * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
+     * Equals to `null` if the node has no parent.
+     */
+    get endOffset(): number | null;
+    /**
+     * Node's next sibling or `null` if the node is a last child of it's parent or if the node has no parent.
+     */
+    get nextSibling(): Node | null;
+    /**
+     * Node's previous sibling or `null` if the node is a first child of it's parent or if the node has no parent.
+     */
+    get previousSibling(): Node | null;
+    /**
+     * The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part
+     * of {@link module:engine/model/documentfragment~DocumentFragment}, it's `root` is equal to that `DocumentFragment`.
+     */
+    get root(): Node | DocumentFragment;
+    /**
+     * Returns `true` if the node is inside a document root that is attached to the document.
+     */
+    isAttached(): boolean;
+    /**
+     * Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node,
+     * beginning from {@link module:engine/model/node~Node#root root}, down to this node's starting offset. The path can be used to
+     * create {@link module:engine/model/position~Position Position} instance.
+     *
+     * ```ts
+     * const abc = new Text( 'abc' );
+     * const foo = new Text( 'foo' );
+     * const h1 = new Element( 'h1', null, new Text( 'header' ) );
+     * const p = new Element( 'p', null, [ abc, foo ] );
+     * const div = new Element( 'div', null, [ h1, p ] );
+     * foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
+     * h1.getPath(); // Returns [ 0 ].
+     * div.getPath(); // Returns [].
+     * ```
+     */
+    getPath(): Array<number>;
+    /**
+     * Returns ancestors array of this node.
+     *
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` this node will be also included in parent's array.
+     * @param options.parentFirst When set to `true`, array will be sorted from node's 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<Node | DocumentFragment>;
+    /**
+     * Returns a {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
+     * which is a common ancestor of both nodes.
+     *
+     * @param node The second node.
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` both nodes will be considered "ancestors" too.
+     * Which means that if e.g. node A is inside B, then their common ancestor will be B.
+     */
+    getCommonAncestor(node: Node, options?: {
+        includeSelf?: boolean;
+    }): Element | DocumentFragment | null;
+    /**
+     * Returns whether this node is before given node. `false` is returned if nodes are in different trees (for example,
+     * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
+     *
+     * @param node Node to compare with.
+     */
+    isBefore(node: Node): boolean;
+    /**
+     * Returns whether this node is after given node. `false` is returned if nodes are in different trees (for example,
+     * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
+     *
+     * @param node Node to compare with.
+     */
+    isAfter(node: Node): boolean;
+    /**
+     * Checks if the node has an attribute with given key.
+     *
+     * @param key Key of attribute to check.
+     * @returns `true` if attribute with given key is set on node, `false` otherwise.
+     */
+    hasAttribute(key: string): boolean;
+    /**
+     * Gets an attribute value for given key or `undefined` if that attribute is not set on node.
+     *
+     * @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>;
+    /**
+     * Converts `Node` to plain object and returns it.
+     *
+     * @returns `Node` converted to plain object.
+     */
+    toJSON(): unknown;
+    /**
+     * Creates a copy of this node, that is a node with exactly same attributes, and returns it.
+     *
+     * @internal
+     * @returns Node with same attributes as this node.
+     */
+    _clone(_deep?: boolean): Node;
+    /**
+     * Removes this node from it's parent.
+     *
+     * @internal
+     * @see module:engine/model/writer~Writer#remove
+     */
+    _remove(): void;
+    /**
+     * Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
+     *
+     * @see module:engine/model/writer~Writer#setAttribute
+     * @internal
+     * @param key Key of attribute to set.
+     * @param value Attribute value.
+     */
+    _setAttribute(key: string, value: unknown): void;
+    /**
+     * Removes all attributes from the node and sets given attributes.
+     *
+     * @see module:engine/model/writer~Writer#setAttributes
+     * @internal
+     * @param attrs Attributes to set. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    _setAttributesTo(attrs: NodeAttributes): void;
+    /**
+     * Removes an attribute with given key from the node.
+     *
+     * @see module:engine/model/writer~Writer#removeAttribute
+     * @internal
+     * @param key Key of attribute to remove.
+     * @returns `true` if the attribute was set on the element, `false` otherwise.
+     */
+    _removeAttribute(key: string): boolean;
+    /**
+     * Removes all attributes from the node.
+     *
+     * @see module:engine/model/writer~Writer#clearAttributes
+     * @internal
+     */
+    _clearAttributes(): void;
+}
+/**
+ * The node's parent does not contain this node.
+ *
+ * @error model-node-not-found-in-parent
+ */
+/**
+ * Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+ */
+export type NodeAttributes = Record<string, unknown> | Iterable<[string, unknown]>;

package/dist/types/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/dist/types/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/dist/types/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/dist/types/model/operation/insertoperation.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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/insertoperation
+ */
+import Operation from './operation.js';
+import Position from '../position.js';
+import NodeList from '../nodelist.js';
+import { type NodeSet } from './utils.js';
+import type { Selectable } from '../selection.js';
+import type Document from '../document.js';
+/**
+ * Operation to insert one or more nodes at given position in the model.
+ */
+export default class InsertOperation extends Operation {
+    /**
+     * Position of insertion.
+     *
+     * @readonly
+     */
+    position: Position;
+    /**
+     * List of nodes to insert.
+     *
+     * @readonly
+     */
+    nodes: NodeList;
+    /**
+     * Flag deciding how the operation should be transformed. If set to `true`, nodes might get additional attributes
+     * during operational transformation. This happens when the operation insertion position is inside of a range
+     * where attributes have changed.
+     */
+    shouldReceiveAttributes: boolean;
+    /**
+     * Creates an insert operation.
+     *
+     * @param position Position of insertion.
+     * @param nodes The list of nodes to be inserted.
+     * @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(position: Position, nodes: NodeSet, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'insert';
+    /**
+     * Total offset size of inserted nodes.
+     */
+    get howMany(): number;
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): InsertOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `InsertOperation` 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): InsertOperation;
+}

package/dist/types/model/operation/markeroperation.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/operation/markeroperation
+ */
+import Operation from './operation.js';
+import Range from '../range.js';
+import type Document from '../document.js';
+import type MarkerCollection from '../markercollection.js';
+import type { Selectable } from '../selection.js';
+export default class MarkerOperation extends Operation {
+    /**
+     * Marker name.
+     *
+     * @readonly
+     */
+    name: string;
+    /**
+     * Marker range before the change.
+     *
+     * @readonly
+     */
+    oldRange: Range | null;
+    /**
+     * Marker range after the change.
+     *
+     * @readonly
+     */
+    newRange: Range | null;
+    /**
+     * Specifies whether the marker operation affects the data produced by the data pipeline
+     * (is persisted in the editor's data).
+     *
+     * @readonly
+     */
+    affectsData: boolean;
+    /**
+     * Marker collection on which change should be executed.
+     */
+    private readonly _markers;
+    /**
+     * @param name Marker name.
+     * @param oldRange Marker range before the change.
+     * @param newRange Marker range after the change.
+     * @param markers Marker collection on which change should be executed.
+     * @param affectsData Specifies whether the marker operation affects the data produced by the data pipeline
+     * (is persisted in the editor's data).
+     * @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(name: string, oldRange: Range | null, newRange: Range | null, markers: MarkerCollection, affectsData: boolean, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'marker';
+    /**
+     * @inheritDoc
+     */
+    get affectedSelectable(): Selectable;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MarkerOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `MarkerOperation` 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): MarkerOperation;
+}