feat: Add support for conditional ephemeral focus. (#9051)

## The basics

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

## The details
### Resolves

Needed for fixing https://github.com/google/blockly-samples/issues/2514 and https://github.com/google/blockly-samples/issues/2515.

### Proposed Changes

Update `FieldInput` along with drop-down and widget divs to support disabling the automatic ephemeral focus functionality.

### Reason for Changes

As mentioned in https://github.com/google/blockly-samples/issues/2514#issuecomment-2881539117 both https://github.com/google/blockly-samples/issues/2514 and https://github.com/google/blockly-samples/issues/2515 were caused by the custom fields leading to both drop-down and widget divs simultaneously taking ephemeral focus (and that's not currently allowed by `FocusManager`). This change updates both widget and drop-down divs with _optional_ parameters to conditionally disable automatic ephemeral focus so that `FieldInput` can, in turn, be customized with disabling automatic ephemeral focus for its inline editor. Being able to disable ephemeral focus for `FieldInput` allows the custom fields' own drop-down divs to take and manage ephemeral focus, instead, avoiding the duplicate scenario that led to the runtime failure.

Note that the drop-down div change in this PR is completely optional, but it's added for consistency and to avoid future scenarios of breakage when trying to use both divs together (as a fix is required in Core without monkeypatching).

It's worth noting that there could be a possibility for a more 'proper' fix in `FocusManager` by allowing multiple calls to `takeEphemeralFocus`, but it's unclear exactly how to solve this consistently (which is why it results in a hard failure today). The main issue is that the current focused node can change from underneath the manager (due to DOM focus changes), and the current focused element may also change. It's not clear if the first, last, or some other call to `takeEphemeralFocus` should take precedent or which node to return focus once ephemeral focus ends (in cases with multiple subsequent calls).

### Test Coverage

No new tests were added, though common field cases were tested manually in core's simple playground and in the plugin-specific playgrounds (per the original regressions). The keyboard navigation plugin test environment was also verified to ensure that this didn't alter any existing behavior (it should be a no-op except for the two custom field plugins).

Automated tests would be nice to add for all three classes, perhaps as part of #8915.

### Documentation

The code documentation changes here should be sufficient.

### Additional Information

These changes are being done directly to ease solving the above samples issues. See https://github.com/google/blockly-samples/pull/2521 for the follow-up fixes to samples.

core/dropdowndiv.ts

@@ -268,6 +268,11 @@ function getScaledBboxOfField(field: Field): Rect {
  * @param field The field to position the dropdown against.
  * @param opt_onHide Optional callback for when the drop-down is hidden.
  * @param opt_secondaryYOffset Optional Y offset for above-block positioning.
+ * @param manageEphemeralFocus Whether ephemeral focus should be managed
+ *     according to the drop-down div's lifetime. Note that if a false value is
+ *     passed in here then callers should manage ephemeral focus directly
+ *     otherwise focus may not properly restore when the widget closes. Defaults
+ *     to true.
  * @returns True if the menu rendered below block; false if above.
  */
 function showPositionedByRect(
@@ -275,6 +280,7 @@ function showPositionedByRect(
   field: Field,
   opt_onHide?: () => void,
   opt_secondaryYOffset?: number,
+  manageEphemeralFocus: boolean = true,
 ): boolean {
   // If we can fit it, render below the block.
   const primaryX = bBox.left + (bBox.right - bBox.left) / 2;
@@ -299,6 +305,7 @@ function showPositionedByRect(
     primaryY,
     secondaryX,
     secondaryY,
+    manageEphemeralFocus,
     opt_onHide,
   );
 }
@@ -319,6 +326,8 @@ function showPositionedByRect(
  * @param secondaryX Secondary/alternative origin point x, in absolute px.
  * @param secondaryY Secondary/alternative origin point y, in absolute px.
  * @param opt_onHide Optional callback for when the drop-down is hidden.
+ * @param manageEphemeralFocus Whether ephemeral focus should be managed
+ *     according to the widget div's lifetime.
  * @returns True if the menu rendered at the primary origin point.
  * @internal
  */
@@ -329,6 +338,7 @@ export function show<T>(
   primaryY: number,
   secondaryX: number,
   secondaryY: number,
+  manageEphemeralFocus: boolean,
   opt_onHide?: () => void,
 ): boolean {
   owner = newOwner as Field;
@@ -342,7 +352,9 @@ export function show<T>(
   dom.addClass(div, renderedClassName);
   dom.addClass(div, themeClassName);
 
-  returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
+  if (manageEphemeralFocus) {
+    returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
+  }
 
   // When we change `translate` multiple times in close succession,
   // Chrome may choose to wait and apply them all at once.

core/field_input.ts

@@ -352,8 +352,16 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
    *     undefined if triggered programmatically.
    * @param quietInput True if editor should be created without focus.
    *     Defaults to false.
+   * @param manageEphemeralFocus Whether ephemeral focus should be managed as
+   *     part of the editor's inline editor (when the inline editor is shown).
+   *     Callers must manage ephemeral focus themselves if this is false.
+   *     Defaults to true.
    */
-  protected override showEditor_(_e?: Event, quietInput = false) {
+  protected override showEditor_(
+    _e?: Event,
+    quietInput = false,
+    manageEphemeralFocus: boolean = true,
+  ) {
     this.workspace_ = (this.sourceBlock_ as BlockSvg).workspace;
     if (
       !quietInput &&
@@ -362,7 +370,7 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
     ) {
       this.showPromptEditor();
     } else {
-      this.showInlineEditor(quietInput);
+      this.showInlineEditor(quietInput, manageEphemeralFocus);
     }
   }
 
@@ -389,8 +397,10 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
    * Create and show a text input editor that sits directly over the text input.
    *
    * @param quietInput True if editor should be created without focus.
+   * @param manageEphemeralFocus Whether ephemeral focus should be managed as
+   *     part of the field's inline editor (widget div).
    */
-  private showInlineEditor(quietInput: boolean) {
+  private showInlineEditor(quietInput: boolean, manageEphemeralFocus: boolean) {
     const block = this.getSourceBlock();
     if (!block) {
       throw new UnattachedFieldError();
@@ -400,6 +410,7 @@ export abstract class FieldInput<T extends InputTypes> extends Field<
       block.RTL,
       this.widgetDispose_.bind(this),
       this.workspace_,
+      manageEphemeralFocus,
     );
     this.htmlInput_ = this.widgetCreate_() as HTMLInputElement;
     this.isBeingEdited_ = true;

core/widgetdiv.ts

@@ -84,12 +84,18 @@ export function createDom() {
  * @param newDispose Optional cleanup function to be run when the widget is
  *     closed.
  * @param workspace The workspace associated with the widget owner.
+ * @param manageEphemeralFocus Whether ephemeral focus should be managed
+ *     according to the widget div's lifetime. Note that if a false value is
+ *     passed in here then callers should manage ephemeral focus directly
+ *     otherwise focus may not properly restore when the widget closes. Defaults
+ *     to true.
  */
 export function show(
   newOwner: unknown,
   rtl: boolean,
   newDispose: () => void,
   workspace?: WorkspaceSvg | null,
+  manageEphemeralFocus: boolean = true,
 ) {
   hide();
   owner = newOwner;
@@ -114,7 +120,9 @@ export function show(
   if (themeClassName) {
     dom.addClass(div, themeClassName);
   }
-  returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
+  if (manageEphemeralFocus) {
+    returnEphemeralFocus = getFocusManager().takeEphemeralFocus(div);
+  }
 }
 
 /**