feat: Add keyboard shortcut to perform an action on the currently focused element (#9673)

* feat: Add keyboard shortcut to perform an action on the currently focused element

* test: Add tests

* chore: Add example of shortcut formats

* fix: Don't show toast if shortcut doesn't exist

* chore: Clarify use of Zelos in tests

* fix: Skip help hint toast until shortcut is added

Author: gonfunko

packages/blockly/core/block_svg.ts

@@ -35,6 +35,7 @@ import {EventType} from './events/type.js';
 import * as eventUtils from './events/utils.js';
 import {FieldLabel} from './field_label.js';
 import {getFocusManager} from './focus_manager.js';
+import * as hints from './hints.js';
 import {IconType} from './icons/icon_types.js';
 import {MutatorIcon} from './icons/mutator_icon.js';
 import {WarningIcon} from './icons/warning_icon.js';
@@ -52,6 +53,7 @@ import type {IFocusableNode} from './interfaces/i_focusable_node.js';
 import type {IFocusableTree} from './interfaces/i_focusable_tree.js';
 import {IIcon} from './interfaces/i_icon.js';
 import * as internalConstants from './internal_constants.js';
+import {KeyboardMover} from './keyboard_nav/keyboard_mover.js';
 import {Msg} from './msg.js';
 import * as renderManagement from './render_management.js';
 import {RenderedConnection} from './rendered_connection.js';
@@ -1903,6 +1905,34 @@ export class BlockSvg
     return true;
   }
 
+  /**
+   * Handles the user acting on this block via keyboard navigation.
+   * If this block is in the flyout, a new copy is spawned in move mode on the
+   * main workspace. If this block has a single full-block field, that field
+   * will be focused. Otherwise, this is a no-op.
+   */
+  performAction() {
+    if (this.workspace.isFlyout) {
+      KeyboardMover.mover.startMove(this);
+      return;
+    } else if (this.isSimpleReporter()) {
+      for (const input of this.inputList) {
+        for (const field of input.fieldRow) {
+          if (field.isClickable() && field.isFullBlockField()) {
+            field.showEditor();
+            return;
+          }
+        }
+      }
+    }
+
+    if (this.workspace.getNavigator().getFirstChild(this)) {
+      hints.showBlockNavigationHint(this.workspace);
+    } else {
+      hints.showHelpHint(this.workspace);
+    }
+  }
+
   /**
    * Returns a set of all of the parent blocks of the given block.
    *

packages/blockly/core/bubbles/mini_workspace_bubble.ts

@@ -6,6 +6,7 @@
 
 import type {BlocklyOptions} from '../blockly_options.js';
 import {Abstract as AbstractEvent} from '../events/events_abstract.js';
+import {getFocusManager} from '../focus_manager.js';
 import {KeyboardMover} from '../keyboard_nav/keyboard_mover.js';
 import {Options} from '../options.js';
 import {Coordinate} from '../utils/coordinate.js';
@@ -287,4 +288,12 @@ export class MiniWorkspaceBubble extends Bubble {
         'monkey-patched in by blockly.ts',
     );
   }
+
+  /**
+   * Handles the user acting on this bubble via keyboard navigation by focusing
+   * the mutator workspace.
+   */
+  performAction() {
+    getFocusManager().focusTree(this.getWorkspace());
+  }
 }

packages/blockly/core/bubbles/textinput_bubble.ts

