@ckeditor/ckeditor5-utils 35.3.2 → 36.0.0

package/src/isiterable.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,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

@@ -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
  */
 import CKEditorError from './ckeditorerror';
@@ -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

@@ -1,11 +1,11 @@
 /**
- * @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
  */
 /**
  * @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

@@ -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
  */
 const RTL_LANGUAGE_CODES = [
@@ -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

@@ -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,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

@@ -1,16 +1,16 @@
 /**
- * @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
  */
 /**
  * @module utils/mapsequal
  */
 /**
- * Checks whether given {Map}s are equal, that is has same size and same key-value pairs.
+ * 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

@@ -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
  */
 /**
@@ -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

@@ -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
  */
 /**
@@ -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

@@ -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,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();