Merge pull request #288 from ckeditor/t/260

Feature: Allowed `BalloonPanelView` position limiter defined as a function. Made `ContextualBalloon` position limiter configurable via `#positionLimiter` property. Closes #260.

Author: oskarwrobel

src/panel/balloon/balloonpanelview.js

@@ -253,15 +253,8 @@ export default class BalloonPanelView extends View {
 	_startPinning( options ) {
 		this.attachTo( options );
 
-		const limiter = options.limiter || defaultLimiterElement;
-		let targetElement = null;
-
-		// We need to take HTMLElement related to the target if it is possible.
-		if ( isElement( options.target ) ) {
-			targetElement = options.target;
-		} else if ( isRange( options.target ) ) {
-			targetElement = options.target.commonAncestorContainer;
-		}
+		const targetElement = getDomElement( options.target );
+		const limiterElement = options.limiter ? getDomElement( options.limiter ) : defaultLimiterElement;
 
 		// Then we need to listen on scroll event of eny element in the document.
 		this.listenTo( global.document, 'scroll', ( evt, domEvt ) => {
@@ -271,10 +264,11 @@ export default class BalloonPanelView extends View {
 			const isWithinScrollTarget = targetElement && scrollTarget.contains( targetElement );
 
 			// The position needs to be updated if the positioning limiter is within the scrolled element.
-			const isLimiterWithinScrollTarget = scrollTarget.contains( limiter );
+			const isLimiterWithinScrollTarget = limiterElement && scrollTarget.contains( limiterElement );
 
-			// The positioning target can be a Rect, object etc.. There's no way to optimize the listener then.
-			if ( isWithinScrollTarget || isLimiterWithinScrollTarget || !targetElement ) {
+			// The positioning target and/or limiter can be a Rect, object etc..
+			// There's no way to optimize the listener then.
+			if ( isWithinScrollTarget || isLimiterWithinScrollTarget || !targetElement || !limiterElement ) {
 				this.attachTo( options );
 			}
 		}, { useCapture: true } );
@@ -296,6 +290,28 @@ export default class BalloonPanelView extends View {
 	}
 }
 
+// Returns the DOM element for given object or null, if there's none,
+// e.g. when passed object is a Rect instance or so.
+//
+// @private
+// @param {*} object
+// @returns {HTMLElement|null}
+function getDomElement( object ) {
+	if ( isElement( object ) ) {
+		return object;
+	}
+
+	if ( isRange( object ) ) {
+		return object.commonAncestorContainer;
+	}
+
+	if ( typeof object == 'function' ) {
+		return getDomElement( object() );
+	}
+
+	return null;
+}
+
 /**
  * A horizontal offset of the arrow tip from the edge of the balloon. Controlled by CSS.
  *

src/panel/balloon/contextualballoon.js

@@ -10,6 +10,7 @@
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import BalloonPanelView from './balloonpanelview';
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import first from '@ckeditor/ckeditor5-utils/src/first';
 
 /**
  * Provides the common contextual balloon panel for the editor.
@@ -47,6 +48,28 @@ export default class ContextualBalloon extends Plugin {
 		 */
 		this.view = new BalloonPanelView();
 
+		/**
+		 * The {@link module:utils/dom/position~Options#limiter position limiter}
+		 * for the {@link #view}, used when no `limiter` has been passed into {@link #add}
+		 * or {@link #updatePosition}.
+		 *
+		 * By default, a function, which obtains the farthest DOM
+		 * {@link module:engine/view/rooteditableelement~RootEditableElement}
+		 * of the {@link module:engine/view/document~Document#selection}.
+		 *
+		 * @member {module:utils/dom/position~Options#limiter} #positionLimiter
+		 */
+		this.positionLimiter = () => {
+			const view = this.editor.editing.view;
+			const editableElement = view.selection.editableElement;
+
+			if ( editableElement ) {
+				return view.domConverter.mapViewToDom( editableElement.root );
+			}
+
+			return null;
+		};
+
 		/**
 		 * Stack of the views injected into the balloon. Last one in the stack is displayed
 		 * as a content of {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon#view}.
@@ -196,6 +219,16 @@ export default class ContextualBalloon extends Plugin {
 	 * @returns {module:utils/dom/position~Options}
 	 */
 	_getBalloonPosition() {
-		return this._stack.values().next().value.position;
+		let position = first( this._stack.values() ).position;
+
+		// Use the default limiter if none has been specified.
+		if ( position && !position.limiter ) {
+			// Don't modify the original options object.
+			position = Object.assign( {}, position, {
+				limiter: this.positionLimiter
+			} );
+		}
+
+		return position;
 	}
 }

src/toolbar/contextual/contextualtoolbar.js

@@ -41,12 +41,14 @@ export default class ContextualToolbar extends Plugin {
 	 * @inheritDoc
 	 */
 	init() {
+		const editor = this.editor;
+
 		/**
 		 * The toolbar view displayed in the balloon.
 		 *
 		 * @member {module:ui/toolbar/toolbarview~ToolbarView}
 		 */
-		this.toolbarView = new ToolbarView( this.editor.locale );
+		this.toolbarView = new ToolbarView( editor.locale );
 
 		Template.extend( this.toolbarView.template, {
 			attributes: {
@@ -63,7 +65,7 @@ export default class ContextualToolbar extends Plugin {
 		 * @private
 		 * @member {module:ui/panel/balloon/contextualballoon~ContextualBalloon}
 		 */
-		this._balloon = this.editor.plugins.get( ContextualBalloon );
+		this._balloon = editor.plugins.get( ContextualBalloon );
 
 		/**
 		 * Fires {@link #event:_selectionChangeDebounced} event using `lodash#debounce`.
@@ -196,7 +198,8 @@ export default class ContextualToolbar extends Plugin {
 	 * @returns {module:utils/dom/position~Options}
 	 */
 	_getBalloonPositionData() {
-		const editingView = this.editor.editing.view;
+		const editor = this.editor;
+		const editingView = editor.editing.view;
 
 		// Get direction of the selection.
 		const isBackward = editingView.selection.isBackward;
@@ -213,7 +216,6 @@ export default class ContextualToolbar extends Plugin {
 				// Select the proper range rect depending on the direction of the selection.
 				return rangeRects[ isBackward ? 0 : rangeRects.length - 1 ];
 			},
-			limiter: this.editor.ui.view.editable.element,
 			positions: getBalloonPositions( isBackward )
 		};
 	}

tests/panel/balloon/balloonpanelview.js

@@ -614,6 +614,22 @@ describe( 'BalloonPanelView', () => {
 				sinon.assert.calledTwice( attachToSpy );
 			} );
 
+			it( 'should work for a function as a target/limiter', () => {
+				// Just check if this normally works without errors.
+				const rect = {};
+
+				view.pin( {
+					target() { return rect; },
+					limiter() { return limiter; }
+				} );
+
+				sinon.assert.calledOnce( attachToSpy );
+
+				limiter.dispatchEvent( new Event( 'scroll' ) );
+
+				sinon.assert.calledTwice( attachToSpy );
+			} );
+
 			// https://github.com/ckeditor/ckeditor5-ui/issues/227
 			it( 'should react to #scroll from anywhere when the target is not an HTMLElement or Range', () => {
 				const rect = {};
@@ -624,6 +640,17 @@ describe( 'BalloonPanelView', () => {
 				notRelatedElement.dispatchEvent( new Event( 'scroll' ) );
 				sinon.assert.calledTwice( attachToSpy );
 			} );
+
+			// https://github.com/ckeditor/ckeditor5-ui/issues/260
+			it( 'should react to #scroll from anywhere when the limiter is not an HTMLElement` or Range', () => {
+				const rect = {};
+
+				view.pin( { target, limiter: rect } );
+				sinon.assert.calledOnce( attachToSpy );
+
+				notRelatedElement.dispatchEvent( new Event( 'scroll' ) );
+				sinon.assert.calledTwice( attachToSpy );
+			} );
 		} );
 
 		describe( 'unpin()', () => {