feat: open_in_win to open aerial in an existing window (#248)

README.md

@@ -680,6 +680,7 @@ hi AerialGuide2 guifg=Blue
 - [close_all()](doc/api.md#close_all)
 - [close_all_but_current()](doc/api.md#close_all_but_current)
 - [open(opts)](doc/api.md#openopts)
+- [open_in_win(target_win, source_win)](doc/api.md#open_in_wintarget_win-source_win)
 - [open_all()](doc/api.md#open_all)
 - [focus()](doc/api.md#focus)
 - [toggle(opts)](doc/api.md#toggleopts)

doc/aerial.txt

@@ -447,6 +447,16 @@ open({opts})                                                         *aerial.ope
                       (default true)
           {direction} `"left"|"right"|"float"` Direction to open aerial window
 
+open_in_win({target_win}, {source_win})                       *aerial.open_in_win*
+    Open aerial in an existing window
+
+    Parameters:
+      {target_win} `integer` The winid to open the aerial buffer
+      {source_win} `integer` The winid that contains the source buffer
+
+    Note:
+      This can be used to create custom layouts, since you can create and position the window yourself
+
 open_all()                                                       *aerial.open_all*
     Open an aerial window for each visible window.
 

doc/api.md

@@ -9,6 +9,7 @@
 - [close_all()](#close_all)
 - [close_all_but_current()](#close_all_but_current)
 - [open(opts)](#openopts)
+- [open_in_win(target_win, source_win)](#open_in_wintarget_win-source_win)
 - [open_all()](#open_all)
 - [focus()](#focus)
 - [toggle(opts)](#toggleopts)
@@ -94,6 +95,21 @@ Open the aerial window for the current buffer.
 |       | focus        | `boolean`                  | If true, jump to aerial window if it is opened (default true) |
 |       | direction    | `"left"\|"right"\|"float"` | Direction to open aerial window                               |
 
+## open_in_win(target_win, source_win)
+
+`open_in_win(target_win, source_win)` \
+Open aerial in an existing window
+
+| Param      | Type      | Desc                                      |
+| ---------- | --------- | ----------------------------------------- |
+| target_win | `integer` | The winid to open the aerial buffer       |
+| source_win | `integer` | The winid that contains the source buffer |
+
+**Note:**
+<pre>
+This can be used to create custom layouts, since you can create and position the window yourself
+</pre>
+
 ## open_all()
 
 `open_all()` \

lua/aerial/init.lua

@@ -244,6 +244,18 @@ M.open = function(opts)
   require("aerial.window").open(opts.focus, opts.direction)
 end
 
+---Open aerial in an existing window
+---@param target_win integer The winid to open the aerial buffer
+---@param source_win integer The winid that contains the source buffer
+---@note
+--- This can be used to create custom layouts, since you can create and position the window yourself
+M.open_in_win = function(target_win, source_win)
+  do_setup()
+  was_closed = false
+  local source_bufnr = vim.api.nvim_win_get_buf(source_win)
+  require("aerial.window").open_aerial_in_win(source_bufnr, source_win, target_win)
+end
+
 ---Open an aerial window for each visible window.
 M.open_all = lazy("window", "open_all")
 

lua/aerial/util.lua

@@ -305,7 +305,8 @@ M.is_managing_folds = function(winid)
   return vim.api.nvim_win_get_option(winid or 0, "foldexpr") == "v:lua.aerial_foldexpr()"
 end
 
-M.detect_split_direction = function(bufnr)
+---@return "left"|"right"|"float"
+M.detect_split_direction = function()
   local default = config.layout.default_direction
   if default ~= "prefer_left" and default ~= "prefer_right" then
     return default

lua/aerial/window.lua

@@ -107,6 +107,11 @@ local function setup_aerial_win(src_winid, aer_winid, aer_bufnr)
   end
 end
 
+---@param bufnr nil|integer
+---@param aer_bufnr nil|integer
+---@param direction "left"|"right"|"float"
+---@param existing_win nil|integer
+---@return integer
 local function create_aerial_window(bufnr, aer_bufnr, direction, existing_win)
   if direction ~= "left" and direction ~= "right" and direction ~= "float" then
     error("Expected direction to be 'left', 'right', or 'float'")
@@ -286,10 +291,9 @@ M.maybe_open_automatic = function(bufnr)
   end
 end
 
-M.open = function(focus, direction, opts)
-  opts = vim.tbl_extend("keep", opts or {}, {
-    winid = nil,
-  })
+---@param focus? boolean
+---@param direction? "left"|"right"|"float"
+M.open = function(focus, direction)
   if util.is_aerial_buffer(0) or util.is_ignored_win() then
     return
   end
@@ -303,7 +307,7 @@ M.open = function(focus, direction, opts)
   end
 
   direction = direction or util.detect_split_direction()
-  local aer_winid = create_aerial_window(bufnr, aer_bufnr, direction, opts.winid or aerial_win)
+  local aer_winid = create_aerial_window(bufnr, aer_bufnr, direction, aerial_win)
   local backend = backends.get(0)
   if backend and not data.has_symbols(bufnr) then
     backend.fetch_symbols(bufnr)

tests/open_spec.lua

@@ -43,4 +43,25 @@ a.describe("layout", function()
     assert.equals("aerial", vim.api.nvim_buf_get_option(aer_bufnr, "filetype"))
     assert(require("aerial.util").is_floating_win(winid))
   end)
+
+  a.it("can open aerial in a specific window (not current)", function()
+    local target_win = vim.api.nvim_get_current_win()
+    vim.cmd("edit README.md")
+    vim.cmd.vsplit()
+    aerial.open_in_win(target_win, 0)
+    local aer_bufnr = vim.api.nvim_win_get_buf(target_win)
+    assert.equals("aerial", vim.bo[aer_bufnr].filetype)
+    assert.truthy(vim.api.nvim_buf_get_name(0):match("README.md$"))
+  end)
+
+  a.it("can open aerial in a specific (current) window", function()
+    local source_win = vim.api.nvim_get_current_win()
+    vim.cmd("edit README.md")
+    vim.cmd.vsplit()
+    local target_win = vim.api.nvim_get_current_win()
+    aerial.open_in_win(target_win, source_win)
+    local source_bufnr = vim.api.nvim_win_get_buf(source_win)
+    assert.equals("aerial", vim.bo.filetype)
+    assert.truthy(vim.api.nvim_buf_get_name(source_bufnr):match("README.md$"))
+  end)
 end)