@ckeditor/ckeditor5-utils 0.0.0-internal-20241017.0

package/dist/dom/resizeobserver.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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
+ */
+/**
+ * A helper class which instances allow performing custom actions when native DOM elements are resized.
+ *
+ * ```ts
+ * const editableElement = editor.editing.view.getDomRoot();
+ *
+ * const observer = new ResizeObserver( editableElement, entry => {
+ * 	console.log( 'The editable element has been resized in DOM.' );
+ * 	console.log( entry.target ); // -> editableElement
+ * 	console.log( entry.contentRect.width ); // -> e.g. '423px'
+ * } );
+ * ```
+ *
+ * It uses the [native DOM resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
+ * under the hood.
+ */
+export default class ResizeObserver {
+    /**
+     * The element observed by this observer.
+     */
+    private readonly _element;
+    /**
+     * The callback executed each time {@link #_element} is resized.
+     */
+    private readonly _callback;
+    /**
+     * The single native observer instance shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+     */
+    private static _observerInstance;
+    /**
+     * A mapping of native DOM elements and their callbacks shared across all
+     * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+     */
+    private static _elementCallbacks;
+    /**
+     * Creates an instance of the `ResizeObserver` class.
+     *
+     * @param element A DOM element that is to be observed for resizing. Note that
+     * the element must be visible (i.e. not detached from DOM) for the observer to work.
+     * @param callback A function called when the observed element was resized. It passes
+     * the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
+     * object with information about the resize event.
+     */
+    constructor(element: Element, callback: (entry: ResizeObserverEntry) => void);
+    /**
+     * The element observed by this observer.
+     */
+    get element(): Element;
+    /**
+     * Destroys the observer which disables the `callback` passed to the {@link #constructor}.
+     */
+    destroy(): void;
+    /**
+     * Registers a new resize callback for the DOM element.
+     */
+    private static _addElementCallback;
+    /**
+     * Removes a resize callback from the DOM element. If no callbacks are left
+     * for the element, it removes the element from the native observer.
+     */
+    private static _deleteElementCallback;
+    /**
+     * Returns are registered resize callbacks for the DOM element.
+     */
+    private static _getElementCallbacks;
+    /**
+     * Creates the single native observer shared across all `ResizeObserver` instances.
+     */
+    private static _createObserver;
+}

package/dist/dom/scroll.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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
+ */
+type IfTrue<T> = T extends true ? true : never;
+/**
+ * Makes any page `HTMLElement` or `Range` (`target`) visible inside the browser viewport.
+ * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to
+ * the user. If the `target` is already visible, nothing will happen.
+ *
+ * @param options Additional configuration of the scrolling behavior.
+ * @param options.target A target, which supposed to become visible to the user.
+ * @param options.viewportOffset An offset from the edge of the viewport (in pixels)
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
+ * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
+ * read or edit by the user.
+ * @param options.ancestorOffset An offset from the boundary of scrollable ancestors (if any)
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
+ * by keeping the `target` some distance from the edge of the ancestors and thus making it easier to
+ * read or edit by the user.
+ * @param options.alignToTop When set `true`, the helper will make sure the `target` is scrolled up
+ * to the top boundary of the viewport and/or scrollable ancestors if scrolled up. When not set
+ * (default), the `target` will be revealed by scrolling as little as possible. This option will
+ * not affect `targets` that must be scrolled down because they will appear at the top of the boundary
+ * anyway.
+ *
+ * ```
+ *                                             scrollViewportToShowTarget() with            scrollViewportToShowTarget() with
+ *          Initial state                        alignToTop unset (default)                        alignToTop = true
+ *
+ * ┌────────────────────────────────┬─┐       ┌────────────────────────────────┬─┐        ┌────────────────────────────────┬─┐
+ * │                                │▲│       │                                │▲│        │   [ Target to be revealed ]    │▲│
+ * │                                │ │       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │ │       │                                │█│        │                                │ │
+ * │                                │ │       │                                │█│        │                                │█│
+ * │                                │ │       │                                │ │        │                                │█│
+ * │                                │▼│       │   [ Target to be revealed ]    │▼│        │                                │▼│
+ * └────────────────────────────────┴─┘       └────────────────────────────────┴─┘        └────────────────────────────────┴─┘
+ *
+ *
+ *     [ Target to be revealed ]
+ *```
+ *
+ * @param options.forceScroll When set `true`, the `target` will be aligned to the top of the viewport
+ * and scrollable ancestors whether it is already visible or not. This option will only work when `alignToTop`
+ * is `true`
+ */
+export declare function scrollViewportToShowTarget<T extends boolean, U extends IfTrue<T>>({ target, viewportOffset, ancestorOffset, alignToTop, forceScroll }: {
+    readonly target: HTMLElement | Range;
+    readonly viewportOffset?: number | {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    readonly ancestorOffset?: number;
+    readonly alignToTop?: T;
+    readonly forceScroll?: U;
+}): void;
+/**
+ * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors,
+ * e.g. if they have `overflow: scroll` CSS style.
+ *
+ * @param target A target, which supposed to become visible to the user.
+ * @param ancestorOffset An offset between the target and the boundary of scrollable ancestors
+ * to be maintained while scrolling.
+ * @param limiterElement The outermost ancestor that should be scrolled. If specified, it can prevent
+ * scrolling the whole page.
+ */
+export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number, limiterElement?: HTMLElement): void;
+export {};

