feat(api): api.tree.find_file feature parity with open/toggle, convert all commands to API, document commands (#2039)

* fix(#1212): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

* fix(#2011): API find file feature parity

doc/nvim-tree-lua.txt

@@ -103,23 +103,35 @@ Setup should be run in a lua file or in a |lua-heredoc| if using in a vim file.
 
 *:NvimTreeOpen*
 
-    opens the tree. Takes an optional path argument.
+    Opens the tree. See |nvim-tree.api.tree.open()|
+
+    Calls: `api.tree.open({ path = "<arg>" })`
 
 *:NvimTreeClose*
 
-    closes the tree
+    Closes the tree. See |nvim-tree.api.tree.close()|
+
+    Calls: `api.tree.close()`
 
 *:NvimTreeToggle*
 
-    open or close the tree. Takes an optional path argument.
+    Open or close the tree. See |nvim-tree.api.tree.toggle()|
+
+    Calls: `api.tree.toggle({ path = "<arg>" })`
 
 *:NvimTreeFocus*
 
-    open the tree if it is closed, and then focus on the tree
+    Open the tree if it is closed, and then focus on the tree.
+
+    See |nvim-tree.api.tree.toggle()|
+
+    Calls: `api.tree.focus()`
 
 *:NvimTreeRefresh*
 
-    refresh the tree
+    Refresh the tree. See |nvim-tree.api.tree.reload()|
+
+    Calls: `api.tree.reload()`
 
 *:NvimTreeFindFile*
 
@@ -131,6 +143,10 @@ Setup should be run in a lua file or in a |lua-heredoc| if using in a vim file.
 
     Invoke with a bang `:NvimTreeFindFile!` to update the root.
 
+    See |nvim-tree.api.tree.find_file()|
+
+    Calls: `api.tree.find_file { open = true, update_root = <bang> }`
+
 *:NvimTreeFindFileToggle*
 
     close the tree or change the cursor in the tree for the current bufname,
@@ -139,10 +155,18 @@ Setup should be run in a lua file or in a |lua-heredoc| if using in a vim file.
 
     Invoke with a bang `:NvimTreeFindFileToggle!` to update the root.
 
+    See |nvim-tree.api.tree.toggle()|
+
+    Calls: `api.tree.toggle { find_file = true, focus = true, path = "<arg>", update_root = <bang> }`
+
 *:NvimTreeClipboard*
 
     Print clipboard content for both cut and copy
 
+    See |nvim-tree.api.fs.print_clipboard()|
+
+    Calls: `api.fs.print_clipboard()`
+
 *:NvimTreeResize*
 
     Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50`
@@ -155,11 +179,19 @@ Setup should be run in a lua file or in a |lua-heredoc| if using in a vim file.
 
     Collapses the nvim-tree recursively.
 
+    See |nvim-tree.api.tree.collapse_all()|
+
+    Calls: `api.tree.collapse_all(false)`
+
 *:NvimTreeCollapseKeepBuffers*
 
     Collapses the nvim-tree recursively, but keep the directories open, which are
     used in an open buffer.
 
+    See |nvim-tree.api.tree.collapse_all()|
+
+    Calls: `api.tree.collapse_all(true)`
+
 *:NvimTreeGenerateOnAttach*
 
     Creates and opens a new file `/tmp/my_on_attach.lua` containing an
@@ -1266,7 +1298,8 @@ api.tree.open({opts})                              *nvim-tree.api.tree.open()*
       • {path}           (string)         root directory for the tree
       • {current_window} (boolean, false) open the tree in the current window
       • {find_file}      (boolean, false) find the current buffer
-      • {update_root}    (boolean, false) see |nvim-tree.update_focused_file.update_root|
+      • {update_root}    (boolean, false) requires {find_file}, see
+                                          |nvim-tree.update_focused_file.update_root|
 
 api.tree.toggle({opts})                          *nvim-tree.api.tree.toggle()*
     Open or close the tree.
@@ -1278,7 +1311,8 @@ api.tree.toggle({opts})                          *nvim-tree.api.tree.toggle()*
       • {path}           (string)         root directory for the tree
       • {current_window} (boolean, false) open the tree in the current window
       • {find_file}      (boolean, false) find the current buffer
-      • {update_root}    (boolean, false) see |nvim-tree.update_focused_file.update_root|
+      • {update_root}    (boolean, false) requires {find_file}, see
+                                          |nvim-tree.update_focused_file.update_root|
       • {focus}          (boolean, true)  focus the tree when opening
 
 api.tree.close()                                   *nvim-tree.api.tree.close()*
@@ -1329,11 +1363,19 @@ api.tree.get_nodes()                           *nvim-tree.api.tree.get_nodes()*
     Return: ~
       table of nodes
 
-api.tree.find_file({path})                     *nvim-tree.api.tree.find_file()*
+api.tree.find_file({opts})                     *nvim-tree.api.tree.find_file()*
-    Find and focus a file or folder in the tree.
+    Find and focus a file or folder in the tree. Finds current buffer unless
+    otherwise specified.
 
     Parameters: ~
-      • {path} (string) absolute path
+    • {opts} (table) optional parameters with boolean defaults
+
+    Options: ~
+    • {buf}            (string|number)  absolute/relative path OR bufnr to find
+    • {open}           (boolean, false) open the tree
+    • {current_window} (boolean, false) requires {open}, open in the current window
+    • {update_root}    (boolean, false) see |nvim-tree.update_focused_file.update_root|
+    • {focus}          (boolean, false) focus the tree
 
 api.tree.search_node()                       *nvim-tree.api.tree.search_node()*
     Open the search dialogue as per the search_node action.

lua/nvim-tree.lua

@@ -8,13 +8,13 @@ local change_dir = require "nvim-tree.actions.root.change-dir"
 local legacy = require "nvim-tree.legacy"
 local core = require "nvim-tree.core"
 local reloaders = require "nvim-tree.actions.reloaders.reloaders"
-local copy_paste = require "nvim-tree.actions.fs.copy-paste"
-local collapse_all = require "nvim-tree.actions.tree-modifiers.collapse-all"
 local git = require "nvim-tree.git"
 local filters = require "nvim-tree.explorer.filters"
 local modified = require "nvim-tree.modified"
 local notify = require "nvim-tree.notify"
 local keymap_legacy = require "nvim-tree.keymap-legacy"
+local find_file = require "nvim-tree.actions.tree.find-file"
+local open = require "nvim-tree.actions.tree.open"
 
 local _config = {}
 
@@ -24,16 +24,21 @@ local M = {
 }
 
 function M.focus()
-  M.open()
+  open.fn()
   view.focus()
 end
 
-function M.change_root(filepath, bufnr)
+--- Update the tree root to a directory or the directory containing
+--- @param path string relative or absolute
+--- @param bufnr number|nil
+function M.change_root(path, bufnr)
   -- skip if current file is in ignore_list
-  local ft = vim.api.nvim_buf_get_option(bufnr, "filetype") or ""
+  if type(bufnr) == "number" then
-  for _, value in pairs(_config.update_focused_file.ignore_list) do
+    local ft = vim.api.nvim_buf_get_option(bufnr, "filetype") or ""
-    if utils.str_find(filepath, value) or utils.str_find(ft, value) then
+    for _, value in pairs(_config.update_focused_file.ignore_list) do
-      return
+      if utils.str_find(path, value) or utils.str_find(ft, value) then
+        return
+      end
     end
   end
 
@@ -41,32 +46,32 @@ function M.change_root(filepath, bufnr)
   local vim_cwd = vim.fn.getcwd()
 
   -- test if in vim_cwd
-  if utils.path_relative(filepath, vim_cwd) ~= filepath then
+  if utils.path_relative(path, vim_cwd) ~= path then
     if vim_cwd ~= cwd then
       change_dir.fn(vim_cwd)
     end
     return
   end
   -- test if in cwd
-  if utils.path_relative(filepath, cwd) ~= filepath then
+  if utils.path_relative(path, cwd) ~= path then
     return
   end
 
   -- otherwise test M.init_root
-  if _config.prefer_startup_root and utils.path_relative(filepath, M.init_root) ~= filepath then
+  if _config.prefer_startup_root and utils.path_relative(path, M.init_root) ~= path then
     change_dir.fn(M.init_root)
     return
   end
   -- otherwise root_dirs
   for _, dir in pairs(_config.root_dirs) do
     dir = vim.fn.fnamemodify(dir, ":p")
-    if utils.path_relative(filepath, dir) ~= filepath then
+    if utils.path_relative(path, dir) ~= path then
       change_dir.fn(dir)
       return
     end
   end
   -- finally fall back to the folder containing the file
-  change_dir.fn(vim.fn.fnamemodify(filepath, ":p:h"))
+  change_dir.fn(vim.fn.fnamemodify(path, ":p:h"))
 end
 
 function M.open_replacing_current_buffer(cwd)
@@ -113,122 +118,6 @@ local function find_existing_windows()
   end, vim.api.nvim_list_wins())
 end
 
-local function is_file_readable(fname)
-  local stat = vim.loop.fs_stat(fname)
-  return stat and stat.type == "file" and vim.loop.fs_access(fname, "R")
-end
-
-local function find_file(with_open, bufnr, bang)
-  if not with_open and not core.get_explorer() then
-    return
-  end
-
-  bufnr = bufnr or vim.api.nvim_get_current_buf()
-  if not vim.api.nvim_buf_is_valid(bufnr) then
-    return
-  end
-  local bufname = vim.api.nvim_buf_get_name(bufnr)
-  local filepath = utils.canonical_path(vim.fn.fnamemodify(bufname, ":p"))
-  if not is_file_readable(filepath) then
-    return
-  end
-
-  if with_open then
-    M.open()
-  end
-
-  if bang or _config.update_focused_file.update_root then
-    M.change_root(filepath, bufnr)
-  end
-
-  require("nvim-tree.actions.finders.find-file").fn(filepath)
-end
-
----@deprecated 2022/12/16
-function M.find_file(with_open, bufnr, bang)
-  vim.notify_once(
-    "require('nvim-tree').find_file is not API and will soon be unavailable. Please use api.tree.find_file as per :help nvim-tree-api",
-    vim.log.levels.WARN
-  )
-  find_file(with_open, bufnr, bang)
-end
-
----Open the tree, focusing if already open.
----@param opts ApiTreeOpenOpts|nil|string
-function M.open(opts)
-  -- legacy arguments
-  if type(opts) == "string" then
-    opts = {
-      path = opts,
-    }
-  end
-
-  opts = opts or {}
-
-  local previous_buf = vim.api.nvim_get_current_buf()
-
-  -- 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(opts)
-  end
-
-  if _config.update_focused_file.enable or opts.find_file then
-    find_file(false, previous_buf, opts.update_root)
-  end
-end
-
----Toggle the tree.
----@param opts ApiTreeToggleOpts|nil|boolean
-function M.toggle(opts, no_focus, cwd, bang)
-  -- legacy arguments
-  if type(opts) == "boolean" then
-    opts = {
-      find_file = opts,
-    }
-    if type(cwd) == "string" then
-      opts.path = cwd
-    end
-    if type(no_focus) == "boolean" then
-      opts.focus = not no_focus
-    end
-    if type(bang) == "boolean" then
-      opts.update_root = bang
-    end
-  end
-
-  opts = opts or {}
-
-  -- defaults
-  if opts.focus == nil then
-    opts.focus = true
-  end
-
-  -- 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 { 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 not opts.focus then
-      vim.cmd "noautocmd wincmd p"
-    end
-  end
-end
-
 M.resize = view.resize
 
 function M.open_on_directory()
@@ -331,7 +220,7 @@ function M.on_enter(netrw_disabled)
     if should_focus_other_window then
       vim.cmd "noautocmd wincmd p"
       if should_find then
-        find_file(false)
+        find_file.fn()
       end
     end
   end
@@ -355,27 +244,37 @@ end
 
 local function setup_vim_commands()
   vim.api.nvim_create_user_command("NvimTreeOpen", function(res)
-    M.open { path = res.args }
+    require("nvim-tree.api").tree.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("NvimTreeClose", function()
+    require("nvim-tree.api").tree.close()
+  end, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeToggle", function(res)
-    M.toggle { find_file = false, focus = true, path = res.args, update_root = false }
+    require("nvim-tree.api").tree.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("NvimTreeFocus", function()
-  vim.api.nvim_create_user_command("NvimTreeRefresh", reloaders.reload_explorer, { bar = true })
+    require("nvim-tree.api").tree.focus()
-  vim.api.nvim_create_user_command("NvimTreeClipboard", copy_paste.print_clipboard, { bar = true })
+  end, { bar = true })
+  vim.api.nvim_create_user_command("NvimTreeRefresh", function()
+    require("nvim-tree.api").tree.reload()
+  end, { bar = true })
+  vim.api.nvim_create_user_command("NvimTreeClipboard", function()
+    require("nvim-tree.api").fs.print_clipboard()
+  end, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeFindFile", function(res)
-    find_file(true, nil, res.bang)
+    require("nvim-tree.api").tree.find_file { open = true, update_root = res.bang }
   end, { bang = true, bar = true })
   vim.api.nvim_create_user_command("NvimTreeFindFileToggle", function(res)
-    M.toggle { find_file = true, focus = true, path = res.args, update_root = res.bang }
+    require("nvim-tree.api").tree.toggle { find_file = true, focus = true, 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)
   end, { nargs = 1, bar = true })
-  vim.api.nvim_create_user_command("NvimTreeCollapse", collapse_all.fn, { bar = true })
+  vim.api.nvim_create_user_command("NvimTreeCollapse", function()
+    require("nvim-tree.api").tree.collapse_all(false)
+  end, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeCollapseKeepBuffers", function()
-    collapse_all.fn(true)
+    require("nvim-tree.api").tree.collapse_all(true)
   end, { bar = true })
   vim.api.nvim_create_user_command("NvimTreeGenerateOnAttach", keymap_legacy.cmd_generate_on_attach, {})
 end
@@ -384,7 +283,7 @@ function M.change_dir(name)
   change_dir.fn(name)
 
   if _config.update_focused_file.enable then
-    find_file(false)
+    find_file.fn()
   end
 end
 
@@ -473,7 +372,7 @@ local function setup_autocommands(opts)
     create_nvim_tree_autocmd("BufEnter", {
       callback = function()
         utils.debounce("BufEnter:find_file", opts.view.debounce_delay, function()
-          find_file(false)
+          find_file.fn()
         end)
       end,
     })

lua/nvim-tree/actions/finders/find-file.lua

@@ -11,28 +11,28 @@ local M = {}
 local running = {}
 
 ---Find a path in the tree, expand it and focus it
----@param fname string full path
+---@param path string relative or absolute
-function M.fn(fname)
+function M.fn(path)
   if not core.get_explorer() or not view.is_visible() then
     return
   end
 
   -- always match against the real path
-  local fname_real = vim.loop.fs_realpath(fname)
+  local path_real = vim.loop.fs_realpath(path)
-  if not fname_real then
+  if not path_real then
     return
   end
 
-  if running[fname_real] then
+  if running[path_real] then
     return
   end
-  running[fname_real] = true
+  running[path_real] = true
 
-  local profile = log.profile_start("find file %s", fname_real)
+  local profile = log.profile_start("find file %s", path_real)
 
   -- we cannot wait for watchers to populate a new node
-  if utils.get_node_from_path(fname_real) == nil then
+  if utils.get_node_from_path(path_real) == nil then
-    reload.refresh_nodes_for_path(vim.fn.fnamemodify(fname_real, ":h"))
+    reload.refresh_nodes_for_path(vim.fn.fnamemodify(path_real, ":h"))
   end
 
   local line = core.get_nodes_starting_line()
@@ -41,7 +41,7 @@ function M.fn(fname)
 
   local found = Iterator.builder(core.get_explorer().nodes)
     :matcher(function(node)
-      return node.absolute_path == fname_real or node.link_to == fname_real
+      return node.absolute_path == path_real or node.link_to == path_real
     end)
     :applier(function(node)
       line = line + 1
@@ -51,8 +51,8 @@ function M.fn(fname)
       end
       table.insert(absolute_paths_searched, node.absolute_path)
 
-      local abs_match = vim.startswith(fname_real, node.absolute_path .. utils.path_separator)
+      local abs_match = vim.startswith(path_real, node.absolute_path .. utils.path_separator)
-      local link_match = node.link_to and vim.startswith(fname_real, node.link_to .. utils.path_separator)
+      local link_match = node.link_to and vim.startswith(path_real, node.link_to .. utils.path_separator)
 
       if abs_match or link_match then
         node.open = true
@@ -71,7 +71,7 @@ function M.fn(fname)
     view.set_cursor { line, 0 }
   end
 
-  running[fname_real] = false
+  running[path_real] = false
 
   log.profile_end(profile)
 end

lua/nvim-tree/actions/init.lua

@@ -11,6 +11,9 @@ function M.setup(opts)
   require("nvim-tree.actions.fs.remove-file").setup(opts)
   require("nvim-tree.actions.fs.copy-paste").setup(opts)
   require("nvim-tree.actions.tree-modifiers.expand-all").setup(opts)
+  require("nvim-tree.actions.tree.find-file").setup(opts)
+  require("nvim-tree.actions.tree.open").setup(opts)
+  require("nvim-tree.actions.tree.toggle").setup(opts)
 end
 
 return M

lua/nvim-tree/actions/tree/find-file.lua

@@ -0,0 +1,70 @@
+local core = require "nvim-tree.core"
+local lib = require "nvim-tree.lib"
+local view = require "nvim-tree.view"
+local finders_find_file = require "nvim-tree.actions.finders.find-file"
+
+local M = {}
+
+--- Find file or buffer
+--- @param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf
+function M.fn(opts)
+  -- legacy arguments
+  if type(opts) == "string" then
+    opts = {
+      buf = opts,
+    }
+  end
+  opts = opts or {}
+
+  -- do nothing if closed and open not requested
+  if not opts.open and not core.get_explorer() then
+    return
+  end
+
+  local bufnr, path
+
+  -- (optional) buffer number and path
+  if type(opts.buf) == "nil" then
+    bufnr = vim.api.nvim_get_current_buf()
+    path = vim.api.nvim_buf_get_name(bufnr)
+  elseif type(opts.buf) == "number" then
+    if not vim.api.nvim_buf_is_valid(opts.buf) then
+      return
+    end
+    bufnr = tonumber(opts.buf)
+    path = vim.api.nvim_buf_get_name(bufnr)
+  elseif type(opts.buf) == "string" then
+    bufnr = nil
+    path = tostring(opts.buf)
+  else
+    return
+  end
+
+  if view.is_visible() then
+    -- focus
+    if opts.focus then
+      lib.set_target_win()
+      view.focus()
+    end
+  elseif opts.open then
+    -- open
+    lib.open { current_window = opts.current_window }
+    if not opts.focus then
+      vim.cmd "noautocmd wincmd p"
+    end
+  end
+
+  -- update root
+  if opts.update_root or M.config.update_focused_file.update_root then
+    require("nvim-tree").change_root(path, bufnr)
+  end
+
+  -- find
+  finders_find_file.fn(path)
+end
+
+function M.setup(opts)
+  M.config = opts or {}
+end
+
+return M

lua/nvim-tree/actions/tree/open.lua

@@ -0,0 +1,51 @@
+local lib = require "nvim-tree.lib"
+local view = require "nvim-tree.view"
+local finders_find_file = require "nvim-tree.actions.finders.find-file"
+
+local M = {}
+
+---Open the tree, focusing if already open.
+---@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path
+function M.fn(opts)
+  -- legacy arguments
+  if type(opts) == "string" then
+    opts = {
+      path = opts,
+    }
+  end
+  opts = opts or {}
+
+  local previous_buf = vim.api.nvim_get_current_buf()
+  local previous_path = vim.api.nvim_buf_get_name(previous_buf)
+
+  -- sanitise path
+  if type(opts.path) ~= "string" or vim.fn.isdirectory(opts.path) == 0 then
+    opts.path = nil
+  end
+
+  if view.is_visible() then
+    -- focus
+    lib.set_target_win()
+    view.focus()
+  else
+    -- open
+    lib.open { path = opts.path, current_window = opts.current_window }
+  end
+
+  -- find file
+  if M.config.update_focused_file.enable or opts.find_file then
+    -- update root
+    if opts.update_root then
+      require("nvim-tree").change_root(previous_path, previous_buf)
+    end
+
+    -- find
+    finders_find_file.fn(previous_path)
+  end
+end
+
+function M.setup(opts)
+  M.config = opts or {}
+end
+
+return M

lua/nvim-tree/actions/tree/toggle.lua

@@ -0,0 +1,72 @@
+local lib = require "nvim-tree.lib"
+local view = require "nvim-tree.view"
+local finders_find_file = require "nvim-tree.actions.finders.find-file"
+
+local M = {}
+
+---Toggle the tree.
+---@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file
+---@param no_focus string|nil legacy -> opts.focus
+---@param cwd boolean|nil legacy -> opts.path
+---@param bang boolean|nil legacy -> opts.update_root
+function M.fn(opts, no_focus, cwd, bang)
+  -- legacy arguments
+  if type(opts) == "boolean" then
+    opts = {
+      find_file = opts,
+    }
+    if type(cwd) == "string" then
+      opts.path = cwd
+    end
+    if type(no_focus) == "boolean" then
+      opts.focus = not no_focus
+    end
+    if type(bang) == "boolean" then
+      opts.update_root = bang
+    end
+  end
+  opts = opts or {}
+
+  -- defaults
+  if opts.focus == nil then
+    opts.focus = true
+  end
+
+  local previous_buf = vim.api.nvim_get_current_buf()
+  local previous_path = vim.api.nvim_buf_get_name(previous_buf)
+
+  -- sanitise path
+  if type(opts.path) ~= "string" or vim.fn.isdirectory(opts.path) == 0 then
+    opts.path = nil
+  end
+
+  if view.is_visible() then
+    -- close
+    view.close()
+  else
+    -- open
+    lib.open { path = opts.path, current_window = opts.current_window }
+
+    -- find file
+    if M.config.update_focused_file.enable or opts.find_file then
+      -- update root
+      if opts.update_root then
+        require("nvim-tree").change_root(previous_path, previous_buf)
+      end
+
+      -- find
+      finders_find_file.fn(previous_path)
+    end
+
+    -- restore focus
+    if not opts.focus then
+      vim.cmd "noautocmd wincmd p"
+    end
+  end
+end
+
+function M.setup(opts)
+  M.config = opts or {}
+end
+
+return M

lua/nvim-tree/api.lua

@@ -22,9 +22,7 @@ end
 ---@field find_file boolean|nil default false
 ---@field update_root boolean|nil default false
 
-Api.tree.open = function(...)
+Api.tree.open = require("nvim-tree.actions.tree.open").fn
-  require("nvim-tree").open(...)
-end
 
 ---@class ApiTreeToggleOpts
 ---@field path string|nil
@@ -33,9 +31,7 @@ end
 ---@field update_root boolean|nil default false
 ---@field focus boolean|nil default true
 
-Api.tree.toggle = function(...)
+Api.tree.toggle = require("nvim-tree.actions.tree.toggle").fn
-  require("nvim-tree").toggle(...)
-end
 
 Api.tree.close = require("nvim-tree.view").close
 
@@ -67,7 +63,14 @@ 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
+---@class ApiTreeFindFileOpts
+---@field buf string|number|nil
+---@field open boolean|nil default false
+---@field current_window boolean|nil default false
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default false
+
+Api.tree.find_file = require("nvim-tree.actions.tree.find-file").fn
 
 Api.tree.search_node = require("nvim-tree.actions.finders.search-node").fn
 

lua/nvim-tree/lib.lua

@@ -4,6 +4,10 @@ local core = require "nvim-tree.core"
 local utils = require "nvim-tree.utils"
 local events = require "nvim-tree.events"
 
+---@class LibOpenOpts
+---@field path string|nil path
+---@field current_window boolean|nil default false
+
 local M = {
   target_winid = nil,
 }
@@ -152,7 +156,7 @@ function M.prompt(prompt_input, prompt_select, items_short, items_long, callback
 end
 
 ---Open the tree, initialising as needed. Maybe hijack the current buffer.
----@param opts ApiTreeOpenOpts|string|nil legacy case opts is path string
+---@param opts LibOpenOpts|nil
 function M.open(opts)
   opts = opts or {}