DOC-3131: New subtoolbar support for context toolbars. (#3664)

Author: kemister85

modules/ROOT/pages/7.8.0-release-notes.adoc

@@ -224,6 +224,47 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 // CCFR here.
 
+=== New subtoolbar support for context toolbars.
+// #TINY-11748
+
+{productname} {release-version} introduces support for multi-level context toolbars, enabling more advanced and interactive editing experiences directly within the editor interface. Previously, developers had to manually configure separate toolbars and manage transitions between them using predicate logic. This release simplifies that process by adding a new API for defining and navigating subtoolbars, similar to the existing context form functionality.
+
+A new `+navigateback+` button streamlines navigation between toolbar levels, while improved focus management ensures input fields are automatically focused when switching toolbars. These enhancements provide a more flexible, intuitive, and responsive workflow for both developers and end users.
+
+.Example of a multi-level context toolbar configuration:
+[source, js]
+----
+tinymce.init({
+  selector: 'textarea',
+  height: 350,
+  setup: (editor) => {
+    editor.ui.registry.addContextToolbar('bar', {
+      predicate: () => true,
+      items: 'bold italic | undo redo | subbar1',
+      position: 'line',
+      scope: 'editor'
+    });
+
+    editor.ui.registry.addContextToolbar('subbar1', {
+      launch: { text: 'Subbar 1' },
+      items: 'navigateback bold italic | undo redo | subbar2'
+    });
+
+    editor.ui.registry.addContextToolbar('subbar2', {
+      launch: { text: 'Subbar 2' },
+      items: 'navigateback bold italic | undo redo | subbar3'
+    });
+
+    editor.ui.registry.addContextToolbar('subbar3', {
+      launch: { text: 'Subbar 3' },
+      items: 'navigateback bold italic | undo redo'
+    });
+  }
+});
+----
+
+For more information on context toolbars, see xref:contexttoolbar.adoc[Context toolbars].
+
 === The `+editor.selection.scrollIntoView()+` method now pads the target scroll area with a small margin, ensuring content doesn't sit at the very edge of the viewport.
 // #TINY-11786
 

modules/ROOT/pages/contexttoolbar.adoc

@@ -60,6 +60,34 @@ items: [
 ]
 ----
 
+[NOTE]
+For editors using 7.8.0+, context toolbars also support the `+navigateback+` button for multi-level toolbar navigation. This built-in button allows returning to the previous context toolbar when using nested toolbars.
+
+.Example of a multi-level context toolbar configuration:
+[source, js]
+----
+tinymce.init({
+  selector: 'textarea',
+  setup: (editor) => {
+    // Register the main context toolbar named 'bar'
+    editor.ui.registry.addContextToolbar('bar', {
+      predicate: () => true, // Always show the toolbar when triggered
+      items: 'bold italic | undo redo | subbar1', // Toolbar buttons and nested toolbar trigger
+      position: 'line',
+      scope: 'editor'
+    });
+
+    // Register a nested context toolbar named 'subbar1'
+    editor.ui.registry.addContextToolbar('subbar1', {
+      launch: { text: 'Subbar 1' }, // Button label that appears in the parent toolbar
+      items: 'navigateback bold italic | undo redo | subbar2' 
+      // 'navigateback' allows users to return to the previous toolbar
+      // 'subbar2' is another nested toolbar (can be defined similarly)
+    });
+  }
+});
+----
+
 liveDemo::context-toolbar-labels[height="600", tab="js"]
 
 == Launching a context toolbar programmatically

modules/ROOT/partials/toolbar-button-ids/core-toolbar-buttons.adoc

@@ -30,6 +30,7 @@ The `+fontsize+` and `+fontsizeinput+` toolbar buttons should not be placed in a
 |`+italic+` |Applies the italic format to the current selection.
 |`+language+` |Dropdown list with languages to apply to the selection. This button requires the xref:content-localization.adoc#content_langs[`+content_langs+` option].
 |`+lineheight+` |Dropdown list with line heights to apply to selection.
+|`+navigateback+` | Allows navigation between subtoolbar levels for multi-level toolbar configurations.
 |`+newdocument+` |Creates a new document.
 |`+outdent+` |Outdents the current list item or block element.
 |`+paste+` |Pastes the current clipboard into the editor.