@ckeditor/ckeditor5-utils 49.0.1 → 49.1.0-alpha.0

package/dist/dom/domtargetslistener.d.ts

@@ -0,0 +1,111 @@
+/**
+* @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/domtargetslistener
+*/
+import { type DomEmitter, type DomEventMap } from "./emittermixin.js";
+import { type CallbackOptions } from "../emittermixin.js";
+import { type EventInfo } from "../eventinfo.js";
+/**
+* Keeps `emitter`'s callback attached to exactly the DOM event targets returned by `getTargets()`, for code whose
+* targets are known only later or change over time.
+*
+* To listen to the events of the whole editor UI, use {@link module:utils/dom/shadowrootregistry~listenToEventRoots}
+* instead, which follows the editor's {@link module:utils/dom/shadowrootregistry~ShadowRootRegistry registry} on its own.
+* Use this listener for particular elements, such as the positioning target of a balloon or the limiter of a sticky
+* panel: return `document` and their {@link module:utils/dom/geteventroots~getEventRoots event roots} from `getTargets()`.
+* Unlike the registry listeners, it does not listen to `document` on its own.
+*
+* The targets are read once, when the listener is created. Call {@link #refresh} whenever they may have changed:
+* it calls `getTargets()` again, attaches the callback to the targets that appeared and detaches it from the targets
+* that disappeared, leaving the others alone. Call {@link #destroy} to detach the callback from every target:
+*
+* ```ts
+* const scrollListener = new DomTargetsListener( () => [ document, ...getEventRoots( limiterElement ) ], {
+* 	emitter: view,
+* 	event: 'scroll',
+* 	listenerOptions: { useCapture: true },
+* 	callback: onScroll
+* } );
+*
+* // For example once the limiter was moved to another shadow root.
+* scrollListener.refresh();
+*
+* // For example when the view is destroyed.
+* scrollListener.destroy();
+* ```
+*
+* Only this callback is ever detached, so other listeners of the same emitter on the same targets are not affected.
+*/
+export declare class DomTargetsListener<TEvent extends keyof DomEventMap = keyof DomEventMap> {
+	/**
+	* Returns the targets that should be listened to.
+	*/
+	private readonly _getTargets;
+	/**
+	* The emitter the callback is attached with.
+	*/
+	private readonly _emitter;
+	/**
+	* The DOM event the callback is attached to.
+	*/
+	private readonly _event;
+	/**
+	* The callback attached to each target.
+	*/
+	private readonly _callback;
+	/**
+	* The options the callback is attached with.
+	*/
+	private readonly _listenerOptions;
+	/**
+	* The targets the callback is currently attached to.
+	*/
+	private readonly _attachedTargets;
+	/**
+	* Creates the listener and attaches the callback to the targets returned by `getTargets()`.
+	*
+	* @param getTargets Returns the targets that should be listened to. `null` and `undefined` entries are skipped.
+	* @param options Describes the listener to attach to each target.
+	*/
+	constructor(getTargets: () => Iterable<EventTarget | null | undefined>, { emitter, event, listenerOptions, callback }: DomTargetsListenerOptions<TEvent>);
+	/**
+	* Reads the targets again: attaches the callback to the targets that appeared and detaches it from the targets that
+	* disappeared.
+	*/
+	refresh(): void;
+	/**
+	* Detaches the callback from every target.
+	*/
+	destroy(): void;
+	/**
+	* Attaches the callback to exactly the given targets.
+	*/
+	private _attachTo;
+}
+/**
+* The listener that {@link ~DomTargetsListener} and the registry helpers attach to each DOM event target.
+*/
+export interface DomTargetsListenerOptions<TEvent extends keyof DomEventMap> {
+	/**
+	* The emitter to which this behavior should be added.
+	*/
+	emitter: DomEmitter;
+	/**
+	* The DOM event to listen to.
+	*/
+	event: TEvent;
+	/**
+	* Listener options, passed through to `DomEmitter#listenTo()`.
+	*/
+	listenerOptions?: CallbackOptions & {
+		useCapture?: boolean;
+		usePassive?: boolean;
+	};
+	/**
+	* The event handler.
+	*/
+	callback: (evt: EventInfo, domEvent: DomEventMap[TEvent]) => void;
+}

package/dist/dom/geteventroots.d.ts