package/dist/dom/setdatainelement.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/dom/setdatainelement
+ */
+/**
+ * Sets data in a given element.
+ *
+ * @param el The element in which the data will be set.
+ * @param data The data string.
+ */
+export default function setDataInElement(el: HTMLElement, data: string): void;

package/dist/dom/tounit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/dom/tounit
+ */
+/**
+ * Returns a helper function, which adds a desired trailing
+ * `unit` to the passed value.
+ *
+ * @param unit An unit like "px" or "em".
+ */
+export default function toUnit(unit: string): ToUnitHelper;
+/**
+ * A function, which adds a pre–defined trailing `unit`
+ * to the passed `value`.
+ *
+ * @param value A value to be given the unit.
+ * @returns A value with the trailing unit.
+ */
+export type ToUnitHelper = (value: string | number) => string;

package/dist/elementreplacer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/elementreplacer
+ */
+/**
+ * Utility class allowing to hide existing HTML elements or replace them with given ones in a way that doesn't remove
+ * the original elements from the DOM.
+ */
+export default class ElementReplacer {
+    /**
+     * The elements replaced by {@link #replace} and their replacements.
+     */
+    private _replacedElements;
+    constructor();
+    /**
+     * Hides the `element` and, if specified, inserts the the given element next to it.
+     *
+     * The effect of this method can be reverted by {@link #restore}.
+     *
+     * @param element The element to replace.
+     * @param newElement The replacement element. If not passed, then the `element` will just be hidden.
+     */
+    replace(element: HTMLElement, newElement?: HTMLElement): void;
+    /**
+     * Restores what {@link #replace} did.
+     */
+    restore(): void;
+}

package/dist/emittermixin.d.ts

