feat: Make toolbox and flyout focusable (#8920)

## The basics

- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)

## The details
### Resolves

Fixes #8918
Fixes #8919
Fixes part of #8771

### Proposed Changes

This updates several classes in order to make toolboxes and flyouts focusable:
- `IFlyout` is now an `IFocusableTree` with corresponding implementations in `FlyoutBase`.
- `IToolbox` is now an `IFocusableTree` with corresponding implementations in `Toolbox`.
- `IToolboxItem` is now an `IFocusableNode` with corresponding implementations in `ToolboxItem`.
- As the primary toolbox items, `ToolboxCategory` and `ToolboxSeparator` were updated to have -1 tab indexes and defined IDs to help `ToolboxItem` fulfill its contracted for `IFocusableNode.getFocusableElement`.

Each of these two new focusable trees have specific noteworthy behaviors behaviors:
- `Toolbox` will automatically indicate that its first item should be focused (if one is present), even overriding the ability to focus the toolbox's root (however there are some cases where that can still happen).
- `Toolbox` will automatically synchronize its selection state with its item nodes being focused.
- `FlyoutBase`, now being a focusable tree, has had a tab index of 0 added. Normally a tab index of -1 is all that's needed, but the keyboard navigation plugin specifically uses 0 for flyout so that the flyout is tabbable. This is a **new** tab stop being introduced.
- `FlyoutBase` holds a workspace (for rendering blocks) and, since `WorkspaceSvg` is already set up to be a focusable tree, it's represented as a subtree to `FlyoutBase`. This does introduce some wonky behaviors: the flyout's root will have passive focus while its contents have active focus. This could be manually disabled with some CSS if it ends up being a confusing user experience.
- Both `FlyoutBase` and `WorkspaceSvg` have built-in behaviors for detecting when a user tries navigating away from an open flyout to ensure that the flyout is closed when it's supposed to be. That is, the flyout is auto-hideable and a non-flyout, non-toolbox node has then been focused. This matches parity with the `T`/`Esc` flows supported in the keyboard navigation plugin playground.

