@ckeditor/ckeditor5-utils 47.6.1 → 48.0.0-alpha.0

package/src/keystrokehandler.js

@@ -1,126 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/keystrokehandler
- */
-import { DomEmitterMixin } from './dom/emittermixin.js';
-import { getCode, parseKeystroke } from './keyboard.js';
-/**
- * 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:
- *
- * ```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:
- *
- * ```ts
- * 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 class KeystrokeHandler {
-    /**
-     * Listener used to listen to events for easier keystroke handler destruction.
-     */
-    _listener;
-    /**
-     * Creates an instance of the keystroke handler.
-     */
-    constructor() {
-        this._listener = new (DomEmitterMixin())();
-    }
-    /**
-     * Starts listening for `keydown` events from a given 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 keystroke Keystroke defined in a format accepted by
-     * the {@link module:utils/keyboard~parseKeystroke} function.
-     * @param callback A function called with the
-     * {@link module:engine/view/observer/keyobserver~ViewDocumentKeyEventData key event data} object and
-     * a helper function to call both `preventDefault()` and `stopPropagation()` on the underlying event.
-     * @param options Additional options.
-     */
-    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) => {
-            if (options.filter && !options.filter(keyEvtData)) {
-                return;
-            }
-            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 keyEvtData Key event data.
-     * @returns Whether the keystroke was handled.
-     */
-    press(keyEvtData) {
-        return !!this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);
-    }
-    /**
-     * Stops listening to `keydown` events from the given emitter.
-     */
-    stopListening(emitter) {
-        this._listener.stopListening(emitter);
-    }
-    /**
-     * Destroys the keystroke handler.
-     */
-    destroy() {
-        this.stopListening();
-    }
-}

package/src/language.js

@@ -1,21 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-const RTL_LANGUAGE_CODES = [
-    'ar', 'ara', // Arabic
-    'dv', 'div', // Dhivehi
-    'fa', 'per', 'fas', // Persian
-    'he', 'heb', // Hebrew
-    'ku', 'kur', // Kurdish
-    'ug', 'uig', // Uighur, Uyghur
-    'ur', 'urd' // Urdu
-];
-/**
- * Helps determine whether a language text direction is LTR or RTL.
- *
- * @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/legacyerrors.js

@@ -1,18 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/legacyerrors
- */
-import { CKEditorError } from './ckeditorerror.js';
-if (false) {
-    /**
-     * The `Locale#language` property was deprecated and will
-     * 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
-     */
-    throw new CKEditorError('locale-deprecated-language-property', null);
-}

package/src/locale.js

