@ckeditor/ckeditor5-utils 36.0.1 → 37.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -14,10 +14,10 @@
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-build-classic": "^36.0.1",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.1",
-    "@ckeditor/ckeditor5-core": "^36.0.1",
-    "@ckeditor/ckeditor5-engine": "^36.0.1",
+    "@ckeditor/ckeditor5-build-classic": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.0",
     "@types/lodash-es": "^4.17.6",
     "typescript": "^4.8.4"
   },
@@ -48,5 +48,6 @@
   "scripts": {
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/areconnectedthroughproperties.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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/areconnectedthroughproperties
+ */
+/**
+ * Traverses both structures to find out whether there is a reference that is shared between both structures.
+ */
+export default function areConnectedThroughProperties(obj1: object, obj2: object): boolean;

package/src/ckeditorerror.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @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/ckeditorerror
+ */
+/**
+ * URL to the documentation with error codes.
+ */
+export declare const DOCUMENTATION_URL = "https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html";
+/**
+ * The CKEditor error class.
+ *
+ * You should throw `CKEditorError` when:
+ *
+ * * An unexpected situation occurred and the editor (most probably) will not work properly. Such exception will be handled
+ * by the {@link module:watchdog/watchdog~Watchdog watchdog} (if it is integrated),
+ * * If the editor is incorrectly integrated or the editor API is used in the wrong way. This way you will give
+ * feedback to the developer as soon as possible. Keep in mind that for common integration issues which should not
+ * stop editor initialization (like missing upload adapter, wrong name of a toolbar component) we use
+ * {@link module:utils/ckeditorerror~logWarning `logWarning()`} and
+ * {@link module:utils/ckeditorerror~logError `logError()`}
+ * to improve developers experience and let them see the a working editor as soon as possible.
+ *
+ * ```ts
+ * /**
+ *  * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
+ *  *
+ *  * @error plugin-load
+ *  * @param pluginName The name of the plugin that could not be loaded.
+ *  * @param moduleName The name of the module which tried to load this plugin.
+ *  *\/
+ * throw new CKEditorError( 'plugin-load', {
+ * 	pluginName: 'foo',
+ * 	moduleName: 'bar'
+ * } );
+ * ```
+ */
+export default class CKEditorError extends Error {
+    /**
+     * A context of the error by which the Watchdog is able to determine which editor crashed.
+     */
+    readonly context: object | null | undefined;
+    /**
+     * The additional error data passed to the constructor. Undefined if none was passed.
+     */
+    readonly data?: object;
+    /**
+     * Creates an instance of the CKEditorError class.
+     *
+     * @param errorName The error id in an `error-name` format. A link to this error documentation page will be added
+     * to the thrown error's `message`.
+     * @param context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
+     * is able to determine which editor crashed. It should be an editor instance or a property connected to it. It can be also
+     * a `null` value if the editor should not be restarted in case of the error (e.g. during the editor initialization).
+     * The error context should be checked using the `areConnectedThroughProperties( editor, context )` utility
+     * to check if the object works as the context.
+     * @param data Additional data describing the error. A stringified version of this object
+     * will be appended to the error message, so the data are quickly visible in the console. The original
+     * data object will also be later available under the {@link #data} property.
+     */
+    constructor(errorName: string, context?: object | null, data?: object);
+    /**
+     * Checks if the error is of the `CKEditorError` type.
+     */
+    is(type: string): boolean;
+    /**
+     * A utility that ensures that the thrown error is a {@link module:utils/ckeditorerror~CKEditorError} one.
+     * It is useful when combined with the {@link module:watchdog/watchdog~Watchdog} feature, which can restart the editor in case
+     * of a {@link module:utils/ckeditorerror~CKEditorError} error.
+     *
+     * @param err The error to rethrow.
+     * @param context An object connected through properties with the editor instance. This context will be used
+     * by the watchdog to verify which editor should be restarted.
+     */
+    static rethrowUnexpectedError(err: Error, context: object): never;
+}
+/**
+ * Logs a warning to the console with a properly formatted message and adds a link to the documentation.
+ * Use whenever you want to log a warning to the console.
+ *
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ * logWarning( 'toolbarview-item-unavailable', { name } );
+ * ```
+ *
+ * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
+ * a warning or an error to the console.
+ *
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
+ */
+export declare function logWarning(errorName: string, data?: object): void;
+/**
+ * Logs an error to the console with a properly formatted message and adds a link to the documentation.
+ * Use whenever you want to log an error to the console.
+ *
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ *  logError( 'toolbarview-item-unavailable', { name } );
+ * ```
+ *
+ * **Note**: In most cases logging a warning using {@link module:utils/ckeditorerror~logWarning} is enough.
+ *
+ * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
+ *
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
+ */
+export declare function logError(errorName: string, data?: object): void;

package/src/collection.d.ts

@@ -0,0 +1,427 @@
+/**
+ * @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
+ */
+declare const Collection_base: {
+    new (): import("./emittermixin").Emitter;
+    prototype: import("./emittermixin").Emitter;
+};
+/**
+ * Collections are ordered sets of objects. Items in the collection can be retrieved by their indexes
+ * in the collection (like in an array) or by their ids.
+ *
+ * If an object without an `id` property is being added to the collection, the `id` property will be generated
+ * automatically. Note that the automatically generated id is unique only within this single collection instance.
+ *
+ * By default an item in the collection is identified by its `id` property. The name of the identifier can be
+ * configured through the constructor of the collection.
+ *
+ * @typeParam T The type of the collection element.
+ */
+export default class Collection<T extends Record<string, any>> extends Collection_base implements Iterable<T> {
+    /**
+     * The internal list of items in the collection.
+     */
+    private readonly _items;
+    /**
+     * The internal map of items in the collection.
+     */
+    private readonly _itemMap;
+    /**
+     * The name of the property which is considered to identify an item.
+     */
+    private readonly _idProperty;
+    /**
+     * A collection instance this collection is bound to as a result
+     * of calling {@link #bindTo} method.
+     */
+    private _bindToCollection?;
+    /**
+     * A helper mapping external items of a bound collection ({@link #bindTo})
+     * and actual items of this collection. It provides information
+     * necessary to properly remove items bound to another collection.
+     *
+     * See {@link #_bindToInternalToExternalMap}.
+     */
+    private readonly _bindToExternalToInternalMap;
+    /**
+     * A helper mapping items of this collection to external items of a bound collection
+     * ({@link #bindTo}). It provides information necessary to manage the bindings, e.g.
+     * to avoid loops in two–way bindings.
+     *
+     * See {@link #_bindToExternalToInternalMap}.
+     */
+    private readonly _bindToInternalToExternalMap;
+    /**
+     * Stores indexes of skipped items from bound external collection.
+     */
+    private _skippedIndexesFromExternal;
+    /**
+     * Creates a new Collection instance.
+     *
+     * You can pass a configuration object as the argument of the constructor:
+     *
+     * ```ts
+     * const emptyCollection = new Collection<{ name: string }>( { idProperty: 'name' } );
+     * emptyCollection.add( { name: 'John' } );
+     * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
+     * ```
+     *
+     * The collection is empty by default. You can add new items using the {@link #add} method:
+     *
+     * ```ts
+     * const collection = new Collection<{ id: string }>();
+     *
+     * collection.add( { id: 'John' } );
+     * console.log( collection.get( 0 ) ); // -> { id: 'John' }
+     * ```
+     *
+     * @label NO_ITEMS
+     * @param options The options object.
+     * @param options.idProperty The name of the property which is used to identify an item.
+     * Items that do not have such a property will be assigned one when added to the collection.
+     */
+    constructor(options?: {
+        readonly idProperty?: string;
+    });
+    /**
+     * Creates a new Collection instance with specified initial items.
+     *
+     * ```ts
+     * const collection = new Collection<{ id: string }>( [ { id: 'John' }, { id: 'Mike' } ] );
+     *
+     * console.log( collection.get( 0 ) ); // -> { id: 'John' }
+     * console.log( collection.get( 1 ) ); // -> { id: 'Mike' }
+     * console.log( collection.get( 'Mike' ) ); // -> { id: 'Mike' }
+     * ```
+     *
+     * You can always pass a configuration object as the last argument of the constructor:
+     *
+     * ```ts
+     * const nonEmptyCollection = new Collection<{ name: string }>( [ { name: 'John' } ], { idProperty: 'name' } );
+     * nonEmptyCollection.add( { name: 'George' } );
+     * console.log( collection.get( 'George' ) ); // -> { name: 'George' }
+     * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
+     * ```
+     *
+     * @label INITIAL_ITEMS
+     * @param initialItems The initial items of the collection.
+     * @param options The options object.
+     * @param options.idProperty The name of the property which is used to identify an item.
+     * Items that do not have such a property will be assigned one when added to the collection.
+     */
+    constructor(initialItems: Iterable<T>, options?: {
+        readonly idProperty?: string;
+    });
+    /**
+     * The number of items available in the collection.
+     */
+    get length(): number;
+    /**
+     * Returns the first item from the collection or null when collection is empty.
+     */
+    get first(): T | null;
+    /**
+     * Returns the last item from the collection or null when collection is empty.
+     */
+    get last(): T | null;
+    /**
+     * Adds an item into the collection.
+     *
+     * If the item does not have an id, then it will be automatically generated and set on the item.
+     *
+     * @param item
+     * @param index The position of the item in the collection. The item
+     * is pushed to the collection when `index` not specified.
+     * @fires add
+     * @fires change
+     */
+    add(item: T, index?: number): this;
+    /**
+     * Adds multiple items into the collection.
+     *
+     * Any item not containing an id will get an automatically generated one.
+     *
+     * @param items
+     * @param index The position of the insertion. Items will be appended if no `index` is specified.
+     * @fires add
+     * @fires change
+     */
+    addMany(items: Iterable<T>, index?: number): this;
+    /**
+     * Gets an item by its ID or index.
+     *
+     * @param idOrIndex The item ID or index in the collection.
+     * @returns The requested item or `null` if such item does not exist.
+     */
+    get(idOrIndex: string | number): T | null;
+    /**
+     * Returns a Boolean indicating whether the collection contains an item.
+     *
+     * @param itemOrId The item or its ID in the collection.
+     * @returns `true` if the collection contains the item, `false` otherwise.
+     */
+    has(itemOrId: T | string): boolean;
+    /**
+     * Gets an index of an item in the collection.
+     * When an item is not defined in the collection, the index will equal -1.
+     *
+     * @param itemOrId The item or its ID in the collection.
+     * @returns The index of a given item.
+     */
+    getIndex(itemOrId: T | string): number;
+    /**
+     * Removes an item from the collection.
+     *
+     * @param subject The item to remove, its ID or index in the collection.
+     * @returns The removed item.
+     * @fires remove
+     * @fires change
+     */
+    remove(subject: T | number | string): T;
+    /**
+     * Executes the callback for each item in the collection and composes an array or values returned by this callback.
+     *
+     * @typeParam U The result type of the callback.
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The result of mapping.
+     */
+    map<U>(callback: (item: T, index: number) => U, ctx?: any): Array<U>;
+    /**
+     * Finds the first item in the collection for which the `callback` returns a true value.
+     *
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The item for which `callback` returned a true value.
+     */
+    find(callback: (item: T, index: number) => boolean, ctx?: any): T | undefined;
+    /**
+     * Returns an array with items for which the `callback` returned a true value.
+     *
+     * @param callback
+     * @param ctx Context in which the `callback` will be called.
+     * @returns The array with matching items.
+     */
+    filter(callback: (item: T, index: number) => boolean, ctx?: any): Array<T>;
+    /**
+     * Removes all items from the collection and destroys the binding created using
+     * {@link #bindTo}.
+     *
+     * @fires remove
+     * @fires change
+     */
+    clear(): void;
+    /**
+     * Binds and synchronizes the collection with another one.
+     *
+     * The binding can be a simple factory:
+     *
+     * ```ts
+     * class FactoryClass {
+     * 	public label: string;
+     *
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
+     *
+     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
+     * const target = new Collection<FactoryClass>();
+     *
+     * target.bindTo( source ).as( FactoryClass );
+     *
+     * source.add( { label: 'foo' } );
+     * source.add( { label: 'bar' } );
+     *
+     * console.log( target.length ); // 2
+     * console.log( target.get( 1 ).label ); // 'bar'
+     *
+     * source.remove( 0 );
+     * console.log( target.length ); // 1
+     * console.log( target.get( 0 ).label ); // 'bar'
+     * ```
+     *
+     * or the factory driven by a custom callback:
+     *
+     * ```ts
+     * class FooClass {
+     * 	public label: string;
+     *
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
+     *
+     * class BarClass {
+     * 	public label: string;
+     *
+     * 	constructor( data: { label: string } ) {
+     * 		this.label = data.label;
+     * 	}
+     * }
+     *
+     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
+     * const target = new Collection<FooClass | BarClass>();
+     *
+     * target.bindTo( source ).using( ( item ) => {
+     * 	if ( item.label == 'foo' ) {
+     * 		return new FooClass( item );
+     * 	} else {
+     * 		return new BarClass( item );
+     * 	}
+     * } );
+     *
+     * source.add( { label: 'foo' } );
+     * source.add( { label: 'bar' } );
+     *
+     * console.log( target.length ); // 2
+     * console.log( target.get( 0 ) instanceof FooClass ); // true
+     * console.log( target.get( 1 ) instanceof BarClass ); // true
+     * ```
+     *
+     * or the factory out of property name:
+     *
+     * ```ts
+     * const source = new Collection<{ nested: { value: string } }>();
+     * const target = new Collection<{ value: string }>();
+     *
+     * target.bindTo( source ).using( 'nested' );
+     *
+     * source.add( { nested: { value: 'foo' } } );
+     * source.add( { nested: { value: 'bar' } } );
+     *
+     * console.log( target.length ); // 2
+     * console.log( target.get( 0 ).value ); // 'foo'
+     * console.log( target.get( 1 ).value ); // 'bar'
+     * ```
+     *
+     * It's possible to skip specified items by returning null value:
+     *
+     * ```ts
+     * const source = new Collection<{ hidden: boolean }>();
+     * const target = new Collection<{ hidden: boolean }>();
+     *
+     * target.bindTo( source ).using( item => {
+     * 	if ( item.hidden ) {
+     * 		return null;
+     * 	}
+     *
+     * 	return item;
+     * } );
+     *
+     * source.add( { hidden: true } );
+     * source.add( { hidden: false } );
+     *
+     * console.log( source.length ); // 2
+     * console.log( target.length ); // 1
+     * ```
+     *
+     * **Note**: {@link #clear} can be used to break the binding.
+     *
+     * @typeParam S The type of `externalCollection` element.
+     * @param externalCollection A collection to be bound.
+     * @returns The binding chain object.
+     */
+    bindTo<S extends Record<string, any>>(externalCollection: Collection<S>): CollectionBindToChain<S, T>;
+    /**
+     * Finalizes and activates a binding initiated by {@link #bindTo}.
+     *
+     * @param factory A function which produces collection items.
+     */
+    private _setUpBindToBinding;
+    /**
+     * Returns an unique id property for a given `item`.
+     *
+     * The method will generate new id and assign it to the `item` if it doesn't have any.
+     *
+     * @param item Item to be added.
+     */
+    private _getItemIdBeforeAdding;
+    /**
+     * Core {@link #remove} method implementation shared in other functions.
+     *
+     * In contrast this method **does not** fire the {@link #event:change} event.
+     *
+     * @param subject The item to remove, its id or index in the collection.
+     * @returns Returns an array with the removed item and its index.
+     * @fires remove
+     */
+    private _remove;
+    /**
+     * Iterable interface.
+     */
+    [Symbol.iterator](): Iterator<T>;
+}
+/**
+ * Fired when an item is added to the collection.
+ *
+ * @eventName add
+ * @param item The added item.
+ * @param index An index where the addition occurred.
+ */
+export type CollectionAddEvent<T = any> = {
+    name: 'add';
+    args: [item: T, index: number];
+};
+/**
+ * Fired when the collection was changed due to adding or removing items.
+ *
+ * @eventName change
+ * @param data Changed items.
+ */
+export type CollectionChangeEvent<T = any> = {
+    name: 'change';
+    args: [data: CollectionChangeEventData<T>];
+};
+/**
+ * A structure describing the {@link ~Collection#event:change `Collection#change`} event.
+ */
+export type CollectionChangeEventData<T = any> = {
+    /**
+     * A list of added items.
+     */
+    added: Iterable<T>;
+    /**
+     * A list of removed items.
+     */
+    removed: Iterable<T>;
+    /**
+     * An index where the addition or removal occurred.
+     */
+    index: number;
+};
+/**
+ * Fired when an item is removed from the collection.
+ *
+ * @eventName remove
+ * @param item The removed item.
+ * @param index Index from which item was removed.
+ */
+export type CollectionRemoveEvent<T = any> = {
+    name: 'remove';
+    args: [item: T, index: number];
+};
+/**
+ * An object returned by the {@link module:utils/collection~Collection#bindTo `bindTo()`} method
+ * providing functions that specify the type of the binding.
+ *
+ * See the {@link module:utils/collection~Collection#bindTo `bindTo()`} documentation for examples.
+ */
+export interface CollectionBindToChain<S, T> {
+    /**
+     * Creates the class factory binding in which items of the source collection are passed to
+     * the constructor of the specified class.
+     *
+     * @param Class The class constructor used to create instances in the factory.
+     */
+    as(Class: new (item: S) => T): void;
+    /**
+     * Creates a callback or a property binding.
+     *
+     * @param callbackOrProperty When the function is passed, it should return
+     * the collection items. When the string is provided, the property value is used to create the bound collection items.
+     */
+    using(callbackOrProperty: keyof S | ((item: S) => T | null)): void;
+}
+export {};

package/src/comparearrays.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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/comparearrays
+ */
+/**
+ * Compares how given arrays relate to each other. One array can be: same as another array, prefix of another array
+ * or completely different. If arrays are different, first index at which they differ is returned. Otherwise,
+ * a flag specifying the relation is returned. Flags are negative numbers, so whenever a number >= 0 is returned
+ * it means that arrays differ.
+ *
+ * ```ts
+ * compareArrays( [ 0, 2 ], [ 0, 2 ] );		// 'same'
+ * compareArrays( [ 0, 2 ], [ 0, 2, 1 ] );		// 'prefix'
+ * compareArrays( [ 0, 2 ], [ 0 ] );			// 'extension'
+ * compareArrays( [ 0, 2 ], [ 1, 2 ] );		// 0
+ * compareArrays( [ 0, 2 ], [ 0, 1 ] );		// 1
+ * ```
+ *
+ * @param a Array that is compared.
+ * @param b Array to compare with.
+ * @returns How array `a` is related to `b`.
+ */
+export default function compareArrays(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): ArrayRelation | number;
+/**
+ * Array relation.
+ */
+export type ArrayRelation = 'extension' | 'same' | 'prefix';