@ckeditor/ckeditor5-utils 39.0.2 → 40.1.0

package/LICENSE.md

@@ -2,7 +2,7 @@ Software License Agreement
 ==========================
 
 **CKEditor&nbsp;5 utilities** – https://github.com/ckeditor/ckeditor5-utils <br>
-Copyright (c) 2003-2023, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
+Copyright (c) 2003–2023, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
 
@@ -13,9 +13,9 @@ Where not otherwise indicated, all CKEditor content is authored by CKSource engi
 
 The following libraries are included in CKEditor under the [MIT license](https://opensource.org/licenses/MIT):
 
-* lodash - Copyright (c) JS Foundation and other contributors https://js.foundation/. Based on Underscore.js, copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors http://underscorejs.org/.
+* Lodash - Copyright (c) JS Foundation and other contributors https://js.foundation/. Based on Underscore.js, copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors http://underscorejs.org/.
 
 Trademarks
 ----------
 
-**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.
+**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "39.0.2",
+  "version": "40.1.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",

package/src/collection.d.ts

@@ -188,6 +188,12 @@ export default class Collection<T extends Record<string, any>> extends Collectio
      * @returns The result of mapping.
      */
     map<U>(callback: (item: T, index: number) => U, ctx?: any): Array<U>;
+    /**
+     * Performs the specified action for each item in the collection.
+     *
+     * @param ctx Context in which the `callback` will be called.
+     */
+    forEach(callback: (item: T, index: number) => unknown, ctx?: any): void;
     /**
      * Finds the first item in the collection for which the `callback` returns a true value.
      *

package/src/collection.js

@@ -198,6 +198,14 @@ export default class Collection extends EmitterMixin() {
     map(callback, ctx) {
         return this._items.map(callback, ctx);
     }
+    /**
+     * Performs the specified action for each item in the collection.
+     *
+     * @param ctx Context in which the `callback` will be called.
+     */
+    forEach(callback, ctx) {
+        this._items.forEach(callback, ctx);
+    }
     /**
      * Finds the first item in the collection for which the `callback` returns a true value.
      *

package/src/config.js

@@ -151,12 +151,13 @@ export default class Config {
  * Clones configuration object or value.
  */
 function cloneConfig(source) {
-    return cloneDeepWith(source, leaveDOMReferences);
+    return cloneDeepWith(source, leaveItemReferences);
 }
 /**
  * A customized function for cloneDeepWith.
- * It will leave references to DOM Elements instead of cloning them.
+ * In case if it's a DOM Element it will leave references to DOM Elements instead of cloning them.
+ * If it's a function it will leave reference to actuall function.
  */
-function leaveDOMReferences(value) {
-    return isElement(value) ? value : undefined;
+function leaveItemReferences(value) {
+    return isElement(value) || typeof value === 'function' ? value : undefined;
 }

package/src/dom/createelement.d.ts

@@ -18,24 +18,6 @@ type SVGElementAttributes = HTMLElementAttributes & {
  * Element or elements that will be added to the created element as children. Strings will be automatically turned into Text nodes.
  */
 type ChildrenElements = Node | string | Iterable<Node | string>;
-/**
- * Creates an HTML element with attributes and children elements.
- *
- * ```ts
- * createElement( document, 'p' ); // <p>
- * createElement( document, 'p', { class: 'foo' } ); // <p class="foo">
- * createElement( document, 'p', null, 'foo' ); // <p>foo</p>
- * createElement( document, 'p', null, [ createElement(...) ] ); // <p><...></p>
- * ```
- *
- * @label HTML_ELEMENT
- * @param doc Document used to create the element.
- * @param name Name of the HTML element.
- * @param attributes Object where keys represent attribute keys and values represent attribute values.
- * @param children Child or any iterable of children. Strings will be automatically turned into Text nodes.
- * @returns HTML element.
- */
-export default function createElement<T extends keyof HTMLElementTagNameMap>(doc: Document, name: T, attributes?: HTMLElementAttributes, children?: ChildrenElements): HTMLElementTagNameMap[T];
 /**
  * Creates an SVG element with attributes and children elements.
  *
@@ -54,4 +36,22 @@ export default function createElement<T extends keyof HTMLElementTagNameMap>(doc
  * @returns SVG element.
  */
 export default function createElement<T extends keyof SVGElementTagNameMap>(doc: Document, name: T, attributes: SVGElementAttributes, children?: ChildrenElements): SVGElementTagNameMap[T];
+/**
+ * Creates an HTML element with attributes and children elements.
+ *
+ * ```ts
+ * createElement( document, 'p' ); // <p>
+ * createElement( document, 'p', { class: 'foo' } ); // <p class="foo">
+ * createElement( document, 'p', null, 'foo' ); // <p>foo</p>
+ * createElement( document, 'p', null, [ createElement(...) ] ); // <p><...></p>
+ * ```
+ *
+ * @label HTML_ELEMENT
+ * @param doc Document used to create the element.
+ * @param name Name of the HTML element.
+ * @param attributes Object where keys represent attribute keys and values represent attribute values.
+ * @param children Child or any iterable of children. Strings will be automatically turned into Text nodes.
+ * @returns HTML element.
+ */
+export default function createElement<T extends keyof HTMLElementTagNameMap>(doc: Document, name: T, attributes?: HTMLElementAttributes, children?: ChildrenElements): HTMLElementTagNameMap[T];
 export {};

package/src/dom/position.d.ts

@@ -8,6 +8,9 @@ import Rect, { type RectSource } from './rect';
  * target in the visually most efficient way, taking various restrictions like viewport or limiter geometry
  * into consideration.
  *
+ * **Note**: If there are no position coordinates found that meet the requirements (arguments of this helper),
+ * `null` is returned.
+ *
  * ```ts
  * // The element which is to be positioned.
  * const element = document.body.querySelector( '#toolbar' );
@@ -68,7 +71,7 @@ import Rect, { type RectSource } from './rect';
  *
  * @param options The input data and configuration of the helper.
  */
-export declare function getOptimalPosition({ element, target, positions, limiter, fitInViewport, viewportOffsetConfig }: Options): Position;
+export declare function getOptimalPosition({ element, target, positions, limiter, fitInViewport, viewportOffsetConfig }: Options): Position | null;
 /**
  * A position object which instances are created and used by the {@link module:utils/dom/position~getOptimalPosition} helper.
  *
@@ -179,7 +182,7 @@ export interface Options {
  * @param viewportRect The rect of the visual browser viewport.
  * @returns When the function returns `null`, it will not be considered by {@link module:utils/dom/position~getOptimalPosition}.
  */
-export type PositioningFunction = (elementRect: Rect, targetRect: Rect, viewportRect: Rect | null) => PositioningFunctionResult | null;
+export type PositioningFunction = (elementRect: Rect, targetRect: Rect, viewportRect: Rect, limiterRect?: Rect) => PositioningFunctionResult | null;
 /**
  * The result of {@link module:utils/dom/position~PositioningFunction}.
  */

package/src/dom/position.js

@@ -8,14 +8,47 @@
 import global from './global';
 import Rect from './rect';
 import getPositionedAncestor from './getpositionedancestor';
-import getBorderWidths from './getborderwidths';
 import { isFunction } from 'lodash-es';
-// @if CK_DEBUG_POSITION // const RectDrawer = require( '@ckeditor/ckeditor5-utils/tests/_utils/rectdrawer' ).default
+// @if CK_DEBUG_POSITION // const {
+// @if CK_DEBUG_POSITION // 	default: RectDrawer,
+// @if CK_DEBUG_POSITION // 	diagonalStylesBlack,
+// @if CK_DEBUG_POSITION // 	diagonalStylesGreen,
+// @if CK_DEBUG_POSITION // 	diagonalStylesRed
+// @if CK_DEBUG_POSITION // } = require( '@ckeditor/ckeditor5-utils/tests/_utils/rectdrawer' );
+// @if CK_DEBUG_POSITION // const TARGET_RECT_STYLE = {
+// @if CK_DEBUG_POSITION // 	outlineWidth: '2px', outlineStyle: 'dashed', outlineColor: 'blue', outlineOffset: '2px'
+// @if CK_DEBUG_POSITION // };
+// @if CK_DEBUG_POSITION // const VISIBLE_TARGET_RECT_STYLE = {
+// @if CK_DEBUG_POSITION //		...diagonalStylesBlack,
+// @if CK_DEBUG_POSITION //		opacity: '1',
+// @if CK_DEBUG_POSITION //		backgroundColor: '#00000033',
+// @if CK_DEBUG_POSITION //		outlineWidth: '2px'
+// @if CK_DEBUG_POSITION // };
+// @if CK_DEBUG_POSITION // const VIEWPORT_RECT_STYLE = {
+// @if CK_DEBUG_POSITION // 	outlineWidth: '2px',
+// @if CK_DEBUG_POSITION // 	outlineOffset: '-2px',
+// @if CK_DEBUG_POSITION // 	outlineStyle: 'solid',
+// @if CK_DEBUG_POSITION // 	outlineColor: 'red'
+// @if CK_DEBUG_POSITION // };
+// @if CK_DEBUG_POSITION // const VISIBLE_LIMITER_RECT_STYLE = {
+// @if CK_DEBUG_POSITION // 	...diagonalStylesGreen,
+// @if CK_DEBUG_POSITION // 	outlineWidth: '2px',
+// @if CK_DEBUG_POSITION // 	outlineOffset: '-2px'
+// @if CK_DEBUG_POSITION // };
+// @if CK_DEBUG_POSITION // const ELEMENT_RECT_STYLE = {
+// @if CK_DEBUG_POSITION // 	outlineWidth: '2px', outlineColor: 'orange', outlineOffset: '-2px'
+// @if CK_DEBUG_POSITION // };
+// @if CK_DEBUG_POSITION // const CHOSEN_POSITION_RECT_STYLE = {
+// @if CK_DEBUG_POSITION // 	opacity: .5, outlineColor: 'magenta', backgroundColor: 'magenta'
+// @if CK_DEBUG_POSITION // };
 /**
  * Calculates the `position: absolute` coordinates of a given element so it can be positioned with respect to the
  * target in the visually most efficient way, taking various restrictions like viewport or limiter geometry
  * into consideration.
  *
+ * **Note**: If there are no position coordinates found that meet the requirements (arguments of this helper),
+ * `null` is returned.
+ *
  * ```ts
  * // The element which is to be positioned.
  * const element = document.body.querySelector( '#toolbar' );
@@ -88,32 +121,56 @@ export function getOptimalPosition({ element, target, positions, limiter, fitInV
         limiter = limiter();
     }
     const positionedElementAncestor = getPositionedAncestor(element);
+    const constrainedViewportRect = getConstrainedViewportRect(viewportOffsetConfig);
     const elementRect = new Rect(element);
-    const targetRect = new Rect(target);
+    const visibleTargetRect = getVisibleViewportIntersectionRect(target, constrainedViewportRect);
     let bestPosition;
+    // @if CK_DEBUG_POSITION // const targetRect = new Rect( target );
     // @if CK_DEBUG_POSITION // RectDrawer.clear();
-    // @if CK_DEBUG_POSITION // RectDrawer.draw( targetRect, { outlineWidth: '5px' }, 'Target' );
-    const viewportRect = fitInViewport && getConstrainedViewportRect(viewportOffsetConfig) || null;
-    const positionOptions = { targetRect, elementRect, positionedElementAncestor, viewportRect };
+    // @if CK_DEBUG_POSITION // RectDrawer.draw( targetRect, TARGET_RECT_STYLE, 'Target' );
+    // @if CK_DEBUG_POSITION // if ( constrainedViewportRect ) {
+    // @if CK_DEBUG_POSITION //		RectDrawer.draw( constrainedViewportRect, VIEWPORT_RECT_STYLE, 'Viewport' );
+    // @if CK_DEBUG_POSITION // }
+    // If the target got cropped by ancestors or went off the screen, positioning does not make any sense.
+    if (!visibleTargetRect || !constrainedViewportRect.getIntersection(visibleTargetRect)) {
+        return null;
+    }
+    // @if CK_DEBUG_POSITION //	RectDrawer.draw( visibleTargetRect, VISIBLE_TARGET_RECT_STYLE, 'VisTgt' );
+    const positionOptions = {
+        targetRect: visibleTargetRect,
+        elementRect,
+        positionedElementAncestor,
+        viewportRect: constrainedViewportRect
+    };
     // If there are no limits, just grab the very first position and be done with that drama.
     if (!limiter && !fitInViewport) {
         bestPosition = new PositionObject(positions[0], positionOptions);
     }
     else {
-        const limiterRect = limiter && new Rect(limiter).getVisible();
-        // @if CK_DEBUG_POSITION // if ( viewportRect ) {
-        // @if CK_DEBUG_POSITION //		RectDrawer.draw( viewportRect, { outlineWidth: '5px' }, 'Viewport' );
-        // @if CK_DEBUG_POSITION // }
-        // @if CK_DEBUG_POSITION // if ( limiter ) {
-        // @if CK_DEBUG_POSITION // 	RectDrawer.draw( limiterRect, { outlineWidth: '5px', outlineColor: 'green' }, 'Visible limiter' );
-        // @if CK_DEBUG_POSITION // }
-        Object.assign(positionOptions, { limiterRect, viewportRect });
+        if (limiter) {
+            const visibleLimiterRect = getVisibleViewportIntersectionRect(limiter, constrainedViewportRect);
+            if (visibleLimiterRect) {
+                positionOptions.limiterRect = visibleLimiterRect;
+                // @if CK_DEBUG_POSITION // RectDrawer.draw( visibleLimiterRect, VISIBLE_LIMITER_RECT_STYLE, 'VisLim' );
+            }
+        }
         // If there's no best position found, i.e. when all intersections have no area because
-        // rects have no width or height, then just use the first available position.
-        bestPosition = getBestPosition(positions, positionOptions) || new PositionObject(positions[0], positionOptions);
+        // rects have no width or height, then just return `null`
+        bestPosition = getBestPosition(positions, positionOptions);
     }
     return bestPosition;
 }
+/**
+ * Returns intersection of visible source `Rect` with Viewport `Rect`. In case when source `Rect` is not visible
+ * or there is no intersection between source `Rect` and Viewport `Rect`, `null` will be returned.
+ */
+function getVisibleViewportIntersectionRect(source, viewportRect) {
+    const visibleSourceRect = new Rect(source).getVisible();
+    if (!visibleSourceRect) {
+        return null;
+    }
+    return visibleSourceRect.getIntersection(viewportRect);
+}
 /**
  * Returns a viewport `Rect` shrunk by the viewport offset config from all sides.
  */
@@ -145,61 +202,30 @@ function getBestPosition(positions, options) {
         // If a such position is found that element is fully contained by the limiter then, obviously,
         // there will be no better one, so finishing.
         if (limiterIntersectionArea === elementRectArea) {
+            // @if CK_DEBUG_POSITION //	RectDrawer.draw( position._rect, CHOSEN_POSITION_RECT_STYLE, [
+            // @if CK_DEBUG_POSITION //		position.name,
+            // @if CK_DEBUG_POSITION //		'100% fit',
+            // @if CK_DEBUG_POSITION //	].join( '\n' ) );
             return position;
         }
         // To maximize both viewport and limiter intersection areas we use distance on _viewportIntersectionArea
         // and _limiterIntersectionArea plane (without sqrt because we are looking for max value).
         const fitFactor = viewportIntersectionArea ** 2 + limiterIntersectionArea ** 2;
+        // @if CK_DEBUG_POSITION //	RectDrawer.draw( position._rect, { opacity: .4 }, [
+        // @if CK_DEBUG_POSITION //		position.name,
+        // @if CK_DEBUG_POSITION //		'Vi=' +  Math.round( viewportIntersectionArea ),
+        // @if CK_DEBUG_POSITION //		'Li=' + Math.round( limiterIntersectionArea )
+        // @if CK_DEBUG_POSITION //	].join( '\n' ) );
         if (fitFactor > maxFitFactor) {
             maxFitFactor = fitFactor;
             bestPosition = position;
         }
     }
+    // @if CK_DEBUG_POSITION // if ( bestPosition ) {
+    // @if CK_DEBUG_POSITION // 	RectDrawer.draw( bestPosition._rect, CHOSEN_POSITION_RECT_STYLE );
+    // @if CK_DEBUG_POSITION // }
     return bestPosition;
 }
-/**
- * For a given absolute Rect coordinates object 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
- * are used in real–life to position elements with `position: absolute`, which are scoped by any positioned
- * (and scrollable) ancestors.
- */
-function shiftRectToCompensatePositionedAncestor(rect, positionedElementAncestor) {
-    const ancestorPosition = getRectForAbsolutePositioning(new Rect(positionedElementAncestor));
-    const ancestorBorderWidths = getBorderWidths(positionedElementAncestor);
-    let moveX = 0;
-    let moveY = 0;
-    // (https://github.com/ckeditor/ckeditor5-ui-default/issues/126)
-    // If there's some positioned ancestor of the panel, then its `Rect` must be taken into
-    // consideration. `Rect` is always relative to the viewport while `position: absolute` works
-    // with respect to that positioned ancestor.
-    moveX -= ancestorPosition.left;
-    moveY -= ancestorPosition.top;
-    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
-    // If there's some positioned ancestor of the panel, not only its position must be taken into
-    // consideration (see above) but also its internal scrolls. Scroll have an impact here because `Rect`
-    // is relative to the viewport (it doesn't care about scrolling), while `position: absolute`
-    // must compensate that scrolling.
-    moveX += positionedElementAncestor.scrollLeft;
-    moveY += positionedElementAncestor.scrollTop;
-    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
-    // If there's some positioned ancestor of the panel, then its `Rect` includes its CSS `borderWidth`
-    // while `position: absolute` positioning does not consider it.
-    // E.g. `{ position: absolute, top: 0, left: 0 }` means upper left corner of the element,
-    // not upper-left corner of its border.
-    moveX -= ancestorBorderWidths.left;
-    moveY -= ancestorBorderWidths.top;
-    rect.moveBy(moveX, moveY);
-}
-/**
- * DOMRect (also Rect) works in a scroll–independent geometry but `position: absolute` doesn't.
- * This function converts Rect to `position: absolute` coordinates.
- */
-function getRectForAbsolutePositioning(rect) {
-    const { scrollX, scrollY } = global.window;
-    return rect.clone().moveBy(scrollX, scrollY);
-}
 /**
  * A position class which instances are created and used by the {@link module:utils/dom/position~getOptimalPosition} helper.
  *
@@ -221,7 +247,7 @@ class PositionObject {
      * @param options.positionedElementAncestor Nearest element ancestor element which CSS position is not "static".
      */
     constructor(positioningFunction, options) {
-        const positioningFunctionOutput = positioningFunction(options.targetRect, options.elementRect, options.viewportRect);
+        const positioningFunctionOutput = positioningFunction(options.targetRect, options.elementRect, options.viewportRect, options.limiterRect);
         // Nameless position for a function that didn't participate.
         if (!positioningFunctionOutput) {
             return;
@@ -229,7 +255,7 @@ class PositionObject {
         const { left, top, name, config } = positioningFunctionOutput;
         this.name = name;
         this.config = config;
-        this._positioningFunctionCorrdinates = { left, top };
+        this._positioningFunctionCoordinates = { left, top };
         this._options = options;
     }
     /**
@@ -252,19 +278,7 @@ class PositionObject {
     get limiterIntersectionArea() {
         const limiterRect = this._options.limiterRect;
         if (limiterRect) {
-            const viewportRect = this._options.viewportRect;
-            if (viewportRect) {
-                // Consider only the part of the limiter which is visible in the viewport. So the limiter is getting limited.
-                const limiterViewportIntersectRect = limiterRect.getIntersection(viewportRect);
-                if (limiterViewportIntersectRect) {
-                    // If the limiter is within the viewport, then check the intersection between that part of the
-                    // limiter and actual position.
-                    return limiterViewportIntersectRect.getIntersectionArea(this._rect);
-                }
-            }
-            else {
-                return limiterRect.getIntersectionArea(this._rect);
-            }
+            return limiterRect.getIntersectionArea(this._rect);
         }
         return 0;
     }
@@ -273,10 +287,7 @@ class PositionObject {
      */
     get viewportIntersectionArea() {
         const viewportRect = this._options.viewportRect;
-        if (viewportRect) {
-            return viewportRect.getIntersectionArea(this._rect);
-        }
-        return 0;
+        return viewportRect.getIntersectionArea(this._rect);
     }
     /**
      * An already positioned element rect. A clone of the element rect passed to the constructor
@@ -286,7 +297,7 @@ class PositionObject {
         if (this._cachedRect) {
             return this._cachedRect;
         }
-        this._cachedRect = this._options.elementRect.clone().moveTo(this._positioningFunctionCorrdinates.left, this._positioningFunctionCorrdinates.top);
+        this._cachedRect = this._options.elementRect.clone().moveTo(this._positioningFunctionCoordinates.left, this._positioningFunctionCoordinates.top);
         return this._cachedRect;
     }
     /**
@@ -296,10 +307,7 @@ class PositionObject {
         if (this._cachedAbsoluteRect) {
             return this._cachedAbsoluteRect;
         }
-        this._cachedAbsoluteRect = getRectForAbsolutePositioning(this._rect);
-        if (this._options.positionedElementAncestor) {
-            shiftRectToCompensatePositionedAncestor(this._cachedAbsoluteRect, this._options.positionedElementAncestor);
-        }
+        this._cachedAbsoluteRect = this._rect.toAbsoluteRect();
         return this._cachedAbsoluteRect;
     }
 }

package/src/dom/rect.d.ts

@@ -117,7 +117,7 @@ export default class Rect {
      */
     getArea(): number;
     /**
-     * Returns a new rect, a part of the original rect, which is actually visible to the user,
+     * Returns a new rect, a part of the original rect, which is actually visible to the user and is relative to the,`body`,
      * e.g. an original rect cropped by parent element rects which have `overflow` set in CSS
      * other than `"visible"`.
      *
@@ -150,6 +150,10 @@ export default class Rect {
      * @returns `true` if contains, `false` otherwise.
      */
     contains(anotherRect: Rect): boolean;
+    /**
+     * Recalculates screen coordinates to coordinates relative to the positioned ancestor offset.
+     */
+    toAbsoluteRect(): Rect;
     /**
      * Excludes scrollbars and CSS borders from the rect.
      *

package/src/dom/rect.js

@@ -9,6 +9,8 @@ import isRange from './isrange';
 import isWindow from './iswindow';
 import getBorderWidths from './getborderwidths';
 import isText from './istext';
+import getPositionedAncestor from './getpositionedancestor';
+import global from './global';
 const rectProperties = ['top', 'right', 'bottom', 'left', 'width', 'height'];
 /**
  * A helper class representing a `ClientRect` object, e.g. value returned by
@@ -141,7 +143,9 @@ export default class Rect {
             return null;
         }
         else {
-            return new Rect(rect);
+            const newRect = new Rect(rect);
+            newRect._source = this._source;
+            return newRect;
         }
     }
     /**
@@ -165,7 +169,7 @@ export default class Rect {
         return this.width * this.height;
     }
     /**
-     * Returns a new rect, a part of the original rect, which is actually visible to the user,
+     * Returns a new rect, a part of the original rect, which is actually visible to the user and is relative to the,`body`,
      * e.g. an original rect cropped by parent element rects which have `overflow` set in CSS
      * other than `"visible"`.
      *
@@ -193,14 +197,47 @@ export default class Rect {
         let absolutelyPositionedChildElement;
         // Check the ancestors all the way up to the <body>.
         while (parent && !isBody(parent)) {
+            const isParentOverflowVisible = getElementOverflow(parent) === 'visible';
             if (child instanceof HTMLElement && getElementPosition(child) === 'absolute') {
                 absolutelyPositionedChildElement = child;
             }
+            const parentElementPosition = getElementPosition(parent);
             // The child will be cropped only if it has `position: absolute` and the parent has `position: relative` + some overflow.
             // Otherwise there's no chance of visual clipping and the parent can be skipped
             // https://github.com/ckeditor/ckeditor5/issues/14107.
-            if (absolutelyPositionedChildElement &&
-                (getElementPosition(parent) !== 'relative' || getElementOverflow(parent) === 'visible')) {
+            //
+            // condition: isParentOverflowVisible
+            // 		+---------------------------+
+            //		| #parent					|
+            //		| (overflow: visible)		|
+            //		|				+-----------+---------------+
+            //		|				| child						|
+            //		|				+-----------+---------------+
+            //		+---------------------------+
+            //
+            // condition: absolutelyPositionedChildElement && parentElementPosition === 'relative' && isParentOverflowVisible
+            // 		+---------------------------+
+            //		| parent					|
+            //		| (position: relative;)		|
+            //		| (overflow: visible;)		|
+            //		|				+-----------+---------------+
+            //		|				| child  					|
+            //		|				| (position: absolute;)		|
+            //		|				+-----------+---------------+
+            //		+---------------------------+
+            //
+            // condition: absolutelyPositionedChildElement && parentElementPosition !== 'relative'
+            // 		+---------------------------+
+            //		| parent					|
+            //		| (position: static;)		|
+            //		|				+-----------+---------------+
+            //		|				| child  					|
+            //		|				| (position: absolute;)		|
+            //		|				+-----------+---------------+
+            //		+---------------------------+
+            if (isParentOverflowVisible ||
+                absolutelyPositionedChildElement && ((parentElementPosition === 'relative' && isParentOverflowVisible) ||
+                    parentElementPosition !== 'relative')) {
                 child = parent;
                 parent = parent.parentNode;
                 continue;
@@ -248,6 +285,20 @@ export default class Rect {
         const intersectRect = this.getIntersection(anotherRect);
         return !!(intersectRect && intersectRect.isEqual(anotherRect));
     }
+    /**
+     * Recalculates screen coordinates to coordinates relative to the positioned ancestor offset.
+     */
+    toAbsoluteRect() {
+        const { scrollX, scrollY } = global.window;
+        const absoluteRect = this.clone().moveBy(scrollX, scrollY);
+        if (isDomElement(absoluteRect._source)) {
+            const positionedAncestor = getPositionedAncestor(absoluteRect._source);
+            if (positionedAncestor) {
+                shiftRectToCompensatePositionedAncestor(absoluteRect, positionedAncestor);
+            }
+        }
+        return absoluteRect;
+    }
     /**
      * Excludes scrollbars and CSS borders from the rect.
      *
@@ -378,11 +429,46 @@ function isDomElement(value) {
  * Returns the value of the `position` style of an `HTMLElement`.
  */
 function getElementPosition(element) {
-    return element.ownerDocument.defaultView.getComputedStyle(element).position;
+    return element instanceof HTMLElement ? element.ownerDocument.defaultView.getComputedStyle(element).position : 'static';
 }
 /**
- * Returns the value of the `overflow` style of an `HTMLElement`.
+ * Returns the value of the `overflow` style of an `HTMLElement` or a `Range`.
  */
 function getElementOverflow(element) {
-    return element.ownerDocument.defaultView.getComputedStyle(element).overflow;
+    return element instanceof HTMLElement ? element.ownerDocument.defaultView.getComputedStyle(element).overflow : 'visible';
+}
+/**
+ * For a given absolute Rect coordinates object 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
+ * are used in real–life to position elements with `position: absolute`, which are scoped by any positioned
+ * (and scrollable) ancestors.
+ */
+function shiftRectToCompensatePositionedAncestor(rect, positionedElementAncestor) {
+    const ancestorPosition = new Rect(positionedElementAncestor);
+    const ancestorBorderWidths = getBorderWidths(positionedElementAncestor);
+    let moveX = 0;
+    let moveY = 0;
+    // (https://github.com/ckeditor/ckeditor5-ui-default/issues/126)
+    // If there's some positioned ancestor of the panel, then its `Rect` must be taken into
+    // consideration. `Rect` is always relative to the viewport while `position: absolute` works
+    // with respect to that positioned ancestor.
+    moveX -= ancestorPosition.left;
+    moveY -= ancestorPosition.top;
+    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
+    // If there's some positioned ancestor of the panel, not only its position must be taken into
+    // consideration (see above) but also its internal scrolls. Scroll have an impact here because `Rect`
+    // is relative to the viewport (it doesn't care about scrolling), while `position: absolute`
+    // must compensate that scrolling.
+    moveX += positionedElementAncestor.scrollLeft;
+    moveY += positionedElementAncestor.scrollTop;
+    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
+    // If there's some positioned ancestor of the panel, then its `Rect` includes its CSS `borderWidth`
+    // while `position: absolute` positioning does not consider it.
+    // E.g. `{ position: absolute, top: 0, left: 0 }` means upper left corner of the element,
+    // not upper-left corner of its border.
+    moveX -= ancestorBorderWidths.left;
+    moveY -= ancestorBorderWidths.top;
+    rect.moveBy(moveX, moveY);
 }

package/src/index.d.ts

@@ -25,9 +25,8 @@ export { default as DomEmitterMixin, type DomEmitter } from './dom/emittermixin'
 export { default as findClosestScrollableAncestor } from './dom/findclosestscrollableancestor';
 export { default as global } from './dom/global';
 export { default as getAncestors } from './dom/getancestors';
-export { default as getElementsIntersectionRect } from './dom/getelementsintersectionrect';
-export { default as getScrollableAncestors } from './dom/getscrollableancestors';
 export { default as getDataFromElement } from './dom/getdatafromelement';
+export { default as getBorderWidths } from './dom/getborderwidths';
 export { default as isText } from './dom/istext';
 export { default as Rect, type RectSource } from './dom/rect';
 export { default as ResizeObserver } from './dom/resizeobserver';

package/src/index.js

@@ -24,9 +24,8 @@ export { default as DomEmitterMixin } from './dom/emittermixin';
 export { default as findClosestScrollableAncestor } from './dom/findclosestscrollableancestor';
 export { default as global } from './dom/global';
 export { default as getAncestors } from './dom/getancestors';
-export { default as getElementsIntersectionRect } from './dom/getelementsintersectionrect';
-export { default as getScrollableAncestors } from './dom/getscrollableancestors';
 export { default as getDataFromElement } from './dom/getdatafromelement';
+export { default as getBorderWidths } from './dom/getborderwidths';
 export { default as isText } from './dom/istext';
 export { default as Rect } from './dom/rect';
 export { default as ResizeObserver } from './dom/resizeobserver';

package/src/keyboard.js

@@ -100,7 +100,7 @@ export function parseKeystroke(keystroke) {
  */
 export function getEnvKeystrokeText(keystroke) {
     let keystrokeCode = parseKeystroke(keystroke);
-    const modifiersToGlyphs = Object.entries(env.isMac ? modifiersToGlyphsMac : modifiersToGlyphsNonMac);
+    const modifiersToGlyphs = Object.entries((env.isMac || env.isiOS) ? modifiersToGlyphsMac : modifiersToGlyphsNonMac);
     const modifiers = modifiersToGlyphs.reduce((modifiers, [name, glyph]) => {
         // Modifier keys are stored as a bit mask so extract those from the keystroke code.
         if ((keystrokeCode & keyCodes[name]) != 0) {
@@ -161,7 +161,7 @@ function getEnvKeyCode(key) {
         return getCode(key.slice(0, -1));
     }
     const code = getCode(key);
-    return env.isMac && code == keyCodes.ctrl ? keyCodes.cmd : code;
+    return (env.isMac || env.isiOS) && code == keyCodes.ctrl ? keyCodes.cmd : code;
 }
 /**
  * Determines if the provided key code moves the {@link module:engine/model/documentselection~DocumentSelection selection}

package/src/splicearray.d.ts

@@ -23,4 +23,4 @@
  *
  * @returns New spliced array.
  */
-export default function spliceArray<T>(target: Array<T>, source: Array<T>, start: number, count: number): Array<T>;
+export default function spliceArray<T>(target: ReadonlyArray<T>, source: ReadonlyArray<T>, start: number, count: number): Array<T>;

package/src/version.d.ts

@@ -2,7 +2,7 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-declare const version = "39.0.2";
+declare const version = "40.1.0";
 export default version;
 export declare const releaseDate: Date;
 declare global {

package/src/version.js

@@ -6,10 +6,10 @@
  * @module utils/version
  */
 import CKEditorError from './ckeditorerror';
-const version = '39.0.2';
+const version = '40.1.0';
 export default version;
 // The second argument is not a month. It is `monthIndex` and starts from `0`.
-export const releaseDate = new Date(2023, 8, 6);
+export const releaseDate = new Date(2023, 10, 15);
 /* istanbul ignore next -- @preserve */
 if (globalThis.CKEDITOR_VERSION) {
     /**

package/src/dom/getelementsintersectionrect.d.ts

@@ -1,14 +0,0 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-import Rect from './rect';
-/**
- * Calculates the intersection `Rect` of a given set of elements (and/or a `document`).
- * Also, takes into account the viewport top offset configuration.
- *
- * @internal
- * @param elements
- * @param viewportTopOffset
- */
-export default function getElementsIntersectionRect(elements: Array<HTMLElement | Document>, viewportTopOffset?: number): Rect | null;

package/src/dom/getelementsintersectionrect.js

@@ -1,43 +0,0 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module utils/dom/getelementsintersectionrect
- */
-import global from './global';
-import Rect from './rect';
-/**
- * Calculates the intersection `Rect` of a given set of elements (and/or a `document`).
- * Also, takes into account the viewport top offset configuration.
- *
- * @internal
- * @param elements
- * @param viewportTopOffset
- */
-export default function getElementsIntersectionRect(elements, viewportTopOffset = 0) {
-    const elementRects = elements.map(element => {
-        // The document (window) is yet another "element", but cropped by the top offset.
-        if (element instanceof Document) {
-            const windowRect = new Rect(global.window);
-            windowRect.top += viewportTopOffset;
-            windowRect.height -= viewportTopOffset;
-            return windowRect;
-        }
-        else {
-            return new Rect(element);
-        }
-    });
-    let intersectionRect = elementRects[0];
-    // @if CK_DEBUG_GETELEMENTSINTERSECTIONRECT // for ( const rect of elementRects ) {
-    // @if CK_DEBUG_GETELEMENTSINTERSECTIONRECT // 	RectDrawer.draw( rect, {
-    // @if CK_DEBUG_GETELEMENTSINTERSECTIONRECT // 		outlineWidth: '1px', opacity: '.7', outlineStyle: 'dashed'
-    // @if CK_DEBUG_GETELEMENTSINTERSECTIONRECT // 	}, 'Scrollable element' );
-    // @if CK_DEBUG_GETELEMENTSINTERSECTIONRECT // }
-    for (const rect of elementRects.slice(1)) {
-        if (intersectionRect) {
-            intersectionRect = intersectionRect.getIntersection(rect);
-        }
-    }
-    return intersectionRect;
-}

package/src/dom/getscrollableancestors.d.ts

@@ -1,14 +0,0 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * Loops over the given element's ancestors to find all the scrollable elements.
- *
- * **Note**: The `document` is always included in the returned array.
- *
- * @internal
- * @param element
- * @returns An array of scrollable element's ancestors (including the `document`).
- */
-export default function getScrollableAncestors(element: HTMLElement): Array<HTMLElement | Document>;

package/src/dom/getscrollableancestors.js

@@ -1,28 +0,0 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module utils/dom/getscrollableancestors
- */
-import global from './global';
-import findClosestScrollableAncestor from './findclosestscrollableancestor';
-/**
- * Loops over the given element's ancestors to find all the scrollable elements.
- *
- * **Note**: The `document` is always included in the returned array.
- *
- * @internal
- * @param element
- * @returns An array of scrollable element's ancestors (including the `document`).
- */
-export default function getScrollableAncestors(element) {
-    const scrollableAncestors = [];
-    let scrollableAncestor = findClosestScrollableAncestor(element);
-    while (scrollableAncestor && scrollableAncestor !== global.document.body) {
-        scrollableAncestors.push(scrollableAncestor);
-        scrollableAncestor = findClosestScrollableAncestor(scrollableAncestor);
-    }
-    scrollableAncestors.push(global.document);
-    return scrollableAncestors;
-}