@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/model/treewalker.js

@@ -0,0 +1,244 @@
+/**
+ * @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/treewalker
+ */
+import Element from './element.js';
+import { default as Position, getTextNodeAtPosition, getNodeAfterPosition, getNodeBeforePosition } from './position.js';
+import Text from './text.js';
+import TextProxy from './textproxy.js';
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * Position iterator class. It allows to iterate forward and backward over the document.
+ */
+export default class TreeWalker {
+    /**
+     * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
+     *
+     * @param options Object with configuration.
+     */
+    constructor(options) {
+        if (!options || (!options.boundaries && !options.startPosition)) {
+            /**
+             * Neither boundaries nor starting position of a `TreeWalker` have been defined.
+             *
+             * @error model-tree-walker-no-start-position
+             */
+            throw new CKEditorError('model-tree-walker-no-start-position', null);
+        }
+        const direction = options.direction || 'forward';
+        if (direction != 'forward' && direction != 'backward') {
+            /**
+             * Only `backward` and `forward` direction allowed.
+             *
+             * @error model-tree-walker-unknown-direction
+             */
+            throw new CKEditorError('model-tree-walker-unknown-direction', options, { direction });
+        }
+        this.direction = direction;
+        this.boundaries = options.boundaries || null;
+        if (options.startPosition) {
+            this._position = options.startPosition.clone();
+        }
+        else {
+            this._position = Position._createAt(this.boundaries[this.direction == 'backward' ? 'end' : 'start']);
+        }
+        // Reset position stickiness in case it was set to other value, as the stickiness is kept after cloning.
+        this.position.stickiness = 'toNone';
+        this.singleCharacters = !!options.singleCharacters;
+        this.shallow = !!options.shallow;
+        this.ignoreElementEnd = !!options.ignoreElementEnd;
+        this._boundaryStartParent = this.boundaries ? this.boundaries.start.parent : null;
+        this._boundaryEndParent = this.boundaries ? this.boundaries.end.parent : null;
+        this._visitedParent = this.position.parent;
+    }
+    /**
+     * Iterable interface.
+     *
+     * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
+     */
+    [Symbol.iterator]() {
+        return this;
+    }
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    get position() {
+        return this._position;
+    }
+    /**
+     * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
+     *
+     * For example:
+     *
+     * ```ts
+     * walker.skip( value => value.type == 'text' ); // <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>
+     * walker.skip( () => true ); // Move the position to the end: <paragraph>[]foo</paragraph> -> <paragraph>foo</paragraph>[]
+     * walker.skip( () => false ); // Do not move the position.
+     * ```
+     *
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * return `true` if the value should be skipped or `false` if not.
+     */
+    skip(skip) {
+        let done, value, prevPosition, prevVisitedParent;
+        do {
+            prevPosition = this.position;
+            prevVisitedParent = this._visitedParent;
+            ({ done, value } = this.next());
+        } while (!done && skip(value));
+        if (!done) {
+            this._position = prevPosition;
+            this._visitedParent = prevVisitedParent;
+        }
+    }
+    /**
+     * Gets the next tree walker's value.
+     */
+    next() {
+        if (this.direction == 'forward') {
+            return this._next();
+        }
+        else {
+            return this._previous();
+        }
+    }
+    /**
+     * Makes a step forward in model. Moves the {@link #position} to the next position and returns the encountered value.
+     */
+    _next() {
+        const previousPosition = this.position;
+        const position = this.position.clone();
+        const parent = this._visitedParent;
+        // We are at the end of the root.
+        if (parent.parent === null && position.offset === parent.maxOffset) {
+            return { done: true, value: undefined };
+        }
+        // We reached the walker boundary.
+        if (parent === this._boundaryEndParent && position.offset == this.boundaries.end.offset) {
+            return { done: true, value: undefined };
+        }
+        // Get node just after the current position.
+        // Use a highly optimized version instead of checking the text node first and then getting the node after. See #6582.
+        const textNodeAtPosition = getTextNodeAtPosition(position, parent);
+        const node = textNodeAtPosition || getNodeAfterPosition(position, parent, textNodeAtPosition);
+        if (node instanceof Element) {
+            if (!this.shallow) {
+                // Manual operations on path internals for optimization purposes. Here and in the rest of the method.
+                position.path.push(0);
+                this._visitedParent = node;
+            }
+            else {
+                // We are past the walker boundaries.
+                if (this.boundaries && this.boundaries.end.isBefore(position)) {
+                    return { done: true, value: undefined };
+                }
+                position.offset++;
+            }
+            this._position = position;
+            return formatReturnValue('elementStart', node, previousPosition, position, 1);
+        }
+        if (node instanceof Text) {
+            let charactersCount;
+            if (this.singleCharacters) {
+                charactersCount = 1;
+            }
+            else {
+                let offset = node.endOffset;
+                if (this._boundaryEndParent == parent && this.boundaries.end.offset < offset) {
+                    offset = this.boundaries.end.offset;
+                }
+                charactersCount = offset - position.offset;
+            }
+            const offsetInTextNode = position.offset - node.startOffset;
+            const item = new TextProxy(node, offsetInTextNode, charactersCount);
+            position.offset += charactersCount;
+            this._position = position;
+            return formatReturnValue('text', item, previousPosition, position, charactersCount);
+        }
+        // `node` is not set, we reached the end of current `parent`.
+        position.path.pop();
+        position.offset++;
+        this._position = position;
+        this._visitedParent = parent.parent;
+        if (this.ignoreElementEnd) {
+            return this._next();
+        }
+        return formatReturnValue('elementEnd', parent, previousPosition, position);
+    }
+    /**
+     * Makes a step backward in model. Moves the {@link #position} to the previous position and returns the encountered value.
+     */
+    _previous() {
+        const previousPosition = this.position;
+        const position = this.position.clone();
+        const parent = this._visitedParent;
+        // We are at the beginning of the root.
+        if (parent.parent === null && position.offset === 0) {
+            return { done: true, value: undefined };
+        }
+        // We reached the walker boundary.
+        if (parent == this._boundaryStartParent && position.offset == this.boundaries.start.offset) {
+            return { done: true, value: undefined };
+        }
+        // Get node just before the current position.
+        // Use a highly optimized version instead of checking the text node first and then getting the node before. See #6582.
+        const positionParent = position.parent;
+        const textNodeAtPosition = getTextNodeAtPosition(position, positionParent);
+        const node = textNodeAtPosition || getNodeBeforePosition(position, positionParent, textNodeAtPosition);
+        if (node instanceof Element) {
+            position.offset--;
+            if (this.shallow) {
+                this._position = position;
+                return formatReturnValue('elementStart', node, previousPosition, position, 1);
+            }
+            position.path.push(node.maxOffset);
+            this._position = position;
+            this._visitedParent = node;
+            if (this.ignoreElementEnd) {
+                return this._previous();
+            }
+            return formatReturnValue('elementEnd', node, previousPosition, position);
+        }
+        if (node instanceof Text) {
+            let charactersCount;
+            if (this.singleCharacters) {
+                charactersCount = 1;
+            }
+            else {
+                let offset = node.startOffset;
+                if (this._boundaryStartParent == parent && this.boundaries.start.offset > offset) {
+                    offset = this.boundaries.start.offset;
+                }
+                charactersCount = position.offset - offset;
+            }
+            const offsetInTextNode = position.offset - node.startOffset;
+            const item = new TextProxy(node, offsetInTextNode - charactersCount, charactersCount);
+            position.offset -= charactersCount;
+            this._position = position;
+            return formatReturnValue('text', item, previousPosition, position, charactersCount);
+        }
+        // `node` is not set, we reached the beginning of current `parent`.
+        position.path.pop();
+        this._position = position;
+        this._visitedParent = parent.parent;
+        return formatReturnValue('elementStart', parent, previousPosition, position, 1);
+    }
+}
+function formatReturnValue(type, item, previousPosition, nextPosition, length) {
+    return {
+        done: false,
+        value: {
+            type,
+            item,
+            previousPosition,
+            nextPosition,
+            length
+        }
+    };
+}

