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

package/src/model/document.d.ts

@@ -0,0 +1,245 @@
+/**
+ * @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/document
+ */
+import Differ from './differ';
+import DocumentSelection from './documentselection';
+import History from './history';
+import RootElement from './rootelement';
+import type { default as Model } from './model';
+import type Batch from './batch';
+import type Range from './range';
+import type Writer from './writer';
+import { Collection } from '@ckeditor/ckeditor5-utils';
+declare const Document_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Emitter;
+    prototype: import("@ckeditor/ckeditor5-utils").Emitter;
+};
+/**
+ * Data model's document. It contains the model's structure, its selection and the history of changes.
+ *
+ * Read more about working with the model in
+ * {@glink framework/architecture/editing-engine#model introduction to the the editing engine's architecture}.
+ *
+ * Usually, the document contains just one {@link module:engine/model/document~Document#roots root element}, so
+ * you can retrieve it by just calling {@link module:engine/model/document~Document#getRoot} without specifying its name:
+ *
+ * ```ts
+ * model.document.getRoot(); // -> returns the main root
+ * ```
+ *
+ * However, the document may contain multiple roots – e.g. when the editor has multiple editable areas
+ * (e.g. a title and a body of a message).
+ */
+export default class Document extends Document_base {
+    /**
+     * The {@link module:engine/model/model~Model model} that the document is a part of.
+     */
+    readonly model: Model;
+    /**
+     * The document's history.
+     */
+    readonly history: History;
+    /**
+     * The selection in this document.
+     */
+    readonly selection: DocumentSelection;
+    /**
+     * A list of roots that are owned and managed by this document. Use {@link #createRoot} and
+     * {@link #getRoot} to manipulate it.
+     */
+    readonly roots: Collection<RootElement>;
+    /**
+     * The model differ object. Its role is to buffer changes done on the model document and then calculate a diff of those changes.
+     */
+    readonly differ: Differ;
+    /**
+     * Post-fixer callbacks registered to the model document.
+     */
+    private readonly _postFixers;
+    /**
+     * A boolean indicates whether the selection has changed until
+     */
+    private _hasSelectionChangedFromTheLastChangeBlock;
+    /**
+     * Creates an empty document instance with no {@link #roots} (other than
+     * the {@link #graveyard graveyard root}).
+     */
+    constructor(model: Model);
+    /**
+     * The document version. Every applied operation increases the version number. It is used to
+     * ensure that operations are applied on a proper document version.
+     *
+     * This property is equal to {@link module:engine/model/history~History#version `model.Document#history#version`}.
+     *
+     * If the {@link module:engine/model/operation/operation~Operation#baseVersion base version} does not match the document version,
+     * a {@link module:utils/ckeditorerror~CKEditorError model-document-applyoperation-wrong-version} error is thrown.
+     */
+    get version(): number;
+    set version(version: number);
+    /**
+     * The graveyard tree root. A document always has a graveyard root that stores removed nodes.
+     */
+    get graveyard(): RootElement;
+    /**
+     * Creates a new root.
+     *
+     * @param elementName The element name. Defaults to `'$root'` which also has some basic schema defined
+     * (`$block`s are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
+     * @param rootName A unique root name.
+     * @returns The created root.
+     */
+    createRoot(elementName?: string, rootName?: string): RootElement;
+    /**
+     * Removes all event listeners set by the document instance.
+     */
+    destroy(): void;
+    /**
+     * Returns a root by its name.
+     *
+     * @param name A unique root name.
+     * @returns The root registered under a given name or `null` when there is no root with the given name.
+     */
+    getRoot(name?: string): RootElement | null;
+    /**
+     * Returns an array with names of all roots (without the {@link #graveyard}) added to the document.
+     *
+     * @returns Roots names.
+     */
+    getRootNames(): Array<string>;
+    /**
+     * Used to register a post-fixer callback. A post-fixer mechanism guarantees that the features
+     * will operate on a correct model state.
+     *
+     * An execution of a feature may lead to an incorrect document tree state. The callbacks are used to fix the document tree after
+     * it has changed. Post-fixers are fired just after all changes from the outermost change block were applied but
+     * before the {@link module:engine/model/document~Document#event:change change 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.
+     *
+     * As a parameter, a post-fixer callback receives a {@link module:engine/model/writer~Writer writer} instance connected with the
+     * executed changes block. Thanks to that, all changes done by the callback will be added to the same
+     * {@link module:engine/model/batch~Batch batch} (and undo step) as the original changes. This makes post-fixer changes transparent
+     * for the user.
+     *
+     * An example of a post-fixer is a callback that checks if all the data were removed from the editor. If so, the
+     * callback should add an empty paragraph so that the editor is never empty:
+     *
+     * ```ts
+     * document.registerPostFixer( writer => {
+     * 	const changes = document.differ.getChanges();
+     *
+     * 	// Check if the changes lead to an empty root in the editor.
+     * 	for ( const entry of changes ) {
+     * 		if ( entry.type == 'remove' && entry.position.root.isEmpty ) {
+     * 			writer.insertElement( 'paragraph', entry.position.root, 0 );
+     *
+     * 			// It is fine to return early, even if multiple roots would need to be fixed.
+     * 			// All post-fixers will be fired again, so if there are more empty roots, those will be fixed, too.
+     * 			return true;
+     * 		}
+     * 	}
+     *
+     * 	return false;
+     * } );
+     * ```
+     */
+    registerPostFixer(postFixer: ModelPostFixer): void;
+    /**
+     * A custom `toJSON()` method to solve child-parent circular dependencies.
+     *
+     * @returns A clone of this object with the document property changed to a string.
+     */
+    toJSON(): unknown;
+    /**
+     * Check if there were any changes done on document, and if so, call post-fixers,
+     * fire `change` event for features and conversion and then reset the differ.
+     * Fire `change:data` event when at least one operation or buffered marker changes the data.
+     *
+     * @internal
+     * @fires change
+     * @fires change:data
+     * @param writer The writer on which post-fixers will be called.
+     */
+    _handleChangeBlock(writer: Writer): void;
+    /**
+     * Returns whether there is a buffered change or if the selection has changed from the last
+     * {@link module:engine/model/model~Model#enqueueChange `enqueueChange()` block}
+     * or {@link module:engine/model/model~Model#change `change()` block}.
+     *
+     * @returns Returns `true` if document has changed from the last `change()` or `enqueueChange()` block.
+     */
+    protected _hasDocumentChangedFromTheLastChangeBlock(): boolean;
+    /**
+     * Returns the default root for this document which is either the first root that was added to the document using
+     * {@link #createRoot} or the {@link #graveyard graveyard root} if no other roots were created.
+     *
+     * @returns The default root for this document.
+     */
+    protected _getDefaultRoot(): RootElement;
+    /**
+     * Returns the default range for this selection. The default range is a collapsed range that starts and ends
+     * at the beginning of this selection's document {@link #_getDefaultRoot default root}.
+     *
+     * @internal
+     */
+    _getDefaultRange(): Range;
+    /**
+     * Checks whether a given {@link module:engine/model/range~Range range} is a valid range for
+     * the {@link #selection document's selection}.
+     *
+     * @internal
+     * @param range A range to check.
+     * @returns `true` if `range` is valid, `false` otherwise.
+     */
+    _validateSelectionRange(range: Range): boolean;
+    /**
+     * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+     *
+     * @param writer The writer on which post-fixer callbacks will be called.
+     */
+    private _callPostFixers;
+}
+/**
+ * Fired after each {@link module:engine/model/model~Model#enqueueChange `enqueueChange()` block} or the outermost
+ * {@link module:engine/model/model~Model#change `change()` block} was executed and the document was changed
+ * during that block's execution.
+ *
+ * The changes which this event will cover include:
+ *
+ * * document structure changes,
+ * * selection changes,
+ * * marker changes.
+ *
+ * If you want to be notified about all these changes, then simply listen to this event like this:
+ *
+ * ```ts
+ * model.document.on( 'change', () => {
+ * 	console.log( 'The document has changed!' );
+ * } );
+ * ```
+ *
+ * If, however, you only want to be notified about the data changes, then use `change:data` event,
+ * which is fired for document structure changes and marker changes (which affects the data).
+ *
+ * ```ts
+ * model.document.on( 'change:data', () => {
+ * 	console.log( 'The data has changed!' );
+ * } );
+ * ```
+ *
+ * @eventName change
+ * @param batch The batch that was used in the executed changes block.
+ */
+export type DocumentChangeEvent = {
+    name: 'change' | 'change:data';
+    args: [batch: Batch];
+};
+/**
+ * Callback passed as an argument to the {@link module:engine/model/document~Document#registerPostFixer} method.
+ */
+export type ModelPostFixer = (writer: Writer) => boolean;
+export {};

