@ckeditor/ckeditor5-utils 29.2.0 → 32.0.0

package/src/dom/position.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -13,6 +13,8 @@ import getPositionedAncestor from './getpositionedancestor';
 import getBorderWidths from './getborderwidths';
 import { isFunction } from 'lodash-es';
 
+// @if CK_DEBUG_POSITION // import { RectDrawer } from '@ckeditor/ckeditor5-minimap/src/utils';
+
 /**
  * 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
@@ -74,10 +76,10 @@ import { isFunction } from 'lodash-es';
  *		element.style.top = top;
  *		element.style.left = left;
  *
- * @param {module:utils/dom/position~Options} options Positioning options object.
+ * @param {module:utils/dom/position~Options} options The input data and configuration of the helper.
  * @returns {module:utils/dom/position~Position}
  */
-export function getOptimalPosition( { element, target, positions, limiter, fitInViewport } ) {
+export function getOptimalPosition( { element, target, positions, limiter, fitInViewport, viewportOffsetConfig } ) {
 	// If the {@link module:utils/dom/position~Options#target} is a function, use what it returns.
 	// https://github.com/ckeditor/ckeditor5-utils/issues/157
 	if ( isFunction( target ) ) {
@@ -94,52 +96,54 @@ export function getOptimalPosition( { element, target, positions, limiter, fitIn
 	const elementRect = new Rect( element );
 	const targetRect = new Rect( target );
 
-	let bestPositionRect;
-	let bestPositionName;
+	let bestPosition;
+
+	// @if CK_DEBUG_POSITION // RectDrawer.clear();
+	// @if CK_DEBUG_POSITION // RectDrawer.draw( targetRect, { outlineWidth: '5px' }, 'Target' );
+
+	const positionOptions = { targetRect, elementRect, positionedElementAncestor };
 
 	// If there are no limits, just grab the very first position and be done with that drama.
 	if ( !limiter && !fitInViewport ) {
-		[ bestPositionName, bestPositionRect ] = getPositionNameAndRect( positions[ 0 ], targetRect, elementRect );
+		bestPosition = new Position( positions[ 0 ], positionOptions );
 	} else {
 		const limiterRect = limiter && new Rect( limiter ).getVisible();
-		const viewportRect = fitInViewport && new Rect( global.window );
-		const bestPosition = getBestPositionNameAndRect( positions, { targetRect, elementRect, limiterRect, viewportRect } );
+		const viewportRect = fitInViewport && getConstrainedViewportRect( viewportOffsetConfig );
 
-		// 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.
-		[ bestPositionName, bestPositionRect ] = bestPosition || getPositionNameAndRect( positions[ 0 ], targetRect, elementRect );
-	}
+		// @if CK_DEBUG_POSITION // if ( viewportRect ) {
+		// @if CK_DEBUG_POSITION //		RectDrawer.draw( viewportRect, { outlineWidth: '5px' }, 'Viewport' );
+		// @if CK_DEBUG_POSITION // }
 
-	let absoluteRectCoordinates = getAbsoluteRectCoordinates( bestPositionRect );
+		// @if CK_DEBUG_POSITION // if ( limiter ) {
+		// @if CK_DEBUG_POSITION // 	RectDrawer.draw( limiterRect, { outlineWidth: '5px', outlineColor: 'green' }, 'Visible limiter' );
+		// @if CK_DEBUG_POSITION // }
 
-	if ( positionedElementAncestor ) {
-		absoluteRectCoordinates = shiftRectCoordinatesDueToPositionedAncestor( absoluteRectCoordinates, positionedElementAncestor );
+		Object.assign( positionOptions, { limiterRect, viewportRect } );
+
+		// 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 Position( positions[ 0 ], positionOptions );
 	}
 
-	return {
-		left: absoluteRectCoordinates.left,
-		top: absoluteRectCoordinates.top,
-		name: bestPositionName
-	};
+	return bestPosition;
 }
 
-// For given position function, returns a corresponding `Rect` instance.
+// Returns a viewport `Rect` shrunk by the viewport offset config from all sides.
 //
 // @private
-// @param {Function} position A function returning {@link module:utils/dom/position~Position}.
-// @param {utils/dom/rect~Rect} targetRect A rect of the target.
-// @param {utils/dom/rect~Rect} elementRect A rect of positioned element.
-// @returns {Array|null} An array containing position name and its Rect (or null if position should be ignored).
-function getPositionNameAndRect( position, targetRect, elementRect ) {
-	const positionData = position( targetRect, elementRect );
-
-	if ( !positionData ) {
-		return null;
-	}
+// @param {Object} An object containing viewportOffset config.
+// @returns {utils/dom/rect~Rect} A shrunken rect of the viewport.
+function getConstrainedViewportRect( viewportOffsetConfig ) {
+	viewportOffsetConfig = Object.assign( { top: 0, bottom: 0, left: 0, right: 0 }, viewportOffsetConfig );
 
-	const { left, top, name } = positionData;
+	const viewportRect = new Rect( global.window );
 
-	return [ name, elementRect.clone().moveTo( left, top ) ];
+	viewportRect.top += viewportOffsetConfig.top;
+	viewportRect.height -= viewportOffsetConfig.top;
+	viewportRect.bottom -= viewportOffsetConfig.bottom;
+	viewportRect.height -= viewportOffsetConfig.bottom;
+
+	return viewportRect;
 }
 
 // For a given array of positioning functions, returns such that provides the best
@@ -148,157 +152,50 @@ function getPositionNameAndRect( position, targetRect, elementRect ) {
 // @private
 //
 // @param {Object} options
-// @param {module:utils/dom/position~Options#positions} positions Functions returning {@link module:utils/dom/position~Position}
-// to be checked, in the order of preference.
+// @param {module:utils/dom/position~Options#positions} positions Functions returning
+// {@link module:utils/dom/position~Position}to be checked, in the order of preference.
 // @param {Object} options
 // @param {utils/dom/rect~Rect} options.targetRect A rect of the {@link module:utils/dom/position~Options#target}.
-// @param {utils/dom/rect~Rect} options.elementRect A rect of positioned {@link module:utils/dom/position~Options#element}.
+// @param {utils/dom/rect~Rect} options.elementRect A rect of positioned
+// {@link module:utils/dom/position~Options#element}.
 // @param {utils/dom/rect~Rect} options.limiterRect A rect of the {@link module:utils/dom/position~Options#limiter}.
-// @param {utils/dom/rect~Rect} options.viewportRect A rect of the viewport.
+// @param {utils/dom/rect~Rect} options.viewportRect A rect of the {@link module:utils/dom/position~Options#viewport}.
 //
 // @returns {Array} An array containing the name of the position and it's rect.
-function getBestPositionNameAndRect( positions, options ) {
-	const { elementRect, viewportRect } = options;
-
-	// This is when element is fully visible.
-	const elementRectArea = elementRect.getArea();
-
-	// Let's calculate intersection areas for positions. It will end early if best match is found.
-	const processedPositions = processPositionsToAreas( positions, options );
-
-	// First let's check all positions that fully fit in the viewport.
-	if ( viewportRect ) {
-		const processedPositionsInViewport = processedPositions.filter( ( { viewportIntersectArea } ) => {
-			return viewportIntersectArea === elementRectArea;
-		} );
-
-		// Try to find best position from those which fit completely in viewport.
-		const bestPositionData = getBestOfProcessedPositions( processedPositionsInViewport, elementRectArea );
-
-		if ( bestPositionData ) {
-			return bestPositionData;
-		}
-	}
-
-	// Either there is no viewportRect or there is no position that fits completely in the viewport.
-	return getBestOfProcessedPositions( processedPositions, elementRectArea );
-}
-
-// For a given array of positioning functions, calculates intersection areas for them.
-//
-// Note: If some position fully fits into the `limiterRect`, it will be returned early, without further consideration
-// of other positions.
-//
-// @private
-//
-// @param {module:utils/dom/position~Options#positions} positions Functions returning {@link module:utils/dom/position~Position}
-// to be checked, in the order of preference.
-// @param {Object} options
-// @param {utils/dom/rect~Rect} options.targetRect A rect of the {@link module:utils/dom/position~Options#target}.
-// @param {utils/dom/rect~Rect} options.elementRect A rect of positioned {@link module:utils/dom/position~Options#element}.
-// @param {utils/dom/rect~Rect} options.limiterRect A rect of the {@link module:utils/dom/position~Options#limiter}.
-// @param {utils/dom/rect~Rect} options.viewportRect A rect of the viewport.
-//
-// @returns {Array.<Object>} Array of positions with calculated intersection areas. Each item is an object containing:
-// * {String} positionName Name of position.
-// * {utils/dom/rect~Rect} positionRect Rect of position.
-// * {Number} limiterIntersectArea Area of intersection of the position with limiter part that is in the viewport.
-// * {Number} viewportIntersectArea Area of intersection of the position with viewport.
-function processPositionsToAreas( positions, { targetRect, elementRect, limiterRect, viewportRect } ) {
-	const processedPositions = [];
+function getBestPosition( positions, options ) {
+	const { elementRect } = options;
 
 	// This is when element is fully visible.
 	const elementRectArea = elementRect.getArea();
 
-	for ( const position of positions ) {
-		const positionData = getPositionNameAndRect( position, targetRect, elementRect );
-
-		if ( !positionData ) {
-			continue;
-		}
-
-		const [ positionName, positionRect ] = positionData;
-		let limiterIntersectArea = 0;
-		let viewportIntersectArea = 0;
-
-		if ( limiterRect ) {
-			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.
-					limiterIntersectArea = limiterViewportIntersectRect.getIntersectionArea( positionRect );
-				}
-			} else {
-				limiterIntersectArea = limiterRect.getIntersectionArea( positionRect );
-			}
-		}
+	const positionInstances = positions
+		.map( positioningFunction => new Position( positioningFunction, options ) )
+		// Some positioning functions may return `null` if they don't want to participate.
+		.filter( position => !!position.name );
 
-		if ( viewportRect ) {
-			viewportIntersectArea = viewportRect.getIntersectionArea( positionRect );
-		}
+	let maxFitFactor = 0;
+	let bestPosition = null;
 
-		const processedPosition = {
-			positionName,
-			positionRect,
-			limiterIntersectArea,
-			viewportIntersectArea
-		};
+	for ( const position of positionInstances ) {
+		const { _limiterIntersectionArea, _viewportIntersectionArea } = position;
 
 		// 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 ( limiterIntersectArea === elementRectArea ) {
-			return [ processedPosition ];
-		}
-
-		processedPositions.push( processedPosition );
-	}
-
-	return processedPositions;
-}
-
-// For a given array of processed position data (with calculated Rects for positions and intersection areas)
-// returns such that provides the best fit of the `elementRect` into the `limiterRect` and `viewportRect` at the same time.
-//
-// **Note**: It will return early if some position fully fits into the `limiterRect`.
-//
-// @private
-// @param {Array.<Object>} Array of positions with calculated intersection areas (in order of preference).
-// Each item is an object containing:
-//
-//	* {String} positionName Name of position.
-//	* {utils/dom/rect~Rect} positionRect Rect of position.
-//	* {Number} limiterIntersectArea Area of intersection of the position with limiter part that is in the viewport.
-//	* {Number} viewportIntersectArea Area of intersection of the position with viewport.
-//
-// @param {Number} elementRectArea Area of positioned {@link module:utils/dom/position~Options#element}.
-// @returns {Array|null} An array containing the name of the position and it's rect, or null if not found.
-function getBestOfProcessedPositions( processedPositions, elementRectArea ) {
-	let maxFitFactor = 0;
-	let bestPositionRect;
-	let bestPositionName;
-
-	for ( const { positionName, positionRect, limiterIntersectArea, viewportIntersectArea } of processedPositions ) {
-		// If a such position is found that element is fully container by the limiter then, obviously,
-		// there will be no better one, so finishing.
-		if ( limiterIntersectArea === elementRectArea ) {
-			return [ positionName, positionRect ];
+		if ( _limiterIntersectionArea === elementRectArea ) {
+			return position;
 		}
 
-		// To maximize both viewport and limiter intersection areas we use distance on viewportIntersectArea
-		// and limiterIntersectArea plane (without sqrt because we are looking for max value).
-		const fitFactor = viewportIntersectArea ** 2 + limiterIntersectArea ** 2;
+		// 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 ( fitFactor > maxFitFactor ) {
 			maxFitFactor = fitFactor;
-			bestPositionRect = positionRect;
-			bestPositionName = positionName;
+			bestPosition = position;
 		}
 	}
 
-	return bestPositionRect ? [ bestPositionName, bestPositionRect ] : null;
+	return bestPosition;
 }
 
 // For a given absolute Rect coordinates object and a positioned element ancestor, it returns an object with
@@ -310,41 +207,44 @@ function getBestOfProcessedPositions( processedPositions, elementRectArea ) {
 //
 // @private
 //
-// @param {Object} absoluteRectCoordinates An object with absolute rect coordinates.
-// @param {Object} absoluteRectCoordinates.top
-// @param {Object} absoluteRectCoordinates.left
+// @param {utils/dom/rect~Rect} rect A rect with absolute rect coordinates.
+// @param {Number} rect.top
+// @param {Number} rect.left
 // @param {HTMLElement} positionedElementAncestor An ancestor element that should be considered.
 //
-// @returns {Object} An object corresponding to `absoluteRectCoordinates` input but with values shifted
+// @returns {utils/dom/rect~Rect} A rect corresponding to `absoluteRect` input but with values shifted
 // to make up for the positioned element ancestor.
-function shiftRectCoordinatesDueToPositionedAncestor( { left, top }, positionedElementAncestor ) {
-	const ancestorPosition = getAbsoluteRectCoordinates( new Rect( positionedElementAncestor ) );
+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.
-	left -= ancestorPosition.left;
-	top -= ancestorPosition.top;
+	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.
-	left += positionedElementAncestor.scrollLeft;
-	top += positionedElementAncestor.scrollTop;
+	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.
-	left -= ancestorBorderWidths.left;
-	top -= ancestorBorderWidths.top;
+	moveX -= ancestorBorderWidths.left;
+	moveY -= ancestorBorderWidths.top;
 
-	return { left, top };
+	rect.moveBy( moveX, moveY );
 }
 
 // DOMRect (also Rect) works in a scroll–independent geometry but `position: absolute` doesn't.
@@ -353,13 +253,172 @@ function shiftRectCoordinatesDueToPositionedAncestor( { left, top }, positionedE
 // @private
 // @param {utils/dom/rect~Rect} rect A rect to be converted.
 // @returns {Object} Object containing `left` and `top` properties, in absolute coordinates.
-function getAbsoluteRectCoordinates( { left, top } ) {
+function getRectForAbsolutePositioning( rect ) {
 	const { scrollX, scrollY } = global.window;
 
-	return {
-		left: left + scrollX,
-		top: top + scrollY
-	};
+	return rect.clone().moveBy( scrollX, scrollY );
+}
+
+/**
+ * A position class which instances are created and used by the {@link module:utils/dom/position~getOptimalPosition} helper.
+ *
+ * {@link module:utils/dom/position~Position#top} and {@link module:utils/dom/position~Position#left} properties of the position instance
+ * translate directly to the `top` and `left` properties in CSS "`position: absolute` coordinate system". If set on the positioned element
+ * in DOM, they will make it display it in the right place in the viewport.
+ */
+export class Position {
+	/**
+	 * Creates an instance of the {@link module:utils/dom/position~Position} class.
+	 *
+	 * @param {module:utils/dom/position~positioningFunction} [positioningFunction] function The function that defines the expected
+	 * coordinates the positioned element should move to.
+	 * @param {Object} [options] options object.
+	 * @param {module:utils/dom/rect~Rect} options.elementRect The positioned element rect.
+	 * @param {module:utils/dom/rect~Rect} options.targetRect The target element rect.
+	 * @param {module:utils/dom/rect~Rect} options.viewportRect The viewport rect.
+	 * @param {HTMLElement|null} [options.positionedElementAncestor] Nearest element ancestor element which CSS position is not "static".
+	 */
+	constructor( positioningFunction, options ) {
+		const positioningFunctionOutput = positioningFunction( options.targetRect, options.elementRect, options.viewportRect );
+
+		// Nameless position for a function that didn't participate.
+		if ( !positioningFunctionOutput ) {
+			return;
+		}
+
+		const { left, top, name, config } = positioningFunctionOutput;
+
+		Object.assign( this, { name, config } );
+
+		this._positioningFunctionCorrdinates = { left, top };
+		this._options = options;
+
+		/**
+		 * Position name.
+		 *
+		 * @readonly
+		 * @member {String} #name
+		 */
+
+		/**
+		 * Additional position configuration, as passed from the {@link module:utils/dom/position~positioningFunction positioning function}.
+		 *
+		 * This object can be use, for instance, to pass through presentation options used by the consumer of the
+		 * {@link module:utils/dom/position~getOptimalPosition} helper.
+		 *
+		 * @readonly
+		 * @member {Object} #config
+		 */
+	}
+
+	/**
+	 * The left value in pixels in the CSS `position: absolute` coordinate system.
+	 * Set it on the positioned element in DOM to move it to the position.
+	 *
+	 * @readonly
+	 * @type {Number}
+	 */
+	get left() {
+		return this._absoluteRect.left;
+	}
+
+	/**
+	 * The top value in pixels in the CSS `position: absolute` coordinate system.
+	 * Set it on the positioned element in DOM to move it to the position.
+	 *
+	 * @readonly
+	 * @type {Number}
+	 */
+	get top() {
+		return this._absoluteRect.top;
+	}
+
+	/**
+	 * An intersection area between positioned element and limiter within viewport constraints.
+	 *
+	 * @readonly
+	 * @private
+	 * @type {Number}
+	 */
+	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 0;
+	}
+
+	/**
+	 * An intersection area between positioned element and viewport.
+	 *
+	 * @readonly
+	 * @private
+	 * @type {Number}
+	 */
+	get _viewportIntersectionArea() {
+		const viewportRect = this._options.viewportRect;
+
+		if ( viewportRect ) {
+			return viewportRect.getIntersectionArea( this._rect );
+		}
+
+		return 0;
+	}
+
+	/**
+	 * An already positioned element rect. A clone of the element rect passed to the constructor
+	 * but placed in the viewport according to the positioning function.
+	 *
+	 * @private
+	 * @type {module:utils/dom/rect~Rect}
+	 */
+	get _rect() {
+		if ( this._cachedRect ) {
+			return this._cachedRect;
+		}
+
+		this._cachedRect = this._options.elementRect.clone().moveTo(
+			this._positioningFunctionCorrdinates.left,
+			this._positioningFunctionCorrdinates.top
+		);
+
+		return this._cachedRect;
+	}
+
+	/**
+	 * An already absolutely positioned element rect. See ({@link #_rect}).
+	 *
+	 * @private
+	 * @type {module:utils/dom/rect~Rect}
+	 */
+	get _absoluteRect() {
+		if ( this._cachedAbsoluteRect ) {
+			return this._cachedAbsoluteRect;
+		}
+
+		this._cachedAbsoluteRect = getRectForAbsolutePositioning( this._rect );
+
+		if ( this._options.positionedElementAncestor ) {
+			shiftRectToCompensatePositionedAncestor( this._cachedAbsoluteRect, this._options.positionedElementAncestor );
+		}
+
+		return this._cachedAbsoluteRect;
+	}
 }
 
 /**
@@ -381,12 +440,15 @@ function getAbsoluteRectCoordinates( { left, top } ) {
  */
 
 /**
- * An array of functions which return {@link module:utils/dom/position~Position} relative
- * to the `target`, in the order of preference.
+ * An array of positioning functions.
+ *
+ * **Note**: Positioning functions are processed in the order of preference. The first function that works
+ * in the current environment (e.g. offers the complete fit in the viewport geometry) will be picked by
+ * `getOptimalPosition()`.
  *
- * **Note**: If a function returns `null`, it is ignored by the `getOptimalPosition()`.
+ * **Note**: Any positioning function returning `null` is ignored.
  *
- * @member {Array.<Function>} #positions
+ * @member {Array.<module:utils/dom/position~positioningFunction>} #positions
  */
 
 /**
@@ -404,12 +466,53 @@ function getAbsoluteRectCoordinates( { left, top } ) {
  */
 
 /**
- * An object describing a position in `position: absolute` coordinate
- * system, along with position name.
+ * Viewport offset config object. It restricts the visible viewport available to the `getOptimalPosition()` from each side.
  *
- * @typedef {Object} module:utils/dom/position~Position
+ *		{
+ *			top: 50,
+ *			right: 50,
+ *			bottom: 50,
+ *			left: 50
+ *		}
+ *
+ * @member {Object} #viewportOffsetConfig
+ */
+
+/**
+ * A positioning function which, based on positioned element and target {@link module:utils/dom/rect~Rect Rects}, returns rect coordinates
+ * representing the geometrical relation between them. Used by the {@link module:utils/dom/position~getOptimalPosition} helper.
+ *
+ *		// This simple position will place the element directly under the target, in the middle:
+ *		//
+ *		//	    [ Target ]
+ *		//	+-----------------+
+ *		//	|     Element     |
+ *		//	+-----------------+
+ *		//
+ *		const position = ( targetRect, elementRect, [ viewportRect ] ) => ( {
+ *			top: targetRect.bottom,
+ *			left: targetRect.left + targetRect.width / 2 - elementRect.width / 2,
+ *			name: 'bottomMiddle',
+ *
+ *			// Note: The config is optional.
+ *			config: {
+ *				zIndex: '999'
+ *			}
+ *		} );
  *
- * @property {Number} top Top position offset.
- * @property {Number} left Left position offset.
- * @property {String} name Name of the position.
+ * @callback module:utils/dom/position~positioningFunction
+ * @param {module:utils/dom/rect~Rect} elementRect The rect of the element to be positioned.
+ * @param {module:utils/dom/rect~Rect} targetRect The rect of the target the element (its rect) is relatively positioned to.
+ * @param {module:utils/dom/rect~Rect} viewportRect The rect of the visual browser viewport.
+ * @returns {Object|null} return When the function returns `null`, it will not be considered by
+ * {@link module:utils/dom/position~getOptimalPosition}.
+ * @returns {Number} return.top The `top` value of the element rect that would represent the position.
+ * @returns {Number} return.left The `left` value of the element rect that would represent the position.
+ * @returns {Number} return.name The name of the position. It helps the user of the {@link module:utils/dom/position~getOptimalPosition}
+ * helper to recognize different positioning function results. It will pass through to the {@link module:utils/dom/position~Position}
+ * returned by the helper.
+ * @returns {Number} [return.config] An optional configuration that will pass-through the
+ * {@link module:utils/dom/position~getOptimalPosition} helper to the {@link module:utils/dom/position~Position} returned by this helper.
+ * This configuration may, for instance, let the user of {@link module:utils/dom/position~getOptimalPosition} know that this particular
+ * position comes with a certain presentation.
  */

package/src/dom/rect.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dom/remove.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dom/resizeobserver.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dom/scroll.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dom/setdatainelement.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dom/tounit.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/elementreplacer.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */