refactor(cli): keyboard handling and AskUserDialog (#17414)

packages/cli/src/ui/hooks/useKeypress.ts

@@ -16,10 +16,11 @@ export type { Key };
  * @param onKeypress - The callback function to execute on each keypress.
  * @param options - Options to control the hook's behavior.
  * @param options.isActive - Whether the hook should be actively listening for input.
+ * @param options.priority - Whether the hook should have priority over normal subscribers.
  */
 export function useKeypress(
   onKeypress: KeypressHandler,
-  { isActive }: { isActive: boolean },
+  { isActive, priority }: { isActive: boolean; priority?: boolean },
 ) {
   const { subscribe, unsubscribe } = useKeypressContext();
 
@@ -28,9 +29,9 @@ export function useKeypress(
       return;
     }
 
-    subscribe(onKeypress);
+    subscribe(onKeypress, priority);
     return () => {
       unsubscribe(onKeypress);
     };
-  }, [isActive, onKeypress, subscribe, unsubscribe]);
+  }, [isActive, onKeypress, subscribe, unsubscribe, priority]);
 }

packages/cli/src/ui/hooks/useSelectionList.ts

@@ -30,6 +30,7 @@ export interface UseSelectionListOptions<T> {
   showNumbers?: boolean;
   wrapAround?: boolean;
   focusKey?: string;
+  priority?: boolean;
 }
 
 export interface UseSelectionListResult {
@@ -288,6 +289,7 @@ export function useSelectionList<T>({
   showNumbers = false,
   wrapAround = true,
   focusKey,
+  priority,
 }: UseSelectionListOptions<T>): UseSelectionListResult {
   const baseItems = toBaseItems(items);
 
@@ -397,17 +399,17 @@ export function useSelectionList<T>({
 
       if (keyMatchers[Command.DIALOG_NAVIGATION_UP](key)) {
         dispatch({ type: 'MOVE_UP' });
-        return;
+        return true;
       }
 
       if (keyMatchers[Command.DIALOG_NAVIGATION_DOWN](key)) {
         dispatch({ type: 'MOVE_DOWN' });
-        return;
+        return true;
       }
 
       if (keyMatchers[Command.RETURN](key)) {
         dispatch({ type: 'SELECT_CURRENT' });
-        return;
+        return true;
       }
 
       // Handle numeric input for quick selection
@@ -426,7 +428,7 @@ export function useSelectionList<T>({
           numberInputTimer.current = setTimeout(() => {
             numberInputRef.current = '';
           }, NUMBER_INPUT_TIMEOUT_MS);
-          return;
+          return true;
         }
 
         if (targetIndex >= 0 && targetIndex < itemsLength) {
@@ -455,12 +457,17 @@ export function useSelectionList<T>({
           // Number is out of bounds
           numberInputRef.current = '';
         }
+        return true;
       }
+      return false;
     },
     [dispatch, itemsLength, showNumbers],
   );
 
-  useKeypress(handleKeypress, { isActive: !!(isFocused && itemsLength > 0) });
+  useKeypress(handleKeypress, {
+    isActive: !!(isFocused && itemsLength > 0),
+    priority,
+  });
 
   const setActiveIndex = (index: number) => {
     dispatch({

packages/cli/src/ui/hooks/useTabbedNavigation.test.ts

@@ -4,29 +4,128 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { act } from 'react';
 import { renderHook } from '../../test-utils/render.js';
 import { useTabbedNavigation } from './useTabbedNavigation.js';
+import { useKeypress } from './useKeypress.js';
+import type { Key, KeypressHandler } from '../contexts/KeypressContext.js';
 
 vi.mock('./useKeypress.js', () => ({
   useKeypress: vi.fn(),
 }));
 
+const createKey = (partial: Partial<Key>): Key => ({
+  name: partial.name || '',
+  sequence: partial.sequence || '',
+  shift: partial.shift || false,
+  alt: partial.alt || false,
+  ctrl: partial.ctrl || false,
+  cmd: partial.cmd || false,
+  insertable: partial.insertable || false,
+  ...partial,
+});
+
 vi.mock('../keyMatchers.js', () => ({
   keyMatchers: {
     'cursor.left': vi.fn((key) => key.name === 'left'),
     'cursor.right': vi.fn((key) => key.name === 'right'),
+    'dialog.next': vi.fn((key) => key.name === 'tab' && !key.shift),
+    'dialog.previous': vi.fn((key) => key.name === 'tab' && key.shift),
   },
   Command: {
     MOVE_LEFT: 'cursor.left',
     MOVE_RIGHT: 'cursor.right',
+    DIALOG_NEXT: 'dialog.next',
+    DIALOG_PREV: 'dialog.previous',
   },
 }));
 
 describe('useTabbedNavigation', () => {
+  let capturedHandler: KeypressHandler;
+
   beforeEach(() => {
-    vi.clearAllMocks();
+    vi.mocked(useKeypress).mockImplementation((handler) => {
+      capturedHandler = handler;
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('keyboard navigation', () => {
+    it('moves to next tab on Right arrow', () => {
+      const { result } = renderHook(() =>
+        useTabbedNavigation({ tabCount: 3, enableArrowNavigation: true }),
+      );
+
+      act(() => {
+        capturedHandler(createKey({ name: 'right' }));
+      });
+
+      expect(result.current.currentIndex).toBe(1);
+    });
+
+    it('moves to previous tab on Left arrow', () => {
+      const { result } = renderHook(() =>
+        useTabbedNavigation({
+          tabCount: 3,
+          initialIndex: 1,
+          enableArrowNavigation: true,
+        }),
+      );
+
+      act(() => {
+        capturedHandler(createKey({ name: 'left' }));
+      });
+
+      expect(result.current.currentIndex).toBe(0);
+    });
+
+    it('moves to next tab on Tab key', () => {
+      const { result } = renderHook(() =>
+        useTabbedNavigation({ tabCount: 3, enableTabKey: true }),
+      );
+
+      act(() => {
+        capturedHandler(createKey({ name: 'tab', shift: false }));
+      });
+
+      expect(result.current.currentIndex).toBe(1);
+    });
+
+    it('moves to previous tab on Shift+Tab key', () => {
+      const { result } = renderHook(() =>
+        useTabbedNavigation({
+          tabCount: 3,
+          initialIndex: 1,
+          enableTabKey: true,
+        }),
+      );
+
+      act(() => {
+        capturedHandler(createKey({ name: 'tab', shift: true }));
+      });
+
+      expect(result.current.currentIndex).toBe(0);
+    });
+
+    it('does not navigate when isNavigationBlocked returns true', () => {
+      const { result } = renderHook(() =>
+        useTabbedNavigation({
+          tabCount: 3,
+          enableArrowNavigation: true,
+          isNavigationBlocked: () => true,
+        }),
+      );
+
+      act(() => {
+        capturedHandler(createKey({ name: 'right' }));
+      });
+
+      expect(result.current.currentIndex).toBe(0);
+    });
   });
 
   describe('initialization', () => {

packages/cli/src/ui/hooks/useTabbedNavigation.ts

@@ -214,8 +214,15 @@ export function useTabbedNavigation({
         }
       }
 
-      if (enableTabKey && key.name === 'tab' && !key.shift) {
-        goToNextTab();
+      if (enableTabKey) {
+        if (keyMatchers[Command.DIALOG_NEXT](key)) {
+          goToNextTab();
+          return;
+        }
+        if (keyMatchers[Command.DIALOG_PREV](key)) {
+          goToPrevTab();
+          return;
+        }
       }
     },
     [