package/src/model/document.js

@@ -17,7 +17,7 @@ const graveyardName = '$graveyard';
  * Data model's document. It contains the model's structure, its selection and the history of changes.
  *
  * Read more about working with the model in
- * {@glink framework/guides/architecture/editing-engine#model introduction to the the editing engine's architecture}.
+ * {@glink framework/architecture/editing-engine#model introduction to the the editing engine's architecture}.
  *
  * Usually, the document contains just one {@link module:engine/model/document~Document#roots root element}, so
  * you can retrieve it by just calling {@link module:engine/model/document~Document#getRoot} without specifying its name:

package/src/model/documentfragment.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @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/documentfragment
+ */
+import TypeCheckable from './typecheckable';
+import type Item from './item';
+import type Node from './node';
+import type Range from './range';
+/**
+ * DocumentFragment represents a part of model which does not have a common root but its top-level nodes
+ * can be seen as siblings. In other words, it is a detached part of model tree, without a root.
+ *
+ * DocumentFragment has own {@link module:engine/model/markercollection~MarkerCollection}. Markers from this collection
+ * will be set to the {@link module:engine/model/model~Model#markers model markers} by a
+ * {@link module:engine/model/writer~Writer#insert} function.
+ */
+export default class DocumentFragment extends TypeCheckable implements Iterable<Node> {
+    /**
+     * DocumentFragment static markers map. This is a list of names and {@link module:engine/model/range~Range ranges}
+     * which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
+     * when DocumentFragment will be inserted to the document.
+     */
+    readonly markers: Map<string, Range>;
+    /**
+     * Artificial element name. Returns `undefined`. Added for compatibility reasons.
+     */
+    name?: undefined;
+    /**
+     * Artificial root name. Returns `undefined`. Added for compatibility reasons.
+     */
+    rootName?: undefined;
+    /**
+     * List of nodes contained inside the document fragment.
+     */
+    private readonly _children;
+    /**
+     * Creates an empty `DocumentFragment`.
+     *
+     * **Note:** Constructor of this class shouldn't be used directly in the code.
+     * Use the {@link module:engine/model/writer~Writer#createDocumentFragment} method instead.
+     *
+     * @internal
+     * @param children Nodes to be contained inside the `DocumentFragment`.
+     */
+    constructor(children?: Node | Iterable<Node>);
+    /**
+     * Returns an iterator that iterates over all nodes contained inside this document fragment.
+     */
+    [Symbol.iterator](): IterableIterator<Node>;
+    /**
+     * Number of this document fragment's children.
+     */
+    get childCount(): number;
+    /**
+     * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all of this document fragment's children.
+     */
+    get maxOffset(): number;
+    /**
+     * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Artificial next sibling. Returns `null`. Added for compatibility reasons.
+     */
+    get nextSibling(): null;
+    /**
+     * Artificial previous sibling. Returns `null`. Added for compatibility reasons.
+     */
+    get previousSibling(): null;
+    /**
+     * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
+     */
+    get root(): DocumentFragment;
+    /**
+     * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
+     */
+    get parent(): null;
+    /**
+     * Artificial owner of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
+     */
+    get document(): null;
+    /**
+     * Returns empty array. Added for compatibility reasons.
+     */
+    getAncestors(): Array<never>;
+    /**
+     * Gets the child at the given index. Returns `null` if incorrect index was passed.
+     *
+     * @param index Index of child.
+     * @returns Child node.
+     */
+    getChild(index: number): Node | null;
+    /**
+     * Returns an iterator that iterates over all of this document fragment's children.
+     */
+    getChildren(): IterableIterator<Node>;
+    /**
+     * Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
+     *
+     * @param node Child node to look for.
+     * @returns Child node's index.
+     */
+    getChildIndex(node: Node): number | null;
+    /**
+     * Returns the starting offset of given child. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all node's siblings that are before it. Returns `null` if
+     * given node is not a child of this document fragment.
+     *
+     * @param node Child node to look for.
+     * @returns Child node's starting offset.
+     */
+    getChildStartOffset(node: Node): number | null;
+    /**
+     * Returns path to a `DocumentFragment`, which is an empty array. Added for compatibility reasons.
+     */
+    getPath(): Array<number>;
+    /**
+     * Returns a descendant node by its path relative to this element.
+     *
+     * ```ts
+     * // <this>a<b>c</b></this>
+     * this.getNodeByPath( [ 0 ] );     // -> "a"
+     * this.getNodeByPath( [ 1 ] );     // -> <b>
+     * this.getNodeByPath( [ 1, 0 ] );  // -> "c"
+     * ```
+     *
+     * @param relativePath Path of the node to find, relative to this element.
+     */
+    getNodeByPath(relativePath: Array<number>): Node | DocumentFragment;
+    /**
+     * Converts offset "position" to index "position".
+     *
+     * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
+     * too high, returns index after last child.
+     *
+     * ```ts
+     * const textNode = new Text( 'foo' );
+     * const pElement = new Element( 'p' );
+     * const docFrag = new DocumentFragment( [ textNode, pElement ] );
+     * docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
+     * docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
+     * docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
+     * docFrag.offsetToIndex( 2 ); // Returns 0.
+     * docFrag.offsetToIndex( 3 ); // Returns 1.
+     * docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
+     * ```
+     *
+     * @param offset Offset to look for.
+     * @returns Index of a node that occupies given offset.
+     */
+    offsetToIndex(offset: number): number;
+    /**
+     * Converts `DocumentFragment` instance to plain object and returns it.
+     * Takes care of converting all of this document fragment's children.
+     *
+     * @returns `DocumentFragment` instance converted to plain object.
+     */
+    toJSON(): unknown;
+    /**
+     * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
+     * Converts `DocumentFragment` children to proper nodes.
+     *
+     * @param json Plain object to be converted to `DocumentFragment`.
+     * @returns `DocumentFragment` instance created using given plain object.
+     */
+    static fromJSON(json: any): DocumentFragment;
+    /**
+     * {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
+     *
+     * @internal
+     * @param items Items to be inserted.
+     */
+    _appendChild(items: string | Item | Iterable<string | Item>): void;
+    /**
+     * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
+     * to this document fragment.
+     *
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param items Items to be inserted.
+     */
+    _insertChild(index: number, items: string | Item | Iterable<string | Item>): void;
+    /**
+     * Removes one or more nodes starting at the given index
+     * and sets {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
+     *
+     * @internal
+     * @param index Index of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns Array containing removed nodes.
+     */
+    _removeChildren(index: number, howMany?: number): Array<Node>;
+}

package/src/model/documentfragment.js

@@ -3,7 +3,7 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
- * @module module:engine/model/documentfragment
+ * @module engine/model/documentfragment
  */
 import TypeCheckable from './typecheckable';
 import Element from './element';
@@ -171,7 +171,7 @@ export default class DocumentFragment extends TypeCheckable {
      * Converts offset "position" to index "position".
      *
      * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
-     * too high, returns index after last child}.
+     * too high, returns index after last child.
      *
      * ```ts
      * const textNode = new Text( 'foo' );