Viewport offset aware and sticky positions

packages/ckeditor5-image/src/image/ui/utils.js

@@ -47,7 +47,8 @@ export function getBalloonPositionData( editor ) {
 			defaultPositions.northArrowSouthEast,
 			defaultPositions.southArrowNorth,
 			defaultPositions.southArrowNorthWest,
-			defaultPositions.southArrowNorthEast
+			defaultPositions.southArrowNorthEast,
+			defaultPositions.viewportStickyNorth
 		]
 	};
 }

packages/ckeditor5-image/tests/image/ui/utils.js

@@ -22,7 +22,8 @@ describe( 'Utils', () => {
 		defaultPositions.northArrowSouthEast,
 		defaultPositions.southArrowNorth,
 		defaultPositions.southArrowNorthWest,
-		defaultPositions.southArrowNorthEast
+		defaultPositions.southArrowNorthEast,
+		defaultPositions.viewportStickyNorth
 	];
 
 	let editor, converter, selection, balloon, editorElement;

packages/ckeditor5-mention/src/mentionui.js

@@ -463,7 +463,9 @@ export default class MentionUI extends Plugin {
 			this._balloon.add( {
 				view: this._mentionsView,
 				position: this._getBalloonPanelPositionData( markerMarker, this._mentionsView.position ),
-				withArrow: false,
+				config: {
+					withArrow: false
+				},
 				singleViewMode: true
 			} );
 		}
@@ -586,7 +588,10 @@ function getBalloonPanelPositions( preferredPosition ) {
 			return {
 				top: targetRect.bottom + VERTICAL_SPACING,
 				left: targetRect.right,
-				name: 'caret_se'
+				name: 'caret_se',
+				config: {
+					withArrow: false
+				}
 			};
 		},
 
@@ -595,7 +600,10 @@ function getBalloonPanelPositions( preferredPosition ) {
 			return {
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
 				left: targetRect.right,
-				name: 'caret_ne'
+				name: 'caret_ne',
+				config: {
+					withArrow: false
+				}
 			};
 		},
 
@@ -604,7 +612,10 @@ function getBalloonPanelPositions( preferredPosition ) {
 			return {
 				top: targetRect.bottom + VERTICAL_SPACING,
 				left: targetRect.right - balloonRect.width,
-				name: 'caret_sw'
+				name: 'caret_sw',
+				config: {
+					withArrow: false
+				}
 			};
 		},
 
@@ -613,7 +624,10 @@ function getBalloonPanelPositions( preferredPosition ) {
 			return {
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
 				left: targetRect.right - balloonRect.width,
-				name: 'caret_nw'
+				name: 'caret_nw',
+				config: {
+					withArrow: false
+				}
 			};
 		}
 	};

packages/ckeditor5-mention/tests/mentionui.js

@@ -196,25 +196,37 @@ describe( 'MentionUI', () => {
 					expect( caretSouthEast( caretRect, balloonRect ) ).to.deep.equal( {
 						left: 501,
 						name: 'caret_se',
-						top: 121
+						top: 121,
+						config: {
+							withArrow: false
+						}
 					} );
 
 					expect( caretSouthWest( caretRect, balloonRect ) ).to.deep.equal( {
 						left: 301,
 						name: 'caret_sw',
-						top: 121
+						top: 121,
+						config: {
+							withArrow: false
+						}
 					} );
 
 					expect( caretNorthEast( caretRect, balloonRect ) ).to.deep.equal( {
 						left: 501,
 						name: 'caret_ne',
-						top: -53
+						top: -53,
+						config: {
+							withArrow: false
+						}
 					} );
 
 					expect( caretNorthWest( caretRect, balloonRect ) ).to.deep.equal( {
 						left: 301,
 						name: 'caret_nw',
-						top: -53
+						top: -53,
+						config: {
+							withArrow: false
+						}
 					} );
 				} );
 		} );

packages/ckeditor5-table/src/utils/ui/contextualballoon.js

@@ -7,7 +7,6 @@
  * @module table/utils/ui/contextualballoon
  */
 
-import { centeredBalloonPositionForLongWidgets } from 'ckeditor5/src/widget';
 import { Rect } from 'ckeditor5/src/utils';
 import { BalloonPanelView } from 'ckeditor5/src/ui';
 
