Merge pull request #188 from ckeditor/t/182

Feature: Introduced `ContextualToolbar` plugin. Closes #182. Closes #187.

Introduced several new positions in `BalloonPanelView#defaultPositions`. Added `className` attribute to the `BalloonPanelView` interface.

BREAKING CHANGE: Default positions of the `BalloonPanelView` have been renamed.

BREAKING CHANGE: Class names controlling the arrow of the panel have been renamed.

Author: oleq

src/panel/balloon/balloonpanelview.js

@@ -52,7 +52,7 @@ export default class BalloonPanelView extends View {
 
 		/**
 		 * Balloon panel's current position. The position name is reflected in the CSS class set
-		 * to the balloon, i.e. `.ck-balloon-panel_arrow_se` for "arrow_se" position. The class
+		 * to the balloon, i.e. `.ck-balloon-panel_arrow_ne` for "arrow_ne" position. The class
 		 * controls the minor aspects of the balloon's visual appearance like placement
 		 * of the "arrow". To support a new position, an additional CSS must be created.
 		 *
@@ -64,10 +64,10 @@ export default class BalloonPanelView extends View {
 		 * See {@link #withArrow}.
 		 *
 		 * @observable
-		 * @default 'arrow_se'
-		 * @member {'arrow_se'|'arrow_sw'|'arrow_ne'|'arrow_nw'} #position
+		 * @default 'arrow_ne'
+		 * @member {'arrow_ne'|'arrow_nw'|'arrow_se'|'arrow_sw'} #position
 		 */
-		this.set( 'position', 'arrow_se' );
+		this.set( 'position', 'arrow_ne' );
 
 		/**
 		 * Controls whether the balloon panel is visible or not.
@@ -88,6 +88,14 @@ export default class BalloonPanelView extends View {
 		 */
 		this.set( 'withArrow', true );
 
+		/**
+		 * Additional css class added to the {#element}.
+		 *
+		 * @observable
+		 * @member {String} #className
+		 */
+		this.set( 'className' );
+
 		/**
 		 * Max width of the balloon panel, as in CSS.
 		 *
@@ -118,7 +126,8 @@ export default class BalloonPanelView extends View {
 					'ck-balloon-panel',
 					bind.to( 'position', ( value ) => `ck-balloon-panel_${ value }` ),
 					bind.if( 'isVisible', 'ck-balloon-panel_visible' ),
-					bind.if( 'withArrow', 'ck-balloon-panel_with-arrow' )
+					bind.if( 'withArrow', 'ck-balloon-panel_with-arrow' ),
+					bind.to( 'className' )
 				],
 
 				style: {
@@ -171,10 +180,10 @@ export default class BalloonPanelView extends View {
 		const positionOptions = Object.assign( {}, {
 			element: this.element,
 			positions: [
-				defaultPositions.se,
-				defaultPositions.sw,
-				defaultPositions.ne,
-				defaultPositions.nw
+				defaultPositions.southEastArrowNorthEast,
+				defaultPositions.southWestArrowNorthEast,
+				defaultPositions.northEastArrowSouthWest,
+				defaultPositions.northWestArrowSouthEast
 			],
 			limiter: defaultLimiterElement,
 			fitInViewport: true
@@ -324,7 +333,7 @@ BalloonPanelView.arrowVerticalOffset = 15;
  *
  * The available positioning functions are as follows:
  *
- * * South east:
+ * * South east (arrow north west):
  *
  *		[ Target ]
  *		    ^
@@ -333,7 +342,7 @@ BalloonPanelView.arrowVerticalOffset = 15;
  *		+-----------------+
  *
  *
- * * South west:
+ * * South west (arrow north east):
  *
  *		         [ Target ]
  *		              ^
@@ -342,7 +351,7 @@ BalloonPanelView.arrowVerticalOffset = 15;
  *		+-----------------+
  *
  *
- * * North east:
+ * * North east (arrow south west):
  *
  *		+-----------------+
  *		|     Balloon     |
@@ -351,14 +360,66 @@ BalloonPanelView.arrowVerticalOffset = 15;
  *		[ Target ]
  *
  *
- * * North west:
+ * * North west (arrow south east):
  *
  *		+-----------------+
  *		|     Balloon     |
  *		+-----------------+
  *		              V
  *		         [ Target ]
  *
+ *
+ * * South east (arrow north):
+ *
+ * 		      [ Target ]
+ * 		           ^
+ * 		  +-----------------+
+ * 		  |     Balloon     |
+ * 		  +-----------------+
+ *
+ *
+ * * North east (arrow south):
+ *
+ * 		  +-----------------+
+ * 		  |     Balloon     |
+ * 		  +-----------------+
+ * 		           V
+ * 		      [ Target ]
+ *
+ *
+ * * North west (arrow south):
+ *
+ * 		+-----------------+
+ * 		|     Balloon     |
+ * 		+-----------------+
+ * 		         V
+ * 		    [ Target ]
+ *
+ *
+ * * South west (arrow north):
+ *
+ * 		    [ Target ]
+ * 		         ^
+ * 		+-----------------+
+ * 		|     Balloon     |
+ * 		+-----------------+
+ *
+ * * South (arrow north):
+ *
+ * 		     [ Target ]
+ * 		         ^
+ * 		+-----------------+
+ * 		|     Balloon     |
+ * 		+-----------------+
+ *
+ * * North (arrow south):
+ *
+ * 		+-----------------+
+ * 		|     Balloon     |
+ * 		+-----------------+
+ * 		        V
+ * 		    [ Target ]
+ *
  * See {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo}.
  *
  * Positioning functions must be compatible with {@link module:utils/dom/position~Position}.
@@ -369,27 +430,63 @@ BalloonPanelView.arrowVerticalOffset = 15;
  * @member {Object} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions
  */
 BalloonPanelView.defaultPositions = {
-	se: ( targetRect ) => ( {
+	southEastArrowNorthEast: ( targetRect ) => ( {
 		top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
 		left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
-		name: 'arrow_se'
+		name: 'arrow_ne'
 	} ),
 
-	sw: ( targetRect, balloonRect ) => ( {
+	southWestArrowNorthEast: ( targetRect, balloonRect ) => ( {
 		top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
 		left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
-		name: 'arrow_sw'
+		name: 'arrow_nw'
 	} ),
 
-	ne: ( targetRect, balloonRect ) => ( {
+	northEastArrowSouthWest: ( targetRect, balloonRect ) => ( {
 		top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
 		left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
-		name: 'arrow_ne'
+		name: 'arrow_se'
 	} ),
 
-	nw: ( targetRect, balloonRect ) => ( {
+	northWestArrowSouthEast: ( targetRect, balloonRect ) => ( {
 		top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
 		left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
-		name: 'arrow_nw'
+		name: 'arrow_sw'
+	} ),
+
+	southEastArrowNorth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.right - balloonRect.width / 2,
+		name: 'arrow_n'
+	} ),
+
+	northEastArrowSouth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.right - balloonRect.width / 2,
+		name: 'arrow_s'
+	} ),
+
+	northWestArrowSouth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.left - balloonRect.width / 2,
+		name: 'arrow_s'
+	} ),
+
+	southWestArrowNorth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.left - balloonRect.width / 2,
+		name: 'arrow_n'
+	} ),
+
+	southArrowNorth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
+		name: 'arrow_n'
+	} ),
+
+	northArrowSouth: ( targetRect, balloonRect ) => ( {
+		top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
+		left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
+		name: 'arrow_s'
 	} )
 };

