@ckeditor/ckeditor5-engine 0.0.0-internal-20241017.0

package/src/view/document.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @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/view/document
+ */
+import DocumentSelection from './documentselection.js';
+import { Collection } from '@ckeditor/ckeditor5-utils';
+import type { StylesProcessor } from './stylesmap.js';
+import type RootEditableElement from './rooteditableelement.js';
+import type DowncastWriter from './downcastwriter.js';
+declare const Document_base: import("@ckeditor/ckeditor5-utils").Mixed<{
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+}, import("@ckeditor/ckeditor5-utils").Emitter>;
+/**
+ * Document class creates an abstract layer over the content editable area, contains a tree of view elements and
+ * {@link module:engine/view/documentselection~DocumentSelection view selection} associated with this document.
+ */
+export default class Document extends /* #__PURE__ */ Document_base {
+    /**
+     * Selection done on this document.
+     */
+    readonly selection: DocumentSelection;
+    /**
+     * Roots of the view tree. Collection of the {@link module:engine/view/element~Element view elements}.
+     *
+     * View roots are created as a result of binding between {@link module:engine/view/document~Document#roots} and
+     * {@link module:engine/model/document~Document#roots} and this is handled by
+     * {@link module:engine/controller/editingcontroller~EditingController}, so to create view root we need to create
+     * model root using {@link module:engine/model/document~Document#createRoot}.
+     */
+    readonly roots: Collection<RootEditableElement>;
+    /**
+     * The styles processor instance used by this document when normalizing styles.
+     */
+    readonly stylesProcessor: StylesProcessor;
+    /**
+     * Defines whether document is in read-only mode.
+     *
+     * When document is read-ony then all roots are read-only as well and caret placed inside this root is hidden.
+     *
+     * @observable
+     */
+    isReadOnly: boolean;
+    /**
+     * True if document is focused.
+     *
+     * This property is updated by the {@link module:engine/view/observer/focusobserver~FocusObserver}.
+     * If the {@link module:engine/view/observer/focusobserver~FocusObserver} is disabled this property will not change.
+     *
+     * @readonly
+     * @observable
+     */
+    isFocused: boolean;
+    /**
+     * `true` while the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
+     * When they stop selecting, the property goes back to `false`.
+     *
+     * This property is updated by the {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+     *
+     * @readonly
+     * @observable
+     */
+    isSelecting: boolean;
+    /**
+     * True if composition is in progress inside the document.
+     *
+     * This property is updated by the {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+     * If the {@link module:engine/view/observer/compositionobserver~CompositionObserver} is disabled this property will not change.
+     *
+     * @readonly
+     * @observable
+     */
+    isComposing: boolean;
+    /**
+     * Post-fixer callbacks registered to the view document.
+     */
+    private readonly _postFixers;
+    /**
+     * Creates a Document instance.
+     *
+     * @param stylesProcessor The styles processor instance.
+     */
+    constructor(stylesProcessor: StylesProcessor);
+    /**
+     * Gets a {@link module:engine/view/document~Document#roots view root element} with the specified name. If the name is not
+     * specific "main" root is returned.
+     *
+     * @param name Name of the root.
+     * @returns The view root element with the specified name or null when there is no root of given name.
+     */
+    getRoot(name?: string): RootEditableElement | null;
+    /**
+     * Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
+     * to the DOM.
+     *
+     * Post-fixers are executed right after all changes from the outermost change block were applied but
+     * before the {@link module:engine/view/view~View#event:render render event} is fired. If a post-fixer callback made
+     * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+     * not be fixed in the new document tree state.
+     *
+     * View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
+     * changes executed in a view post-fixer should not break model-view mapping.
+     *
+     * The types of changes which should be safe:
+     *
+     * * adding or removing attribute from elements,
+     * * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
+     * * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
+     * re-converted}.
+     *
+     * Try to avoid changes which touch view structure:
+     *
+     * * you should not add or remove nor wrap or unwrap any view elements,
+     * * you should not change the editor data model in a view post-fixer.
+     *
+     * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
+     *
+     * Typically, a post-fixer will look like this:
+     *
+     * ```ts
+     * editor.editing.view.document.registerPostFixer( writer => {
+     * 	if ( checkSomeCondition() ) {
+     * 		writer.doSomething();
+     *
+     * 		// Let other post-fixers know that something changed.
+     * 		return true;
+     * 	}
+     *
+     * 	return false;
+     * } );
+     * ```
+     *
+     * Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
+     * That is because adding a post-fixer does not execute it.
+     * The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
+     * If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
+     * {@link module:engine/view/view~View#forceRender `view.forceRender()`}.
+     *
+     * If you need to register a callback which is executed when DOM elements are already updated,
+     * use {@link module:engine/view/view~View#event:render render event}.
+     */
+    registerPostFixer(postFixer: ViewDocumentPostFixer): void;
+    /**
+     * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
+     */
+    destroy(): void;
+    /**
+     * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+     *
+     * @internal
+     */
+    _callPostFixers(writer: DowncastWriter): void;
+}
+/**
+ * Document PostFixer.
+ *
+ * @see module:engine/view/document~Document#registerPostFixer
+ */
+export type ViewDocumentPostFixer = (writer: DowncastWriter) => boolean;
+/**
+ * Enum representing type of the change.
+ *
+ * Possible values:
+ *
+ * * `children` - for child list changes,
+ * * `attributes` - for element attributes changes,
+ * * `text` - for text nodes changes.
+ */
+export type ChangeType = 'children' | 'attributes' | 'text';
+/**
+ * Event fired whenever document content layout changes. It is fired whenever content is
+ * {@link module:engine/view/view~View#event:render rendered}, but should be also fired by observers in case of
+ * other actions which may change layout, for instance when image loads.
+ *
+ * @eventName ~Document#layoutChanged
+ */
+export type ViewDocumentLayoutChangedEvent = {
+    name: 'layoutChanged';
+    args: [];
+};
+export {};

