feat(ui): indicate margins for the area used by win_viewport

Problem: using win_viewport for implementing smooth scrolling in an external
UI might run into problems when winbar or borders is used, as there is
no indication that the entire grid is not used for scrolled buffer text.

Solution: add `win_viewport_margins` event.

runtime/doc/ui.txt

@@ -656,6 +656,11 @@ tabs.
 	the screen and copy it to the viewport destination once `win_viewport`
 	is received.
 
+["win_viewport_margins", grid, win, top, bottom, left, right] ~
+	Indicates the margins of a window grid which are _not_ part of the
+	viewport as indicated by the `win_viewport` event. This happens
+	e.g. in the presence of 'winbar' and floating window borders.
+
 ["win_extmark", grid, win, ns_id, mark_id, row, col] ~
 	Updates the position of an extmark which is currently visible in a
 	window. Only emitted if the mark has the `ui_watched` attribute.

src/nvim/api/ui_events.in.h

@@ -118,6 +118,10 @@ void win_viewport(Integer grid, Window win, Integer topline, Integer botline, In
                   Integer curcol, Integer line_count, Integer scroll_delta)
   FUNC_API_SINCE(7) FUNC_API_CLIENT_IGNORE;
 
+void win_viewport_margins(Integer grid, Window win, Integer top, Integer bottom, Integer left,
+                          Integer right)
+  FUNC_API_SINCE(12) FUNC_API_CLIENT_IGNORE;
+
 void win_extmark(Integer grid, Window win, Integer ns_id, Integer mark_id, Integer row, Integer col)
   FUNC_API_SINCE(10) FUNC_API_REMOTE_ONLY;
 

src/nvim/window.c

@@ -6744,6 +6744,13 @@ void win_set_inner_size(win_T *wp, bool valid_cursor)
   wp->w_width_outer = (wp->w_width_inner + win_border_width(wp));
   wp->w_winrow_off = wp->w_border_adj[0] + wp->w_winbar_height;
   wp->w_wincol_off = wp->w_border_adj[3];
+
+  if (ui_has(kUIMultigrid)) {
+    ui_call_win_viewport_margins(wp->w_grid_alloc.handle, wp->handle,
+                                 wp->w_winrow_off, wp->w_border_adj[2],
+                                 wp->w_wincol_off, wp->w_border_adj[1]);
+  }
+
   wp->w_redr_status = true;
 }
 

test/functional/ui/float_spec.lua

@@ -1536,7 +1536,12 @@ describe('float window', function()
         }, win_viewport={
           [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
           [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 2, sum_scroll_delta = 0};
-        }}
+        },
+        win_viewport_margins={
+          [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+          [4] = {win = 1001, top = 1, bottom = 1, left = 1, right = 1};
+        }
+      }
       else
         screen:expect{grid=[[
           ^                                        |
@@ -1736,7 +1741,12 @@ describe('float window', function()
         }, win_viewport={
           [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
           [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 2, sum_scroll_delta = 0};
-        }}
+        },
+        win_viewport_margins={
+          [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+          [4] = {win = 1001, top = 0, bottom = 0, left = 1, right = 1};
+        }
+      }
       else
         screen:expect{grid=[[
           ^                                        |
@@ -1769,6 +1779,10 @@ describe('float window', function()
         }, win_viewport={
           [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
           [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 2, sum_scroll_delta = 0};
+        },
+        win_viewport_margins={
+          [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+          [4] = {win = 1001, top = 1, bottom = 1, left = 0, right = 0};
         }}
       else
         screen:expect{grid=[[
@@ -1814,6 +1828,10 @@ describe('float window', function()
         }, win_viewport={
           [2] = {win = 1000, topline = 0, botline = 6, curline = 5, curcol = 0, linecount = 6, sum_scroll_delta = 0};
           [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 2, sum_scroll_delta = 0};
+        },
+        win_viewport_margins={
+          [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+          [4] = {win = 1001, top = 0, bottom = 1, left = 0, right = 1};
         }}
       else
         screen:expect{grid=[[
@@ -8361,6 +8379,10 @@ describe('float window', function()
         }, win_viewport={
           [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
           [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
+        },
+        win_viewport_margins={
+          [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+          [4] = {win = 1001, top = 2, bottom = 1, left = 1, right = 1};
         }}
       else
         screen:expect{grid=[[

test/functional/ui/multigrid_spec.lua

@@ -2354,6 +2354,9 @@ describe('ext_multigrid', function()
     ]], win_viewport={
       [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
       [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
+    }, win_viewport_margins={
+      [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+      [4] = {win = 1001, top = 0, bottom = 0, left = 0, right = 0};
     }}
 
     -- XXX: hack to get notifications. Could use next_msg() also.
@@ -2384,6 +2387,9 @@ describe('ext_multigrid', function()
     ]], win_viewport={
       [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
       [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
+    }, win_viewport_margins={
+      [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+      [4] = {win = 1001, top = 1, bottom = 0, left = 0, right = 0};
     }}
     eq({}, win_pos)
 
@@ -2406,6 +2412,9 @@ describe('ext_multigrid', function()
     ]], win_viewport={
       [2] = {win = 1000, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
       [4] = {win = 1001, topline = 0, botline = 2, curline = 0, curcol = 0, linecount = 1, sum_scroll_delta = 0};
+    }, win_viewport_margins={
+      [2] = {win = 1000, top = 0, bottom = 0, left = 0, right = 0};
+      [4] = {win = 1001, top = 0, bottom = 0, left = 0, right = 0};
     }}
     eq({}, win_pos)
   end)

test/functional/ui/screen.lua

@@ -204,6 +204,7 @@ function Screen.new(width, height)
     wildmenu_selected = nil,
     win_position = {},
     win_viewport = {},
+    win_viewport_margins = {},
     float_pos = {},
     msg_grid = nil,
     msg_grid_pos = nil,
@@ -337,6 +338,7 @@ local ext_keys = {
   'ruler',
   'float_pos',
   'win_viewport',
+  'win_viewport_margins',
 }
 
 local expect_keys = {
@@ -621,6 +623,9 @@ screen:redraw_debug() to show all intermediate screen states.]]
     if expected.win_viewport == nil then
       extstate.win_viewport = nil
     end
+    if expected.win_viewport_margins == nil then
+      extstate.win_viewport_margins = nil
+    end
 
     if expected.float_pos then
       expected.float_pos = deepcopy(expected.float_pos)
@@ -993,6 +998,7 @@ function Screen:_handle_grid_destroy(grid)
   if self._options.ext_multigrid then
     self.win_position[grid] = nil
     self.win_viewport[grid] = nil
+    self.win_viewport_margins[grid] = nil
   end
 end
 
@@ -1048,6 +1054,16 @@ function Screen:_handle_win_viewport(
   }
 end
 
+function Screen:_handle_win_viewport_margins(grid, win, top, bottom, left, right)
+  self.win_viewport_margins[grid] = {
+    win = win,
+    top = top,
+    bottom = bottom,
+    left = left,
+    right = right,
+  }
+end
+
 function Screen:_handle_win_float_pos(grid, ...)
   self.win_position[grid] = nil
   self.float_pos[grid] = { ... }
@@ -1466,6 +1482,8 @@ function Screen:_extstate_repr(attr_state)
   end
 
   local win_viewport = (next(self.win_viewport) and self.win_viewport) or nil
+  local win_viewport_margins = (next(self.win_viewport_margins) and self.win_viewport_margins)
+    or nil
 
   return {
     popupmenu = self.popupmenu,
@@ -1480,6 +1498,7 @@ function Screen:_extstate_repr(attr_state)
     msg_history = msg_history,
     float_pos = self.float_pos,
     win_viewport = win_viewport,
+    win_viewport_margins = win_viewport_margins,
   }
 end