feat(api): add nvim__redraw for more granular redrawing

Experimental and subject to future changes.
Add a way to redraw certain elements that are not redrawn while Nvim is waiting
for input, or currently have no API to do so. This API covers all that can be
done with the :redraw* commands, in addition to the following new features:
- Immediately move the cursor to a (non-current) window.
- Target a specific window or buffer to mark for redraw.
- Mark a buffer range for redraw (replaces nvim__buf_redraw_range()).
- Redraw the 'statuscolumn'.

5 files changed, 44 insertions, 12 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index d799446647..64c67be076 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -14,12 +14,6 @@ function vim.api.nvim__buf_debug_extmarks(buffer, keys, dot) end
 
 --- @private
 --- @param buffer integer
---- @param first integer
---- @param last integer
-function vim.api.nvim__buf_redraw_range(buffer, first, last) end
-
---- @private
---- @param buffer integer
 --- @return table<string,any>
 function vim.api.nvim__buf_stats(buffer) end
 
@@ -106,6 +100,32 @@ function vim.api.nvim__inspect_cell(grid, row, col) end
 function vim.api.nvim__invalidate_glyph_cache() end
 
 --- @private
+--- EXPERIMENTAL: this API may change in the future.
+---
+--- Instruct Nvim to redraw various components.
+---
+--- @param opts vim.api.keyset.redraw Optional parameters.
+---             • win: Target a specific `window-ID` as described below.
+---             • buf: Target a specific buffer number as described below.
+---             • flush: Update the screen with pending updates.
+---             • valid: When present mark `win`, `buf`, or all windows for
+---               redraw. When `true`, only redraw changed lines (useful for
+---               decoration providers). When `false`, forcefully redraw.
+---             • range: Redraw a range in `buf`, the buffer in `win` or the
+---               current buffer (useful for decoration providers). Expects a
+---               tuple `[first, last]` with the first and last line number of
+---               the range, 0-based end-exclusive `api-indexing`.
+---             • cursor: Immediately update cursor position on the screen in
+---               `win` or the current window.
+---             • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or
+---               all windows.
+---             • statusline: Redraw the 'statusline' in `buf`, `win` or all
+---               windows.
+---             • winbar: Redraw the 'winbar' in `buf`, `win` or all windows.
+---             • tabline: Redraw the 'tabline'.
+function vim.api.nvim__redraw(opts) end
+
+--- @private
 --- @return any[]
 function vim.api.nvim__runtime_inspect() end
 
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index 9f9ade3e76..f7cd92a3b2 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -207,6 +207,18 @@ error('Cannot require a meta file')
 --- @field buf? integer
 --- @field filetype? string
 
+--- @class vim.api.keyset.redraw
+--- @field flush? boolean
+--- @field cursor? boolean
+--- @field valid? boolean
+--- @field statuscolumn? boolean
+--- @field statusline? boolean
+--- @field tabline? boolean
+--- @field winbar? boolean
+--- @field range? any[]
+--- @field win? integer
+--- @field buf? integer
+
 --- @class vim.api.keyset.runtime
 --- @field is_lua? boolean
 --- @field do_source? boolean
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index 985cbef5ff..c9e485f474 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -62,7 +62,7 @@ function M.on_inlayhint(err, result, ctx, _)
   if num_unprocessed == 0 then
     client_hints[client_id] = {}
     bufstate.version = ctx.version
-    api.nvim__buf_redraw_range(bufnr, 0, -1)
+    api.nvim__redraw({ buf = bufnr, valid = true })
     return
   end
 
@@ -91,7 +91,7 @@ function M.on_inlayhint(err, result, ctx, _)
 
   client_hints[client_id] = new_lnum_hints
   bufstate.version = ctx.version
-  api.nvim__buf_redraw_range(bufnr, 0, -1)
+  api.nvim__redraw({ buf = bufnr, valid = true })
 end
 
 --- |lsp-handler| for the method `textDocument/inlayHint/refresh`
@@ -224,7 +224,7 @@ local function clear(bufnr)
     end
   end
   api.nvim_buf_clear_namespace(bufnr, namespace, 0, -1)
-  api.nvim__buf_redraw_range(bufnr, 0, -1)
+  api.nvim__redraw({ buf = bufnr, valid = true })
 end
 
 --- Disable inlay hints for a buffer
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 20ac0a125f..be2d6ee0ae 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -394,7 +394,7 @@ function STHighlighter:process_response(response, client, version)
   current_result.namespace_cleared = false
 
   -- redraw all windows displaying buffer
-  api.nvim__buf_redraw_range(self.bufnr, 0, -1)
+  api.nvim__redraw({ buf = self.bufnr, valid = true })
 end
 
 --- on_win handler for the decoration provider (see |nvim_set_decoration_provider|)
diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index 3f7e31212c..d2f986b874 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -215,7 +215,7 @@ end
 ---@param start_row integer
 ---@param new_end integer
 function TSHighlighter:on_bytes(_, _, start_row, _, _, _, _, _, new_end)
-  api.nvim__buf_redraw_range(self.bufnr, start_row, start_row + new_end + 1)
+  api.nvim__redraw({ buf = self.bufnr, range = { start_row, start_row + new_end + 1 } })
 end
 
 ---@package
@@ -227,7 +227,7 @@ end
 ---@param changes Range6[]
 function TSHighlighter:on_changedtree(changes)
   for _, ch in ipairs(changes) do
-    api.nvim__buf_redraw_range(self.bufnr, ch[1], ch[4] + 1)
+    api.nvim__redraw({ buf = self.bufnr, range = { ch[1], ch[4] + 1 } })
   end
 end