@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "35.3.2",
+  "version": "35.4.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -14,10 +14,10 @@
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-build-classic": "^35.3.2",
-    "@ckeditor/ckeditor5-editor-classic": "^35.3.2",
-    "@ckeditor/ckeditor5-core": "^35.3.2",
-    "@ckeditor/ckeditor5-engine": "^35.3.2",
+    "@ckeditor/ckeditor5-build-classic": "^35.4.0",
+    "@ckeditor/ckeditor5-editor-classic": "^35.4.0",
+    "@ckeditor/ckeditor5-core": "^35.4.0",
+    "@ckeditor/ckeditor5-engine": "^35.4.0",
     "@types/lodash-es": "^4.17.6",
     "typescript": "^4.8.4"
   },

package/src/areconnectedthroughproperties.js

@@ -8,10 +8,6 @@
 /* globals EventTarget, Event */
 /**
  * Traverses both structures to find out whether there is a reference that is shared between both structures.
- *
- * @param {Object|Array} obj1
- * @param {Object|Array} obj2
- * @returns {Boolean}
  */
 export default function areConnectedThroughProperties(obj1, obj2) {
     if (obj1 === obj2 && isObject(obj1)) {
@@ -26,9 +22,11 @@ export default function areConnectedThroughProperties(obj1, obj2) {
     }
     return false;
 }
-// Traverses JS structure and stores all sub-nodes, including the head node.
-// It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
-// tree walking. All primitives, functions and built-ins are skipped.
+/**
+ * Traverses JS structure and stores all sub-nodes, including the head node.
+ * It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
+ * tree walking. All primitives, functions and built-ins are skipped.
+ */
 function getSubNodes(head) {
     const nodes = [head];
     // Nodes are stored to prevent infinite looping.

package/src/ckeditorerror.js

@@ -24,57 +24,43 @@ export const DOCUMENTATION_URL = 'https://ckeditor.com/docs/ckeditor5/latest/sup
  * {@link module:utils/ckeditorerror~logError `logError()`}
  * to improve developers experience and let them see the a working editor as soon as possible.
  *
- *		/**
- *		 * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
- *		 *
- *		 * @error plugin-load
- *		 * @param pluginName The name of the plugin that could not be loaded.
- *		 * @param moduleName The name of the module which tried to load this plugin.
- *		 * /
- *		throw new CKEditorError( 'plugin-load', {
- *			pluginName: 'foo',
- *			moduleName: 'bar'
- *		} );
- *
- * @extends Error
+ * ```ts
+ * /**
+ *  * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
+ *  *
+ *  * @error plugin-load
+ *  * @param pluginName The name of the plugin that could not be loaded.
+ *  * @param moduleName The name of the module which tried to load this plugin.
+ *  *\/
+ * throw new CKEditorError( 'plugin-load', {
+ * 	pluginName: 'foo',
+ * 	moduleName: 'bar'
+ * } );
+ * ```
  */
 export default class CKEditorError extends Error {
     /**
      * Creates an instance of the CKEditorError class.
      *
-     * @param {String} errorName The error id in an `error-name` format. A link to this error documentation page will be added
+     * @param errorName The error id in an `error-name` format. A link to this error documentation page will be added
      * to the thrown error's `message`.
-     * @param {Object|null} context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
+     * @param context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
      * is able to determine which editor crashed. It should be an editor instance or a property connected to it. It can be also
      * a `null` value if the editor should not be restarted in case of the error (e.g. during the editor initialization).
      * The error context should be checked using the `areConnectedThroughProperties( editor, context )` utility
      * to check if the object works as the context.
-     * @param {Object} [data] Additional data describing the error. A stringified version of this object
+     * @param data Additional data describing the error. A stringified version of this object
      * will be appended to the error message, so the data are quickly visible in the console. The original
      * data object will also be later available under the {@link #data} property.
      */
     constructor(errorName, context, data) {
         super(getErrorMessage(errorName, data));
-        /**
-         * @type {String}
-         */
         this.name = 'CKEditorError';
-        /**
-         * A context of the error by which the Watchdog is able to determine which editor crashed.
-         *
-         * @type {Object|null}
-         */
         this.context = context;
-        /**
-         * The additional error data passed to the constructor. Undefined if none was passed.
-         *
-         * @type {Object|undefined}
-         */
         this.data = data;
     }
     /**
      * Checks if the error is of the `CKEditorError` type.
-     * @returns {Boolean}
      */
     is(type) {
         return type === 'CKEditorError';
@@ -84,9 +70,8 @@ export default class CKEditorError extends Error {
      * It is useful when combined with the {@link module:watchdog/watchdog~Watchdog} feature, which can restart the editor in case
      * of a {@link module:utils/ckeditorerror~CKEditorError} error.
      *
-     * @static
-     * @param {Error} err The error to rethrow.
-     * @param {Object} context An object connected through properties with the editor instance. This context will be used
+     * @param err The error to rethrow.
+     * @param context An object connected through properties with the editor instance. This context will be used
      * by the watchdog to verify which editor should be restarted.
      */
     static rethrowUnexpectedError(err, context) {
@@ -113,20 +98,22 @@ export default class CKEditorError extends Error {
  * Logs a warning to the console with a properly formatted message and adds a link to the documentation.
  * Use whenever you want to log a warning to the console.
  *
- *		/**
- *		 * There was a problem processing the configuration of the toolbar. The item with the given
- *		 * name does not exist, so it was omitted when rendering the toolbar.
- *		 *
- *		 * @error toolbarview-item-unavailable
- *		 * @param {String} name The name of the component.
- *		 * /
- *		logWarning( 'toolbarview-item-unavailable', { name } );
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ * logWarning( 'toolbarview-item-unavailable', { name } );
+ * ```
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
  * a warning or an error to the console.
  *
- * @param {String} errorName The error name to be logged.
- * @param {Object} [data] Additional data to be logged.
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
  */
 export function logWarning(errorName, data) {
     console.warn(...formatConsoleArguments(errorName, data));
@@ -135,39 +122,36 @@ export function logWarning(errorName, data) {
  * Logs an error to the console with a properly formatted message and adds a link to the documentation.
  * Use whenever you want to log an error to the console.
  *
- *		/**
- *		 * There was a problem processing the configuration of the toolbar. The item with the given
- *		 * name does not exist, so it was omitted when rendering the toolbar.
- *		 *
- *		 * @error toolbarview-item-unavailable
- *		 * @param {String} name The name of the component.
- *		 * /
- *		 logError( 'toolbarview-item-unavailable', { name } );
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ *  logError( 'toolbarview-item-unavailable', { name } );
+ * ```
  *
  * **Note**: In most cases logging a warning using {@link module:utils/ckeditorerror~logWarning} is enough.
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
  *
- * @param {String} errorName The error name to be logged.
- * @param {Object} [data] Additional data to be logged.
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
  */
 export function logError(errorName, data) {
     console.error(...formatConsoleArguments(errorName, data));
 }
-// Returns formatted link to documentation message.
-//
-// @private
-// @param {String} errorName
-// @returns {string}
+/**
+ * Returns formatted link to documentation message.
+ */
 function getLinkToDocumentationMessage(errorName) {
     return `\nRead more: ${DOCUMENTATION_URL}#error-${errorName}`;
 }
-// Returns formatted error message.
-//
-// @private
-// @param {String} errorName
-// @param {Object} [data]
-// @returns {string}
+/**
+ * Returns formatted error message.
+ */
 function getErrorMessage(errorName, data) {
     const processedObjects = new WeakSet();
     const circularReferencesReplacer = (key, value) => {
@@ -183,12 +167,9 @@ function getErrorMessage(errorName, data) {
     const documentationLink = getLinkToDocumentationMessage(errorName);
     return errorName + stringifiedData + documentationLink;
 }
-// Returns formatted console error arguments.
-//
-// @private
-// @param {String} errorName
-// @param {Object} [data]
-// @returns {Array}
+/**
+ * Returns formatted console error arguments.
+ */
 function formatConsoleArguments(errorName, data) {
     const documentationMessage = getLinkToDocumentationMessage(errorName);
     return data ? [errorName, data, documentationMessage] : [errorName, documentationMessage];

package/src/collection.js

@@ -5,7 +5,7 @@
 /**
  * @module utils/collection
  */
-import { Emitter } from './emittermixin';
+import EmitterMixin from './emittermixin';
 import CKEditorError from './ckeditorerror';
 import uid from './uid';
 import isIterable from './isiterable';
@@ -19,45 +19,9 @@ import isIterable from './isiterable';
  * By default an item in the collection is identified by its `id` property. The name of the identifier can be
  * configured through the constructor of the collection.
  *
- * @mixes module:utils/emittermixin~EmitterMixin
+ * @typeParam T The type of the collection element.
  */
-export default class Collection extends Emitter {
-    /**
-     * Creates a new Collection instance.
-     *
-     * You can provide an iterable of initial items the collection will be created with:
-     *
-     *		const collection = new Collection( [ { id: 'John' }, { id: 'Mike' } ] );
-     *
-     *		console.log( collection.get( 0 ) ); // -> { id: 'John' }
-     *		console.log( collection.get( 1 ) ); // -> { id: 'Mike' }
-     *		console.log( collection.get( 'Mike' ) ); // -> { id: 'Mike' }
-     *
-     * Or you can first create a collection and then add new items using the {@link #add} method:
-     *
-     *		const collection = new Collection();
-     *
-     *		collection.add( { id: 'John' } );
-     *		console.log( collection.get( 0 ) ); // -> { id: 'John' }
-     *
-     * Whatever option you choose, you can always pass a configuration object as the last argument
-     * of the constructor:
-     *
-     *		const emptyCollection = new Collection( { idProperty: 'name' } );
-     *		emptyCollection.add( { name: 'John' } );
-     *		console.log( collection.get( 'John' ) ); // -> { name: 'John' }
-     *
-     *		const nonEmptyCollection = new Collection( [ { name: 'John' } ], { idProperty: 'name' } );
-     *		nonEmptyCollection.add( { name: 'George' } );
-     *		console.log( collection.get( 'George' ) ); // -> { name: 'George' }
-     *		console.log( collection.get( 'John' ) ); // -> { name: 'John' }
-     *
-     * @param {Iterable.<Object>|Object} [initialItemsOrOptions] The initial items of the collection or
-     * the options object.
-     * @param {Object} [options={}] The options object, when the first argument is an array of initial items.
-     * @param {String} [options.idProperty='id'] The name of the property which is used to identify an item.
-     * Items that do not have such a property will be assigned one when added to the collection.
-     */
+export default class Collection extends EmitterMixin() {
     constructor(initialItemsOrOptions = {}, options = {}) {
         super();
         const hasInitialItems = isIterable(initialItemsOrOptions);
@@ -80,24 +44,18 @@ export default class Collection extends Emitter {
     }
     /**
      * The number of items available in the collection.
-     *
-     * @member {Number} #length
      */
     get length() {
         return this._items.length;
     }
     /**
      * Returns the first item from the collection or null when collection is empty.
-     *
-     * @returns {Object|null} The first item or `null` if collection is empty.
      */
     get first() {
         return this._items[0] || null;
     }
     /**
      * Returns the last item from the collection or null when collection is empty.
-     *
-     * @returns {Object|null} The last item or `null` if collection is empty.
      */
     get last() {
         return this._items[this.length - 1] || null;
@@ -107,9 +65,8 @@ export default class Collection extends Emitter {
      *
      * If the item does not have an id, then it will be automatically generated and set on the item.
      *
-     * @chainable
-     * @param {Object} item
-     * @param {Number} [index] The position of the item in the collection. The item
+     * @param item
+     * @param index The position of the item in the collection. The item
      * is pushed to the collection when `index` not specified.
      * @fires add
      * @fires change
@@ -122,9 +79,8 @@ export default class Collection extends Emitter {
      *
      * Any item not containing an id will get an automatically generated one.
      *
-     * @chainable
-     * @param {Iterable.<Object>} items
-     * @param {Number} [index] The position of the insertion. Items will be appended if no `index` is specified.
+     * @param items
+     * @param index The position of the insertion. Items will be appended if no `index` is specified.
      * @fires add
      * @fires change
      */
@@ -160,8 +116,8 @@ export default class Collection extends Emitter {
     /**
      * Gets an item by its ID or index.
      *
-     * @param {String|Number} idOrIndex The item ID or index in the collection.
-     * @returns {Object|null} The requested item or `null` if such item does not exist.
+     * @param idOrIndex The item ID or index in the collection.
+     * @returns The requested item or `null` if such item does not exist.
      */
     get(idOrIndex) {
         let item;
@@ -184,8 +140,8 @@ export default class Collection extends Emitter {
     /**
      * Returns a Boolean indicating whether the collection contains an item.
      *
-     * @param {Object|String} itemOrId The item or its ID in the collection.
-     * @returns {Boolean} `true` if the collection contains the item, `false` otherwise.
+     * @param itemOrId The item or its ID in the collection.
+     * @returns `true` if the collection contains the item, `false` otherwise.
      */
     has(itemOrId) {
         if (typeof itemOrId == 'string') {
@@ -201,8 +157,8 @@ export default class Collection extends Emitter {
      * Gets an index of an item in the collection.
      * When an item is not defined in the collection, the index will equal -1.
      *
-     * @param {Object|String} itemOrId The item or its ID in the collection.
-     * @returns {Number} The index of a given item.
+     * @param itemOrId The item or its ID in the collection.
+     * @returns The index of a given item.
      */
     getIndex(itemOrId) {
         let item;
@@ -217,8 +173,8 @@ export default class Collection extends Emitter {
     /**
      * Removes an item from the collection.
      *
-     * @param {Object|Number|String} subject The item to remove, its ID or index in the collection.
-     * @returns {Object} The removed item.
+     * @param subject The item to remove, its ID or index in the collection.
+     * @returns The removed item.
      * @fires remove
      * @fires change
      */
@@ -234,11 +190,10 @@ export default class Collection extends Emitter {
     /**
      * Executes the callback for each item in the collection and composes an array or values returned by this callback.
      *
-     * @param {Function} callback
-     * @param {Object} callback.item
-     * @param {Number} callback.index
-     * @param {Object} [ctx] Context in which the `callback` will be called.
-     * @returns {Array} The result of mapping.
+     * @typeParam U The result type of the callback.
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The result of mapping.
      */
     map(callback, ctx) {
         return this._items.map(callback, ctx);
@@ -246,11 +201,9 @@ export default class Collection extends Emitter {
     /**
      * Finds the first item in the collection for which the `callback` returns a true value.
      *
-     * @param {Function} callback
-     * @param {Object} callback.item
-     * @param {Number} callback.index
-     * @param {Object} [ctx] Context in which the `callback` will be called.
-     * @returns {Object|undefined} The item for which `callback` returned a true value.
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The item for which `callback` returned a true value.
      */
     find(callback, ctx) {
         return this._items.find(callback, ctx);
@@ -258,11 +211,9 @@ export default class Collection extends Emitter {
     /**
      * Returns an array with items for which the `callback` returned a true value.
      *
-     * @param {Function} callback
-     * @param {Object} callback.item
-     * @param {Number} callback.index
-     * @param {Object} [ctx] Context in which the `callback` will be called.
-     * @returns {Array} The array with matching items.
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The array with matching items.
      */
     filter(callback, ctx) {
         return this._items.filter(callback, ctx);
@@ -294,96 +245,111 @@ export default class Collection extends Emitter {
      *
      * The binding can be a simple factory:
      *
-     *		class FactoryClass {
-     *			constructor( data ) {
-     *				this.label = data.label;
-     *			}
-     *		}
+     * ```ts
+     * class FactoryClass {
+     * 	public label: string;
      *
-     *		const source = new Collection( { idProperty: 'label' } );
-     *		const target = new Collection();
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
      *
-     *		target.bindTo( source ).as( FactoryClass );
+     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
+     * const target = new Collection<FactoryClass>();
      *
-     *		source.add( { label: 'foo' } );
-     *		source.add( { label: 'bar' } );
+     * target.bindTo( source ).as( FactoryClass );
      *
-     *		console.log( target.length ); // 2
-     *		console.log( target.get( 1 ).label ); // 'bar'
+     * source.add( { label: 'foo' } );
+     * source.add( { label: 'bar' } );
      *
-     *		source.remove( 0 );
-     *		console.log( target.length ); // 1
-     *		console.log( target.get( 0 ).label ); // 'bar'
+     * console.log( target.length ); // 2
+     * console.log( target.get( 1 ).label ); // 'bar'
+     *
+     * source.remove( 0 );
+     * console.log( target.length ); // 1
+     * console.log( target.get( 0 ).label ); // 'bar'
+     * ```
      *
      * or the factory driven by a custom callback:
      *
-     *		class FooClass {
-     *			constructor( data ) {
-     *				this.label = data.label;
-     *			}
-     *		}
+     * ```ts
+     * class FooClass {
+     * 	public label: string;
+     *
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
      *
-     *		class BarClass {
-     *			constructor( data ) {
-     *				this.label = data.label;
-     *			}
-     *		}
+     * class BarClass {
+     * 	public label: string;
      *
-     *		const source = new Collection( { idProperty: 'label' } );
-     *		const target = new Collection();
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
      *
-     *		target.bindTo( source ).using( ( item ) => {
-     *			if ( item.label == 'foo' ) {
-     *				return new FooClass( item );
-     *			} else {
-     *				return new BarClass( item );
-     *			}
-     *		} );
+     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
+     * const target = new Collection<FooClass | BarClass>();
      *
-     *		source.add( { label: 'foo' } );
-     *		source.add( { label: 'bar' } );
+     * target.bindTo( source ).using( ( item ) => {
+     * 	if ( item.label == 'foo' ) {
+     * 		return new FooClass( item );
+     * 	} else {
+     * 		return new BarClass( item );
+     * 	}
+     * } );
      *
-     *		console.log( target.length ); // 2
-     *		console.log( target.get( 0 ) instanceof FooClass ); // true
-     *		console.log( target.get( 1 ) instanceof BarClass ); // true
+     * source.add( { label: 'foo' } );
+     * source.add( { label: 'bar' } );
+     *
+     * console.log( target.length ); // 2
+     * console.log( target.get( 0 ) instanceof FooClass ); // true
+     * console.log( target.get( 1 ) instanceof BarClass ); // true
+     * ```
      *
      * or the factory out of property name:
      *
-     *		const source = new Collection( { idProperty: 'label' } );
-     *		const target = new Collection();
+     * ```ts
+     * const source = new Collection<{ nested: { value: string } }>();
+     * const target = new Collection<{ value: string }>();
      *
-     *		target.bindTo( source ).using( 'label' );
+     * target.bindTo( source ).using( 'nested' );
      *
-     *		source.add( { label: { value: 'foo' } } );
-     *		source.add( { label: { value: 'bar' } } );
+     * source.add( { nested: { value: 'foo' } } );
+     * source.add( { nested: { value: 'bar' } } );
      *
-     *		console.log( target.length ); // 2
-     *		console.log( target.get( 0 ).value ); // 'foo'
-     *		console.log( target.get( 1 ).value ); // 'bar'
+     * console.log( target.length ); // 2
+     * console.log( target.get( 0 ).value ); // 'foo'
+     * console.log( target.get( 1 ).value ); // 'bar'
+     * ```
      *
-     * It's possible to skip specified items by returning falsy value:
+     * It's possible to skip specified items by returning null value:
      *
-     *		const source = new Collection();
-     *		const target = new Collection();
+     * ```ts
+     * const source = new Collection<{ hidden: boolean }>();
+     * const target = new Collection<{ hidden: boolean }>();
      *
-     *		target.bindTo( source ).using( item => {
-     *			if ( item.hidden ) {
-     *				return null;
-     *			}
+     * target.bindTo( source ).using( item => {
+     * 	if ( item.hidden ) {
+     * 		return null;
+     * 	}
      *
-     *			return item;
-     *		} );
+     * 	return item;
+     * } );
      *
-     *		source.add( { hidden: true } );
-     *		source.add( { hidden: false } );
+     * source.add( { hidden: true } );
+     * source.add( { hidden: false } );
      *
-     *		console.log( source.length ); // 2
-     *		console.log( target.length ); // 1
+     * console.log( source.length ); // 2
+     * console.log( target.length ); // 1
+     * ```
      *
      * **Note**: {@link #clear} can be used to break the binding.
      *
-     * @param {module:utils/collection~Collection} externalCollection A collection to be bound.
-     * @returns {module:utils/collection~CollectionBindToChain} The binding chain object.
+     * @typeParam S The type of `externalCollection` element.
+     * @param externalCollection A collection to be bound.
+     * @returns The binding chain object.
      */
     bindTo(externalCollection) {
         if (this._bindToCollection) {
@@ -412,14 +378,11 @@ export default class Collection extends Emitter {
     /**
      * Finalizes and activates a binding initiated by {#bindTo}.
      *
-     * @private
-     * @param {Function} factory A function which produces collection items.
+     * @param factory A function which produces collection items.
      */
     _setUpBindToBinding(factory) {
         const externalCollection = this._bindToCollection;
         // Adds the item to the collection once a change has been done to the external collection.
-        //
-        // @private
         const addItem = (evt, externalItem, index) => {
             const isExternalBoundToThis = externalCollection._bindToCollection == this;
             const externalItemBound = externalCollection._bindToInternalToExternalMap.get(externalItem);
@@ -523,9 +486,7 @@ export default class Collection extends Emitter {
      *
      * The method will generate new id and assign it to the `item` if it doesn't have any.
      *
-     * @private
-     * @param {Object} item Item to be added.
-     * @returns {String}
+     * @param item Item to be added.
      */
     _getItemIdBeforeAdding(item) {
         const idProperty = this._idProperty;
@@ -559,9 +520,8 @@ export default class Collection extends Emitter {
      *
      * In contrast this method **does not** fire the {@link #event:change} event.
      *
-     * @private
-     * @param {Object|Number|String} subject The item to remove, its id or index in the collection.
-     * @returns {Array} Returns an array with the removed item and its index.
+     * @param subject The item to remove, its id or index in the collection.
+     * @returns Returns an array with the removed item and its index.
      * @fires remove
      */
     _remove(subject) {
@@ -608,8 +568,6 @@ export default class Collection extends Emitter {
     }
     /**
      * Iterable interface.
-     *
-     * @returns {Iterator.<*>}
      */
     [Symbol.iterator]() {
         return this._items[Symbol.iterator]();