package/src/view/document.js

@@ -0,0 +1,122 @@
+/**
+ * @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/view/document
+ */
+import DocumentSelection from './documentselection.js';
+import BubblingEmitterMixin from './observer/bubblingemittermixin.js';
+import { Collection, ObservableMixin } from '@ckeditor/ckeditor5-utils';
+// @if CK_DEBUG_ENGINE // const { logDocument } = require( '../dev-utils/utils' );
+/**
+ * Document class creates an abstract layer over the content editable area, contains a tree of view elements and
+ * {@link module:engine/view/documentselection~DocumentSelection view selection} associated with this document.
+ */
+export default class Document extends /* #__PURE__ */ BubblingEmitterMixin(/* #__PURE__ */ ObservableMixin()) {
+    /**
+     * Creates a Document instance.
+     *
+     * @param stylesProcessor The styles processor instance.
+     */
+    constructor(stylesProcessor) {
+        super();
+        /**
+         * Post-fixer callbacks registered to the view document.
+         */
+        this._postFixers = new Set();
+        this.selection = new DocumentSelection();
+        this.roots = new Collection({ idProperty: 'rootName' });
+        this.stylesProcessor = stylesProcessor;
+        this.set('isReadOnly', false);
+        this.set('isFocused', false);
+        this.set('isSelecting', false);
+        this.set('isComposing', false);
+    }
+    /**
+     * Gets a {@link module:engine/view/document~Document#roots view root element} with the specified name. If the name is not
+     * specific "main" root is returned.
+     *
+     * @param name Name of the root.
+     * @returns The view root element with the specified name or null when there is no root of given name.
+     */
+    getRoot(name = 'main') {
+        return this.roots.get(name);
+    }
+    /**
+     * Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
+     * to the DOM.
+     *
+     * Post-fixers are executed right after all changes from the outermost change block were applied but
+     * before the {@link module:engine/view/view~View#event:render render event} is fired. If a post-fixer callback made
+     * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+     * not be fixed in the new document tree state.
+     *
+     * View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
+     * changes executed in a view post-fixer should not break model-view mapping.
+     *
+     * The types of changes which should be safe:
+     *
+     * * adding or removing attribute from elements,
+     * * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
+     * * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
+     * re-converted}.
+     *
+     * Try to avoid changes which touch view structure:
+     *
+     * * you should not add or remove nor wrap or unwrap any view elements,
+     * * you should not change the editor data model in a view post-fixer.
+     *
+     * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
+     *
+     * Typically, a post-fixer will look like this:
+     *
+     * ```ts
+     * editor.editing.view.document.registerPostFixer( writer => {
+     * 	if ( checkSomeCondition() ) {
+     * 		writer.doSomething();
+     *
+     * 		// Let other post-fixers know that something changed.
+     * 		return true;
+     * 	}
+     *
+     * 	return false;
+     * } );
+     * ```
+     *
+     * Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
+     * That is because adding a post-fixer does not execute it.
+     * The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
+     * If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
+     * {@link module:engine/view/view~View#forceRender `view.forceRender()`}.
+     *
+     * If you need to register a callback which is executed when DOM elements are already updated,
+     * use {@link module:engine/view/view~View#event:render render event}.
+     */
+    registerPostFixer(postFixer) {
+        this._postFixers.add(postFixer);
+    }
+    /**
+     * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
+     */
+    destroy() {
+        this.roots.forEach(root => root.destroy());
+        this.stopListening();
+    }
+    /**
+     * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+     *
+     * @internal
+     */
+    _callPostFixers(writer) {
+        let wasFixed = false;
+        do {
+            for (const callback of this._postFixers) {
+                wasFixed = callback(writer);
+                if (wasFixed) {
+                    break;
+                }
+            }
+        } while (wasFixed);
+    }
+}

