feat(api): api.tree.open/toggle: add current_window option (#1935)

* feat(api): api.tree.open: add current_window option

* feat(api): api.tree.toggle: add current_window option

* feat(api): api.tree.toggle: add current_window option

* doc: api.tree.*

* doc: api.tree.*

lua/nvim-tree.lua

@@ -70,13 +70,28 @@ end
 ---@deprecated
 M.on_keypress = require("nvim-tree.actions.dispatch").dispatch
 
-function M.open(cwd)
-  cwd = cwd ~= "" and cwd or nil
+---Open the tree, focusing if already open.
+---@param opts ApiTreeOpenOpts|nil|string
+function M.open(opts)
+  -- legacy arguments
+  if type(opts) ~= "table" then
+    opts = {
+      path = opts,
+    }
+  end
+
+  opts = opts or {}
+
+  -- sanitise path
+  if type(opts.path) ~= "string" or vim.fn.isdirectory(opts.path) == 0 then
+    opts.path = nil
+  end
+
   if view.is_visible() then
     lib.set_target_win()
     view.focus()
   else
-    lib.open(cwd)
+    lib.open(opts)
   end
 end
 
@@ -164,16 +179,35 @@ function M.find_file(with_open, bufnr, bang)
   find_file(with_open, bufnr, bang)
 end
 
-function M.toggle(with_find_file, no_focus, cwd, bang)
+---Toggle the tree.
+---@param opts ApiTreeToggleOpts|nil|boolean
+function M.toggle(opts, no_focus, cwd, bang)
+  -- legacy arguments
+  if type(opts) ~= "table" then
+    opts = {
+      path = cwd,
+      focus = not no_focus,
+      find_file = opts,
+      update_root = bang,
+    }
+  end
+
+  opts = opts or {}
+
+  -- sanitise path
+  if type(opts.path) ~= "string" or vim.fn.isdirectory(opts.path) == 0 then
+    opts.path = nil
+  end
+
   if view.is_visible() then
     view.close()
   else
     local previous_buf = vim.api.nvim_get_current_buf()
-    M.open(cwd)
-    if _config.update_focused_file.enable or with_find_file then
-      find_file(false, previous_buf, bang)
+    M.open { path = opts.path, current_window = opts.current_window }
+    if _config.update_focused_file.enable or opts.find_file then
+      find_file(false, previous_buf, opts.update_root)
     end
-    if no_focus then
+    if not opts.focus then
       vim.cmd "noautocmd wincmd p"
     end
   end
@@ -275,7 +309,7 @@ function M.on_enter(netrw_disabled)
   end
 
   if should_open or should_hijack or existing_tree_wins[1] ~= nil then
-    lib.open(cwd)
+    lib.open { path = cwd }
 
     if should_focus_other_window then
       vim.cmd "noautocmd wincmd p"
@@ -304,11 +338,11 @@ end
 
 local function setup_vim_commands()
   vim.api.nvim_create_user_command("NvimTreeOpen", function(res)
-    M.open(res.args)
+    M.open { path = res.args }
   end, { nargs = "?", complete = "dir" })
   vim.api.nvim_create_user_command("NvimTreeClose", view.close, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeToggle", function(res)
-    M.toggle(false, false, res.args)
+    M.toggle { find_file = false, focus = true, path = res.args, update_root = false }
   end, { nargs = "?", complete = "dir" })
   vim.api.nvim_create_user_command("NvimTreeFocus", M.focus, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeRefresh", reloaders.reload_explorer, { bar = true })
@@ -317,7 +351,7 @@ local function setup_vim_commands()
     find_file(true, nil, res.bang)
   end, { bang = true, bar = true })
   vim.api.nvim_create_user_command("NvimTreeFindFileToggle", function(res)
-    M.toggle(true, false, res.args, res.bang)
+    M.toggle { find_file = true, focus = false, path = res.args, update_root = res.bang }
   end, { bang = true, nargs = "?", complete = "dir" })
   vim.api.nvim_create_user_command("NvimTreeResize", function(res)
     M.resize(res.args)

lua/nvim-tree/api.lua

@@ -16,14 +16,33 @@ local function inject_node(f)
   end
 end
 
+---@class ApiTreeOpenOpts
+---@field path string|nil path
+---@field current_window boolean|nil
+
 Api.tree.open = require("nvim-tree").open
+
+---@class ApiTreeToggleOpts
+---@field path string|nil
+---@field current_window boolean|nil
+---@field focus boolean|nil
+---@field find_file boolean|nil
+---@field update_root boolean|nil
+
 Api.tree.toggle = require("nvim-tree").toggle
+
 Api.tree.close = require("nvim-tree.view").close
+
 Api.tree.close_in_this_tab = require("nvim-tree.view").close_this_tab_only
+
 Api.tree.close_in_all_tabs = require("nvim-tree.view").close_all_tabs
+
 Api.tree.focus = require("nvim-tree").focus
+
 Api.tree.reload = require("nvim-tree.actions.reloaders.reloaders").reload_explorer
+
 Api.tree.change_root = require("nvim-tree").change_dir
+
 Api.tree.change_root_to_node = inject_node(function(node)
   if node.name == ".." then
     require("nvim-tree.actions.root.change-dir").fn ".."
@@ -31,18 +50,31 @@ Api.tree.change_root_to_node = inject_node(function(node)
     require("nvim-tree.actions.root.change-dir").fn(require("nvim-tree.lib").get_last_group_node(node).absolute_path)
   end
 end)
+
 Api.tree.change_root_to_parent = inject_node(require("nvim-tree.actions.root.dir-up").fn)
+
 Api.tree.get_node_under_cursor = require("nvim-tree.lib").get_node_at_cursor
+
 Api.tree.get_nodes = require("nvim-tree.lib").get_nodes
+
 Api.tree.find_file = require("nvim-tree.actions.finders.find-file").fn
+
 Api.tree.search_node = require("nvim-tree.actions.finders.search-node").fn
+
 Api.tree.collapse_all = require("nvim-tree.actions.tree-modifiers.collapse-all").fn
+
 Api.tree.expand_all = inject_node(require("nvim-tree.actions.tree-modifiers.expand-all").fn)
+
 Api.tree.toggle_gitignore_filter = require("nvim-tree.actions.tree-modifiers.toggles").git_ignored
+
 Api.tree.toggle_git_clean_filter = require("nvim-tree.actions.tree-modifiers.toggles").git_clean
+
 Api.tree.toggle_no_buffer_filter = require("nvim-tree.actions.tree-modifiers.toggles").no_buffer
+
 Api.tree.toggle_custom_filter = require("nvim-tree.actions.tree-modifiers.toggles").custom
+
 Api.tree.toggle_hidden_filter = require("nvim-tree.actions.tree-modifiers.toggles").dotfiles
+
 Api.tree.toggle_help = require("nvim-tree.actions.tree-modifiers.toggles").help
 
 Api.fs.create = inject_node(require("nvim-tree.actions.fs.create-file").fn)

lua/nvim-tree/lib.lua

@@ -150,15 +150,22 @@ function M.prompt(prompt_input, prompt_select, items_short, items_long, callback
   end
 end
 
-function M.open(cwd)
+---Open the tree, initialising as needed. Maybe hijack the current buffer.
+---@param opts ApiTreeOpenOpts|string|nil legacy case opts is path string
+function M.open(opts)
+  opts = opts or {}
+
   M.set_target_win()
-  if not core.get_explorer() or cwd then
-    core.init(cwd or vim.loop.cwd())
+  if not core.get_explorer() or opts.path then
+    core.init(opts.path or vim.loop.cwd())
   end
   if should_hijack_current_buf() then
     view.close_this_tab_only()
     view.open_in_current_win()
     renderer.draw()
+  elseif opts.current_window then
+    view.open_in_current_win { hijack_current_buf = false, resize = false }
+    renderer.draw()
   else
     open_view_and_draw()
   end