@ckeditor/ckeditor5-engine 35.4.0 → 36.0.0

package/src/model/document.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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
  */
 /**
@@ -22,12 +22,12 @@ const graveyardName = '$graveyard';
  * 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:
  *
- *		model.document.getRoot(); // -> returns the main root
+ * ```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).
- *
- * @mixes module:utils/emittermixin~EmitterMixin
  */
 export default class Document extends EmitterMixin() {
     /**
@@ -36,55 +36,12 @@ export default class Document extends EmitterMixin() {
      */
     constructor(model) {
         super();
-        /**
-         * The {@link module:engine/model/model~Model model} that the document is a part of.
-         *
-         * @readonly
-         * @type {module:engine/model/model~Model}
-         */
         this.model = model;
-        /**
-         * The document's history.
-         *
-         * @readonly
-         * @type {module:engine/model/history~History}
-         */
         this.history = new History();
-        /**
-         * The selection in this document.
-         *
-         * @readonly
-         * @type {module:engine/model/documentselection~DocumentSelection}
-         */
         this.selection = new DocumentSelection(this);
-        /**
-         * A list of roots that are owned and managed by this document. Use {@link #createRoot} and
-         * {@link #getRoot} to manipulate it.
-         *
-         * @readonly
-         * @type {module:utils/collection~Collection}
-         */
         this.roots = new Collection({ idProperty: 'rootName' });
-        /**
-         * The model differ object. Its role is to buffer changes done on the model document and then calculate a diff of those changes.
-         *
-         * @readonly
-         * @type {module:engine/model/differ~Differ}
-         */
         this.differ = new Differ(model.markers);
-        /**
-         * Post-fixer callbacks registered to the model document.
-         *
-         * @private
-         * @type {Set.<Function>}
-         */
         this._postFixers = new Set();
-        /**
-         * A boolean indicates whether the selection has changed until
-         *
-         * @private
-         * @type {Boolean}
-         */
         this._hasSelectionChangedFromTheLastChangeBlock = false;
         // Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
         this.createRoot('$root', graveyardName);
@@ -131,8 +88,6 @@ export default class Document extends EmitterMixin() {
      *
      * 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.
-     *
-     * @type {Number}
      */
     get version() {
         return this.history.version;
@@ -142,9 +97,6 @@ export default class Document extends EmitterMixin() {
     }
     /**
      * The graveyard tree root. A document always has a graveyard root that stores removed nodes.
-     *
-     * @readonly
-     * @member {module:engine/model/rootelement~RootElement}
      */
     get graveyard() {
         return this.getRoot(graveyardName);
@@ -152,10 +104,10 @@ export default class Document extends EmitterMixin() {
     /**
      * Creates a new root.
      *
-     * @param {String} [elementName='$root'] The element name. Defaults to `'$root'` which also has some basic schema defined
+     * @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 {String} [rootName='main'] A unique root name.
-     * @returns {module:engine/model/rootelement~RootElement} The created root.
+     * @param rootName A unique root name.
+     * @returns The created root.
      */
     createRoot(elementName = '$root', rootName = 'main') {
         if (this.roots.get(rootName)) {
@@ -163,8 +115,6 @@ export default class Document extends EmitterMixin() {
              * A root with the specified name already exists.
              *
              * @error model-document-createroot-name-exists
-             * @param {module:engine/model/document~Document} doc
-             * @param {String} name
              */
             throw new CKEditorError('model-document-createroot-name-exists', this, { name: rootName });
         }
@@ -182,9 +132,8 @@ export default class Document extends EmitterMixin() {
     /**
      * Returns a root by its name.
      *
-     * @param {String} [name='main'] A unique root name.
-     * @returns {module:engine/model/rootelement~RootElement|null} The root registered under a given name or `null` when
-     * there is no root with the given 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 = 'main') {
         return this.roots.get(name);
@@ -192,7 +141,7 @@ export default class Document extends EmitterMixin() {
     /**
      * Returns an array with names of all roots (without the {@link #graveyard}) added to the document.
      *
-     * @returns {Array.<String>} Roots names.
+     * @returns Roots names.
      */
     getRootNames() {
         return Array.from(this.roots, root => root.rootName).filter(name => name != graveyardName);
@@ -215,24 +164,24 @@ export default class Document extends EmitterMixin() {
      * 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:
      *
-     *		document.registerPostFixer( writer => {
-     *			const changes = document.differ.getChanges();
+     * ```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 );
+     * 	// 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;
-     *				}
-     *			}
+     * 			// 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;
-     *		} );
-     *
-     * @param {Function} postFixer
+     * 	return false;
+     * } );
+     * ```
      */
     registerPostFixer(postFixer) {
         this._postFixers.add(postFixer);
@@ -240,7 +189,7 @@ export default class Document extends EmitterMixin() {
     /**
      * A custom `toJSON()` method to solve child-parent circular dependencies.
      *
-     * @returns {Object} A clone of this object with the document property changed to a string.
+     * @returns A clone of this object with the document property changed to a string.
      */
     toJSON() {
         const json = clone(this);
@@ -255,10 +204,9 @@ export default class Document extends EmitterMixin() {
      * Fire `change:data` event when at least one operation or buffered marker changes the data.
      *
      * @internal
-     * @protected
      * @fires change
      * @fires change:data
-     * @param {module:engine/model/writer~Writer} writer The writer on which post-fixers will be called.
+     * @param writer The writer on which post-fixers will be called.
      */
     _handleChangeBlock(writer) {
         if (this._hasDocumentChangedFromTheLastChangeBlock()) {
@@ -283,8 +231,7 @@ export default class Document extends EmitterMixin() {
      * {@link module:engine/model/model~Model#enqueueChange `enqueueChange()` block}
      * or {@link module:engine/model/model~Model#change `change()` block}.
      *
-     * @protected
-     * @returns {Boolean} Returns `true` if document has changed from the last `change()` or `enqueueChange()` block.
+     * @returns Returns `true` if document has changed from the last `change()` or `enqueueChange()` block.
      */
     _hasDocumentChangedFromTheLastChangeBlock() {
         return !this.differ.isEmpty || this._hasSelectionChangedFromTheLastChangeBlock;
@@ -293,8 +240,7 @@ export default class Document extends EmitterMixin() {
      * 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.
      *
-     * @protected
-     * @returns {module:engine/model/rootelement~RootElement} The default root for this document.
+     * @returns The default root for this document.
      */
     _getDefaultRoot() {
         for (const root of this.roots) {
@@ -309,8 +255,6 @@ export default class Document extends EmitterMixin() {
      * at the beginning of this selection's document {@link #_getDefaultRoot default root}.
      *
      * @internal
-     * @protected
-     * @returns {module:engine/model/range~Range}
      */
     _getDefaultRange() {
         const defaultRoot = this._getDefaultRoot();
@@ -327,9 +271,8 @@ export default class Document extends EmitterMixin() {
      * the {@link #selection document's selection}.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/range~Range} range A range to check.
-     * @returns {Boolean} `true` if `range` is valid, `false` otherwise.
+     * @param range A range to check.
+     * @returns `true` if `range` is valid, `false` otherwise.
      */
     _validateSelectionRange(range) {
         return validateTextNodePosition(range.start) && validateTextNodePosition(range.end);
@@ -337,8 +280,7 @@ export default class Document extends EmitterMixin() {
     /**
      * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
      *
-     * @private
-     * @param {module:engine/model/writer~Writer} writer The writer on which post-fixer callbacks will be called.
+     * @param writer The writer on which post-fixer callbacks will be called.
      */
     _callPostFixers(writer) {
         let wasFixed = false;
@@ -359,8 +301,10 @@ export default class Document extends EmitterMixin() {
         } while (wasFixed);
     }
 }
-// Checks whether given range boundary position is valid for document selection, meaning that is not between
-// unicode surrogate pairs or base character and combining marks.
+/**
+ * Checks whether given range boundary position is valid for document selection, meaning that is not between
+ * unicode surrogate pairs or base character and combining marks.
+ */
 function validateTextNodePosition(rangeBoundary) {
     const textNode = rangeBoundary.textNode;
     if (textNode) {

package/src/model/documentfragment.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @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
  */
 /**
@@ -27,9 +27,8 @@ export default class DocumentFragment extends TypeCheckable {
      * **Note:** Constructor of this class shouldn't be used directly in the code.
      * Use the {@link module:engine/model/writer~Writer#createDocumentFragment} method instead.
      *
-     * @protected
-     * @param {module:engine/model/node~Node|Iterable.<module:engine/model/node~Node>} [children]
-     * Nodes to be contained inside the `DocumentFragment`.
+     * @internal
+     * @param children Nodes to be contained inside the `DocumentFragment`.
      */
     constructor(children) {
         super();
@@ -37,16 +36,10 @@ export default class DocumentFragment extends TypeCheckable {
          * 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
-         * @member {Map<String,module:engine/model/range~Range>} module:engine/model/documentfragment~DocumentFragment#markers
          */
         this.markers = new Map();
         /**
          * List of nodes contained inside the document fragment.
-         *
-         * @private
-         * @member {module:engine/model/nodelist~NodeList} module:engine/model/documentfragment~DocumentFragment#_children
          */
         this._children = new NodeList();
         if (children) {
@@ -55,88 +48,60 @@ export default class DocumentFragment extends TypeCheckable {
     }
     /**
      * Returns an iterator that iterates over all nodes contained inside this document fragment.
-     *
-     * @returns {Iterator.<module:engine/model/node~Node>}
      */
     [Symbol.iterator]() {
         return this.getChildren();
     }
     /**
      * Number of this document fragment's children.
-     *
-     * @readonly
-     * @type {Number}
      */
     get childCount() {
         return this._children.length;
     }
     /**
      * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all of this document fragment's children.
-     *
-     * @readonly
-     * @type {Number}
      */
     get maxOffset() {
         return this._children.maxOffset;
     }
     /**
      * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isEmpty() {
         return this.childCount === 0;
     }
     /**
      * Artificial next sibling. Returns `null`. Added for compatibility reasons.
-     *
-     * @readonly
-     * @type {null}
      */
     get nextSibling() {
         return null;
     }
     /**
      * Artificial previous sibling. Returns `null`. Added for compatibility reasons.
-     *
-     * @readonly
-     * @type {null}
      */
     get previousSibling() {
         return null;
     }
     /**
      * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
-     *
-     * @readonly
-     * @type {module:engine/model/documentfragment~DocumentFragment}
      */
     get root() {
         return this;
     }
     /**
      * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
-     *
-     * @readonly
-     * @type {null}
      */
     get parent() {
         return null;
     }
     /**
      * Artificial owner of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
-     *
-     * @readonly
-     * @type {null}
      */
     get document() {
         return null;
     }
     /**
      * Returns empty array. Added for compatibility reasons.
-     *
-     * @returns {Array}
      */
     getAncestors() {
         return [];
@@ -144,16 +109,14 @@ export default class DocumentFragment extends TypeCheckable {
     /**
      * Gets the child at the given index. Returns `null` if incorrect index was passed.
      *
-     * @param {Number} index Index of child.
-     * @returns {module:engine/model/node~Node|null} Child node.
+     * @param index Index of child.
+     * @returns Child node.
      */
     getChild(index) {
         return this._children.getNode(index);
     }
     /**
      * Returns an iterator that iterates over all of this document fragment's children.
-     *
-     * @returns {Iterable.<module:engine/model/node~Node>}
      */
     getChildren() {
         return this._children[Symbol.iterator]();
@@ -161,8 +124,8 @@ export default class DocumentFragment extends TypeCheckable {
     /**
      * Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
      *
-     * @param {module:engine/model/node~Node} node Child node to look for.
-     * @returns {Number|null} Child node's index.
+     * @param node Child node to look for.
+     * @returns Child node's index.
      */
     getChildIndex(node) {
         return this._children.getNodeIndex(node);
@@ -172,16 +135,14 @@ export default class DocumentFragment extends TypeCheckable {
      * {@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 {module:engine/model/node~Node} node Child node to look for.
-     * @returns {Number|null} Child node's starting offset.
+     * @param node Child node to look for.
+     * @returns Child node's starting offset.
      */
     getChildStartOffset(node) {
         return this._children.getNodeStartOffset(node);
     }
     /**
      * Returns path to a `DocumentFragment`, which is an empty array. Added for compatibility reasons.
-     *
-     * @returns {Array}
      */
     getPath() {
         return [];
@@ -189,13 +150,14 @@ export default class DocumentFragment extends TypeCheckable {
     /**
      * Returns a descendant node by its path relative to this element.
      *
-     *		// <this>a<b>c</b></this>
-     *		this.getNodeByPath( [ 0 ] );     // -> "a"
-     *		this.getNodeByPath( [ 1 ] );     // -> <b>
-     *		this.getNodeByPath( [ 1, 0 ] );  // -> "c"
+     * ```ts
+     * // <this>a<b>c</b></this>
+     * this.getNodeByPath( [ 0 ] );     // -> "a"
+     * this.getNodeByPath( [ 1 ] );     // -> <b>
+     * this.getNodeByPath( [ 1, 0 ] );  // -> "c"
+     * ```
      *
-     * @param {Array.<Number>} relativePath Path of the node to find, relative to this element.
-     * @returns {module:engine/model/node~Node|module:engine/model/documentfragment~DocumentFragment}
+     * @param relativePath Path of the node to find, relative to this element.
      */
     getNodeByPath(relativePath) {
         // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
@@ -211,18 +173,20 @@ export default class DocumentFragment extends TypeCheckable {
      * 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}.
      *
-     *		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.
+     * ```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 {Number} offset Offset to look for.
-     * @returns {Number} Index of a node that occupies given offset.
+     * @param offset Offset to look for.
+     * @returns Index of a node that occupies given offset.
      */
     offsetToIndex(offset) {
         return this._children.offsetToIndex(offset);
@@ -231,7 +195,7 @@ export default class DocumentFragment extends TypeCheckable {
      * Converts `DocumentFragment` instance to plain object and returns it.
      * Takes care of converting all of this document fragment's children.
      *
-     * @returns {Object} `DocumentFragment` instance converted to plain object.
+     * @returns `DocumentFragment` instance converted to plain object.
      */
     toJSON() {
         const json = [];
@@ -244,8 +208,8 @@ export default class DocumentFragment extends TypeCheckable {
      * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
      * Converts `DocumentFragment` children to proper nodes.
      *
-     * @param {Object} json Plain object to be converted to `DocumentFragment`.
-     * @returns {module:engine/model/documentfragment~DocumentFragment} `DocumentFragment` instance created using given plain object.
+     * @param json Plain object to be converted to `DocumentFragment`.
+     * @returns `DocumentFragment` instance created using given plain object.
      */
     static fromJSON(json) {
         const children = [];
@@ -265,8 +229,7 @@ export default class DocumentFragment extends TypeCheckable {
      * {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
      *
      * @internal
-     * @protected
-     * @param {String|module:engine/model/item~Item|Iterable.<String|module:engine/model/item~Item>} items Items to be inserted.
+     * @param items Items to be inserted.
      */
     _appendChild(items) {
         this._insertChild(this.childCount, items);
@@ -276,9 +239,8 @@ export default class DocumentFragment extends TypeCheckable {
      * to this document fragment.
      *
      * @internal
-     * @protected
-     * @param {Number} index Index at which nodes should be inserted.
-     * @param {String|module:engine/model/item~Item|Iterable.<String|module:engine/model/item~Item>} items Items to be inserted.
+     * @param index Index at which nodes should be inserted.
+     * @param items Items to be inserted.
      */
     _insertChild(index, items) {
         const nodes = normalize(items);
@@ -296,10 +258,9 @@ export default class DocumentFragment extends TypeCheckable {
      * and sets {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
      *
      * @internal
-     * @protected
-     * @param {Number} index Index of the first node to remove.
-     * @param {Number} [howMany=1] Number of nodes to remove.
-     * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
+     * @param index Index of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns Array containing removed nodes.
      */
     _removeChildren(index, howMany = 1) {
         const nodes = this._children._removeNodes(index, howMany);
@@ -309,28 +270,14 @@ export default class DocumentFragment extends TypeCheckable {
         return nodes;
     }
 }
-/**
- * Checks whether this object is of the given type.
- *
- *		docFrag.is( 'documentFragment' ); // -> true
- *		docFrag.is( 'model:documentFragment' ); // -> true
- *
- *		docFrag.is( 'view:documentFragment' ); // -> false
- *		docFrag.is( 'element' ); // -> false
- *		docFrag.is( 'node' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// 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 === 'model:documentFragment';
 };
-// Converts strings to Text and non-iterables to arrays.
-//
-// @param {String|module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>}
-// @returns {Iterable.<module:engine/model/node~Node>}
+/**
+ * Converts strings to Text and non-iterables to arrays.
+ */
 function normalize(nodes) {
     // Separate condition because string is iterable.
     if (typeof nodes == 'string') {