package/src/model/typecheckable.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @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/typecheckable
+ */
+import type { Marker } from './markercollection.js';
+import type DocumentFragment from './documentfragment.js';
+import type DocumentSelection from './documentselection.js';
+import type Element from './element.js';
+import type LivePosition from './liveposition.js';
+import type LiveRange from './liverange.js';
+import type Node from './node.js';
+import type Position from './position.js';
+import type Range from './range.js';
+import type RootElement from './rootelement.js';
+import type Selection from './selection.js';
+import type Text from './text.js';
+import type TextProxy from './textproxy.js';
+export default abstract class TypeCheckable {
+    /**
+     * Checks whether the object is of type {@link module:engine/model/node~Node} or its subclass.
+     *
+     * This method is useful when processing model objects that are of unknown type. For example, a function
+     * may return a {@link module:engine/model/documentfragment~DocumentFragment} or a {@link module:engine/model/node~Node}
+     * that can be either a text node or an element. This method can be used to check what kind of object is returned.
+     *
+     * ```ts
+     * someObject.is( 'element' ); // -> true if this is an element
+     * someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
+     * someObject.is( 'documentFragment' ); // -> true if this is a document fragment
+     * ```
+     *
+     * Since this method is also available on a range of view objects, you can prefix the type of the object with
+     * `model:` or `view:` to check, for example, if this is the model's or view's element:
+     *
+     * ```ts
+     * modelElement.is( 'model:element' ); // -> true
+     * modelElement.is( 'view:element' ); // -> false
+     * ```
+     *
+     * By using this method it is also possible to check a name of an element:
+     *
+     * ```ts
+     * imageElement.is( 'element', 'imageBlock' ); // -> true
+     * imageElement.is( 'element', 'imageBlock' ); // -> same as above
+     * imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
+     * ```
+     *
+     * @label NODE
+     */
+    is(type: 'node' | 'model:node'): this is Node | Element | Text | RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/element~Element} or its subclass.
+     *
+     * ```ts
+     * element.is( 'element' ); // -> true
+     * element.is( 'node' ); // -> true
+     * element.is( 'model:element' ); // -> true
+     * element.is( 'model:node' ); // -> true
+     *
+     * element.is( 'view:element' ); // -> false
+     * element.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * Assuming that the object being checked is an element, you can also check its
+     * {@link module:engine/model/element~Element#name name}:
+     *
+     * ```ts
+     * element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
+     * text.is( 'element', 'imageBlock' ); -> false
+     * ```
+     *
+     * @label ELEMENT
+     */
+    is(type: 'element' | 'model:element'): this is Element | RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/rootelement~RootElement}.
+     *
+     * ```ts
+     * rootElement.is( 'rootElement' ); // -> true
+     * rootElement.is( 'element' ); // -> true
+     * rootElement.is( 'node' ); // -> true
+     * rootElement.is( 'model:rootElement' ); // -> true
+     * rootElement.is( 'model:element' ); // -> true
+     * rootElement.is( 'model:node' ); // -> true
+     *
+     * rootElement.is( 'view:element' ); // -> false
+     * rootElement.is( 'documentFragment' ); // -> false
+     * ```
+     *
+     * Assuming that the object being checked is an element, you can also check its
+     * {@link module:engine/model/element~Element#name name}:
+     *
+     * ```ts
+     * rootElement.is( 'rootElement', '$root' ); // -> same as above
+     * ```
+     *
+     * @label ROOT_ELEMENT
+     */
+    is(type: 'rootElement' | 'model:rootElement'): this is RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/text~Text}.
+     *
+     * ```ts
+     * text.is( '$text' ); // -> true
+     * text.is( 'node' ); // -> true
+     * text.is( 'model:$text' ); // -> true
+     * text.is( 'model:node' ); // -> true
+     *
+     * text.is( 'view:$text' ); // -> false
+     * text.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * **Note:** Until version 20.0.0 this method wasn't accepting `'$text'` type. The legacy `'text'` type is still
+     * accepted for backward compatibility.
+     *
+     * @label TEXT
+     */
+    is(type: '$text' | 'model:$text'): this is Text;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/position~Position} or its subclass.
+     *
+     * ```ts
+     * position.is( 'position' ); // -> true
+     * position.is( 'model:position' ); // -> true
+     *
+     * position.is( 'view:position' ); // -> false
+     * position.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label POSITION
+     */
+    is(type: 'position' | 'model:position'): this is Position | LivePosition;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/liveposition~LivePosition}.
+     *
+     * ```ts
+     * livePosition.is( 'position' ); // -> true
+     * livePosition.is( 'model:position' ); // -> true
+     * livePosition.is( 'liveposition' ); // -> true
+     * livePosition.is( 'model:livePosition' ); // -> true
+     *
+     * livePosition.is( 'view:position' ); // -> false
+     * livePosition.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label LIVE_POSITION
+     */
+    is(type: 'livePosition' | 'model:livePosition'): this is LivePosition;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/range~Range} or its subclass.
+     *
+     * ```ts
+     * range.is( 'range' ); // -> true
+     * range.is( 'model:range' ); // -> true
+     *
+     * range.is( 'view:range' ); // -> false
+     * range.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label RANGE
+     */
+    is(type: 'range' | 'model:range'): this is Range | LiveRange;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/liverange~LiveRange}.
+     *
+     * ```ts
+     * liveRange.is( 'range' ); // -> true
+     * liveRange.is( 'model:range' ); // -> true
+     * liveRange.is( 'liveRange' ); // -> true
+     * liveRange.is( 'model:liveRange' ); // -> true
+     *
+     * liveRange.is( 'view:range' ); // -> false
+     * liveRange.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label LIVE_RANGE
+     */
+    is(type: 'liveRange' | 'model:liveRange'): this is LiveRange;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/documentfragment~DocumentFragment}.
+     *
+     * ```ts
+     * docFrag.is( 'documentFragment' ); // -> true
+     * docFrag.is( 'model:documentFragment' ); // -> true
+     *
+     * docFrag.is( 'view:documentFragment' ); // -> false
+     * docFrag.is( 'element' ); // -> false
+     * docFrag.is( 'node' ); // -> false
+     * ```
+     *
+     * @label DOCUMENT_FRAGMENT
+     */
+    is(type: 'documentFragment' | 'model:documentFragment'): this is DocumentFragment;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/selection~Selection}
+     * or {@link module:engine/model/documentselection~DocumentSelection}.
+     *
+     * ```ts
+     * selection.is( 'selection' ); // -> true
+     * selection.is( 'model:selection' ); // -> true
+     *
+     * selection.is( 'view:selection' ); // -> false
+     * selection.is( 'range' ); // -> false
+     * ```
+     *
+     * @label SELECTION
+     */
+    is(type: 'selection' | 'model:selection'): this is Selection | DocumentSelection;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/documentselection~DocumentSelection}.
+     *
+     * ```ts
+     * selection.is( 'selection' ); // -> true
+     * selection.is( 'documentSelection' ); // -> true
+     * selection.is( 'model:selection' ); // -> true
+     * selection.is( 'model:documentSelection' ); // -> true
+     *
+     * selection.is( 'view:selection' ); // -> false
+     * selection.is( 'element' ); // -> false
+     * selection.is( 'node' ); // -> false
+     * ```
+     *
+     * @label DOCUMENT_SELECTION
+     */
+    is(type: 'documentSelection' | 'model:documentSelection'): this is DocumentSelection;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/markercollection~Marker}.
+     *
+     * ```ts
+     * marker.is( 'marker' ); // -> true
+     * marker.is( 'model:marker' ); // -> true
+     *
+     * marker.is( 'view:element' ); // -> false
+     * marker.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label MARKER
+     */
+    is(type: 'marker' | 'model:marker'): this is Marker;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/textproxy~TextProxy}.
+     *
+     * ```ts
+     * textProxy.is( '$textProxy' ); // -> true
+     * textProxy.is( 'model:$textProxy' ); // -> true
+     *
+     * textProxy.is( 'view:$textProxy' ); // -> false
+     * textProxy.is( 'range' ); // -> false
+     * ```
+     *
+     * **Note:** Until version 20.0.0 this method wasn't accepting `'$textProxy'` type. The legacy `'textProxt'` type is still
+     * accepted for backward compatibility.
+     *
+     * @label TEXT_PROXY
+     */
+    is(type: '$textProxy' | 'model:$textProxy'): this is TextProxy;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/element~Element} or its subclass and has the specified `name`.
+     *
+     * ```ts
+     * element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
+     * text.is( 'element', 'imageBlock' ); -> false
+     * ```
+     *
+     * @label ELEMENT_NAME
+     */
+    is<N extends string>(type: 'element' | 'model:element', name: N): this is (Element | RootElement) & {
+        name: N;
+    };
+    /**
+     * Checks whether the object is of type {@link module:engine/model/rootelement~RootElement} and has the specified `name`.
+     *
+     * ```ts
+     * rootElement.is( 'rootElement', '$root' );
+     * ```
+     *
+     * @label ROOT_ELEMENT_NAME
+     */
+    is<N extends string>(type: 'rootElement' | 'model:rootElement', name: N): this is RootElement & {
+        name: N;
+    };
+}

package/src/model/typecheckable.js

@@ -0,0 +1,16 @@
+/**
+ * @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 default class TypeCheckable {
+    /* istanbul ignore next -- @preserve */
+    is() {
+        // There are a lot of overloads above.
+        // Overriding method in derived classes remove them and only `is( type: string ): boolean` is visible which we don't want.
+        // One option would be to copy them all to all classes, but that's ugly.
+        // It's best when TypeScript compiler doesn't see those overloads, except the one in the top base class.
+        // To overload a method, but not let the compiler see it, do after class definition:
+        // `MyClass.prototype.is = function( type: string ) {...}`
+        throw new Error('is() method is abstract');
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * @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 Position from '../position.js';
+import type Schema from '../schema.js';
+import type Writer from '../writer.js';
+/**
+ * @module engine/model/utils/autoparagraphing
+ */
+/**
+ * Fixes all empty roots.
+ *
+ * @internal
+ * @param writer The model writer.
+ * @returns `true` if any change has been applied, `false` otherwise.
+ */
+export declare function autoParagraphEmptyRoots(writer: Writer): boolean;
+/**
+ * Checks if the given node wrapped with a paragraph would be accepted by the schema in the given position.
+ *
+ * @internal
+ * @param position The position at which to check.
+ * @param nodeOrType The child node or child type to check.
+ * @param schema A schema instance used for element validation.
+ */
+export declare function isParagraphable(position: Position, nodeOrType: Node | string, schema: Schema): boolean;
+/**
+ * Inserts a new paragraph at the given position and returns a position inside that paragraph.
+ *
+ * @internal
+ * @param position The position where a paragraph should be inserted.
+ * @param writer The model writer.
+ * @returns  Position inside the created paragraph.
+ */
+export declare function wrapInParagraph(position: Position, writer: Writer): Position;

package/src/model/utils/autoparagraphing.js

@@ -0,0 +1,63 @@
+/**
+ * @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/utils/autoparagraphing
+ */
+/**
+ * Fixes all empty roots.
+ *
+ * @internal
+ * @param writer The model writer.
+ * @returns `true` if any change has been applied, `false` otherwise.
+ */
+export function autoParagraphEmptyRoots(writer) {
+    const { schema, document } = writer.model;
+    for (const root of document.getRoots()) {
+        if (root.isEmpty && !schema.checkChild(root, '$text')) {
+            // If paragraph element is allowed in the root, create paragraph element.
+            if (schema.checkChild(root, 'paragraph')) {
+                writer.insertElement('paragraph', root);
+                // Other roots will get fixed in the next post-fixer round. Those will be triggered
+                // in the same batch no matter if this method was triggered by the post-fixing or not
+                // (the above insertElement call will trigger the post-fixers).
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Checks if the given node wrapped with a paragraph would be accepted by the schema in the given position.
+ *
+ * @internal
+ * @param position The position at which to check.
+ * @param nodeOrType The child node or child type to check.
+ * @param schema A schema instance used for element validation.
+ */
+export function isParagraphable(position, nodeOrType, schema) {
+    const context = schema.createContext(position);
+    // When paragraph is allowed in this context...
+    if (!schema.checkChild(context, 'paragraph')) {
+        return false;
+    }
+    // And a node would be allowed in this paragraph...
+    if (!schema.checkChild(context.push('paragraph'), nodeOrType)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Inserts a new paragraph at the given position and returns a position inside that paragraph.
+ *
+ * @internal
+ * @param position The position where a paragraph should be inserted.
+ * @param writer The model writer.
+ * @returns  Position inside the created paragraph.
+ */
+export function wrapInParagraph(position, writer) {
+    const paragraph = writer.createElement('paragraph');
+    writer.insert(paragraph, position);
+    return writer.createPositionAt(paragraph, 0);
+}