@ckeditor/ckeditor5-utils 35.0.0 → 35.0.1

package/src/keystrokehandler.js

@@ -0,0 +1,114 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/keystrokehandler
+ */
+import DomEmitterMixin from './dom/emittermixin';
+import { getCode, parseKeystroke } from './keyboard';
+/**
+ * Keystroke handler allows registering callbacks for given keystrokes.
+ *
+ * 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();
+ *		} );
+ *
+ * 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();
+ *
+ * 				this.keystrokes.set( 'tab', handleTabKey );
+ *			}
+ *
+ *			render() {
+ *				super.render();
+ *
+ *				this.keystrokes.listenTo( this.element );
+ *			}
+ *		}
+ *
+ * That keystroke handler will listen to `keydown` events fired in this view's main element.
+ *
+ */
+export default class KeystrokeHandler {
+    /**
+     * Creates an instance of the keystroke handler.
+     */
+    constructor() {
+        this._listener = Object.create(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
+        // keystroke so the listeners can be attached to them with different priorities.
+        //
+        // E.g. all the keystrokes with the `keyCode` of 42 coming from the `emitter` are propagated
+        // as a `_keydown:42` event by the `_listener`. If there's a callback created by the `set`
+        // method for this 42 keystroke, it listens to the `_listener#_keydown:42` event only and interacts
+        // only with other listeners of this particular event, thus making it possible to prioritize
+        // the listeners and safely cancel execution, when needed. Instead of duplicating the Emitter logic,
+        // the KeystrokeHandler re–uses it to do its job.
+        this._listener.listenTo(emitter, 'keydown', (evt, keyEvtData) => {
+            this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);
+        });
+    }
+    /**
+     * Registers a handler for the specified keystroke.
+     *
+     * @param {String|Array.<String|Number>} keystroke Keystroke defined in a format accepted by
+     * the {@link module:utils/keyboard~parseKeystroke} function.
+     * @param {Function} callback A function called with the
+     * {@link module:engine/view/observer/keyobserver~KeyEventData key event data} object and
+     * a helper funcion to call both `preventDefault()` and `stopPropagation()` on the underlying event.
+     * @param {Object} [options={}] Additional options.
+     * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] 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.
+     */
+    set(keystroke, callback, options = {}) {
+        const keyCode = parseKeystroke(keystroke);
+        const priority = options.priority;
+        // Execute the passed callback on KeystrokeHandler#_keydown.
+        // TODO: https://github.com/ckeditor/ckeditor5-utils/issues/144
+        this._listener.listenTo(this._listener, '_keydown:' + keyCode, (evt, keyEvtData) => {
+            callback(keyEvtData, () => {
+                // Stop the event in the DOM: no listener in the web page
+                // will be triggered by this event.
+                keyEvtData.preventDefault();
+                keyEvtData.stopPropagation();
+                // Stop the event in the KeystrokeHandler: no more callbacks
+                // will be executed for this keystroke.
+                evt.stop();
+            });
+            // Mark this keystroke as handled by the callback. See: #press.
+            evt.return = true;
+        }, { priority });
+    }
+    /**
+     * 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.
+     */
+    press(keyEvtData) {
+        return !!this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);
+    }
+    /**
+     * Destroys the keystroke handler.
+     */
+    destroy() {
+        this._listener.stopListening();
+    }
+}

package/src/language.js

@@ -0,0 +1,20 @@
+/**
+ * @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
+ */
+const RTL_LANGUAGE_CODES = [
+    'ar', 'ara',
+    'fa', 'per', 'fas',
+    'he', 'heb',
+    'ku', 'kur',
+    'ug', 'uig' // Uighur, Uyghur
+];
+/**
+ * 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}
+ */
+export function getLanguageDirection(languageCode) {
+    return RTL_LANGUAGE_CODES.includes(languageCode) ? 'rtl' : 'ltr';
+}

package/src/locale.js

