feat(ui): support grid=0 in nvim_input_mouse #32535

Problem:
Multigrid UIs have to find out which window to send the input by using
the Nvim focus rules, which are not fully documented.

Furthermore,`getmousepos()` has several problems when multigrid is
enabled, with the main one being that screenrow and screencol are window
relative instead of screen relative, due to the fact that the UI don't
send any absolute coordinates.

Solution:
Allow passing 0 as grid to `nvim_input_mouse`, with absolute
coordinates, which lets nvim determine the actual window to send the
mouse input to. This works as long as nvim is in charge of the window
positioning. If the UI repositions or resizes the windows, it can still
pass the grid it determines like before.

runtime/doc/api.txt

@@ -1147,8 +1147,9 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
                     press, except that the "-" separator is optional, so
                     "C-A-", "c-a" and "CA" can all be used to specify
                     Ctrl+Alt+click.
-      • {grid}      (`integer`) Grid number if the client uses |ui-multigrid|,
-                    else 0.
+      • {grid}      (`integer`) Grid number (used by |ui-multigrid| client),
+                    or 0 to let Nvim decide positioning of windows. For more
+                    information, see |dev-ui-multigrid|
       • {row}       (`integer`) Mouse row-position (zero-based, like redraw
                     events)
       • {col}       (`integer`) Mouse column-position (zero-based, like redraw

runtime/doc/develop.txt

@@ -685,5 +685,23 @@ External UIs are expected to implement these common features:
 - Handle the "restart" UI event so that |:restart| works.
 - Detect capslock and show an indicator if capslock is active.
 
+Multigrid UI ~
+                                                        *dev-ui-multigrid*
+- A multigrid UI should display floating windows using one of the following
+  methods, using the `win_float_pos` |ui-multigrid| event. Different methods
+  can be selected for each window as needed.
+
+  1. Let Nvim determine the position and z-order of the windows. This can be
+  achieved by using the `compindex`, `screen_row`, and `screen_col` information from
+  the `win_float_pos` UI event. To allow Nvim to automatically determine the grid,
+  the UI should call `nvim_input_mouse` with 0 as the `grid` parameter.
+  2. Use the `anchor`, `anchor_grid`, `anchor_row`, `anchor_col`, and `zindex` as
+  references for positioning the windows. If windows are outside the screen,
+  it is the UI's responsibility to reposition and/or resize them. Since Nvim
+  lacks information about actual window placement in this case, the UI must
+  call `nvim_input_mouse` with the actual grid id, factoring in `mouse_enabled`.
+  Note: Some API functions may return unexpected results for these windows due
+  to the missing information.
+- For external windows, the grid id should also be passed to `nvim_input_mouse`.
 
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/news.txt

@@ -339,6 +339,7 @@ UI
   • "Error executing Lua:" changed to "Lua:".
 • 'busy' status is shown in default statusline with symbol ◐
 • Improved LSP signature help rendering.
+• Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid.
 
 VIMSCRIPT
 

runtime/lua/vim/_meta/api.lua

@@ -1606,7 +1606,8 @@ function vim.api.nvim_input(keys) end
 --- The same specifiers are used as for a key press, except
 --- that the "-" separator is optional, so "C-A-", "c-a"
 --- and "CA" can all be used to specify Ctrl+Alt+click.
---- @param grid integer Grid number if the client uses `ui-multigrid`, else 0.
+--- @param grid integer Grid number (used by `ui-multigrid` client), or 0 to let Nvim decide positioning of
+--- windows. For more information, see [dev-ui-multigrid]
 --- @param row integer Mouse row-position (zero-based, like redraw events)
 --- @param col integer Mouse column-position (zero-based, like redraw events)
 function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end