feat(#2789): add optional function expand_until to api.tree.expand_all and api.node.expand (#3166)

* feat: Allow to expand nodes until certain condition is met

* Fix warnings

* Restore original position of edit function

* Rename field to match the api method name

* Rename ApiTreeExpandAllOpts to ApiTreeExpandOpts

* Remove toggle_descend_until

* Remove redundant empty line

* Update :help for changed methods

* Fix partial expansion of grouped nodes

* Fix lint error

* Fix linting error

* Fix incorrect open/close indicator state

* Update docs

* Rename descend_until option to expand_until

* Always check directory expansion limit

* Fix linter errors

* Ignore unused param warning

* Apply suggestions from code review

* simplify MAX_FOLDER_DISCOVERY warning

* fix bad comment whitespace

---------

Co-authored-by: ghostbuster91 <ghostbuster91@users.noreply.github.com>
Co-authored-by: Alexander Courtis <alex@courtis.org>

doc/nvim-tree-lua.txt

@@ -1841,11 +1841,17 @@ tree.collapse_all({opts})                  *nvim-tree-api.tree.collapse_all()*
     Options: ~
       • {keep_buffers} (boolean) do not collapse nodes with open buffers.
 
-tree.expand_all({node})                      *nvim-tree-api.tree.expand_all()*
+tree.expand_all({node}, {opts})              *nvim-tree-api.tree.expand_all()*
     Recursively expand all nodes under the tree root or specified folder.
 
     Parameters: ~
       • {node} (Node|nil) folder
+      • {opts} (ApiTreeExpandOpts) optional parameters
+
+    Options: ~
+      • {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.
 
                                   *nvim-tree-api.tree.toggle_enable_filters()*
 tree.toggle_enable_filters()
@@ -2279,12 +2285,18 @@ node.buffer.wipe({node}, {opts})            *nvim-tree-api.node.buffer.wipe()*
     Options: ~
       • {force} (boolean) wipe even if buffer is modified, default false
 
-node.expand({node})                              *nvim-tree-api.node.expand()*
+node.expand({node}, {opts})                      *nvim-tree-api.node.expand()*
     Recursively expand all nodes under a directory or a file's parent
     directory.
 
     Parameters: ~
       • {node} (Node|nil) file or folder
+      • {opts} (ApiTreeExpandOpts) optional parameters
+
+    Options: ~
+      • {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.
 
 node.collapse({node}, {opts})                  *nvim-tree-api.node.collapse()*
     Collapse the tree under a directory or a file's parent directory.