feat: Make fields focusable (#8923)

## The basics

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

## The details
### Resolves

Fixes #8922
Fixes #8929
Fixes part of #8771

### Proposed Changes

This PR introduces support for fields to be focusable (and thus navigable with keyboard navigation when paired with downstream changes to `LineCursor` and the keyboard navigation plugin). This is a largely isolated change in how it fundamentally works:
- `Field` was updated to become an `IFocusableNode`. Note that it uses a specific string-based ID schema in order to ensure that it can be properly linked back to its unique block (which helps make the search for the field in `WorkspaceSvg` a bit more efficient). This could be done with a globally unique ID, instead, but all fields would need to be searched vs. just those for the field's parent block.
- The drop-down and widget divs have been updated to manage ephemeral focus with `FocusManager` when they're open for non-system dialogs (ephemeral focus isn't needed for system dialogs/prompts since those already take/restore focus in a native way that `FocusManager` will respond to--this may require future work, however, if the restoration causes unexpected behavior for users). This approach was done due to a suggestion from @maribethb as the alternative would be a more complicated breaking change (forcing `Field` subclasses to properly manage ephemeral focus). It may still be the case that certain cases will need to do so, but widget and drop-down divs seem to address the majority of possibilities.

**Important**: `Input`s are not explicitly being supported here. As far as I can tell, we can't run into a case where `LineCursor` tries to set an input node, though perhaps I simply haven't come across this case. Supporting `Fields` and `Connections` (per #8928) seems to cover the main needed cases, though making `Input`s focusable may be a future requirement.

### 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).

Note that #8929 isn't broadly addressed since making widget & drop down divs manage ephemeral focus directly addresses a large class of cases. Additional cases may arise where a plugin or Blockly integration may require additional effort to make keyboard navigation work for their field--this may be best addressed with documentation and guidance.

### 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 new documentation is planned, however it may be prudent to update the field documentation in the future to explain how to utilize ephemeral focus when specifically building compatibility for keyboard navigation.

### Additional Information

This includes changes that have been pulled from #8875.

core/dialog.ts

@@ -33,6 +33,8 @@ const defaultPrompt = function (
   defaultValue: string,
   callback: (result: string | null) => void,
 ) {
+  // NOTE TO DEVELOPER: Ephemeral focus doesn't need to be taken for the native
+  // window prompt since it prevents focus from changing while open.
   callback(window.prompt(message, defaultValue));
 };
 
@@ -116,6 +118,11 @@ export function prompt(
 /**
  * Sets the function to be run when Blockly.dialog.prompt() is called.
  *
+ * **Important**: When overridding this, be aware that non-native prompt
+ * experiences may require managing ephemeral focus in FocusManager. This isn't
+ * needed for the native window prompt because it prevents focus from being
+ * changed while open.
+ *
  * @param promptFunction The function to be run, or undefined to restore the
  *     default implementation.
  * @see Blockly.dialog.prompt

core/dropdowndiv.ts

@@ -15,6 +15,7 @@
 import type {BlockSvg} from './block_svg.js';
 import * as common from './common.js';
 import type {Field} from './field.js';
+import {ReturnEphemeralFocus, getFocusManager} from './focus_manager.js';
 import * as dom from './utils/dom.js';
 import * as math from './utils/math.js';
 import {Rect} from './utils/rect.js';
@@ -82,6 +83,9 @@ let owner: Field | null = null;
 /** Whether the dropdown was positioned to a field or the source block. */
 let positionToField: boolean | null = null;
 
+/** Callback to FocusManager to return ephemeral focus when the div closes. */
+let returnEphemeralFocus: ReturnEphemeralFocus | null = null;
+
 /**
  * Dropdown bounds info object used to encapsulate sizing information about a
  * bounding element (bounding box and width/height).
@@ -338,6 +342,8 @@ export function show<T>(
   dom.addClass(div, renderedClassName);
   dom.addClass(div, themeClassName);
 
+  returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
+
   // When we change `translate` multiple times in close succession,
   // Chrome may choose to wait and apply them all at once.
   // Since we want the translation to initial X, Y to be immediate,
@@ -623,6 +629,10 @@ export function hide() {
   animateOutTimer = setTimeout(function () {
     hideWithoutAnimation();
   }, ANIMATION_TIME * 1000);
+  if (returnEphemeralFocus) {
+    returnEphemeralFocus();
+    returnEphemeralFocus = null;
+  }
   if (onHide) {
     onHide();
     onHide = null;
@@ -638,6 +648,10 @@ export function hideWithoutAnimation() {
     clearTimeout(animateOutTimer);
   }
 
+  if (returnEphemeralFocus) {
+    returnEphemeralFocus();
+    returnEphemeralFocus = null;
+  }
   if (onHide) {
     onHide();
     onHide = null;

core/field.ts

@@ -25,6 +25,8 @@ import * as eventUtils from './events/utils.js';
 import type {Input} from './inputs/input.js';
 import type {IASTNodeLocationSvg} from './interfaces/i_ast_node_location_svg.js';
 import type {IASTNodeLocationWithBlock} from './interfaces/i_ast_node_location_with_block.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 {IRegistrable} from './interfaces/i_registrable.js';
 import {ISerializable} from './interfaces/i_serializable.js';
@@ -34,6 +36,7 @@ import type {KeyboardShortcut} from './shortcut_registry.js';
 import * as Tooltip from './tooltip.js';
 import type {Coordinate} from './utils/coordinate.js';
 import * as dom from './utils/dom.js';
+import * as idGenerator from './utils/idgenerator.js';
 import * as parsing from './utils/parsing.js';
 import {Rect} from './utils/rect.js';
 import {Size} from './utils/size.js';
@@ -42,7 +45,7 @@ import {Svg} from './utils/svg.js';
 import * as userAgent from './utils/useragent.js';
 import * as utilsXml from './utils/xml.js';
 import * as WidgetDiv from './widgetdiv.js';
-import type {WorkspaceSvg} from './workspace_svg.js';
+import {WorkspaceSvg} from './workspace_svg.js';
 
 /**
  * A function that is called to validate changes to the field's value before
@@ -72,7 +75,8 @@ export abstract class Field<T = any>
     IASTNodeLocationWithBlock,
     IKeyboardAccessible,
     IRegistrable,
-    ISerializable
+    ISerializable,
+    IFocusableNode
 {
   /**
    * To overwrite the default value which is set in **Field**, directly update
@@ -191,6 +195,9 @@ export abstract class Field<T = any>
    */
   SERIALIZABLE = false;
 
+  /** The unique ID of this field. */
+  private id_: string | null = null;
+
   /**
    * @param value The initial value of the field.
    *     Also accepts Field.SKIP_SETUP if you wish to skip setup (only used by
@@ -255,6 +262,7 @@ export abstract class Field<T = any>
       throw Error('Field already bound to a block');
     }
     this.sourceBlock_ = block;
+    this.id_ = `${block.id}_field_${idGenerator.getNextUniqueId()}`;
   }
 
   /**
@@ -298,7 +306,12 @@ export abstract class Field<T = any>
       // Field has already been initialized once.
       return;
     }
-    this.fieldGroup_ = dom.createSvgElement(Svg.G, {});
+    const id = this.id_;
+    if (!id) throw new Error('Expected ID to be defined prior to init.');
+    this.fieldGroup_ = dom.createSvgElement(Svg.G, {
+      'tabindex': '-1',
+      'id': id,
+    });
     if (!this.isVisible()) {
       this.fieldGroup_.style.display = 'none';
     }
@@ -1401,6 +1414,29 @@ export abstract class Field<T = any>
     }
   }
 
+  /** See IFocusableNode.getFocusableElement. */
+  getFocusableElement(): HTMLElement | SVGElement {
+    if (!this.fieldGroup_) {
+      throw Error('This field currently has no representative DOM element.');
+    }
+    return this.fieldGroup_;
+  }
+
+  /** See IFocusableNode.getFocusableTree. */
+  getFocusableTree(): IFocusableTree {
+    const block = this.getSourceBlock();
+    if (!block) {
+      throw new UnattachedFieldError();
+    }
+    return block.workspace as WorkspaceSvg;
+  }
+
+  /** See IFocusableNode.onNodeFocus. */
+  onNodeFocus(): void {}
+
+  /** See IFocusableNode.onNodeBlur. */
+  onNodeBlur(): void {}
+
   /**
    * Subclasses should reimplement this method to construct their Field
    * subclass from a JSON arg object.

core/widgetdiv.ts

@@ -8,6 +8,7 @@
 
 import * as common from './common.js';
 import {Field} from './field.js';
+import {ReturnEphemeralFocus, getFocusManager} from './focus_manager.js';
 import * as dom from './utils/dom.js';
 import type {Rect} from './utils/rect.js';
 import type {Size} from './utils/size.js';
@@ -34,6 +35,9 @@ let themeClassName = '';
 /** The HTML container for popup overlays (e.g. editor widgets). */
 let containerDiv: HTMLDivElement | null;
 
+/** Callback to FocusManager to return ephemeral focus when the div closes. */
+let returnEphemeralFocus: ReturnEphemeralFocus | null = null;
+
 /**
  * Returns the HTML container for editor widgets.
  *
@@ -110,6 +114,7 @@ export function show(
   if (themeClassName) {
     dom.addClass(div, themeClassName);
   }
+  returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
 }
 
 /**
@@ -126,8 +131,14 @@ export function hide() {
   div.style.display = 'none';
   div.style.left = '';
   div.style.top = '';
-  if (dispose) dispose();
-  dispose = null;
+  if (returnEphemeralFocus) {
+    returnEphemeralFocus();
+    returnEphemeralFocus = null;
+  }
+  if (dispose) {
+    dispose();
+    dispose = null;
+  }
   div.textContent = '';
 
   if (rendererClassName) {

core/workspace_svg.ts

@@ -2709,6 +2709,18 @@ export class WorkspaceSvg
       }
     }
 
+    const fieldIndicatorIndex = id.indexOf('_field_');
+    if (fieldIndicatorIndex !== -1) {
+      const blockId = id.substring(0, fieldIndicatorIndex);
+      const block = this.getBlockById(blockId);
+      if (block) {
+        for (const field of block.getFields()) {
+          if (field.getFocusableElement().id === id) return field;
+        }
+      }
+      return null;
+    }
+
     return this.getBlockById(id) as IFocusableNode;
   }