@ckeditor/ckeditor5-utils 48.2.0 → 48.3.0-alpha.1

package/dist/dom/scroll.d.ts

@@ -1,78 +1,81 @@
 /**
- * @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
- */
+* @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 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;
+* 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.
- * @param alignToTop When set `true`, the function will make sure the `target` is scrolled up
- * to the top boundary of the 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 target elements that must be
- * scrolled down because they will appear at the top of the boundary anyway.
- * @param forceScroll When set `true`, the `target` will be aligned to the top of scrollable ancestors
- * whether it is already visible or not. This option will only work when `alignToTop` is `true`
- */
+* 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.
+* @param alignToTop When set `true`, the function will make sure the `target` is scrolled up
+* to the top boundary of the 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 target elements that must be
+* scrolled down because they will appear at the top of the boundary anyway.
+* @param forceScroll When set `true`, the `target` will be aligned to the top of scrollable ancestors
+* whether it is already visible or not. This option will only work when `alignToTop` is `true`
+*/
 export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number, limiterElement?: HTMLElement, alignToTop?: boolean, forceScroll?: true): void;

package/dist/dom/setdatainelement.d.ts

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

package/dist/dom/tounit.d.ts

@@ -1,22 +1,22 @@
 /**
- * @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
- */
+* @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/dom/tounit
- */
+* @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".
- */
+* Returns a helper function, which adds a desired trailing
+* `unit` to the passed value.
+*
+* @param unit An unit like "px" or "em".
+*/
 export declare 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.
- */
+* 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

@@ -1,31 +1,31 @@
 /**
- * @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
- */
+* @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/elementreplacer
- */
+* @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.
- */
+* 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 declare 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;
+	/**
+	* 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;
 }