@ckeditor/ckeditor5-utils 0.0.0-internal-20241017.0

package/src/focustracker.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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
+ */
+declare const FocusTracker_base: import("./mix.js").Mixed<{
+    new (): import("./observablemixin.js").Observable;
+    prototype: import("./observablemixin.js").Observable;
+}, import("./dom/emittermixin.js").DomEmitter>;
+/**
+ * Allows observing a group of `Element`s whether at least one of them is focused.
+ *
+ * Used by the {@link module:core/editor/editor~Editor} in order to track whether the focus is still within the application,
+ * or were used outside of its UI.
+ *
+ * **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `Element`
+ * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
+ * (have e.g. `tabindex="-1"`).
+ *
+ * Check out the {@glink framework/deep-dive/ui/focus-tracking "Deep dive into focus tracking"} guide to learn more.
+ */
+export default class FocusTracker extends /* #__PURE__ */ FocusTracker_base {
+    /**
+     * True when one of the registered elements is focused.
+     *
+     * @readonly
+     * @observable
+     */
+    isFocused: boolean;
+    /**
+     * The currently focused element.
+     *
+     * While {@link #isFocused `isFocused`} remains `true`, the focus can
+     * move between different UI elements. This property tracks those
+     * elements and tells which one is currently focused.
+     *
+     * @readonly
+     * @observable
+     */
+    focusedElement: Element | null;
+    /**
+     * List of registered elements.
+     *
+     * @internal
+     */
+    _elements: Set<Element>;
+    /**
+     * Event loop timeout.
+     */
+    private _nextEventLoopTimeout;
+    constructor();
+    /**
+     * List of registered elements.
+     */
+    get elements(): Array<Element>;
+    /**
+     * Starts tracking the specified element.
+     */
+    add(element: Element): void;
+    /**
+     * Stops tracking the specified element and stops listening on this element.
+     */
+    remove(element: Element): void;
+    /**
+     * Destroys the focus tracker by:
+     * - Disabling all event listeners attached to tracked elements.
+     * - Removing all tracked elements that were previously added.
+     */
+    destroy(): void;
+    /**
+     * Stores currently focused element and set {@link #isFocused} as `true`.
+     */
+    private _focus;
+    /**
+     * Clears currently focused element and set {@link #isFocused} as `false`.
+     * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
+     */
+    private _blur;
+}
+export {};

package/src/focustracker.js

