@ckeditor/ckeditor5-utils 34.2.0 → 35.0.0

package/src/dom/resizeobserver.js

@@ -1,378 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, 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/resizeobserver
- */
-
-/* globals setTimeout, clearTimeout */
-
-import mix from '../mix';
-import global from './global';
-import Rect from './rect';
-import DomEmitterMixin from './emittermixin';
-
-const RESIZE_CHECK_INTERVAL = 100;
-
-/**
- * A helper class which instances allow performing custom actions when native DOM elements are resized.
- *
- *		const editableElement = editor.editing.view.getDomRoot();
- *
- *		const observer = new ResizeObserver( editableElement, entry => {
- *			console.log( 'The editable element has been resized in DOM.' );
- *			console.log( entry.target ); // -> editableElement
- *			console.log( entry.contentRect.width ); // -> e.g. '423px'
- *		} );
- *
- * By default, it uses the [native DOM resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
- * under the hood and in browsers that do not support the native API yet, a polyfilled observer is
- * used instead.
- */
-export default class ResizeObserver {
-	/**
-	 * Creates an instance of the `ResizeObserver` class.
-	 *
-	 * @param {HTMLElement} element A DOM element that is to be observed for resizing. Note that
-	 * the element must be visible (i.e. not detached from DOM) for the observer to work.
-	 * @param {Function} callback A function called when the observed element was resized. It passes
-	 * the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
-	 * object with information about the resize event.
-	 */
-	constructor( element, callback ) {
-		// **Note**: For the maximum performance, this class ensures only a single instance of the native
-		// (or polyfilled) observer is used no matter how many instances of this class were created.
-		if ( !ResizeObserver._observerInstance ) {
-			ResizeObserver._createObserver();
-		}
-
-		/**
-		 * The element observer by this observer.
-		 *
-		 * @readonly
-		 * @private
-		 * @member {HTMLElement}
-		 */
-		this._element = element;
-
-		/**
-		 * The callback executed each time {@link #_element} is resized.
-		 *
-		 * @readonly
-		 * @private
-		 * @member {Function}
-		 */
-		this._callback = callback;
-
-		ResizeObserver._addElementCallback( element, callback );
-		ResizeObserver._observerInstance.observe( element );
-	}
-
-	/**
-	 * Destroys the observer which disables the `callback` passed to the {@link #constructor}.
-	 */
-	destroy() {
-		ResizeObserver._deleteElementCallback( this._element, this._callback );
-	}
-
-	/**
-	 * Registers a new resize callback for the DOM element.
-	 *
-	 * @private
-	 * @static
-	 * @param {HTMLElement} element
-	 * @param {Function} callback
-	 */
-	static _addElementCallback( element, callback ) {
-		if ( !ResizeObserver._elementCallbacks ) {
-			ResizeObserver._elementCallbacks = new Map();
-		}
-
-		let callbacks = ResizeObserver._elementCallbacks.get( element );
-
-		if ( !callbacks ) {
-			callbacks = new Set();
-			ResizeObserver._elementCallbacks.set( element, callbacks );
-		}
-
-		callbacks.add( callback );
-	}
-
-	/**
-	 * Removes a resize callback from the DOM element. If no callbacks are left
-	 * for the element, it removes the element from the native observer.
-	 *
-	 * @private
-	 * @static
-	 * @param {HTMLElement} element
-	 * @param {Function} callback
-	 */
-	static _deleteElementCallback( element, callback ) {
-		const callbacks = ResizeObserver._getElementCallbacks( element );
-
-		// Remove the element callback. Check if exist first in case someone
-		// called destroy() twice.
-		if ( callbacks ) {
-			callbacks.delete( callback );
-
-			// If no callbacks left for the element, also remove the element.
-			if ( !callbacks.size ) {
-				ResizeObserver._elementCallbacks.delete( element );
-				ResizeObserver._observerInstance.unobserve( element );
-			}
-		}
-
-		if ( ResizeObserver._elementCallbacks && !ResizeObserver._elementCallbacks.size ) {
-			ResizeObserver._observerInstance = null;
-			ResizeObserver._elementCallbacks = null;
-		}
-	}
-
-	/**
-	 * Returns are registered resize callbacks for the DOM element.
-	 *
-	 * @private
-	 * @static
-	 * @param {HTMLElement} element
-	 * @returns {Set.<HTMLElement>|null}
-	 */
-	static _getElementCallbacks( element ) {
-		if ( !ResizeObserver._elementCallbacks ) {
-			return null;
-		}
-
-		return ResizeObserver._elementCallbacks.get( element );
-	}
-
-	/**
-	 * Creates the single native observer shared across all `ResizeObserver` instances.
-	 * If the browser does not support the native API, it creates a polyfill.
-	 *
-	 * @private
-	 * @static
-	 */
-	static _createObserver() {
-		let ObserverConstructor;
-
-		// TODO: One day, the `ResizeObserver` API will be supported in all modern web browsers.
-		// When it happens, this module will no longer make sense and should be removed and
-		// the native implementation should be used across the project to save bytes.
-		// Check out https://caniuse.com/#feat=resizeobserver.
-		if ( typeof global.window.ResizeObserver === 'function' ) {
-			ObserverConstructor = global.window.ResizeObserver;
-		} else {
-			ObserverConstructor = ResizeObserverPolyfill;
-		}
-
-		ResizeObserver._observerInstance = new ObserverConstructor( entries => {
-			for ( const entry of entries ) {
-				const callbacks = ResizeObserver._getElementCallbacks( entry.target );
-
-				if ( callbacks ) {
-					for ( const callback of callbacks ) {
-						callback( entry );
-					}
-				}
-			}
-		} );
-	}
-}
-
-/**
- * The single native observer instance (or polyfill in browsers that do not support the API)
- * shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
- *
- * @static
- * @protected
- * @readonly
- * @property {Object|null} module:utils/dom/resizeobserver~ResizeObserver#_observerInstance
- */
-ResizeObserver._observerInstance = null;
-
-/**
- * A mapping of native DOM elements and their callbacks shared across all
- * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
- *
- * @static
- * @private
- * @readonly
- * @property {Map.<HTMLElement,Set>|null} module:utils/dom/resizeobserver~ResizeObserver#_elementCallbacks
- */
-ResizeObserver._elementCallbacks = null;
-
-/**
- * A polyfill class for the native [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
- *
- * @private
- * @mixes module:utils/domemittermixin~DomEmitterMixin
- */
-class ResizeObserverPolyfill {
-	/**
-	 * Creates an instance of the {@link module:utils/dom/resizeobserver~ResizeObserverPolyfill} class.
-	 *
-	 * It synchronously reacts to resize of the window to check if observed elements' geometry changed.
-	 *
-	 * Additionally, the polyfilled observer uses a timeout to check if observed elements' geometry has changed
-	 * in some other way (dynamic layouts, scrollbars showing up, etc.), so its response can also be asynchronous.
-	 *
-	 * @param {Function} callback A function called when any observed element was resized. Refer to the
-	 * native [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) API to
-	 * learn more.
-	 */
-	constructor( callback ) {
-		/**
-		 * A function called when any observed {@link #_elements element} was resized.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {Function}
-		 */
-		this._callback = callback;
-
-		/**
-		 * DOM elements currently observed by the observer instance.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {Set}
-		 */
-		this._elements = new Set();
-
-		/**
-		 * Cached DOM {@link #_elements elements} bounding rects to compare to upon the next check.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {Map.<HTMLElement,module:utils/dom/rect~Rect>}
-		 */
-		this._previousRects = new Map();
-
-		/**
-		 * An UID of the current timeout upon which the observed elements rects
-		 * will be compared to the {@link #_previousRects previous rects} from the past.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {Map.<HTMLElement,module:utils/dom/rect~Rect>}
-		 */
-		this._periodicCheckTimeout = null;
-	}
-
-	/**
-	 * Starts observing a DOM element.
-	 *
-	 * Learn more in the
-	 * [native method documentation](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe).
-	 *
-	 * @param {HTMLElement} element
-	 */
-	observe( element ) {
-		this._elements.add( element );
-
-		this._checkElementRectsAndExecuteCallback();
-
-		if ( this._elements.size === 1 ) {
-			this._startPeriodicCheck();
-		}
-	}
-
-	/**
-	 * Stops observing a DOM element.
-	 *
-	 * Learn more in the
-	 * [native method documentation](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/unobserve).
-	 *
-	 * @param {HTMLElement} element
-	 */
-	unobserve( element ) {
-		this._elements.delete( element );
-		this._previousRects.delete( element );
-
-		if ( !this._elements.size ) {
-			this._stopPeriodicCheck();
-		}
-	}
-
-	/**
-	 * When called, the observer calls the {@link #_callback resize callback} for all observed
-	 * {@link #_elements elements} but also starts checking periodically for changes in the elements' geometry.
-	 * If some are detected, {@link #_callback resize callback} is called for relevant elements that were resized.
-	 *
-	 * @protected
-	 */
-	_startPeriodicCheck() {
-		const periodicCheck = () => {
-			this._checkElementRectsAndExecuteCallback();
-			this._periodicCheckTimeout = setTimeout( periodicCheck, RESIZE_CHECK_INTERVAL );
-		};
-
-		this.listenTo( global.window, 'resize', () => {
-			this._checkElementRectsAndExecuteCallback();
-		} );
-
-		this._periodicCheckTimeout = setTimeout( periodicCheck, RESIZE_CHECK_INTERVAL );
-	}
-
-	/**
-	 * Stops checking for changes in all observed {@link #_elements elements} geometry.
-	 *
-	 * @protected
-	 */
-	_stopPeriodicCheck() {
-		clearTimeout( this._periodicCheckTimeout );
-		this.stopListening();
-		this._previousRects.clear();
-	}
-
-	/**
-	 * Checks if the geometry of any of the {@link #_elements element} has changed. If so, executes
-	 * the {@link #_callback resize callback} with element geometry data.
-	 *
-	 * @protected
-	 */
-	_checkElementRectsAndExecuteCallback() {
-		const entries = [];
-
-		for ( const element of this._elements ) {
-			if ( this._hasRectChanged( element ) ) {
-				entries.push( {
-					target: element,
-					contentRect: this._previousRects.get( element )
-				} );
-			}
-		}
-
-		if ( entries.length ) {
-			this._callback( entries );
-		}
-	}
-
-	/**
-	 * Compares the DOM element geometry to the {@link #_previousRects cached geometry} from the past.
-	 * Returns `true` if geometry has changed or the element is checked for the first time.
-	 *
-	 * @protected
-	 * @param {HTMLElement} element
-	 * @returns {Boolean}
-	 */
-	_hasRectChanged( element ) {
-		if ( !element.ownerDocument.body.contains( element ) ) {
-			return false;
-		}
-
-		const currentRect = new Rect( element );
-		const previousRect = this._previousRects.get( element );
-
-		// The first check should always yield true despite no Previous rect to compare to.
-		// The native ResizeObserver does that and... that makes sense. Sort of.
-		const hasChanged = !previousRect || !previousRect.isEqual( currentRect );
-
-		this._previousRects.set( element, currentRect );
-
-		return hasChanged;
-	}
-}
-
-mix( ResizeObserverPolyfill, DomEmitterMixin );

