feat: add wrap_around option for cursor navigation (#452)

* feat: add wrap_around option for cursor navigation

When enabled (wrap_around = true), the cursor wraps to the opposite end
when reaching the first or last item in the results list, instead of
stopping at the boundary.

This applies to:
- move_up/move_down in insert mode (C-k/C-j, Up/Down, Tab/S-Tab, etc.)
- j/k navigation in normal mode (list buffer)
- Both top and bottom prompt positions

The option defaults to false to preserve existing behavior.
Pagination still takes priority: wrapping only occurs when there are
no more pages to load in the current direction.

* fix: wrap_around takes priority over pagination

When wrap_around is enabled, cursor wraps within the current page
instead of loading the next/previous page. This gives the expected
cycling behavior where Tab at the top jumps to the bottom and
S-Tab at the bottom jumps to the top.

* fix: wrap only at global boundaries, paginate on intermediate pages

Pagination now takes priority over wrap_around on non-boundary pages.
Wrapping only occurs at the true global edges:
- First item on first page → wraps to last item on last page
- Last item on last page → wraps to first item on first page

On all other page boundaries, normal pagination continues as expected.

* fix: stylua formatting and remove wrap_around from FffKeymapsConfig type

- Collapse multi-line callbacks to single-line (stylua)
- Remove wrap_around from FffKeymapsConfig type annotation (belongs only on FffConfig)

Author: RielJ

lua/fff/conf.lua

@@ -74,6 +74,7 @@ local M = {}
 --- @field git table
 --- @field debug table
 --- @field logging table
+--- @field wrap_around boolean
 --- @field file_picker table
 --- @field grep FffGrepConfig
 
@@ -199,6 +200,7 @@ local function init()
     max_threads = 4,
     lazy_sync = true, -- set to false if you want file indexing to start on open
     prompt_vim_mode = false, -- set to true to enable vim-mode in the prompt: <Esc> leaves insert for normal mode bindings (also allows <leader>p or <leader>l to jump around) the second <Esc> closes the picker
+    wrap_around = false, -- set to true to wrap cursor to the opposite end when reaching the first/last item
     layout = {
       height = 0.8,
       width = 0.8,

lua/fff/picker_ui.lua

@@ -913,8 +913,18 @@ local function move_list_cursor(direction)
   local items = M.state.filtered_items
   if #items == 0 then return end
 
+  local wrap_around = M.state.config and M.state.config.wrap_around or false
   local new_cursor = M.state.cursor + direction
-  new_cursor = math.max(1, math.min(new_cursor, #items))
+
+  if wrap_around then
+    if new_cursor < 1 then
+      new_cursor = #items
+    elseif new_cursor > #items then
+      new_cursor = 1
+    end
+  else
+    new_cursor = math.max(1, math.min(new_cursor, #items))
+  end
 
   if new_cursor ~= M.state.cursor then
     M.state.cursor = new_cursor
@@ -2048,12 +2058,60 @@ function M.update_status(progress)
   })
 end
 
+--- Wrap cursor to the first page, first item (best result)
+function M.wrap_to_first()
+  if M.state.pagination.page_index == 0 then
+    -- Already on first page, just move cursor
+    M.state.cursor = 1
+    return true
+  end
+
+  -- For non-grep mode, jump directly to page 0
+  if M.state.mode ~= 'grep' then
+    return M.load_page_at_index(0, function() M.state.cursor = 1 end)
+  end
+
+  -- For grep mode, we can only go back if page 0 offset is recorded
+  if M.state.pagination.grep_file_offsets[1] ~= nil then
+    return M.load_page_at_index(0, function() M.state.cursor = 1 end)
+  end
+
+  M.state.cursor = 1
+  return true
+end
+
+--- Wrap cursor to the last page, last item (worst result)
+function M.wrap_to_last()
+  local page_size = M.state.pagination.page_size
+  if page_size == 0 then return false end
+
+  if M.state.mode ~= 'grep' then
+    local total = M.state.pagination.total_matched
+    if total == 0 then return false end
+    local max_page_index = math.max(0, math.ceil(total / page_size) - 1)
+
+    if M.state.pagination.page_index == max_page_index then
+      -- Already on last page, just move cursor to last item
+      M.state.cursor = #M.state.filtered_items
+      return true
+    end
+
+    return M.load_page_at_index(max_page_index, function(result_count) M.state.cursor = result_count end)
+  end
+
+  -- For grep mode, we can't jump to last page (sequential offsets required)
+  -- Just wrap within current page
+  M.state.cursor = #M.state.filtered_items
+  return true
+end
+
 function M.move_up()
   if not M.state.active then return end
   if #M.state.filtered_items == 0 then return end
 
   local prompt_position = get_prompt_position()
   local items_count = #M.state.filtered_items
+  local wrap_around = M.state.config and M.state.config.wrap_around or false
 
   -- Pagination logic depends on prompt position
   if prompt_position == 'bottom' then
@@ -2064,32 +2122,41 @@ function M.move_up()
 
     if near_bottom and at_last_item then
       local page_size = M.state.pagination.page_size
+      local has_more = false
       if page_size > 0 then
-        local has_more
         if M.state.mode == 'grep' then
           has_more = M.state.pagination.grep_next_file_offset > 0
         else
           local max_page = math.max(0, math.ceil(M.state.pagination.total_matched / page_size) - 1)
           has_more = M.state.pagination.page_index < max_page
         end
-        if has_more then
-          M.load_next_page()
-          return
-        end
       end
-    end
 
-    M.state.cursor = math.min(M.state.cursor + 1, items_count)
+      if has_more then
+        -- More pages available: paginate normally
+        M.load_next_page()
+        return
+      elseif wrap_around then
+        -- At global end (last item on last page): wrap to first
+        M.wrap_to_first()
+      end
+    else
+      M.state.cursor = math.min(M.state.cursor + 1, items_count)
+    end
   else
     -- Top prompt: scrolling UP means going to BETTER results (previous page)
     if M.state.cursor <= M.state.pagination.prefetch_margin + 1 and M.state.cursor <= 1 then
       if M.state.pagination.page_index > 0 then
+        -- More pages available: paginate normally
         vim.schedule(M.load_previous_page)
         return
+      elseif wrap_around then
+        -- At global start (first item on first page): wrap to last
+        M.wrap_to_last()
       end
+    else
+      M.state.cursor = math.max(M.state.cursor - 1, 1)
     end
-
-    M.state.cursor = math.max(M.state.cursor - 1, 1)
   end
 
   M.render_list()
@@ -2119,42 +2186,52 @@ function M.move_down()
 
   local prompt_position = get_prompt_position()
   local items_count = #M.state.filtered_items
+  local wrap_around = M.state.config and M.state.config.wrap_around or false
 
   -- Pagination logic depends on prompt position
   if prompt_position == 'bottom' then
     -- Bottom prompt with reverse rendering: visually moving DOWN means cursor DECREASES
     -- because lower index items (better) are rendered at higher line numbers
     if M.state.cursor <= M.state.pagination.prefetch_margin + 1 and M.state.cursor <= 1 then
       if M.state.pagination.page_index > 0 then
+        -- More pages available: paginate normally
         vim.schedule(M.load_previous_page)
         return
+      elseif wrap_around then
+        -- At global start (first item on first page): wrap to last
+        M.wrap_to_last()
       end
+    else
+      M.state.cursor = math.max(M.state.cursor - 1, 1)
     end
-
-    M.state.cursor = math.max(M.state.cursor - 1, 1)
   else
     -- Top prompt: scrolling DOWN means going to WORSE results (next page)
     local near_bottom = M.state.cursor >= (items_count - M.state.pagination.prefetch_margin)
     local at_last_item = M.state.cursor >= items_count
 
     if near_bottom and at_last_item then
       local page_size = M.state.pagination.page_size
+      local has_more = false
       if page_size > 0 then
-        local has_more
         if M.state.mode == 'grep' then
           has_more = M.state.pagination.grep_next_file_offset > 0
         else
           local max_page = math.max(0, math.ceil(M.state.pagination.total_matched / page_size) - 1)
           has_more = M.state.pagination.page_index < max_page
         end
-        if has_more then
-          M.load_next_page()
-          return
-        end
       end
-    end
 
-    M.state.cursor = math.min(M.state.cursor + 1, items_count)
+      if has_more then
+        -- More pages available: paginate normally
+        M.load_next_page()
+        return
+      elseif wrap_around then
+        -- At global end (last item on last page): wrap to first
+        M.wrap_to_first()
+      end
+    else
+      M.state.cursor = math.min(M.state.cursor + 1, items_count)
+    end
   end
 
   M.render_list()