@@ -0,0 +1,79 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/locale
+ */
+/* globals console */
+import toArray from './toarray';
+import { _translate } from './translation-service';
+import { getLanguageDirection } from './language';
+/**
+ * Represents the localization services.
+ */
+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
+     * [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
+     * [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;
+        this.uiLanguageDirection = getLanguageDirection(this.uiLanguage);
+        this.contentLanguageDirection = getLanguageDirection(this.contentLanguage);
+        this.t = (message, values) => this._t(message, values);
+    }
+    /**
+     * The editor UI language code in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
+     *
+     * **Note**: This property was deprecated. Please use {@link #uiLanguage} and {@link #contentLanguage}
+     * 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.
+         *
+         * @error locale-deprecated-language-property
+         */
+        console.warn('locale-deprecated-language-property: ' +
+            'The Locale#language property has been deprecated and will be removed in the near future. ' +
+            'Please use #uiLanguage and #contentLanguage properties instead.');
+        return this.uiLanguage;
+    }
+    /**
+     * 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);
+        if (typeof message === 'string') {
+            message = { string: message };
+        }
+        const hasPluralForm = !!message.plural;
+        const quantity = hasPluralForm ? values[0] : 1;
+        const translatedString = _translate(this.uiLanguage, message, quantity);
+        return interpolateString(translatedString, 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

@@ -0,0 +1,27 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/mapsequal
+ */
+/**
+ * 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.
+ */
+export default function mapsEqual(mapA, mapB) {
+    if (mapA.size != mapB.size) {
+        return false;
+    }
+    for (const attr of mapA.entries()) {
+        const valA = JSON.stringify(attr[1]);
+        const valB = JSON.stringify(mapB.get(attr[0]));
+        if (valA !== valB) {
+            return false;
+        }
+    }
+    return true;
+}

package/src/mix.js

@@ -0,0 +1,44 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/mix
+ */
+/**
+ * Copies enumerable properties and symbols from the objects given as 2nd+ parameters to the
+ * prototype of first object (a constructor).
+ *
+ *		class Editor {
+ *			...
+ *		}
+ *
+ *		const SomeMixin = {
+ *			a() {
+ *				return 'a';
+ *			}
+ *		};
+ *
+ *		mix( Editor, SomeMixin, ... );
+ *
+ *		new Editor().a(); // -> 'a'
+ *
+ * Note: Properties which already exist in the base class will not be overriden.
+ *
+ * @param {Function} [baseClass] Class which prototype will be extended.
+ * @param {Object} [...mixins] Objects from which to get properties.
+ */
+export default function mix(baseClass, ...mixins) {
+    mixins.forEach(mixin => {
+        const propertyNames = Object.getOwnPropertyNames(mixin);
+        const propertySymbols = Object.getOwnPropertySymbols(mixin);
+        propertyNames.concat(propertySymbols).forEach(key => {
+            if (key in baseClass.prototype) {
+                return;
+            }
+            const sourceDescriptor = Object.getOwnPropertyDescriptor(mixin, key);
+            sourceDescriptor.enumerable = false;
+            Object.defineProperty(baseClass.prototype, key, sourceDescriptor);
+        });
+    });
+}

package/src/nth.js

@@ -0,0 +1,28 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/nth
+ */
+/**
+ * Returns `nth` (starts from `0` of course) item of the given `iterable`.
+ *
+ * If the iterable is a generator, then it consumes **all its items**.
+ * 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) {
+        if (index === 0) {
+            return item;
+        }
+        index -= 1;
+    }
+    return null;
+}

package/src/objecttomap.js

@@ -0,0 +1,25 @@
+/**
+ * @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
+ */
+/**
+ * @module utils/objecttomap
+ */
+/**
+ * Transforms object to map.
+ *
+ *		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.
+ */
+export default function objectToMap(obj) {
+    const map = new Map();
+    for (const key in obj) {
+        map.set(key, obj[key]);
+    }
+    return map;
+}