feat(api): Add new node selection action based on tab :drop command

[hinell]

NvimTree.Drop.selection.demo.mov

• Demo of the new action allowing to always jumpt to an already-opened window based in built-in command. Every time <CR> is hit, the same buffer window of the file is focused.
• Usage docs added

Demo link: https://user-images.githubusercontent.com/8136158/233742234-c4f4bb4b-1927-4ab4-b0cc-779c64a0e1b1.mov

PRs

PREVIOUS PRs got CLOSED BECAUSE OF FORCE-PUSH, GITHUB IS REALLY NUTS

Usage example

    require("nvim-tree").setup({
        on_attach = function(bufnr)
            local function opts(desc)
                return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
            end
            local ok, api = pcall(require, "nvim-tree.api")
            assert(ok, "api module is not found")
            vim.keymap.set("n", "<CR>", api.node.open.tab_drop, opts("Tab drop"))
        end
    })

[hinell]

@alex-courtis Please merge asap!

[gegoune]

Have updated docs a bit and resolved styling.

Thanks for your contribution.

[hinell]

@gegoune I think we should provide and example somewhere in docs. Otherwise it's a black box for unfamiliar people.

[gegoune]

I am not against examples of course, is just that this one was not well placed. Other api don't provide any examples at all and this is what it should stay as. We can provide some example api usages on top of api help, more generic ones.

[hinell]

@gegoune But where should such docs be placed?

[gegoune]

Actually there is already an example of how to use API functions in :h nvim-tree-mappings. Do you think it could be improved?

[alex-courtis]

API would be great!

[hinell]

@gegoune Well, it doesn't say explicitly that api.node.<*> namespace can be used:

nvim-tree.lua/doc/nvim-tree-lua.txt

Lines 1757 to 1777 in bb375fb

	|vim.keymap.set()| or |nvim_set_keymap()| to define mappings as usual. e.g. >
	local function my_on_attach(bufnr)
	local api = require('nvim-tree.api')
	local function opts(desc)
	return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
	end
	-- put some default mappings here
	-- user mappings
	vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
	end
	require("nvim-tree").setup({
	---
	on_attach = my_on_attach,
	---
	})
	<

[gegoune]

It shouldn't list all the available namespaces, local api = require('nvim-tree.api') is provided indicating all api can be used.

This is out of topic here now. If you think documentation can be improved please open new issue or better yet a PR.

[hinell]

@

[hinell]

Well I could have made an improvement via this PR, but anyway.

[gegoune]

That wasn't what we wanted to add to docs. Please open new issue if you want to continue this conversation.

[alex-courtis]

How about we just add a Recipe ?

The :help is factual and correct.