From 60c1945b804f47dafcce53328b41cbf12bbffc98 Mon Sep 17 00:00:00 2001
From: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com>
Date: Mon, 24 Mar 2025 20:13:24 +1000
Subject: [PATCH] DOC-3131: New subtoolbar support for context toolbars.

---
 modules/ROOT/pages/7.8.0-release-notes.adoc   | 41 +++++++++++++++++++
 modules/ROOT/pages/contexttoolbar.adoc        | 28 +++++++++++++
 .../core-toolbar-buttons.adoc                 |  1 +
 3 files changed, 70 insertions(+)

diff --git a/modules/ROOT/pages/7.8.0-release-notes.adoc b/modules/ROOT/pages/7.8.0-release-notes.adoc
index dff76301c5..8c9d4fcfe2 100644
--- a/modules/ROOT/pages/7.8.0-release-notes.adoc
+++ b/modules/ROOT/pages/7.8.0-release-notes.adoc
@@ -114,6 +114,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].
+
 
 [[additions]]
 == Additions
diff --git a/modules/ROOT/pages/contexttoolbar.adoc b/modules/ROOT/pages/contexttoolbar.adoc
index 8fb96d06e2..11a788416d 100644
--- a/modules/ROOT/pages/contexttoolbar.adoc
+++ b/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
diff --git a/modules/ROOT/partials/toolbar-button-ids/core-toolbar-buttons.adoc b/modules/ROOT/partials/toolbar-button-ids/core-toolbar-buttons.adoc
index c239685d09..f56e173f33 100644
--- a/modules/ROOT/partials/toolbar-button-ids/core-toolbar-buttons.adoc
+++ b/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.