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

package/dist/index.js

@@ -915,8 +915,8 @@ function formatConsoleArguments(errorName, data) {
 /**
 * @module utils/version
 */
-const version = "49.0.1";
-const releaseDate = new Date(2026, 9, 27);
+const version = "49.1.0-alpha.0";
+const releaseDate = new Date(2026, 9, 28);
 /* v8 ignore next -- @preserve */
 if (globalThis.CKEDITOR_VERSION)
  /**
@@ -2820,6 +2820,138 @@ function getShadowRoots(node) {
 	return shadowRoots;
 }
 
+/**
+* @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/geteventroots
+*/
+/**
+* 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.
+*/
+function getEventRoots(node) {
+	if (!node) return [];
+	const roots = getShadowRoots(node);
+	if (node.nodeType == Node.DOCUMENT_NODE) roots.push(node);
+	else if (node.isConnected) roots.push(node.ownerDocument);
+	return roots;
+}
+
+/**
+* @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
+*/
+/**
+* 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.
+*/
+var DomTargetsListener = class {
+	/**
+	* Returns the targets that should be listened to.
+	*/
+	_getTargets;
+	/**
+	* The emitter the callback is attached with.
+	*/
+	_emitter;
+	/**
+	* The DOM event the callback is attached to.
+	*/
+	_event;
+	/**
+	* The callback attached to each target.
+	*/
+	_callback;
+	/**
+	* The options the callback is attached with.
+	*/
+	_listenerOptions;
+	/**
+	* The targets the callback is currently attached to.
+	*/
+	_attachedTargets = /* @__PURE__ */ new Set();
+	/**
+	* 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, { emitter, event, listenerOptions, callback }) {
+		this._getTargets = getTargets;
+		this._emitter = emitter;
+		this._event = event;
+		this._callback = callback;
+		this._listenerOptions = listenerOptions;
+		this.refresh();
+	}
+	/**
+	* Reads the targets again: attaches the callback to the targets that appeared and detaches it from the targets that
+	* disappeared.
+	*/
+	refresh() {
+		const targets = /* @__PURE__ */ new Set();
+		for (const target of this._getTargets()) if (target) targets.add(target);
+		this._attachTo(targets);
+	}
+	/**
+	* Detaches the callback from every target.
+	*/
+	destroy() {
+		this._attachTo(/* @__PURE__ */ new Set());
+	}
+	/**
+	* Attaches the callback to exactly the given targets.
+	*/
+	_attachTo(targets) {
+		for (const target of this._attachedTargets) if (!targets.has(target)) {
+			this._emitter.stopListening(target, this._event, this._callback);
+			this._attachedTargets.delete(target);
+		}
+		for (const target of targets) if (!this._attachedTargets.has(target)) {
+			this._emitter.listenTo(target, this._event, this._callback, this._listenerOptions);
+			this._attachedTargets.add(target);
+		}
+	}
+};
+
 /**
 * @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
@@ -3464,12 +3596,10 @@ var Rect = class Rect {
 	* Recalculates screen coordinates to coordinates relative to the positioned ancestor offset.
 	*/
 	toAbsoluteRect() {
-		const { scrollX, scrollY } = globalVar.window;
-		const absoluteRect = this.clone().moveBy(scrollX, scrollY);
-		if (isDomElement(absoluteRect._source)) {
-			const positionedAncestor = getPositionedAncestor(absoluteRect._source);
-			if (positionedAncestor) shiftRectToCompensatePositionedAncestor(absoluteRect, positionedAncestor);
-		}
+		const absoluteRect = this.clone();
+		const positionedAncestor = isDomElement(this._source) ? getPositionedAncestor(this._source) : null;
+		if (positionedAncestor) shiftRectToCompensatePositionedAncestor(absoluteRect, positionedAncestor);
+		else absoluteRect.moveBy(globalVar.window.scrollX, globalVar.window.scrollY);
 		return absoluteRect;
 	}
 	/**
@@ -3611,7 +3741,7 @@ function isPositioned(node) {
 	return node instanceof HTMLElement && POSITIONING_VALUES.has(getElementPosition(node));
 }
 /**
-* For a given absolute Rect coordinates object and a positioned element ancestor, it updates its
+* For a given Rect relative to the viewport and a positioned element ancestor, it updates its
 * coordinates that make up for the position and the scroll of the ancestor.
 *
 * This is necessary because while Rects (and DOMRects) are relative to the browser's viewport, their coordinates
@@ -3985,6 +4115,20 @@ function insertAt(parentElement, index, nodeToInsert) {
 	parentElement.insertBefore(nodeToInsert, parentElement.childNodes[index] || null);
 }
 
+/**
+* @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.
+*/
+function isProcessingInstruction(obj) {
+	return obj && obj.nodeType === Node.PROCESSING_INSTRUCTION_NODE;
+}
+
 /**
 * @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
@@ -4079,19 +4223,33 @@ const ShadowRootRegistryBase = /* #__PURE__ */ EmitterMixin();
 * 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.
 */
 var ShadowRootRegistry = class 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}.
 	*/
 	_rootsByNode = /* @__PURE__ */ new Map();
 	/**
 	* Returns the shadow roots currently hosting at least one registered node.
 	*/
 	getShadowRoots() {
+		const roots = /* @__PURE__ */ new Set();
+		for (const root of this.getEventRoots()) if (isShadowRoot(root)) roots.add(root);
+		return roots;
+	}
+	/**
+	* 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() {
 		const roots = /* @__PURE__ */ new Set();
 		for (const nodeRoots of this._rootsByNode.values()) for (const root of nodeRoots) roots.add(root);
 		return roots;
