feat: Allow to expand until certain condition is met

[ghostbuster91]

This is my attempt to solve #2789

With this change I can now define the following mapping:

local function stop_expansion(_, node)
    return false, stop_expansion
end
local function expand_until_non_single(count, node)
    local cwd = node.link_to or node.absolute_path
    local handle = vim.loop.fs_scandir(cwd)
    if not handle then
        return false, stop_expansion
    end
    local status = git.load_project_status(cwd)
    populate_children(handle, cwd, node, status)
    local child_folder_only = explorer_node.has_one_child_folder(node) and node.nodes[1]
    if count > 1 and not child_folder_only then
        return true, stop_expansion
    elseif child_folder_only then
        return true, expand_until_non_single
    else
        return false, stop_expansion
    end
end
map('n', 'E', function()
    api.tree.expand_all(nil, expand_until_non_single)
end, opts("Expand until not single"))

This works as expected however it has some downsides:

1. the api is very flexible but at the same time quite complex. I had to do it in this way because the expand_all function will not expand the last directory. It stops as soon as should_expand returns false but I wanted the last directory to be expanded.
2. I had to copy populate_children method which is not a part of public api replaced with explorer.explore(node, status)

Btw if this got accepted in some form I am going to replace the default expand behavior in my config with this, since I find it so useful.

[alex-courtis]

I love the concept and it is something we should do. Tried your example after a lot of hacking and it looks to work nicely.

• Does nothing when called from the root node
• Needs documentation

Use of private functions in your example aside, this is far too complex and not approachable for users. Having to populate the children is the key problem.

Suggestion: come up with a simple use case and example - one that would go in the documentation. We can start simplifying from there.

Perhaps I'm misunderstanding: why does this need to be an iterator? I was imagining the user would supply a simple boolean returning function to test against a node.