@@ -279,6 +279,14 @@ export class TextInputBubble extends Bubble {
   getEditor() {
     return this.editor;
   }
+
+  /**
+   * Handles the user acting on this bubble via keyboard navigation by focusing
+   * the comment editor.
+   */
+  performAction() {
+    getFocusManager().focusNode(this.getEditor());
+  }
 }
 
 Css.register(`

packages/blockly/core/comments/rendered_workspace_comment.ts

@@ -358,4 +358,13 @@ export class RenderedWorkspaceComment
   canBeFocused(): boolean {
     return true;
   }
+
+  /**
+   * Handles the user acting on this comment via keyboard navigation.
+   * Expands the comment and focuses its editor.
+   */
+  performAction() {
+    this.setCollapsed(false);
+    getFocusManager().focusNode(this.getEditorFocusableNode());
+  }
 }

packages/blockly/core/field.ts

@@ -1488,6 +1488,14 @@ export abstract class Field<T = any>
     return true;
   }
 
+  /**
+   * Handles the user acting on this field via keyboard navigation.
+   * Shows and focuses the field editor.
+   */
+  performAction() {
+    this.showEditor();
+  }
+
   /**
    * Subclasses should reimplement this method to construct their Field
    * subclass from a JSON arg object.

packages/blockly/core/flyout_button.ts

@@ -421,6 +421,19 @@ export class FlyoutButton
   getId() {
     return this.id;
   }
+
+  /**
+   * Handles the user acting on this button via keyboard navigation.
+   * Invokes the click handler callback.
+   */
+  performAction(): void {
+    if (!this.isFlyoutLabel) {
+      const callback = this.targetWorkspace.getButtonCallback(this.callbackKey);
+      if (callback) {
+        callback(this);
+      }
+    }
+  }
 }
 
 /** CSS for buttons and labels. See css.js for use. */

packages/blockly/core/hints.ts

@@ -6,11 +6,15 @@
 
 import {Msg} from './msg.js';
 import {Toast} from './toast.js';
+import {getShortActionShortcut} from './utils/shortcut_formatting.js';
 import * as userAgent from './utils/useragent.js';
 import type {WorkspaceSvg} from './workspace_svg.js';
 
 const unconstrainedMoveHintId = 'unconstrainedMoveHint';
 const constrainedMoveHintId = 'constrainedMoveHint';
+const helpHintId = 'helpHint';
+const blockNavigationHintId = 'blockNavigationHint';
+const workspaceNavigationHintId = 'workspaceNavigationHint';
 
 /**
  * Nudge the user to use unconstrained movement.
@@ -62,3 +66,39 @@ export function clearMoveHints(workspace: WorkspaceSvg) {
   Toast.hide(workspace, constrainedMoveHintId);
   Toast.hide(workspace, unconstrainedMoveHintId);
 }
+
+/**
+ * Nudge the user to open the help.
+ *
+ * @param workspace The workspace.
+ */
+export function showHelpHint(workspace: WorkspaceSvg) {
+  const shortcut = getShortActionShortcut('list_shortcuts');
+  if (!shortcut) return;
+
+  const message = Msg['HELP_PROMPT'].replace('%1', shortcut);
+  const id = helpHintId;
+  Toast.show(workspace, {message, id});
+}
+
+/**
+ * Tell the user how to navigate inside blocks.
+ *
+ * @param workspace The workspace.
+ */
+export function showBlockNavigationHint(workspace: WorkspaceSvg) {
+  const message = Msg['KEYBOARD_NAV_BLOCK_NAVIGATION_HINT'];
+  const id = blockNavigationHintId;
+  Toast.show(workspace, {message, id});
+}
+
+/**
+ * Tell the user how to navigate inside the workspace.
+ *
+ * @param workspace The workspace.
+ */
+export function showWorkspaceNavigationHint(workspace: WorkspaceSvg) {
+  const message = Msg['KEYBOARD_NAV_WORKSPACE_NAVIGATION_HINT'];
+  const id = workspaceNavigationHintId;
+  Toast.show(workspace, {message, id});
+}

packages/blockly/core/icons/icon.ts

@@ -7,10 +7,12 @@
 import type {Block} from '../block.js';
 import type {BlockSvg} from '../block_svg.js';
 import * as browserEvents from '../browser_events.js';
+import {getFocusManager} from '../focus_manager.js';
 import type {IContextMenu} from '../interfaces/i_contextmenu.js';
 import type {IFocusableTree} from '../interfaces/i_focusable_tree.js';
 import {hasBubble} from '../interfaces/i_has_bubble.js';
 import type {IIcon} from '../interfaces/i_icon.js';
+import * as renderManagement from '../render_management.js';
 import * as tooltip from '../tooltip.js';
 import {Coordinate} from '../utils/coordinate.js';
 import * as dom from '../utils/dom.js';
@@ -189,6 +191,22 @@ export abstract class Icon implements IIcon, IContextMenu {
     return true;
   }
 
+  /**
+   * Handles the user acting on this icon via keyboard navigation.
+   * Performs the same action as a click would, and focuses this icon's bubble
+   * if it has one.
+   */
+  performAction() {
+    this.onClick();
+    renderManagement.finishQueuedRenders().then(() => {
+      if (hasBubble(this) && this.bubbleIsVisible()) {
+        const bubble = this.getBubble();
+        if (!bubble) return;
+        getFocusManager().focusNode(bubble);
+      }
+    });
+  }
+
   /**
    * Returns the block that this icon is attached to.
    *

packages/blockly/core/interfaces/i_focusable_node.ts

@@ -99,6 +99,13 @@ export interface IFocusableNode {
    * @returns Whether this node can be focused by FocusManager.
    */
   canBeFocused(): boolean;
+
+  /**
+   * Optional method invoked when this node has focus and the user acts on it by
+   * pressing Enter or Space. Behavior should generally be similar to the node
+   * being clicked on.
+   */
+  performAction?(): void;
 }
 
 /**

packages/blockly/core/keyboard_nav/keyboard_mover.ts

@@ -102,7 +102,7 @@ export class KeyboardMover {
    * @param event The keyboard event that triggered this move.
    * @returns True iff a move has successfully begun.
    */
-  startMove(draggable: IDraggable, event: KeyboardEvent) {
+  startMove(draggable: IDraggable, event?: KeyboardEvent) {
     if (!this.canMove(draggable) || this.isMoving()) return false;
 
     const DraggerClass = registry.getClassFromOptions(