fix(dir): respect directory buffer lifetime #40453

Problem:
dir.lua leaves previously-navigated directory buffers around.
This is fine by default, but users need a simple way to opt out.

Solution:
1. Respect `set hidden` (via `'bufhidden'`) as one way to make
   previously-navigated dir buffers from showing up.
2. Document a one-liner to hide these buffers

runtime/doc/plugins.txt

@@ -65,6 +65,12 @@ These keys map to <Plug>(nvim-dir-open), <Plug>(nvim-dir-up), and
 
 The listing is read-only and does not modify the filesystem.
 
+Directory buffers follow the global 'hidden' option by default. To delete them
+after use: >vim
+	autocmd FileType directory setlocal bufhidden=delete
+<
+Use "wipe" to discard all buffer state; see |'bufhidden'|.
+
                                                     *g:loaded_nvim_dir_plugin*
 To disable this plugin, set this in your config before startup: >lua
 	vim.g.loaded_nvim_dir_plugin = 1

runtime/doc/windows.txt

@@ -1429,7 +1429,7 @@ terminal	A terminal window buffer, see |terminal|.  The contents cannot
 directory	Displays directory contents.  Can be used by a file explorer
 		plugin.  The buffer is created with these settings: >
 			:setlocal buftype=nowrite
-			:setlocal bufhidden=delete
+			:setlocal bufhidden=
 			:setlocal noswapfile
 <		The buffer name is the name of the directory and is adjusted
 		when using the |:cd| command.

runtime/lua/nvim/dir.lua

@@ -85,7 +85,6 @@ local function render(buf, dir)
     not set_buf_options(buf, {
       { 'modeline', false },
       { 'buftype', 'nowrite' },
-      { 'bufhidden', 'hide' },
       { 'buflisted', true },
       { 'swapfile', false },
       { 'readonly', false },

test/functional/plugin/dir_spec.lua

@@ -215,6 +215,46 @@ describe('nvim.dir', function()
     line_of('beta.txt')
   end)
 
+  it("follows global 'hidden' when abandoned", function()
+    make_fixture()
+    n.clear({ args_rm = { '-u' } })
+
+    command('set hidden')
+
+    edit(root)
+    local root_buf = api.nvim_get_current_buf()
+    eq('', bufopt('bufhidden'))
+
+    edit(subdir)
+    eq(true, api.nvim_buf_is_loaded(root_buf))
+    eq(1, fn.getbufinfo(root_buf)[1].hidden)
+
+    n.clear({ args_rm = { '-u' } })
+    command('set nohidden')
+
+    edit(root)
+    root_buf = api.nvim_get_current_buf()
+    eq('', bufopt('bufhidden'))
+
+    edit(subdir)
+    eq(false, api.nvim_buf_is_loaded(root_buf))
+  end)
+
+  it("preserves custom 'bufhidden' when reloading", function()
+    make_fixture()
+    n.clear({
+      args_rm = { '-u' },
+      args = { '--cmd', [[autocmd FileType directory ++once setlocal bufhidden=delete]] },
+    })
+
+    edit(root)
+    eq('delete', bufopt('bufhidden'))
+
+    feed('R')
+    poke_eventloop()
+    eq('delete', bufopt('bufhidden'))
+  end)
+
   it('reports an error and keeps the buffer when reloading a removed directory', function()
     make_fixture()
     n.clear({ args_rm = { '-u' } })