refactor(#3255): all API is lazily loaded (#3287)

* refactor(#3255): wire node.navigate.sibling API impl directly to functions

* refactor(#3255): wire fs.rename API impl directly to functions

* refactor(#3255): wire node.navigate.parent API impl directly to functions

* refactor(#3255): wire remaining node.navigate API impl directly to functions

* refactor(#3255): wire node.open API impl directly to functions, move edit and open_or_expand_or_dir_up to open-file

* refactor(#3255): wire tree.change_root API impl directly to a function in new action module change-dir

* refactor(#3255): lazy post requires, split into formatted groups

* refactor(#3255): all post are lazy

* refactor(#3255): all post are wrapped consistently

* refactor(#3255): all pre are lazy

* refactor(#3255): move Event to meta

* refactor(#3255): ensure all args passed to api

* refactor(#3255): ensure all args passed to api, fix incorrectly documented api interface

* refactor(#3255): ensure all args passed to api, fix incorrectly documented api interface

* refactor(#3255): ensure all args passed to api

* refactor(#3255): add visual mode wrappers

* refactor(#3255): define @enum nvim_tree.api.events.Event

* refactor(#3255): merge api pre and post

* refactor(#3255): merge api pre and post

* refactor(#3255): merge api pre and post

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -2420,7 +2420,7 @@ subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
     Register a handler for an event, see |nvim-tree-events|.
 
     Parameters: ~
-      • {event_type}  (`string`) |nvim_tree_events_kind|
+      • {event_type}  (`nvim_tree.api.events.Event`) |nvim_tree_events_kind|
       • {callback}    (`fun(payload: table?)`)
 
 
@@ -2616,9 +2616,12 @@ bulk.trash()                                *nvim_tree.api.marks.bulk.trash()*
 clear()                                          *nvim_tree.api.marks.clear()*
     Clear all marks.
 
-get()                                              *nvim_tree.api.marks.get()*
+get({node})                                        *nvim_tree.api.marks.get()*
     Return the node if it is marked.
 
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) file or directory
+
     Return: ~
         (`nvim_tree.api.Node?`)
 
@@ -2828,64 +2831,39 @@ open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
+open.horizontal({node})                 *nvim_tree.api.node.open.horizontal()*
     Open file in a new horizontal split.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
                               *nvim_tree.api.node.open.horizontal_no_picker()*
-open.horizontal_no_picker({node}, {opts})
+open.horizontal_no_picker({node})
     Open file in a new horizontal split without using the window picker.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
                                   *nvim_tree.api.node.open.no_window_picker()*
-open.no_window_picker({node}, {opts})
+open.no_window_picker({node})
     Open file without using the window picker.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
-open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
+open.preview({node})                       *nvim_tree.api.node.open.preview()*
     Open file with |'bufhidden'| set to `delete`.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
                                  *nvim_tree.api.node.open.preview_no_picker()*
-open.preview_no_picker({node}, {opts})
+open.preview_no_picker({node})
     Open file with |'bufhidden'| set to `delete` without using the window
     picker.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
                                *nvim_tree.api.node.open.replace_tree_buffer()*
 open.replace_tree_buffer({node})
@@ -2894,16 +2872,11 @@ open.replace_tree_buffer({node})
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
 
-open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
+open.tab({node})                               *nvim_tree.api.node.open.tab()*
     Open file in a new tab.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
 open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
     Switch to tab containing window with selected file if it exists. Open file
@@ -2913,40 +2886,25 @@ open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                 *nvim_tree.api.node.open.toggle_group_empty()*
-open.toggle_group_empty({node}, {opts})
+open.toggle_group_empty({node})
     Toggle |nvim_tree.config.renderer| {group_empty} for a directory. Needs
     {group_empty} set.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
-open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
+open.vertical({node})                     *nvim_tree.api.node.open.vertical()*
     Open file in a new vertical split.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
                                 *nvim_tree.api.node.open.vertical_no_picker()*
-open.vertical_no_picker({node}, {opts})
+open.vertical_no_picker({node})
     Open file in a new vertical split without using the window picker.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
-      • {opts}  (`table?`) optional
-                • {quit_on_open}? (`boolean`, default: false) Quits the tree
-                  when opening the file.
-                • {focus}? (`boolean`, default: false) Keep focus in the tree
-                  when opening the file.
 
 run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
     Enter |cmdline| with the full path of the node and the cursor at the start

lua/nvim-tree.lua

@@ -141,17 +141,6 @@ local function manage_netrw()
   end
 end
 
----@param name string|nil
-function M.change_dir(name)
-  if name then
-    explorer_fn("change_dir", name)
-  end
-
-  if config.g.update_focused_file.update_root.enable then
-    actions.tree.find_file.fn()
-  end
-end
-
 local function setup_autocommands()
   local augroup_id = vim.api.nvim_create_augroup("NvimTree", { clear = true })
   local function create_nvim_tree_autocmd(name, custom_opts)
@@ -180,7 +169,7 @@ local function setup_autocommands()
   if config.g.sync_root_with_cwd then
     create_nvim_tree_autocmd("DirChanged", {
       callback = function()
-        M.change_dir(vim.loop.cwd())
+        actions.tree.change_dir.fn(vim.loop.cwd())
       end,
     })
   end
@@ -320,7 +309,7 @@ function M.setup(config_user)
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
 
-  require("nvim-tree.api.impl.post").hydrate(api)
+  require("nvim-tree.api.impl").hydrate_post_setup(api)
 end
 
 vim.g.NvimTreeRequired = 1

lua/nvim-tree/_meta/api/events.lua

@@ -1,10 +1,29 @@
 ---@meta
 local nvim_tree = { api = { events = {} } }
 
+---@enum nvim_tree.api.events.Event
+nvim_tree.api.events.Event = {
+  Ready = "Ready",
+  WillRenameNode = "WillRenameNode",
+  NodeRenamed = "NodeRenamed",
+  TreePreOpen = "TreePreOpen",
+  TreeOpen = "TreeOpen",
+  TreeClose = "TreeClose",
+  WillCreateFile = "WillCreateFile",
+  FileCreated = "FileCreated",
+  WillRemoveFile = "WillRemoveFile",
+  FileRemoved = "FileRemoved",
+  FolderCreated = "FolderCreated",
+  FolderRemoved = "FolderRemoved",
+  Resize = "Resize",
+  TreeAttachedPost = "TreeAttachedPost",
+  TreeRendered = "TreeRendered",
+}
+
 ---
 ---Register a handler for an event, see [nvim-tree-events].
 ---
----@param event_type string [nvim_tree_events_kind]
+---@param event_type nvim_tree.api.events.Event [nvim_tree_events_kind]
 ---@param callback fun(payload: table?)
 function nvim_tree.api.events.subscribe(event_type, callback) end
 

lua/nvim-tree/_meta/api/marks.lua

@@ -4,8 +4,9 @@ local nvim_tree = { api = { marks = {} } }
 ---
 ---Return the node if it is marked.
 ---
+---@param node? nvim_tree.api.Node file or directory
 ---@return nvim_tree.api.Node?
-function nvim_tree.api.marks.get() end
+function nvim_tree.api.marks.get(node) end
 
 ---
 ---Retrieve all marked nodes.

lua/nvim-tree/_meta/api/node.lua

@@ -29,36 +29,31 @@ function nvim_tree.api.node.open.edit(node, opts) end
 ---Open file in a new horizontal split.
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal(node, opts) end
+function nvim_tree.api.node.open.horizontal(node) end
 
 ---
 ---Open file in a new horizontal split without using the window picker.
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
+function nvim_tree.api.node.open.horizontal_no_picker(node) end
 
 ---
 ---Open file without using the window picker.
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.no_window_picker(node, opts) end
+function nvim_tree.api.node.open.no_window_picker(node) end
 
 ---
 ---Open file with ['bufhidden'] set to `delete`.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview(node, opts) end
+function nvim_tree.api.node.open.preview(node) end
 
 ---
 ---Open file with ['bufhidden'] set to `delete` without using the window picker.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview_no_picker(node, opts) end
+function nvim_tree.api.node.open.preview_no_picker(node) end
 
 ---
 ---Open file in place: in the nvim-tree window.
@@ -70,8 +65,7 @@ function nvim_tree.api.node.open.replace_tree_buffer(node) end
 ---Open file in a new tab.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.tab(node, opts) end
+function nvim_tree.api.node.open.tab(node) end
 
 ---
 ---Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
@@ -83,22 +77,19 @@ function nvim_tree.api.node.open.tab_drop(node) end
 ---Toggle [nvim_tree.config.renderer] {group_empty} for a directory. Needs {group_empty} set.
 ---
 ---@param node? nvim_tree.api.Node directory
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
+function nvim_tree.api.node.open.toggle_group_empty(node) end
 
 ---
 ---Open file in a new vertical split.
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical(node, opts) end
+function nvim_tree.api.node.open.vertical(node) end
 
 ---
 ---Open file in a new vertical split without using the window picker.
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
+function nvim_tree.api.node.open.vertical_no_picker(node) end
 
 ---
 ---@class nvim_tree.api.node.buffer.RemoveOpts