Merge pull request #8507 from ckeditor/i/6146-multiline-toolbar

Feature (ui, theme-lark): Implemented a toolbar configuration that allows rendering toolbar items in multiple rows. Closes #6146.

Feature (build-decoupled-document): Added new features to the build configuration (horizontal line, page break, remove formatting, and special characters) (see #6146).

Internal (editor-inline): Aligned the editor view to the latest API of `ToolbarView` (see #6146).

Docs (core): Explained how to configure the editor toolbar to make it break in multiple lines (see #6146).

docs/builds/guides/integration/configuration.md

@@ -33,7 +33,7 @@ As you can see, configurations are set by a simple JavaScript object passed to t
 
 ## Removing features
 
-Builds come with all features included in the distribution package enabled by default. They are defined as plugins for CKEditor.
+The official builds come with all the features included in the distribution package enabled by default. They are defined as plugins for CKEditor.
 
 In some cases, you may need to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in the editor at runtime.
 
@@ -119,7 +119,7 @@ ClassicEditor
 
 ## Toolbar setup
 
-In builds that contain toolbars an optimal default configuration is defined for it. You may need a different toolbar arrangement, though, and this can be achieved through configuration.
+In the builds that contain toolbars an optimal default configuration is defined for it. You may need a different toolbar arrangement, though, and this can be achieved through configuration.
 
 Each editor may have a different toolbar configuration scheme, so it is recommended to check its documentation. In any case, the following example may give you a general idea:
 
@@ -133,6 +133,46 @@ ClassicEditor
 	} );
 ```
 
+### Extended format
+
+You can use the extended toolbar configuration format to access additional options:
+
+```js
+    toolbar: {
+        items: [ 'bold', 'italic', '|', 'undo', 'redo', '-', 'numberedList', 'bulletedList' ],
+        viewportTopOffset: 30,
+        shouldNotGroupWhenFull: true
+    }
+```
+
+ * **`items`** – An array of toolbar item names. Most of the components (buttons, dropdowns, etc.) which can be used as toolbar items are described under the {@link features/index Features} tab. A full list is defined in {@link module:ui/componentfactory~ComponentFactory editor.ui.componentFactory} and can be listed using the following snippet: `Array.from( editor.ui.componentFactory.names() )`. More details could be found in the {@link framework/guides/creating-simple-plugin Creating a simple plugin} guide.
+
+ * **`viewportTopOffset`** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar. Useful when a page with which the editor is being integrated has some other sticky or fixed elements (e.g. the top menu). Thanks to setting the toolbar offset, the toolbar will not be positioned underneath or above the page's UI.
+
+ * **`shouldNotGroupWhenFull`** – When set to `true`, the toolbar will stop grouping items and let them wrap to the next line when there is not enough space to display them in a single row. This setting is `false` by default, which enables items grouping.
+
+#### Separating toolbar items
+
+You can use `'|'` to create a separator between groups of toolbar items. Works in both config formats:
+
+```js
+    toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
+```
+
+```js
+    toolbar: {
+        items: [ 'bold', 'italic', '|', 'undo', 'redo' ]
+    }
+```
+
+It is also possible to arrange toolbar items into multiple lines. In the extended format set `shouldNotGroupWhenFull` option to `true`, so items will not be grouped when the toolbar overflows but will wrap to the new line instead. Additionally, a `'-'` could be used inside items list to set the breaking point explicitly.
+
+```js
+    toolbar: {
+        items: [ 'bold', 'italic', '-', 'undo', 'redo' ]
+    }
+```
+
 <info-box hint>
 	The above is a strict UI-related configuration. Removing a toolbar item does not remove the feature from the editor internals. If your goal with the toolbar configuration is to remove features, the right solution is to also remove their respective plugins. Check [Removing features](#removing-features) above for more information.
 </info-box>

docs/builds/guides/migrate.md

@@ -648,7 +648,7 @@ Note: The number of options was reduced on purpose. We understood that configuri
 		</tr>
 		<tr>
 			<td><a href="../../../../ckeditor4/latest/api/CKEDITOR_config.html#cfg-toolbarGroupCycling">toolbarGroupCycling</a> <br> <a href="../../../../ckeditor4/latest/api/CKEDITOR_config.html#cfg-toolbarGroups">toolbarGroups</a></td>
-			<td>N/A. {@link module:core/editor/editorconfig~EditorConfig#toolbar Toolbar buttons can be grouped} by using <code>'|'</code> as a separator.</td>
+			<td>N/A. {@link module:core/editor/editorconfig~EditorConfig#toolbar The toolbar buttons can be grouped} by using <code>'|'</code> as a separator or divided into multiple lines by using <code>'-'</code>.</td>
 		</tr>
 		<tr>
 			<td><a href="../../../../ckeditor4/latest/api/CKEDITOR_config.html#cfg-toolbarLocation">toolbarLocation</a></td>

packages/ckeditor5-build-decoupled-document/package.json

@@ -40,13 +40,17 @@
     "@ckeditor/ckeditor5-font": "^23.1.0",
     "@ckeditor/ckeditor5-heading": "^23.1.0",
     "@ckeditor/ckeditor5-highlight": "^23.1.0",
+    "@ckeditor/ckeditor5-horizontal-line": "^23.1.0",
     "@ckeditor/ckeditor5-image": "^23.1.0",
     "@ckeditor/ckeditor5-indent": "^23.1.0",
     "@ckeditor/ckeditor5-link": "^23.1.0",
     "@ckeditor/ckeditor5-list": "^23.1.0",
     "@ckeditor/ckeditor5-media-embed": "^23.1.0",
     "@ckeditor/ckeditor5-paragraph": "^23.1.0",
     "@ckeditor/ckeditor5-paste-from-office": "^23.1.0",
+    "@ckeditor/ckeditor5-page-break": "^23.1.0",
+    "@ckeditor/ckeditor5-remove-format": "^23.1.0",
+    "@ckeditor/ckeditor5-special-characters": "^23.1.0",
     "@ckeditor/ckeditor5-table": "^23.1.0",
     "@ckeditor/ckeditor5-typing": "^23.1.0",
     "@ckeditor/ckeditor5-theme-lark": "^23.1.0",

packages/ckeditor5-build-decoupled-document/src/ckeditor.js

@@ -22,6 +22,7 @@ import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
 import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';
 import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';
 import Heading from '@ckeditor/ckeditor5-heading/src/heading';
+import HorizontalLine from '@ckeditor/ckeditor5-horizontal-line/src/horizontalline';
 import Image from '@ckeditor/ckeditor5-image/src/image';
 import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
 import ImageStyle from '@ckeditor/ckeditor5-image/src/imagestyle';
@@ -33,8 +34,12 @@ import Link from '@ckeditor/ckeditor5-link/src/link';
 import List from '@ckeditor/ckeditor5-list/src/list';
 import ListStyle from '@ckeditor/ckeditor5-list/src/liststyle';
 import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/mediaembed';
+import PageBreak from '@ckeditor/ckeditor5-page-break/src/pagebreak';
 import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
 import PasteFromOffice from '@ckeditor/ckeditor5-paste-from-office/src/pastefromoffice';
+import RemoveFormat from '@ckeditor/ckeditor5-remove-format/src/removeformat';
+import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
+import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
 import Table from '@ckeditor/ckeditor5-table/src/table';
 import TableToolbar from '@ckeditor/ckeditor5-table/src/tabletoolbar';
 import TextTransformation from '@ckeditor/ckeditor5-typing/src/texttransformation';
@@ -69,9 +74,14 @@ DecoupledEditor.builtinPlugins = [
 	Link,
 	List,
 	ListStyle,
+	HorizontalLine,
 	MediaEmbed,
 	Paragraph,
+	PageBreak,
 	PasteFromOffice,
+	RemoveFormat,
+	SpecialCharacters,
+	SpecialCharactersEssentials,
 	Table,
 	TableToolbar,
 	TextTransformation
@@ -93,23 +103,34 @@ DecoupledEditor.defaultConfig = {
 			'underline',
 			'strikethrough',
 			'|',
-			'alignment',
+			'link',
+			'blockquote',
+			'|',
+			'undo',
+			'redo',
+			'-',
+			'alignment:left',
+			'alignment:right',
+			'alignment:center',
+			'alignment:justify',
 			'|',
 			'numberedList',
 			'bulletedList',
-			'|',
 			'indent',
 			'outdent',
 			'|',
-			'link',
-			'blockquote',
 			'imageUpload',
 			'insertTable',
 			'mediaEmbed',
+			'specialCharacters',
 			'|',
-			'undo',
-			'redo'
-		]
+			'pageBreak',
+			'horizontalLine',
+			'|',
+			'removeformat'
+		],
+
+		shouldNotGroupWhenFull: true
 	},
 	image: {
 		styles: [

packages/ckeditor5-core/src/editor/editorconfig.jsdoc

@@ -142,7 +142,7 @@
  *
  *		const config = {
  *			toolbar: {
- *				items: [ 'bold', 'italic', '|', 'undo', 'redo' ],
+ *				items: [ 'bold', 'italic', '|', 'undo', 'redo', '-', 'numberedList', 'bulletedList' ],
  *
  *				viewportTopOffset: 30,
  *
@@ -161,11 +161,17 @@
  *
  *		toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
  *
+ *	or `'-'` to make a line break and render items in multiple lines:
+ *
+ *		toolbar: [ 'bold', 'italic', '-', 'undo', 'redo' ]
+ *
+ *	Line break will work only in the extended format when `shouldNotGroupWhenFull` option is set to `true`.
+ *
  * * **`toolbar.viewportTopOffset`** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
  * Useful when a page with which the editor is being integrated has some other sticky or fixed elements
  * (e.g. the top menu). Thanks to setting the toolbar offset the toolbar will not be positioned underneath or above the page's UI.
- * * **`toolbar.shouldNotGroupWhenFull`** – When set `true`, the toolbar will stop grouping items that wrap to the next line when
- * there is not enough space to display them in a single row.
+ * * **`toolbar.shouldNotGroupWhenFull`** – When set to `true`, the toolbar will stop grouping items
+ * and let them wrap to the next line if there is not enough space to display them in a single row.
  *
  * @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
  */

packages/ckeditor5-editor-inline/src/inlineeditoruiview.js

@@ -45,7 +45,8 @@ export default class InlineEditorUIView extends EditorUIView {
 		 * @member {module:ui/toolbar/toolbarview~ToolbarView}
 		 */
 		this.toolbar = new ToolbarView( locale, {
-			shouldGroupWhenFull: options.shouldToolbarGroupWhenFull
+			shouldGroupWhenFull: options.shouldToolbarGroupWhenFull,
+			isFloating: true
 		} );
 
 		/**
@@ -63,15 +64,6 @@ export default class InlineEditorUIView extends EditorUIView {
 		 */
 		this.set( 'viewportTopOffset', 0 );
 
-		this.toolbar.extendTemplate( {
-			attributes: {
-				class: [
-					// https://github.com/ckeditor/ckeditor5-editor-inline/issues/11
-					'ck-toolbar_floating'
-				]
-			}
-		} );
-
 		/**
 		 * A balloon panel view instance.
 		 *

packages/ckeditor5-editor-inline/tests/inlineeditoruiview.js

@@ -74,6 +74,10 @@ describe( 'InlineEditorUIView', () => {
 
 				view.destroy();
 			} );
+
+			it( 'should have the isFloating option set to true', () => {
+				expect( view.toolbar.options.isFloating ).to.be.true;
+			} );
 		} );
 
 		describe( '#panel', () => {
@@ -115,10 +119,6 @@ describe( 'InlineEditorUIView', () => {
 		} );
 
 		describe( '#toolbar', () => {
-			it( 'is given the right CSS classes', () => {
-				expect( view.toolbar.element.classList.contains( 'ck-toolbar_floating' ) ).to.be.true;
-			} );
-
 			it( 'sets the default value of the #viewportTopOffset attribute', () => {
 				expect( view.viewportTopOffset ).to.equal( 0 );
 			} );

packages/ckeditor5-theme-lark/theme/ckeditor5-ui/components/toolbar/toolbar.css

@@ -27,12 +27,12 @@
 		margin-bottom: var(--ck-spacing-small);
 	}
 
-	& > .ck-toolbar__items {
-		& > * {
-			/* Make sure items wrapped to the next line have v-spacing */
-			margin-top: var(--ck-spacing-small);
-			margin-bottom: var(--ck-spacing-small);
+	& .ck-toolbar__line-break {
+		height: 0;
+	}
 
+	& > .ck-toolbar__items {
+		& > *:not(.ck-toolbar__line-break) {
 			/* (#11) Separate toolbar items. */
 			margin-right: var(--ck-spacing-small);
 		}
@@ -44,7 +44,7 @@
 		}
 	}
 
-	& > .ck-toolbar__items > *,
+	& > .ck-toolbar__items > *:not(.ck-toolbar__line-break),
 	& > .ck.ck-toolbar__grouped-dropdown {
 		/* Make sure items wrapped to the next line have v-spacing */
 		margin-top: var(--ck-spacing-small);

packages/ckeditor5-ui/src/toolbar/balloon/balloontoolbar.js

@@ -197,13 +197,8 @@ export default class BalloonToolbar extends Plugin {
 	_createToolbarView() {
 		const shouldGroupWhenFull = !this._balloonConfig.shouldNotGroupWhenFull;
 		const toolbarView = new ToolbarView( this.editor.locale, {
-			shouldGroupWhenFull
-		} );
-
-		toolbarView.extendTemplate( {
-			attributes: {
-				class: [ 'ck-toolbar_floating' ]
-			}
+			shouldGroupWhenFull,
+			isFloating: true
 		} );
 
 		toolbarView.render();

packages/ckeditor5-ui/src/toolbar/block/blocktoolbar.js

@@ -223,14 +223,8 @@ export default class BlockToolbar extends Plugin {
 	_createToolbarView() {
 		const shouldGroupWhenFull = !this._blockToolbarConfig.shouldNotGroupWhenFull;
 		const toolbarView = new ToolbarView( this.editor.locale, {
-			shouldGroupWhenFull
-		} );
-
-		toolbarView.extendTemplate( {
-			attributes: {
-				// https://github.com/ckeditor/ckeditor5-editor-inline/issues/11
-				class: [ 'ck-toolbar_floating' ]
-			}
+			shouldGroupWhenFull,
+			isFloating: true
 		} );
 
 		// When toolbar lost focus then panel should hide.

packages/ckeditor5-ui/src/toolbar/toolbarlinebreakview.js

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module ui/toolbar/toolbarlinebreakview
+ */
+
+import View from '../view';
+
+/**
+ * The toolbar line break view class.
+ *
+ * @extends module:ui/view~View
+ */
+export default class ToolbarLineBreakView extends View {
+	/**
+	 * @inheritDoc
+	 */
+	constructor( locale ) {
+		super( locale );
+
+		this.setTemplate( {
+			tag: 'span',
+			attributes: {
+				class: [
+					'ck',
+					'ck-toolbar__line-break'
+				]
+			}
+		} );
+	}
+}