feat: Use FocusManager for navigation & state management (#482)

Fixes #142
Fixes #481

This removes nearly all custom focus/blur management and instead leverages `FocusManager` as the source of truth and primary system for focusing/selecting elements.

This largely continues the work in Core starting with RaspberryPiFoundation/blockly#8938 and ending with RaspberryPiFoundation/blockly#8941 in order to bring basic parity in the keyboard navigation plugin using `FocusManager`.

Specifically:
- This replaces all cases where explicit focus/opening logic is needed with `focusNode`/`focusTree` calls via `FocusManager`.
- `Navigation` now infers state based on what's currently focused rather than tracking it separately.
- All of the existing focus/blur response logic has been made redundant due to the inferred navigation mode and focus being tightly coupled with the components themselves.
- The gesture monkey patch seems no longer necessary since, as far as I can tell, focus gets forced back to where it's supposed to be at specific lifecycle moments (which helps undo many of the problems caused by `WorkspaceSvg`'s `markFocused`).
- The passive indicator is no longer necessary now that the `FocusManager`-driven `blocklyPassiveFocus` CSS class exists for styling.
- Note that there's a lot of automatic state synchronizing that has been purposely pushed into Core to simplify the navigation pieces, particularly:
  - Blocks will auto-select/unselect themselves based on focus.
  - `Toolbox` will automatically synchronize its selected item state with its item that has active focus.
  - `Toolbox` and `Flyout` cooperate for automatically closing the `Flyout` at the correct times.
- The new CSS classes are not yet final as the overall strategy for indicating active/passive focus isn't final. There's also additional work needed to ensure selection and active focus can be properly stylized as a combined state, but this is blocked on the completion of RaspberryPiFoundation/blockly#8942.
- `Toolbox` navigation was moved to using its methods directly instead of its event since selection logic now needs to be paired with `focusNode`.
- There are a number of changes in this PR that could probably go into Core, but these can wait for a future PR as they shouldn't be API breaking. Some of the changes include:
  - `Toolbox` item selection could auto-focus within `Toolbox` itself, or this could be done as part of `Toolbox`-specific navigation.
  - `Flyout` focus could automatically focus its first item if nothing is currently focused.
