feat(api): use zindex to determine dimmed cursor shape #39054

Problem:  The cursor shape is changed to indicate when it is behind an
          unfocused floating window (since a2b92a5e). This behavior
          cannot be controlled by a floating window that doesn't want
          to dim the cursor.

Solution: Assign a zindex-offset of 50 to the zindex of the current
          window. To not dim the cursor when creating a floating window
          on top of the current window one can assign the zindex
          accordingly.

src/nvim/api/win_config.c

@@ -194,7 +194,8 @@
 ///       - 250: cmdline completion popupmenu (when wildoptions+=pum)
 ///     The default value for floats are 50.  In general, values below 100 are
 ///     recommended, unless there is a good reason to overshadow builtin
-///     elements.
+///     elements. The cursor is dimmed if an unfocused float above the cursor
+///     exceeds the zindex of the current window by 50.
 ///   - _cmdline_offset: (EXPERIMENTAL) When provided, anchor the |cmdline-completion|
 ///     popupmenu to this window, with an offset in screen cell width.
 ///

src/nvim/ui.c

@@ -685,7 +685,8 @@ void ui_cursor_shape(void)
 }
 
 /// Check if the cursor is behind a floating window (only in compositor mode).
-/// @return true if cursor is obscured by a float with higher zindex
+/// @return true if cursor is obscured by a float (when its zindex exceeds the
+/// zindex of the current window by 50).
 static bool ui_cursor_is_behind_floatwin(void)
 {
   if ((State & MODE_CMDLINE) || !ui_comp_should_draw()) {
@@ -697,7 +698,9 @@ static bool ui_cursor_is_behind_floatwin(void)
              + (curwin->w_p_rl ? curwin->w_view_width - curwin->w_wcol - 1 : curwin->w_wcol);
 
   ScreenGrid *top_grid = ui_comp_get_grid_at_coord(crow, ccol);
-  return top_grid != &curwin->w_grid_alloc && top_grid != &default_grid;
+  return top_grid != &curwin->w_grid_alloc
+         && top_grid != &default_grid
+         && top_grid->zindex >= curwin->w_grid_alloc.zindex + 50;
 }
 
 /// Returns true if the given UI extension is enabled.