@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/observablemixin.js

@@ -2,11 +2,11 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-/* eslint-disable @typescript-eslint/unified-signatures, new-cap */
+/* eslint-disable @typescript-eslint/unified-signatures */
 /**
  * @module utils/observablemixin
  */
-import { Emitter } from './emittermixin';
+import EmitterMixin from './emittermixin';
 import CKEditorError from './ckeditorerror';
 import { isObject } from 'lodash-es';
 const observablePropertiesSymbol = Symbol('observableProperties');
@@ -14,20 +14,11 @@ const boundObservablesSymbol = Symbol('boundObservables');
 const boundPropertiesSymbol = Symbol('boundProperties');
 const decoratedMethods = Symbol('decoratedMethods');
 const decoratedOriginal = Symbol('decoratedOriginal');
-/**
- * A mixin that injects the "observable properties" and data binding functionality described in the
- * {@link ~Observable} interface.
- *
- * Read more about the concept of observables in the:
- * * {@glink framework/guides/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
- * section of the {@glink framework/guides/architecture/core-editor-architecture Core editor architecture} guide,
- * * {@glink framework/guides/deep-dive/observables Observables deep dive} guide.
- *
- * @mixin ObservableMixin
- * @mixes module:utils/emittermixin~EmitterMixin
- * @implements module:utils/observablemixin~Observable
- */
+const defaultObservableClass = ObservableMixin(EmitterMixin());
 export default function ObservableMixin(base) {
+    if (!base) {
+        return defaultObservableClass;
+    }
     class Mixin extends base {
         set(name, value) {
             // If the first parameter is an Object, iterate over its properties.
@@ -43,15 +34,17 @@ export default function ObservableMixin(base) {
                 /**
                  * Cannot override an existing property.
                  *
-                 * This error is thrown when trying to {@link ~Observable#set set} a property with
+                 * This error is thrown when trying to {@link module:utils/observablemixin~Observable#set set} a property with
                  * a name of an already existing property. For example:
                  *
-                 *		let observable = new Model();
-                 *		observable.property = 1;
-                 *		observable.set( 'property', 2 );			// throws
+                 * ```ts
+                 * let observable = new Model();
+                 * observable.property = 1;
+                 * observable.set( 'property', 2 );			// throws
                  *
-                 *		observable.set( 'property', 1 );
-                 *		observable.set( 'property', 2 );			// ok, because this is an existing property.
+                 * observable.set( 'property', 1 );
+                 * observable.set( 'property', 2 );			// ok, because this is an existing property.
+                 * ```
                  *
                  * @error observable-set-cannot-override
                  */
@@ -112,24 +105,11 @@ export default function ObservableMixin(base) {
                 }
             });
             const bindings = new Map();
-            // @typedef {Object} Binding
-            // @property {Array} property Property which is bound.
-            // @property {Array} to Array of observable–property components of the binding (`{ observable: ..., property: .. }`).
-            // @property {Array} callback A function which processes `to` components.
             bindProperties.forEach(a => {
                 const binding = { property: a, to: [] };
                 boundProperties.set(a, binding);
                 bindings.set(a, binding);
             });
-            // @typedef {Object} BindChain
-            // @property {Function} to See {@link ~ObservableMixin#_bindTo}.
-            // @property {Function} toMany See {@link ~ObservableMixin#_bindToMany}.
-            // @property {module:utils/observablemixin~Observable} _observable The observable which initializes the binding.
-            // @property {Array} _bindProperties Array of `_observable` properties to be bound.
-            // @property {Array} _to Array of `to()` observable–properties (`{ observable: toObservable, properties: ...toProperties }`).
-            // @property {Map} _bindings Stores bindings to be kept in
-            // {@link ~ObservableMixin#_boundProperties}/{@link ~ObservableMixin#_boundObservables}
-            // initiated in this binding chain.
             return {
                 to: bindTo,
                 toMany: bindToMany,
@@ -222,12 +202,11 @@ export default function ObservableMixin(base) {
                 }
                 delete this[decoratedMethods];
             }
-            Emitter.prototype.stopListening.call(this, emitter, event, callback);
+            super.stopListening(emitter, event, callback);
         }
     }
     return Mixin;
 }
