@ckeditor/ckeditor5-engine 36.0.0 → 37.0.0-alpha.0

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

@@ -0,0 +1,97 @@
+/**
+ * @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/rootattributeoperation
+ */
+import Operation from './operation';
+import type Document from '../document';
+import type RootElement from '../rootelement';
+/**
+ * Operation to change root element's attribute. Using this class you can add, remove or change value of the attribute.
+ *
+ * This operation is needed, because root elements can't be changed through
+ * {@link module:engine/model/operation/attributeoperation~AttributeOperation}.
+ * It is because {@link module:engine/model/operation/attributeoperation~AttributeOperation}
+ * requires a range to change and root element can't
+ * be a part of range because every {@link module:engine/model/position~Position} has to be inside a root.
+ * {@link module:engine/model/position~Position} can't be created before a root element.
+ */
+export default class RootAttributeOperation extends Operation {
+    /**
+     * Root element to change.
+     *
+     * @readonly
+     */
+    root: RootElement;
+    /**
+     * Key of an attribute to change or remove.
+     *
+     * @readonly
+     */
+    key: string;
+    /**
+     * Old value of the attribute with given key or `null` if adding a new attribute.
+     *
+     * @readonly
+     */
+    oldValue: unknown;
+    /**
+     * New value to set for the attribute. If `null`, then the operation just removes the attribute.
+     *
+     * @readonly
+     */
+    newValue: unknown;
+    /**
+     * Creates an operation that changes, removes or adds attributes on root element.
+     *
+     * @see module:engine/model/operation/attributeoperation~AttributeOperation
+     * @param root Root element to change.
+     * @param key Key of an attribute to change or remove.
+     * @param oldValue Old value of the attribute with given key or `null` if adding a new attribute.
+     * @param newValue New value to set for the attribute. If `null`, then the operation just removes the 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(root: RootElement, key: string, oldValue: unknown, newValue: unknown, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'addRootAttribute' | 'removeRootAttribute' | 'changeRootAttribute';
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     *
+     * @returns Clone of this operation.
+     */
+    clone(): RootAttributeOperation;
+    /**
+     * 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 RootAttributeOperation 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): RootAttributeOperation;
+}

package/src/model/operation/rootattributeoperation.js

@@ -11,7 +11,7 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  * Operation to change root element's attribute. Using this class you can add, remove or change value of the attribute.
  *
  * This operation is needed, because root elements can't be changed through
- * @link module:engine/model/operation/attributeoperation~AttributeOperation}.
+ * {@link module:engine/model/operation/attributeoperation~AttributeOperation}.
  * It is because {@link module:engine/model/operation/attributeoperation~AttributeOperation}
  * requires a range to change and root element can't
  * be a part of range because every {@link module:engine/model/position~Position} has to be inside a root.

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

@@ -0,0 +1,104 @@
+/**
+ * @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/splitoperation
+ */
+import Operation from './operation';
+import Position from '../position';
+import Range from '../range';
+import type Document from '../document';
+/**
+ * Operation to split {@link module:engine/model/element~Element an element} at given
+ * {@link module:engine/model/operation/splitoperation~SplitOperation#splitPosition split position} into two elements,
+ * both containing a part of the element's original content.
+ */
+export default class SplitOperation extends Operation {
+    /**
+     * Position at which an element should be split.
+     */
+    splitPosition: Position;
+    /**
+     * Total offset size of elements that are in the split element after `position`.
+     */
+    howMany: number;
+    /**
+     * Position at which the clone of split element (or element from graveyard) will be inserted.
+     */
+    insertionPosition: Position;
+    /**
+     * Position in the graveyard root before the element which should be used as a parent of the nodes after `position`.
+     * If it is not set, a copy of the the `position` parent will be used.
+     *
+     * The default behavior is to clone the split element. Element from graveyard is used during undo.
+     */
+    graveyardPosition: Position | null;
+    /**
+     * Creates a split operation.
+     *
+     * @param splitPosition Position at which an element should be split.
+     * @param howMany Total offset size of elements that are in the split element after `position`.
+     * @param insertionPosition Position at which the clone of split element (or element from graveyard) will be inserted.
+     * @param graveyardPosition Position in the graveyard root before the element which
+     * should be used as a parent of the nodes after `position`. If it is not set, a copy of the the `position` parent will be used.
+     * @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(splitPosition: Position, howMany: number, insertionPosition: Position, graveyardPosition: Position | null, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'split';
+    /**
+     * Position inside the new clone of a split element.
+     *
+     * This is a position where nodes that are after the split position will be moved to.
+     */
+    get moveTargetPosition(): Position;
+    /**
+     * Artificial range that contains all the nodes from the split element that will be moved to the new element.
+     * The range starts at {@link ~#splitPosition} 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.
+     *
+     * @returns Clone of this operation.
+     */
+    clone(): SplitOperation;
+    /**
+     * 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;
+    /**
+     * Helper function that returns a default insertion position basing on given `splitPosition`. The default insertion
+     * position is after the split element.
+     */
+    static getInsertionPosition(splitPosition: Position): Position;
+    /**
+     * Creates `SplitOperation` 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): SplitOperation;
+}

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

@@ -0,0 +1,100 @@
+/**
+ * @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 Operation from './operation';
+import type Document from '../document';
+/**
+ * Transforms operation `a` by operation `b`.
+ *
+ * @param a Operation to be transformed.
+ * @param b Operation to transform by.
+ * @param context Transformation context for this transformation.
+ * @returns Transformation result.
+ */
+export declare function transform(a: Operation, b: Operation, context?: TransformationContext): Array<Operation>;
+/**
+ * Performs a transformation of two sets of operations - `operationsA` and `operationsB`. The transformation is two-way -
+ * both transformed `operationsA` and transformed `operationsB` are returned.
+ *
+ * Note, that the first operation in each set should base on the same document state (
+ * {@link module:engine/model/document~Document#version document version}).
+ *
+ * It is assumed that `operationsA` are "more important" during conflict resolution between two operations.
+ *
+ * New copies of both passed arrays and operations inside them are returned. Passed arguments are not altered.
+ *
+ * Base versions of the transformed operations sets are updated accordingly. For example, assume that base versions are `4`
+ * and there are `3` operations in `operationsA` and `5` operations in `operationsB`. Then:
+ *
+ * * transformed `operationsA` will start from base version `9` (`4` base version + `5` operations B),
+ * * transformed `operationsB` will start from base version `7` (`4` base version + `3` operations A).
+ *
+ * If no operation was broken into two during transformation, then both sets will end up with an operation that bases on version `11`:
+ *
+ * * transformed `operationsA` start from `9` and there are `3` of them, so the last will have `baseVersion` equal to `11`,
+ * * transformed `operationsB` start from `7` and there are `5` of them, so the last will have `baseVersion` equal to `11`.
+ *
+ * @param operationsA
+ * @param operationsB
+ * @param options Additional transformation options.
+ * @param options.document Document which the operations change.
+ * @param options.useRelations Whether during transformation relations should be used (used during undo for better conflict resolution).
+ * @param options.padWithNoOps Whether additional {@link module:engine/model/operation/nooperation~NoOperation}s
+ * should be added to the transformation results to force the same last base version for both transformed sets (in case
+ * if some operations got broken into multiple operations during transformation).
+ * @param options.forceWeakRemove If set to `false`, remove operation will be always stronger than move operation,
+ * so the removed nodes won't end up back in the document root. When set to `true`, context data will be used.
+ * @returns Transformation result.
+ */
+export declare function transformSets(operationsA: Array<Operation>, operationsB: Array<Operation>, options: {
+    document: Document;
+    useRelations?: boolean;
+    padWithNoOps?: boolean;
+    forceWeakRemove?: boolean;
+}): TransformSetsResult;
+/**
+ * The result of {@link module:engine/model/operation/transform~transformSets}.
+ */
+export interface TransformSetsResult {
+    /**
+     * Transformed `operationsA`.
+     */
+    operationsA: Array<Operation>;
+    /**
+     * Transformed `operationsB`.
+     */
+    operationsB: Array<Operation>;
+    /**
+     * A map that links transformed operations to original operations. The keys are the transformed
+     * operations and the values are the original operations from the input (`operationsA` and `operationsB`).
+     */
+    originalOperations: Map<Operation, Operation>;
+}
+/**
+ * Holds additional contextual information about a transformed pair of operations (`a` and `b`). Those information
+ * can be used for better conflict resolving.
+ */
+export type TransformationContext = {
+    /**
+     * Whether `a` is strong operation in this transformation, or weak.
+     */
+    aIsStrong?: boolean;
+    /**
+     * Whether `a` operation was undone.
+     */
+    aWasUndone?: boolean;
+    /**
+     * Whether `b` operation was undone.
+     */
+    bWasUndone?: boolean;
+    /**
+     * The relation between `a` operation and an operation undone by `b` operation.
+     */
+    abRelation?: any;
+    /**
+     * The relation between `b` operation and an operation undone by `a` operation.
+     */
+    baRelation?: any;
+    forceWeakRemove?: boolean;
+};

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

@@ -0,0 +1,71 @@
+/**
+ * @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/utils
+ */
+import Node from '../node';
+import Range from '../range';
+import type DocumentFragment from '../documentfragment';
+import type Item from '../item';
+import type NodeList from '../nodelist';
+import type Position from '../position';
+/**
+ * Inserts given nodes at given position.
+ *
+ * @internal
+ * @param position Position at which nodes should be inserted.
+ * @param normalizedNodes Nodes to insert.
+ * @returns Range spanning over inserted elements.
+ */
+export declare function _insert(position: Position, nodes: NodeSet): Range;
+/**
+ * Removed nodes in given range. Only {@link module:engine/model/range~Range#isFlat flat} ranges are accepted.
+ *
+ * @internal
+ * @param range Range containing nodes to remove.
+ */
+export declare function _remove(this: any, range: Range): Array<Node>;
+/**
+ * Moves nodes in given range to given target position. Only {@link module:engine/model/range~Range#isFlat flat} ranges are accepted.
+ *
+ * @internal
+ * @param sourceRange Range containing nodes to move.
+ * @param targetPosition Position to which nodes should be moved.
+ * @returns Range containing moved nodes.
+ */
+export declare function _move(this: any, sourceRange: Range, targetPosition: Position): Range;
+/**
+ * Sets given attribute on nodes in given range. The attributes are only set on top-level nodes of the range, not on its children.
+ *
+ * @internal
+ * @param range Range containing nodes that should have the attribute set. Must be a flat range.
+ * @param key Key of attribute to set.
+ * @param value Attribute value.
+ */
+export declare function _setAttribute(range: Range, key: string, value: unknown): void;
+/**
+ * Normalizes given object or an array of objects to an array of {@link module:engine/model/node~Node nodes}. See
+ * {@link module:engine/model/node~NodeSet NodeSet} for details on how normalization is performed.
+ *
+ * @internal
+ * @param nodes Objects to normalize.
+ * @returns Normalized nodes.
+ */
+export declare function _normalizeNodes(nodes: NodeSet): Array<Node>;
+/**
+ * Value that can be normalized to an array of {@link module:engine/model/node~Node nodes}.
+ *
+ * Non-arrays are normalized as follows:
+ * * {@link module:engine/model/node~Node Node} is left as is,
+ * * {@link module:engine/model/textproxy~TextProxy TextProxy} and `string` are normalized to {@link module:engine/model/text~Text Text},
+ * * {@link module:engine/model/nodelist~NodeList NodeList} is normalized to an array containing all nodes that are in that node list,
+ * * {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment} is normalized to an array containing all of it's
+ * * children.
+ *
+ * Arrays are processed item by item like non-array values and flattened to one array. Normalization always results in
+ * a flat array of {@link module:engine/model/node~Node nodes}. Consecutive text nodes (or items normalized to text nodes) will be
+ * merged if they have same attributes.
+ */
+export type NodeSet = Item | string | NodeList | DocumentFragment | Iterable<Item | string | NodeList | DocumentFragment>;