One other thing to note: `Toolbox` had a few tests to update that were trying to reinit a toolbox without first disposing of it (which was caught by one of `FocusManager`'s state guardrails).

### Reason for Changes

This is part of an ongoing effort to ensure key components of Blockly are focusable so that they can be keyboard-navigable (with other needed changes yet both in Core Blockly and the keyboard navigation plugin).

### Test Coverage

No new tests have been added. It's certainly possible to add unit tests for the focusable configurations being introduced in this PR, but it may not be highly beneficial. It's largely assumed that the individual implementations should work due to a highly tested FocusManager, and it may be the case that the interactions of the components working together is far more important to verify (that is, the end user flows). The latter is planned to be tackled as part of #8915.

### Documentation

No documentation changes should be needed here.

### Additional Information

This includes changes that have been pulled from #8875.

core/flyout_base.ts

@@ -21,9 +21,12 @@ import * as eventUtils from './events/utils.js';
 import {FlyoutItem} from './flyout_item.js';
 import {FlyoutMetricsManager} from './flyout_metrics_manager.js';
 import {FlyoutSeparator, SeparatorAxis} from './flyout_separator.js';
+import {getFocusManager} from './focus_manager.js';
 import {IAutoHideable} from './interfaces/i_autohideable.js';
 import type {IFlyout} from './interfaces/i_flyout.js';
 import type {IFlyoutInflater} from './interfaces/i_flyout_inflater.js';
+import {IFocusableNode} from './interfaces/i_focusable_node.js';
+import {IFocusableTree} from './interfaces/i_focusable_tree.js';
 import type {Options} from './options.js';
 import * as registry from './registry.js';
 import * as renderManagement from './render_management.js';
@@ -43,7 +46,7 @@ import {WorkspaceSvg} from './workspace_svg.js';
  */
 export abstract class Flyout
   extends DeleteArea
-  implements IAutoHideable, IFlyout
+  implements IAutoHideable, IFlyout, IFocusableNode
 {
   /**
    * Position the flyout.
@@ -303,6 +306,7 @@ export abstract class Flyout
     // hide/show code will set up proper visibility and size later.
     this.svgGroup_ = dom.createSvgElement(tagName, {
       'class': 'blocklyFlyout',
+      'tabindex': '0',
     });
     this.svgGroup_.style.display = 'none';
     this.svgBackground_ = dom.createSvgElement(
@@ -317,6 +321,9 @@ export abstract class Flyout
     this.workspace_
       .getThemeManager()
       .subscribe(this.svgBackground_, 'flyoutOpacity', 'fill-opacity');
+
+    getFocusManager().registerTree(this);
+
     return this.svgGroup_;
   }
 
@@ -398,6 +405,7 @@ export abstract class Flyout
     if (this.svgGroup_) {
       dom.removeNode(this.svgGroup_);
     }
+    getFocusManager().unregisterTree(this);
   }
 
   /**
@@ -961,4 +969,63 @@ export abstract class Flyout
 
     return null;
   }
+
+  /** See IFocusableNode.getFocusableElement. */
+  getFocusableElement(): HTMLElement | SVGElement {
+    if (!this.svgGroup_) throw new Error('Flyout DOM is not yet created.');
+    return this.svgGroup_;
+  }
+
+  /** See IFocusableNode.getFocusableTree. */
+  getFocusableTree(): IFocusableTree {
+    return this;
+  }
+
+  /** See IFocusableNode.onNodeFocus. */
+  onNodeFocus(): void {}
+
+  /** See IFocusableNode.onNodeBlur. */
+  onNodeBlur(): void {}
+
+  /** See IFocusableTree.getRootFocusableNode. */
+  getRootFocusableNode(): IFocusableNode {
+    return this;
+  }
+
+  /** See IFocusableTree.getRestoredFocusableNode. */
+  getRestoredFocusableNode(
+    _previousNode: IFocusableNode | null,
+  ): IFocusableNode | null {
+    return null;
+  }
+
+  /** See IFocusableTree.getNestedTrees. */
+  getNestedTrees(): Array<IFocusableTree> {
+    return [this.workspace_];
+  }
+
+  /** See IFocusableTree.lookUpFocusableNode. */
+  lookUpFocusableNode(_id: string): IFocusableNode | null {
+    // No focusable node needs to be returned since the flyout's subtree is a
+    // workspace that will manage its own focusable state.
+    return null;
+  }
+
+  /** See IFocusableTree.onTreeFocus. */
+  onTreeFocus(
+    _node: IFocusableNode,
+    _previousTree: IFocusableTree | null,
+  ): void {}
+
+  /** See IFocusableTree.onTreeBlur. */
+  onTreeBlur(nextTree: IFocusableTree | null): void {
+    const toolbox = this.targetWorkspace.getToolbox();
+    // If focus is moving to either the toolbox or the flyout's workspace, do
+    // not close the flyout. For anything else, do close it since the flyout is
+    // no longer focused.
+    if (toolbox && nextTree === toolbox) return;
+    if (nextTree == this.workspace_) return;
+    if (toolbox) toolbox.clearSelection();
+    this.autoHide(false);
+  }
 }

core/interfaces/i_flyout.ts

@@ -12,12 +12,13 @@ import type {Coordinate} from '../utils/coordinate.js';
 import type {Svg} from '../utils/svg.js';
 import type {FlyoutDefinition} from '../utils/toolbox.js';
 import type {WorkspaceSvg} from '../workspace_svg.js';
+import {IFocusableTree} from './i_focusable_tree.js';
 import type {IRegistrable} from './i_registrable.js';
 
 /**
  * Interface for a flyout.
  */
-export interface IFlyout extends IRegistrable {
+export interface IFlyout extends IRegistrable, IFocusableTree {
   /** Whether the flyout is laid out horizontally or not. */
   horizontalLayout: boolean;
 

core/interfaces/i_toolbox.ts

@@ -9,13 +9,14 @@
 import type {ToolboxInfo} from '../utils/toolbox.js';
 import type {WorkspaceSvg} from '../workspace_svg.js';
 import type {IFlyout} from './i_flyout.js';
+import type {IFocusableTree} from './i_focusable_tree.js';
 import type {IRegistrable} from './i_registrable.js';
 import type {IToolboxItem} from './i_toolbox_item.js';
 
 /**
  * Interface for a toolbox.
  */
-export interface IToolbox extends IRegistrable {
+export interface IToolbox extends IRegistrable, IFocusableTree {
   /** Initializes the toolbox. */
   init(): void;
 

core/interfaces/i_toolbox_item.ts

@@ -6,10 +6,12 @@
 
 // Former goog.module ID: Blockly.IToolboxItem
 
+import type {IFocusableNode} from './i_focusable_node.js';
+
 /**
  * Interface for an item in the toolbox.
  */
-export interface IToolboxItem {
+export interface IToolboxItem extends IFocusableNode {
   /**
    * Initializes the toolbox item.
    * This includes creating the DOM and updating the state of any items based

core/toolbox/category.ts

@@ -225,6 +225,8 @@ export class ToolboxCategory
    */
   protected createContainer_(): HTMLDivElement {
     const container = document.createElement('div');
+    container.tabIndex = -1;
+    container.id = this.getId();
     const className = this.cssConfig_['container'];
     if (className) {
       dom.addClass(container, className);

core/toolbox/separator.ts

@@ -54,6 +54,8 @@ export class ToolboxSeparator extends ToolboxItem {
    */
   protected createDom_(): HTMLDivElement {
     const container = document.createElement('div');
+    container.tabIndex = -1;
+    container.id = this.getId();
     const className = this.cssConfig_['container'];
     if (className) {
       dom.addClass(container, className);

core/toolbox/toolbox.ts

@@ -22,11 +22,14 @@ import {DeleteArea} from '../delete_area.js';
 import '../events/events_toolbox_item_select.js';
 import {EventType} from '../events/type.js';
 import * as eventUtils from '../events/utils.js';
+import {getFocusManager} from '../focus_manager.js';
 import type {IAutoHideable} from '../interfaces/i_autohideable.js';
 import type {ICollapsibleToolboxItem} from '../interfaces/i_collapsible_toolbox_item.js';
 import {isDeletable} from '../interfaces/i_deletable.js';
 import type {IDraggable} from '../interfaces/i_draggable.js';
 import type {IFlyout} from '../interfaces/i_flyout.js';
+import type {IFocusableNode} from '../interfaces/i_focusable_node.js';
+import type {IFocusableTree} from '../interfaces/i_focusable_tree.js';
 import type {IKeyboardAccessible} from '../interfaces/i_keyboard_accessible.js';
 import type {ISelectableToolboxItem} from '../interfaces/i_selectable_toolbox_item.js';
 import {isSelectableToolboxItem} from '../interfaces/i_selectable_toolbox_item.js';
@@ -51,7 +54,12 @@ import {CollapsibleToolboxCategory} from './collapsible_category.js';
  */
 export class Toolbox
   extends DeleteArea
-  implements IAutoHideable, IKeyboardAccessible, IStyleable, IToolbox
+  implements
+    IAutoHideable,
+    IKeyboardAccessible,
+    IStyleable,
+    IToolbox,
+    IFocusableNode
 {
   /**
    * The unique ID for this component that is used to register with the
@@ -163,6 +171,7 @@ export class Toolbox
         ComponentManager.Capability.DRAG_TARGET,
       ],
     });
+    getFocusManager().registerTree(this);
   }
 
   /**
@@ -177,7 +186,6 @@ export class Toolbox
     const container = this.createContainer_();
 
     this.contentsDiv_ = this.createContentsContainer_();
-    this.contentsDiv_.tabIndex = 0;
     aria.setRole(this.contentsDiv_, aria.Role.TREE);
     container.appendChild(this.contentsDiv_);
 
@@ -194,6 +202,7 @@ export class Toolbox
    */
   protected createContainer_(): HTMLDivElement {
     const toolboxContainer = document.createElement('div');
+    toolboxContainer.tabIndex = 0;
     toolboxContainer.setAttribute('layout', this.isHorizontal() ? 'h' : 'v');
     dom.addClass(toolboxContainer, 'blocklyToolbox');
     toolboxContainer.setAttribute('dir', this.RTL ? 'RTL' : 'LTR');
@@ -1077,7 +1086,71 @@ export class Toolbox
       this.workspace_.getThemeManager().unsubscribe(this.HtmlDiv);
       dom.removeNode(this.HtmlDiv);
     }
+
+    getFocusManager().unregisterTree(this);
   }
+
+  /** See IFocusableNode.getFocusableElement. */
+  getFocusableElement(): HTMLElement | SVGElement {
+    if (!this.HtmlDiv) throw Error('Toolbox DOM has not yet been created.');
+    return this.HtmlDiv;
+  }
+
+  /** See IFocusableNode.getFocusableTree. */
+  getFocusableTree(): IFocusableTree {
+    return this;
+  }
+
+  /** See IFocusableNode.onNodeFocus. */
+  onNodeFocus(): void {}
+
+  /** See IFocusableNode.onNodeBlur. */
+  onNodeBlur(): void {}
+
+  /** See IFocusableTree.getRootFocusableNode. */
+  getRootFocusableNode(): IFocusableNode {
+    return this;
+  }
+
+  /** See IFocusableTree.getRestoredFocusableNode. */
+  getRestoredFocusableNode(
+    previousNode: IFocusableNode | null,
+  ): IFocusableNode | null {
+    // Always try to select the first selectable toolbox item rather than the
+    // root of the toolbox.
+    if (!previousNode || previousNode === this) {
+      return this.getToolboxItems().find((item) => item.isSelectable()) ?? null;
+    }
+    return null;
+  }
+
+  /** See IFocusableTree.getNestedTrees. */
+  getNestedTrees(): Array<IFocusableTree> {
+    return [];
+  }
+
+  /** See IFocusableTree.lookUpFocusableNode. */
+  lookUpFocusableNode(id: string): IFocusableNode | null {
+    return this.getToolboxItemById(id) as IFocusableNode;
+  }
+
+  /** See IFocusableTree.onTreeFocus. */
+  onTreeFocus(
+    node: IFocusableNode,
+    _previousTree: IFocusableTree | null,
+  ): void {
+    if (node !== this) {
+      // Only select the item if it isn't already selected so as to not toggle.
+      if (this.getSelectedItem() !== node) {
+        this.setSelectedItem(node as IToolboxItem);
+      }
+    } else {
+      this.clearSelection();
+    }
+  }
+
+  /** See IFocusableTree.onTreeBlur. */
+  onTreeBlur(_nextTree: IFocusableTree | null): void {}
 }
 
 /** CSS for Toolbox.  See css.js for use. */

core/toolbox/toolbox_item.ts

@@ -12,6 +12,7 @@
 // Former goog.module ID: Blockly.ToolboxItem
 
 import type {ICollapsibleToolboxItem} from '../interfaces/i_collapsible_toolbox_item.js';
+import type {IFocusableTree} from '../interfaces/i_focusable_tree.js';
 import type {IToolbox} from '../interfaces/i_toolbox.js';
 import type {IToolboxItem} from '../interfaces/i_toolbox_item.js';
 import * as idGenerator from '../utils/idgenerator.js';
@@ -148,5 +149,28 @@ export class ToolboxItem implements IToolboxItem {
    * @param _isVisible True if category should be visible.
    */
   setVisible_(_isVisible: boolean) {}
+
+  /** See IFocusableNode.getFocusableElement. */
+  getFocusableElement(): HTMLElement | SVGElement {
+    const div = this.getDiv();
+    if (!div) {
+      throw Error('Trying to access toolbox item before DOM is initialized.');
+    }
+    if (!(div instanceof HTMLElement)) {
+      throw Error('Toolbox item div is unexpectedly not an HTML element.');
+    }
+    return div as HTMLElement;
+  }
+
+  /** See IFocusableNode.getFocusableTree. */
+  getFocusableTree(): IFocusableTree {
+    return this.parentToolbox_;
+  }
+
+  /** See IFocusableNode.onNodeFocus. */
+  onNodeFocus(): void {}
+
+  /** See IFocusableNode.onNodeBlur. */
+  onNodeBlur(): void {}
 }
 // nop by default

core/workspace_svg.ts

@@ -2690,7 +2690,19 @@ export class WorkspaceSvg
   ): void {}
 
   /** See IFocusableTree.onTreeBlur. */
-  onTreeBlur(_nextTree: IFocusableTree | null): void {}
+  onTreeBlur(nextTree: IFocusableTree | null): void {
+    // If the flyout loses focus, make sure to close it.
+    if (this.isFlyout && this.targetWorkspace) {
+      // Only hide the flyout if the flyout's workspace is losing focus and that
+      // focus isn't returning to the flyout itself or the toolbox.
+      const flyout = this.targetWorkspace.getFlyout();
+      const toolbox = this.targetWorkspace.getToolbox();
+      if (flyout && nextTree === flyout) return;
+      if (toolbox && nextTree === toolbox) return;
+      if (toolbox) toolbox.clearSelection();
+      if (flyout && flyout instanceof Flyout) flyout.autoHide(false);
+    }
+  }
 }
 
 /**

tests/mocha/toolbox_test.js

@@ -54,6 +54,7 @@ suite('Toolbox', function () {
       const themeManagerSpy = sinon.spy(themeManager, 'subscribe');
       const componentManager = this.toolbox.workspace_.getComponentManager();
       sinon.stub(componentManager, 'addComponent');
+      this.toolbox.dispose(); // Dispose of the old toolbox so that it can be reinited.
       this.toolbox.init();
       sinon.assert.calledWith(
         themeManagerSpy,
@@ -72,12 +73,14 @@ suite('Toolbox', function () {
       const renderSpy = sinon.spy(this.toolbox, 'render');
       const componentManager = this.toolbox.workspace_.getComponentManager();
       sinon.stub(componentManager, 'addComponent');
+      this.toolbox.dispose(); // Dispose of the old toolbox so that it can be reinited.
       this.toolbox.init();
       sinon.assert.calledOnce(renderSpy);
     });
     test('Init called -> Flyout is initialized', function () {
       const componentManager = this.toolbox.workspace_.getComponentManager();
       sinon.stub(componentManager, 'addComponent');
+      this.toolbox.dispose(); // Dispose of the old toolbox so that it can be reinited.
       this.toolbox.init();
       assert.isDefined(this.toolbox.getFlyout());
     });