feat: DH-19632: Add shortcuts to cycle stacks and panels (#2458)

gzh2003 · web-flow · commit 97098f257d08 · 2025-06-20T12:08:06.000-04:00
Part of DH-19632. Introduces keyboard navigation to cycle between and within stacks. Navigating through shortcuts activates content items and respects any existing active selections. `Ctrl + '` / `Ctrl + ;`: to cycle forward/backward between different stacks in the layout `Ctrl + Shift + '` / `Ctrl + Shift + ;`: to cycle forward/backward between tabs within the currently focused stack Changes: - Create`NavigationEvent` system - Implement stack and tab cycling handlers in `PanelManager` - Add `getFocusedStack()` and `getFocusedStackIndex()` helper methods to `LayoutUtils` for focus detection - Add `forceFocus` parameter that bypasses the normal `isFocusonShow` check
diff --git a/packages/code-studio/src/main/AppMainContainer.tsx b/packages/code-studio/src/main/AppMainContainer.tsx
@@ -14,6 +14,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import {
   ContextActions,
   GLOBAL_SHORTCUTS,
+  NAVIGATION_SHORTCUTS,
   Popper,
   type ContextAction,
   Button,
@@ -39,6 +40,10 @@ import {
   setDashboardData as setDashboardDataAction,
   setDashboardPluginData as setDashboardPluginDataAction,
   updateDashboardData as updateDashboardDataAction,
+  emitCycleToNextStack,
+  emitCycleToPreviousStack,
+  emitCycleToNextTab,
+  emitCycleToPreviousTab,
 } from '@deephaven/dashboard';
 import {
   ConsolePlugin,
@@ -235,6 +240,34 @@ export class AppMainContainer extends Component<
           shortcut: IRIS_GRID_SHORTCUTS.TABLE.CLEAR_ALL_FILTERS,
           isGlobal: true,
         },
+        {
+          action: () => {
+            this.sendCycleStackForward();
+          },
+          shortcut: NAVIGATION_SHORTCUTS.CYCLE_TO_NEXT_STACK,
+          isGlobal: true,
+        },
+        {
+          action: () => {
+            this.sendCycleStackBackward();
+          },
+          shortcut: NAVIGATION_SHORTCUTS.CYCLE_TO_PREVIOUS_STACK,
+          isGlobal: true,
+        },
+        {
+          action: () => {
+            this.sendCycleTabForward();
+          },
+          shortcut: NAVIGATION_SHORTCUTS.CYCLE_TO_NEXT_TAB,
+          isGlobal: true,
+        },
+        {
+          action: () => {
+            this.sendCycleTabBackward();
+          },
+          shortcut: NAVIGATION_SHORTCUTS.CYCLE_TO_PREVIOUS_TAB,
+          isGlobal: true,
+        },
         {
           action: () => {
             this.sendReopenLast();
@@ -411,6 +444,22 @@ export class AppMainContainer extends Component<
     this.emitLayoutEvent(InputFilterEvent.CLEAR_ALL_FILTERS);
   }
 
+  sendCycleStackForward(): void {
+    emitCycleToNextStack(this.getActiveEventHub());
+  }
+
+  sendCycleStackBackward(): void {
+    emitCycleToPreviousStack(this.getActiveEventHub());
+  }
+
+  sendCycleTabForward(): void {
+    emitCycleToNextTab(this.getActiveEventHub());
+  }
+
+  sendCycleTabBackward(): void {
+    emitCycleToPreviousTab(this.getActiveEventHub());
+  }
+
   sendReopenLast(): void {
     this.emitLayoutEvent(PanelEvent.REOPEN_LAST);
   }
diff --git a/packages/components/src/shortcuts/NavigationShortcuts.ts b/packages/components/src/shortcuts/NavigationShortcuts.ts
@@ -0,0 +1,35 @@
+import ShortcutRegistry from './ShortcutRegistry';
+import { MODIFIER, KEY } from './Shortcut';
+
+const NAVIGATION_SHORTCUTS = {
+  CYCLE_TO_NEXT_STACK: ShortcutRegistry.createAndAdd({
+    id: 'NAVIGATION.CYCLE_TO_NEXT_STACK',
+    name: 'Cycle To Next Stack',
+    shortcut: [MODIFIER.CTRL, KEY.SINGLE_QUOTE],
+    macShortcut: [MODIFIER.CMD, KEY.SINGLE_QUOTE],
+    isEditable: true,
+  }),
+  CYCLE_TO_PREVIOUS_STACK: ShortcutRegistry.createAndAdd({
+    id: 'NAVIGATION.CYCLE_TO_PREVIOUS_STACK',
+    name: 'Cycle To Previous Stack',
+    shortcut: [MODIFIER.CTRL, KEY.SEMICOLON],
+    macShortcut: [MODIFIER.CMD, KEY.SEMICOLON],
+    isEditable: true,
+  }),
+  CYCLE_TO_NEXT_TAB: ShortcutRegistry.createAndAdd({
+    id: 'NAVIGATION.CYCLE_TO_NEXT_TAB',
+    name: 'Cycle To Next Tab',
+    shortcut: [MODIFIER.CTRL, MODIFIER.SHIFT, KEY.DOUBLE_QUOTE],
+    macShortcut: [MODIFIER.CMD, MODIFIER.SHIFT, KEY.SINGLE_QUOTE],
+    isEditable: true,
+  }),
+  CYCLE_TO_PREVIOUS_TAB: ShortcutRegistry.createAndAdd({
+    id: 'NAVIGATION.CYCLE_TO_PREVIOUS_TAB',
+    name: 'Cycle To Previous TAB',
+    shortcut: [MODIFIER.CTRL, MODIFIER.SHIFT, KEY.COLON],
+    macShortcut: [MODIFIER.CMD, MODIFIER.SHIFT, KEY.SEMICOLON],
+    isEditable: true,
+  }),
+};
+
+export default NAVIGATION_SHORTCUTS;
diff --git a/packages/components/src/shortcuts/index.ts b/packages/components/src/shortcuts/index.ts
@@ -1,4 +1,5 @@
 export { default as GLOBAL_SHORTCUTS } from './GlobalShortcuts';
+export { default as NAVIGATION_SHORTCUTS } from './NavigationShortcuts';
 export { default as Shortcut } from './Shortcut';
 export * from './Shortcut';
 export { default as ShortcutRegistry } from './ShortcutRegistry';
diff --git a/packages/dashboard/src/NavigationEvent.ts b/packages/dashboard/src/NavigationEvent.ts
@@ -0,0 +1,34 @@
+import { makeEventFunctions } from '@deephaven/golden-layout';
+
+const NavigationEvent = Object.freeze({
+  CYCLE_TO_NEXT_STACK: 'NavigationEvent.CYCLE_TO_NEXT_STACK',
+  CYCLE_TO_PREVIOUS_STACK: 'NavigationEvent.CYCLE_TO_PREVIOUS_STACK',
+  CYCLE_TO_NEXT_TAB: 'NavigationEvent.CYCLE_TO_NEXT_TAB',
+  CYCLE_TO_PREVIOUS_TAB: 'NavigationEvent.CYCLE_TO_PREVIOUS_TAB',
+});
+
+export const {
+  listen: listenForCycleToNextStack,
+  emit: emitCycleToNextStack,
+  useListener: useCycleToNextStackListener,
+} = makeEventFunctions(NavigationEvent.CYCLE_TO_NEXT_STACK);
+
+export const {
+  listen: listenForCycleToPreviousStack,
+  emit: emitCycleToPreviousStack,
+  useListener: useCycleToPreviousStackListener,
+} = makeEventFunctions(NavigationEvent.CYCLE_TO_PREVIOUS_STACK);
+
+export const {
+  listen: listenForCycleToNextTab,
+  emit: emitCycleToNextTab,
+  useListener: useCycleToNextTabListener,
+} = makeEventFunctions(NavigationEvent.CYCLE_TO_NEXT_TAB);
+
+export const {
+  listen: listenForCycleToPreviousTab,
+  emit: emitCycleToPreviousTab,
+  useListener: useCycleToPreviousTabListener,
+} = makeEventFunctions(NavigationEvent.CYCLE_TO_PREVIOUS_TAB);
+
+export default NavigationEvent;
diff --git a/packages/dashboard/src/PanelManager.ts b/packages/dashboard/src/PanelManager.ts
@@ -8,6 +8,12 @@ import type {
 } from '@deephaven/golden-layout';
 import Log from '@deephaven/log';
 import PanelEvent from './PanelEvent';
+import {
+  listenForCycleToNextStack,
+  listenForCycleToPreviousStack,
+  listenForCycleToNextTab,
+  listenForCycleToPreviousTab,
+} from './NavigationEvent';
 import LayoutUtils, { isReactComponentConfig } from './layout/LayoutUtils';
 import {
   isWrappedComponent,
@@ -18,6 +24,11 @@ import {
 
 const log = Log.module('PanelManager');
 
+enum CycleDirection {
+  Next,
+  Previous,
+}
+
 export type PanelHydraterFunction = (
   name: string,
   props: PanelProps
@@ -64,6 +75,8 @@ class PanelManager {
 
   openedMap: OpenedPanelMap;
 
+  navigationEventListenerRemovers: (() => void)[];
+
   /**
    * @param layout The GoldenLayout object to attach to
    * @param hydrateComponent Function to hydrate a panel from a dehydrated state
@@ -88,6 +101,11 @@ class PanelManager {
     this.handleUnmount = this.handleUnmount.bind(this);
     this.handleReopen = this.handleReopen.bind(this);
     this.handleReopenLast = this.handleReopenLast.bind(this);
+    this.handleCycleToNextStack = this.handleCycleToNextStack.bind(this);
+    this.handleCycleToPreviousStack =
+      this.handleCycleToPreviousStack.bind(this);
+    this.handleCycleToNextTab = this.handleCycleToNextTab.bind(this);
+    this.handleCycleToPreviousTab = this.handleCycleToPreviousTab.bind(this);
     this.handleDeleted = this.handleDeleted.bind(this);
     this.handleClosed = this.handleClosed.bind(this);
     this.handleControlClose = this.handleControlClose.bind(this);
@@ -103,6 +121,9 @@ class PanelManager {
     // Closed panels are stored in their dehydrated state
     this.closed = [...closed];
 
+    // Store the navigation event listener removers
+    this.navigationEventListenerRemovers = [];
+
     this.startListening();
   }
 
@@ -117,6 +138,19 @@ class PanelManager {
     eventHub.on(PanelEvent.CLOSED, this.handleClosed);
     eventHub.on(PanelEvent.CLOSE, this.handleControlClose);
     // PanelEvent.OPEN should be listened to by plugins to open a panel
+
+    this.navigationEventListenerRemovers.push(
+      listenForCycleToNextStack(eventHub, this.handleCycleToNextStack)
+    );
+    this.navigationEventListenerRemovers.push(
+      listenForCycleToPreviousStack(eventHub, this.handleCycleToPreviousStack)
+    );
+    this.navigationEventListenerRemovers.push(
+      listenForCycleToNextTab(eventHub, this.handleCycleToNextTab)
+    );
+    this.navigationEventListenerRemovers.push(
+      listenForCycleToPreviousTab(eventHub, this.handleCycleToPreviousTab)
+    );
   }
 
   stopListening(): void {
@@ -129,6 +163,9 @@ class PanelManager {
     eventHub.off(PanelEvent.DELETE, this.handleDeleted);
     eventHub.off(PanelEvent.CLOSED, this.handleClosed);
     eventHub.off(PanelEvent.CLOSE, this.handleControlClose);
+
+    this.navigationEventListenerRemovers.forEach(remover => remover());
+    this.navigationEventListenerRemovers = [];
   }
 
   getClosedPanelConfigsOfType(typeString: string): ClosedPanels {
@@ -271,6 +308,79 @@ class PanelManager {
     this.sendUpdate();
   }
 
+  cycleStack(direction: CycleDirection): void {
+    const allStacks = LayoutUtils.getAllStackContainers(this.layout);
+    if (allStacks.length <= 1) {
+      return;
+    }
+
+    const focusedIndex = LayoutUtils.getFocusedStackIndex(allStacks);
+
+    // If no stack is focused, activate the first stack's content item
+    if (focusedIndex === -1) {
+      const targetStack = allStacks[0];
+      const activeContentIndex = targetStack.config.activeItemIndex;
+      const activeContentItem =
+        activeContentIndex != null
+          ? targetStack.contentItems[activeContentIndex]
+          : targetStack.contentItems[0];
+
+      targetStack.setActiveContentItem(activeContentItem, true);
+      return;
+    }
+
+    const targetIndex =
+      direction === CycleDirection.Next
+        ? (focusedIndex + 1) % allStacks.length
+        : (focusedIndex - 1 + allStacks.length) % allStacks.length;
+    const targetStack = allStacks[targetIndex];
+
+    const activeContentIndex = targetStack.config.activeItemIndex;
+    const activeContentItem =
+      activeContentIndex != null
+        ? targetStack.contentItems[activeContentIndex]
+        : targetStack.contentItems[0];
+
+    targetStack.setActiveContentItem(activeContentItem, true);
+  }
+
+  handleCycleToNextStack(): void {
+    this.cycleStack(CycleDirection.Next);
+  }
+
+  handleCycleToPreviousStack(): void {
+    this.cycleStack(CycleDirection.Previous);
+  }
+
+  cycleTab(direction: CycleDirection): void {
+    const focusedStack = LayoutUtils.getFocusedStack(this.layout);
+    if (focusedStack === undefined) {
+      return;
+    }
+    const { contentItems } = focusedStack;
+
+    if (contentItems.length <= 1) {
+      return;
+    }
+
+    const activeItemIndex = focusedStack.config.activeItemIndex ?? 0;
+    const targetIndex =
+      direction === CycleDirection.Next
+        ? (activeItemIndex + 1) % contentItems.length
+        : (activeItemIndex - 1 + contentItems.length) % contentItems.length;
+
+    const targetContentItem = contentItems[targetIndex];
+    focusedStack.setActiveContentItem(targetContentItem, true);
+  }
+
+  handleCycleToNextTab(): void {
+    this.cycleTab(CycleDirection.Next);
+  }
+
+  handleCycleToPreviousTab(): void {
+    this.cycleTab(CycleDirection.Previous);
+  }
+
   /**
    *
    * @param panelConfig The config to hydrate and load
diff --git a/packages/dashboard/src/index.ts b/packages/dashboard/src/index.ts
@@ -20,6 +20,7 @@ export {
 } from './BasePanel';
 export * from './PanelManager';
 export * from './PanelEvent';
+export * from './NavigationEvent';
 export { default as PanelErrorBoundary } from './PanelErrorBoundary';
 export { default as PanelManager } from './PanelManager';
 export { default as TabEvent } from './TabEvent';
diff --git a/packages/dashboard/src/layout/LayoutUtils.ts b/packages/dashboard/src/layout/LayoutUtils.ts
@@ -164,6 +164,43 @@ class LayoutUtils {
     return this.addStack(newParent, !columnPreferred);
   }
 
+  /**
+   * Gets all stack containers in the layout
+   * @param layout GoldenLayout instance
+   * @returns The found stack containers
+   */
+  static getAllStackContainers(layout: GoldenLayout): Stack[] {
+    // eslint-disable-next-line no-underscore-dangle
+    return layout._findAllStackContainers();
+  }
+
+  /**
+   * Get the index of the stack that is currently focused
+   * @param allStacks All the stacks
+   * @returns The focused stack's index or -1 if not found
+   */
+  static getFocusedStackIndex(allStacks: Stack[]): number {
+    // NOTE: We target the 'lm_focusin' class because GoldenLayout automatically applies this class
+    // to tab elements when they receive focus. Until we enhance focus tracking in GoldenLayout, we
+    // will have to rely on this internal CSS class.
+    return allStacks.findIndex(stack =>
+      stack.header.tabs.some(tab =>
+        tab.element[0].classList.contains('lm_focusin')
+      )
+    );
+  }
+
+  /**
+   * Get the stack that is currently focused
+   * @param layout GoldenLayout instance
+   * @returns The focused stack or undefined if none found
+   */
+  static getFocusedStack(layout: GoldenLayout): Stack | undefined {
+    const allStacks = LayoutUtils.getAllStackContainers(layout);
+    const focusedStackIndex = LayoutUtils.getFocusedStackIndex(allStacks);
+    return allStacks[focusedStackIndex];
+  }
+
   /**
    * Gets a stack by its ID
    * @param item Golden layout content item to search for the stack
diff --git a/packages/golden-layout/src/items/Component.ts b/packages/golden-layout/src/items/Component.ts
@@ -86,9 +86,9 @@ export default class Component extends AbstractContentItem {
     AbstractContentItem.prototype._$hide.call(this);
   }
 
-  _$show() {
+  _$show(forceFocus?: boolean) {
     this.container.show();
-    if (this.container._config.isFocusOnShow) {
+    if (this.container._config.isFocusOnShow || forceFocus) {
       // focus the shown container element on show
       // preventScroll isn't supported in safari, but also doesn't matter for illumon when 100% window
       this.container._contentElement[0].focus({ preventScroll: true });
diff --git a/packages/golden-layout/src/items/Stack.ts b/packages/golden-layout/src/items/Stack.ts
