feat(api): make nvim_open_win support non-floating windows (#25550)

Adds support to `nvim_open_win` and `nvim_win_set_config` for creating
and manipulating split (non-floating) windows.

runtime/doc/api.txt

@@ -3093,18 +3093,28 @@ nvim_win_text_height({window}, {*opts})               *nvim_win_text_height()*
 Win_Config Functions                                          *api-win_config*
 
 nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
-    Open a new window.
+    Opens a new split window, or a floating window if `relative` is specified,
+    or an external window (managed by the UI) if `external` is specified.
 
-    Currently this is used to open floating and external windows. Floats are
-    windows that are drawn above the split layout, at some anchor position in
-    some other window. Floats can be drawn internally or by external GUI with
-    the |ui-multigrid| extension. External windows are only supported with
-    multigrid GUIs, and are displayed as separate top-level windows.
+    Floats are windows that are drawn above the split layout, at some anchor
+    position in some other window. Floats can be drawn internally or by
+    external GUI with the |ui-multigrid| extension. External windows are only
+    supported with multigrid GUIs, and are displayed as separate top-level
+    windows.
 
     For a general overview of floats, see |api-floatwin|.
 
-    Exactly one of `external` and `relative` must be specified. The `width`
-    and `height` of the new window must be specified.
+    The `width` and `height` of the new window must be specified when opening
+    a floating window, but are optional for normal windows.
+
+    If `relative` and `external` are omitted, a normal "split" window is
+    created. The `win` property determines which window will be split. If no
+    `win` is provided or `win == 0`, a window will be created adjacent to the
+    current window. If -1 is provided, a top-level split will be created.
+    `vertical` and `split` are only valid for normal windows, and are used to
+    control split direction. For `vertical`, the exact direction is determined
+    by |'splitright'| and |'splitbelow'|. Split windows cannot have
+    `bufpos`/`row`/`col`/`border`/`title`/`footer` properties.
 
     With relative=editor (row=0,col=0) refers to the top-left corner of the
     screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
@@ -3127,6 +3137,13 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
           {relative='win', width=12, height=3, bufpos={100,10}})
 <
 
+    Example (Lua): vertical split left of the current window >lua
+        vim.api.nvim_open_win(0, false, {
+          split = 'left',
+          win = 0
+        })
+<
+
     Attributes: ~
         not allowed when |textlock| is active
 
@@ -3142,7 +3159,8 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                     • "cursor" Cursor position in current window.
                     • "mouse" Mouse position
 
-                  • win: |window-ID| for relative="win".
+                  • win: |window-ID| window to split, or relative window when
+                    creating a float (relative="win").
                   • anchor: Decides which corner of the float to place at
                     (row,col):
                     • "NW" northwest (default)
@@ -3239,6 +3257,8 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                   • fixed: If true when anchor is NW or SW, the float window
                     would be kept fixed even if the window would be truncated.
                   • hide: If true the floating window will be hidden.
+                  • vertical: Split vertically |:vertical|.
+                  • split: Split direction: "left", "right", "above", "below".
 
     Return: ~
         Window handle, or 0 on error

runtime/doc/news.txt

@@ -406,6 +406,9 @@ The following changes to existing APIs or features add new behavior.
 • |:checkhealth| buffer can now be opened in a split window using modifiers like
   |:vertical|, |:horizontal| and |:botright|.
 
+• |nvim_open_win()| and |nvim_win_set_config()| now support opening normal (split)
+  windows, and moving floating windows into split windows.
+
 ==============================================================================
 REMOVED FEATURES                                                 *news-removed*
 

runtime/lua/vim/_meta/api.lua

@@ -1483,15 +1483,24 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- @return integer
 function vim.api.nvim_open_term(buffer, opts) end
 
---- Open a new window.
---- Currently this is used to open floating and external windows. Floats are
---- windows that are drawn above the split layout, at some anchor position in
---- some other window. Floats can be drawn internally or by external GUI with
---- the `ui-multigrid` extension. External windows are only supported with
---- multigrid GUIs, and are displayed as separate top-level windows.
+--- Opens a new split window, or a floating window if `relative` is specified,
+--- or an external window (managed by the UI) if `external` is specified.
+--- Floats are windows that are drawn above the split layout, at some anchor
+--- position in some other window. Floats can be drawn internally or by
+--- external GUI with the `ui-multigrid` extension. External windows are only
+--- supported with multigrid GUIs, and are displayed as separate top-level
+--- windows.
 --- For a general overview of floats, see `api-floatwin`.
---- Exactly one of `external` and `relative` must be specified. The `width`
---- and `height` of the new window must be specified.
+--- The `width` and `height` of the new window must be specified when opening
+--- a floating window, but are optional for normal windows.
+--- If `relative` and `external` are omitted, a normal "split" window is
+--- created. The `win` property determines which window will be split. If no
+--- `win` is provided or `win == 0`, a window will be created adjacent to the
+--- current window. If -1 is provided, a top-level split will be created.
+--- `vertical` and `split` are only valid for normal windows, and are used to
+--- control split direction. For `vertical`, the exact direction is determined
+--- by `'splitright'` and `'splitbelow'`. Split windows cannot have
+--- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties.
 --- With relative=editor (row=0,col=0) refers to the top-left corner of the
 --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
 --- corner. Fractional values are allowed, but the builtin implementation
@@ -1515,6 +1524,15 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---       {relative='win', width=12, height=3, bufpos={100,10}})
 --- ```
 ---
+--- Example (Lua): vertical split left of the current window
+---
+--- ```lua
+---     vim.api.nvim_open_win(0, false, {
+---       split = 'left',
+---       win = 0
+---     })
+--- ```
+---
 --- @param buffer integer Buffer to display, or 0 for current buffer
 --- @param enter boolean Enter the window (make it the current window)
 --- @param config vim.api.keyset.float_config Map defining the window configuration. Keys:
@@ -1526,7 +1544,8 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---                 • "cursor" Cursor position in current window.
 ---                 • "mouse" Mouse position
 ---
----               • win: `window-ID` for relative="win".
+---               • win: `window-ID` window to split, or relative window when
+---                 creating a float (relative="win").
 ---               • anchor: Decides which corner of the float to place at
 ---                 (row,col):
 ---                 • "NW" northwest (default)
@@ -1623,6 +1642,8 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---               • fixed: If true when anchor is NW or SW, the float window
 ---                 would be kept fixed even if the window would be truncated.
 ---               • hide: If true the floating window will be hidden.
+---               • vertical: Split vertically `:vertical`.
+---               • split: Split direction: "left", "right", "above", "below".
 --- @return integer
 function vim.api.nvim_open_win(buffer, enter, config) end
 

runtime/lua/vim/_meta/api_keysets.lua

@@ -118,10 +118,12 @@ error('Cannot require a meta file')
 --- @field height? integer
 --- @field anchor? string
 --- @field relative? string
+--- @field split? string
 --- @field win? integer
 --- @field bufpos? any[]
 --- @field external? boolean
 --- @field focusable? boolean
+--- @field vertical? boolean
 --- @field zindex? integer
 --- @field border? any
 --- @field title? any