@ckeditor/ckeditor5-utils 38.2.0-alpha.0 → 39.0.0

package/README.md

@@ -4,7 +4,6 @@ CKEditor 5 utilities
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-utils.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)
 [![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
 [![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
-![Dependency Status](https://img.shields.io/librariesio/release/npm/@ckeditor/ckeditor5-utils)
 
 Various utilities used by CKEditor 5 and its features. This is a sort of  CKEditor 5's standard library.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "38.2.0-alpha.0",
+  "version": "39.0.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -10,9 +10,8 @@
     "ckeditor5-dll"
   ],
   "main": "src/index.js",
-  "type": "module",
   "dependencies": {
-    "lodash-es": "^4.17.15"
+    "lodash-es": "4.17.21"
   },
   "engines": {
     "node": ">=16.0.0",

package/src/dom/getelementsintersectionrect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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 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

@@ -0,0 +1,42 @@
+/**
+ * @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 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

@@ -0,0 +1,14 @@
+/**
+ * @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

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

package/src/dom/scroll.d.ts

@@ -66,6 +66,8 @@ export declare function scrollViewportToShowTarget<T extends boolean, U extends
  * @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.
  */
-export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number): void;
+export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number, limiterElement?: HTMLElement): void;
 export {};

package/src/dom/scroll.js

@@ -124,13 +124,16 @@ export function scrollViewportToShowTarget({ target, viewportOffset = 0, ancesto
  * @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.
  */
-export function scrollAncestorsToShowTarget(target, ancestorOffset) {
+export function scrollAncestorsToShowTarget(target, ancestorOffset, limiterElement) {
     const targetParent = getParentElement(target);
     scrollAncestorsToShowRect({
         parent: targetParent,
         getRect: () => new Rect(target),
-        ancestorOffset
+        ancestorOffset,
+        limiterElement
     });
 }
 /**
@@ -246,12 +249,14 @@ function scrollWindowToShowRect({ window, rect, alignToTop, forceScroll, viewpor
  * anyway.
  * @param options.forceScroll When set `true`, the `rect` 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`
+ * @param options.limiterElement The outermost ancestor that should be scrolled. Defaults to the `<body>` element.
  */
-function scrollAncestorsToShowRect({ parent, getRect, alignToTop, forceScroll, ancestorOffset = 0 }) {
+function scrollAncestorsToShowRect({ parent, getRect, alignToTop, forceScroll, ancestorOffset = 0, limiterElement }) {
     const parentWindow = getWindow(parent);
     const forceScrollToTop = alignToTop && forceScroll;
     let parentRect, targetRect, targetFitsInTarget;
-    while (parent != parentWindow.document.body) {
+    const limiter = limiterElement || parentWindow.document.body;
+    while (parent != limiter) {
         targetRect = getRect();
         parentRect = new Rect(parent).excludeScrollbarsAndBorders();
         targetFitsInTarget = parentRect.contains(targetRect);

package/src/focustracker.d.ts

@@ -39,8 +39,10 @@ export default class FocusTracker extends FocusTracker_base {
     focusedElement: Element | null;
     /**
      * List of registered elements.
+     *
+     * @internal
      */
-    private _elements;
+    _elements: Set<Element>;
     /**
      * Event loop timeout.
      */

package/src/focustracker.js

@@ -26,6 +26,8 @@ export default class FocusTracker extends DomEmitterMixin(ObservableMixin()) {
         super();
         /**
          * List of registered elements.
+         *
+         * @internal
          */
         this._elements = new Set();
         /**

package/src/index.d.ts

@@ -25,6 +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 isText } from './dom/istext';
 export { default as Rect, type RectSource } from './dom/rect';
@@ -38,7 +40,7 @@ export { default as isNode } from './dom/isnode';
 export { default as isRange } from './dom/isrange';
 export { default as isValidAttributeName } from './dom/isvalidattributename';
 export { default as isVisible } from './dom/isvisible';
-export { getOptimalPosition, type Options as PositionOptions, type PositioningFunction } from './dom/position';
+export { getOptimalPosition, type Options as PositionOptions, type PositioningFunction, type Position } from './dom/position';
 export { default as remove } from './dom/remove';
 export * from './dom/scroll';
 export * from './keyboard';

package/src/index.js

@@ -24,6 +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 isText } from './dom/istext';
 export { default as Rect } from './dom/rect';

package/src/observablemixin.d.ts

@@ -531,6 +531,8 @@ interface SingleBindChain<TKey extends string, TVal> {
     to<O1 extends Observable, K1 extends keyof O1, O2 extends Observable, K2 extends keyof O2, O3 extends Observable, K3 extends keyof O3>(observable1: O1, key1: K1, observable2: O2, key2: K2, observable3: O3, key3: K3, callback: (value1: O1[K1], value2: O2[K2], value3: O3[K3]) => TVal): void;
     to<O1 extends ObservableWithProperty<TKey>, O2 extends ObservableWithProperty<TKey>, O3 extends ObservableWithProperty<TKey>, O4 extends ObservableWithProperty<TKey>>(observable1: O1, observable2: O2, observable3: O3, observable4: O4, callback: (value1: O1[TKey], value2: O2[TKey], value3: O3[TKey], value4: O4[TKey]) => TVal): void;
     to<O1 extends Observable, K1 extends keyof O1, O2 extends Observable, K2 extends keyof O2, O3 extends Observable, K3 extends keyof O3, O4 extends Observable, K4 extends keyof O4>(observable1: O1, key1: K1, observable2: O2, key2: K2, observable3: O3, key3: K3, observable4: O4, key4: K4, callback: (value1: O1[K1], value2: O2[K2], value3: O3[K3], value4: O4[K4]) => TVal): void;
+    to<O1 extends ObservableWithProperty<TKey>, O2 extends ObservableWithProperty<TKey>, O3 extends ObservableWithProperty<TKey>, O4 extends ObservableWithProperty<TKey>, O5 extends ObservableWithProperty<TKey>>(observable1: O1, observable2: O2, observable3: O3, observable4: O4, observable5: O5, callback: (value1: O1[TKey], value2: O2[TKey], value3: O3[TKey], value4: O4[TKey], value5: O5[TKey]) => TVal): void;
+    to<O1 extends Observable, K1 extends keyof O1, O2 extends Observable, K2 extends keyof O2, O3 extends Observable, K3 extends keyof O3, O4 extends Observable, K4 extends keyof O4, O5 extends Observable, K5 extends keyof O5>(observable1: O1, key1: K1, observable2: O2, key2: K2, observable3: O3, key3: K3, observable4: O4, key4: K4, observable5: O5, key5: K5, callback: (value1: O1[K1], value2: O2[K2], value3: O3[K3], value4: O4[K4], value5: O5[K5]) => TVal): void;
 }
 /**
  * A helper type that can be used as a constraint, ensuring the type is both observable and have the given property.

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 = "38.2.0-alpha.0";
+declare const version = "39.0.0";
 export default version;
 export declare const releaseDate: Date;
 declare global {

package/src/version.js

@@ -7,10 +7,10 @@
  */
 /* globals window, global */
 import CKEditorError from './ckeditorerror';
-const version = '38.2.0-alpha.0';
+const version = '39.0.0';
 export default version;
 // The second argument is not a month. It is `monthIndex` and starts from `0`.
-export const releaseDate = new Date(2023, 5, 29);
+export const releaseDate = new Date(2023, 7, 2);
 /* istanbul ignore next -- @preserve */
 const windowOrGlobal = typeof window === 'object' ? window : global;
 /* istanbul ignore next -- @preserve */