@ckeditor/ckeditor5-utils 41.3.1 → 41.4.0

package/dist/types/locale.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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
+ */
+import { type ArrayOrItem } from './toarray.js';
+import { type Message } from './translation-service.js';
+import { type LanguageDirection } from './language.js';
+/**
+ * Represents the localization services.
+ */
+export default 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.
+     */
+    readonly uiLanguage: string;
+    /**
+     * Text direction of the {@link #uiLanguage editor UI language}. Either `'ltr'` or `'rtl'`.
+     */
+    readonly uiLanguageDirection: LanguageDirection;
+    /**
+     * 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.
+     */
+    readonly contentLanguage: string;
+    /**
+     * 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'`.
+     */
+    readonly contentLanguageDirection: LanguageDirection;
+    /**
+     * 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' } );
+     * ```
+     */
+    readonly t: LocaleTranslate;
+    /**
+     * Object that contains translations.
+     */
+    translations?: Translations;
+    /**
+     * Creates a new instance of the locale class. Learn more about
+     * {@glink features/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 translations Translations passed as a editor config parameter.
+     */
+    constructor({ uiLanguage, contentLanguage, translations }?: {
+        readonly uiLanguage?: string;
+        readonly contentLanguage?: string;
+        readonly translations?: ArrayOrItem<Translations>;
+    });
+    /**
+     * 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
+     */
+    get language(): string;
+    /**
+     * An unbound version of the {@link #t} method.
+     */
+    private _t;
+}
+/**
+ * @param message A message that will be localized (translated).
+ * @param values A value or an array of values that will fill message placeholders.
+ * For messages supporting plural forms the first value will determine the plural form.
+ */
+export type LocaleTranslate = (message: string | Message, values?: number | string | ReadonlyArray<number | string>) => string;
+/**
+ * Translations object definition.
+ */
+export type Translations = {
+    [language: string]: {
+        dictionary: {
+            [messageId: string]: string | ReadonlyArray<string>;
+        };
+        getPluralForm?: ((n: number) => number | boolean) | null;
+    };
+};

package/dist/types/mapsequal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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 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<Key>(mapA: Map<Key, unknown>, mapB: Map<Key, unknown>): boolean;

package/dist/types/mix.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.
+ *
+ * @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: Function, ...mixins: Array<object>): void;
+/**
+ * Helper type that represents constructor creating given objects. Can be used as a type constraint.
+ *
+ * ```ts
+ * // The function accepts any class constructor.
+ * function MyFunction<Ctor extends Constructor>( ctor: Ctor ) {
+ * 	// ...
+ * }
+ *
+ * // The function accepts any class constructor of type derived from `MyBase`.
+ * function MyFunction<Ctor extends Constructor<MyBase>>( ctor: Ctor ) {
+ * 	// ...
+ * }
+ * ```
+ */
+export type Constructor<Instance = object> = abstract new (...args: Array<any>) => Instance;
+/**
+ * Helper type that creates constructor types from a base class and a mixin interface.
+ *
+ * ```ts
+ * interface MyMixinInterface {
+ * 	mixinMethod(): void;
+ * }
+ *
+ * function MyMixin<Base extends Constructor>( base: Base ): Mixed<Base, MyMixinInterface> {
+ * 	// ...
+ * }
+ *
+ * class BaseClass {
+ * 	baseMethod(): void {
+ * 		// ...
+ * 	}
+ * }
+ *
+ * const MixedClass = MyMixin( BaseClass );
+ *
+ * // Contains both `mixinMethod()` and `baseMethod()`.
+ * const myObject = new MixedClass();
+ * myObject.mixinMethod();
+ * myObject.baseMethod();
+ * ```
+ *
+ * @typeParam Base A type of constructor of a class to apply mixin to.
+ * @typeParam Mixin An interface representing mixin.
+ */
+export type Mixed<Base extends Constructor, Mixin extends object> = {
+    new (...args: ConstructorParameters<Base>): Mixin & InstanceType<Base>;
+    prototype: Mixin & InstanceType<Base>;
+} & {
+    [K in keyof Base]: Base[K];
+};

package/dist/types/nth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.
+ */
+export default function nth<T>(index: number, iterable: Iterable<T>): T | null;

package/dist/types/objecttomap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.
+ *
+ * ```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 default function objectToMap<T>(obj: {
+    readonly [key: string]: T;
+} | null | undefined): Map<string, T>;