package/src/view/documentfragment.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @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/view/documentfragment
+ */
+import TypeCheckable from './typecheckable.js';
+import type { default as Document, ChangeType } from './document.js';
+import type Item from './item.js';
+import type Node from './node.js';
+declare const DocumentFragment_base: import("@ckeditor/ckeditor5-utils").Mixed<typeof TypeCheckable, import("@ckeditor/ckeditor5-utils").Emitter>;
+/**
+ * Document fragment.
+ *
+ * To create a new document fragment instance use the
+ * {@link module:engine/view/upcastwriter~UpcastWriter#createDocumentFragment `UpcastWriter#createDocumentFragment()`}
+ * method.
+ */
+export default class DocumentFragment extends /* #__PURE__ */ DocumentFragment_base implements Iterable<Node> {
+    /**
+     * The document to which this document fragment belongs.
+     */
+    readonly document: Document;
+    /**
+     * Array of child nodes.
+     */
+    private readonly _children;
+    /**
+     * Map of custom properties.
+     * Custom properties can be added to document fragment instance.
+     */
+    private readonly _customProperties;
+    /**
+     * Creates new DocumentFragment instance.
+     *
+     * @internal
+     * @param document The document to which this document fragment belongs.
+     * @param children A list of nodes to be inserted into the created document fragment.
+     */
+    constructor(document: Document, children?: Node | Iterable<Node>);
+    /**
+     * Iterable interface.
+     *
+     * Iterates over nodes added to this document fragment.
+     */
+    [Symbol.iterator](): Iterator<Node>;
+    /**
+     * Number of child nodes in this document fragment.
+     */
+    get childCount(): number;
+    /**
+     * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
+     */
+    get root(): this;
+    /**
+     * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
+     */
+    get parent(): null;
+    /**
+     * Artificial element name. Returns `undefined`. Added for compatibility reasons.
+     */
+    get name(): undefined;
+    /**
+     * Artificial element getFillerOffset. Returns `undefined`. Added for compatibility reasons.
+     */
+    get getFillerOffset(): undefined;
+    /**
+     * Returns the custom property value for the given key.
+     */
+    getCustomProperty(key: string | symbol): unknown;
+    /**
+     * Returns an iterator which iterates over this document fragment's custom properties.
+     * Iterator provides `[ key, value ]` pairs for each stored property.
+     */
+    getCustomProperties(): Iterable<[string | symbol, unknown]>;
+    /**
+     * {@link module:engine/view/documentfragment~DocumentFragment#_insertChild Insert} a child node or a list of child nodes at the end
+     * and sets the parent of these nodes to this fragment.
+     *
+     * @internal
+     * @param items Items to be inserted.
+     * @returns Number of appended nodes.
+     */
+    _appendChild(items: Item | string | Iterable<Item | string>): number;
+    /**
+     * Gets child at the given index.
+     *
+     * @param index Index of child.
+     * @returns Child node.
+     */
+    getChild(index: number): Node;
+    /**
+     * Gets index of the given child node. Returns `-1` if child node is not found.
+     *
+     * @param node Child node.
+     * @returns Index of the child node.
+     */
+    getChildIndex(node: Node): number;
+    /**
+     * Gets child nodes iterator.
+     *
+     * @returns Child nodes iterator.
+     */
+    getChildren(): IterableIterator<Node>;
+    /**
+     * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
+     * this fragment.
+     *
+     * @internal
+     * @param index Position where nodes should be inserted.
+     * @param items Items to be inserted.
+     * @returns Number of inserted nodes.
+     */
+    _insertChild(index: number, items: Item | string | Iterable<Item | string>): number;
+    /**
+     * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
+     *
+     * @internal
+     * @param index Number of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns The array of removed nodes.
+     */
+    _removeChildren(index: number, howMany?: number): Array<Node>;
+    /**
+     * Fires `change` event with given type of the change.
+     *
+     * @internal
+     * @param type Type of the change.
+     * @param node Changed node.
+     */
+    _fireChange(type: ChangeType, node: Node | DocumentFragment): void;
+    /**
+     * Sets a custom property. They can be used to add special data to elements.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#setCustomProperty
+     * @internal
+     */
+    _setCustomProperty(key: string | symbol, value: unknown): void;
+    /**
+     * Removes the custom property stored under the given key.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#removeCustomProperty
+     * @internal
+     * @returns Returns true if property was removed.
+     */
+    _removeCustomProperty(key: string | symbol): boolean;
+}
+export {};

