doc(#2934): add nvim_tree.Config meta classes, add nvim_tree.api. meta classes

alex-courtis · alex-courtis · commit 6a867ffc62c5 · 2026-01-05T12:15:07.000+11:00
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
@@ -621,7 +621,7 @@ local ACCEPTED_ENUMS = {
   },
 }
 
----@param conf table|nil
+---@param conf? nvim_tree.Config
 local function validate_options(conf)
   local msg
 
@@ -726,7 +726,7 @@ function M.purge_all_state()
   require("nvim-tree.watcher").purge_watchers()
 end
 
----@param conf table|nil
+---@param conf? nvim_tree.Config
 function M.setup(conf)
   if vim.fn.has("nvim-0.9") == 0 then
     notify.warn("nvim-tree.lua requires Neovim 0.9 or higher")
diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
@@ -1,6 +1,59 @@
 ---@meta
 error("Cannot require a meta file")
 
+--
+-- API Options
+--
+
+---@class nvim_tree.api.TreeOpenOpts
+---@field path? string root directory for the tree
+---@field current_window? boolean open the tree in the current window
+---@field winid? number open the tree in the specified winid, overrides current_window
+---@field find_file? boolean find the current buffer
+---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree when opening, default true
+
+---@class nvim_tree.api.TreeToggleOpts
+---@field path? string root directory for the tree
+---@field current_window? boolean open the tree in the current window
+---@field winid? number open the tree in the specified |winid|, overrides current_window
+---@field find_file? boolean find the current buffer
+---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree when opening, default true
+
+---@class nvim_tree.api.TreeResizeOpts
+---@field width? string|function|number|table new |nvim-tree.view.width| value
+---@field absolute? number set the width
+---@field relative? number relative width adjustment
+
+---@class nvim_tree.api.TreeFindFileOpts
+---@field buf? string|number absolute/relative path OR bufnr to find
+---@field open? boolean open the tree if necessary
+---@field current_window? boolean requires open, open in the current window
+---@field winid? number open the tree in the specified |winid|, overrides current_window
+---@field update_root? boolean see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree
+
+---@class nvim_tree.api.CollapseOpts
+---@field keep_buffers? boolean do not collapse nodes with open buffers
+
+---@class nvim_tree.api.TreeExpandOpts
+---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded.
+
+---@class nvim_tree.api.TreeIsVisibleOpts
+---@field tabpage? number as per |nvim_get_current_tabpage()|
+---@field any_tabpage? boolean visible on any tab, default false
+
+---@class nvim_tree.api.TreeWinIdOpts
+---@field tabpage? number tabpage, 0 or nil for current, default nil
+
+---@class nvim_tree.api.NodeEditOpts
+---@field quit_on_open? boolean quits the tree when opening the file
+---@field focus? boolean keep focus in the tree when opening the file
+
+---@class nvim_tree.api.NodeBufferOpts
+---@field force? boolean delete/wipe even if buffer is modified, default false
+
 --
 -- Nodes
 --
diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua
diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua
@@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify")
 local M = {}
 
 ---@param node Node
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts nvim_tree.api.NodeBufferOpts|nil
 ---@return nil
 function M.delete(node, opts)
   M.delete_buffer("delete", node.absolute_path, opts)
 end
 
 ---@param node Node
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts nvim_tree.api.NodeBufferOpts|nil
 ---@return nil
 function M.wipe(node, opts)
   M.delete_buffer("wipe", node.absolute_path, opts)
@@ -21,7 +21,7 @@ end
 
 ---@param mode ApiNodeDeleteWipeBufferMode
 ---@param filename string
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts nvim_tree.api.NodeBufferOpts|nil
 ---@return nil
 function M.delete_buffer(mode, filename, opts)
   if type(mode) ~= "string" then
diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua
@@ -6,7 +6,7 @@ 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
+---@param opts nvim_tree.api.TreeFindFileOpts|nil|boolean legacy -> opts.buf
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
@@ -26,7 +26,7 @@ end
 
 ---Collapse a node, root if nil
 ---@param node Node?
----@param opts ApiCollapseOpts
+---@param opts nvim_tree.api.CollapseOpts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
   if not explorer then
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers
+---@param opts nvim_tree.api.CollapseOpts|boolean|nil legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -73,7 +73,7 @@ function M.all(opts)
 end
 
 ---@param node Node
----@param opts ApiCollapseOpts?
+---@param opts nvim_tree.api.CollapseOpts?
 function M.node(node, opts)
   collapse(node, opts or {})
 end
diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
@@ -125,7 +125,7 @@ local function gen_iterator(should_descend)
 end
 
 ---@param node Node?
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.TreeExpandOpts?
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -141,14 +141,14 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.TreeExpandOpts?
 function M.all(node, expand_opts)
   expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
 end
 
 ---Expand the directory node or parent node
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.TreeExpandOpts?
 function M.node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua
@@ -5,7 +5,7 @@ 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
+---@param opts nvim_tree.api.TreeOpenOpts|nil|string legacy -> opts.path
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua
@@ -3,7 +3,7 @@ local view = require("nvim-tree.view")
 local M = {}
 
 ---Resize the tree, persisting the new size.
