@ckeditor/ckeditor5-utils 48.8.1-alpha.4 → 49.0.0-alpha.1

package/dist/dom/scroll.d.ts

@@ -1,78 +1,89 @@
 /**
- * @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.
+*
+* **Note**: The ancestor walk crosses shadow DOM boundaries, continuing from the host element of a shadow root
+* instead of stopping at it, so scrollable ancestors in the surrounding document are scrolled too. Works for open
+* and closed shadow roots alike.
+*
+* @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.
+*
+* **Note**: The ancestor walk crosses shadow DOM boundaries, continuing from the host element of a shadow root
+* instead of stopping at it, so scrollable ancestors in the surrounding document are scrolled too. Works for open
+* and closed shadow roots alike.
+*
+* @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,11 @@
 /**
- * @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
- */
-/**
- * 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/shadowrootregistry.d.ts

@@ -0,0 +1,125 @@
+/**
+* @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
+*/
+import { type CallbackOptions, type EmitterMixinConstructor } from "../emittermixin.js";
+import { type DomEmitter, type DomEventMap } from "./emittermixin.js";
+import { type EventInfo } from "../eventinfo.js";
+declare const ShadowRootRegistryBase: EmitterMixinConstructor;
+/**
+* Keeps track of the shadow roots hosting a set of registered DOM nodes (for example an editor UI's editables,
+* toolbars and menu bars, or a feature's own UI), so that consumers can, for instance, inject styles or listeners
+* into every shadow root those nodes currently live in.
+*/
+export declare class ShadowRootRegistry extends ShadowRootRegistryBase {
+	/**
+	* The shadow roots hosting each registered node, as of the last time that node was looked at. Empty for a node
+	* that was detached or lived in the light DOM then. Re-derived for every node by each {@link #refresh}, so a
+	* node that has since been attached, or moved to another tree, is picked up. The union of the values is
+	* {@link #getShadowRoots}.
+	*/
+	private _rootsByNode;
+	/**
+	* Returns the shadow roots currently hosting at least one registered node.
+	*/
+	getShadowRoots(): Set<ShadowRoot>;
+	/**
+	* Registers a node, so the shadow roots hosting it become a part of {@link #getShadowRoots}.
+	*
+	* The node does not have to be attached to the DOM yet; while it is not, it simply contributes no shadow root.
+	* The next {@link #refresh} picks it up once it is attached.
+	*/
+	registerNode(node: Node): void;
+	/**
+	* Unregisters a previously {@link #registerNode registered} node. Shadow roots that no longer host any
+	* registered node stop being a part of {@link #getShadowRoots}.
+	*/
+	unregisterNode(node: Node): void;
+	/**
+	* Re-derives the shadow roots of every registered node, firing {@link #event:add} for the roots that started
+	* hosting one and {@link #event:remove} for those that stopped.
+	*
+	* Call it whenever a registered node may have been attached, detached, or moved – for example on every editor
+	* UI update. Nodes are re-derived rather than resolved once, because the tree a node lives in is not fixed:
+	* an editable mounted by the integrator after the editor was created, or moved into a fullscreen container in
+	* another tree, ends up somewhere its roots were never derived from.
+	*/
+	refresh(): void;
+	/**
+	* Unregisters every currently registered node at once, firing {@link #event:remove} for every shadow root
+	* that consequently stops being tracked.
+	*
+	* @internal
+	*/
+	destroy(): void;
+	/**
+	* Fires {@link #event:add} and {@link #event:remove} for the difference between the given set of tracked
+	* shadow roots and the current one.
+	*/
+	private _fireRootChanges;
+}
+/**
+* Some DOM events never reach a listener on `document` if they originate inside a shadow root — `scroll` and
+* `mouseenter`/`mouseleave`, for instance, do not cross a shadow boundary at all. This function is how code that
+* needs those events anyway reacts to them for every shadow root a registry is currently tracking: it attaches
+* `emitter`'s callback directly to each one tracked by `registry`, and keeps that up to date — attaching to
+* roots that appear later, detaching from roots that disappear — for as long as the returned function is not
+* called.
+*
+* Attach it alongside the `document` listener rather than instead of it — one covers the light DOM, the other
+* each shadow root:
+*
+* ```ts
+* view.listenTo( global.document, 'scroll', repositionOnScroll, { useCapture: true } );
+*
+* const stopListening = listenToShadowRoots( editor.ui.shadowRootRegistry, {
+* 	emitter: view,
+* 	event: 'scroll',
+* 	callback: repositionOnScroll,
+* 	listenerOptions: { useCapture: true }
+* } );
+* ```
+*
+* The `useCapture` above is not incidental. The events this function exists for do not bubble when fired on an
+* element, so a listener on a shadow root only sees one that originates inside that root during the capture
+* phase. Without it the listener is attached but never fires.
+*
+* Call the returned function to detach.
+*
+* @param registry The registry whose shadow roots should be listened to.
+* @param options Describes the listener to attach to each shadow root.
+* @param options.emitter The emitter to which this behavior should be added.
+* @param options.event The DOM event to listen to.
+* @param options.callback The event handler.
+* @param options.listenerOptions Listener options, passed through to `DomEmitter#listenTo()`.
+*/
+export declare function listenToShadowRoots(registry: ShadowRootRegistry, { emitter, event, callback, listenerOptions }: {
+	emitter: DomEmitter;
+	event: keyof DomEventMap;
+	callback: (evt: EventInfo, domEvent: any) => void;
+	listenerOptions?: CallbackOptions & {
+		useCapture?: boolean;
+		usePassive?: boolean;
+	};
+}): () => void;
+/**
+* Fired when a shadow root starts hosting a registered node.
+*
+* @eventName ~ShadowRootRegistry#add
+* @param root The shadow root that started being tracked.
+*/
+export type ShadowRootRegistryAddEvent = {
+	name: "add";
+	args: [root: ShadowRoot];
+};
+/**
+* Fired when a shadow root no longer hosts any registered node.
+*
+* @eventName ~ShadowRootRegistry#remove
+* @param root The shadow root that stopped being tracked.
+*/
+export type ShadowRootRegistryRemoveEvent = {
+	name: "remove";
+	args: [root: ShadowRoot];
+};
+export {};

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/dom/trustedtypes.d.ts