@@ -21,12 +20,8 @@ const BALLOON_POSITIONS = [
 	DEFAULT_BALLOON_POSITIONS.northArrowSouthEast,
 	DEFAULT_BALLOON_POSITIONS.southArrowNorth,
 	DEFAULT_BALLOON_POSITIONS.southArrowNorthWest,
-	DEFAULT_BALLOON_POSITIONS.southArrowNorthEast
-];
-
-const TABLE_PROPERTIES_BALLOON_POSITIONS = [
-	...BALLOON_POSITIONS,
-	centeredBalloonPositionForLongWidgets
+	DEFAULT_BALLOON_POSITIONS.southArrowNorthEast,
+	DEFAULT_BALLOON_POSITIONS.viewportStickyNorth
 ];
 
 /**
@@ -69,7 +64,7 @@ export function getBalloonTablePositionData( editor ) {
 
 	return {
 		target: editor.editing.view.domConverter.viewToDom( viewTable ),
-		positions: TABLE_PROPERTIES_BALLOON_POSITIONS
+		positions: BALLOON_POSITIONS
 	};
 }
 

packages/ckeditor5-table/tests/utils/ui/contextualballoon.js

@@ -13,7 +13,6 @@ import BalloonPanelView from '@ckeditor/ckeditor5-ui/src/panel/balloon/balloonpa
 
 import { setData } from '@ckeditor/ckeditor5-engine/src/dev-utils/model';
 import testUtils from '@ckeditor/ckeditor5-core/tests/_utils/utils';
-import { centeredBalloonPositionForLongWidgets } from '@ckeditor/ckeditor5-widget/src/utils';
 import { modelTable } from '../../_utils/utils';
 import { getTableCellsContainingSelection } from '../../../src/utils/selection';
 import { getBalloonCellPositionData, repositionContextualBalloon } from '../../../src/utils/ui/contextualballoon';
@@ -79,7 +78,8 @@ describe( 'table utils', () => {
 							defaultPositions.northArrowSouthEast,
 							defaultPositions.southArrowNorth,
 							defaultPositions.southArrowNorthWest,
-							defaultPositions.southArrowNorthEast
+							defaultPositions.southArrowNorthEast,
+							defaultPositions.viewportStickyNorth
 						]
 					} );
 				} );
@@ -128,7 +128,7 @@ describe( 'table utils', () => {
 							defaultPositions.southArrowNorth,
 							defaultPositions.southArrowNorthWest,
 							defaultPositions.southArrowNorthEast,
-							centeredBalloonPositionForLongWidgets
+							defaultPositions.viewportStickyNorth
 						]
 					} );
 				} );
@@ -186,7 +186,8 @@ describe( 'table utils', () => {
 						defaultPositions.northArrowSouthEast,
 						defaultPositions.southArrowNorth,
 						defaultPositions.southArrowNorthWest,
-						defaultPositions.southArrowNorthEast
+						defaultPositions.southArrowNorthEast,
+						defaultPositions.viewportStickyNorth
 					]
 				} );
 			} );

packages/ckeditor5-ui/src/panel/balloon/balloonpanelview.js

@@ -232,7 +232,8 @@ export default class BalloonPanelView extends View {
 				defaultPositions.northArrowSouthMiddleWest,
 				defaultPositions.northArrowSouthMiddleEast,
 				defaultPositions.northArrowSouthWest,
-				defaultPositions.northArrowSouthEast
+				defaultPositions.northArrowSouthEast,
+				defaultPositions.viewportStickyNorth
 			],
 			limiter: defaultLimiterElement,
 			fitInViewport: true
@@ -244,9 +245,11 @@ export default class BalloonPanelView extends View {
 		// so it is better to use int values.
 		const left = parseInt( optimalPosition.left );
 		const top = parseInt( optimalPosition.top );
-		const position = optimalPosition.name;
 
-		Object.assign( this, { top, left, position } );
+		const { name: position, config = {} } = optimalPosition;
+		const { withArrow } = config;
+
+		Object.assign( this, { top, left, position, withArrow } );
 	}
 
 	/**
@@ -401,7 +404,7 @@ function getDomElement( object ) {
  *		      \|/
  *	    >|-----|<---------------- horizontal offset
  *
- * @default 30
+ * @default 25
  * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowHorizontalOffset
  */
 BalloonPanelView.arrowHorizontalOffset = 25;
@@ -420,11 +423,26 @@ BalloonPanelView.arrowHorizontalOffset = 25;
  *		-------------------------------
  *		                       ^
  *
