Merge pull request #12506 from ckeditor/ck/12490-nested-toolbars

Feature (ui): Allowed grouping toolbar items into drop-downs by using a declarative config. Closes #12490. BREAKING CHANGE (basic-styles): The bold icon has been moved to the ckeditor5-core package. BREAKING CHANGE (paragraph): The paragraph icon has been moved to the ckeditor5-core package.
ckeditor · Sep 27, 2022 · a0f92cb · a0f92cb
2 parents 10448f6 + 647485e
commit a0f92cb
Show file tree

Hide file tree

Showing 31 changed files with 913 additions and 31 deletions.
diff --git a/docs/_snippets/features/toolbar-nested-icon.html b/docs/_snippets/features/toolbar-nested-icon.html
@@ -0,0 +1,5 @@
+<div id="toolbar-nested-icon">
+	<p>
+		The <a href="https://en.wikipedia.org/wiki/Mars">Red Planet</a> is a target that has been aimed at for decades. Both Soviet (later Russian) and American designers looked at the sky and planned. Valeri Polyakov spent almost <strong>438 days</strong> during a single long-term mission onboard the <i>Mir</i> space station to test the ability of humans to thrive in space for long periods of time. It was twenty years ago.
+	</p>
+</div>
diff --git a/docs/_snippets/features/toolbar-nested-icon.js b/docs/_snippets/features/toolbar-nested-icon.js
@@ -0,0 +1,51 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#toolbar-nested-icon' ), {
+		toolbar: [
+			{
+				label: 'Default icon',
+				items: [ 'bold', 'italic' ]
+			},
+			{
+				label: 'Icon disabled',
+				icon: false,
+				items: [ 'bold', 'italic' ]
+			},
+			{
+				label: 'Insert',
+				icon: 'plus',
+				items: [ 'uploadImage', 'insertTable' ]
+			},
+			{
+				label: 'A drop-down with a custom icon',
+				// eslint-disable-next-line max-len
+				icon: '<svg viewBox="0 0 68 64" xmlns="http://www.w3.org/2000/svg"><g fill="none" fill-rule="evenodd"><path d="M43.71 11.025a11.508 11.508 0 0 0-1.213 5.159c0 6.42 5.244 11.625 11.713 11.625.083 0 .167 0 .25-.002v16.282a5.464 5.464 0 0 1-2.756 4.739L30.986 60.7a5.548 5.548 0 0 1-5.512 0L4.756 48.828A5.464 5.464 0 0 1 2 44.089V20.344c0-1.955 1.05-3.76 2.756-4.738L25.474 3.733a5.548 5.548 0 0 1 5.512 0l12.724 7.292z" fill="#FFF"/><path d="M45.684 8.79a12.604 12.604 0 0 0-1.329 5.65c0 7.032 5.744 12.733 12.829 12.733.091 0 .183-.001.274-.003v17.834a5.987 5.987 0 0 1-3.019 5.19L31.747 63.196a6.076 6.076 0 0 1-6.037 0L3.02 50.193A5.984 5.984 0 0 1 0 45.003V18.997c0-2.14 1.15-4.119 3.019-5.19L25.71.804a6.076 6.076 0 0 1 6.037 0L45.684 8.79zm-29.44 11.89c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h18.479c.833 0 1.509-.67 1.509-1.498v-.715c0-.827-.676-1.498-1.51-1.498H16.244zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm41.191-14.459c-5.835 0-10.565-4.695-10.565-10.486 0-5.792 4.73-10.487 10.565-10.487C63.27 3.703 68 8.398 68 14.19c0 5.791-4.73 10.486-10.565 10.486v-.001z" fill="#1EBC61" fill-rule="nonzero"/><path d="M60.857 15.995c0-.467-.084-.875-.251-1.225a2.547 2.547 0 0 0-.686-.88 2.888 2.888 0 0 0-1.026-.531 4.418 4.418 0 0 0-1.259-.175c-.134 0-.283.006-.447.018-.15.01-.3.034-.446.07l.075-1.4h3.587v-1.8h-5.462l-.214 5.06c.319-.116.682-.21 1.089-.28.406-.071.77-.107 1.088-.107.218 0 .437.021.655.063.218.041.413.114.585.218s.313.244.422.419c.109.175.163.391.163.65 0 .424-.132.745-.396.961a1.434 1.434 0 0 1-.938.325c-.352 0-.656-.1-.912-.3-.256-.2-.43-.453-.523-.762l-1.925.588c.1.35.258.664.472.943.214.279.47.514.767.706.298.191.63.339.995.443.365.104.749.156 1.151.156.437 0 .86-.064 1.272-.193.41-.13.778-.323 1.1-.581a2.8 2.8 0 0 0 .775-.981c.193-.396.29-.864.29-1.405h-.001z" fill="#FFF" fill-rule="nonzero"/></g></svg>',
+				items: [ 'bold', 'italic' ]
+			},
+			'|',
+			'undo', 'redo'
+		],
+		image: {
+			toolbar: [ 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side', '|', 'toggleImageCaption', 'imageTextAlternative' ]
+		},
+		cloudServices: CS_CONFIG,
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/_snippets/features/toolbar-nested-label.html b/docs/_snippets/features/toolbar-nested-label.html
@@ -0,0 +1,5 @@
+<div id="toolbar-nested-label">
+	<p>
+		The <a href="https://en.wikipedia.org/wiki/Mars">Red Planet</a> is a target that has been aimed at for decades. Both Soviet (later Russian) and American designers looked at the sky and planned. Valeri Polyakov spent almost <strong>438 days</strong> during a single long-term mission onboard the <i>Mir</i> space station to test the ability of humans to thrive in space for long periods of time. It was twenty years ago.
+	</p>
+</div>
diff --git a/docs/_snippets/features/toolbar-nested-label.js b/docs/_snippets/features/toolbar-nested-label.js
@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#toolbar-nested-label' ), {
+		toolbar: [
+			{
+				label: 'Basic styles',
+				withText: true,
+				items: [ 'bold', 'italic' ]
+			},
+			'|',
+			'undo', 'redo'
+		],
+		cloudServices: CS_CONFIG,
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/_snippets/features/toolbar-nested-simple.html b/docs/_snippets/features/toolbar-nested-simple.html
@@ -0,0 +1,5 @@
+<div id="toolbar-nested-simple">
+	<p>
+		The <a href="https://en.wikipedia.org/wiki/Mars">Red Planet</a> is a target that has been aimed at for decades. Both Soviet (later Russian) and American designers looked at the sky and planned. Valeri Polyakov spent almost <strong>438 days</strong> during a single long-term mission onboard the <i>Mir</i> space station to test the ability of humans to thrive in space for long periods of time. It was twenty years ago.
+	</p>
+</div>
diff --git a/docs/_snippets/features/toolbar-nested-simple.js b/docs/_snippets/features/toolbar-nested-simple.js
@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#toolbar-nested-simple' ), {
+		toolbar: [
+			{
+				label: 'Basic styles',
+				icon: 'text',
+				items: [ 'bold', 'italic' ]
+			},
+			'|',
+			'undo', 'redo'
+		],
+		cloudServices: CS_CONFIG,
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/_snippets/features/toolbar-nested-tooltip.html b/docs/_snippets/features/toolbar-nested-tooltip.html
@@ -0,0 +1,5 @@
+<div id="toolbar-nested-tooltip">
+	<p>
+		The <a href="https://en.wikipedia.org/wiki/Mars">Red Planet</a> is a target that has been aimed at for decades. Both Soviet (later Russian) and American designers looked at the sky and planned. Valeri Polyakov spent almost <strong>438 days</strong> during a single long-term mission onboard the <i>Mir</i> space station to test the ability of humans to thrive in space for long periods of time. It was twenty years ago.
+	</p>
+</div>
diff --git a/docs/_snippets/features/toolbar-nested-tooltip.js b/docs/_snippets/features/toolbar-nested-tooltip.js
@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#toolbar-nested-tooltip' ), {
+		toolbar: [
+			{
+				label: 'Others',
+				tooltip: 'Additional editing features',
+				items: [ 'bold', 'italic' ]
+			},
+			'|',
+			'undo', 'redo'
+		],
+		cloudServices: CS_CONFIG,
+		ui: {
+			viewportOffset: {
+				top: window.getViewportTopOffsetConfig()
+			}
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
diff --git a/docs/features/toolbar.md b/docs/features/toolbar.md
@@ -78,6 +78,118 @@ The demo below presents the "regular" toolbar look with `shouldNotGroupWhenFull`
 
 {@snippet features/toolbar-grouping}
 
+## Grouping toolbar items in drop-downs (nested toolbars)
+
+To save space in your toolbar or arrange the features thematically, you can group several items into a dropdown. For instance, check out the following configuration:
+
+```js
+toolbar: [
+	{
+		label: 'Basic styles',
+		icon: 'text',
+		items: [ 'bold', 'italic' ]
+	},
+	'|',
+	'undo', 'redo'
+]
+```
+
+It will create a "Basic styles" dropdown with a "text" icon containing the "bold" and "italic" buttons. You can test it in the demo below.
+
+{@snippet features/toolbar-nested-simple}
+
+### Customization
+
+You can customize the look of the dropdown by configuring additional properties, such as the icon, label or tooltip text.
+
+#### Displaying the label
+
+You can control the way the UI element is displayed. For instance, to hide the icon and to display the label only, you can use the following configuration:
+
+```js
+{
+	label: 'Basic styles',
+	// Show the textual label of the dropdown. Note that the "icon" property is not configured.
+	withText: true,
+	items: [ 'bold', 'italic' ]
+}
+```
+
+**Note**: The label will automatically show up if the `icon` is `false` ([learn more](#changing-the-icon)).
+
+{@snippet features/toolbar-nested-label}
+
+#### Changing the icon
+
+You can use one of the icons listed below for your dropdown:
+
+| Icon name         | Preview                                                                     |
+|-------------------|-----------------------------------------------------------------------------|
+| `'threeVerticalDots'` **(default)** | {@icon @ckeditor/ckeditor5-core/theme/icons/three-vertical-dots.svg Three vertical dots} |
+| `'alignLeft'`     | {@icon @ckeditor/ckeditor5-core/theme/icons/align-left.svg Align left}      |
+| `'bold'`          | {@icon @ckeditor/ckeditor5-core/theme/icons/bold.svg Bold}                  |
+| `'importExport'`  | {@icon @ckeditor/ckeditor5-core/theme/icons/importexport.svg Import export} |
+| `'paragraph'`     | {@icon @ckeditor/ckeditor5-core/theme/icons/paragraph.svg Paragraph}        |
+| `'text'`          | {@icon @ckeditor/ckeditor5-core/theme/icons/text.svg Text}                  |
+
+* If no icon is specified, `'threeVerticalDots'` will be used as a default.
+* If `icon: false` is configured, no icon will be displayed and the text label will show up instead.
+* You can set a custom icon for the drop-down by passing an SVG string.
+
+Here is an example:
+
+```js
+toolbar: [
+	{
+		// Using a default icon because none was specified.
+		label: 'Default icon',
+		items: [ 'bold', 'italic' ]
+	},
+	{
+		label: 'Icon disabled',
+		// This drop-down has the icon disabled and a text label instead.
+		icon: false,
+		items: [ 'bold', 'italic' ]
+	},
+	{
+		label: 'Insert',
+		// A "plus" sign icon works best for content insertion tools.
+		icon: 'plus',
+		items: [ 'bold', 'italic' ]
+	},
+	{
+		label: 'A dropdown with a custom icon',
+		// If you want your icon to change the color dynamically (e.g. when the dropdown opens), avoid fill="..."
+		// and stroke="..." styling attributes. Use solid shapes and avoid paths with strokes.
+		icon: '<svg viewBox="0 0 68 64" xmlns="http://www.w3.org/2000/svg"><g fill="none" fill-rule="evenodd"><path d="M43.71 11.025a11.508 11.508 0 0 0-1.213 5.159c0 6.42 5.244 11.625 11.713 11.625.083 0 .167 0 .25-.002v16.282a5.464 5.464 0 0 1-2.756 4.739L30.986 60.7a5.548 5.548 0 0 1-5.512 0L4.756 48.828A5.464 5.464 0 0 1 2 44.089V20.344c0-1.955 1.05-3.76 2.756-4.738L25.474 3.733a5.548 5.548 0 0 1 5.512 0l12.724 7.292z" fill="#FFF"/><path d="M45.684 8.79a12.604 12.604 0 0 0-1.329 5.65c0 7.032 5.744 12.733 12.829 12.733.091 0 .183-.001.274-.003v17.834a5.987 5.987 0 0 1-3.019 5.19L31.747 63.196a6.076 6.076 0 0 1-6.037 0L3.02 50.193A5.984 5.984 0 0 1 0 45.003V18.997c0-2.14 1.15-4.119 3.019-5.19L25.71.804a6.076 6.076 0 0 1 6.037 0L45.684 8.79zm-29.44 11.89c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h18.479c.833 0 1.509-.67 1.509-1.498v-.715c0-.827-.676-1.498-1.51-1.498H16.244zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm41.191-14.459c-5.835 0-10.565-4.695-10.565-10.486 0-5.792 4.73-10.487 10.565-10.487C63.27 3.703 68 8.398 68 14.19c0 5.791-4.73 10.486-10.565 10.486v-.001z" fill="#1EBC61" fill-rule="nonzero"/><path d="M60.857 15.995c0-.467-.084-.875-.251-1.225a2.547 2.547 0 0 0-.686-.88 2.888 2.888 0 0 0-1.026-.531 4.418 4.418 0 0 0-1.259-.175c-.134 0-.283.006-.447.018-.15.01-.3.034-.446.07l.075-1.4h3.587v-1.8h-5.462l-.214 5.06c.319-.116.682-.21 1.089-.28.406-.071.77-.107 1.088-.107.218 0 .437.021.655.063.218.041.413.114.585.218s.313.244.422.419c.109.175.163.391.163.65 0 .424-.132.745-.396.961a1.434 1.434 0 0 1-.938.325c-.352 0-.656-.1-.912-.3-.256-.2-.43-.453-.523-.762l-1.925.588c.1.35.258.664.472.943.214.279.47.514.767.706.298.191.63.339.995.443.365.104.749.156 1.151.156.437 0 .86-.064 1.272-.193.41-.13.778-.323 1.1-.581a2.8 2.8 0 0 0 .775-.981c.193-.396.29-.864.29-1.405h-.001z" fill="#FFF" fill-rule="nonzero"/></g></svg>',
+		items: [ 'bold', 'italic' ]
+	},
+	'|',
+	'undo', 'redo'
+]
+```
+And here is the effect:
+
+{@snippet features/toolbar-nested-icon}
+
+#### Customizing the tooltip
+
+By default, the tooltip of the button shares its text with the label. You can customize it to better describe your dropdown and make it more accessible by using the `tooltip` property ({@link module:ui/button/buttonview~ButtonView#tooltip learn more}):
+
+```js
+toolbar: [
+	{
+		label: 'Others',
+		tooltip: 'Additional editing features',
+		items: [ 'bold', 'italic' ]
+	},
+	'|',
+	'undo', 'redo'
+]
+```
+
+{@snippet features/toolbar-nested-tooltip}
+
 ## Multiline (wrapping) toolbar
 
 In the [extended toolbar configuration format](#extended-toolbar-configuration-format) it is also possible to arrange toolbar items into multiple lines. Here is how to achieve this:

diff --git a/packages/ckeditor5-basic-styles/ckeditor5-metadata.json b/packages/ckeditor5-basic-styles/ckeditor5-metadata.json
@@ -10,7 +10,7 @@
 				{
 					"type": "Button",
 					"name": "bold",
-					"iconPath": "theme/icons/bold.svg"
+					"iconPath": "@ckeditor/ckeditor5-core/theme/icons/bold.svg"
 				}
 			],
 			"htmlOutput": [

diff --git a/packages/ckeditor5-basic-styles/docs/features/basic-styles.md b/packages/ckeditor5-basic-styles/docs/features/basic-styles.md
@@ -12,7 +12,7 @@ The basic styles feature allows you to apply the most frequently used formatting
 </info-box>
 
 Basic formatting options may be applied with the toolbar buttons (pictured below) or thanks to the {@link features/autoformat autoformatting feature} with Markdown code as you type. Use one these to format the text:
-* Bold &ndash; Use the bold toolbar button {@icon @ckeditor/ckeditor5-basic-styles/theme/icons/bold.svg Bold} or type `**text**` or `__text__`
+* Bold &ndash; Use the bold toolbar button {@icon @ckeditor/ckeditor5-core/theme/icons/bold.svg Bold} or type `**text**` or `__text__`
 * Italic &ndash; Use the italic toolbar button {@icon @ckeditor/ckeditor5-basic-styles/theme/icons/italic.svg Italic} or type `*text*` or `_text_`
 * Code &ndash; Use the code toolbar button {@icon @ckeditor/ckeditor5-basic-styles/theme/icons/code.svg Code} or type ``` `text` ```
 * Strikethrough &ndash; Use the strikethrough toolbar button {@icon @ckeditor/ckeditor5-basic-styles/theme/icons/strikethrough.svg Strikethrough} or type `~~text~~`.

diff --git a/packages/ckeditor5-basic-styles/src/bold/boldui.js b/packages/ckeditor5-basic-styles/src/bold/boldui.js
@@ -7,11 +7,9 @@
  * @module basic-styles/bold/boldui
  */
 
-import { Plugin } from 'ckeditor5/src/core';
+import { Plugin, icons } from 'ckeditor5/src/core';
 import { ButtonView } from 'ckeditor5/src/ui';
 
-import boldIcon from '../../theme/icons/bold.svg';
-
 const BOLD = 'bold';
 
 /**
@@ -41,7 +39,7 @@ export default class BoldUI extends Plugin {
 
 			view.set( {
 				label: t( 'Bold' ),
-				icon: boldIcon,
+				icon: icons.bold,
 				keystroke: 'CTRL+B',
 				tooltip: true,
 				isToggleable: true