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'.

4 files changed, 273 insertions, 2 deletions

diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 2d3871a37d..fbb6d42633 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -5016,4 +5016,216 @@ describe('API', function()
       eq(false, exec_lua('return _G.success'))
     end)
   end)
+
+  it('nvim__redraw', function()
+    local screen = Screen.new(60, 5)
+    screen:attach()
+    local win = api.nvim_get_current_win()
+    eq('at least one action required', pcall_err(api.nvim__redraw, {}))
+    eq('at least one action required', pcall_err(api.nvim__redraw, { buf = 0 }))
+    eq('at least one action required', pcall_err(api.nvim__redraw, { win = 0 }))
+    eq("cannot use both 'buf' and 'win'", pcall_err(api.nvim__redraw, { buf = 0, win = 0 }))
+    feed(':echo getchar()<CR>')
+    fn.setline(1, 'foobar')
+    command('vnew')
+    fn.setline(1, 'foobaz')
+    -- Can flush pending screen updates
+    api.nvim__redraw({ flush = true })
+    screen:expect({
+      grid = [[
+        foobaz                        │foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:[No Name] [+]                  }{2:[No Name] [+]                }|
+        ^:echo getchar()                                             |
+      ]],
+    })
+    -- Can update the grid cursor position #20793
+    api.nvim__redraw({ cursor = true })
+    screen:expect({
+      grid = [[
+        ^foobaz                        │foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:[No Name] [+]                  }{2:[No Name] [+]                }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Also in non-current window
+    api.nvim__redraw({ cursor = true, win = win })
+    screen:expect({
+      grid = [[
+        foobaz                        │^foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:[No Name] [+]                  }{2:[No Name] [+]                }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update the 'statusline' in a single window
+    api.nvim_set_option_value('statusline', 'statusline1', { win = 0 })
+    api.nvim_set_option_value('statusline', 'statusline2', { win = win })
+    api.nvim__redraw({ cursor = true, win = 0, statusline = true })
+    screen:expect({
+      grid = [[
+        ^foobaz                        │foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:statusline1                    }{2:[No Name] [+]                }|
+        :echo getchar()                                             |
+      ]],
+    })
+    api.nvim__redraw({ win = win, statusline = true })
+    screen:expect({
+      grid = [[
+        ^foobaz                        │foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:statusline1                    }{2:statusline2                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update the 'statusline' in all windows
+    api.nvim_set_option_value('statusline', '', { win = win })
+    api.nvim_set_option_value('statusline', 'statusline3', {})
+    api.nvim__redraw({ statusline = true })
+    screen:expect({
+      grid = [[
+        ^foobaz                        │foobar                       |
+        {1:~                             }│{1:~                            }|*2
+        {3:statusline3                    }{2:statusline3                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update the 'statuscolumn'
+    api.nvim_set_option_value('statuscolumn', 'statuscolumn', { win = win })
+    api.nvim__redraw({ statuscolumn = true })
+    screen:expect({
+      grid = [[
+        ^foobaz                        │{8:statuscolumn}foobar           |
+        {1:~                             }│{1:~                            }|*2
+        {3:statusline3                    }{2:statusline3                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update the 'winbar'
+    api.nvim_set_option_value('winbar', 'winbar', { win = 0 })
+    api.nvim__redraw({ win = 0, winbar = true })
+    screen:expect({
+      grid = [[
+        {5:^winbar                        }│{8:statuscolumn}foobar           |
+        foobaz                        │{1:~                            }|
+        {1:~                             }│{1:~                            }|
+        {3:statusline3                    }{2:statusline3                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update the 'tabline'
+    api.nvim_set_option_value('showtabline', 2, {})
+    api.nvim_set_option_value('tabline', 'tabline', {})
+    api.nvim__redraw({ tabline = true })
+    screen:expect({
+      grid = [[
+        {2:^tabline                                                     }|
+        {5:winbar                        }│{8:statuscolumn}foobar           |
+        foobaz                        │{1:~                            }|
+        {3:statusline3                    }{2:statusline3                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update multiple status widgets
+    api.nvim_set_option_value('tabline', 'tabline2', {})
+    api.nvim_set_option_value('statusline', 'statusline4', {})
+    api.nvim__redraw({ statusline = true, tabline = true })
+    screen:expect({
+      grid = [[
+        {2:^tabline2                                                    }|
+        {5:winbar                        }│{8:statuscolumn}foobar           |
+        foobaz                        │{1:~                            }|
+        {3:statusline4                    }{2:statusline4                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update all status widgets
+    api.nvim_set_option_value('tabline', 'tabline3', {})
+    api.nvim_set_option_value('statusline', 'statusline5', {})
+    api.nvim_set_option_value('statuscolumn', 'statuscolumn2', {})
+    api.nvim_set_option_value('winbar', 'winbar2', {})
+    api.nvim__redraw({ statuscolumn = true, statusline = true, tabline = true, winbar = true })
+    screen:expect({
+      grid = [[
+        {2:^tabline3                                                    }|
+        {5:winbar2                       }│{5:winbar2                      }|
+        {8:statuscolumn2}foobaz           │{8:statuscolumn}foobar           |
+        {3:statusline5                    }{2:statusline5                  }|
+        :echo getchar()                                             |
+      ]],
+    })
+    -- Can update status widget for a specific window
+    feed('<CR><CR>')
+    command('let g:status=0')
+    api.nvim_set_option_value('statusline', '%{%g:status%}', { win = 0 })
+    command('vsplit')
+    screen:expect({
+      grid = [[
+        {2:tabline3                                                    }|
+        {5:winbar2             }│{5:winbar2            }│{5:winbar2            }|
+        {8:statuscolumn2}^foobaz │{8:statuscolumn2}foobaz│{8:statuscolumn}foobar |
+        {3:0                    }{2:0                   statusline5        }|
+        13                                                          |
+      ]],
+    })
+    command('let g:status=1')
+    api.nvim__redraw({ win = 0, statusline = true })
+    screen:expect({
+      grid = [[
+        {2:tabline3                                                    }|
+        {5:winbar2             }│{5:winbar2            }│{5:winbar2            }|
+        {8:statuscolumn2}^foobaz │{8:statuscolumn2}foobaz│{8:statuscolumn}foobar |
+        {3:1                    }{2:0                   statusline5        }|
+        13                                                          |
+      ]],
+    })
+    -- Can update status widget for a specific buffer
+    command('let g:status=2')
+    api.nvim__redraw({ buf = 0, statusline = true })
+    screen:expect({
+      grid = [[
+        {2:tabline3                                                    }|
+        {5:winbar2             }│{5:winbar2            }│{5:winbar2            }|
+        {8:statuscolumn2}^foobaz │{8:statuscolumn2}foobaz│{8:statuscolumn}foobar |
+        {3:2                    }{2:2                   statusline5        }|
+        13                                                          |
+      ]],
+    })
+    -- valid = true does not draw any lines on its own
+    exec_lua([[
+      lines = 0
+      ns = vim.api.nvim_create_namespace('')
+      on_win = function()
+        if do_win then
+          vim.api.nvim_buf_set_extmark(0, ns, 0, 0, { hl_group = 'IncSearch', end_col = 6 })
+        end
+      end
+      vim.api.nvim_set_decoration_provider(ns, {
+        on_win = on_win,
+        on_line = function()
+          lines = lines + 1
+        end,
+      })
+    ]])
+    local lines = exec_lua('return lines')
+    api.nvim__redraw({ buf = 0, valid = true, flush = true })
+    eq(lines, exec_lua('return lines'))
+    -- valid = false does
+    api.nvim__redraw({ buf = 0, valid = false, flush = true })
+    neq(lines, exec_lua('return lines'))
+    -- valid = true does redraw lines if affected by on_win callback
+    exec_lua('do_win = true')
+    api.nvim__redraw({ buf = 0, valid = true, flush = true })
+    screen:expect({
+      grid = [[
+        {2:tabline3                                                    }|
+        {5:winbar2             }│{5:winbar2            }│{5:winbar2            }|
+        {8:statuscolumn2}{2:^foobaz} │{8:statuscolumn2}{2:foobaz}│{8:statuscolumn}foobar |
+        {3:2                    }{2:2                   statusline5        }|
+        13                                                          |
+      ]],
+    })
+  end)
 end)
diff --git a/test/functional/ui/cmdline_spec.lua b/test/functional/ui/cmdline_spec.lua
index b3ec5f7535..6edfb4a49c 100644
--- a/test/functional/ui/cmdline_spec.lua
+++ b/test/functional/ui/cmdline_spec.lua
@@ -827,14 +827,14 @@ local function test_cmdline(linegrid)
     ]])
   end)
 
-  -- Needs new API
-  pending('does not move cursor to curwin #20309', function()
+  it('does not move cursor to curwin #20309', function()
     local win = api.nvim_get_current_win()
     command('norm icmdlinewin')
     command('new')
     command('norm icurwin')
     feed(':')
     api.nvim_win_set_cursor(win, { 1, 7 })
+    api.nvim__redraw({ win = win, cursor = true })
     screen:expect {
       grid = [[
       curwin                   |
diff --git a/test/functional/ui/inccommand_spec.lua b/test/functional/ui/inccommand_spec.lua
index 6bcfae2eee..c11e009fef 100644
--- a/test/functional/ui/inccommand_spec.lua
+++ b/test/functional/ui/inccommand_spec.lua
@@ -2594,6 +2594,12 @@ it(':substitute with inccommand, timer-induced :redraw #9777', function()
     {2:[Preview]                     }|
     :%s/foo/ZZZ^                   |
   ]])
+
+  -- Also with nvim__redraw()
+  command('call timer_start(10, {-> nvim__redraw(#{flush:1})}, {"repeat":-1})')
+  command('call timer_start(10, {-> nvim__redraw(#{statusline:1})}, {"repeat":-1})')
+  sleep(20) -- Allow some timer activity.
+  screen:expect_unchanged()
 end)
 
 it(':substitute with inccommand, allows :redraw before first separator is typed #18857', function()
diff --git a/test/functional/ui/statuscolumn_spec.lua b/test/functional/ui/statuscolumn_spec.lua
index cce9cca2ca..9a8629018f 100644
--- a/test/functional/ui/statuscolumn_spec.lua
+++ b/test/functional/ui/statuscolumn_spec.lua
@@ -918,4 +918,57 @@ describe('statuscolumn', function()
                                        |
     ]])
   end)
+
+  it('forces a rebuild with nvim__redraw', function()
+    screen:try_resize(40, 4)
+    -- Current window
+    command([[
+      let g:insert = v:false
+      set nonu stc=%{g:insert?'insert':''}
+      vsplit
+      au InsertEnter * let g:insert = v:true | call nvim__redraw(#{statuscolumn:1, win:0})
+      au InsertLeave * let g:insert = v:false | call nvim__redraw(#{statuscolumn:1, win:0})
+    ]])
+    feed('i')
+    screen:expect({
+      grid = [[
+        {8:insert}^aaaaa         │aaaaa              |
+        {8:insert}aaaaa         │aaaaa              |
+        {3:[No Name] [+]        }{2:[No Name] [+]      }|
+        {5:-- INSERT --}                            |
+      ]],
+    })
+    feed('<esc>')
+    screen:expect({
+      grid = [[
+        ^aaaaa               │aaaaa              |
+        aaaaa               │aaaaa              |
+        {3:[No Name] [+]        }{2:[No Name] [+]      }|
+                                                |
+      ]],
+    })
+    -- All windows
+    command([[
+      au! InsertEnter * let g:insert = v:true | call nvim__redraw(#{statuscolumn:1})
+      au! InsertLeave * let g:insert = v:false | call nvim__redraw(#{statuscolumn:1})
+    ]])
+    feed('i')
+    screen:expect({
+      grid = [[
+        {8:insert}^aaaaa         │{8:insert}aaaaa        |
+        {8:insert}aaaaa         │{8:insert}aaaaa        |
+        {3:[No Name] [+]        }{2:[No Name] [+]      }|
+        {5:-- INSERT --}                            |
+      ]],
+    })
+    feed('<esc>')
+    screen:expect({
+      grid = [[
+        ^aaaaa               │aaaaa              |
+        aaaaa               │aaaaa              |
+        {3:[No Name] [+]        }{2:[No Name] [+]      }|
+                                                |
+      ]],
+    })
+  end)
 end)