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

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1238,27 +1238,118 @@ that injects the node from the cursor position in the tree when calling
 the function. It will use the node you pass as an argument in priority if it
 exists.
 
-- api.tree:                                             *nvim-tree.api.tree*
-    - open `(path?: string)`
-    - close
-    - toggle `(find_file?: bool, no_focus?: bool, path?: string)`
-    - focus
-    - reload
-    - change_root `(path: string)`
-    - change_root_to_node
-    - change_root_to_parent
-    - get_node_under_cursor
-    - get_nodes
-    - find_file `(filename: string)`
-    - search_node
-    - collapse_all `(keep_buffers?: bool)`
-    - expand_all
-    - toggle_gitignore_filter
-    - toggle_git_clean_filter
-    - toggle_no_buffer_filter
-    - toggle_custom_filter
-    - toggle_hidden_filter
-    - toggle_help
+api.tree.open({opts})                              *nvim-tree.api.tree.open()*
+    Open the tree, focusing it if already open.
+
+    Parameters: ~
+      • {opts} (table) optional parameters
+
+    Options: ~
+      • {path}           (string)  root directory for the tree
+      • {current_window} (boolean) open the tree in the current window
+
+api.tree.toggle({opts})                          *nvim-tree.api.tree.toggle()*
+    Open or close the tree.
+
+    Parameters: ~
+      • {opts} (table) optional parameters
+
+    Options: ~
+      • {path}           (string)  root directory for the tree
+      • {current_window} (boolean) open the tree in the current window
+      • {focus}          (boolean) focus the tree when opening
+      • {find_file}      (boolean) find the current buffer
+      • {update_root}    (boolean) see |nvim-tree.update_focused_file.update_root|
+
+api.tree.close()                                   *nvim-tree.api.tree.close()*
+    Close the tree, affecting all tabs as per |nvim-tree.tab.sync.close|
+
+api.tree.close_in_this_tab()           *nvim-tree.api.tree.close_in_this_tab()*
+    Close the tree in this tab only.
+
+api.tree.close_in_all_tabs()           *nvim-tree.api.tree.close_in_all_tabs()*
+    Close the tree in all tabs.
+
+api.tree.focus()                                   *nvim-tree.api.tree.focus()*
+    Focus the tree, opening it if necessary.
+
+api.tree.reload()                                  *nvim-tree.api.tree.focus()*
+    Refresh the tree. Does nothing if closed.
+
+api.tree.change_root({path})                 *nvim-tree.api.tree.change_root()*
+    Change the tree's root to a path.   
+
+    Parameters: ~
+      • {path} (string) absolute or relative path
+
+                                     *nvim-tree.api.tree.change_root_to_node()*
+api.tree.change_root_to_node({node})
+    Change the tree's root to a folder node or the parent of a file node.
+
+    Parameters: ~
+      • {node} (Node) folder or file
+
+                                   *nvim-tree.api.tree.change_root_to_parent()*
+api.tree.change_root_to_parent({node})
+    Change the tree's root to the parent of a node.
+
+    Parameters: ~
+      • {node} (Node) folder or file
+
+                                
+api.tree.get_node_under_cursor()   *nvim-tree.api.tree.get_node_under_cursor()*
+    Retrieve the currently focused node.
+
+    Return: ~
+      node or nil if tree is not visible
+
+api.tree.get_nodes()                           *nvim-tree.api.tree.get_nodes()*
+    Retrieve a hierarchical list of all the nodes. This is a cloned list for
+    reference purposes only and should not be passed into other API functions.
+
+    Return: ~
+      table of nodes
+
+api.tree.find_file({path})                     *nvim-tree.api.tree.find_file()*
+    Find and focus a file or folder in the tree.
+
+    Parameters: ~
+      • {path} (string) absolute path
+
+api.tree.search_node()                       *nvim-tree.api.tree.search_node()*
+    Open the search dialogue as per the search_node action.
+
+api.tree.collapse_all({keep_buffers})       *nvim-tree.api.tree.collapse_all()*
+    Collapse the tree.
+
+    Parameters: ~
+      • {keep_buffers} (boolean) do not collapse nodes with open buffers.
+
+api.tree.expand_all({keep_buffers})           *nvim-tree.api.tree.expand_all()*
+    Expand all nodes in the tree.
+
+                                 *nvim-tree.api.tree.toggle_gitignore_filter()*
+api.tree.toggle_gitignore_filter()
+    Toggle |nvim-tree.git.ignore| filter.
+
+                                 *nvim-tree.api.tree.toggle_git_clean_filter()*
+api.tree.toggle_git_clean_filter()
+    Toggle |nvim-tree.filters.git_clean| filter.
+
+                                 *nvim-tree.api.tree.toggle_no_buffer_filter()*
+api.tree.toggle_no_buffer_filter()
+    Toggle |nvim-tree.filters.no_buffer| filter.
+
+                                    *nvim-tree.api.tree.toggle_custom_filter()*
+api.tree.toggle_custom_filter()
+    Toggle |nvim-tree.filters.custom| filter.
+
+                                    *nvim-tree.api.tree.toggle_hidden_filter()*
+api.tree.toggle_hidden_filter()
+    Toggle |nvim-tree.filters.dotfiles| filter.
+
+api.tree.toggle_help()                       *nvim-tree.api.tree.toggle_help()*
+    Toggle help view.
 
 - api.fs:                                               *nvim-tree.api.fs*
     - create

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,33 +16,65 @@ 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 ".."
   elseif node.nodes ~= nil then
     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