@@ -0,0 +1,65 @@
+/**
+* @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
+*/
+/**
+* Prepares an HTML string for a DOM injection sink, which means any place that turns a string into HTML, for example
+* `innerHTML` or `DOMParser#parseFromString()`:
+*
+* ```ts
+* element.innerHTML = trustedHtml( '<p>Hello world!</p>' );
+* ```
+*
+* An application can tell the browser to reject plain strings in those places, using the `require-trusted-types-for 'script'`
+* CSP directive. A sink then accepts only a `TrustedHTML` object. This function returns such an object when the browser
+* supports Trusted Types, and the string it was given when it does not. TypeScript types every sink as taking a
+* `string`, so the result is typed that way too, whichever it is. That keeps type casts out of the call sites, but it
+* also means the result is not always a real string: pass it to a sink, and do not call string methods on it. For the
+* same reason `+=` never works on a sink: it reads the property, joins the strings and assigns a plain one.
+*
+* An application that enforces Trusted Types must also allow the name of the editor's policy, plus `lit-html` when it
+* loads the premium features, whichever of them it uses:
+*
+* ```
+* Content-Security-Policy: require-trusted-types-for 'script'; trusted-types ckeditor5 lit-html;
+* ```
+*
+* The policy returns the string unchanged, because the editor writes markup that it created itself. It makes the browser
+* accept the assignment, but it cleans nothing, so pass this function only markup that the calling code produced, and
+* never content that came from a user or from a server response. Making sure that the data loaded into the editor is
+* safe stays the job of the application, exactly as before.
+*
+* See the {@glink getting-started/setup/csp#trusted-types Content Security Policy} guide for more information.
+*
+* @param html The HTML string to prepare.
+* @returns A value that can be assigned to a DOM injection sink.
+*/
+export declare function trustedHtml(html: string): string;
+/**
+* Returns `true` if the application enforces Trusted Types with the `require-trusted-types-for 'script'` CSP directive.
+* That is the only case where a DOM injection sink rejects a plain string, so it is also the only case where a feature
+* that writes HTML in code the editor cannot reach, for example inside a third-party library, stops working.
+*/
+export declare function isTrustedTypesEnforced(): boolean;
+/**
+* Prepares the value of an attribute for `setAttribute()`. Under Trusted Types, some attributes accept only the object of
+* a Trusted Type, even in a document that is not displayed: an event handler such as `onclick` takes a `TrustedScript`,
+* `src` of a `<script>` takes a `TrustedScriptURL`, and `srcdoc` of an `<iframe>` takes a `TrustedHTML`. For such an
+* attribute, the editor's policy creates that object from the unchanged value. Any other attribute gets the given string.
+* The browser tells which attribute is which, because the list differs between browsers.
+*
+* Like {@link ~trustedHtml}, it cleans nothing, and its result is typed as a string whichever it is.
+*
+* @internal
+* @param element The element that the attribute is set on.
+* @param attributeName The name of the attribute.
+* @param value The value of the attribute.
+*/
+export declare function _trustedAttributeValue(element: Element, attributeName: string, value: string): string;
+/**
+* Forgets the policy that was created and whether the application enforces Trusted Types, so that both are worked out
+* again. Only tests need it, because a document never changes either answer.
+*
+* @internal
+*/
+export declare function _clearTrustedTypesCache(): void;

package/dist/dom/whenelementconnected.d.ts

@@ -0,0 +1,26 @@
+/**
+* @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
+*/
+/**
+* Calls the callback once the given element is connected to a document, and at most once.
+*
+* For code that has to act on the tree an element lives in – injecting styles, resolving a mount target – but is
+* handed the element before it is mounted. The editable of a `DecoupledEditor`, or of any editor created from a
+* data string, is put in the DOM by the integrator at an arbitrary point in time. An element that is already
+* connected is reported synchronously, so the caller needs no second path for that case.
+*
+* "Connected" means connected to a document: an element in a shadow tree qualifies once that tree's host does,
+* and one in a detached tree never does. It is not a visibility check – the element may be connected while
+* having no box of its own, or while an ancestor is not rendered.
+*
+* The waiting is backed by a {@link module:utils/dom/resizeobserver~ResizeObserver}, so the notification is
+* asynchronous and arrives once the element is rendered. For an element mounted into a `display: none` subtree
+* the callback may therefore run on the mount or only once that subtree is shown, depending on the engine. It
+* runs exactly once either way.
+*
+* @param element The element to wait for.
+* @param callback Called once `element` is connected, or immediately if it already is.
+* @returns Cancels the waiting. Safe to call any number of times, and does nothing once the callback has run.
+*/
+export declare function whenElementConnected(element: HTMLElement, callback: () => void): () => void;

package/dist/elementreplacer.d.ts

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