@@ -1,135 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/locale
- */
-import { toArray } from './toarray.js';
-import { _translate, _unifyTranslations } from './translation-service.js';
-import { getLanguageDirection } from './language.js';
-/**
- * Represents the localization services.
- */
-export class Locale {
-    /**
-     * The editor UI language code in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
-     *
-     * If the {@link #contentLanguage content language} was not specified in the `Locale` constructor,
-     * it also defines the language of the content.
-     */
-    uiLanguage;
-    /**
-     * Text direction of the {@link #uiLanguage editor UI language}. Either `'ltr'` or `'rtl'`.
-     */
-    uiLanguageDirection;
-    /**
-     * The editor content language code in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
-     *
-     * Usually the same as the {@link #uiLanguage editor language}, it can be customized by passing an optional
-     * argument to the `Locale` constructor.
-     */
-    contentLanguage;
-    /**
-     * Text direction of the {@link #contentLanguage editor content language}.
-     *
-     * If the content language was passed directly to the `Locale` constructor, this property represents the
-     * direction of that language.
-     *
-     * If the {@link #contentLanguage editor content language} was derived from the {@link #uiLanguage editor language},
-     * the content language direction is the same as the {@link #uiLanguageDirection UI language direction}.
-     *
-     * The value is either `'ltr'` or `'rtl'`.
-     */
-    contentLanguageDirection;
-    /**
-     * Translates the given message to the {@link #uiLanguage}. This method is also available in
-     * {@link module:core/editor/editor~Editor#t `Editor`} and {@link module:ui/view~View#t `View`}.
-     *
-     * This method's context is statically bound to the `Locale` instance and **should always be called as a function**:
-     *
-     * ```ts
-     * const t = locale.t;
-     * t( 'Label' );
-     * ```
-     *
-     * The message can be either a string or an object implementing the {@link module:utils/translation-service~Message} interface.
-     *
-     * The message may contain placeholders (`%<index>`) for value(s) that are passed as a `values` parameter.
-     * For an array of values, the `%<index>` will be changed to an element of that array at the given index.
-     * For a single value passed as the second argument, only the `%0` placeholders will be changed to the provided value.
-     *
-     * ```ts
-     * t( 'Created file "%0" in %1ms.', [ fileName, timeTaken ] );
-     * t( 'Created file "%0", fileName );
-     * ```
-     *
-     * The message supports plural forms. To specify the plural form, use the `plural` property. Singular or plural form
-     * will be chosen depending on the first value from the passed `values`. The value of the `plural` property is used
-     * as a default plural translation when the translation for the target language is missing.
-     *
-     * ```ts
-     * t( { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Add a space' for the English language.
-     * t( { string: 'Add a space', plural: 'Add %0 spaces' }, 5 ); // 'Add 5 spaces' for the English language.
-     * t( { string: '%1 a space', plural: '%1 %0 spaces' }, [ 2, 'Add' ] ); // 'Add 2 spaces' for the English language.
-     *
-     * t( { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Dodaj spację' for the Polish language.
-     * t( { string: 'Add a space', plural: 'Add %0 spaces' }, 5 ); // 'Dodaj 5 spacji' for the Polish language.
-     * t( { string: '%1 a space', plural: '%1 %0 spaces' }, [ 2, 'Add' ] ); // 'Dodaj 2 spacje' for the Polish language.
-     * ```
-     *
-     *  * The message should provide an ID using the `id` property when the message strings are not unique and their
-     * translations should be different.
-     *
-     * ```ts
-     * translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
-     * translate( 'en', { string: 'image', id: 'AN_IMAGE' } );
-     * ```
-     */
-    t;
-    /**
-     * Object that contains translations.
-     */
-    translations;
-    /**
-     * Creates a new instance of the locale class. Learn more about
-     * {@glink getting-started/setup/ui-language configuring the language of the editor}.
-     *
-     * @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 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}.
-     * @param options.translations Translations passed as a editor config parameter.
-     */
-    constructor({ uiLanguage = 'en', contentLanguage, translations } = {}) {
-        this.uiLanguage = uiLanguage;
-        this.contentLanguage = contentLanguage || this.uiLanguage;
-        this.uiLanguageDirection = getLanguageDirection(this.uiLanguage);
-        this.contentLanguageDirection = getLanguageDirection(this.contentLanguage);
-        this.translations = _unifyTranslations(translations);
-        this.t = (message, values) => this._t(message, values);
-    }
-    /**
-     * An unbound version of the {@link #t} method.
-     */
-    _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, this.translations);
-        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

@@ -1,27 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/mapsequal
- */
-/**
- * Checks whether given `Map`s are equal, that is has same size and same key-value pairs.
- *
- * @param mapA The first map to compare.
- * @param mapB The second map to compare.
- * @returns `true` if given maps are equal, `false` otherwise.
- */
-export 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

@@ -1,5 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-export {};

package/src/nth.js

@@ -1,24 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @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.
- */
-export function nth(index, iterable) {
-    for (const item of iterable) {
-        if (index === 0) {
-            return item;
-        }
-        index -= 1;
-    }
-    return null;
-}

package/src/objecttomap.js

@@ -1,27 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/objecttomap
- */
-/**
- * Transforms object to map.
- *
- * ```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 obj Object to transform.
- * @returns Map created from object.
- */
-export function objectToMap(obj) {
-    const map = new Map();
-    for (const key in obj) {
-        map.set(key, obj[key]);
-    }
-    return map;
-}