@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/model/history.js

@@ -0,0 +1,207 @@
+/**
+ * @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 { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * @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 {
+    constructor() {
+        /**
+         * Operations added to the history.
+         */
+        this._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".
+         */
+        this._undoPairs = new Map();
+        /**
+         * Holds all undone operations.
+         */
+        this._undoneOperations = new Set();
+        /**
+         * A map that allows retrieving the operations fast based on the given base version.
+         */
+        this._baseVersionToOperationIndex = new Map();
+        /**
+         * The history version.
+         */
+        this._version = 0;
+        /**
+         * 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.
+         */
+        this._gaps = new Map();
+    }
+    /**
+     * 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() {
+        return this._version;
+    }
+    set version(version) {
+        // Store a gap if there are some operations already in the history and the
+        // new version does not increment the latest one.
+        if (this._operations.length && version > this._version + 1) {
+            this._gaps.set(this._version, version);
+        }
+        this._version = version;
+    }
+    /**
+     * The last history operation.
+     */
+    get lastOperation() {
+        return this._operations[this._operations.length - 1];
+    }
+    /**
+     * 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) {
+        if (operation.baseVersion !== this.version) {
+            /**
+             * Only operations with matching versions can be added to the history.
+             *
+             * @error model-document-history-addoperation-incorrect-version
+             * @param errorData The operation and the current document history version.
+             */
+            throw new CKEditorError('model-document-history-addoperation-incorrect-version', this, {
+                operation,
+                historyVersion: this.version
+            });
+        }
+        this._operations.push(operation);
+        this._version++;
+        this._baseVersionToOperationIndex.set(operation.baseVersion, this._operations.length - 1);
+    }
+    /**
+     * 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, toBaseVersion = this.version) {
+        // When there is no operation in the history, return an empty array.
+        // After that we can be sure that `firstOperation`, `lastOperation` are not nullish.
+        if (!this._operations.length) {
+            return [];
+        }
+        const firstOperation = this._operations[0];
+        if (fromBaseVersion === undefined) {
+            fromBaseVersion = firstOperation.baseVersion;
+        }
+        // Change exclusive `toBaseVersion` to inclusive, so it will refer to the actual index.
+        // Thanks to that mapping from base versions to operation indexes are possible.
+        let inclusiveTo = toBaseVersion - 1;
+        // Check if "from" or "to" point to a gap between versions.
+        // If yes, then change the incorrect position to the proper side of the gap.
+        // Thanks to it, it will be possible to get index of the operation.
+        for (const [gapFrom, gapTo] of this._gaps) {
+            if (fromBaseVersion > gapFrom && fromBaseVersion < gapTo) {
+                fromBaseVersion = gapTo;
+            }
+            if (inclusiveTo > gapFrom && inclusiveTo < gapTo) {
+                inclusiveTo = gapFrom - 1;
+            }
+        }
+        // If the whole range is outside of the operation versions, then return an empty array.
+        if (inclusiveTo < firstOperation.baseVersion || fromBaseVersion > this.lastOperation.baseVersion) {
+            return [];
+        }
+        let fromIndex = this._baseVersionToOperationIndex.get(fromBaseVersion);
+        // If the range starts before the first operation, then use the first operation as the range's start.
+        if (fromIndex === undefined) {
+            fromIndex = 0;
+        }
+        let toIndex = this._baseVersionToOperationIndex.get(inclusiveTo);
+        // If the range ends after the last operation, then use the last operation as the range's end.
+        if (toIndex === undefined) {
+            toIndex = this._operations.length - 1;
+        }
+        // Return the part of the history operations based on the calculated start index and end index.
+        return this._operations.slice(fromIndex, 
+        // The `toIndex` should be included in the returned operations, so add `1`.
+        toIndex + 1);
+    }
+    /**
+     * 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) {
+        const operationIndex = this._baseVersionToOperationIndex.get(baseVersion);
+        if (operationIndex === undefined) {
+            return;
+        }
+        return this._operations[operationIndex];
+    }
+    /**
+     * 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, undoingOperation) {
+        this._undoPairs.set(undoingOperation, undoneOperation);
+        this._undoneOperations.add(undoneOperation);
+    }
+    /**
+     * 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) {
+        return this._undoPairs.has(operation);
+    }
+    /**
+     * 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) {
+        return this._undoneOperations.has(operation);
+    }
+    /**
+     * 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) {
+        return this._undoPairs.get(undoingOperation);
+    }
+    /**
+     * Resets the history of operations.
+     */
+    reset() {
+        this._version = 0;
+        this._undoPairs = new Map();
+        this._operations = [];
+        this._undoneOperations = new Set();
+        this._gaps = new Map();
+        this._baseVersionToOperationIndex = new Map();
+    }
+}

