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/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