feat!(selection): do not display hint immediately

Selection hint that is displayed immediately upon entering visual mode
([<leader>aa: ask, <leader>ae: edit]) gets old pretty quickly. Add a
config option to control when the hint is displayed:

  selection = {
    enabled = true,
    hint_display = "delayed",
  },

The "hint_display" option recognizes the following values:

- "immediate" results in the hint being shown immediately after entering
  visual mode. This is the old behavior.
- "delayed" causes the hint be displayed only if the cursor has not been
  moved for vim.o.updatetime milliseconds. This is the new default.
- "none" suppresses showing the hint completely.

Unfortunately "CursorHold" event is not emitted in visual mode so we
have to emulate it using Utils.debounce().

This is a breaking change because selection behavior was controller by
"hints" config entry which makes little sense, so the config section and
associated commands were renamed to "selection".

Additionally the "hints"/"selection" was mapped to "<leader>ah", but the
very same key combination was used to select from old Avante chat
histories, which overrode the toggle. New selection toggle keymap is
"<leader>aC".

README.md

@@ -452,7 +452,10 @@ _See [config.lua#L9](./lua/avante/config.lua) for the full config_
       close_from_input = nil, -- e.g., { normal = "<Esc>", insert = "<C-d>" }
     },
   },
-  hints = { enabled = true },
+  selection = {
+    enabled = true,
+    hint_display = "delayed",
+  },
   windows = {
     ---@type "right" | "left" | "top" | "bottom"
     position = "right", -- the position of the sidebar

README_zh.md

@@ -405,7 +405,10 @@ _请参见 [config.lua#L9](./lua/avante/config.lua) 以获取完整配置_
       close_from_input = nil, -- 例如，{ normal = "<Esc>", insert = "<C-d>" }
     },
   },
