@ckeditor/ckeditor5-utils 29.2.0 → 30.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "29.2.0",
+  "version": "30.0.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -14,10 +14,10 @@
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-build-classic": "^29.2.0",
-    "@ckeditor/ckeditor5-editor-classic": "^29.2.0",
-    "@ckeditor/ckeditor5-core": "^29.2.0",
-    "@ckeditor/ckeditor5-engine": "^29.2.0",
+    "@ckeditor/ckeditor5-build-classic": "^30.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^30.0.0",
+    "@ckeditor/ckeditor5-core": "^30.0.0",
+    "@ckeditor/ckeditor5-engine": "^30.0.0",
     "assertion-error": "^1.1.0",
     "js-beautify": "^1.11.0"
   },

package/src/ckeditorerror.js

@@ -85,6 +85,7 @@ export default class CKEditorError extends Error {
 
 	/**
 	 * Checks if the error is of the `CKEditorError` type.
+	 * @returns {Boolean}
 	 */
 	is( type ) {
 		return type === 'CKEditorError';
@@ -142,7 +143,6 @@ export default class CKEditorError extends Error {
  *
  * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
- * @returns {String}
  */
 export function logWarning( errorName, data ) {
 	console.warn( ...formatConsoleArguments( errorName, data ) );
@@ -167,7 +167,6 @@ export function logWarning( errorName, data ) {
  *
  * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
- * @returns {String}
  */
 export function logError( errorName, data ) {
 	console.error( ...formatConsoleArguments( errorName, data ) );

package/src/collection.js

@@ -56,7 +56,7 @@ export default class Collection {
 	 *		console.log( collection.get( 'George' ) ); // -> { name: 'George' }
 	 *		console.log( collection.get( 'John' ) ); // -> { name: 'John' }
 	 *
-	 * @param {Iterable.<Object>|Object} initialItemsOrOptions The initial items of the collection or
+	 * @param {Iterable.<Object>|Object} [initialItemsOrOptions] The initial items of the collection or
 	 * the options object.
 	 * @param {Object} [options={}] The options object, when the first argument is an array of initial items.
 	 * @param {String} [options.idProperty='id'] The name of the property which is used to identify an item.

package/src/dom/position.js

@@ -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/keyboard.js

@@ -33,6 +33,7 @@ const modifiersToGlyphsNonMac = {
  * * `a-z`,
  * * `0-9`,
  * * `f1-f12`,
+ * * `` ` ``, `-`, `=`, `[`, `]`, `;`, `'`, `,`, `.`, `/`, `\`,
  * * `arrow(left|up|right|bottom)`,
  * * `backspace`, `delete`, `enter`, `esc`, `tab`,
  * * `ctrl`, `cmd`, `shift`, `alt`.
@@ -251,6 +252,11 @@ function generateKnownKeyCodes() {
 		keyCodes[ 'f' + ( code - 111 ) ] = code;
 	}
 
+	// other characters
+	for ( const char of '`-=[];\',./\\' ) {
+		keyCodes[ char ] = char.charCodeAt( 0 );
+	}
+
 	return keyCodes;
 }
 

package/src/translation-service.js

@@ -131,7 +131,7 @@ export function add( language, translations, getPluralForm ) {
  *
  * @protected
  * @param {String} language Target language.
- * @param {module:utils/translation-service~Message|String} message A message that will be translated.
+ * @param {module:utils/translation-service~Message} message A message that will be translated.
  * @param {Number} [quantity] The number of elements for which a plural form should be picked from the target language dictionary.
  * @returns {String} Translated sentence.
  */

package/src/version.js

@@ -11,7 +11,7 @@
 
 import CKEditorError from './ckeditorerror';
 
-const version = '29.2.0';
+const version = '30.0.0';
 
 export default version;
 

package/CHANGELOG.md

@@ -1,324 +0,0 @@
-Changelog
-=========
-
-All changes in the package are documented in the main repository. See: https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md.
-
-Changes for the past releases are available below.
-
-## [19.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v18.0.0...v19.0.0) (2020-04-29)
-
-### MINOR BREAKING CHANGES
-
-* The `translate` function from the `translation-service` was marked as protected. See [#334](https://github.com/ckeditor/ckeditor5-utils/issues/334).
-* The format of stored editor translations has been changed. If you use `window.CKEDITOR_TRANSLATIONS` please see [#334](https://github.com/ckeditor/ckeditor5-utils/issues/334).
-* The `getPositionedAncestor()` helper will no longer return the passed element when it is positioned.
-
-### MAJOR BREAKING CHANGES
-
-* `env.isEdge` is no longer available. See [ckeditor/ckeditor5#6202](https://github.com/ckeditor/ckeditor5/issues/6202).
-
-### Features
-
-* Added the support for initializing `Collection` items via the `constructor()`. Closes [ckeditor/ckeditor5#6319](https://github.com/ckeditor/ckeditor5/issues/6319). ([8846e66](https://github.com/ckeditor/ckeditor5-utils/commit/8846e66))
-* Provided support for plural forms internalization. Part of [ckeditor/ckeditor5#6526](https://github.com/ckeditor/ckeditor5/issues/6526). ([5f6ea75](https://github.com/ckeditor/ckeditor5-utils/commit/5f6ea75))
-
-### Bug fixes
-
-* Do not execute `ResizeObserver` callbacks when the resized element is invisible (but still in DOM) (see [ckeditor/ckeditor5#6570](https://github.com/ckeditor/ckeditor5/issues/6570)). ([fb13d9d](https://github.com/ckeditor/ckeditor5-utils/commit/fb13d9d))
-* Editor will now load correctly in environment with `Symbol` polyfill. Closes [ckeditor/ckeditor5#6489](https://github.com/ckeditor/ckeditor5/issues/6489). ([7cd1f48](https://github.com/ckeditor/ckeditor5-utils/commit/7cd1f48))
-* Fixed various cases with typing multi-byte unicode sequences (e.g. emojis). Closes [ckeditor/ckeditor5#3147](https://github.com/ckeditor/ckeditor5/issues/3147). Closes [ckeditor/ckeditor5#6495](https://github.com/ckeditor/ckeditor5/issues/6495). ([6dc1ba6](https://github.com/ckeditor/ckeditor5-utils/commit/6dc1ba6))
-* The `getOptimalPosition()` helper should prefer positions that fit inside the viewport even though there are some others that fit better into the limiter. Closes [ckeditor/ckeditor5#6181](https://github.com/ckeditor/ckeditor5/issues/6181). ([7cd1238](https://github.com/ckeditor/ckeditor5-utils/commit/7cd1238))
-
-### Other changes
-
-* Removed `env.isEdge` as Edge is now detected and treated as Chrome. Closes [ckeditor/ckeditor5#6202](https://github.com/ckeditor/ckeditor5/issues/6202). ([2902b30](https://github.com/ckeditor/ckeditor5-utils/commit/2902b30))
-* The `getPositionedAncestor()` helper should use `offsetParent` instead of `getComputedStyle()` for performance reasons. Closes [ckeditor/ckeditor5#6573](https://github.com/ckeditor/ckeditor5/issues/6573). ([7939756](https://github.com/ckeditor/ckeditor5-utils/commit/7939756))
-
-
-## [18.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v17.0.0...v18.0.0) (2020-03-19)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [17.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v16.0.0...v17.0.0) (2020-02-19)
-
-### MINOR BREAKING CHANGES
-
-* The `getResizeObserver()` helper is no longer available. We recommend using the [`ResizeObserver`](http://ckeditor.com/docs/ckeditor5/latest/api/module_utils_dom_resizeobserver-ResizeObserver.html) class instead.
-
-### Features
-
-* Added iterator interface to the `Config` class. ([1fdf2f1](https://github.com/ckeditor/ckeditor5-utils/commit/1fdf2f1))
-
-### Other changes
-
-* Improved `toMap()` method performance. This results in improved editor data processing speed. Closes [ckeditor/ckeditor5#5854](https://github.com/ckeditor/ckeditor5/issues/5854). ([fef816e](https://github.com/ckeditor/ckeditor5-utils/commit/fef816e))
-* Replaced the `getResizeObserver()` helper with the `ResizeObserver` class for performance reasons. See [ckeditor/ckeditor5#6145](https://github.com/ckeditor/ckeditor5/issues/6145). ([05c97f8](https://github.com/ckeditor/ckeditor5-utils/commit/05c97f8))
-* The `uid()` helper should be a lot faster. Closes [ckeditor/ckeditor5#6188](https://github.com/ckeditor/ckeditor5/issues/6188). ([b57fc3f](https://github.com/ckeditor/ckeditor5-utils/commit/b57fc3f))
-
-
-## [16.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v15.0.0...v16.0.0) (2019-12-04)
-
-### Bug fixes
-
-* Improved error rethrowing by replacing the error stack. Closes [ckeditor/ckeditor5#5595](https://github.com/ckeditor/ckeditor5/issues/5595). ([7685c0d](https://github.com/ckeditor/ckeditor5-utils/commit/7685c0d))
-
-
-## [15.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v14.0.0...v15.0.0) (2019-10-23)
-
-### Features
-
-* Implemented the `getResizeObserver()` helper that offers an entry to the native `ResizeObserver` API (see [ckeditor/ckeditor5#416](https://github.com/ckeditor/ckeditor5/issues/416)). ([875d5a4](https://github.com/ckeditor/ckeditor5-utils/commit/875d5a4))
-* Introduced `assertEqualMarkup()` test util method. Closes [ckeditor/ckeditor5-paste-from-office#14](https://github.com/ckeditor/ckeditor5-paste-from-office/issues/14). ([ee1655f](https://github.com/ckeditor/ckeditor5-utils/commit/ee1655f))
-* Introduced support for creating elements in other XML namespaces. See [ckeditor/ckeditor5#1842](https://github.com/ckeditor/ckeditor5/issues/1842). ([37fbcb9](https://github.com/ckeditor/ckeditor5-utils/commit/37fbcb9))
-
-  Thanks [@Sebobo](https://github.com/Sebobo)!
-
-### Bug fixes
-
-* `Rect#excludeScrollbarsAndBorders` should support RTL environments. Fixed incorrect output of the method. Closes [#297](https://github.com/ckeditor/ckeditor5-utils/issues/297). ([35f34fc](https://github.com/ckeditor/ckeditor5-utils/commit/35f34fc))
-
-### Other changes
-
-* Introduced the `CKEditorError.rethrowUnexpectedError()` helper. Added custom error handling for the `Emitter#fire()` function. Part of [ckeditor/ckeditor5#1304](https://github.com/ckeditor/ckeditor5/issues/1304). ([1d84705](https://github.com/ckeditor/ckeditor5-utils/commit/1d84705))
-
-
-## [14.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v13.0.1...v14.0.0) (2019-08-26)
-
-### Features
-
-* Add feature detection of Unicode properties entities' support. ([21c0f6b](https://github.com/ckeditor/ckeditor5-utils/commit/21c0f6b))
-* Allowed specifying editor content language in `Locale`. Implemented the (UI and content) language direction discovery in `Locale`. Implemented `Locale#uiLanguage`, `Locale#uiLanguageDirection`, `Locale#contentLanguage`, and `Locale#contentLanguageDirection` properties. See [ckeditor/ckeditor5#1151](https://github.com/ckeditor/ckeditor5/issues/1151). ([91c95f3](https://github.com/ckeditor/ckeditor5-utils/commit/91c95f3))
-
-### Other changes
-
-* The issue tracker for this package was moved to https://github.com/ckeditor/ckeditor5/issues. See [ckeditor/ckeditor5#1988](https://github.com/ckeditor/ckeditor5/issues/1988). ([71469ac](https://github.com/ckeditor/ckeditor5-utils/commit/71469ac))
-* Removed the CKEditor 5 logger and its usage. Part of [ckeditor/ckeditor5#383](https://github.com/ckeditor/ckeditor5/issues/383). ([584ef1d](https://github.com/ckeditor/ckeditor5-utils/commit/584ef1d))
-
-### BREAKING CHANGES
-
-* The`Locale()` constructor arguments syntax has changed. Please refer to the API documentation to learn more.
-* The `Locale#language` property has been deprecated by `Locale#uiLanguage`. Please refer to the API documentation to learn more.
-* Removed the CKEditor 5 logger utility.
-
-
-## [13.0.1](https://github.com/ckeditor/ckeditor5-utils/compare/v13.0.0...v13.0.1) (2019-07-10)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [13.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v12.1.1...v13.0.0) (2019-07-04)
-
-### Features
-
-* Added `env.isAndroid`. ([591f641](https://github.com/ckeditor/ckeditor5-utils/commit/591f641))
-
-### Other changes
-
-* Added context as second required argument to the `CKEditorError`'s constructor, changed `isCKEditorError()` method to `is()`. Introduced the `areConnectedThroughProperties()` utility. See [ckeditor/ckeditor5-watchdog#1](https://github.com/ckeditor/ckeditor5-watchdog/issues/1). ([bacc764](https://github.com/ckeditor/ckeditor5-utils/commit/bacc764))
-
-### BREAKING CHANGES
-
-* The list of `CKEditorError()`'s parameters was changed – now it requires the message, context and then data. The `isCKEditorError()` method was renamed to `is()`.
-
-
-## [12.1.1](https://github.com/ckeditor/ckeditor5-utils/compare/v12.1.0...v12.1.1) (2019-06-05)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [12.1.0](https://github.com/ckeditor/ckeditor5-utils/compare/v12.0.0...v12.1.0) (2019-04-10)
-
-### Features
-
-* Added `isSafari` property and `isSafari()` helper to the `env` module. See: [ckeditor/ckeditor5#1463](https://github.com/ckeditor/ckeditor5/issues/1463). ([f1ba6ae](https://github.com/ckeditor/ckeditor5-utils/commit/f1ba6ae))
-* Made `FocusTracker#focusedElement` observable to bring support for multi-root editors (see [ckeditor/ckeditor5#1599](https://github.com/ckeditor/ckeditor5/issues/1599)). ([952d440](https://github.com/ckeditor/ckeditor5-utils/commit/952d440))
-
-
-## [12.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v11.1.0...v12.0.0) (2019-02-28)
-
-### Features
-
-* Introduce `Collection.has()` method. Closes [#266](https://github.com/ckeditor/ckeditor5-utils/issues/266). ([312d55e](https://github.com/ckeditor/ckeditor5-utils/commit/312d55e))
-
-### Bug fixes
-
-* Prevent infinite loops on `.once()`. Closes [#272](https://github.com/ckeditor/ckeditor5-utils/issues/272). Closes [#204](https://github.com/ckeditor/ckeditor5-utils/issues/204). ([54b8108](https://github.com/ckeditor/ckeditor5-utils/commit/54b8108))
-* Fixed memory leaks during editor initialization and destruction (see [ckeditor/ckeditor5#1341](https://github.com/ckeditor/ckeditor5/issues/1341)). ([94bc59e](https://github.com/ckeditor/ckeditor5-utils/commit/94bc59e))
-
-### Other changes
-
-* Configuration options should be cloned to prevent features from altering the original values. Closes [#257](https://github.com/ckeditor/ckeditor5-utils/issues/257). ([7981d4e](https://github.com/ckeditor/ckeditor5-utils/commit/7981d4e))
-* DOM Elements will not be cloned when returned from config.get. Closes [#264](https://github.com/ckeditor/ckeditor5-utils/issues/264). ([4ad23b1](https://github.com/ckeditor/ckeditor5-utils/commit/4ad23b1))
-* Optimized `diff()` function to use `fastDiff()` function internally for large data sets. Closes [#269](https://github.com/ckeditor/ckeditor5-utils/issues/269). ([ee9bed0](https://github.com/ckeditor/ckeditor5-utils/commit/ee9bed0))
-* Replaced `for..of` statement in `EventEmitter` with `Array.prototype.forEach`. This changes allows building a React application using `create-react-app@2`. Closes [ckeditor/ckeditor5-react#40](https://github.com/ckeditor/ckeditor5-react/issues/40). ([900b54b](https://github.com/ckeditor/ckeditor5-utils/commit/900b54b))
-
-### BREAKING CHANGES
-
-* Upgraded minimal versions of Node to `8.0.0` and npm to `5.7.1`. See: [ckeditor/ckeditor5#1507](https://github.com/ckeditor/ckeditor5/issues/1507). ([612ea3c](https://github.com/ckeditor/ckeditor5-cloud-services/commit/612ea3c))
-
-
-## [11.1.0](https://github.com/ckeditor/ckeditor5-utils/compare/v11.0.0...v11.1.0) (2018-12-05)
-
-### Features
-
-* Implemented `env#isGecko()`. See [ckeditor/ckeditor5-engine#1439](https://github.com/ckeditor/ckeditor5-engine/issues/1439). ([53b7c94](https://github.com/ckeditor/ckeditor5-utils/commit/53b7c94))
-
-### Other changes
-
-* Vairous fixes in the API docs. Thanks to [@denisname](https://github.com/denisname)!
-
-
-## [11.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v10.2.1...v11.0.0) (2018-10-08)
-
-### Other changes
-
-* Removed the `lodash` library from this package (a modular `lodash` build has been kept under `src/lib/lodash/`). We now recommend using `lodash-es` directly. Closes [#251](https://github.com/ckeditor/ckeditor5-utils/issues/251). ([637c9e3](https://github.com/ckeditor/ckeditor5-utils/commit/637c9e3))
-
-### BREAKING CHANGES
-
-* Removed the `lodash` library from this package (a modular `lodash` build has been kept under `src/lib/lodash/`). We now recommend using `lodash-es` directly.
-
-
-## [10.2.1](https://github.com/ckeditor/ckeditor5-utils/compare/v10.2.0...v10.2.1) (2018-07-18)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [10.2.0](https://github.com/ckeditor/ckeditor5-utils/compare/v10.1.0...v10.2.0) (2018-07-18)
-
-### Features
-
-* Implemented a module exposing the `CKEDIOR_VERSION` to the global scope. Closes [ckeditor/ckeditor5#1005](https://github.com/ckeditor/ckeditor5/issues/1005). ([3546ac4](https://github.com/ckeditor/ckeditor5-utils/commit/3546ac4))
-* Introduced `env.isEdge`. ([13d4af4](https://github.com/ckeditor/ckeditor5-utils/commit/13d4af4))
-
-### Bug fixes
-
-* The `isWindow()` helper should work in the Electron environment. Closes [ckeditor/ckeditor5#879](https://github.com/ckeditor/ckeditor5/issues/879). ([d561151](https://github.com/ckeditor/ckeditor5-utils/commit/d561151))
-
-
-## [10.1.0](https://github.com/ckeditor/ckeditor5-utils/compare/v10.0.0...v10.1.0) (2018-06-21)
-
-### Features
-
-* Introduced `set:{property}` event in `ObservableMixin`. Closes [#171](https://github.com/ckeditor/ckeditor5-utils/issues/171). ([6ef1246](https://github.com/ckeditor/ckeditor5-utils/commit/6ef1246))
-* Introduced `fastDiff()` function. Closes [#235](https://github.com/ckeditor/ckeditor5-utils/issues/235). ([81fefc9](https://github.com/ckeditor/ckeditor5-utils/commit/81fefc9))
-
-### Bug fixes
-
-* Error should not be thrown when scrolling the viewport from within an iframe in a different domain. Closes [ckeditor/ckeditor5#930](https://github.com/ckeditor/ckeditor5/issues/930). ([ad4656e](https://github.com/ckeditor/ckeditor5-utils/commit/ad4656e))
-
-
-## [10.0.0](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-beta.4...v10.0.0) (2018-04-25)
-
-### Other changes
-
-* Changed the license to GPL2+ only. See [ckeditor/ckeditor5#991](https://github.com/ckeditor/ckeditor5/issues/991). ([3177252](https://github.com/ckeditor/ckeditor5-utils/commit/3177252))
-
-### BREAKING CHANGES
-
-* The license under which CKEditor 5 is released has been changed from a triple GPL, LGPL and MPL license to a GPL2+ only. See [ckeditor/ckeditor5#991](https://github.com/ckeditor/ckeditor5/issues/991) for more information.
-
-
-## [1.0.0-beta.4](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-beta.2...v1.0.0-beta.4) (2018-04-19)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [1.0.0-beta.2](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-beta.1...v1.0.0-beta.2) (2018-04-10)
-
-Internal changes only (updated dependencies, documentation, etc.).
-
-
-## [1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-alpha.2...v1.0.0-beta.1) (2018-03-15)
-
-### Features
-
-* Introduce `bind().toMany()` binding chain in `ObservableMixin`. Closes [#224](https://github.com/ckeditor/ckeditor5-utils/issues/224). ([cfa7d0e](https://github.com/ckeditor/ckeditor5-utils/commit/cfa7d0e))
-* Introduced skipping items when binding collections. Closes [#215](https://github.com/ckeditor/ckeditor5-utils/issues/215). Closes https://github.com/ckeditor/ckeditor5-ui/issues/92. ([6e0d063](https://github.com/ckeditor/ckeditor5-utils/commit/6e0d063))
-
-### Bug fixes
-
-* `Rect.getDomRangeRects()` should not throw if the provided DOM range starts in a text node. Closes [ckeditor/ckeditor5-ui#317](https://github.com/ckeditor/ckeditor5-ui/issues/317). ([bfa55e9](https://github.com/ckeditor/ckeditor5-utils/commit/bfa55e9))
-* Bulletproofed `isDomNode()` helper when used in iframes. Removed `isWindow()` logic from the helper. Closes [#201](https://github.com/ckeditor/ckeditor5-utils/issues/201). ([84ccda2](https://github.com/ckeditor/ckeditor5-utils/commit/84ccda2))
-* Long keystrokes should be handled properly by getEnvKeystrokeText on Mac. Added support for ⇧ and ⌥ modifiers. Closes [#206](https://github.com/ckeditor/ckeditor5-utils/issues/206). ([d8443e2](https://github.com/ckeditor/ckeditor5-utils/commit/d8443e2))
-
-### Other changes
-
-* `ObservableMixin#unbind()` should not throw if used for an attribute which is not bound. Closes [#5](https://github.com/ckeditor/ckeditor5-utils/issues/5). ([848a818](https://github.com/ckeditor/ckeditor5-utils/commit/848a818))
-* Aligned behaviors of `EmitterMixin` methods responsible for adding end removing listeners. Closes [#144](https://github.com/ckeditor/ckeditor5-utils/issues/144). ([460d7f4](https://github.com/ckeditor/ckeditor5-utils/commit/460d7f4))
-
-  The `emitter.on()` now has the same behavior as `emitter.listenTo( emitter )` as well as `emitter.off()` is the same as `emitter.stopListening( emitter )`. This made `emitter.stopListening()` correctly remove all listeners added in any way to it which prevents memory leaks.
-* Aligned code to the new Translation Service ([ckeditor/ckeditor5#624](https://github.com/ckeditor/ckeditor5/issues/624)). ([a51767a](https://github.com/ckeditor/ckeditor5-utils/commit/a51767a))
-* Introduced the `isText()` helper. Closes [#214](https://github.com/ckeditor/ckeditor5-utils/issues/214). ([a9a6bec](https://github.com/ckeditor/ckeditor5-utils/commit/a9a6bec))
-* Renamed `env.mac` to `env.isMac`. Closes [#222](https://github.com/ckeditor/ckeditor5-utils/issues/222). ([dc6b226](https://github.com/ckeditor/ckeditor5-utils/commit/dc6b226))
-* Renamed `isDomNode()` to `isNode()`. Closes [#219](https://github.com/ckeditor/ckeditor5-utils/issues/219). ([1823196](https://github.com/ckeditor/ckeditor5-utils/commit/1823196))
-
-### BREAKING CHANGES
-
-* Renamed `env.mac` to `env.isMac`.
-* `isDomNode()` was renamed to `isNode()`.
-
-
-## [1.0.0-alpha.2](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2017-11-14)
-
-### Bug fixes
-
-* Removed a period at the end of an error message because some browsers included the period in links to errors. Closes [#193](https://github.com/ckeditor/ckeditor5-utils/issues/193). ([fdebc2f](https://github.com/ckeditor/ckeditor5-utils/commit/fdebc2f))
-
-
-## [1.0.0-alpha.1](https://github.com/ckeditor/ckeditor5-utils/compare/v0.10.0...v1.0.0-alpha.1) (2017-10-03)
-
-### Features
-
-* Scrolling DOM utilities should support multi-window scenarios. Closes [#175](https://github.com/ckeditor/ckeditor5-utils/issues/175). ([a5c27ea](https://github.com/ckeditor/ckeditor5-utils/commit/a5c27ea))
-
-### Other changes
-
-* `CKEditorError#message`, `log.error()` and `log.warn()` will contain a link to the error documentation. Closes [#185](https://github.com/ckeditor/ckeditor5-utils/issues/185). ([b7a00c9](https://github.com/ckeditor/ckeditor5-utils/commit/b7a00c9))
-
-
-## [0.10.0](https://github.com/ckeditor/ckeditor5-utils/compare/v0.9.1...v0.10.0) (2017-09-03)
-
-### Bug fixes
-
-* `FocusTracker` should remain in sync when multiple `blur` events are followed by the `focus` event. Closes [#159](https://github.com/ckeditor/ckeditor5-utils/issues/159). ([0ff1b34](https://github.com/ckeditor/ckeditor5-utils/commit/0ff1b34))
-
-### Features
-
-* `KeystrokeHandler` should support priorities and proper keystroke cancelling. Closes [#180](https://github.com/ckeditor/ckeditor5-utils/issues/180). ([14af24c](https://github.com/ckeditor/ckeditor5-utils/commit/14af24c))
-* Added support for `'space'` key code in the `parseKeystroke()` helper. Closes [#169](https://github.com/ckeditor/ckeditor5-utils/issues/169). ([f86b1ad](https://github.com/ckeditor/ckeditor5-utils/commit/f86b1ad))
-* Introduced `ObservableMixin#decorate()` and support for setting `EmitterMixin#fire()`'s return value by listeners. Closes [#162](https://github.com/ckeditor/ckeditor5-utils/issues/162). ([377c875](https://github.com/ckeditor/ckeditor5-utils/commit/377c875))
-* Introduced a static `Rect.getDomRangeRects()` method for external usage. Closes [#168](https://github.com/ckeditor/ckeditor5-utils/issues/168). ([f67aea1](https://github.com/ckeditor/ckeditor5-utils/commit/f67aea1))
-
-### Other changes
-
-* The `getOptimalPosition()` utility should accept the target option defined as a function. Closes [#157](https://github.com/ckeditor/ckeditor5-utils/issues/157). ([d63abae](https://github.com/ckeditor/ckeditor5-utils/commit/d63abae))
-
-
-## [0.9.1](https://github.com/ckeditor/ckeditor5-utils/compare/v0.9.0...v0.9.1) (2017-05-07)
-
-### Bug fixes
-
-* The `Rect` utility should work for collapsed DOM Ranges. Closes [#153](https://github.com/ckeditor/ckeditor5-utils/issues/153). ([92aff35](https://github.com/ckeditor/ckeditor5-utils/commit/92aff35))
-* The `getOptimalPosition()` utility should consider limiter ancestors with CSS overflow. Closes [#148](https://github.com/ckeditor/ckeditor5-utils/issues/148). ([6bf1741](https://github.com/ckeditor/ckeditor5-utils/commit/6bf1741))
-
-
-## [0.9.0](https://github.com/ckeditor/ckeditor5-utils/compare/v0.8.0...v0.9.0) (2017-04-05)
-
-### Bug fixes
-
-* The `getOptimalPosition()` utility should work fine when the parent element has a scroll. Closes [#139](https://github.com/ckeditor/ckeditor5-utils/issues/139). ([b878949](https://github.com/ckeditor/ckeditor5-utils/commit/b878949))
-
-### Features
-
-* `Collection.bindTo()` method now is not only available in the `ViewCollection` but in all `Collection`s. Closes [#125](https://github.com/ckeditor/ckeditor5-utils/issues/125). ([4e299be](https://github.com/ckeditor/ckeditor5-utils/commit/4e299be))
-* Added the `first()` function. Closes [#130](https://github.com/ckeditor/ckeditor5-utils/issues/130). ([8ab07d2](https://github.com/ckeditor/ckeditor5-utils/commit/8ab07d2))
-* Two–way data binding between `Collection` instances. Closes [#132](https://github.com/ckeditor/ckeditor5-utils/issues/132). ([6b79624](https://github.com/ckeditor/ckeditor5-utils/commit/6b79624))
-
-
-## [0.8.0](https://github.com/ckeditor/ckeditor5-utils/compare/v0.7.0...v0.8.0) (2017-03-06)
-
-### Features
-
-* Added ability to provide default configurations to `Config` constructor. Closes [#126](https://github.com/ckeditor/ckeditor5/issues/126). ([16a2a31](https://github.com/ckeditor/ckeditor5-utils/commit/16a2a31))