package/src/view/documentfragment.js

@@ -0,0 +1,234 @@
+/**
+ * @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/view/documentfragment
+ */
+import TypeCheckable from './typecheckable.js';
+import Text from './text.js';
+import TextProxy from './textproxy.js';
+import { EmitterMixin, isIterable } from '@ckeditor/ckeditor5-utils';
+/**
+ * Document fragment.
+ *
+ * To create a new document fragment instance use the
+ * {@link module:engine/view/upcastwriter~UpcastWriter#createDocumentFragment `UpcastWriter#createDocumentFragment()`}
+ * method.
+ */
+export default class DocumentFragment extends /* #__PURE__ */ EmitterMixin(TypeCheckable) {
+    /**
+     * Creates new DocumentFragment instance.
+     *
+     * @internal
+     * @param document The document to which this document fragment belongs.
+     * @param children A list of nodes to be inserted into the created document fragment.
+     */
+    constructor(document, children) {
+        super();
+        /**
+         * Array of child nodes.
+         */
+        this._children = [];
+        /**
+         * Map of custom properties.
+         * Custom properties can be added to document fragment instance.
+         */
+        this._customProperties = new Map();
+        this.document = document;
+        if (children) {
+            this._insertChild(0, children);
+        }
+    }
+    /**
+     * Iterable interface.
+     *
+     * Iterates over nodes added to this document fragment.
+     */
+    [Symbol.iterator]() {
+        return this._children[Symbol.iterator]();
+    }
+    /**
+     * Number of child nodes in this document fragment.
+     */
+    get childCount() {
+        return this._children.length;
+    }
+    /**
+     * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
+     */
+    get isEmpty() {
+        return this.childCount === 0;
+    }
+    /**
+     * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
+     */
+    get root() {
+        return this;
+    }
+    /**
+     * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
+     */
+    get parent() {
+        return null;
+    }
+    /**
+     * Artificial element name. Returns `undefined`. Added for compatibility reasons.
+     */
+    get name() {
+        return undefined;
+    }
+    /**
+     * Artificial element getFillerOffset. Returns `undefined`. Added for compatibility reasons.
+     */
+    get getFillerOffset() {
+        return undefined;
+    }
+    /**
+     * Returns the custom property value for the given key.
+     */
+    getCustomProperty(key) {
+        return this._customProperties.get(key);
+    }
+    /**
+     * Returns an iterator which iterates over this document fragment's custom properties.
+     * Iterator provides `[ key, value ]` pairs for each stored property.
+     */
+    *getCustomProperties() {
+        yield* this._customProperties.entries();
+    }
+    /**
+     * {@link module:engine/view/documentfragment~DocumentFragment#_insertChild Insert} a child node or a list of child nodes at the end
+     * and sets the parent of these nodes to this fragment.
+     *
+     * @internal
+     * @param items Items to be inserted.
+     * @returns Number of appended nodes.
+     */
+    _appendChild(items) {
+        return this._insertChild(this.childCount, items);
+    }
+    /**
+     * Gets child at the given index.
+     *
+     * @param index Index of child.
+     * @returns Child node.
+     */
+    getChild(index) {
+        return this._children[index];
+    }
+    /**
+     * Gets index of the given child node. Returns `-1` if child node is not found.
+     *
+     * @param node Child node.
+     * @returns Index of the child node.
+     */
+    getChildIndex(node) {
+        return this._children.indexOf(node);
+    }
+    /**
+     * Gets child nodes iterator.
+     *
+     * @returns Child nodes iterator.
+     */
+    getChildren() {
+        return this._children[Symbol.iterator]();
+    }
+    /**
+     * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
+     * this fragment.
+     *
+     * @internal
+     * @param index Position where nodes should be inserted.
+     * @param items Items to be inserted.
+     * @returns Number of inserted nodes.
+     */
+    _insertChild(index, items) {
+        this._fireChange('children', this);
+        let count = 0;
+        const nodes = normalize(this.document, items);
+        for (const node of nodes) {
+            // If node that is being added to this element is already inside another element, first remove it from the old parent.
+            if (node.parent !== null) {
+                node._remove();
+            }
+            node.parent = this;
+            this._children.splice(index, 0, node);
+            index++;
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
+     *
+     * @internal
+     * @param index Number of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns The array of removed nodes.
+     */
+    _removeChildren(index, howMany = 1) {
+        this._fireChange('children', this);
+        for (let i = index; i < index + howMany; i++) {
+            this._children[i].parent = null;
+        }
+        return this._children.splice(index, howMany);
+    }
+    /**
+     * Fires `change` event with given type of the change.
+     *
+     * @internal
+     * @param type Type of the change.
+     * @param node Changed node.
+     */
+    _fireChange(type, node) {
+        this.fire('change:' + type, node);
+    }
+    /**
+     * Sets a custom property. They can be used to add special data to elements.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#setCustomProperty
+     * @internal
+     */
+    _setCustomProperty(key, value) {
+        this._customProperties.set(key, value);
+    }
+    /**
+     * Removes the custom property stored under the given key.
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#removeCustomProperty
+     * @internal
+     * @returns Returns true if property was removed.
+     */
+    _removeCustomProperty(key) {
+        return this._customProperties.delete(key);
+    }
+}
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
+DocumentFragment.prototype.is = function (type) {
+    return type === 'documentFragment' || type === 'view:documentFragment';
+};
+/**
+ * Converts strings to Text and non-iterables to arrays.
+ */
+function normalize(document, nodes) {
+    // Separate condition because string is iterable.
+    if (typeof nodes == 'string') {
+        return [new Text(document, nodes)];
+    }
+    if (!isIterable(nodes)) {
+        nodes = [nodes];
+    }
+    // Array.from to enable .map() on non-arrays.
+    return Array.from(nodes)
+        .map(node => {
+        if (typeof node == 'string') {
+            return new Text(document, node);
+        }
+        if (node instanceof TextProxy) {
+            return new Text(document, node.data);
+        }
+        return node;
+    });
+}