-export const Observable = ObservableMixin(Emitter);
 // Backward compatibility with `mix`
 ([
     'set', 'bind', 'unbind', 'decorate',
@@ -235,28 +214,22 @@ export const Observable = ObservableMixin(Emitter);
     'stopListening', 'fire', 'delegate', 'stopDelegating',
     '_addEventListener', '_removeEventListener'
 ]).forEach(key => {
-    ObservableMixin[key] = Observable.prototype[key];
+    ObservableMixin[key] = defaultObservableClass.prototype[key];
 });
 // Init symbol properties needed for the observable mechanism to work.
-//
-// @private
-// @param {module:utils/observablemixin~ObservableMixin} observable
 function initObservable(observable) {
     // Do nothing if already inited.
     if (observable[observablePropertiesSymbol]) {
         return;
     }
     // The internal hash containing the observable's state.
-    //
-    // @private
-    // @type {Map}
     Object.defineProperty(observable, observablePropertiesSymbol, {
         value: new Map()
     });
     // Map containing bindings to external observables. It shares the binding objects
-    // (`{ observable: A, property: 'a', to: ... }`) with {@link module:utils/observablemixin~ObservableMixin#_boundProperties} and
+    // (`{ observable: A, property: 'a', to: ... }`) with {@link module:utils/observablemixin~Observable#_boundProperties} and
     // it is used to observe external observables to update own properties accordingly.
-    // See {@link module:utils/observablemixin~ObservableMixin#bind}.
+    // See {@link module:utils/observablemixin~Observable#bind}.
     //
     //		A.bind( 'a', 'b', 'c' ).to( B, 'x', 'y', 'x' );
     //		console.log( A._boundObservables );
@@ -296,18 +269,16 @@ function initObservable(observable) {
     //				}
     //			} )
     //
-    // @private
-    // @type {Map}
     Object.defineProperty(observable, boundObservablesSymbol, {
         value: new Map()
     });
     // Object that stores which properties of this observable are bound and how. It shares
     // the binding objects (`{ observable: A, property: 'a', to: ... }`) with
-    // {@link module:utils/observablemixin~ObservableMixin#_boundObservables}. This data structure is
-    // a reverse of {@link module:utils/observablemixin~ObservableMixin#_boundObservables} and it is helpful for
-    // {@link module:utils/observablemixin~ObservableMixin#unbind}.
+    // {@link module:utils/observablemixin~Observable#_boundObservables}. This data structure is
+    // a reverse of {@link module:utils/observablemixin~Observable#_boundObservables} and it is helpful for
+    // {@link module:utils/observablemixin~Observable#unbind}.
     //
-    // See {@link module:utils/observablemixin~ObservableMixin#bind}.
+    // See {@link module:utils/observablemixin~Observable#bind}.
     //
     //		A.bind( 'a', 'b', 'c' ).to( B, 'x', 'y', 'x' );
     //		console.log( A._boundProperties );
@@ -327,17 +298,15 @@ function initObservable(observable) {
     //				c: { observable: A, property: 'c', to: [ [ B, 'x' ] ] },
     //				d: { observable: A, property: 'd', to: [ [ B, 'z' ], [ C, 'w' ] ], callback: callback }
     //			} )
-    //
-    // @private
-    // @type {Map}
     Object.defineProperty(observable, boundPropertiesSymbol, {
         value: new Map()
     });
 }
-// A chaining for {@link module:utils/observablemixin~ObservableMixin#bind} providing `.to()` interface.
-//
-// @private
-// @param {...[Observable|String|Function]} args Arguments of the `.to( args )` binding.
+/**
+ * A chaining for {@link module:utils/observablemixin~Observable#bind} providing `.to()` interface.
+ *
+ * @param args Arguments of the `.to( args )` binding.
+ */
 function bindTo(...args) {
     const parsedArgs = parseBindToArgs(...args);
     const bindingsKeys = Array.from(this._bindings.keys());
@@ -389,12 +358,9 @@ function bindTo(...args) {
         updateBoundObservableProperty(this._observable, propertyName);
     });
 }
-// Binds to an attribute in a set of iterable observables.
-//
-// @private
-// @param {Array.<Observable>} observables
-// @param {String} attribute
-// @param {Function} callback
+/**
+ * Binds to an attribute in a set of iterable observables.
+ */
 function bindToMany(observables, attribute, callback) {
     if (this._bindings.size > 1) {
         /**
@@ -410,43 +376,42 @@ function bindToMany(observables, attribute, callback) {
     // ...using given callback to parse attribute values.
     callback);
 }
-// Returns an array of binding components for
-// {@link Observable#bind} from a set of iterable observables.
-//
-// @param {Array.<Observable>} observables
-// @param {String} attribute
-// @returns {Array.<String|Observable>}
+/**
+ * Returns an array of binding components for
+ * {@link Observable#bind} from a set of iterable observables.
+ */
 function getBindingTargets(observables, attribute) {
     const observableAndAttributePairs = observables.map(observable => [observable, attribute]);
     // Merge pairs to one-dimension array of observables and attributes.
     return Array.prototype.concat.apply([], observableAndAttributePairs);
 }
-// Check if all entries of the array are of `String` type.
-//
-// @private
-// @param {Array} arr An array to be checked.
-// @returns {Boolean}
+/**
+ * Check if all entries of the array are of `String` type.
+ */
 function isStringArray(arr) {
     return arr.every(a => typeof a == 'string');
 }
-// Parses and validates {@link Observable#bind}`.to( args )` arguments and returns
-// an object with a parsed structure. For example
-//
-//		A.bind( 'x' ).to( B, 'a', C, 'b', call );
-//
-// becomes
-//
-//		{
-//			to: [
-//				{ observable: B, properties: [ 'a' ] },
-//				{ observable: C, properties: [ 'b' ] },
-//			],
-//			callback: call
-// 		}
-//
-// @private
-// @param {...*} args Arguments of {@link Observable#bind}`.to( args )`.
-// @returns {Object}
+/**
+ * Parses and validates {@link Observable#bind}`.to( args )` arguments and returns
+ * an object with a parsed structure. For example
+ *
+ * ```ts
+ * A.bind( 'x' ).to( B, 'a', C, 'b', call );
+ * ```
+ *
+ * becomes
+ *
+ * ```ts
+ * {
+ * 	to: [
+ * 		{ observable: B, properties: [ 'a' ] },
+ * 		{ observable: C, properties: [ 'b' ] },
+ * 	],
+ * 	callback: call
+ * }
+ *
+ * @param args Arguments of {@link Observable#bind}`.to( args )`.
+ */
 function parseBindToArgs(...args) {
     // Eliminate A.bind( 'x' ).to()
     if (!args.length) {
@@ -476,12 +441,13 @@ function parseBindToArgs(...args) {
     });
     return parsed;
 }
-// Synchronizes {@link module:utils/observablemixin#_boundObservables} with {@link Binding}.
-//
-// @private
-// @param {Binding} binding A binding to store in {@link Observable#_boundObservables}.
-// @param {Observable} toObservable A observable, which is a new component of `binding`.
-// @param {String} toPropertyName A name of `toObservable`'s property, a new component of the `binding`.
+/**
+ * Synchronizes {@link module:utils/observable#_boundObservables} with {@link Binding}.
+ *
+ * @param binding A binding to store in {@link Observable#_boundObservables}.
+ * @param toObservable A observable, which is a new component of `binding`.
+ * @param toPropertyName A name of `toObservable`'s property, a new component of the `binding`.
+ */
 function updateBoundObservables(observable, binding, toObservable, toPropertyName) {
     const boundObservables = observable[boundObservablesSymbol];
     const bindingsToObservable = boundObservables.get(toObservable);
@@ -495,44 +461,53 @@ function updateBoundObservables(observable, binding, toObservable, toPropertyNam
         boundObservables.set(toObservable, bindings);
     }
 }
-// Synchronizes {@link Observable#_boundProperties} and {@link Observable#_boundObservables}
-// with {@link BindChain}.
-//
-// Assuming the following binding being created
-//
-// 		A.bind( 'a', 'b' ).to( B, 'x', 'y' );
-//
-// the following bindings were initialized by {@link Observable#bind} in {@link BindChain#_bindings}:
-//
-// 		{
-// 			a: { observable: A, property: 'a', to: [] },
-// 			b: { observable: A, property: 'b', to: [] },
-// 		}
-//
-// Iterate over all bindings in this chain and fill their `to` properties with
-// corresponding to( ... ) arguments (components of the binding), so
-//
-// 		{
-// 			a: { observable: A, property: 'a', to: [ B, 'x' ] },
-// 			b: { observable: A, property: 'b', to: [ B, 'y' ] },
-// 		}
-//
-// Then update the structure of {@link Observable#_boundObservables} with updated
-// binding, so it becomes:
-//
-// 		Map( {
-// 			B: {
-// 				x: Set( [
-// 					{ observable: A, property: 'a', to: [ [ B, 'x' ] ] }
-// 				] ),
-// 				y: Set( [
-// 					{ observable: A, property: 'b', to: [ [ B, 'y' ] ] },
-// 				] )
-//			}
-// 		} )
-//
-// @private
-// @param {BindChain} chain The binding initialized by {@link Observable#bind}.
+/**
+ * Synchronizes {@link Observable#_boundProperties} and {@link Observable#_boundObservables}
+ * with {@link BindChain}.
+ *
+ * Assuming the following binding being created
+ *
+ * ```ts
+ * A.bind( 'a', 'b' ).to( B, 'x', 'y' );
+ * ```
+ *
+ * the following bindings were initialized by {@link Observable#bind} in {@link BindChain#_bindings}:
+ *
+ * ```ts
+ * {
+ * 	a: { observable: A, property: 'a', to: [] },
+ * 	b: { observable: A, property: 'b', to: [] },
+ * }
+ * ```
+ *
+ * Iterate over all bindings in this chain and fill their `to` properties with
+ * corresponding to( ... ) arguments (components of the binding), so
+ *
+ * ```ts
+ * {
+ * 	a: { observable: A, property: 'a', to: [ B, 'x' ] },
+ * 	b: { observable: A, property: 'b', to: [ B, 'y' ] },
+ * }
+ * ```
+ *
+ * Then update the structure of {@link Observable#_boundObservables} with updated
+ * binding, so it becomes:
+ *
+ * ```ts
+ * Map( {
+ * 	B: {
+ * 		x: Set( [
+ * 			{ observable: A, property: 'a', to: [ [ B, 'x' ] ] }
+ * 		] ),
+ * 		y: Set( [
+ * 			{ observable: A, property: 'b', to: [ [ B, 'y' ] ] },
+ * 		] )
+ * 	}
+ * } )
+ * ```
+ *
+ * @param chain The binding initialized by {@link Observable#bind}.
+ */
 function updateBindToBound(chain) {
     let toProperty;
     chain._bindings.forEach((binding, propertyName) => {
@@ -546,12 +521,13 @@ function updateBindToBound(chain) {
         });
     });
 }
-// Updates an property of a {@link Observable} with a value
-// determined by an entry in {@link Observable#_boundProperties}.
-//
-// @private
-// @param {Observable} observable A observable which property is to be updated.
-// @param {String} propertyName An property to be updated.
+/**
+ * Updates an property of a {@link Observable} with a value
+ * determined by an entry in {@link Observable#_boundProperties}.
+ *
+ * @param observable A observable which property is to be updated.
+ * @param propertyName An property to be updated.
+ */
 function updateBoundObservableProperty(observable, propertyName) {
     const boundProperties = observable[boundPropertiesSymbol];
     const binding = boundProperties.get(propertyName);
@@ -575,13 +551,13 @@ function updateBoundObservableProperty(observable, propertyName) {
         observable.set(propertyName, propertyValue);
     }
 }
-// Starts listening to changes in {@link BindChain._to} observables to update
-// {@link BindChain._observable} {@link BindChain._bindProperties}. Also sets the
-// initial state of {@link BindChain._observable}.
-//
-// @private
-// @param {Observable} observable
-// @param {BindChain} chain The chain initialized by {@link Observable#bind}.
+/**
+ * Starts listening to changes in {@link BindChain._to} observables to update
+ * {@link BindChain._observable} {@link BindChain._bindProperties}. Also sets the
+ * initial state of {@link BindChain._observable}.
+ *
+ * @param chain The chain initialized by {@link Observable#bind}.
+ */
 function attachBindToListeners(observable, toBindings) {
     toBindings.forEach(to => {
         const boundObservables = observable[boundObservablesSymbol];

package/src/priorities.js

@@ -4,17 +4,8 @@
  */
 /**
  * Provides group of constants to use instead of hardcoding numeric priority values.
- *
- * @namespace
  */
 const priorities = {
-    /**
-     * Converts a string with priority name to it's numeric value. If `Number` is given, it just returns it.
-     *
-     * @static
-     * @param {module:utils/priorities~PriorityString} [priority] Priority to convert.
-     * @returns {Number} Converted priority.
-     */
     get(priority = 'normal') {
         if (typeof priority != 'number') {
             return this[priority] || this.normal;

package/src/splicearray.js

@@ -12,19 +12,20 @@ const BIG_CHUNK_SIZE = 10000;
  *
  * Note: in contrary to Array.splice, this function does not modify the original `target`.
  *
- * 		spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );		// [ 3, 4, 1, 2 ]
- * 		spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );		// [ 1, 3, 4 ]
- * 		spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );		// [ 1, 3, 4, 2 ]
- * 		spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );		// [ 1, 2, 3, 4 ]
- * 		spliceArray( [ 1, 2 ], [], 0, 1 );				// [ 2 ]
+ * ```ts
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );	// [ 3, 4, 1, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );	// [ 1, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );	// [ 1, 3, 4, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );	// [ 1, 2, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [],       0, 1 );	// [ 2 ]
+ * ```
  *
- * @private
- * @param {Array} target Array to be spliced.
- * @param {Array} source Array of elements to be inserted to target.
- * @param {Number} start Index at which nodes should be inserted/removed.
- * @param {Number} count Number of items.
+ * @param target Array to be spliced.
+ * @param source Array of elements to be inserted to target.
+ * @param start Index at which nodes should be inserted/removed.
+ * @param count Number of items.
  *
- * @returns {Array} New spliced array.
+ * @returns New spliced array.
  */
 export default function spliceArray(target, source, start, count) {
     // In case of performance problems, see: https://github.com/ckeditor/ckeditor5/pull/12429/files#r965850568

package/src/spy.js

@@ -12,7 +12,7 @@
  *
  * * spy.called: property set to `true` if the function has been called at least once.
  *
- * @returns {Function} The spy function.
+ * @returns The spy function.
  */
 function spy() {
     return function spy() {

package/src/tomap.js

@@ -10,12 +10,14 @@ import isIterable from './isiterable';
 /**
  * Transforms object or iterable to map. Iterable needs to be in the format acceptable by the `Map` constructor.
  *
- *		map = toMap( { 'foo': 1, 'bar': 2 } );
- *		map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
- *		map = toMap( anotherMap );
+ * ```ts
+ * map = toMap( { 'foo': 1, 'bar': 2 } );
+ * map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
+ * map = toMap( anotherMap );
+ * ```
  *
- * @param {Object|Iterable|null} data Object or iterable to transform.
- * @returns {Map} Map created from data.
+ * @param data Object or iterable to transform.
+ * @returns Map created from data.
  */
 export default function toMap(data) {
     if (isIterable(data)) {