@ckeditor/ckeditor5-engine 35.4.0 → 36.0.0

package/src/model/text.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,18 +27,12 @@ export default class Text extends Node {
      * **Note:** Constructor of this class shouldn't be used directly in the code.
      * Use the {@link module:engine/model/writer~Writer#createText} method instead.
      *
-     * @protected
-     * @param {String} [data] Node's text.
-     * @param {Object} [attrs] Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     * @internal
+     * @param data Node's text.
+     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
      */
     constructor(data, attrs) {
         super(attrs);
-        /**
-         * Text data contained in this text node.
-         *
-         * @protected
-         * @type {String}
-         */
         this._data = data || '';
     }
     /**
@@ -49,9 +43,6 @@ export default class Text extends Node {
     }
     /**
      * Returns a text data contained in the node.
-     *
-     * @readonly
-     * @type {String}
      */
     get data() {
         return this._data;
@@ -59,7 +50,7 @@ export default class Text extends Node {
     /**
      * Converts `Text` instance to plain object and returns it.
      *
-     * @returns {Object} `Text` instance converted to plain object.
+     * @returns`Text` instance converted to plain object.
      */
     toJSON() {
         const json = super.toJSON();
@@ -70,8 +61,7 @@ export default class Text extends Node {
      * Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
      *
      * @internal
-     * @protected
-     * @returns {module:engine/model/text~Text} `Text` instance created using given plain object.
+     * @returns `Text` instance created using given plain object.
      */
     _clone() {
         return new Text(this.data, this.getAttributes());
@@ -79,32 +69,15 @@ export default class Text extends Node {
     /**
      * Creates a `Text` instance from given plain object (i.e. parsed JSON string).
      *
-     * @param {Object} json Plain object to be converted to `Text`.
-     * @returns {module:engine/model/text~Text} `Text` instance created using given plain object.
+     * @param json Plain object to be converted to `Text`.
+     * @returns `Text` instance created using given plain object.
      */
     static fromJSON(json) {
         return new Text(json.data, json.attributes);
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		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
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * **Note:** Until version 20.0.0 this method wasn't accepting `'$text'` type. The legacy `'text'` type is still
- * accepted for backward compatibility.
- *
- * @param {String} type Type to check.
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Text.prototype.is = function (type) {
     return type === '$text' || type === 'model:$text' ||
         // This are legacy values kept for backward compatibility.

package/src/model/textproxy.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
  */
 /**
@@ -41,21 +41,14 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Creates a text proxy.
      *
-     * @protected
-     * @param {module:engine/model/text~Text} textNode Text node which part is represented by this text proxy.
-     * @param {Number} offsetInText Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy
+     * @internal
+     * @param textNode Text node which part is represented by this text proxy.
+     * @param offsetInText Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy
      * starts.
-     * @param {Number} length Text proxy length, that is how many text node's characters, starting from `offsetInText` it represents.
-     * @constructor
+     * @param length Text proxy length, that is how many text node's characters, starting from `offsetInText` it represents.
      */
     constructor(textNode, offsetInText, length) {
         super();
-        /**
-         * Text node which part is represented by this text proxy.
-         *
-         * @readonly
-         * @member {module:engine/model/text~Text}
-         */
         this.textNode = textNode;
         if (offsetInText < 0 || offsetInText > textNode.offsetSize) {
             /**
@@ -73,27 +66,13 @@ export default class TextProxy extends TypeCheckable {
              */
             throw new CKEditorError('model-textproxy-wrong-length', this);
         }
-        /**
-         * Text data represented by this text proxy.
-         *
-         * @readonly
-         * @member {String}
-         */
         this.data = textNode.data.substring(offsetInText, offsetInText + length);
-        /**
-         * Offset in {@link module:engine/model/textproxy~TextProxy#textNode text node} from which the text proxy starts.
-         *
-         * @readonly
-         * @member {Number}
-         */
         this.offsetInText = offsetInText;
     }
     /**
      * Offset at which this text proxy starts in it's parent.
      *
      * @see module:engine/model/node~Node#startOffset
-     * @readonly
-     * @type {Number|null}
      */
     get startOffset() {
         return this.textNode.startOffset !== null ? this.textNode.startOffset + this.offsetInText : null;
@@ -102,8 +81,6 @@ export default class TextProxy extends TypeCheckable {
      * Offset size of this text proxy. Equal to the number of characters represented by the text proxy.
      *
      * @see module:engine/model/node~Node#offsetSize
-     * @readonly
-     * @type {Number}
      */
     get offsetSize() {
         return this.data.length;
@@ -112,8 +89,6 @@ export default class TextProxy extends TypeCheckable {
      * Offset at which this text proxy ends in it's parent.
      *
      * @see module:engine/model/node~Node#endOffset
-     * @readonly
-     * @type {Number|null}
      */
     get endOffset() {
         return this.startOffset !== null ? this.startOffset + this.offsetSize : null;
@@ -125,27 +100,18 @@ export default class TextProxy extends TypeCheckable {
      * This is `false` when text proxy starts at the very beginning of {@link module:engine/model/textproxy~TextProxy#textNode textNode}
      * ({@link module:engine/model/textproxy~TextProxy#offsetInText offsetInText} equals `0`) and text proxy sizes is equal to
      * text node size.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isPartial() {
         return this.offsetSize !== this.textNode.offsetSize;
     }
     /**
      * Parent of this text proxy, which is same as parent of text node represented by this text proxy.
-     *
-     * @readonly
-     * @type {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment|null}
      */
     get parent() {
         return this.textNode.parent;
     }
     /**
      * Root of this text proxy, which is same as root of text node represented by this text proxy.
-     *
-     * @readonly
-     * @type {module:engine/model/node~Node|module:engine/model/documentfragment~DocumentFragment}
      */
     get root() {
         return this.textNode.root;
@@ -154,7 +120,6 @@ export default class TextProxy extends TypeCheckable {
      * Gets path to this text proxy.
      *
      * @see module:engine/model/node~Node#getPath
-     * @returns {Array.<Number>}
      */
     getPath() {
         const path = this.textNode.getPath();
@@ -166,11 +131,11 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Returns ancestors array of this text proxy.
      *
-     * @param {Object} options Options object.
-     * @param {Boolean} [options.includeSelf=false] When set to `true` this text proxy will be also included in parent's array.
-     * @param {Boolean} [options.parentFirst=false] When set to `true`, array will be sorted from text proxy parent to root element,
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` this text proxy will be also included in parent's array.
+     * @param options.parentFirst When set to `true`, array will be sorted from text proxy parent to root element,
      * otherwise root element will be the first item in the array.
-     * @returns {Array} Array with ancestors.
+     * @returns Array with ancestors.
      */
     getAncestors(options = {}) {
         const ancestors = [];
@@ -184,8 +149,8 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Checks if this text proxy has an attribute for given key.
      *
-     * @param {String} key Key of attribute to check.
-     * @returns {Boolean} `true` if attribute with given key is set on text proxy, `false` otherwise.
+     * @param key Key of attribute to check.
+     * @returns `true` if attribute with given key is set on text proxy, `false` otherwise.
      */
     hasAttribute(key) {
         return this.textNode.hasAttribute(key);
@@ -193,8 +158,8 @@ export default class TextProxy extends TypeCheckable {
     /**
      * Gets an attribute value for given key or `undefined` if that attribute is not set on text proxy.
      *
-     * @param {String} key Key of attribute to look for.
-     * @returns {*} Attribute value or `undefined`.
+     * @param key Key of attribute to look for.
+     * @returns Attribute value or `undefined`.
      */
     getAttribute(key) {
         return this.textNode.getAttribute(key);
@@ -204,38 +169,19 @@ export default class TextProxy extends TypeCheckable {
      * items. First one is attribute key and second is attribute value.
      *
      * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
-     *
-     * @returns {Iterable.<*>}
      */
     getAttributes() {
         return this.textNode.getAttributes();
     }
     /**
      * Returns iterator that iterates over this node's attribute keys.
-     *
-     * @returns {Iterable.<String>}
      */
     getAttributeKeys() {
         return this.textNode.getAttributeKeys();
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		textProxy.is( '$textProxy' ); // -> true
- *		textProxy.is( 'model:$textProxy' ); // -> true
- *
- *		textProxy.is( 'view:$textProxy' ); // -> false
- *		textProxy.is( 'range' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * **Note:** Until version 20.0.0 this method wasn't accepting `'$textProxy'` type. The legacy `'textProxt'` type is still
- * accepted for backward compatibility.
- *
- * @param {String} type Type to check.
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 TextProxy.prototype.is = function (type) {
     return type === '$textProxy' || type === 'model:$textProxy' ||
         // This are legacy values kept for backward compatibility.

package/src/model/treewalker.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
  */
 /**
@@ -17,23 +17,10 @@ export default class TreeWalker {
     /**
      * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
      *
-     * @constructor
-     * @param {Object} [options={}] Object with configuration.
-     * @param {'forward'|'backward'} [options.direction='forward'] Walking direction.
-     * @param {module:engine/model/range~Range|null} [options.boundaries=null] Range to define boundaries of the iterator.
-     * @param {module:engine/model/position~Position} [options.startPosition] Starting position.
-     * @param {Boolean} [options.singleCharacters=false] Flag indicating whether all consecutive characters with the same attributes
-     * should be returned one by one as multiple {@link module:engine/model/textproxy~TextProxy} (`true`) objects or as one
-     * {@link module:engine/model/textproxy~TextProxy} (`false`).
-     * @param {Boolean} [options.shallow=false] Flag indicating whether iterator should enter elements or not. If the
-     * iterator is shallow child nodes of any iterated node will not be returned along with `elementEnd` tag.
-     * @param {Boolean} [options.ignoreElementEnd=false] Flag indicating whether iterator should ignore `elementEnd`
-     * tags. If the option is true walker will not return a parent node of start position. If this option is `true`
-     * each {@link module:engine/model/element~Element} will be returned once, while if the option is `false` they might be returned
-     * twice: for `'elementStart'` and `'elementEnd'`.
+     * @param options Object with configuration.
      */
-    constructor(options = {}) {
-        if (!options.boundaries && !options.startPosition) {
+    constructor(options) {
+        if (!options || (!options.boundaries && !options.startPosition)) {
             /**
              * Neither boundaries nor starting position of a `TreeWalker` have been defined.
              *
@@ -50,34 +37,8 @@ export default class TreeWalker {
              */
             throw new CKEditorError('model-tree-walker-unknown-direction', options, { direction });
         }
-        /**
-         * Walking direction. Defaults `'forward'`.
-         *
-         * @readonly
-         * @member {'backward'|'forward'} module:engine/model/treewalker~TreeWalker#direction
-         */
         this.direction = direction;
-        /**
-         * Iterator boundaries.
-         *
-         * When the iterator is walking `'forward'` on the end of boundary or is walking `'backward'`
-         * on the start of boundary, then `{ done: true }` is returned.
-         *
-         * If boundaries are not defined they are set before first and after last child of the root node.
-         *
-         * @readonly
-         * @member {module:engine/model/range~Range|null} module:engine/model/treewalker~TreeWalker#boundaries
-         */
         this.boundaries = options.boundaries || null;
-        /**
-         * 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.
-         *
-         * @readonly
-         * @member {module:engine/model/position~Position} module:engine/model/treewalker~TreeWalker#position
-         */
         if (options.startPosition) {
             this.position = options.startPosition.clone();
         }
@@ -86,53 +47,11 @@ export default class TreeWalker {
         }
         // Reset position stickiness in case it was set to other value, as the stickiness is kept after cloning.
         this.position.stickiness = 'toNone';
-        /**
-         * Flag indicating whether all consecutive characters with the same attributes should be
-         * returned as one {@link module:engine/model/textproxy~TextProxy} (`true`) or one by one (`false`).
-         *
-         * @readonly
-         * @member {Boolean} module:engine/model/treewalker~TreeWalker#singleCharacters
-         */
         this.singleCharacters = !!options.singleCharacters;
-        /**
-         * Flag indicating whether iterator should enter elements or not. If the iterator is shallow child nodes of any
-         * iterated node will not be returned along with `elementEnd` tag.
-         *
-         * @readonly
-         * @member {Boolean} module:engine/model/treewalker~TreeWalker#shallow
-         */
         this.shallow = !!options.shallow;
-        /**
-         * Flag indicating whether iterator should ignore `elementEnd` tags. If the option is true walker will not
-         * return a parent node of the start position. If this option is `true` each {@link module:engine/model/element~Element} will
-         * be returned once, while if the option is `false` they might be returned twice:
-         * for `'elementStart'` and `'elementEnd'`.
-         *
-         * @readonly
-         * @member {Boolean} module:engine/model/treewalker~TreeWalker#ignoreElementEnd
-         */
         this.ignoreElementEnd = !!options.ignoreElementEnd;
-        /**
-         * Start boundary cached for optimization purposes.
-         *
-         * @private
-         * @member {module:engine/model/element~Element} module:engine/model/treewalker~TreeWalker#_boundaryStartParent
-         */
         this._boundaryStartParent = this.boundaries ? this.boundaries.start.parent : null;
-        /**
-         * End boundary cached for optimization purposes.
-         *
-         * @private
-         * @member {module:engine/model/element~Element} module:engine/model/treewalker~TreeWalker#_boundaryEndParent
-         */
         this._boundaryEndParent = this.boundaries ? this.boundaries.end.parent : null;
-        /**
-         * Parent of the most recently visited node. Cached for optimization purposes.
-         *
-         * @private
-         * @member {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment}
-         * module:engine/model/treewalker~TreeWalker#_visitedParent
-         */
         this._visitedParent = this.position.parent;
     }
     /**
@@ -148,11 +67,13 @@ export default class TreeWalker {
      *
      * For example:
      *
-     * 		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.
+     * ```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 {Function} skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * @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) {
@@ -169,8 +90,6 @@ export default class TreeWalker {
     }
     /**
      * Gets the next tree walker's value.
-     *
-     * @returns {IteratorResult} Next tree walker's value.
      */
     next() {
         if (this.direction == 'forward') {
@@ -182,11 +101,6 @@ export default class TreeWalker {
     }
     /**
      * Makes a step forward in model. Moves the {@link #position} to the next position and returns the encountered value.
-     *
-     * @private
-     * @returns {Object}
-     * @returns {Boolean} return.done True if iterator is done.
-     * @returns {IteratorResult} return.value Information about taken step.
      */
     _next() {
         const previousPosition = this.position;
@@ -250,11 +164,6 @@ export default class TreeWalker {
     }
     /**
      * Makes a step backward in model. Moves the {@link #position} to the previous position and returns the encountered value.
-     *
-     * @private
-     * @returns {Object}
-     * @returns {Boolean} return.done True if iterator is done.
-     * @returns {IteratorResulte} return.value Information about taken step.
      */
     _previous() {
         const previousPosition = this.position;

package/src/model/typecheckable.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
  */
 export default class TypeCheckable {

package/src/model/utils/autoparagraphing.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
  */
 /**
@@ -8,9 +8,9 @@
 /**
  * Fixes all empty roots.
  *
- * @protected
- * @param {module:engine/model/writer~Writer} writer The model writer.
- * @returns {Boolean} `true` if any change has been applied, `false` otherwise.
+ * @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;
@@ -33,10 +33,9 @@ export function autoParagraphEmptyRoots(writer) {
  * Checks if the given node wrapped with a paragraph would be accepted by the schema in the given position.
  *
  * @internal
- * @protected
- * @param {module:engine/model/position~Position} position The position at which to check.
- * @param {module:engine/model/node~Node|String} nodeOrType The child node or child type to check.
- * @param {module:engine/model/schema~Schema} schema A schema instance used for element validation.
+ * @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);
@@ -53,10 +52,10 @@ export function isParagraphable(position, nodeOrType, schema) {
 /**
  * Inserts a new paragraph at the given position and returns a position inside that paragraph.
  *
- * @protected
- * @param {module:engine/model/position~Position} position The position where a paragraph should be inserted.
- * @param {module:engine/model/writer~Writer} writer The model writer.
- * @returns {module:engine/model/position~Position} Position inside the created 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');