package/src/model/item.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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 Node from './node.js';
+import type TextProxy from './textproxy.js';
+/**
+ * @module engine/model/item
+ */
+/**
+ * Item is a {@link module:engine/model/node~Node} or {@link module:engine/model/textproxy~TextProxy}.
+ */
+type Item = Node | TextProxy;
+export default Item;

package/src/model/item.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/model/liveposition.d.ts

@@ -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/liveposition
+ */
+import Position, { type PositionOffset, type PositionStickiness } from './position.js';
+import type DocumentFragment from './documentfragment.js';
+import type Item from './item.js';
+import type RootElement from './rootelement.js';
+declare const LivePosition_base: import("@ckeditor/ckeditor5-utils").Mixed<typeof Position, import("@ckeditor/ckeditor5-utils").Emitter>;
+/**
+ * `LivePosition` is a type of {@link module:engine/model/position~Position Position}
+ * that updates itself as {@link module:engine/model/document~Document document}
+ * is changed through operations. It may be used as a bookmark.
+ *
+ * **Note:** Contrary to {@link module:engine/model/position~Position}, `LivePosition` works only in roots that are
+ * {@link module:engine/model/rootelement~RootElement}.
+ * If {@link module:engine/model/documentfragment~DocumentFragment} is passed, error will be thrown.
+ *
+ * **Note:** Be very careful when dealing with `LivePosition`. Each `LivePosition` instance bind events that might
+ * have to be unbound.
+ * Use {@link module:engine/model/liveposition~LivePosition#detach} whenever you don't need `LivePosition` anymore.
+ */
+export default class LivePosition extends /* #__PURE__ */ LivePosition_base {
+    /**
+     * Root of the position path.
+     */
+    readonly root: RootElement;
+    /**
+     * Creates a live position.
+     *
+     * @see module:engine/model/position~Position
+     */
+    constructor(root: RootElement, path: Array<number>, stickiness?: PositionStickiness);
+    /**
+     * Unbinds all events previously bound by `LivePosition`. Use it whenever you don't need `LivePosition` instance
+     * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
+     * referring to it).
+     */
+    detach(): void;
+    /**
+     * Creates a {@link module:engine/model/position~Position position instance}, which is equal to this live position.
+     */
+    toPosition(): Position;
+    /**
+     * Creates a `LivePosition` instance that is equal to position.
+     */
+    static fromPosition(position: Position, stickiness?: PositionStickiness): LivePosition;
+    /**
+     * @internal
+     * @see module:engine/model/position~Position._createAfter
+     */
+    static readonly _createAfter: (item: Item | DocumentFragment, stickiness?: PositionStickiness) => LivePosition;
+    /**
+     * @internal
+     * @see module:engine/model/position~Position._createBefore
+     */
+    static readonly _createBefore: (item: Item | DocumentFragment, stickiness?: PositionStickiness) => LivePosition;
+    /**
+     * @internal
+     * @see module:engine/model/position~Position._createAt
+     */
+    static readonly _createAt: (itemOrPosition: Item | Position | DocumentFragment, offset?: PositionOffset, stickiness?: PositionStickiness) => LivePosition;
+}
+/**
+ * Fired when `LivePosition` instance is changed due to changes on {@link module:engine/model/document~Document}.
+ *
+ * @eventName ~LivePosition#change
+ * @param oldPosition Position equal to this live position before it got changed.
+ */
+export type LivePositionChangeEvent = {
+    name: 'change';
+    args: [oldPosition: Position];
+};
+export {};