- For regression testing, the following has been checked:
  - 'T' and 'I' do work as expected (ensuring RaspberryPiFoundation/blockly#8933 (review) is no longer an issue).
  - Verified #227, #200, #229, #222, and #287 have not regressed. RaspberryPiFoundation/blockly-samples#2498 shouldn't be possible anymore (even with the fix) due to ephemeral focus, and we seem to be matching parity with #326 per the `handleFocus*()` functions, though there may be cases from `handleFocusWorkspace` yet to check.

The test updates were necessary because, at present, clicking does not force focus which means the tests need to rely purely on keys for navigation. I think these changes are actually an improvement since it closer aligns them with keyboard-only usage.

**Current gaps** that may need resolution prior to this PR being mergeable:
- There's a regression with clicking to create a variable closing the flyout that I'm still investigating. This is detailed more in RaspberryPiFoundation/blockly#8941.
- At some point between the latest changes to this branch and the ones in RaspberryPiFoundation/blockly#8941 block movement regressed slightly: finishing a movement gesture now defocuses the workspace entirely (even though this was working earlier).
- There are a lot of inconsistencies between the focus and selection styling before this PR and with this PR. It's unclear how much of this requires actual resolution.
- Much more testing is needed to understand gaps as this changes a significant amount of state handling for the plugin.

Author: BenHenning

src/actions/arrow_navigation.ts

@@ -8,6 +8,7 @@ import {ASTNode, ShortcutRegistry, utils as BlocklyUtils} from 'blockly/core';
 
 import type {Field, Toolbox, WorkspaceSvg} from 'blockly/core';
 
+import * as Blockly from 'blockly/core';
 import * as Constants from '../constants';
 import type {Navigation} from '../navigation';
 
@@ -53,6 +54,7 @@ export class ArrowNavigation {
       shortcut: ShortcutRegistry.KeyboardShortcut,
     ): boolean => {
       const toolbox = workspace.getToolbox() as Toolbox;
+      const flyout = workspace.getFlyout();
       let isHandled = false;
       switch (this.navigation.getState(workspace)) {
         case Constants.STATE.WORKSPACE:
@@ -67,12 +69,11 @@ export class ArrowNavigation {
           }
           return isHandled;
         case Constants.STATE.TOOLBOX:
-          isHandled =
-            toolbox && typeof toolbox.onShortcut === 'function'
-              ? toolbox.onShortcut(shortcut)
-              : false;
-          if (!isHandled) {
-            this.navigation.focusFlyout(workspace);
+          // @ts-expect-error private method
+          isHandled = toolbox && toolbox.selectChild();
+          if (!isHandled && flyout) {
+            Blockly.getFocusManager().focusTree(flyout.getWorkspace());
+            this.navigation.defaultFlyoutCursorIfNeeded(workspace);
           }
           return true;
         default:
@@ -100,12 +101,13 @@ export class ArrowNavigation {
           }
           return isHandled;
         case Constants.STATE.FLYOUT:
-          this.navigation.focusToolbox(workspace);
+          if (toolbox) {
+            Blockly.getFocusManager().focusTree(toolbox);
+          }
           return true;
         case Constants.STATE.TOOLBOX:
-          return toolbox && typeof toolbox.onShortcut === 'function'
-            ? toolbox.onShortcut(shortcut)
-            : false;
+          // @ts-expect-error private method
+          return toolbox && toolbox.selectParent();
         default:
           return false;
       }
@@ -173,9 +175,24 @@ export class ArrowNavigation {
               }
               return isHandled;
             case Constants.STATE.TOOLBOX:
-              return toolbox && typeof toolbox.onShortcut === 'function'
-                ? toolbox.onShortcut(shortcut)
-                : false;
+              if (toolbox) {
+                if (!toolbox.getSelectedItem()) {
+                  const firstItem =
+                    toolbox
+                      .getToolboxItems()
+                      .find((item) => item.isSelectable()) ?? null;
+                  toolbox.setSelectedItem(firstItem);
+                  isHandled = true;
+                } else {
+                  // @ts-expect-error private method
+                  isHandled = toolbox.selectNext();
+                }
+                const selectedItem = toolbox.getSelectedItem();
+                if (selectedItem) {
+                  Blockly.getFocusManager().focusNode(selectedItem);
+                }
+              }
+              return isHandled;
             default:
               return false;
           }
@@ -221,9 +238,15 @@ export class ArrowNavigation {
               }
               return isHandled;
             case Constants.STATE.TOOLBOX:
-              return toolbox && typeof toolbox.onShortcut === 'function'
-                ? toolbox.onShortcut(shortcut)
-                : false;
+              if (toolbox) {
+                // @ts-expect-error private method
+                isHandled = toolbox.selectPrevious();
+                const selectedItem = toolbox.getSelectedItem();
+                if (selectedItem) {
+                  Blockly.getFocusManager().focusNode(selectedItem);
+                }
+              }
+              return isHandled;
             default:
               return false;
           }

src/actions/clipboard.ts

@@ -13,6 +13,7 @@ import {
   clipboard,
   ICopyData,
   LineCursor,
+  getFocusManager,
 } from 'blockly';
 import * as Constants from '../constants';
 import type {BlockSvg, WorkspaceSvg} from 'blockly';
@@ -281,7 +282,7 @@ export class Clipboard {
     const copied = !!this.copyData;
     if (copied) {
       if (navigationState === Constants.STATE.FLYOUT) {
-        this.navigation.focusWorkspace(workspace);
+        getFocusManager().focusTree(workspace);
       }
       showCopiedHint(workspace);
     }
@@ -375,10 +376,10 @@ export class Clipboard {
       ? workspace
       : this.copyWorkspace;
 
-    const targetNode = this.navigation.getStationaryNode(pasteWorkspace);
-    // If we're pasting in the flyout it still targets the workspace. Focus first
-    // so ensure correct selection handling.
-    this.navigation.focusWorkspace(workspace);
+    const targetNode = this.navigation.getFocusedASTNode(pasteWorkspace);
+    // If we're pasting in the flyout it still targets the workspace. Focus
+    // first as to ensure correct selection handling.
+    getFocusManager().focusTree(workspace);
 
     Events.setGroup(true);
     const block = clipboard.paste(this.copyData, pasteWorkspace) as BlockSvg;

src/actions/enter.ts

@@ -9,6 +9,7 @@ import {
   Events,
   ShortcutRegistry,
   utils as BlocklyUtils,
+  getFocusManager,
 } from 'blockly/core';
 
 import type {
@@ -134,7 +135,7 @@ export class EnterAction {
       Events.setGroup(true);
     }
 
-    const stationaryNode = this.navigation.getStationaryNode(workspace);
+    const stationaryNode = this.navigation.getFocusedASTNode(workspace);
     const newBlock = this.createNewBlock(workspace);
     if (!newBlock) return;
     const insertStartPoint = stationaryNode
@@ -146,7 +147,7 @@ export class EnterAction {
 
     workspace.setResizesEnabled(true);
 
-    this.navigation.focusWorkspace(workspace);
+    getFocusManager().focusTree(workspace);
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     workspace.getCursor()?.setCurNode(ASTNode.createBlockNode(newBlock)!);
     this.mover.startMove(workspace, newBlock, insertStartPoint);

src/actions/exit.ts

@@ -4,7 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {ShortcutRegistry, utils as BlocklyUtils} from 'blockly/core';
+import {
+  ShortcutRegistry,
+  utils as BlocklyUtils,
+  getFocusManager,
+  Gesture,
+} from 'blockly/core';
 
 import * as Constants from '../constants';
 import type {Navigation} from '../navigation';
@@ -29,7 +34,10 @@ export class ExitAction {
         switch (this.navigation.getState(workspace)) {
           case Constants.STATE.FLYOUT:
           case Constants.STATE.TOOLBOX:
-            this.navigation.focusWorkspace(workspace);
+            getFocusManager().focusTree(workspace);
+            if (!Gesture.inProgress()) {
+              workspace.hideChaff();
+            }
             return true;
           default:
             return false;

src/actions/mover.ts

@@ -15,6 +15,7 @@ import {
   ASTNode,
   Connection,
   dragging,
+  getFocusManager,
   registry,
   utils,
   WorkspaceSvg,
@@ -132,6 +133,9 @@ export class Mover {
     // Begin drag.
     dragger.onDragStart(info.fakePointerEvent('pointerdown'));
     info.updateTotalDelta();
+    // In case the block is detached, ensure that it still retains focus
+    // (otherwise dragging will break).
+    getFocusManager().focusNode(block);
     return true;
   }
 
@@ -159,6 +163,8 @@ export class Mover {
     this.moves.delete(workspace);
     // Delay scroll until after block has finished moving.
     setTimeout(() => this.scrollCurrentBlockIntoView(workspace), 0);
+    // If the block gets reattached, ensure it retains focus.
+    getFocusManager().focusNode(info.block);
     return true;
   }
 
@@ -205,6 +211,8 @@ export class Mover {
     this.moves.delete(workspace);
     // Delay scroll until after block has finished moving.
     setTimeout(() => this.scrollCurrentBlockIntoView(workspace), 0);
+    // If the block gets reattached, ensure it retains focus.
+    getFocusManager().focusNode(info.block);
     return true;
   }