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

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
-function M.fn(fname)
+---@param path string relative or absolute
+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)
-  if not fname_real then
+  local path_real = vim.loop.fs_realpath(path)
+  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
-    reload.refresh_nodes_for_path(vim.fn.fnamemodify(fname_real, ":h"))
+  if utils.get_node_from_path(path_real) == nil then
+    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 link_match = node.link_to and vim.startswith(fname_real, node.link_to .. 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(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(...)
-  require("nvim-tree").open(...)
-end
+Api.tree.open = require("nvim-tree.actions.tree.open").fn
 
 ---@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(...)
-  require("nvim-tree").toggle(...)
-end
+Api.tree.toggle = require("nvim-tree.actions.tree.toggle").fn
 
 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 {}