feat(ui): navigate stack view cursor by stack items

Author: mhiro2

README.md

@@ -130,6 +130,8 @@ Defaults in stack view:
 - `r` — rename
 - `p` — pin
 - `/` — filter
+- `gg/G` — jump to first/last stack item
+- `j/k` — move cursor by stack item (skip header/preview lines)
 - `J/K` — move item down/up
 - `?` — help
 - `q` — close

doc/peekstack.txt

@@ -381,6 +381,8 @@ Stack view keymaps:
     `r`           Rename the selected popup
     `p`           Toggle pin (skip auto-close)
     `/`           Filter the list
+    `gg/G`        Jump to first/last stack item
+    `j/k`         Move cursor by stack item (skip header/preview lines)
     `J/K`         Move the selected item down/up
     `?`           Toggle help
     `q`           Close the stack view

lua/peekstack/ui/stack_view.lua

@@ -598,10 +598,14 @@ local function render(s)
   end
   apply_preview_treesitter_highlights(s.bufnr, preview_lines)
 
-  if s.winid and vim.api.nvim_win_is_valid(s.winid) and #visible > 0 then
-    local cursor = vim.api.nvim_win_get_cursor(s.winid)[1]
-    if cursor <= s.header_lines then
-      vim.api.nvim_win_set_cursor(s.winid, { s.header_lines + 1, 0 })
+  if s.winid and vim.api.nvim_win_is_valid(s.winid) and s.bufnr and vim.api.nvim_buf_is_valid(s.bufnr) then
+    local line_count = vim.api.nvim_buf_line_count(s.bufnr)
+    if line_count > s.header_lines then
+      local min_line = s.header_lines + 1
+      local cursor = vim.api.nvim_win_get_cursor(s.winid)[1]
+      if cursor < min_line then
+        vim.api.nvim_win_set_cursor(s.winid, { min_line, 0 })
+      end
     end
   end
 end
@@ -623,6 +627,88 @@ local function move_cursor_to_id(s, id)
   end
 end
 
+---@param s table
+---@return integer[]
+local function entry_lines(s)
+  local id_to_line = {}
+  for line, id in pairs(s.line_to_id or {}) do
+    if line > (s.header_lines or 0) and (not id_to_line[id] or line < id_to_line[id]) then
+      id_to_line[id] = line
+    end
+  end
+  local lines = {}
+  for _, line in pairs(id_to_line) do
+    table.insert(lines, line)
+  end
+  table.sort(lines)
+  return lines
+end
+
+---@param s table
+local function ensure_non_header_cursor(s)
+  if not (s.winid and vim.api.nvim_win_is_valid(s.winid) and s.bufnr and vim.api.nvim_buf_is_valid(s.bufnr)) then
+    return
+  end
+  local line_count = vim.api.nvim_buf_line_count(s.bufnr)
+  if line_count <= 0 then
+    return
+  end
+  local min_line = math.min((s.header_lines or 0) + 1, line_count)
+  local cursor = vim.api.nvim_win_get_cursor(s.winid)[1]
+  if cursor < min_line then
+    vim.api.nvim_win_set_cursor(s.winid, { min_line, 0 })
+  end
+end
+
+---@param s table
+---@param step integer
+local function move_cursor_by_stack_item(s, step)
+  if not (s.winid and vim.api.nvim_win_is_valid(s.winid)) then
+    return
+  end
+  local lines = entry_lines(s)
+  if #lines == 0 then
+    ensure_non_header_cursor(s)
+    return
+  end
+
+  local cursor_line = vim.api.nvim_win_get_cursor(s.winid)[1]
+  if cursor_line <= (s.header_lines or 0) then
+    vim.api.nvim_win_set_cursor(s.winid, { lines[1], 0 })
+    return
+  end
+
+  local current_id = s.line_to_id[cursor_line]
+  local base_line = cursor_line
+  if current_id then
+    for line, id in pairs(s.line_to_id) do
+      if id == current_id and line < base_line then
+        base_line = line
+      end
+    end
+  end
+
+  local target_line = base_line
+  if step > 0 then
+    for _, line in ipairs(lines) do
+      if line > base_line then
+        target_line = line
+        break
+      end
+    end
+  else
+    for idx = #lines, 1, -1 do
+      local line = lines[idx]
+      if line < base_line then
+        target_line = line
+        break
+      end
+    end
+  end
+
+  vim.api.nvim_win_set_cursor(s.winid, { target_line, 0 })
+end
+
 ---@param s table
 local function toggle_help(s)
   if s.help_winid and vim.api.nvim_win_is_valid(s.help_winid) then
@@ -641,6 +727,8 @@ local function toggle_help(s)
     "r     Rename selected popup",
     "p     Toggle pin (skip auto-close)",
     "/     Filter list",
+    "gg/G  Jump to first/last stack item",
+    "j/k   Move cursor by stack item",
     "J/K   Move item down/up",
     "q     Close stack view",
     "?     Toggle this help",
@@ -798,6 +886,38 @@ local function apply_keymaps(s)
     end)
   end, { buffer = s.bufnr, nowait = true, silent = true })
 
