@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/first.js

@@ -7,9 +7,6 @@
  */
 /**
  * Returns first item of the given `iterator`.
- *
- * @param {Iterator.<*>} iterator
- * @returns {*}
  */
 export default function first(iterator) {
     const iteratorItem = iterator.next();

package/src/focustracker.js

@@ -3,12 +3,11 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /* global setTimeout, clearTimeout */
-/* eslint-disable new-cap */
 /**
  * @module utils/focustracker
  */
 import DomEmitterMixin from './dom/emittermixin';
-import { Observable } from './observablemixin';
+import ObservableMixin from './observablemixin';
 import CKEditorError from './ckeditorerror';
 /**
  * Allows observing a group of `Element`s whether at least one of them is focused.
@@ -21,22 +20,23 @@ import CKEditorError from './ckeditorerror';
  * (have e.g. `tabindex="-1"`).
  *
  * Check out the {@glink framework/guides/deep-dive/ui/focus-tracking "Deep dive into focus tracking" guide} to learn more.
- *
- * @mixes module:utils/dom/emittermixin~EmitterMixin
- * @mixes module:utils/observablemixin~ObservableMixin
  */
-export default class FocusTracker extends DomEmitterMixin(Observable) {
+export default class FocusTracker extends DomEmitterMixin(ObservableMixin()) {
     constructor() {
         super();
-        this.set('isFocused', false);
-        this.set('focusedElement', null);
+        /**
+         * List of registered elements.
+         */
         this._elements = new Set();
+        /**
+         * Event loop timeout.
+         */
         this._nextEventLoopTimeout = null;
+        this.set('isFocused', false);
+        this.set('focusedElement', null);
     }
     /**
      * Starts tracking the specified element.
-     *
-     * @param {Element} element
      */
     add(element) {
         if (this._elements.has(element)) {
@@ -53,8 +53,6 @@ export default class FocusTracker extends DomEmitterMixin(Observable) {
     }
     /**
      * Stops tracking the specified element and stops listening on this element.
-     *
-     * @param {Element} element
      */
     remove(element) {
         if (element === this.focusedElement) {
@@ -75,9 +73,6 @@ export default class FocusTracker extends DomEmitterMixin(Observable) {
     }
     /**
      * Stores currently focused element and set {#isFocused} as `true`.
-     *
-     * @private
-     * @param {Element} element Element which has been focused.
      */
     _focus(element) {
         clearTimeout(this._nextEventLoopTimeout);
@@ -87,9 +82,6 @@ export default class FocusTracker extends DomEmitterMixin(Observable) {
     /**
      * Clears currently focused element and set {@link #isFocused} as `false`.
      * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
-     *
-     * @private
-     * @fires blur
      */
     _blur() {
         clearTimeout(this._nextEventLoopTimeout);

package/src/index.js

@@ -7,20 +7,35 @@
  */
 export { default as env } from './env';
 export { default as diff } from './diff';
+export { default as fastDiff } from './fastdiff';
 export { default as mix } from './mix';
 export { default as EmitterMixin } from './emittermixin';
+export { default as EventInfo } from './eventinfo';
 export { default as ObservableMixin } from './observablemixin';
 export { default as CKEditorError, logError, logWarning } from './ckeditorerror';
 export { default as ElementReplacer } from './elementreplacer';
+export { default as count } from './count';
+export { default as compareArrays } from './comparearrays';
 export { default as createElement } from './dom/createelement';
+export { default as Config } from './config';
+export { default as isIterable } from './isiterable';
 export { default as DomEmitterMixin } from './dom/emittermixin';
 export { default as global } from './dom/global';
+export { default as getAncestors } from './dom/getancestors';
 export { default as getDataFromElement } from './dom/getdatafromelement';
+export { default as isText } from './dom/istext';
 export { default as Rect } from './dom/rect';
 export { default as ResizeObserver } from './dom/resizeobserver';
 export { default as setDataInElement } from './dom/setdatainelement';
 export { default as toUnit } from './dom/tounit';
+export { default as indexOf } from './dom/indexof';
+export { default as insertAt } from './dom/insertat';
+export { default as isComment } from './dom/iscomment';
+export { default as isNode } from './dom/isnode';
+export { default as isRange } from './dom/isrange';
 export { default as isVisible } from './dom/isvisible';
+export { getOptimalPosition } from './dom/position';
+export { default as remove } from './dom/remove';
 export * from './dom/scroll';
 export * from './keyboard';
 export * from './language';
@@ -33,5 +48,7 @@ export { default as toArray } from './toarray';
 export { default as toMap } from './tomap';
 export { default as priorities } from './priorities';
 export { default as insertToPriorityArray } from './inserttopriorityarray';
+export { default as spliceArray } from './splicearray';
 export { default as uid } from './uid';
+export * from './unicode';
 export { default as version } from './version';

package/src/inserttopriorityarray.js

@@ -6,8 +6,8 @@ import priorities from './priorities';
 /**
  * Inserts any object with priority at correct index by priority so registered objects are always sorted from highest to lowest priority.
  *
- * @param {Array.<module:utils/inserttopriorityarray~ObjectWithPriority>} objects Array of objects with priority to insert object to.
- * @param {module:utils/inserttopriorityarray~ObjectWithPriority} objectToInsert Object with `priority` property.
+ * @param objects Array of objects with priority to insert object to.
+ * @param objectToInsert Object with `priority` property.
  */
 export default function insertToPriorityArray(objects, objectToInsert) {
     const priority = priorities.get(objectToInsert.priority);

package/src/isiterable.js

@@ -8,8 +8,8 @@
 /**
  * Checks if value implements iterator interface.
  *
- * @param {*} value The value to check.
- * @returns {Boolean} True if value implements iterator interface.
+ * @param value The value to check.
+ * @returns True if value implements iterator interface.
  */
 export default function isIterable(value) {
     return !!(value && value[Symbol.iterator]);

package/src/keyboard.js

@@ -35,9 +35,8 @@ const keyCodeNames = Object.fromEntries(Object.entries(keyCodes).map(([name, cod
  *
  * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
  *
- * @param {String|module:utils/keyboard~KeystrokeInfo} A key name (see {@link module:utils/keyboard~keyCodes})
- * or a keystroke data object.
- * @returns {Number} Key or keystroke code.
+ * @param key A key name (see {@link module:utils/keyboard~keyCodes}) or a keystroke data object.
+ * @returns Key or keystroke code.
  */
 export function getCode(key) {
     let keyCode;
@@ -81,8 +80,8 @@ export function getCode(key) {
  * For example, a registered keystroke `Ctrl+A` will be translated to `Cmd+A` on macOS. To disable the translation of some keystroke,
  * use the forced modifier: `Ctrl!+A` (note the exclamation mark).
  *
- * @param {String|Array.<Number|String>} keystroke The keystroke definition.
- * @returns {Number} Keystroke code.
+ * @param keystroke The keystroke definition.
+ * @returns Keystroke code.
  */
 export function parseKeystroke(keystroke) {
     if (typeof keystroke == 'string') {
@@ -96,8 +95,8 @@ export function parseKeystroke(keystroke) {
  * Translates any keystroke string text like `"Ctrl+A"` to an
  * environment–specific keystroke, i.e. `"⌘A"` on macOS.
  *
- * @param {String} keystroke The keystroke text.
- * @returns {String} The keystroke text specific for the environment.
+ * @param keystroke The keystroke text.
+ * @returns The keystroke text specific for the environment.
  */
 export function getEnvKeystrokeText(keystroke) {
     let keystrokeCode = parseKeystroke(keystroke);
@@ -115,8 +114,7 @@ export function getEnvKeystrokeText(keystroke) {
 /**
  * Returns `true` if the provided key code represents one of the arrow keys.
  *
- * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
- * @returns {Boolean}
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
  */
 export function isArrowKeyCode(keyCode) {
     return keyCode == keyCodes.arrowright ||
@@ -131,10 +129,10 @@ export function isArrowKeyCode(keyCode) {
  * For instance, in right–to–left (RTL) content languages, pressing the left arrow means moving the selection right (forward)
  * in the model structure. Similarly, pressing the right arrow moves the selection left (backward).
  *
- * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
- * @param {module:utils/language~LanguageDirection} contentLanguageDirection The content language direction, corresponding to
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
+ * @param contentLanguageDirection The content language direction, corresponding to
  * {@link module:utils/locale~Locale#contentLanguageDirection}.
- * @returns {module:utils/keyboard~ArrowKeyCodeDirection|undefined} Localized arrow direction or `undefined` for non-arrow key codes.
+ * @returns Localized arrow direction or `undefined` for non-arrow key codes.
  */
 export function getLocalizedArrowKeyCodeDirection(keyCode, contentLanguageDirection) {
     const isLtrContent = contentLanguageDirection === 'ltr';
@@ -149,12 +147,14 @@ export function getLocalizedArrowKeyCodeDirection(keyCode, contentLanguageDirect
             return 'down';
     }
 }
-// Converts a key name to the key code with mapping based on the env.
-//
-// See: {@link module:utils/keyboard~getCode}.
-//
-// @param {String} key The key name (see {@link module:utils/keyboard~keyCodes}).
-// @returns {Number} Key code.
+/**
+ * Converts a key name to the key code with mapping based on the env.
+ *
+ * See: {@link module:utils/keyboard~getCode}.
+ *
+ * @param key The key name (see {@link module:utils/keyboard~keyCodes}).
+ * @returns Key code.
+ */
 function getEnvKeyCode(key) {
     // Don't remap modifier key for forced modifiers.
     if (key.endsWith('!')) {
@@ -170,10 +170,9 @@ function getEnvKeyCode(key) {
  * For instance, in right–to–left (RTL) languages, pressing the left arrow means moving forward
  * in the model structure. Similarly, pressing the right arrow moves the selection backward.
  *
- * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
- * @param {module:utils/language~LanguageDirection} contentLanguageDirection The content language direction, corresponding to
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
+ * @param contentLanguageDirection The content language direction, corresponding to
  * {@link module:utils/locale~Locale#contentLanguageDirection}.
- * @returns {Boolean}
  */
 export function isForwardArrowKeyCode(keyCode, contentLanguageDirection) {
     const localizedKeyCodeDirection = getLocalizedArrowKeyCodeDirection(keyCode, contentLanguageDirection);

package/src/keystrokehandler.js

@@ -5,7 +5,7 @@
 /**
  * @module utils/keystrokehandler
  */
-import { Emitter as DomEmitter } from './dom/emittermixin';
+import DomEmitterMixin from './dom/emittermixin';
 import { getCode, parseKeystroke } from './keyboard';
 /**
  * Keystroke handler allows registering callbacks for given keystrokes.
@@ -13,27 +13,31 @@ import { getCode, parseKeystroke } from './keyboard';
  * The most frequent use of this class is through the {@link module:core/editor/editor~Editor#keystrokes `editor.keystrokes`}
  * property. It allows listening to keystrokes executed in the editing view:
  *
- *		editor.keystrokes.set( 'Ctrl+A', ( keyEvtData, cancel ) => {
- *			console.log( 'Ctrl+A has been pressed' );
- *			cancel();
- *		} );
+ * ```ts
+ * editor.keystrokes.set( 'Ctrl+A', ( keyEvtData, cancel ) => {
+ * 	console.log( 'Ctrl+A has been pressed' );
+ * 	cancel();
+ * } );
+ * ```
  *
  * However, this utility class can be used in various part of the UI. For instance, a certain {@link module:ui/view~View}
  * can use it like this:
  *
- *		class MyView extends View {
- *			constructor() {
- *				this.keystrokes = new KeystrokeHandler();
+ * ```ts
+ * class MyView extends View {
+ * 	constructor() {
+ * 		this.keystrokes = new KeystrokeHandler();
  *
- * 				this.keystrokes.set( 'tab', handleTabKey );
- *			}
+ * 		this.keystrokes.set( 'tab', handleTabKey );
+ * 	}
  *
- *			render() {
- *				super.render();
+ * 	render() {
+ * 		super.render();
  *
- *				this.keystrokes.listenTo( this.element );
- *			}
- *		}
+ * 		this.keystrokes.listenTo( this.element );
+ * 	}
+ * }
+ * ```
  *
  * That keystroke handler will listen to `keydown` events fired in this view's main element.
  *
@@ -43,12 +47,10 @@ export default class KeystrokeHandler {
      * Creates an instance of the keystroke handler.
      */
     constructor() {
-        this._listener = new DomEmitter();
+        this._listener = new (DomEmitterMixin())();
     }
     /**
      * Starts listening for `keydown` events from a given emitter.
-     *
-     * @param {module:utils/emittermixin~Emitter|HTMLElement|Window} emitter
      */
     listenTo(emitter) {
         // The #_listener works here as a kind of dispatcher. It groups the events coming from the same
@@ -67,13 +69,13 @@ export default class KeystrokeHandler {
     /**
      * Registers a handler for the specified keystroke.
      *
-     * @param {String|Array.<String|Number>} keystroke Keystroke defined in a format accepted by
+     * @param keystroke Keystroke defined in a format accepted by
      * the {@link module:utils/keyboard~parseKeystroke} function.
-     * @param {Function} callback A function called with the
+     * @param callback A function called with the
      * {@link module:engine/view/observer/keyobserver~KeyEventData key event data} object and
      * a helper function to call both `preventDefault()` and `stopPropagation()` on the underlying event.
-     * @param {Object} [options={}] Additional options.
-     * @param {module:utils/priorities~PriorityString} [options.priority='normal'] The priority of the keystroke
+     * @param options Additional options.
+     * @param options.priority The priority of the keystroke
      * callback. The higher the priority value the sooner the callback will be executed. Keystrokes having the same priority
      * are called in the order they were added.
      */
@@ -99,8 +101,8 @@ export default class KeystrokeHandler {
     /**
      * Triggers a keystroke handler for a specified key combination, if such a keystroke was {@link #set defined}.
      *
-     * @param {module:engine/view/observer/keyobserver~KeyEventData} keyEvtData Key event data.
-     * @returns {Boolean} Whether the keystroke was handled.
+     * @param keyEvtData Key event data.
+     * @returns Whether the keystroke was handled.
      */
     press(keyEvtData) {
         return !!this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);

package/src/language.js

@@ -12,8 +12,7 @@ const RTL_LANGUAGE_CODES = [
 /**
  * Helps determine whether a language text direction is LTR or RTL.
  *
- * @param {String} languageCode The ISO 639-1 or ISO 639-2 language code.
- * @returns {module:utils/language~LanguageDirection}
+ * @param languageCode The ISO 639-1 or ISO 639-2 language code.
  */
 export function getLanguageDirection(languageCode) {
     return RTL_LANGUAGE_CODES.includes(languageCode) ? 'rtl' : 'ltr';

package/src/locale.js

@@ -17,16 +17,16 @@ export default class Locale {
      * Creates a new instance of the locale class. Learn more about
      * {@glink features/ui-language configuring the language of the editor}.
      *
-     * @param {Object} [options] Locale configuration.
-     * @param {String} [options.uiLanguage='en'] The editor UI language code in the
+     * @param options Locale configuration.
+     * @param options.uiLanguage The editor UI language code in the
      * [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format. See {@link #uiLanguage}.
-     * @param {String} [options.contentLanguage] The editor content language code in the
+     * @param options.contentLanguage The editor content language code in the
      * [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format. If not specified, the same as `options.language`.
      * See {@link #contentLanguage}.
      */
-    constructor(options = {}) {
-        this.uiLanguage = options.uiLanguage || 'en';
-        this.contentLanguage = options.contentLanguage || this.uiLanguage;
+    constructor({ uiLanguage = 'en', contentLanguage } = {}) {
+        this.uiLanguage = uiLanguage;
+        this.contentLanguage = contentLanguage || this.uiLanguage;
         this.uiLanguageDirection = getLanguageDirection(this.uiLanguage);
         this.contentLanguageDirection = getLanguageDirection(this.contentLanguage);
         this.t = (message, values) => this._t(message, values);
@@ -38,12 +38,12 @@ export default class Locale {
      * properties instead.
      *
      * @deprecated
-     * @member {String}
      */
     get language() {
         /**
          * The {@link module:utils/locale~Locale#language `Locale#language`} property was deprecated and will
-         * be removed in the near future. Please use the {@link #uiLanguage} and {@link #contentLanguage} properties instead.
+         * be removed in the near future. Please use the {@link module:utils/locale~Locale#uiLanguage `Locale#uiLanguage`} and
+         * {@link module:utils/locale~Locale#contentLanguage `Locale#contentLanguage`} properties instead.
          *
          * @error locale-deprecated-language-property
          */
@@ -54,11 +54,6 @@ export default class Locale {
     }
     /**
      * An unbound version of the {@link #t} method.
-     *
-     * @private
-     * @param {String|module:utils/translation-service~Message} message
-     * @param {Number|String|Array.<Number|String>} [values]
-     * @returns {String}
      */
     _t(message, values = []) {
         values = toArray(values);
@@ -71,7 +66,9 @@ export default class Locale {
         return interpolateString(translatedString, values);
     }
 }
-// Fills the `%0, %1, ...` string placeholders with values.
+/**
+ * Fills the `%0, %1, ...` string placeholders with values.
+ */
 function interpolateString(string, values) {
     return string.replace(/%(\d+)/g, (match, index) => {
         return (index < values.length) ? values[index] : match;

package/src/mapsequal.js

@@ -8,9 +8,9 @@
 /**
  * Checks whether given {Map}s are equal, that is has same size and same key-value pairs.
  *
- * @param {Map} mapA The first map to compare.
- * @param {Map} mapB The second map to compare.
- * @returns {Boolean} `true` if given maps are equal, `false` otherwise.
+ * @param mapA The first map to compare.
+ * @param mapB The second map to compare.
+ * @returns `true` if given maps are equal, `false` otherwise.
  */
 export default function mapsEqual(mapA, mapB) {
     if (mapA.size != mapB.size) {

package/src/mix.js

@@ -9,25 +9,27 @@
  * Copies enumerable properties and symbols from the objects given as 2nd+ parameters to the
  * prototype of first object (a constructor).
  *
- *		class Editor {
- *			...
- *		}
+ * ```
+ * class Editor {
+ * 	...
+ * }
  *
- *		const SomeMixin = {
- *			a() {
- *				return 'a';
- *			}
- *		};
+ * const SomeMixin = {
+ * 	a() {
+ * 		return 'a';
+ * 	}
+ * };
  *
- *		mix( Editor, SomeMixin, ... );
+ * mix( Editor, SomeMixin, ... );
  *
- *		new Editor().a(); // -> 'a'
+ * new Editor().a(); // -> 'a'
+ * ```
  *
  * Note: Properties which already exist in the base class will not be overriden.
  *
- * @depreciated Use mixin pattern, see: https://www.typescriptlang.org/docs/handbook/mixins.html.
- * @param {Function} [baseClass] Class which prototype will be extended.
- * @param {Object} [...mixins] Objects from which to get properties.
+ * @deprecated Use mixin pattern, see: https://www.typescriptlang.org/docs/handbook/mixins.html.
+ * @param baseClass Class which prototype will be extended.
+ * @param mixins Objects from which to get properties.
  */
 export default function mix(baseClass, ...mixins) {
     mixins.forEach(mixin => {

package/src/nth.js

@@ -12,10 +12,6 @@
  * If it's a normal iterator, then it consumes **all items up to the given index**.
  * Refer to the [Iterators and Generators](https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Iterators_and_Generators)
  * guide to learn differences between these interfaces.
- *
- * @param {Number} index
- * @param {Iterable.<*>} iterable
- * @returns {*}
  */
 export default function nth(index, iterable) {
     for (const item of iterable) {

package/src/objecttomap.js

@@ -8,13 +8,15 @@
 /**
  * Transforms object to map.
  *
- *		const map = objectToMap( { 'foo': 1, 'bar': 2 } );
- *		map.get( 'foo' ); // 1
+ * ```ts
+ * const map = objectToMap( { 'foo': 1, 'bar': 2 } );
+ * map.get( 'foo' ); // 1
+ * ```
  *
  * **Note**: For mixed data (`Object` or `Iterable`) there's a dedicated {@link module:utils/tomap~toMap} function.
  *
- * @param {Object|null} obj Object to transform.
- * @returns {Map} Map created from object.
+ * @param obj Object to transform.
+ * @returns Map created from object.
  */
 export default function objectToMap(obj) {
     const map = new Map();