feat: make goto and fold keymaps configurable

Goto closes the agenda and opens the file at the headline
position in the previous window, like default org-agenda.

- Add configurable goto keymap (default: gf) to open file
  in previous window
- Add fold_or_action keymap (default: Tab) with configurable
  fold_item_action (default: 'preview', also supports 'goto')
- Make edit keymap configurable (default: CR)
- Guard goto against popup_mode (no previous window available)
- Extract goto_headline() as reusable function for both keymaps
- Update help menu (g?) and vimdoc with new config keys

Author: seflue

doc/org-super-agenda.txt

@@ -23,8 +23,12 @@ Press the keymap defined for a TODO state to filter by it and
 `oa` to reset the filter. Use `cs` to reschedule, `cd` to set a
 deadline, `t` to cycle TODO state, `s` to set state directly,
 and `r` to refresh the agenda from disk. Press `K` to preview
-the current headline and `q` to close the preview. Press <Tab> on
-a group header to toggle collapse/expand.
+the current headline and `q` to close the preview. Press `<CR>`
+to edit a headline in the float, `gf` to go to the selected headline —
+closes the agenda and opens the file at the headline position in the
+previous window. Press <Tab> on a group header
+to toggle collapse/expand; on an item line it runs `fold_item_action`
+(default: preview).
 
 ```
     Additional useful keys:
@@ -205,7 +209,17 @@ Group headers show item counts in this format:
 Use `<Tab>` on a group header to collapse/expand that group.
 Use `zM` to fold all groups and `zR` to unfold all groups.
 
-When cursor is on a normal item line, `<Tab>` behaves like preview (`K`).
+When cursor is on a normal item line, `<Tab>` runs the action configured
+via `fold_item_action`:
+
+    'preview'   Show item in preview popup (default)
+    'goto'      Close agenda and open file at headline in previous
+                window
+
+`gf` always goes to the headline in the previous window, regardless
+of `fold_item_action`. To match org-agenda `<Tab>` behavior, set
+`fold_item_action = 'goto'`.
+Note: `goto` is not available in |org-super-agenda-popup| mode.
 
 ==============================================================================
 FILTERS & QUERY                                               *org-super-agenda-query*
@@ -418,6 +432,9 @@ M.defaults = {
     toggle_duplicates = 'D',
     cycle_view        = 'ov',
     open_view         = 'V',
+    ['goto']          = 'gf',
+    fold_or_action    = '<Tab>',
+    edit              = '<CR>',
   },
 
   todo_states         = {
@@ -498,6 +515,7 @@ M.defaults = {
   show_filename       = true,
   heading_max_length  = 70,
   persist_hidden      = false,
+  fold_item_action    = 'preview',  -- 'preview' or 'goto'
   view_mode           = 'classic',
   classic             = { heading_order = { 'filename', 'todo', 'priority', 'headline' }, short_date_labels = false, inline_dates = true },
   compact             = { filename_min_width = 10, label_min_width = 12 },

lua/org-super-agenda/adapters/neovim/actions.lua

@@ -807,26 +807,73 @@ function A.set_keymaps(buf, win, line_map, reopen)
     vim.keymap.set('n', k, wipe, { buffer = buf, silent = true })
   end
 
-  -- open file
-  vim.keymap.set('n', '<CR>', function()
+  -- edit file in floating window (configurable keymap, default Enter)
+  if cfg.keymaps.edit and cfg.keymaps.edit ~= '' then
+    vim.keymap.set('n', cfg.keymaps.edit, function()
+      with_headline(line_map, function(cur, hl)
+        local agendabuf = vim.api.nvim_get_current_buf()
+        vim.cmd('edit ' .. vim.fn.fnameescape(hl.file.filename))
+        vim.api.nvim_win_set_cursor(0, { hl.position.start_line, 0 })
+        local filebuf = vim.api.nvim_get_current_buf()
+        pcall(vim.api.nvim_buf_delete, agendabuf, { force = true })
+
+        -- Add q/Esc keymaps to file buffer for consistent close behavior
+        local function close_file()
+          if vim.api.nvim_buf_is_valid(filebuf) then
+            pcall(vim.api.nvim_buf_delete, filebuf, { force = false })
+          end
+        end
+        for _, k in ipairs({ 'q', '<Esc>' }) do
+          vim.keymap.set('n', k, close_file, { buffer = filebuf, silent = true })
+        end
+
+        vim.api.nvim_create_autocmd('BufWinLeave', {
+          buffer = filebuf,
+          once = true,
+          callback = function()
+            vim.schedule(function()
+              pcall(vim.api.nvim_buf_delete, filebuf, { force = true })
+              reopen(cur)
+            end)
+          end,
+        })
+      end)
+    end, { buffer = buf, silent = true })
+  end
+
+  -- goto: close float and open file in previous window
+  local function goto_headline()
+    local popup = cfg.popup_mode
+    if popup and popup.enabled then
+      vim.notify('goto not available in popup mode', vim.log.levels.WARN)
+      return
+    end
+
     with_headline(line_map, function(cur, hl)
-      local agendabuf = vim.api.nvim_get_current_buf()
+      local ViewPort = require('org-super-agenda.adapters.neovim.view_float')
+      local prev_win = ViewPort.prev_win()
+
+      -- Close the floating window
+      if vim.api.nvim_win_is_valid(win) then
+        pcall(vim.api.nvim_win_close, win, true)
+      end
+      if vim.api.nvim_buf_is_valid(buf) then
+        pcall(vim.api.nvim_buf_delete, buf, { force = true })
+      end
+      require('org-super-agenda').on_close()
+
+      -- Switch to previous window and open file
+      if prev_win and vim.api.nvim_win_is_valid(prev_win) then
+        vim.api.nvim_set_current_win(prev_win)
+      end
       vim.cmd('edit ' .. vim.fn.fnameescape(hl.file.filename))
       vim.api.nvim_win_set_cursor(0, { hl.position.start_line, 0 })
-      local filebuf = vim.api.nvim_get_current_buf()
-      pcall(vim.api.nvim_buf_delete, agendabuf, { force = true })
-      vim.api.nvim_create_autocmd('BufWinLeave', {
-        buffer = filebuf,
-        once = true,
-        callback = function()
-          vim.schedule(function()
-            pcall(vim.api.nvim_buf_delete, filebuf, { force = true })
-            reopen(cur)
-          end)
-        end,
-      })
     end)
-  end, { buffer = buf, silent = true })
+  end
+
+  if cfg.keymaps['goto'] and cfg.keymaps['goto'] ~= '' then
+    vim.keymap.set('n', cfg.keymaps['goto'], goto_headline, { buffer = buf, silent = true })
+  end
 
   -- reschedule / deadline (unchanged but undo-aware)
   vim.keymap.set('n', cfg.keymaps.reschedule, function()
@@ -1097,12 +1144,21 @@ function A.set_keymaps(buf, win, line_map, reopen)
     end, { buffer = buf, silent = true })
   end
 
-  -- <Tab>: toggle group fold on group header, otherwise preview item
-  vim.keymap.set('n', '<Tab>', function()
-    if not toggle_group_on_cursor(line_map) then
+  -- fold + fallback: toggle group fold on group header, otherwise run fold_item_action
+  local fold_actions = {
+    ['goto'] = goto_headline,
+    preview = function()
       preview_headline(line_map)
-    end
-  end, { buffer = buf, silent = true })
+    end,
+  }
+  if cfg.keymaps.fold_or_action and cfg.keymaps.fold_or_action ~= '' then
+    vim.keymap.set('n', cfg.keymaps.fold_or_action, function()
+      if not toggle_group_on_cursor(line_map) then
+        local action = fold_actions[cfg.fold_item_action] or fold_actions['preview']
+        action()
+      end
+    end, { buffer = buf, silent = true })
+  end
 
   if cfg.keymaps.fold_all and cfg.keymaps.fold_all ~= '' then
     vim.keymap.set('n', cfg.keymaps.fold_all, function()

lua/org-super-agenda/adapters/neovim/utils.lua

@@ -65,9 +65,12 @@ function U.show_help()
   end
 
   vim.list_extend(lines, {
+    'Navigation:',
+    fmt(km.edit, 'Edit headline (float)'),
+    fmt(km['goto'], 'Goto headline (prev window)'),
+    fmt(km.fold_or_action, 'Fold group / ' .. (cfg.fold_item_action or 'preview') .. ' item'),
+    '',
     'Misc:',
-    fmt('<CR>', 'Open headline'),
-    fmt('<Tab>', 'Toggle fold on group header'),
     fmt(km.reload, 'Reload agenda'),
     fmt(km.clock_in, 'Clock in'),
     fmt(km.clock_out, 'Clock out'),

lua/org-super-agenda/adapters/neovim/view_float.lua

@@ -2,7 +2,7 @@
 local hi = require('org-super-agenda.adapters.neovim.highlight')
 local get_cfg = require('org-super-agenda.config').get
 
-local V = { _buf = nil, _win = nil, _line_map = {}, _ns = vim.api.nvim_create_namespace('OrgSuperAgenda') }
+local V = { _buf = nil, _win = nil, _prev_win = nil, _line_map = {}, _ns = vim.api.nvim_create_namespace('OrgSuperAgenda') }
 
 local function active_clock_status()
   local ok, org = pcall(require, 'orgmode')
@@ -27,6 +27,9 @@ end
 function V.line_map()
   return V._line_map
 end
+function V.prev_win()
+  return V._prev_win
+end
 
 local function add_hl(buf, row, col_start, col_end, entry)
   if entry.field == 'mark' then
@@ -173,6 +176,8 @@ function V.render(producer, cursor, _mode, opts)
     vim.api.nvim_win_set_buf(win, buf)
     vim.api.nvim_set_current_win(win)
   else
+    -- Store current window before creating floating window (for Tab keymap)
+    V._prev_win = vim.api.nvim_get_current_win()
     win = vim.api.nvim_open_win(buf, true, {
       relative = 'editor',
       style = 'minimal',

lua/org-super-agenda/config.lua

@@ -41,13 +41,40 @@ M.defaults = {
     bulk_reselect = 'gv',
     bulk_action = 'B',
     open_view = 'V',
+    ['goto'] = 'gf',
+    fold_or_action = '<Tab>',
+    edit = '<CR>',
   },
 
   todo_states = {
-    { name = 'TODO', keymap = 'ot', color = '#FF5555', strike_through = false, fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' } },
-    { name = 'PROGRESS', keymap = 'op', color = '#FFAA00', strike_through = false, fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' } },
-    { name = 'WAITING', keymap = 'ow', color = '#BD93F9', strike_through = false, fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' } },
-    { name = 'DONE', keymap = 'od', color = '#50FA7B', strike_through = true, fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' } },
+    {
+      name = 'TODO',
+      keymap = 'ot',
+      color = '#FF5555',
+      strike_through = false,
+      fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' },
+    },
+    {
+      name = 'PROGRESS',
+      keymap = 'op',
+      color = '#FFAA00',
+      strike_through = false,
+      fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' },
+    },
+    {
+      name = 'WAITING',
+      keymap = 'ow',
+      color = '#BD93F9',
+      strike_through = false,
+      fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' },
+    },
+    {
+      name = 'DONE',
+      keymap = 'od',
+      color = '#50FA7B',
+      strike_through = true,
+      fields = { 'filename', 'todo', 'headline', 'priority', 'date', 'tags' },
+    },
   },
 
   -- You can add per-group { sort = { by='deadline'|'scheduled'|'priority'|'todo'|'filename'|'headline'|'date_nearest', order='asc'|'desc' } }
@@ -135,8 +162,13 @@ M.defaults = {
   show_filename = true,
   heading_max_length = 70,
   persist_hidden = false,
+  fold_item_action = 'preview',
   view_mode = 'classic',
-  classic = { heading_order = { 'filename', 'todo', 'priority', 'headline' }, short_date_labels = false, inline_dates = true },
+  classic = {
+    heading_order = { 'filename', 'todo', 'priority', 'headline' },
+    short_date_labels = false,
+    inline_dates = true,
+  },
   compact = { filename_min_width = 10, label_min_width = 12 },
 
   -- Global fallback sort for groups that don't specify their own `sort`