@@ -4104,7 +4262,7 @@ var ShadowRootRegistry = class extends ShadowRootRegistryBase {
 	*/
 	registerNode(node) {
 		if (this._rootsByNode.has(node)) return;
-		const previousRoots = this.getShadowRoots();
+		const previousRoots = this.getEventRoots();
 		this._rootsByNode.set(node, deriveRoots(node));
 		this._fireRootChanges(previousRoots);
 	}
@@ -4114,13 +4272,14 @@ var ShadowRootRegistry = class extends ShadowRootRegistryBase {
 	*/
 	unregisterNode(node) {
 		if (!this._rootsByNode.has(node)) return;
-		const previousRoots = this.getShadowRoots();
+		const previousRoots = this.getEventRoots();
 		this._rootsByNode.delete(node);
 		this._fireRootChanges(previousRoots);
 	}
 	/**
 	* 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:
@@ -4128,29 +4287,38 @@ var ShadowRootRegistry = class extends ShadowRootRegistryBase {
 	* another tree, ends up somewhere its roots were never derived from.
 	*/
 	refresh() {
-		const previousRoots = this.getShadowRoots();
+		const previousRoots = this.getEventRoots();
 		for (const node of this._rootsByNode.keys()) this._rootsByNode.set(node, deriveRoots(node));
 		this._fireRootChanges(previousRoots);
 	}
 	/**
 	* 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() {
-		const previousRoots = this.getShadowRoots();
+		const previousRoots = this.getEventRoots();
 		this._rootsByNode.clear();
 		this._fireRootChanges(previousRoots);
 	}
 	/**
-	* 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.
 	*/
 	_fireRootChanges(previousRoots) {
-		const currentRoots = this.getShadowRoots();
-		for (const root of previousRoots) if (!currentRoots.has(root)) this.fire("remove", root);
-		for (const root of currentRoots) if (!previousRoots.has(root)) this.fire("add", root);
+		const currentRoots = this.getEventRoots();
+		let hasChanged = false;
+		for (const root of previousRoots) if (!currentRoots.has(root)) {
+			hasChanged = true;
+			if (isShadowRoot(root)) this.fire("remove", root);
+		}
+		for (const root of currentRoots) if (!previousRoots.has(root)) {
+			hasChanged = true;
+			if (isShadowRoot(root)) this.fire("add", root);
+		}
+		if (hasChanged) this.fire("changeEventRoots");
 	}
 };
 /**
@@ -4170,55 +4338,80 @@ var ShadowRootRegistry = class 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()`.
-*/
-function listenToShadowRoots(registry, { emitter, event, callback, listenerOptions }) {
-	const attachedRoots = /* @__PURE__ */ new Set();
-	const sync = () => {
-		const currentRoots = registry.getShadowRoots();
-		for (const root of attachedRoots) if (!currentRoots.has(root)) {
-			emitter.stopListening(root, event, callback);
-			attachedRoots.delete(root);
-		}
-		for (const root of currentRoots) if (!attachedRoots.has(root)) {
-			emitter.listenTo(root, event, callback, listenerOptions);
-			attachedRoots.add(root);
-		}
-	};
-	emitter.listenTo(registry, "add", sync);
-	emitter.listenTo(registry, "remove", sync);
-	sync();
+*/
+function listenToShadowRoots(registry, options) {
+	return listenToTrackedRoots(registry, ["add", "remove"], () => registry.getShadowRoots(), options);
+}
+/**
+* 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.
+*/
+function listenToEventRoots(registry, options) {
+	return listenToTrackedRoots(registry, ["changeEventRoots"], () => {
+		const roots = registry.getEventRoots();
+		roots.add(globalVar.document);
+		return roots;
+	}, options);
+}
+/**
+* Keeps `emitter`'s callback attached to exactly the roots returned by `getRoots()`, re-reading them whenever
+* the registry fires one of `registryEvents`.
+*/
+function listenToTrackedRoots(registry, registryEvents, getRoots, options) {
+	const rootsListener = new DomTargetsListener(getRoots, options);
+	const refresh = () => rootsListener.refresh();
+	for (const registryEvent of registryEvents) options.emitter.listenTo(registry, registryEvent, refresh);
 	return () => {
-		emitter.stopListening(registry, "add", sync);
-		emitter.stopListening(registry, "remove", sync);
-		for (const root of attachedRoots) emitter.stopListening(root, event, callback);
-		attachedRoots.clear();
+		for (const registryEvent of registryEvents) options.emitter.stopListening(registry, registryEvent, refresh);
+		rootsListener.destroy();
 	};
 }
 /**
-* The shadow roots a node lives in, or none while it is detached.
+* The event roots a node lives in, or none while it is detached.
 *
 * A detached node still reports the shadow roots of the tree it sits in – those roots exist whether or not their
 * host is in a document – but nothing in them is rendered yet, so there is nothing to listen to or inject into.
 */
 function deriveRoots(node) {
-	return node.isConnected ? getShadowRoots(node) : [];
+	return node.isConnected ? getEventRoots(node) : [];
 }
 
 /**
@@ -7034,5 +7227,5 @@ function tryCastDimensionsToUnit(parentDimensionPx, dimension, targetUnit) {
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
 */
 
-export { CKEditorError, Collection, Config, DOCUMENTATION_URL, DomEmitterMixin, ElementReplacer, EmitterMixin, EventInfo, FocusTracker, KeystrokeHandler, Locale, ObservableMixin, Rect, ResizeObserver, ShadowRootRegistry, ShadowSelection, _clear as _clearTranslations, _clearTrustedTypesCache, _getEmitterId, _getEmitterListenedTo, getUserAgent as _getUserAgent, isAndroid as _isAndroid, isBlink as _isBlink, isGecko as _isGecko, isMac as _isMac, isMediaForcedColors as _isMediaForcedColors, isMotionReduced as _isMotionReduced, isRegExpUnicodePropertySupported as _isRegExpUnicodePropertySupported, isSafari as _isSafari, isWindows as _isWindows, isiOS as _isiOS, _setEmitterId, _translate, _trustedAttributeValue, tryCastDimensionsToUnit as _tryCastDimensionsToUnit, tryParseDimensionWithUnit as _tryParseDimensionWithUnit, _unifyTranslations, abortableDebounce, add, adoptGlobalStyleSheet, areConnectedThroughProperties, collectStylesheets, compareArrays, containsNode, count, crc32, createElement, decodeLicenseKey, delay, diff, diffToChanges, env, exponentialDelay, fastDiff, findClosestScrollableAncestor, first, formatHtml, getActiveElement, getAncestors, getBorderWidths, getCode, getConstrainedViewportRect, getDataFromElement, getElementFromPoint, getEnvKeystrokeText, getLanguageDirection, getLayoutParentElement, getLayoutParentNode, getLocalizedArrowKeyCodeDirection, getOptimalPosition, getOverlayMountRoot, getParentElement, getParentNode, getPositionedAncestor, getRangeFromMouseEvent, getSelection, getShadowRoots, getVisualViewportOffset, globalVar as global, indexOf, insertAt, insertToPriorityArray, isArrowKeyCode, isCombiningMark, isComment, isDomSelectionBackward, isFeatureBlockedByLicenseKey, isForwardArrowKeyCode, isHighSurrogateHalf, isInsideCombinedSymbol, isInsideEmojiSequence, isInsideSurrogatePair, isIterable, isLowSurrogateHalf, isNode, isOffline, isRange, isShadowHostOf, isShadowRoot, isText, isTrustedTypesEnforced, isValidAttributeName, isViewWithFocusTracker, isVisible, isWindow, keyCodes, listenToShadowRoots, logError, logWarning, mapsEqual, nth, objectToMap, parseBase64EncodedObject, parseKeystroke, priorities, releaseDate, remove, retry, scrollAncestorsToShowTarget, scrollViewportToShowTarget, setDataInElement, spliceArray, spy, toArray, toMap, toUnit, trustedHtml, uid, version, wait, whenElementConnected };
+export { CKEditorError, Collection, Config, DOCUMENTATION_URL, DomEmitterMixin, DomTargetsListener, ElementReplacer, EmitterMixin, EventInfo, FocusTracker, KeystrokeHandler, Locale, ObservableMixin, Rect, ResizeObserver, ShadowRootRegistry, ShadowSelection, _clear as _clearTranslations, _clearTrustedTypesCache, _getEmitterId, _getEmitterListenedTo, getUserAgent as _getUserAgent, isAndroid as _isAndroid, isBlink as _isBlink, isGecko as _isGecko, isMac as _isMac, isMediaForcedColors as _isMediaForcedColors, isMotionReduced as _isMotionReduced, isRegExpUnicodePropertySupported as _isRegExpUnicodePropertySupported, isSafari as _isSafari, isWindows as _isWindows, isiOS as _isiOS, _setEmitterId, _translate, _trustedAttributeValue, tryCastDimensionsToUnit as _tryCastDimensionsToUnit, tryParseDimensionWithUnit as _tryParseDimensionWithUnit, _unifyTranslations, abortableDebounce, add, adoptGlobalStyleSheet, areConnectedThroughProperties, collectStylesheets, compareArrays, containsNode, count, crc32, createElement, decodeLicenseKey, delay, diff, diffToChanges, env, exponentialDelay, fastDiff, findClosestScrollableAncestor, first, formatHtml, getActiveElement, getAncestors, getBorderWidths, getCode, getConstrainedViewportRect, getDataFromElement, getElementFromPoint, getEnvKeystrokeText, getEventRoots, getLanguageDirection, getLayoutParentElement, getLayoutParentNode, getLocalizedArrowKeyCodeDirection, getOptimalPosition, getOverlayMountRoot, getParentElement, getParentNode, getPositionedAncestor, getRangeFromMouseEvent, getSelection, getShadowRoots, getVisualViewportOffset, globalVar as global, indexOf, insertAt, insertToPriorityArray, isArrowKeyCode, isCombiningMark, isComment, isDomSelectionBackward, isFeatureBlockedByLicenseKey, isForwardArrowKeyCode, isHighSurrogateHalf, isInsideCombinedSymbol, isInsideEmojiSequence, isInsideSurrogatePair, isIterable, isLowSurrogateHalf, isNode, isOffline, isProcessingInstruction, isRange, isShadowHostOf, isShadowRoot, isText, isTrustedTypesEnforced, isValidAttributeName, isViewWithFocusTracker, isVisible, isWindow, keyCodes, listenToEventRoots, listenToShadowRoots, logError, logWarning, mapsEqual, nth, objectToMap, parseBase64EncodedObject, parseKeystroke, priorities, releaseDate, remove, retry, scrollAncestorsToShowTarget, scrollViewportToShowTarget, setDataInElement, spliceArray, spy, toArray, toMap, toUnit, trustedHtml, uid, version, wait, whenElementConnected };
 //# sourceMappingURL=index.js.map