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.

1 files changed, 30 insertions, 9 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index bedc218626..77a29cb4c1 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/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