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