@@ -0,0 +1,18 @@
+/**
+* @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
+*/
+/**
+* Returns every event root of the given node: the shadow roots it renders in, innermost first, followed by
+* the document it is connected to.
+*
+* For code that listens to the DOM events of a node, which a listener on `document` alone may miss: events that
+* are not `composed`, such as `scroll`, never leave the shadow root they started in, and the events that do are
+* retargeted to the shadow host. Works for open and closed roots alike.
+*
+* Like {@link module:utils/dom/getshadowroots~getShadowRoots}, it reports the shadow roots of a detached node too.
+* The document is only included while the node is connected to it. Empty for `null`.
+*
+* @param node The node to collect the event roots of.
+*/
+export declare function getEventRoots(node: Node | null): Array<Document | ShadowRoot>;

package/dist/dom/isprocessinginstruction.d.ts

@@ -0,0 +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
+*/
+/**
+* @module utils/dom/isprocessinginstruction
+*/
+/**
+* Checks whether the object is a native DOM Processing Instruction node.
+*/
+export declare function isProcessingInstruction(obj: any): obj is ProcessingInstruction;

package/dist/dom/shadowrootregistry.d.ts

@@ -2,21 +2,24 @@
 * @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";
+import { type DomTargetsListenerOptions } from "./domtargetslistener.js";
+import { type EmitterMixinConstructor } from "../emittermixin.js";
+import { type DomEventMap } from "./emittermixin.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.
+*
+* It also keeps track of the wider set of the {@link #getEventRoots event roots} of those nodes – the shadow roots
+* plus the documents the nodes are connected to – for consumers that listen to DOM events of those nodes.
 */
 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}.