@@ -0,0 +1,101 @@
+/**
+ * @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
+ */
+/* global setTimeout, clearTimeout */
+/**
+ * @module utils/focustracker
+ */
+import DomEmitterMixin from './dom/emittermixin.js';
+import ObservableMixin from './observablemixin.js';
+import CKEditorError from './ckeditorerror.js';
+/**
+ * Allows observing a group of `Element`s whether at least one of them is focused.
+ *
+ * Used by the {@link module:core/editor/editor~Editor} in order to track whether the focus is still within the application,
+ * or were used outside of its UI.
+ *
+ * **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `Element`
+ * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
+ * (have e.g. `tabindex="-1"`).
+ *
+ * Check out the {@glink framework/deep-dive/ui/focus-tracking "Deep dive into focus tracking"} guide to learn more.
+ */
+export default class FocusTracker extends /* #__PURE__ */ DomEmitterMixin(/* #__PURE__ */ ObservableMixin()) {
+    constructor() {
+        super();
+        /**
+         * List of registered elements.
+         *
+         * @internal
+         */
+        this._elements = new Set();
+        /**
+         * Event loop timeout.
+         */
+        this._nextEventLoopTimeout = null;
+        this.set('isFocused', false);
+        this.set('focusedElement', null);
+    }
+    /**
+     * List of registered elements.
+     */
+    get elements() {
+        return Array.from(this._elements.values());
+    }
+    /**
+     * Starts tracking the specified element.
+     */
+    add(element) {
+        if (this._elements.has(element)) {
+            /**
+             * This element is already tracked by {@link module:utils/focustracker~FocusTracker}.
+             *
+             * @error focustracker-add-element-already-exist
+             */
+            throw new CKEditorError('focustracker-add-element-already-exist', this);
+        }
+        this.listenTo(element, 'focus', () => this._focus(element), { useCapture: true });
+        this.listenTo(element, 'blur', () => this._blur(), { useCapture: true });
+        this._elements.add(element);
+    }
+    /**
+     * Stops tracking the specified element and stops listening on this element.
+     */
+    remove(element) {
+        if (element === this.focusedElement) {
+            this._blur();
+        }
+        if (this._elements.has(element)) {
+            this.stopListening(element);
+            this._elements.delete(element);
+        }
+    }
+    /**
+     * Destroys the focus tracker by:
+     * - Disabling all event listeners attached to tracked elements.
+     * - Removing all tracked elements that were previously added.
+     */
+    destroy() {
+        this.stopListening();
+    }
+    /**
+     * Stores currently focused element and set {@link #isFocused} as `true`.
+     */
+    _focus(element) {
+        clearTimeout(this._nextEventLoopTimeout);
+        this.focusedElement = element;
+        this.isFocused = true;
+    }
+    /**
+     * Clears currently focused element and set {@link #isFocused} as `false`.
+     * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
+     */
+    _blur() {
+        clearTimeout(this._nextEventLoopTimeout);
+        this._nextEventLoopTimeout = setTimeout(() => {
+            this.focusedElement = null;
+            this.isFocused = false;
+        }, 0);
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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
+ */
+export { default as env } from './env.js';
+export { default as diff, type DiffResult } from './diff.js';
+export { default as fastDiff } from './fastdiff.js';
+export { default as diffToChanges } from './difftochanges.js';
+export { default as mix } from './mix.js';
+export type { Constructor, Mixed } from './mix.js';
+export { default as EmitterMixin, type Emitter, type BaseEvent, type CallbackOptions, type EmitterMixinDelegateChain, type GetCallback, type GetCallbackOptions, type GetEventInfo, type GetNameOrEventInfo } from './emittermixin.js';
+export { default as EventInfo } from './eventinfo.js';
+export { default as ObservableMixin, type Observable, type DecoratedMethodEvent, type ObservableChangeEvent, type ObservableSetEvent } from './observablemixin.js';
+export { default as CKEditorError, logError, logWarning } from './ckeditorerror.js';
+export { default as ElementReplacer } from './elementreplacer.js';
+export { default as abortableDebounce, type AbortableFunc } from './abortabledebounce.js';
+export { default as count } from './count.js';
+export { default as compareArrays } from './comparearrays.js';
+export { default as createElement } from './dom/createelement.js';
+export { default as Config } from './config.js';
+export { default as isIterable } from './isiterable.js';
+export { default as DomEmitterMixin, type DomEmitter } from './dom/emittermixin.js';
+export { default as findClosestScrollableAncestor } from './dom/findclosestscrollableancestor.js';
+export { default as global } from './dom/global.js';
+export { default as getAncestors } from './dom/getancestors.js';
+export { default as getDataFromElement } from './dom/getdatafromelement.js';
+export { default as getBorderWidths } from './dom/getborderwidths.js';
+export { default as getRangeFromMouseEvent } from './dom/getrangefrommouseevent.js';
+export { default as isText } from './dom/istext.js';
+export { default as Rect, type RectSource } from './dom/rect.js';
+export { default as ResizeObserver } from './dom/resizeobserver.js';
+export { default as setDataInElement } from './dom/setdatainelement.js';
+export { default as toUnit } from './dom/tounit.js';
+export { default as indexOf } from './dom/indexof.js';
+export { default as insertAt } from './dom/insertat.js';
+export { default as isComment } from './dom/iscomment.js';
+export { default as isNode } from './dom/isnode.js';
+export { default as isRange } from './dom/isrange.js';
+export { default as isValidAttributeName } from './dom/isvalidattributename.js';
+export { default as isVisible } from './dom/isvisible.js';
+export { getOptimalPosition, type Options as PositionOptions, type PositioningFunction, type DomPoint } from './dom/position.js';
+export { default as remove } from './dom/remove.js';
+export * from './dom/scroll.js';
+export * from './keyboard.js';
+export * from './language.js';
+export { default as Locale, type LocaleTranslate, type Translations } from './locale.js';
+export { default as Collection, type CollectionAddEvent, type CollectionChangeEvent, type CollectionRemoveEvent } from './collection.js';
+export { default as first } from './first.js';
+export { default as FocusTracker } from './focustracker.js';
+export { default as KeystrokeHandler, type KeystrokeHandlerOptions } from './keystrokehandler.js';
+export { default as toArray, type ArrayOrItem, type ReadonlyArrayOrItem } from './toarray.js';
+export { default as toMap } from './tomap.js';
+export { default as priorities, type PriorityString } from './priorities.js';
+export { default as retry, exponentialDelay } from './retry.js';
+export { default as insertToPriorityArray } from './inserttopriorityarray.js';
+export { default as spliceArray } from './splicearray.js';
+export { default as uid } from './uid.js';
+export { default as delay, type DelayedFunc } from './delay.js';
+export { default as wait } from './wait.js';
+export { default as parseBase64EncodedObject } from './parsebase64encodedobject.js';
+export { default as crc32, type CRCData } from './crc32.js';
+export * from './unicode.js';
+export { default as version, releaseDate } from './version.js';

package/src/index.js

@@ -0,0 +1,65 @@
+/**
+ * @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
+ */
+export { default as env } from './env.js';
+export { default as diff } from './diff.js';
+export { default as fastDiff } from './fastdiff.js';
+export { default as diffToChanges } from './difftochanges.js';
+export { default as mix } from './mix.js';
+export { default as EmitterMixin } from './emittermixin.js';
+export { default as EventInfo } from './eventinfo.js';
+export { default as ObservableMixin } from './observablemixin.js';
+export { default as CKEditorError, logError, logWarning } from './ckeditorerror.js';
+export { default as ElementReplacer } from './elementreplacer.js';
+export { default as abortableDebounce } from './abortabledebounce.js';
+export { default as count } from './count.js';
+export { default as compareArrays } from './comparearrays.js';
+export { default as createElement } from './dom/createelement.js';
+export { default as Config } from './config.js';
+export { default as isIterable } from './isiterable.js';
+export { default as DomEmitterMixin } from './dom/emittermixin.js';
+export { default as findClosestScrollableAncestor } from './dom/findclosestscrollableancestor.js';
+export { default as global } from './dom/global.js';
+export { default as getAncestors } from './dom/getancestors.js';
+export { default as getDataFromElement } from './dom/getdatafromelement.js';
+export { default as getBorderWidths } from './dom/getborderwidths.js';
+export { default as getRangeFromMouseEvent } from './dom/getrangefrommouseevent.js';
+export { default as isText } from './dom/istext.js';
+export { default as Rect } from './dom/rect.js';
+export { default as ResizeObserver } from './dom/resizeobserver.js';
+export { default as setDataInElement } from './dom/setdatainelement.js';
+export { default as toUnit } from './dom/tounit.js';
+export { default as indexOf } from './dom/indexof.js';
+export { default as insertAt } from './dom/insertat.js';
+export { default as isComment } from './dom/iscomment.js';
+export { default as isNode } from './dom/isnode.js';
+export { default as isRange } from './dom/isrange.js';
+export { default as isValidAttributeName } from './dom/isvalidattributename.js';
+export { default as isVisible } from './dom/isvisible.js';
+export { getOptimalPosition } from './dom/position.js';
+export { default as remove } from './dom/remove.js';
+export * from './dom/scroll.js';
+export * from './keyboard.js';
+export * from './language.js';
+export { default as Locale } from './locale.js';
+export { default as Collection } from './collection.js';
+export { default as first } from './first.js';
+export { default as FocusTracker } from './focustracker.js';
+export { default as KeystrokeHandler } from './keystrokehandler.js';
+export { default as toArray } from './toarray.js';
+export { default as toMap } from './tomap.js';
+export { default as priorities } from './priorities.js';
+export { default as retry, exponentialDelay } from './retry.js';
+export { default as insertToPriorityArray } from './inserttopriorityarray.js';
+export { default as spliceArray } from './splicearray.js';
+export { default as uid } from './uid.js';
+export { default as delay } from './delay.js';
+export { default as wait } from './wait.js';
+export { default as parseBase64EncodedObject } from './parsebase64encodedobject.js';
+export { default as crc32 } from './crc32.js';
+export * from './unicode.js';
+export { default as version, releaseDate } from './version.js';

package/src/inserttopriorityarray.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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
+ */
+import { type PriorityString } from './priorities.js';
+/**
+ * @module utils/inserttopriorityarray
+ */
+/**
+ * The priority object descriptor.
+ *
+ * ```ts
+ * const objectWithPriority = {
+ * 	priority: 'high'
+ * }
+ * ```
+ */
+export interface ObjectWithPriority {
+    /**
+     * Priority of the object.
+     */
+    priority: PriorityString;
+}
+/**
+ * Inserts any object with priority at correct index by priority so registered objects are always sorted from highest to lowest priority.
+ *
+ * @param objects Array of objects with priority to insert object to.
+ * @param objectToInsert Object with `priority` property.
+ */
+export default function insertToPriorityArray<T extends ObjectWithPriority>(objects: Array<T>, objectToInsert: T): void;

package/src/inserttopriorityarray.js

@@ -0,0 +1,21 @@
+/**
+ * @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
+ */
+import priorities from './priorities.js';
+/**
+ * Inserts any object with priority at correct index by priority so registered objects are always sorted from highest to lowest priority.
+ *
+ * @param objects Array of objects with priority to insert object to.
+ * @param objectToInsert Object with `priority` property.
+ */
+export default function insertToPriorityArray(objects, objectToInsert) {
+    const priority = priorities.get(objectToInsert.priority);
+    for (let i = 0; i < objects.length; i++) {
+        if (priorities.get(objects[i].priority) < priority) {
+            objects.splice(i, 0, objectToInsert);
+            return;
+        }
+    }
+    objects.push(objectToInsert);
+}

package/src/isiterable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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/isiterable
+ */
+/**
+ * Checks if value implements iterator interface.
+ *
+ * @param value The value to check.
+ * @returns True if value implements iterator interface.
+ */
+export default function isIterable(value: any): value is Iterable<any>;

package/src/isiterable.js

@@ -0,0 +1,16 @@
+/**
+ * @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/isiterable
+ */
+/**
+ * Checks if value implements iterator interface.
+ *
+ * @param value The value to check.
+ * @returns True if value implements iterator interface.
+ */
+export default function isIterable(value) {
+    return !!(value && value[Symbol.iterator]);
+}

package/src/keyboard.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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 set of utilities related to keyboard support.
+ *
+ * @module utils/keyboard
+ */
+import type { LanguageDirection } from './language.js';
+/**
+ * An object with `keyName => keyCode` pairs for a set of known keys.
+ *
+ * Contains:
+ *
+ * * `a-z`,
+ * * `0-9`,
+ * * `f1-f12`,
+ * * `` ` ``, `-`, `=`, `[`, `]`, `;`, `'`, `,`, `.`, `/`, `\`,
+ * * `arrow(left|up|right|bottom)`,
+ * * `backspace`, `delete`, `enter`, `esc`, `tab`,
+ * * `ctrl`, `cmd`, `shift`, `alt`.
+ */
+export declare const keyCodes: {
+    readonly [keyCode: string]: number;
+};
+/**
+ * Converts a key name or {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code.
+ *
+ * Note: Key names are matched with {@link module:utils/keyboard#keyCodes} in a case-insensitive way.
+ *
+ * @param key A key name (see {@link module:utils/keyboard#keyCodes}) or a keystroke data object.
+ * @returns Key or keystroke code.
+ */
+export declare function getCode(key: string | Readonly<KeystrokeInfo>): number;
+/**
+ * Parses the keystroke and returns a keystroke code that will match the code returned by
+ * {@link module:utils/keyboard~getCode} for the corresponding {@link module:utils/keyboard~KeystrokeInfo keystroke info}.
+ *
+ * The keystroke can be passed in two formats:
+ *
+ * * as a single string – e.g. `ctrl + A`,
+ * * as an array of {@link module:utils/keyboard~keyCodes known key names} and key codes – e.g.:
+ *   * `[ 'ctrl', 32 ]` (ctrl + space),
+ *   * `[ 'ctrl', 'a' ]` (ctrl + A).
+ *
+ * Note: Key names are matched with {@link module:utils/keyboard#keyCodes} in a case-insensitive way.
+ *
+ * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not).
+ *
+ * Note: On macOS, keystroke handling is translating the `Ctrl` key to the `Cmd` key and handling only that keystroke.
+ * For example, a registered keystroke `Ctrl+A` will be translated to `Cmd+A` on macOS. To disable the translation of some keystroke,
+ * use the forced modifier: `Ctrl!+A` (note the exclamation mark).
+ *
+ * @param keystroke The keystroke definition.
+ * @returns Keystroke code.
+ */
+export declare function parseKeystroke(keystroke: string | ReadonlyArray<number | string>): number;
+/**
+ * Translates any keystroke string text like `"Ctrl+A"` to an
+ * environment–specific keystroke, i.e. `"⌘A"` on macOS.
+ *
+ * @param keystroke The keystroke text.
+ * @returns The keystroke text specific for the environment.
+ */
+export declare function getEnvKeystrokeText(keystroke: string): string;
+/**
+ * Returns `true` if the provided key code represents one of the arrow keys.
+ *
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
+ */
+export declare function isArrowKeyCode(keyCode: number): boolean;
+/**
+ * String representing a direction of an arrow key kode.
+ */
+export type ArrowKeyCodeDirection = 'left' | 'up' | 'right' | 'down';
+/**
+ * Returns the direction in which the {@link module:engine/model/documentselection~DocumentSelection selection}
+ * will move when the provided arrow key code is pressed considering the language direction of the editor content.
+ *
+ * For instance, in right–to–left (RTL) content languages, pressing the left arrow means moving the selection right (forward)
+ * in the model structure. Similarly, pressing the right arrow moves the selection left (backward).
+ *
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
+ * @param contentLanguageDirection The content language direction, corresponding to
+ * {@link module:utils/locale~Locale#contentLanguageDirection}.
+ * @returns Localized arrow direction or `undefined` for non-arrow key codes.
+ */
+export declare function getLocalizedArrowKeyCodeDirection(keyCode: number, contentLanguageDirection: LanguageDirection): ArrowKeyCodeDirection | undefined;
+/**
+ * Determines if the provided key code moves the {@link module:engine/model/documentselection~DocumentSelection selection}
+ * forward or backward considering the language direction of the editor content.
+ *
+ * For instance, in right–to–left (RTL) languages, pressing the left arrow means moving forward
+ * in the model structure. Similarly, pressing the right arrow moves the selection backward.
+ *
+ * @param keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
+ * @param contentLanguageDirection The content language direction, corresponding to
+ * {@link module:utils/locale~Locale#contentLanguageDirection}.
+ */
+export declare function isForwardArrowKeyCode(keyCode: number, contentLanguageDirection: LanguageDirection): boolean;
+/**
+ * Information about the keystroke.
+ */
+export interface KeystrokeInfo {
+    /**
+     * The [key code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode).
+     */
+    keyCode: number;
+    /**
+     * Whether the <kbd>Alt</kbd> modifier was pressed.
+     */
+    altKey: boolean;
+    /**
+     * Whether the <kbd>Cmd</kbd> modifier was pressed.
+     */
+    metaKey: boolean;
+    /**
+     * Whether the <kbd>Ctrl</kbd> modifier was pressed.
+     */
+    ctrlKey: boolean;
+    /**
+     * Whether the <kbd>Shift</kbd> modifier was pressed.
+     */
+    shiftKey: boolean;
+}