+  vim.keymap.set("n", "gg", function()
+    local lines = entry_lines(s)
+    if #lines == 0 then
+      ensure_non_header_cursor(s)
+      return
+    end
+    vim.api.nvim_win_set_cursor(s.winid, { lines[1], 0 })
+  end, { buffer = s.bufnr, nowait = true, silent = true })
+
+  vim.keymap.set("n", "G", function()
+    local lines = entry_lines(s)
+    if #lines == 0 then
+      ensure_non_header_cursor(s)
+      return
+    end
+    vim.api.nvim_win_set_cursor(s.winid, { lines[#lines], 0 })
+  end, { buffer = s.bufnr, nowait = true, silent = true })
+
+  vim.keymap.set("n", "j", function()
+    local count = vim.v.count1
+    for _ = 1, count do
+      move_cursor_by_stack_item(s, 1)
+    end
+  end, { buffer = s.bufnr, nowait = true, silent = true })
+
+  vim.keymap.set("n", "k", function()
+    local count = vim.v.count1
+    for _ = 1, count do
+      move_cursor_by_stack_item(s, -1)
+    end
+  end, { buffer = s.bufnr, nowait = true, silent = true })
+
   vim.keymap.set("n", "J", function()
     local line = vim.api.nvim_win_get_cursor(s.winid)[1]
     local id = s.line_to_id[line]
@@ -994,6 +1114,13 @@ function M.open()
       end)
     end,
   })
+  vim.api.nvim_create_autocmd("CursorMoved", {
+    group = au_group,
+    buffer = s.bufnr,
+    callback = function()
+      ensure_non_header_cursor(s)
+    end,
+  })
 
   apply_keymaps(s)
   render(s)

tests/stack_view_spec.lua

@@ -164,6 +164,112 @@ describe("peekstack.ui.stack_view", function()
     assert.is_true(found, "H keymap should be bound in stack view")
   end)
 
+  it("moves cursor by stack item with j/k", function()
+    local tmpfile1 = vim.fn.tempname() .. ".lua"
+    local tmpfile2 = vim.fn.tempname() .. ".lua"
+    vim.fn.writefile({ "local first = 1" }, tmpfile1)
+    vim.fn.writefile({ "local second = 2" }, tmpfile2)
+
+    local loc1 = helpers.make_location({
+      uri = vim.uri_from_fname(tmpfile1),
+      range = { start = { line = 0, character = 0 }, ["end"] = { line = 0, character = 0 } },
+    })
+    local loc2 = helpers.make_location({
+      uri = vim.uri_from_fname(tmpfile2),
+      range = { start = { line = 0, character = 0 }, ["end"] = { line = 0, character = 0 } },
+    })
+
+    local m1 = stack.push(loc1)
+    local m2 = stack.push(loc2)
+    assert.is_not_nil(m1)
+    assert.is_not_nil(m2)
+
+    stack_view.open()
+    local state = stack_view._get_state()
+    stack_view._render(state)
+    vim.api.nvim_set_current_win(state.winid)
+
+    local min_by_id = {}
+    local max_by_id = {}
+    for line, id in pairs(state.line_to_id) do
+      if not min_by_id[id] or line < min_by_id[id] then
+        min_by_id[id] = line
+      end
+      if not max_by_id[id] or line > max_by_id[id] then
+        max_by_id[id] = line
+      end
+    end
+
+    assert.is_not_nil(min_by_id[m1.id])
+    assert.is_not_nil(min_by_id[m2.id])
+    assert.is_not_nil(max_by_id[m2.id])
+
+    local entry_lines = { min_by_id[m1.id], min_by_id[m2.id] }
+    table.sort(entry_lines)
+    local last_entry_line = entry_lines[#entry_lines]
+    local prev_entry_line = entry_lines[#entry_lines - 1]
+    assert.is_not_nil(prev_entry_line)
+
+    local start_id = nil
+    if min_by_id[m1.id] == last_entry_line then
+      start_id = m1.id
+    else
+      start_id = m2.id
+    end
+    assert.is_not_nil(start_id)
+    assert.is_true(max_by_id[start_id] >= last_entry_line)
+
+    vim.api.nvim_win_set_cursor(state.winid, { max_by_id[start_id], 0 })
+    vim.api.nvim_feedkeys("k", "mx", false)
+    vim.wait(50, function()
+      return vim.api.nvim_win_get_cursor(state.winid)[1] == prev_entry_line
+    end)
+    assert.equals(prev_entry_line, vim.api.nvim_win_get_cursor(state.winid)[1])
+
+    vim.api.nvim_feedkeys("j", "mx", false)
+    vim.wait(50, function()
+      return vim.api.nvim_win_get_cursor(state.winid)[1] == last_entry_line
+    end)
+    assert.equals(last_entry_line, vim.api.nvim_win_get_cursor(state.winid)[1])
+
+    vim.fn.delete(tmpfile1)
+    vim.fn.delete(tmpfile2)
+  end)
+
+  it("does not allow cursor on stack header line", function()
+    local tmpfile = vim.fn.tempname() .. ".lua"
+    vim.fn.writefile({ "local header_guard = true" }, tmpfile)
+
+    local loc = helpers.make_location({
+      uri = vim.uri_from_fname(tmpfile),
+      range = { start = { line = 0, character = 0 }, ["end"] = { line = 0, character = 0 } },
+    })
+    local model = stack.push(loc)
+    assert.is_not_nil(model)
+
+    stack_view.open()
+    local state = stack_view._get_state()
+    stack_view._render(state)
+    vim.api.nvim_set_current_win(state.winid)
+
+    vim.api.nvim_feedkeys("gg", "mx", false)
+    vim.wait(50, function()
+      return vim.api.nvim_win_get_cursor(state.winid)[1] > state.header_lines
+    end)
+    assert.is_true(vim.api.nvim_win_get_cursor(state.winid)[1] > state.header_lines)
+
+    local first_entry_line = nil
+    for line, _ in pairs(state.line_to_id) do
+      if line > state.header_lines and (not first_entry_line or line < first_entry_line) then
+        first_entry_line = line
+      end
+    end
+    assert.is_not_nil(first_entry_line)
+    assert.equals(first_entry_line, vim.api.nvim_win_get_cursor(state.winid)[1])
+
+    vim.fn.delete(tmpfile)
+  end)
+
   it("does not error when render is called after close", function()
     stack_view.open()
     local state = stack_view._get_state()