navigate down/up with j/k (#468)

* Add Vim navigation to stack view

* Advertise Vim navigation in stack modify

* Add Vim navigation to stack checkout

* Add Vim navigation to stack switch

* Advertise Vim navigation in stack merge

Author: skarim

README.md

@@ -255,22 +255,22 @@ If the stack of PRs has been created on GitHub, run `gh stack submit` afterwards
 - **Fold down** (`d`): Absorb a branch's commits into the branch below (toward trunk). Folded branch removed from stack.
 - **Fold up** (`u`): Absorb a branch's commits into the branch above (away from trunk). Folded branch removed from stack.
 - **Insert** (`i`/`I`): Insert a new empty branch into the stack. `i` inserts below the cursor; `I` inserts above.
-- **Reorder** (`Shift+↑`/`Shift+↓`): Move a branch up (away from trunk) or down (toward trunk) in the stack.
+- **Reorder** (`Shift+↓`/`Shift+↑`): Move a branch down (toward trunk) or up (away from trunk) in the stack.
 - **Rename** (`r`): Rename a branch locally and in the stack metadata.
 - **Undo** (`z`): Undo the last staged action.
 
 **Keybindings:**
 
 | Key | Action |
 |-----|--------|
-| `↑`/`↓` | Navigate branch list |
+| `↓`/`↑` or `j`/`k` | Navigate branch list |
 | `f` | View files changed |
 | `c` | View commits |
 | `x` | Drop branch |
 | `r` | Rename branch |
 | `i/I` | Insert branch below/above |
 | `d/u` | Fold branch down/up |
-| `Shift+↑`/`Shift+↓` | Move branch up/down |
+| `Shift+↓`/`Shift+↑` | Move branch down/up |
 | `z` | Undo last action |
 | `Ctrl+S` | Apply all changes |
 | `q`/`Esc` | Cancel and exit |

cmd/switch.go

@@ -2,8 +2,10 @@ package cmd
 
 import (
 	"fmt"
+	"strings"
 
-	"github.com/cli/go-gh/v2/pkg/prompter"
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/cli/go-gh/v2/pkg/text"
 	"github.com/github/gh-stack/internal/config"
 	"github.com/github/gh-stack/internal/git"
 	"github.com/spf13/cobra"
@@ -17,11 +19,11 @@ func SwitchCmd(cfg *config.Config) *cobra.Command {
 and switch to the selected one.
 
 Branches are displayed from top (furthest from trunk) to bottom (closest to
-trunk) with their position number. Use the arrow keys to navigate and Enter
-to select.
+trunk) with their position number. Use the down/up arrow keys or j/k to
+navigate and Enter to select.
 
-To move one branch up or down without an interactive picker, use
-'gh stack up' or 'gh stack down' instead.`,
+To move one branch down or up without an interactive picker, use
+'gh stack down' or 'gh stack up' instead.`,
 		Example: `  # Open the branch picker for the current stack
   $ gh stack switch`,
 		Args: cobra.NoArgs,
@@ -61,17 +63,7 @@ func runSwitch(cfg *config.Config) error {
 		}
 	}
 
-	var selectFn func(prompt, def string, opts []string) (int, error)
-	if cfg.SelectFn != nil {
-		selectFn = cfg.SelectFn
-	} else {
-		p := prompter.New(cfg.In, cfg.Out, cfg.Err)
-		selectFn = func(prompt, def string, opts []string) (int, error) {
-			return p.Select(prompt, def, opts)
-		}
-	}
-
-	selected, err := selectFn("Select a branch in the stack to switch to:", defaultOpt, options)
+	selected, err := selectSwitchBranch(cfg, "Select a branch in the stack to switch to:", defaultOpt, options)
 	if err != nil {
 		if isInterruptError(err) {
 			clearSelectPrompt(cfg, len(options))
@@ -103,3 +95,46 @@ func runSwitch(cfg *config.Config) error {
 	cfg.Successf("Switched to %s", targetBranch)
 	return nil
 }
+
+func selectSwitchBranch(cfg *config.Config, prompt, defaultValue string, options []string) (int, error) {
+	if cfg.SelectFn != nil {
+		return cfg.SelectFn(prompt, defaultValue, options)
+	}
+
+	var selected int
+	err := survey.AskOne(
+		newSwitchSelect(prompt, defaultValue, options),
+		&selected,
+		survey.WithStdio(cfg.In, cfg.Out, cfg.Err),
+	)
+	if err != nil {
+		return 0, fmt.Errorf("could not prompt: %w", err)
+	}
+	return selected, nil
+}
+
+func newSwitchSelect(prompt, defaultValue string, options []string) *survey.Select {
+	selectPrompt := &survey.Select{
+		Message:  prompt,
+		Options:  options,
+		PageSize: selectPromptPageSize,
+		VimMode:  true,
+		Filter:   switchSelectFilter,
+	}
+	if defaultValue != "" {
+		for _, option := range options {
+			if option == defaultValue {
+				selectPrompt.Default = defaultValue
+				break
+			}
+		}
+	}
+	return selectPrompt
+}
+
+func switchSelectFilter(filter, value string, _ int) bool {
+	filter = strings.ToLower(filter)
+	value = strings.ToLower(value)
+	return strings.Contains(value, filter) ||
+		strings.Contains(text.RemoveDiacritics(value), filter)
+}

cmd/switch_test.go

@@ -271,3 +271,21 @@ func TestSwitch_CmdIntegration(t *testing.T) {
 	err := cmd.Execute()
 	assert.NoError(t, err)
 }
+
+func TestNewSwitchSelect_EnablesVimNavigation(t *testing.T) {
+	options := []string{"3. résumé", "2. b2", "1. b1"}
+	prompt := newSwitchSelect("Select a branch:", "2. b2", options)
+
+	assert.True(t, prompt.VimMode)
+	assert.Equal(t, selectPromptPageSize, prompt.PageSize)
+	assert.Equal(t, "2. b2", prompt.Default)
+	assert.Equal(t, options, prompt.Options)
+	require.NotNil(t, prompt.Filter)
+	assert.True(t, prompt.Filter("resume", options[0], 0), "filter should retain diacritic-insensitive matching")
+}
+
+func TestSwitchCmd_DescribesVimNavigation(t *testing.T) {
+	cfg, _, _ := config.NewTestConfig()
+
+	assert.Contains(t, SwitchCmd(cfg).Long, "down/up arrow keys or j/k")
+}

docs/src/content/docs/guides/modify.md

@@ -55,9 +55,9 @@ Inserts a new empty branch into the stack at the cursor position. Lowercase `i`
 
 Opens an inline prompt to enter a new name for the branch. The branch is renamed locally and in the stack metadata. On the next `submit`, the new branch name is pushed to GitHub.
 
-### Reorder (`Shift+↑`/`Shift+↓`)
+### Reorder (`Shift+↓`/`Shift+↑`)
 
-Moves the selected branch up (away from trunk) or down (toward trunk) in the stack. A cascading rebase adjusts all affected branches. Note: reordering and structural changes (drop/fold/insert/rename) cannot be mixed in the same session.
+Moves the selected branch down (toward trunk) or up (away from trunk) in the stack. A cascading rebase adjusts all affected branches. Note: reordering and structural changes (drop/fold/insert/rename) cannot be mixed in the same session.
 
 ### Undo (`z`)
 

docs/src/content/docs/guides/workflows.md

@@ -357,7 +357,7 @@ gh stack modify
 #   u     → fold up (into branch above)
 #   i     → insert below
 #   I     → insert above
-#   Shift+↑/↓ → reorder
+#   Shift+↓/↑ → reorder
 #   r     → rename
 #   z     → undo
 #   Ctrl+S → apply changes
@@ -385,7 +385,7 @@ gh stack submit
 **Reorder branches:**
 1. `gh stack modify`
 2. Navigate to the branch to move
-3. Press `Shift+↑` to move up or `Shift+↓` to move down
+3. Press `Shift+↓` to move down or `Shift+↑` to move up
 4. Press `Ctrl+S` to apply
 5. `gh stack submit`
 

internal/tui/checkoutview/model.go

@@ -35,6 +35,8 @@ func (t tab) String() string {
 type keyMap struct {
 	Up      key.Binding
 	Down    key.Binding
+	VimUp   key.Binding
+	VimDown key.Binding
 	Select  key.Binding
 	NextTab key.Binding
 	PrevTab key.Binding
@@ -45,6 +47,8 @@ type keyMap struct {
 var keys = keyMap{
 	Up:      key.NewBinding(key.WithKeys("up", "ctrl+p")),
 	Down:    key.NewBinding(key.WithKeys("down", "ctrl+n")),
+	VimUp:   key.NewBinding(key.WithKeys("k")),
+	VimDown: key.NewBinding(key.WithKeys("j")),
 	Select:  key.NewBinding(key.WithKeys("enter")),
 	NextTab: key.NewBinding(key.WithKeys("tab", "right")),
 	PrevTab: key.NewBinding(key.WithKeys("shift+tab", "left")),
@@ -111,11 +115,11 @@ func (m Model) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		m.cancelled = true
 		return m, tea.Quit
 
-	case key.Matches(msg, keys.Up):
+	case key.Matches(msg, keys.Up) || (!m.searching && key.Matches(msg, keys.VimUp)):
 		m.moveCursor(-1)
 		return m, nil
 
-	case key.Matches(msg, keys.Down):
+	case key.Matches(msg, keys.Down) || (!m.searching && key.Matches(msg, keys.VimDown)):
 		m.moveCursor(1)
 		return m, nil
 
@@ -563,13 +567,13 @@ func (m Model) renderFooter() string {
 	var pairs [][2]string
 	if m.searching {
 		pairs = [][2]string{
-			{"↑↓", "navigate"},
+			{"↓↑", "navigate"},
 			{"enter", "select"},
 			{"esc", "clear search"},
 		}
 	} else {
 		pairs = [][2]string{
-			{"↑↓", "navigate"},
+			{"↓↑/jk", "navigate"},
 			{"←→", "tabs"},
 			{"/", "search"},
 			{"enter", "select"},

internal/tui/checkoutview/model_test.go

@@ -144,13 +144,25 @@ func TestSearchMatchesMidStackBranch(t *testing.T) {
 }
 
 func TestCursorNavigationClamps(t *testing.T) {
-	m := sized(New(sampleRows()))
-	// Up at the top stays at 0.
-	m = drive(m, tea.KeyMsg{Type: tea.KeyUp})
-	assert.Equal(t, 0, m.cursor)
-	// Down past the end clamps to the last row.
-	m = drive(m, tea.KeyMsg{Type: tea.KeyDown}, tea.KeyMsg{Type: tea.KeyDown}, tea.KeyMsg{Type: tea.KeyDown})
-	assert.Equal(t, 2, m.cursor)
+	tests := []struct {
+		name string
+		up   tea.KeyMsg
+		down tea.KeyMsg
+	}{
+		{name: "arrow keys", up: tea.KeyMsg{Type: tea.KeyUp}, down: tea.KeyMsg{Type: tea.KeyDown}},
+		{name: "vim keys", up: runeKey("k"), down: runeKey("j")},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			m := sized(New(sampleRows()))
+			m = drive(m, tt.up)
+			assert.Equal(t, 0, m.cursor)
+
+			m = drive(m, tt.down, tt.down, tt.down)
+			assert.Equal(t, 2, m.cursor)
+		})
+	}
 }
 
 func TestEnterSelectsLocalRow(t *testing.T) {
@@ -210,6 +222,14 @@ func TestQTypesIntoSearchInsteadOfQuitting(t *testing.T) {
 	assert.False(t, m.Cancelled())
 }
 
+func TestVimKeysTypeIntoSearchInsteadOfNavigating(t *testing.T) {
+	m := sized(New(sampleRows()))
+	m = drive(m, runeKey("/"), runeKey("j"), runeKey("k"))
+
+	assert.True(t, m.searching)
+	assert.Equal(t, "jk", m.query)
+}
+
 func TestView_RendersColumnsAndRows(t *testing.T) {
 	m := sized(New(sampleRows()))
 	out := stripANSI(m.View())
@@ -222,6 +242,7 @@ func TestView_RendersColumnsAndRows(t *testing.T) {
 	assert.Contains(t, out, "Remote")
 	assert.Contains(t, out, "1h ago")
 	assert.Contains(t, out, "/ search")
+	assert.Contains(t, out, "↓↑/jk")
 }
 
 func TestView_SearchFooterAndPrompt(t *testing.T) {
@@ -230,6 +251,8 @@ func TestView_SearchFooterAndPrompt(t *testing.T) {
 	out := stripANSI(m.View())
 	assert.Contains(t, out, "/ a")
 	assert.Contains(t, out, "clear search")
+	assert.Contains(t, out, "↓↑ navigate")
+	assert.NotContains(t, out, "↓↑/jk")
 }
 
 func TestView_EmptyStateMessage(t *testing.T) {

internal/tui/mergeview/model_test.go

@@ -29,6 +29,8 @@ func step(m Model, msg tea.Msg) Model {
 
 func keyType(t tea.KeyType) tea.KeyMsg { return tea.KeyMsg{Type: t} }
 
+func keyRune(r rune) tea.KeyMsg { return tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{r}} }
+
 func space() tea.KeyMsg { return tea.KeyMsg{Type: tea.KeySpace} }
 
 func TestNew_DefaultsSelectAll(t *testing.T) {
@@ -124,19 +126,32 @@ func TestSelect_Viewport(t *testing.T) {
 	assert.Contains(t, view, "more")
 }
 
-func TestSelect_ArrowDirection(t *testing.T) {
-	m := New(baseOptions()) // cursor starts at the top of the stack (index 2)
-	assert.Equal(t, 2, m.cursor)
-
-	// "up" moves toward the top of the stack and is clamped there.
-	m = step(m, keyType(tea.KeyUp))
-	assert.Equal(t, 2, m.cursor)
+func TestSelect_NavigationDirection(t *testing.T) {
+	tests := []struct {
+		name string
+		up   tea.KeyMsg
+		down tea.KeyMsg
+	}{
+		{name: "arrow keys", up: keyType(tea.KeyUp), down: keyType(tea.KeyDown)},
+		{name: "vim keys", up: keyRune('k'), down: keyRune('j')},
+	}
 
-	// "down" moves toward the bottom of the stack (lower index).
-	m = step(m, keyType(tea.KeyDown))
-	assert.Equal(t, 1, m.cursor)
-	m = step(m, keyType(tea.KeyUp))
-	assert.Equal(t, 2, m.cursor)
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			m := New(baseOptions()) // cursor starts at the top of the stack (index 2)
+			assert.Equal(t, 2, m.cursor)
+
+			// Up moves toward the top of the stack and is clamped there.
+			m = step(m, tt.up)
+			assert.Equal(t, 2, m.cursor)
+
+			// Down moves toward the bottom of the stack (lower index).
+			m = step(m, tt.down)
+			assert.Equal(t, 1, m.cursor)
+			m = step(m, tt.up)
+			assert.Equal(t, 2, m.cursor)
+		})
+	}
 }
 
 func TestTruncate_WideRunes(t *testing.T) {
@@ -260,6 +275,18 @@ func TestMethod_SelectAndAdvance(t *testing.T) {
 	assert.Equal(t, "rebase", m.method)
 }
 
+func TestMethod_VimNavigation(t *testing.T) {
+	m := New(baseOptions())
+	m = step(m, keyType(tea.KeyEnter))
+	require.Equal(t, StepMethod, m.step)
+	require.Equal(t, 1, m.methodCursor)
+
+	m = step(m, keyRune('j'))
+	assert.Equal(t, 2, m.methodCursor)
+	m = step(m, keyRune('k'))
+	assert.Equal(t, 1, m.methodCursor)
+}
+
 func TestMethod_EscCancels(t *testing.T) {
 	m := New(baseOptions())
 	m = step(m, keyType(tea.KeyEnter))
@@ -392,9 +419,12 @@ func TestView_RendersBannerAndSteps(t *testing.T) {
 	assert.Contains(t, sel, "Confirm")
 	assert.Contains(t, sel, "Will merge 3 PRs into main")
 	assert.Contains(t, sel, "feat-a") // branch shown on the item's second line
+	assert.Contains(t, sel, "↓↑/jk")
 
 	m = step(m, keyType(tea.KeyTab))
-	assert.Contains(t, m.View(), "Squash and merge") // method labels, no subheading
+	method := m.View()
+	assert.Contains(t, method, "Squash and merge") // method labels, no subheading
+	assert.Contains(t, method, "↓↑/jk")
 
 	m = step(m, keyType(tea.KeyTab))
 	confirm := m.View()

internal/tui/mergeview/view.go

@@ -198,7 +198,7 @@ func (m Model) viewSelect() string {
 	}
 
 	// Reserve the indicator lines at all times (blank when nothing is hidden) so
-	// the list doesn't shift as the ↑/↓ hints appear and disappear while scrolling.
+	// the list doesn't shift as the ↓/↑ hints appear and disappear while scrolling.
 	if start > 0 {
 		b.WriteString(faintStyle.Render(fmt.Sprintf("  ↑ %d more", start)) + "\n")
 	} else {
@@ -251,7 +251,7 @@ func (m Model) viewSelect() string {
 	}
 	b.WriteString("\n\n")
 	b.WriteString(shortcuts(
-		[2]string{"↑/↓", "move"},
+		[2]string{"↓↑/jk", "move"},
 		[2]string{"space", "toggle"},
 		[2]string{"tab/enter", "next"},
 		[2]string{"esc", "cancel"},
@@ -278,7 +278,7 @@ func (m Model) viewMethod() string {
 
 	b.WriteString("\n")
 	b.WriteString(shortcuts(
-		[2]string{"↑/↓", "move"},
+		[2]string{"↓↑/jk", "move"},
 		[2]string{"tab/enter", "next"},
 		[2]string{"shift+tab", "back"},
 		[2]string{"esc", "cancel"},