src/panel/balloon/contextualballoon.js

@@ -28,6 +28,13 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  * @extends module:core/plugin~Plugin
  */
 export default class ContextualBalloon extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ui/contextualballoon';
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -56,10 +63,6 @@ export default class ContextualBalloon extends Plugin {
 		return this.editor.ui.view.body.add( this.view );
 	}
 
-	static get pluginName() {
-		return 'contextualballoon';
-	}
-
 	/**
 	 * Returns the currently visible view or `null` when there are no
 	 * views in the stack.
@@ -88,6 +91,7 @@ export default class ContextualBalloon extends Plugin {
 	 * @param {Object} data Configuration of the view.
 	 * @param {module:ui/view~View} [data.view] Content of the balloon.
 	 * @param {module:utils/dom/position~Options} [data.position] Positioning options.
+	 * @param {String} [data.balloonClassName] Additional css class for {@link #view} added when given view is visible.
 	 * @returns {Promise} A Promise resolved when the child {@link module:ui/view~View#init} is done.
 	 */
 	add( data ) {
@@ -109,7 +113,7 @@ export default class ContextualBalloon extends Plugin {
 		// Add new view to the stack.
 		this._stack.set( data.view, data );
 		// And display it.
-		return this._show( data.view );
+		return this._show( data );
 	}
 
 	/**
@@ -147,7 +151,7 @@ export default class ContextualBalloon extends Plugin {
 			// If it is some other view.
 			if ( last ) {
 				// Just show it.
-				promise = this._show( last.view );
+				promise = this._show( last );
 			} else {
 				// Hide the balloon panel.
 				this.view.hide();
@@ -161,10 +165,16 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Updates the position of the balloon panel according to position data
-	 * of the first view in the stack.
+	 * Updates the position of the balloon panel according to the given position data
+	 * or position data of the first view in the stack.
+	 *
+	 * @param {module:utils/dom/position~Options} [position] position options.
 	 */
-	updatePosition() {
+	updatePosition( position ) {
+		if ( position ) {
+			this._stack.values().next().value.position = position;
+		}
+
 		this.view.attachTo( this._getBalloonPosition() );
 	}
 
@@ -173,10 +183,13 @@ export default class ContextualBalloon extends Plugin {
 	 * options of the first view.
 	 *
 	 * @private
-	 * @param {module:ui/view~View} view View to show in the balloon.
-	 * @returns {Promise} A Promise resolved when the child {@link module:ui/view~View#init} is done.
+	 * @param {Object} data Configuration.
+	 * @param {module:ui/view~View} [data.view] View to show in the balloon.
+	 * @param {String} [data.balloonClassName=''] Additional class name which will added to the {#_balloon} view.
 	 */
-	_show( view ) {
+	_show( { view, balloonClassName = '' } ) {
+		this.view.className = balloonClassName;
+
 		return this.view.content.add( view ).then( () => {
 			this.view.pin( this._getBalloonPosition() );
 		} );
@@ -190,7 +203,7 @@ export default class ContextualBalloon extends Plugin {
 	 * @returns {module:utils/dom/position~Options}
 	 */
 	_getBalloonPosition() {
-		return Array.from( this._stack.values() )[ 0 ].position;
+		return this._stack.values().next().value.position;
 	}
 
 	/**