-  hints = { enabled = true },
+  selection = {
+    enabled = true,
+    hint_display = "delayed",
+  },
   windows = {
     ---@type "right" | "left" | "top" | "bottom"
     position = "right", -- 侧边栏的位置

lua/avante/config.lua

@@ -528,7 +528,7 @@ M._defaults = {
     toggle = {
       default = "<leader>at",
       debug = "<leader>ad",
-      hint = "<leader>ah",
+      selection = "<leader>aC",
       suggestion = "<leader>as",
       repomap = "<leader>aR",
     },
@@ -645,9 +645,14 @@ M._defaults = {
     --- Disable by setting to -1.
     override_timeoutlen = 500,
   },
-  --- @class AvanteHintsConfig
+  --- Allows selecting code or other data in a buffer and ask LLM questions about it or
-  hints = {
+  --- to perform edits/transformations.
+  --- @class AvanteSelectionConfig
+  --- @field enabled boolean
+  --- @field hint_display "delayed" | "immediate" | "none" When to show key map hints.
+  selection = {
     enabled = true,
+    hint_display = "delayed",
   },
   --- @class AvanteRepoMapConfig
   repo_map = {

lua/avante/init.lua

@@ -75,7 +75,7 @@ function H.keymaps()
   vim.keymap.set("n", "<Plug>(AvanteBuild)", function() require("avante.api").build() end, { noremap = true })
   vim.keymap.set("n", "<Plug>(AvanteToggle)", function() M.toggle() end, { noremap = true })
   vim.keymap.set("n", "<Plug>(AvanteToggleDebug)", function() M.toggle.debug() end)
-  vim.keymap.set("n", "<Plug>(AvanteToggleHint)", function() M.toggle.hint() end)
+  vim.keymap.set("n", "<Plug>(AvanteToggleSelection)", function() M.toggle.selection() end)
   vim.keymap.set("n", "<Plug>(AvanteToggleSuggestion)", function() M.toggle.suggestion() end)
 
   vim.keymap.set({ "n", "v" }, "<Plug>(AvanteConflictOurs)", function() Diff.choose("ours") end)
@@ -134,9 +134,9 @@ function H.keymaps()
     )
     Utils.safe_keymap_set(
       "n",
-      Config.mappings.toggle.hint,
+      Config.mappings.toggle.selection,
       function() M.toggle.hint() end,
-      { desc = "avante: toggle hint" }
+      { desc = "avante: toggle selection" }
     )
     Utils.safe_keymap_set(
       "n",
@@ -230,7 +230,7 @@ function H.autocmds()
     callback = function(ev)
       local tab = tonumber(ev.file)
       M._init(tab or api.nvim_get_current_tabpage())
-      if Config.hints.enabled and not M.current.selection.did_setup then M.current.selection:setup_autocmds() end
+      if Config.selection.enabled and not M.current.selection.did_setup then M.current.selection:setup_autocmds() end
     end,
   })
 
@@ -287,7 +287,7 @@ function H.autocmds()
 
   vim.schedule(function()
     M._init(api.nvim_get_current_tabpage())
-    if Config.hints.enabled then M.current.selection:setup_autocmds() end
+    if Config.selection.enabled then M.current.selection:setup_autocmds() end
   end)
 
   local function setup_colors()
@@ -405,10 +405,10 @@ M.toggle.debug = H.api(Utils.toggle_wrap({
   set = function(state) Config.override({ debug = state }) end,
 }))
 
-M.toggle.hint = H.api(Utils.toggle_wrap({
+M.toggle.selection = H.api(Utils.toggle_wrap({
-  name = "hint",
+  name = "selection",
-  get = function() return Config.hints.enabled end,
+  get = function() return Config.selection.enabled end,
-  set = function(state) Config.override({ hints = { enabled = state } }) end,
+  set = function(state) Config.override({ selection = { enabled = state } }) end,
 }))
 
 M.toggle.suggestion = H.api(Utils.toggle_wrap({

lua/avante/selection.lua

@@ -19,6 +19,7 @@ local PRIORITY = (vim.hl or vim.highlight).priorities.user
 ---@field selection avante.SelectionResult | nil
 ---@field cursor_pos table | nil
 ---@field shortcuts_extmark_id integer | nil
+---@field shortcuts_hint_timer? uv.uv_timer_t
 ---@field selected_code_extmark_id integer | nil
 ---@field augroup integer | nil
 ---@field visual_mode_augroup integer | nil
@@ -308,16 +309,34 @@ end
 ---Show the hints virtual line and set up autocommands to update it or stop showing it when exiting visual mode
 ---@param bufnr integer
 function Selection:on_entering_visual_mode(bufnr)
+  if Config.selection.hint_display == "none" then return end
   if vim.bo[bufnr].buftype == "terminal" or Utils.is_sidebar_buffer(bufnr) then return end
 
   self:show_shortcuts_hints_popup()
 
   self.visual_mode_augroup = api.nvim_create_augroup("avante_selection_visual_" .. self.id, { clear = true })
+  if Config.selection.hint_display == "delayed" then
+    local deferred_show_shortcut_hints_popup = Utils.debounce(function()
+      self:show_shortcuts_hints_popup()
+      self.shortcuts_hint_timer = nil
+    end, vim.o.updatetime)
+
+    api.nvim_create_autocmd({ "CursorMoved" }, {
+      group = self.visual_mode_augroup,
+      buffer = bufnr,
+      callback = function()
+        self:close_shortcuts_hints_popup()
+        self.shortcuts_hint_timer = deferred_show_shortcut_hints_popup()
+      end,
+    })
+  else
+    self:show_shortcuts_hints_popup()
     api.nvim_create_autocmd({ "CursorMoved" }, {
       group = self.visual_mode_augroup,
       buffer = bufnr,
       callback = function() self:show_shortcuts_hints_popup() end,
     })
+  end
   api.nvim_create_autocmd({ "ModeChanged" }, {
     group = self.visual_mode_augroup,
     buffer = bufnr,
@@ -337,6 +356,12 @@ end
 function Selection:on_exiting_visual_mode()
   self:close_shortcuts_hints_popup()
 
+  if self.shortcuts_hint_timer then
+    self.shortcuts_hint_timer:stop()
+    self.shortcuts_hint_timer:close()
+    self.shortcuts_hint_timer = nil
+  end
+
   api.nvim_del_augroup_by_id(self.visual_mode_augroup)
   self.visual_mode_augroup = nil
 end