----@param opts ApiTreeResizeOpts|nil
+---@param opts nvim_tree.api.TreeResizeOpts|nil
 function M.fn(opts)
   if opts == nil then
     -- reset to config values
diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua
@@ -5,7 +5,7 @@ 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 opts nvim_tree.api.TreeToggleOpts|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
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
@@ -14,6 +14,18 @@ local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
+-- Backwards compatibility aliases for renamed classes
+---@alias ApiTreeOpenOpts nvim_tree.api.TreeOpenOpts
+---@alias ApiTreeToggleOpts nvim_tree.api.TreeToggleOpts
+---@alias ApiTreeResizeOpts nvim_tree.api.TreeResizeOpts
+---@alias ApiTreeFindFileOpts nvim_tree.api.TreeFindFileOpts
+---@alias ApiCollapseOpts nvim_tree.api.CollapseOpts
+---@alias ApiTreeExpandOpts nvim_tree.api.TreeExpandOpts
+---@alias ApiTreeIsVisibleOpts nvim_tree.api.TreeIsVisibleOpts
+---@alias ApiTreeWinIdOpts nvim_tree.api.TreeWinIdOpts
+---@alias NodeEditOpts nvim_tree.api.NodeEditOpts
+---@alias ApiNodeDeleteWipeBufferOpts nvim_tree.api.NodeBufferOpts
+
 local Api = {
   tree = {},
   node = {
@@ -123,35 +135,15 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
----@class ApiTreeOpenOpts
----@field path string|nil path
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
-
 Api.tree.open = wrap(actions.tree.open.fn)
 Api.tree.focus = Api.tree.open
 
----@class ApiTreeToggleOpts
----@field path string|nil
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
----@field focus boolean|nil default true
-
 Api.tree.toggle = wrap(actions.tree.toggle.fn)
 Api.tree.close = wrap(view.close)
 Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
 Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
 Api.tree.reload = wrap_explorer("reload_explorer")
 
----@class ApiTreeResizeOpts
----@field width string|function|number|table|nil
----@field absolute number|nil
----@field relative number|nil
-
 Api.tree.resize = wrap(actions.tree.resize.fn)
 
 Api.tree.change_root = wrap(function(...)
@@ -179,25 +171,11 @@ Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
 Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
 Api.tree.get_nodes = wrap_explorer("get_nodes")
 
----@class ApiTreeFindFileOpts
----@field buf string|number|nil
----@field open boolean|nil default false
----@field current_window boolean|nil default false
----@field winid number|nil
----@field update_root boolean|nil default false
----@field focus boolean|nil default false
-
 Api.tree.find_file = wrap(actions.tree.find_file.fn)
 Api.tree.search_node = wrap(actions.finders.search_node.fn)
 
----@class ApiCollapseOpts
----@field keep_buffers boolean|nil default false
-
 Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
 
----@class ApiTreeExpandOpts
----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
-
 Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
 Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
 Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
@@ -209,15 +187,8 @@ Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggl
 Api.tree.toggle_help = wrap(help.toggle)
 Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
 
----@class ApiTreeIsVisibleOpts
----@field tabpage number|nil
----@field any_tabpage boolean|nil default false
-
 Api.tree.is_visible = wrap(view.is_visible)
 
----@class ApiTreeWinIdOpts
----@field tabpage number|nil default nil
-
 Api.tree.winid = wrap(view.winid)
 
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
@@ -238,13 +209,9 @@ Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filenam
 Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
 Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
 ---
----@class NodeEditOpts
----@field quit_on_open boolean|nil default false
----@field focus boolean|nil default true
-
 ---@param mode string
 ---@param node Node
----@param edit_opts NodeEditOpts?
+---@param edit_opts nvim_tree.api.NodeEditOpts?
 local function edit(mode, node, edit_opts)
   local file_link = node:as(FileLinkNode)
   local path = file_link and file_link.link_to or node.absolute_path
@@ -272,10 +239,10 @@ end
 
 ---@param mode string
 ---@param toggle_group boolean?
----@return fun(node: Node, edit_opts: NodeEditOpts?)
+---@return fun(node: Node, edit_opts: nvim_tree.api.NodeEditOpts?)
 local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node
-  ---@param edit_opts NodeEditOpts?
+  ---@param edit_opts nvim_tree.api.NodeEditOpts?
   return function(node, edit_opts)
     local root = node:as(RootNode)
     local dir = node:as(DirectoryNode)
@@ -330,9 +297,6 @@ Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev"
 Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
 Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
----@class ApiNodeDeleteWipeBufferOpts
----@field force boolean|nil default false
-
 Api.node.buffer.delete = wrap_node(function(node, opts)
   actions.node.buffer.delete(node, opts)
 end)
diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua
@@ -437,7 +437,7 @@ function M.abandon_all_windows()
   end
 end
 
----@param opts table|nil
+---@param opts? nvim_tree.api.TreeIsVisibleOpts
 ---@return boolean
 function M.is_visible(opts)
   if opts and opts.tabpage then
@@ -486,7 +486,7 @@ function M.focus(winnr, open_if_closed)
 end
 
 --- Retrieve the winid of the open tree.
----@param opts ApiTreeWinIdOpts|nil
+---@param opts nvim_tree.api.TreeWinIdOpts|nil
 ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
 function M.winid(opts)
   local tabpage = opts and opts.tabpage