@@ -0,0 +1,316 @@
+/**
+ * @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/emittermixin
+ */
+import EventInfo from './eventinfo.js';
+import { type PriorityString } from './priorities.js';
+import type { Constructor, Mixed } from './mix.js';
+import './version.js';
+/**
+ * Mixin that injects the {@link ~Emitter events API} into its host.
+ *
+ * This function creates a class that inherits from the provided `base` and implements `Emitter` interface.
+ *
+ * ```ts
+ * class BaseClass { ... }
+ *
+ * class MyClass extends EmitterMixin( BaseClass ) {
+ * 	// This class derives from `BaseClass` and implements the `Emitter` interface.
+ * }
+ * ```
+ *
+ * Read more about the concept of emitters in the:
+ * * {@glink framework/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
+ * section of the {@glink framework/architecture/core-editor-architecture Core editor architecture} guide.
+ * * {@glink framework/deep-dive/event-system Event system} deep-dive guide.
+ *
+ * @label EXTENDS
+ */
+export default function EmitterMixin<Base extends Constructor>(base: Base): Mixed<Base, Emitter>;
+/**
+ * Mixin that injects the {@link ~Emitter events API} into its host.
+ *
+ * This function creates a class that implements `Emitter` interface.
+ *
+ * ```ts
+ * class MyClass extends EmitterMixin() {
+ * 	// This class implements the `Emitter` interface.
+ * }
+ * ```
+ *
+ * Read more about the concept of emitters in the:
+ * * {@glink framework/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
+ * section of the {@glink framework/architecture/core-editor-architecture Core editor architecture} guide.
+ * * {@glink framework/deep-dive/event-system Event system} deep dive guide.
+ *
+ * @label NO_ARGUMENTS
+ */
+export default function EmitterMixin(): {
+    new (): Emitter;
+    prototype: Emitter;
+};
+/**
+ * Emitter/listener interface.
+ *
+ * Can be easily implemented by a class by mixing the {@link module:utils/emittermixin~Emitter} mixin.
+ *
+ * ```ts
+ * class MyClass extends EmitterMixin() {
+ * 	// This class now implements the `Emitter` interface.
+ * }
+ * ```
+ *
+ * Read more about the usage of this interface in the:
+ * * {@glink framework/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
+ * section of the {@glink framework/architecture/core-editor-architecture Core editor architecture} guide.
+ * * {@glink framework/deep-dive/event-system Event system} deep-dive guide.
+ */
+export interface Emitter {
+    /**
+     * Registers a callback function to be executed when an event is fired.
+     *
+     * Shorthand for {@link #listenTo `this.listenTo( this, event, callback, options )`} (it makes the emitter
+     * listen on itself).
+     *
+     * @typeParam TEvent The type descibing the event. See {@link module:utils/emittermixin~BaseEvent}.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
+     */
+    on<TEvent extends BaseEvent>(event: TEvent['name'], callback: GetCallback<TEvent>, options?: GetCallbackOptions<TEvent>): void;
+    /**
+     * Registers a callback function to be executed on the next time the event is fired only. This is similar to
+     * calling {@link #on} followed by {@link #off} in the callback.
+     *
+     * @typeParam TEvent The type descibing the event. See {@link module:utils/emittermixin~BaseEvent}.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
+     */
+    once<TEvent extends BaseEvent>(event: TEvent['name'], callback: GetCallback<TEvent>, options?: GetCallbackOptions<TEvent>): void;
+    /**
+     * Stops executing the callback on the given event.
+     * Shorthand for {@link #stopListening `this.stopListening( this, event, callback )`}.
+     *
+     * @param event The name of the event.
+     * @param callback The function to stop being called.
+     */
+    off(event: string, callback: Function): void;
+    /**
+     * Registers a callback function to be executed when an event is fired in a specific (emitter) object.
+     *
+     * Events can be grouped in namespaces using `:`.
+     * When namespaced event is fired, it additionally fires all callbacks for that namespace.
+     *
+     * ```ts
+     * // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
+     * myEmitter.on( 'myGroup', genericCallback );
+     * myEmitter.on( 'myGroup:myEvent', specificCallback );
+     *
+     * // genericCallback is fired.
+     * myEmitter.fire( 'myGroup' );
+     * // both genericCallback and specificCallback are fired.
+     * myEmitter.fire( 'myGroup:myEvent' );
+     * // genericCallback is fired even though there are no callbacks for "foo".
+     * myEmitter.fire( 'myGroup:foo' );
+     * ```
+     *
+     * An event callback can {@link module:utils/eventinfo~EventInfo#stop stop the event} and
+     * set the {@link module:utils/eventinfo~EventInfo#return return value} of the {@link #fire} method.
+     *
+     * @label BASE_EMITTER
+     * @typeParam TEvent The type describing the event. See {@link module:utils/emittermixin~BaseEvent}.
+     * @param emitter The object that fires the event.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
+     */
+    listenTo<TEvent extends BaseEvent>(emitter: Emitter, event: TEvent['name'], callback: GetCallback<TEvent>, options?: GetCallbackOptions<TEvent>): void;
+    /**
+     * Stops listening for events. It can be used at different levels:
+     *
+     * * To stop listening to a specific callback.
+     * * To stop listening to a specific event.
+     * * To stop listening to all events fired by a specific object.
+     * * To stop listening to all events fired by all objects.
+     *
+     * @label BASE_STOP
+     * @param emitter The object to stop listening to. If omitted, stops it for all objects.
+     * @param event (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it
+     * for all events from `emitter`.
+     * @param callback (Requires the `event`) The function to be removed from the call list for the given
+     * `event`.
+     */
+    stopListening(emitter?: Emitter, event?: string, callback?: Function): void;
+    /**
+     * Fires an event, executing all callbacks registered for it.
+     *
+     * The first parameter passed to callbacks is an {@link module:utils/eventinfo~EventInfo} object,
+     * followed by the optional `args` provided in the `fire()` method call.
+     *
+     * @typeParam TEvent The type describing the event. See {@link module:utils/emittermixin~BaseEvent}.
+     * @param eventOrInfo The name of the event or `EventInfo` object if event is delegated.
+     * @param args Additional arguments to be passed to the callbacks.
+     * @returns By default the method returns `undefined`. However, the return value can be changed by listeners
+     * through modification of the {@link module:utils/eventinfo~EventInfo#return `evt.return`}'s property (the event info
+     * is the first param of every callback).
+     */
+    fire<TEvent extends BaseEvent>(eventOrInfo: GetNameOrEventInfo<TEvent>, ...args: TEvent['args']): GetEventInfo<TEvent>['return'];
+    /**
+     * Delegates selected events to another {@link module:utils/emittermixin~Emitter}. For instance:
+     *
+     * ```ts
+     * emitterA.delegate( 'eventX' ).to( emitterB );
+     * emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
+     * ```
+     *
+     * then `eventX` is delegated (fired by) `emitterB` and `emitterC` along with `data`:
+     *
+     * ```ts
+     * emitterA.fire( 'eventX', data );
+     * ```
+     *
+     * and `eventY` is delegated (fired by) `emitterC` along with `data`:
+     *
+     * ```ts
+     * emitterA.fire( 'eventY', data );
+     * ```
+     *
+     * @param events Event names that will be delegated to another emitter.
+     */
+    delegate(...events: Array<string>): EmitterMixinDelegateChain;
+    /**
+     * Stops delegating events. It can be used at different levels:
+     *
+     * * To stop delegating all events.
+     * * To stop delegating a specific event to all emitters.
+     * * To stop delegating a specific event to a specific emitter.
+     *
+     * @param event The name of the event to stop delegating. If omitted, stops it all delegations.
+     * @param emitter (requires `event`) The object to stop delegating a particular event to.
+     * If omitted, stops delegation of `event` to all emitters.
+     */
+    stopDelegating(event?: string, emitter?: Emitter): void;
+}
+/**
+ * Default type describing any event.
+ *
+ * Every custom event has to be compatible with `BaseEvent`.
+ *
+ * ```ts
+ * type MyEvent = {
+ * 	// In `fire<MyEvent>( name )`, `on<MyEvent>( name )`, `once<MyEvent>( name )` and `listenTo<MyEvent>( name )` calls
+ * 	// the `name` argument will be type-checked to ensure it's `'myEvent'` or have `'myEvent:'` prefix.
+ * 	// Required.
+ * 	name: 'myEvent' | `myEvent:${ string }`;
+ *
+ * 	// In `fire<MyEvent>( name, a, b )` call, `a` and `b` parameters will be type-checked against `number` and `string`.
+ * 	// In `on<MyEvent>`, `once<MyEvent>` and `listenTo<MyEvent>` calls, the parameters of provided callback function
+ * 	// will be automatically inferred as `EventInfo`, `number` and `string`.
+ * 	// Required.
+ * 	args: [ number, string ];
+ *
+ * 	// `fire<MyEvent>` will have return type `boolean | undefined`.
+ * 	// Optional, unknown by default.
+ * 	return: boolean;
+ *
+ * 	// `fire<MyEvent>( eventInfo )` will type-check that `eventInfo` is `MyEventInfo`, not a base `EventInfo` or string.
+ * 	// In `on<MyEvent>`, `once<MyEvent>` and `listenTo<MyEvent>` calls, the first callback parameter will be of this type.
+ * 	// Optional.
+ * 	eventInfo: MyEventInfo;
+ *
+ * 	// In `on<MyEvent>`, `once<MyEvent>` and `listenTo<MyEvent>` calls, the `options` parameter will be of type
+ * 	// `{ myOption?: boolean; priority?: PriorityString }
+ * 	// Optional.
+ * 	callbackOptions: { myOption?: boolean };
+ * };
+ * ```
+ */
+export type BaseEvent = {
+    name: string;
+    args: Array<any>;
+};
+/**
+ * Utility type that gets the `EventInfo` subclass for the given event.
+ */
+export type GetEventInfo<TEvent extends BaseEvent> = TEvent extends {
+    eventInfo: EventInfo;
+} ? TEvent['eventInfo'] : EventInfo<TEvent['name'], (TEvent extends {
+    return: infer TReturn;
+} ? TReturn : unknown)>;
+/**
+ * Utility type that gets the `EventInfo` subclass or event name type for the given event.
+ */
+export type GetNameOrEventInfo<TEvent extends BaseEvent> = TEvent extends {
+    eventInfo: EventInfo;
+} ? TEvent['eventInfo'] : TEvent['name'] | EventInfo<TEvent['name'], (TEvent extends {
+    return: infer TReturn;
+} ? TReturn : unknown)>;
+/**
+ * Utility type that gets the callback type for the given event.
+ */
+export type GetCallback<TEvent extends BaseEvent> = (this: Emitter, ev: GetEventInfo<TEvent>, ...args: TEvent['args']) => void;
+/**
+ * Utility type that gets the callback options for the given event.
+ */
+export type GetCallbackOptions<TEvent extends BaseEvent> = TEvent extends {
+    callbackOptions: infer TOptions;
+} ? TOptions & CallbackOptions : CallbackOptions;
+/**
+ * Additional options for registering a callback.
+ */
+export interface CallbackOptions {
+    /**
+     * The priority of this event callback. The higher
+     * the priority value the sooner the callback will be fired. Events having the same priority are called in the
+     * order they were added.
+     *
+     * @defaultValue `'normal'`
+     */
+    readonly priority?: PriorityString;
+}
+/**
+ * Checks if `listeningEmitter` listens to an emitter with given `listenedToEmitterId` and if so, returns that emitter.
+ * If not, returns `null`.
+ *
+ * @internal
+ * @param listeningEmitter An emitter that listens.
+ * @param listenedToEmitterId Unique emitter id of emitter listened to.
+ */
+export declare function _getEmitterListenedTo(listeningEmitter: Emitter, listenedToEmitterId: string): Emitter | null;
+/**
+ * Sets emitter's unique id.
+ *
+ * **Note:** `_emitterId` can be set only once.
+ *
+ * @internal
+ * @param emitter An emitter for which id will be set.
+ * @param id Unique id to set. If not passed, random unique id will be set.
+ */
+export declare function _setEmitterId(emitter: Emitter, id?: string): void;
+/**
+ * Returns emitter's unique id.
+ *
+ * @internal
+ * @param emitter An emitter which id will be returned.
+ */
+export declare function _getEmitterId(emitter: Emitter): string | undefined;
+/**
+ * The return value of {@link ~Emitter#delegate}.
+ */
+export interface EmitterMixinDelegateChain {
+    /**
+     * Selects destination for {@link module:utils/emittermixin~Emitter#delegate} events.
+     *
+     * @param emitter An `EmitterMixin` instance which is the destination for delegated events.
+     * @param nameOrFunction A custom event name or function which converts the original name string.
+     */
+    to(emitter: Emitter, nameOrFunction?: string | ((name: string) => string)): void;
+}