package/src/dom/scroll.js

@@ -1,302 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, 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/scroll
- */
-
-import isRange from './isrange';
-import Rect from './rect';
-import isText from './istext';
-
-const utils = {};
-
-/**
- * Makes any page `HTMLElement` or `Range` (`target`) visible inside the browser viewport.
- * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to
- * the user. If the `target` is already visible, nothing will happen.
- *
- * @param {HTMLElement|Range} options.target A target, which supposed to become visible to the user.
- * @param {Number} [options.viewportOffset] An offset from the edge of the viewport (in pixels)
- * the `target` will be moved by when the viewport is scrolled. It enhances the user experience
- * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
- * read or edit by the user.
- */
-export function scrollViewportToShowTarget( { target, viewportOffset = 0 } ) {
-	const targetWindow = getWindow( target );
-	let currentWindow = targetWindow;
-	let currentFrame = null;
-
-	// Iterate over all windows, starting from target's parent window up to window#top.
-	while ( currentWindow ) {
-		let firstAncestorToScroll;
-
-		// Let's scroll target's ancestors first to reveal it. Then, once the ancestor scrolls
-		// settled down, the algorithm can eventually scroll the viewport of the current window.
-		//
-		// Note: If the current window is target's **original** window (e.g. the first one),
-		// start scrolling the closest parent of the target. If not, scroll the closest parent
-		// of an iframe that resides in the current window.
-		if ( currentWindow == targetWindow ) {
-			firstAncestorToScroll = getParentElement( target );
-		} else {
-			firstAncestorToScroll = getParentElement( currentFrame );
-		}
-
-		// Scroll the target's ancestors first. Once done, scrolling the viewport is easy.
-		scrollAncestorsToShowRect( firstAncestorToScroll, () => {
-			// Note: If the target does not belong to the current window **directly**,
-			// i.e. it resides in an iframe belonging to the window, obtain the target's rect
-			// in the coordinates of the current window. By default, a Rect returns geometry
-			// relative to the current window's viewport. To make it work in a parent window,
-			// it must be shifted.
-			return getRectRelativeToWindow( target, currentWindow );
-		} );
-
-		// Obtain the rect of the target after it has been scrolled within its ancestors.
-		// It's time to scroll the viewport.
-		const targetRect = getRectRelativeToWindow( target, currentWindow );
-
-		scrollWindowToShowRect( currentWindow, targetRect, viewportOffset );
-
-		if ( currentWindow.parent != currentWindow ) {
-			// Keep the reference to the <iframe> element the "previous current window" was
-			// rendered within. It will be useful to re–calculate the rect of the target
-			// in the parent window's relative geometry. The target's rect must be shifted
-			// by it's iframe's position.
-			currentFrame = currentWindow.frameElement;
-			currentWindow = currentWindow.parent;
-
-			// If the current window has some parent but frameElement is inaccessible, then they have
-			// different domains/ports and, due to security reasons, accessing and scrolling
-			// the parent window won't be possible.
-			// See https://github.com/ckeditor/ckeditor5/issues/930.
-			if ( !currentFrame ) {
-				return;
-			}
-		} else {
-			currentWindow = null;
-		}
-	}
-}
-
-/**
- * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors,
- * e.g. if they have `overflow: scroll` CSS style.
- *
- * @param {HTMLElement|Range} target A target, which supposed to become visible to the user.
- */
-export function scrollAncestorsToShowTarget( target ) {
-	const targetParent = getParentElement( target );
-
-	scrollAncestorsToShowRect( targetParent, () => {
-		return new Rect( target );
-	} );
-}
-
-// TODO: Using a property value shorthand in the top of the file
-// causes JSDoc to throw errors. See https://github.com/cksource/docs-builder/issues/75.
-Object.assign( utils, {
-	scrollViewportToShowTarget,
-	scrollAncestorsToShowTarget
-} );
-
-// Makes a given rect visible within its parent window.
-//
-// Note: Avoid the situation where the caret is still in the viewport, but totally
-// at the edge of it. In such situation, if it moved beyond the viewport in the next
-// action e.g. after paste, the scrolling would move it to the viewportOffset level
-// and it all would look like the caret visually moved up/down:
-//
-// 1.
-//		| foo[]
-//		|                                    <--- N px of space below the caret
-//		+---------------------------------...
-//
-// 2. *paste*
-// 3.
-//		|
-//		|
-//		+-foo-----------------------------...
-//		  bar[]                              <--- caret below viewport, scrolling...
-//
-// 4. *scrolling*
-// 5.
-//		|
-//		| foo
-//		| bar[]                              <--- caret precisely at the edge
-//		+---------------------------------...
-//
-// To prevent this, this method checks the rects moved by the viewportOffset to cover
-// the upper/lower edge of the viewport. It makes sure if the action repeats, there's
-// no twitching – it's a purely visual improvement:
-//
-// 5. (after fix)
-//		|
-//		| foo
-//		| bar[]
-//		|                                    <--- N px of space below the caret
-//		+---------------------------------...
-//
-// @private
-// @param {Window} window A window which is scrolled to reveal the rect.
-// @param {module:utils/dom/rect~Rect} rect A rect which is to be revealed.
-// @param {Number} viewportOffset See scrollViewportToShowTarget.
-function scrollWindowToShowRect( window, rect, viewportOffset ) {
-	const targetShiftedDownRect = rect.clone().moveBy( 0, viewportOffset );
-	const targetShiftedUpRect = rect.clone().moveBy( 0, -viewportOffset );
-	const viewportRect = new Rect( window ).excludeScrollbarsAndBorders();
-
-	const rects = [ targetShiftedUpRect, targetShiftedDownRect ];
-
-	if ( !rects.every( rect => viewportRect.contains( rect ) ) ) {
-		let { scrollX, scrollY } = window;
-
-		if ( isAbove( targetShiftedUpRect, viewportRect ) ) {
-			scrollY -= viewportRect.top - rect.top + viewportOffset;
-		} else if ( isBelow( targetShiftedDownRect, viewportRect ) ) {
-			scrollY += rect.bottom - viewportRect.bottom + viewportOffset;
-		}
-
-		// TODO: Web browsers scroll natively to place the target in the middle
-		// of the viewport. It's not a very popular case, though.
-		if ( isLeftOf( rect, viewportRect ) ) {
-			scrollX -= viewportRect.left - rect.left + viewportOffset;
-		} else if ( isRightOf( rect, viewportRect ) ) {
-			scrollX += rect.right - viewportRect.right + viewportOffset;
-		}
-
-		window.scrollTo( scrollX, scrollY );
-	}
-}
-
-// Recursively scrolls element ancestors to visually reveal a rect.
-//
-// @private
-// @param {HTMLElement} A parent The first ancestors to start scrolling.
-// @param {Function} getRect A function which returns the Rect, which is to be revealed.
-function scrollAncestorsToShowRect( parent, getRect ) {
-	const parentWindow = getWindow( parent );
-	let parentRect, targetRect;
-
-	while ( parent != parentWindow.document.body ) {
-		targetRect = getRect();
-		parentRect = new Rect( parent ).excludeScrollbarsAndBorders();
-
-		if ( !parentRect.contains( targetRect ) ) {
-			if ( isAbove( targetRect, parentRect ) ) {
-				parent.scrollTop -= parentRect.top - targetRect.top;
-			} else if ( isBelow( targetRect, parentRect ) ) {
-				parent.scrollTop += targetRect.bottom - parentRect.bottom;
-			}
-
-			if ( isLeftOf( targetRect, parentRect ) ) {
-				parent.scrollLeft -= parentRect.left - targetRect.left;
-			} else if ( isRightOf( targetRect, parentRect ) ) {
-				parent.scrollLeft += targetRect.right - parentRect.right;
-			}
-		}
-
-		parent = parent.parentNode;
-	}
-}
-
-// Determines if a given `Rect` extends beyond the bottom edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-function isBelow( firstRect, secondRect ) {
-	return firstRect.bottom > secondRect.bottom;
-}
-
-// Determines if a given `Rect` extends beyond the top edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-function isAbove( firstRect, secondRect ) {
-	return firstRect.top < secondRect.top;
-}
-
-// Determines if a given `Rect` extends beyond the left edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-function isLeftOf( firstRect, secondRect ) {
-	return firstRect.left < secondRect.left;
-}
-
-// Determines if a given `Rect` extends beyond the right edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-function isRightOf( firstRect, secondRect ) {
-	return firstRect.right > secondRect.right;
-}
-
-// Returns the closest window of an element or range.
-//
-// @private
-// @param {HTMLElement|Range} firstRect
-// @returns {Window}
-function getWindow( elementOrRange ) {
-	if ( isRange( elementOrRange ) ) {
-		return elementOrRange.startContainer.ownerDocument.defaultView;
-	} else {
-		return elementOrRange.ownerDocument.defaultView;
-	}
-}
-
-// Returns the closest parent of an element or DOM range.
-//
-// @private
-// @param {HTMLElement|Range} firstRect
-// @returns {HTMLelement}
-function getParentElement( elementOrRange ) {
-	if ( isRange( elementOrRange ) ) {
-		let parent = elementOrRange.commonAncestorContainer;
-
-		// If a Range is attached to the Text, use the closest element ancestor.
-		if ( isText( parent ) ) {
-			parent = parent.parentNode;
-		}
-
-		return parent;
-	} else {
-		return elementOrRange.parentNode;
-	}
-}
-
-// Returns the rect of an element or range residing in an iframe.
-// The result rect is relative to the geometry of the passed window instance.
-//
-// @private
-// @param {HTMLElement|Range} target Element or range which rect should be returned.
-// @param {Window} relativeWindow A window the rect should be relative to.
-// @returns {module:utils/dom/rect~Rect}
-function getRectRelativeToWindow( target, relativeWindow ) {
-	const targetWindow = getWindow( target );
-	const rect = new Rect( target );
-
-	if ( targetWindow === relativeWindow ) {
-		return rect;
-	} else {
-		let currentWindow = targetWindow;
-
-		while ( currentWindow != relativeWindow ) {
-			const frame = currentWindow.frameElement;
-			const frameRect = new Rect( frame ).excludeScrollbarsAndBorders();
-
-			rect.moveBy( frameRect.left, frameRect.top );
-
-			currentWindow = currentWindow.parent;
-		}
-	}
-
-	return rect;
-}

package/src/dom/setdatainelement.js

@@ -1,24 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, 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/setdatainelement
- */
-
-/* globals HTMLTextAreaElement */
-
-/**
- * Sets data in a given element.
- *
- * @param {HTMLElement} el The element in which the data will be set.
- * @param {String} data The data string.
- */
-export default function setDataInElement( el, data ) {
-	if ( el instanceof HTMLTextAreaElement ) {
-		el.value = data;
-	}
-
-	el.innerHTML = data;
-}