- * @default 15
+ * @default 10
  * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowVerticalOffset
  */
 BalloonPanelView.arrowVerticalOffset = 10;
 
+/**
+ * A vertical offset of the balloon panel from the edge of the viewport if sticky.
+ * It helps in accessing toolbar buttons underneath the balloon panel.
+ *
+ *       Toolbar                        /-- vertical offset
+ *       +-----------------------------V--------------------+
+ *       |                  +-------------+                 |
+ *       +------------------|   Balloon   |-----------------+
+ *                          +-------------+
+ *
+ * @default 20
+ * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.stickyVerticalOffset
+ */
+BalloonPanelView.stickyVerticalOffset = 20;
+
 /**
  * Function used to calculate the optimal position for the balloon.
  *
@@ -702,6 +720,22 @@ BalloonPanelView._getOptimalPosition = getOptimalPosition;
  *		|     Balloon     |
  *		+-----------------+
  *
+ * * `viewportStickyNorth`
+ *
+ *	    +---------------------------+
+ *	    |        [ Target ]         |
+ *	    |                           |
+ *	+-----------------------------------+
+ *	|   |    +-----------------+    |   |
+ *	|   |    |     Balloon     |    |   |
+ *	|   |    +-----------------+    |   |
+ *	|   |                           |   |
+ *	|   |                           |   |
+ *	|   |                           |   |
+ * 	|   |                           |   |
+ *	|   +---------------------------+   |
+ * 	|             Viewport              |
+ *	+-----------------------------------+
  *
  * See {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo}.
  *
@@ -791,6 +825,7 @@ BalloonPanelView.defaultPositions = {
 		left: targetRect.right - ( balloonRect.width * .25 ) - BalloonPanelView.arrowHorizontalOffset,
 		name: 'arrow_smw'
 	} ),
+
 	northEastArrowSouth: ( targetRect, balloonRect ) => ( {
 		top: getNorthTop( targetRect, balloonRect ),
 		left: targetRect.right - balloonRect.width / 2,
@@ -808,6 +843,7 @@ BalloonPanelView.defaultPositions = {
 		left: targetRect.right - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
 		name: 'arrow_se'
 	} ),
+
 	// ------- South west
 
 	southWestArrowNorthWest: ( targetRect, balloonRect ) => ( {
@@ -901,8 +937,24 @@ BalloonPanelView.defaultPositions = {
 		top: getSouthTop( targetRect, balloonRect ),
 		left: targetRect.right - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
 		name: 'arrow_ne'
-	} )
+	} ),
+
+	// ------- Sticky
+
+	viewportStickyNorth: ( targetRect, balloonRect, viewportRect ) => {
+		if ( !targetRect.getIntersection( viewportRect ) ) {
+			return null;
+		}
 
+		return {
+			top: viewportRect.top + BalloonPanelView.stickyVerticalOffset,
+			left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
+			name: 'arrowless',
+			config: {
+				withArrow: false
+			}
+		};
+	}
 };
 
 // Returns the top coordinate for positions starting with `north*`.

packages/ckeditor5-ui/src/panel/balloon/contextualballoon.js

@@ -498,11 +498,18 @@ export default class ContextualBalloon extends Plugin {
 	_getBalloonPosition() {
 		let position = Array.from( this._visibleStack.values() ).pop().position;
 
-		// Use the default limiter if none has been specified.
-		if ( position && !position.limiter ) {
+		if ( position ) {
+			// Use the default limiter if none has been specified.
+			if ( !position.limiter ) {
+				// Don't modify the original options object.
+				position = Object.assign( {}, position, {
+					limiter: this.positionLimiter
+				} );
+			}
+
 			// Don't modify the original options object.
 			position = Object.assign( {}, position, {
-				limiter: this.positionLimiter
+				viewportOffsetConfig: this.editor.config.get( 'ui.viewportOffset' )
 			} );
 		}
 

packages/ckeditor5-ui/tests/manual/panel/balloon/balloonpanelview.js

@@ -10,6 +10,10 @@ import BalloonPanelView from '../../../../src/panel/balloon/balloonpanelview';
 const defaultPositions = BalloonPanelView.defaultPositions;
 const container = document.querySelector( '#container' );
 
+// It makes no sense to test the sticky position in this context,
+// thus exclude it from this manual test.
+delete defaultPositions.viewportStickyNorth;
+
 let currentHeading = '';
 
 for ( const i in defaultPositions ) {