@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

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

@@ -0,0 +1,98 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import Range from '../range';
+import type Document from '../document';
+/**
+ * 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';
+    /**
+     * 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 deserilized 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/detachoperation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type Position from '../position';
+/**
+ * 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
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import Position from '../position';
+import NodeList from '../nodelist';
+import { type NodeSet } from './utils';
+import type Document from '../document';
+/**
+ * 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;
+    /**
+     * 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 deserilized 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/src/model/operation/markeroperation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import Range from '../range';
+import type Document from '../document';
+import type MarkerCollection from '../markercollection';
+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';
+    /**
+     * 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;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/mergeoperation
+ */
+import Operation from './operation';
+import Position from '../position';
+import Range from '../range';
+import type Document from '../document';
+/**
+ * Operation to merge two {@link module:engine/model/element~Element elements}.
+ *
+ * The merged element is the parent of {@link ~MergeOperation#sourcePosition} and it is merged into the parent of
+ * {@link ~MergeOperation#targetPosition}. All nodes from the merged element are moved to {@link ~MergeOperation#targetPosition}.
+ *
+ * The merged element is moved to the graveyard at {@link ~MergeOperation#graveyardPosition}.
+ */
+export default class MergeOperation extends Operation {
+    /**
+     * Position inside the merged element. All nodes from that element after that position will be moved to {@link #targetPosition}.
+     */
+    sourcePosition: Position;
+    /**
+     * Summary offset size of nodes which will be moved from the merged element to the new parent.
+     */
+    howMany: number;
+    /**
+     * Position which the nodes from the merged elements will be moved to.
+     */
+    targetPosition: Position;
+    /**
+     * Position in graveyard to which the merged element will be moved.
+     */
+    graveyardPosition: Position;
+    /**
+     * Creates a merge operation.
+     *
+     * @param sourcePosition Position inside the merged element. All nodes from that
+     * element after that position will be moved to {@link #targetPosition}.
+     * @param howMany Summary offset size of nodes which will be moved from the merged element to the new parent.
+     * @param targetPosition Position which the nodes from the merged elements will be moved to.
+     * @param graveyardPosition Position in graveyard to which the merged element will be moved.
+     * @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(sourcePosition: Position, howMany: number, targetPosition: Position, graveyardPosition: Position, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'merge';
+    /**
+     * Position before the merged element (which will be deleted).
+     */
+    get deletionPosition(): Position;
+    /**
+     * Artificial range that contains all the nodes from the merged element that will be moved to {@link ~MergeOperation#sourcePosition}.
+     * The range starts at {@link ~MergeOperation#sourcePosition} and ends in the same parent, at `POSITIVE_INFINITY` offset.
+     */
+    get movedRange(): Range;
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MergeOperation;
+    /**
+     * 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 `MergeOperation` object from deserilized 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): MergeOperation;
+}

package/src/model/operation/mergeoperation.js

@@ -24,7 +24,7 @@ export default class MergeOperation extends Operation {
      * Creates a merge operation.
      *
      * @param sourcePosition Position inside the merged element. All nodes from that
-     * element after that position will be moved to {@link ~#targetPosition}.
+     * element after that position will be moved to {@link #targetPosition}.
      * @param howMany Summary offset size of nodes which will be moved from the merged element to the new parent.
      * @param targetPosition Position which the nodes from the merged elements will be moved to.
      * @param graveyardPosition Position in graveyard to which the merged element will be moved.

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

@@ -0,0 +1,91 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/moveoperation
+ */
+import Operation from './operation';
+import Position from '../position';
+import type Document from '../document';
+/**
+ * Operation to move a range of {@link module:engine/model/item~Item model items}
+ * to given {@link module:engine/model/position~Position target position}.
+ */
+export default class MoveOperation extends Operation {
+    /**
+     * Position before the first {@link module:engine/model/item~Item model item} to move.
+     */
+    sourcePosition: Position;
+    /**
+     * Offset size of moved range.
+     */
+    howMany: number;
+    /**
+     * Position at which moved nodes will be inserted.
+     */
+    targetPosition: Position;
+    /**
+     * Creates a move 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`.
+     * @param targetPosition Position at which moved nodes will 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(sourcePosition: Position, howMany: number, targetPosition: Position, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'move' | 'remove' | 'reinsert';
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): MoveOperation;
+    /**
+     * Returns the start position of the moved range after it got moved. This may be different than
+     * {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition} in some cases, i.e. when a range is moved
+     * inside the same parent but {@link module:engine/model/operation/moveoperation~MoveOperation#targetPosition targetPosition}
+     * is after {@link module:engine/model/operation/moveoperation~MoveOperation#sourcePosition sourcePosition}.
+     *
+     * ```
+     *  vv              vv
+     * abcdefg ===> adefbcg
+     *      ^          ^
+     *      targetPos  movedRangeStart
+     *      offset 6   offset 4
+     *```
+     */
+    getMovedRangeStart(): Position;
+    /**
+     * 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 `MoveOperation` object from deserilized 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): MoveOperation;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/nooperation
+ */
+import Operation from './operation';
+/**
+ * Operation which is doing nothing ("empty operation", "do-nothing operation", "noop"). This is an operation,
+ * which when executed does not change the tree model. It still has some parameters defined for transformation purposes.
+ *
+ * In most cases this operation is a result of transforming operations. When transformation returns
+ * {@link module:engine/model/operation/nooperation~NoOperation} it means that changes done by the transformed operation
+ * have already been applied.
+ */
+export default class NoOperation extends Operation {
+    get type(): 'noop';
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): NoOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /** @internal */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type Batch from '../batch';
+import type Document from '../document';
+/**
+ * @module engine/model/operation/operation
+ */
+/**
+ * Abstract base operation class.
+ */
+export default abstract class Operation {
+    /**
+     * {@link module:engine/model/document~Document#version} on which operation can be applied. If you try to
+     * {@link module:engine/model/model~Model#applyOperation apply} operation with different base version than the
+     * {@link module:engine/model/document~Document#version document version} the
+     * {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
+     */
+    baseVersion: number | null;
+    /**
+     * Defines whether operation is executed on attached or detached {@link module:engine/model/item~Item items}.
+     */
+    readonly isDocumentOperation: boolean;
+    /**
+     * {@link module:engine/model/batch~Batch Batch} to which the operation is added or `null` if the operation is not
+     * added to any batch yet.
+     */
+    batch: Batch | null;
+    /**
+     * Operation type.
+     */
+    abstract readonly type: string;
+    /**
+     * Base operation constructor.
+     *
+     * @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(baseVersion: number | null);
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     *
+     * @returns Clone of this operation.
+     */
+    abstract clone(): Operation;
+    /**
+     * Creates and returns a reverse operation. Reverse operation when executed right after
+     * the original operation will bring back tree model state to the point before the original
+     * operation execution. In other words, it reverses changes done by the original operation.
+     *
+     * Keep in mind that tree model state may change since executing the original operation,
+     * so reverse operation will be "outdated". In that case you will need to transform it by
+     * all operations that were executed after the original operation.
+     *
+     * @returns Reversed operation.
+     */
+    abstract getReversed(): Operation;
+    /**
+     * Executes the operation - modifications described by the operation properties will be applied to the model tree.
+     *
+     * @internal
+     */
+    abstract _execute(): void;
+    /**
+     * Checks whether the operation's parameters are correct and the operation can be correctly executed. Throws
+     * an error if operation is not valid.
+     *
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * Custom toJSON method to solve child-parent circular dependencies.
+     *
+     * @returns Clone of this object with the operation property replaced with string.
+     */
+    toJSON(): unknown;
+    /**
+     * Name of the operation class used for serialization.
+     */
+    static get className(): string;
+    /**
+     * Creates Operation object from deserilized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param doc Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): Operation;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import Operation from './operation';
+import type Document from '../document';
+/**
+ * A factory class for creating operations.
+ */
+export default abstract class OperationFactory {
+    /**
+     * Creates an operation instance from a JSON object (parsed JSON string).
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): Operation;
+}