Merge pull request #12064 from ckeditor/ck/10368-source-editing-focus…

…-toolbar-v2

Feature (core): Enabled toolbar focusing and navigation across various editor implementations and features. Closes #10368. Closes #5146. Closes #9906. Closes #10025.

BREAKING CHANGE (ui): The `enableToolbarKeyboardFocus()` helper has been removed. Please use the [`EditorUI#addToolbar()`](https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editorui-EditorUI.html#function-addToolbar) method instead to enable accessible toolbar navigation (and focusing) using `Alt+F10` and `Esc` keystrokes (see #10368).

docs/_snippets/examples/multi-root-editor.js

@@ -12,7 +12,6 @@ import getDataFromElement from '@ckeditor/ckeditor5-utils/src/dom/getdatafromele
 import setDataInElement from '@ckeditor/ckeditor5-utils/src/dom/setdatainelement';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import EditorUI from '@ckeditor/ckeditor5-core/src/editor/editorui';
-import enableToolbarKeyboardFocus from '@ckeditor/ckeditor5-ui/src/toolbar/enabletoolbarkeyboardfocus';
 import { enablePlaceholder } from '@ckeditor/ckeditor5-engine/src/view/placeholder';
 import EditorUIView from '@ckeditor/ckeditor5-ui/src/editorui/editoruiview';
 import InlineEditableUIView from '@ckeditor/ckeditor5-ui/src/editableui/inline/inlineeditableuiview';
@@ -205,11 +204,6 @@ class MultirootEditorUI extends EditorUI {
 			// editable areas (roots) but the decoupled editor has only one.
 			this.setEditableElement( editable.name, editableElement );
 
-			// Let the global focus tracker know that the editable UI element is focusable and
-			// belongs to the editor. From now on, the focus tracker will sustain the editor focus
-			// as long as the editable is focused (e.g. the user is typing).
-			this.focusTracker.add( editableElement );
-
 			// Let the editable UI element respond to the changes in the global editor focus
 			// tracker. It has been added to the same tracker a few lines above but, in reality, there are
 			// many focusable areas in the editor, like balloons, toolbars or dropdowns and as long
@@ -279,12 +273,8 @@ class MultirootEditorUI extends EditorUI {
 
 		toolbar.fillFromConfig( editor.config.get( 'toolbar' ), this.componentFactory );
 
-		enableToolbarKeyboardFocus( {
-			origin: editor.editing.view,
-			originFocusTracker: this.focusTracker,
-			originKeystrokeHandler: editor.keystrokes,
-			toolbar
-		} );
+		// Register the toolbar so it becomes available for Alt+F10 and Esc navigation.
+		this.addToolbar( view.toolbar );
 	}
 
 	/**

docs/examples/framework/multi-root-editor.md

@@ -28,7 +28,6 @@ import getDataFromElement from '@ckeditor/ckeditor5-utils/src/dom/getdatafromele
 import setDataInElement from '@ckeditor/ckeditor5-utils/src/dom/setdatainelement';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import EditorUI from '@ckeditor/ckeditor5-core/src/editor/editorui';
-import enableToolbarKeyboardFocus from '@ckeditor/ckeditor5-ui/src/toolbar/enabletoolbarkeyboardfocus';
 import { enablePlaceholder } from '@ckeditor/ckeditor5-engine/src/view/placeholder';
 import EditorUIView from '@ckeditor/ckeditor5-ui/src/editorui/editoruiview';
 import InlineEditableUIView from '@ckeditor/ckeditor5-ui/src/editableui/inline/inlineeditableuiview';
@@ -220,11 +219,6 @@ class MultirootEditorUI extends EditorUI {
 			// editable areas (roots) but the decoupled editor has only one.
 			this.setEditableElement( editable.name, editableElement );
 
-			// Let the global focus tracker know that the editable UI element is focusable and
-			// belongs to the editor. From now on, the focus tracker will sustain the editor focus
-			// as long as the editable is focused (e.g. the user is typing).
-			this.focusTracker.add( editableElement );
-
 			// Let the editable UI element respond to the changes in the global editor focus
 			// tracker. It has been added to the same tracker a few lines above but, in reality, there are
 			// many focusable areas in the editor, like balloons, toolbars or dropdowns and as long
@@ -294,12 +288,8 @@ class MultirootEditorUI extends EditorUI {
 
 		toolbar.fillFromConfig( editor.config.get( 'toolbar' ), this.componentFactory );
 
-		enableToolbarKeyboardFocus( {
-			origin: editor.editing.view,
-			originFocusTracker: this.focusTracker,
-			originKeystrokeHandler: editor.keystrokes,
-			toolbar
-		} );
+		// Register the toolbar so it becomes available for Alt+F10 and Esc navigation.
+		this.addToolbar( view.toolbar );
 	}
 
 	/**

docs/framework/guides/custom-editor-creator.md

@@ -124,7 +124,6 @@ The `*EditorUI` class is the main UI class which initializes UI components (the
 
 ```js
 import EditorUI from '@ckeditor/ckeditor5-core/src/editor/editorui';
-import enableToolbarKeyboardFocus from '@ckeditor/ckeditor5-ui/src/toolbar/enabletoolbarkeyboardfocus';
 import { enablePlaceholder } from '@ckeditor/ckeditor5-engine/src/view/placeholder';
 
 /**
@@ -194,11 +193,6 @@ class MultirootEditorUI extends EditorUI {
 			// Register each editable UI view in the editor.
 			this.setEditableElement( editable.name, editableElement );
 
-			// Let the global focus tracker know that the editable UI element is focusable and
-			// belongs to the editor. From now on, the focus tracker will sustain the editor focus
-			// as long as the editable is focused (e.g. the user is typing).
-			this.focusTracker.add( editableElement );
-
 			// Let the editable UI element respond to the changes in the global editor focus
 			// tracker. It has been added to the same tracker a few lines above but, in reality, there are
 			// many focusable areas in the editor, like balloons, toolbars or dropdowns and as long
@@ -268,12 +262,8 @@ class MultirootEditorUI extends EditorUI {
 
 		toolbar.fillFromConfig( editor.config.get( 'toolbar' ), this.componentFactory );
 
-		enableToolbarKeyboardFocus( {
-			origin: editor.editing.view,
-			originFocusTracker: this.focusTracker,
-			originKeystrokeHandler: editor.keystrokes,
-			toolbar
-		} );
+		// Register the toolbar so it becomes available for Alt+F10 and Esc navigation.
+		this.addToolbar( view.toolbar );
 	}
 
 	/**

docs/updating/migration-to-35.md

@@ -5,7 +5,76 @@ order: 89
 modified_at: 2022-07-18
 ---
 
-# Migration to CKEditor 5 v35.0.0
+# Migration to CKEditor 5 v35.x
+
+## Migration to CKEditor 5 v35.1.0
+
+### Changes to API providing the accessible navigation between editing roots and toolbars on <kbd>Alt</kbd>+<kbd>F10</kbd> and <kbd>Esc</kbd> keystrokes
+
+<info-box>
+	This information applies only to integrators who develop their own {@link framework/guides/custom-editor-creator editor creators} from scratch by using {@link module:core/editor/editor~Editor} and {@link module:core/editor/editorui~EditorUI} classes as building blocks.
+</info-box>
+
+* The `enableToolbarKeyboardFocus()` helper that allowed the navigation has been removed. To bring the functionality back, use the {@link module:core/editor/editorui~EditorUI#addToolbar} method instead.
+* Also, please note that editable elements are now automatically added to the {@link module:core/editor/editorui~EditorUI#focusTracker main focus tracker} and should not be added individually.
+
+**Before**:
+```js
+import { EditorUI } from 'ckeditor5/src/core';
+
+export default class MyEditorUI extends EditorUI {
+	// ...
+
+	init() {
+		const view = this.view;
+		const editableElement = view.editable.element;
+		const toolbarViewInstance = this.view.toolbar;
+
+		// ...
+
+		this.setEditableElement( 'editableName', editableElement );
+
+		this.focusTracker.add( editableElement );
+
+		enableToolbarKeyboardFocus( {
+			// ...
+
+			toolbar: toolbarViewInstance
+		} );
+
+		// ...
+	}
+}
+```
+
+**After**:
+```js
+import { EditorUI } from 'ckeditor5/src/core';
+
+export default class MyEditorUI extends EditorUI {
+	// ...
+
+	init() {
+		const view = this.view;
+		const editableElement = view.editable.element;
+		const toolbarViewInstance = this.view.toolbar;
+
+		// ...
+
+		// Note: You should not add the editable element to the focus tracker here.
+		// This is handled internally by EditorUI#setEditableElement() method.
+		this.setEditableElement( 'editableName', editableElement );
+
+		// Note: Add the toolbar to enable Alt+F10 navigation.
+		// The rest (e.g. Esc key handling) is handled by EditorUI#setEditableElement() method.
+		this.addToolbar( toolbarViewInstance );
+
+		// ...
+	}
+}
+```
+
+## Migration to CKEditor 5 v35.0.0
 
 <info-box>
 	When updating your CKEditor 5 installation, make sure **all the packages are the same version** to avoid errors.
@@ -17,9 +86,9 @@ For the entire list of changes introduced in version 35.0.0, see the [changelog
 
 Listed below are the most important changes that require your attention when upgrading to CKEditor 5 v35.0.0.
 
-## Important changes
+### Important changes
 
-### The source element is not updated automatically after the editor destroy
+#### The source element is not updated automatically after the editor destroy
 
 The last version of CKEditor 5 changes the default behavior of the source element after the editor is destroyed (when `editor.destroy()` is called). So far, the source element was updated with the output coming from `editor.getData()`. Now, the source element becomes empty after the editor is destroyed and it is not updated anymore.
 
@@ -36,7 +105,7 @@ ClassicEditor.create( sourceElement, {
 	Enabling the `updateSourceElementOnDestroy` option in your configuration, depending on the plugins you use, might have some security implications. While the editing view is secured, there might be some unsafe content in the data output, so enable this option only if you know what you are doing. Be especially careful when using Markdown, General HTML Support and HTML embed features.
 </info-box>
 
-### Dropdown focus is moved back to the dropdown button after choosing an option
+#### Dropdown focus is moved back to the dropdown button after choosing an option
 
 Due to the ongoing accessibility improvements the default behavior of the {@link module:ui/dropdown/dropdownview~DropdownView dropdown UI component} has been changed. From now on, by default, after choosing an option from a dropdown (either by mouse or keyboard), the focus will be automatically moved to the dropdown button.
 
@@ -64,15 +133,15 @@ dropdownView.on( 'execute', () => {
 } );
 ```
 
-### There is now a TypeScript code on GitHub (and how it affects your build)
+#### There is now a TypeScript code on GitHub (and how it affects your build)
 
 Starting from v35.0.0, the first of CKEditor 5 packages (namely: `@ckeditor/ckeditor5-utils`) is developed in TypeScript. This is the first step of [our migration to TypeScript](https://github.com/ckeditor/ckeditor5/issues/11704).
 
-#### Whom does it affect?
+##### Whom does it affect?
 
 It affects you **only if** you use the [source code directly from git repository (GitHub)](https://github.com/ckeditor/ckeditor5). If you use it via any other channel (npm, CDN, ZIP, etc.) this change is completely transparent for you as we publish only JavaScript code there.
 
-#### How does it affect you?
+##### How does it affect you?
 
 For instance, if you happen to have a custom CKEditor 5 build that, for some reason, installs its dependencies from the git repository, you will need to update your webpack config to support the TypeScript code.