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.

runtime/doc/api.txt

@@ -3991,6 +3991,8 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                       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.
+                      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.

runtime/doc/news.txt

@@ -106,6 +106,8 @@ The following new features were added.
 API
 
 • |nvim_set_hl()| supports "font" key.
+• |nvim_open_win()| `zindex` controls whether the UI will use a dimmed cursor
+  shape when an unfocused float is on top of the cursor.
 
 BUILD
 

runtime/lua/vim/_meta/api.gen.lua

@@ -1887,7 +1887,8 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---     - 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.
 --- @return integer # |window-ID|, or 0 on error