+	* The event roots of each registered node, as of the last time that node was looked at: the shadow roots hosting
+	* it and the document it is connected to. Empty for a node that was detached 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 #getEventRoots}, and its shadow roots are {@link #getShadowRoots}.
 	*/
 	private _rootsByNode;
 	/**
@@ -24,6 +27,13 @@ export declare class ShadowRootRegistry extends ShadowRootRegistryBase {
 	*/
 	getShadowRoots(): Set<ShadowRoot>;
 	/**
+	* Returns the event roots of the currently registered nodes: every shadow root hosting at least one of them,
+	* as in {@link #getShadowRoots}, and every document at least one of them is connected to.
+	*
+	* See {@link module:utils/dom/geteventroots~getEventRoots} for what an event root is.
+	*/
+	getEventRoots(): Set<Document | 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.
@@ -37,7 +47,8 @@ export declare class ShadowRootRegistry extends ShadowRootRegistryBase {
 	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.
+	* hosting one and {@link #event:remove} for those that stopped. Fires {@link #event:changeEventRoots} if
+	* the {@link #getEventRoots event roots} changed.
 	*
 	* 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:
@@ -47,14 +58,15 @@ export declare class ShadowRootRegistry extends ShadowRootRegistryBase {
 	refresh(): void;
 	/**
 	* Unregisters every currently registered node at once, firing {@link #event:remove} for every shadow root
-	* that consequently stops being tracked.
+	* that consequently stops being tracked, and {@link #event:changeEventRoots} if any event root was 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.
+	* Fires {@link #event:add} and {@link #event:remove} for the difference between the shadow roots in the given
+	* set of tracked event roots and the current ones, followed by a single {@link #event:changeEventRoots} if
+	* the event roots differ at all.
 	*/
 	private _fireRootChanges;
 }
@@ -75,33 +87,51 @@ export declare class ShadowRootRegistry extends ShadowRootRegistryBase {
 * const stopListening = listenToShadowRoots( editor.ui.shadowRootRegistry, {
 * 	emitter: view,
 * 	event: 'scroll',
-* 	callback: repositionOnScroll,
-* 	listenerOptions: { useCapture: true }
+* 	listenerOptions: { useCapture: true },
+* 	callback: repositionOnScroll
 * } );
 * ```
 *
+* To cover both with a single call, use {@link ~listenToEventRoots} instead.
+*
 * 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.
+* Call the returned function to detach. There is nothing to refresh, as the listener follows the registry on its own.
 *
 * @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;
+export declare function listenToShadowRoots<TEvent extends keyof DomEventMap>(registry: ShadowRootRegistry, options: DomTargetsListenerOptions<TEvent>): () => void;
+/**
+* Attaches `emitter`'s callback to the global `document` and to every {@link ~ShadowRootRegistry#getEventRoots event root}
+* 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.
+*
+* It replaces a pair of a `document` listener and {@link ~listenToShadowRoots}:
+*
+* ```ts
+* const stopListening = listenToEventRoots( editor.ui.shadowRootRegistry, {
+* 	emitter: view,
+* 	event: 'scroll',
+* 	listenerOptions: { useCapture: true },
+* 	callback: repositionOnScroll
+* } );
+* ```
+*
+* The global `document` is always listened to, even if no registered node lives in it, so the callback receives
+* the same events as a listener on `document` would, plus the events of the other event roots. Each root is listened
+* to once, no matter how many registered nodes it hosts.
+*
+* As with {@link ~listenToShadowRoots}, use `useCapture: true` for events that do not bubble, such as `scroll`.
+*
+* Call the returned function to detach. There is nothing to refresh, as the listener follows the registry on its own.
+*
+* @param registry The registry whose event roots should be listened to.
+* @param options Describes the listener to attach to each event root.
+*/
+export declare function listenToEventRoots<TEvent extends keyof DomEventMap>(registry: ShadowRootRegistry, options: DomTargetsListenerOptions<TEvent>): () => void;
 /**
 * Fired when a shadow root starts hosting a registered node.
 *
@@ -122,4 +152,15 @@ export type ShadowRootRegistryRemoveEvent = {
 	name: "remove";
 	args: [root: ShadowRoot];
 };
+/**
+* Fired when the {@link ~ShadowRootRegistry#getEventRoots event roots} of the registered nodes change: a shadow root
+* or a document starts or stops hosting a registered node. Fired once per change, after any {@link ~ShadowRootRegistry#event:add}
+* and {@link ~ShadowRootRegistry#event:remove} events, so read the current roots with {@link ~ShadowRootRegistry#getEventRoots}.
+*
+* @eventName ~ShadowRootRegistry#changeEventRoots
+*/
+export type ShadowRootRegistryChangeEventRootsEvent = {
+	name: "changeEventRoots";
+	args: [];
+};
 export {};

package/dist/index.d.ts

@@ -36,6 +36,8 @@ export { getElementFromPoint } from "./dom/getelementfrompoint.js";
 export { getPositionedAncestor } from "./dom/getpositionedancestor.js";
 export { getActiveElement } from "./dom/getactiveelement.js";
 export { getShadowRoots } from "./dom/getshadowroots.js";
+export { getEventRoots } from "./dom/geteventroots.js";
+export { DomTargetsListener, type DomTargetsListenerOptions } from "./dom/domtargetslistener.js";
 export { getOverlayMountRoot } from "./dom/getoverlaymountroot.js";
 export { adoptGlobalStyleSheet } from "./dom/adoptglobalstylesheet.js";
 export { getParentElement } from "./dom/getparentelement.js";
@@ -51,6 +53,7 @@ export { toUnit, type ToUnitHelper } from "./dom/tounit.js";
 export { indexOf } from "./dom/indexof.js";
 export { insertAt } from "./dom/insertat.js";
 export { isComment } from "./dom/iscomment.js";
+export { isProcessingInstruction } from "./dom/isprocessinginstruction.js";
 export { isDomSelectionBackward } from "./dom/isdomselectionbackward.js";
 export { isOffline } from "./dom/isoffline.js";
 export { isNode } from "./dom/isnode.js";
@@ -58,7 +61,7 @@ export { isRange } from "./dom/isrange.js";
 export { isShadowRoot } from "./dom/isshadowroot.js";
 export { isShadowHostOf } from "./dom/isshadowhostof.js";
 export { whenElementConnected } from "./dom/whenelementconnected.js";
-export { ShadowRootRegistry, listenToShadowRoots, type ShadowRootRegistryAddEvent, type ShadowRootRegistryRemoveEvent } from "./dom/shadowrootregistry.js";
+export { ShadowRootRegistry, listenToShadowRoots, listenToEventRoots, type ShadowRootRegistryAddEvent, type ShadowRootRegistryRemoveEvent, type ShadowRootRegistryChangeEventRootsEvent } from "./dom/shadowrootregistry.js";
 export { isValidAttributeName } from "./dom/isvalidattributename.js";
 export { isVisible } from "./dom/isvisible.js";
 export { getOptimalPosition, getConstrainedViewportRect, type DomOptimalPositionOptions, type PositioningFunction, type DomPoint, type DomPositioningFunctionResult } from "./dom/position.js";