feat: navigation between stacks via n/b

Include workspace comments in the sequence as they are also top-level
navigation items.

Author: glastonbridge

src/actions/stack_navigation.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {ShortcutRegistry, WorkspaceSvg, utils} from 'blockly/core';
+import * as Constants from '../constants';
+
+/**
+ * Class for registering a shortcut for quick movement between top level bounds
+ * in the workspace.
+ */
+export class StackNavigationAction {
+  private stackShortcuts: ShortcutRegistry.KeyboardShortcut[] = [];
+
+  install() {
+    const preconditionFn = (workspace: WorkspaceSvg) =>
+      !!getCurNodeRoot(workspace);
+
+    function getCurNodeRoot(workspace: WorkspaceSvg) {
+      const cursor = workspace.getCursor();
+      // The fallback case includes workspace comments.
+      return cursor.getSourceBlock()?.getRootBlock() ?? cursor.getCurNode();
+    }
+
+    const previousStackShortcut: ShortcutRegistry.KeyboardShortcut = {
+      name: Constants.SHORTCUT_NAMES.PREVIOUS_STACK,
+      preconditionFn,
+      callback: (workspace) => {
+        const curNodeRoot = getCurNodeRoot(workspace);
+        if (!curNodeRoot) return false;
+        const prevRoot = workspace
+          .getNavigator()
+          .getPreviousSibling(curNodeRoot);
+        if (!prevRoot) return false;
+        workspace.getCursor().setCurNode(prevRoot);
+        return true;
+      },
+      keyCodes: [utils.KeyCodes.B],
+    };
+
+    const nextStackShortcut: ShortcutRegistry.KeyboardShortcut = {
+      name: Constants.SHORTCUT_NAMES.NEXT_STACK,
+      preconditionFn,
+      callback: (workspace) => {
+        const curNodeRoot = getCurNodeRoot(workspace);
+        if (!curNodeRoot) return false;
+        const nextRoot = workspace.getNavigator().getNextSibling(curNodeRoot);
+        if (!nextRoot) return false;
+        workspace.getCursor().setCurNode(nextRoot);
+        return true;
+      },
+      keyCodes: [utils.KeyCodes.N],
+    };
+
+    ShortcutRegistry.registry.register(previousStackShortcut);
+    this.stackShortcuts.push(previousStackShortcut);
+    ShortcutRegistry.registry.register(nextStackShortcut);
+    this.stackShortcuts.push(nextStackShortcut);
+  }
+
+  /**
+   * Unregisters the shortcut.
+   */
+  uninstall() {
+    this.stackShortcuts.forEach((shortcut) =>
+      ShortcutRegistry.registry.unregister(shortcut.name),
+    );
+    this.stackShortcuts.length = 0;
+  }
+}

src/constants.ts

@@ -33,6 +33,8 @@ export enum SHORTCUT_NAMES {
   DOWN = 'down',
   RIGHT = 'right',
   LEFT = 'left',
+  NEXT_STACK = 'next_stack',
+  PREVIOUS_STACK = 'previous_stack',
   INSERT = 'insert',
   EDIT_OR_CONFIRM = 'edit_or_confirm',
   DISCONNECT = 'disconnect',
@@ -100,4 +102,6 @@ SHORTCUT_CATEGORIES[Msg['SHORTCUTS_CODE_NAVIGATION']] = [
   SHORTCUT_NAMES.DOWN,
   SHORTCUT_NAMES.RIGHT,
   SHORTCUT_NAMES.LEFT,
+  SHORTCUT_NAMES.NEXT_STACK,
+  SHORTCUT_NAMES.PREVIOUS_STACK,
 ];

src/navigation_controller.ts

@@ -36,6 +36,7 @@ import {ActionMenu} from './actions/action_menu';
 import {MoveActions} from './actions/move';
 import {Mover} from './actions/mover';
 import {DuplicateAction} from './actions/duplicate';
+import {StackNavigationAction} from './actions/stack_navigation';
 
 const KeyCodes = BlocklyUtils.KeyCodes;
 
@@ -75,6 +76,8 @@ export class NavigationController {
 
   moveActions = new MoveActions(this.mover);
 
+  stackNavigationAction: StackNavigationAction = new StackNavigationAction();
+
   /**
    * Original Toolbox.prototype.onShortcut method, saved by
    * addShortcutHandlers.
@@ -250,6 +253,7 @@ export class NavigationController {
     this.duplicateAction.install();
     this.moveActions.install();
     this.shortcutDialog.install();
+    this.stackNavigationAction.install();
 
     // Initialize the shortcut modal with available shortcuts.  Needs
     // to be done separately rather at construction, as many shortcuts
@@ -273,6 +277,7 @@ export class NavigationController {
     this.enterAction.uninstall();
     this.actionMenu.uninstall();
     this.shortcutDialog.uninstall();
+    this.stackNavigationAction.uninstall();
 
     for (const shortcut of Object.values(this.shortcuts)) {
       ShortcutRegistry.registry.unregister(shortcut.name);

test/webdriverio/test/stack_navigation.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as chai from 'chai';
+import {
+  getCurrentFocusedBlockId,
+  getCurrentFocusNodeId,
+  PAUSE_TIME,
+  tabNavigateToWorkspace,
+  testFileLocations,
+  testSetup,
+} from './test_setup.js';
+
+suite('Stack navigation', function () {
+  // Setting timeout to unlimited as these tests take longer time to run
+  this.timeout(0);
+
+  // Clear the workspace and load start blocks
+  setup(async function () {
+    this.browser = await testSetup(testFileLocations.COMMENTS);
+    await this.browser.pause(PAUSE_TIME);
+  });
+
+  test('Next', async function () {
+    await tabNavigateToWorkspace(this.browser);
+    chai.assert.equal(
+      'p5_setup_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+    await this.browser.keys('n');
+    chai.assert.equal(
+      'p5_draw_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+    await this.browser.keys('n');
+    chai.assert.equal(
+      'workspace_comment_1',
+      await getCurrentFocusNodeId(this.browser),
+    );
+    await this.browser.keys('n');
+    // Looped around.
+    chai.assert.equal(
+      'p5_setup_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+  });
+
+  test('Previous', async function () {
+    await tabNavigateToWorkspace(this.browser);
+    chai.assert.equal(
+      'p5_setup_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+    await this.browser.keys('b');
+    // Looped to bottom.
+    chai.assert.equal(
+      'workspace_comment_1',
+      await getCurrentFocusNodeId(this.browser),
+    );
+    await this.browser.keys('b');
+    chai.assert.equal(
+      'p5_draw_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+    await this.browser.keys('b');
+    chai.assert.equal(
+      'p5_setup_1',
+      await getCurrentFocusedBlockId(this.browser),
+    );
+  });
+});

test/webdriverio/test/test_setup.ts

@@ -141,6 +141,7 @@ export const testFileLocations = {
   MOVE_TEST_BLOCKS: createTestUrl(
     new URLSearchParams({scenario: 'moveTestBlocks'}),
   ),
+  COMMENTS: createTestUrl(new URLSearchParams({scenario: 'comments'})),
   // eslint-disable-next-line @typescript-eslint/naming-convention
   BASE_RTL: createTestUrl(new URLSearchParams({rtl: 'true'})),
   GERAS: createTestUrl(new URLSearchParams({renderer: 'geras'})),