package/src/model/liveposition.js

@@ -0,0 +1,93 @@
+/**
+ * @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/liveposition
+ */
+import Position from './position.js';
+import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * `LivePosition` is a type of {@link module:engine/model/position~Position Position}
+ * that updates itself as {@link module:engine/model/document~Document document}
+ * is changed through operations. It may be used as a bookmark.
+ *
+ * **Note:** Contrary to {@link module:engine/model/position~Position}, `LivePosition` works only in roots that are
+ * {@link module:engine/model/rootelement~RootElement}.
+ * If {@link module:engine/model/documentfragment~DocumentFragment} is passed, error will be thrown.
+ *
+ * **Note:** Be very careful when dealing with `LivePosition`. Each `LivePosition` instance bind events that might
+ * have to be unbound.
+ * Use {@link module:engine/model/liveposition~LivePosition#detach} whenever you don't need `LivePosition` anymore.
+ */
+export default class LivePosition extends /* #__PURE__ */ EmitterMixin(Position) {
+    /**
+     * Creates a live position.
+     *
+     * @see module:engine/model/position~Position
+     */
+    constructor(root, path, stickiness = 'toNone') {
+        super(root, path, stickiness);
+        if (!this.root.is('rootElement')) {
+            /**
+             * LivePosition's root has to be an instance of RootElement.
+             *
+             * @error model-liveposition-root-not-rootelement
+             */
+            throw new CKEditorError('model-liveposition-root-not-rootelement', root);
+        }
+        bindWithDocument.call(this);
+    }
+    /**
+     * Unbinds all events previously bound by `LivePosition`. Use it whenever you don't need `LivePosition` instance
+     * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
+     * referring to it).
+     */
+    detach() {
+        this.stopListening();
+    }
+    /**
+     * Creates a {@link module:engine/model/position~Position position instance}, which is equal to this live position.
+     */
+    toPosition() {
+        return new Position(this.root, this.path.slice(), this.stickiness);
+    }
+    /**
+     * Creates a `LivePosition` instance that is equal to position.
+     */
+    static fromPosition(position, stickiness) {
+        return new this(position.root, position.path.slice(), stickiness ? stickiness : position.stickiness);
+    }
+}
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
+LivePosition.prototype.is = function (type) {
+    return type === 'livePosition' || type === 'model:livePosition' ||
+        // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        type == 'position' || type === 'model:position';
+};
+/**
+ * Binds this `LivePosition` to the {@link module:engine/model/document~Document document} that owns
+ * this position's {@link module:engine/model/position~Position#root root}.
+ */
+function bindWithDocument() {
+    this.listenTo(this.root.document.model, 'applyOperation', (event, args) => {
+        const operation = args[0];
+        if (!operation.isDocumentOperation) {
+            return;
+        }
+        transform.call(this, operation);
+    }, { priority: 'low' });
+}
+/**
+ * Updates this position accordingly to the updates applied to the model. Bases on change events.
+ */
+function transform(operation) {
+    const result = this.getTransformedByOperation(operation);
+    if (!this.isEqual(result)) {
+        const oldPosition = this.toPosition();
+        this.path = result.path;
+        this.root = result.root;
+        this.fire('change', oldPosition);
+    }
+}

package/src/model/liverange.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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/liverange
+ */
+import Range from './range.js';
+import type DocumentFragment from './documentfragment.js';
+import type Element from './element.js';
+import type Item from './item.js';
+import type Position from './position.js';
+declare const LiveRange_base: import("@ckeditor/ckeditor5-utils").Mixed<typeof Range, import("@ckeditor/ckeditor5-utils").Emitter>;
+/**
+ * `LiveRange` is a type of {@link module:engine/model/range~Range Range}
+ * that updates itself as {@link module:engine/model/document~Document document}
+ * is changed through operations. It may be used as a bookmark.
+ *
+ * **Note:** Be very careful when dealing with `LiveRange`. Each `LiveRange` instance bind events that might
+ * have to be unbound. Use {@link module:engine/model/liverange~LiveRange#detach detach} whenever you don't need `LiveRange` anymore.
+ */
+export default class LiveRange extends /* #__PURE__ */ LiveRange_base {
+    /**
+     * Creates a live range.
+     *
+     * @see module:engine/model/range~Range
+     */
+    constructor(start: Position, end?: Position | null);
+    /**
+     * Unbinds all events previously bound by `LiveRange`. Use it whenever you don't need `LiveRange` instance
+     * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
+     * referring to it).
+     */
+    detach(): void;
+    /**
+     * Creates a {@link module:engine/model/range~Range range instance} that is equal to this live range.
+     */
+    toRange(): Range;
+    /**
+     * Creates a `LiveRange` instance that is equal to the given range.
+     */
+    static fromRange(range: Range): LiveRange;
+    /**
+     * @see module:engine/model/range~Range._createIn
+     * @internal
+     */
+    static readonly _createIn: (element: Element | DocumentFragment) => LiveRange;
+    /**
+     * @see module:engine/model/range~Range._createOn
+     * @internal
+     */
+    static readonly _createOn: (element: Item | DocumentFragment) => LiveRange;
+    /**
+     * @see module:engine/model/range~Range._createFromPositionAndShift
+     * @internal
+     */
+    static readonly _createFromPositionAndShift: (position: Position, shift: number) => LiveRange;
+}
+/**
+ * Fired when `LiveRange` instance boundaries have changed due to changes in the
+ * {@link module:engine/model/document~Document document}.
+ *
+ * @eventName ~LiveRange#change:range
+ * @param oldRange Range with start and end position equal to start and end position of this live
+ * range before it got changed.
+ * @param data Object with additional information about the change.
+ * @param data.deletionPosition Source position for remove and merge changes.
+ * Available if the range was moved to the graveyard root, `null` otherwise.
+ */
+export type LiveRangeChangeRangeEvent = {
+    name: 'change' | 'change:range';
+    args: [range: Range, data: {
+        deletionPosition: Position | null;
+    }];
+};
+/**
+ * Fired when `LiveRange` instance boundaries have not changed after a change in {@link module:engine/model/document~Document document}
+ * but the change took place inside the range, effectively changing its content.
+ *
+ * @eventName ~LiveRange#change:content
+ * @param range Range with start and end position equal to start and end position of
+ * change range.
+ * @param data Object with additional information about the change.
+ * @param data.deletionPosition Due to the nature of this event, this property is always set to `null`. It is passed
+ * for compatibility with the {@link module:engine/model/liverange~LiveRange#event:change:range} event.
+ */
+export type LiveRangeChangeContentEvent = {
+    name: 'change' | 'change:content';
+    args: [range: Range, data: {
+        deletionPosition: null;
+    }];
+};
+/**
+ * Describes `change:range` or `change:content` event.
+ */
+export type LiveRangeChangeEvent = {
+    name: 'change' | 'change:range' | 'change:content';
+    args: [range: Range, data: {
+        deletionPosition: Position | null;
+    }];
+};
+export {};

package/src/model/liverange.js

@@ -0,0 +1,120 @@
+/**
+ * @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/liverange
+ */
+import Range from './range.js';
+import { EmitterMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * `LiveRange` is a type of {@link module:engine/model/range~Range Range}
+ * that updates itself as {@link module:engine/model/document~Document document}
+ * is changed through operations. It may be used as a bookmark.
+ *
+ * **Note:** Be very careful when dealing with `LiveRange`. Each `LiveRange` instance bind events that might
+ * have to be unbound. Use {@link module:engine/model/liverange~LiveRange#detach detach} whenever you don't need `LiveRange` anymore.
+ */
+export default class LiveRange extends /* #__PURE__ */ EmitterMixin(Range) {
+    /**
+     * Creates a live range.
+     *
+     * @see module:engine/model/range~Range
+     */
+    constructor(start, end) {
+        super(start, end);
+        bindWithDocument.call(this);
+    }
+    /**
+     * Unbinds all events previously bound by `LiveRange`. Use it whenever you don't need `LiveRange` instance
+     * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
+     * referring to it).
+     */
+    detach() {
+        this.stopListening();
+    }
+    /**
+     * Creates a {@link module:engine/model/range~Range range instance} that is equal to this live range.
+     */
+    toRange() {
+        return new Range(this.start, this.end);
+    }
+    /**
+     * Creates a `LiveRange` instance that is equal to the given range.
+     */
+    static fromRange(range) {
+        return new LiveRange(range.start, range.end);
+    }
+}
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
+LiveRange.prototype.is = function (type) {
+    return type === 'liveRange' || type === 'model:liveRange' ||
+        // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        type == 'range' || type === 'model:range';
+};
+/**
+ * Binds this `LiveRange` to the {@link module:engine/model/document~Document document}
+ * that owns this range's {@link module:engine/model/range~Range#root root}.
+ */
+function bindWithDocument() {
+    this.listenTo(this.root.document.model, 'applyOperation', (event, args) => {
+        const operation = args[0];
+        if (!operation.isDocumentOperation) {
+            return;
+        }
+        transform.call(this, operation);
+    }, { priority: 'low' });
+}
+/**
+ * Updates this range accordingly to the updates applied to the model. Bases on change events.
+ */
+function transform(operation) {
+    // Transform the range by the operation. Join the result ranges if needed.
+    const ranges = this.getTransformedByOperation(operation);
+    const result = Range._createFromRanges(ranges);
+    const boundariesChanged = !result.isEqual(this);
+    const contentChanged = doesOperationChangeRangeContent(this, operation);
+    let deletionPosition = null;
+    if (boundariesChanged) {
+        // If range boundaries have changed, fire `change:range` event.
+        //
+        if (result.root.rootName == '$graveyard') {
+            // If the range was moved to the graveyard root, set `deletionPosition`.
+            if (operation.type == 'remove') {
+                deletionPosition = operation.sourcePosition;
+            }
+            else {
+                // Merge operation.
+                deletionPosition = operation.deletionPosition;
+            }
+        }
+        const oldRange = this.toRange();
+        this.start = result.start;
+        this.end = result.end;
+        this.fire('change:range', oldRange, { deletionPosition });
+    }
+    else if (contentChanged) {
+        // If range boundaries have not changed, but there was change inside the range, fire `change:content` event.
+        this.fire('change:content', this.toRange(), { deletionPosition });
+    }
+}
+/**
+ * Checks whether given operation changes something inside the range (even if it does not change boundaries).
+ */
+function doesOperationChangeRangeContent(range, operation) {
+    switch (operation.type) {
+        case 'insert':
+            return range.containsPosition(operation.position);
+        case 'move':
+        case 'remove':
+        case 'reinsert':
+        case 'merge':
+            return range.containsPosition(operation.sourcePosition) ||
+                range.start.isEqual(operation.sourcePosition) ||
+                range.containsPosition(operation.targetPosition);
+        case 'split':
+            return range.containsPosition(operation.splitPosition) || range.containsPosition(operation.insertionPosition);
+    }
+    return false;
+}