feat: add toggle() API for regular windows (#88)

* feat: add `toggle()` API for regular windows

Problem: `toggle_float()` and `toggle_split()` exist but there is no
`toggle()` for regular windows, forcing users to write their own
filetype-checking wrapper.

Solution: add `M.toggle()` that delegates to `close()` or `open()`
based on whether the current buffer is a canola buffer. Includes
vimdoc entry.

* docs(upstream): mark #621 fixed

doc/canola.txt

@@ -479,6 +479,21 @@ close({opts})                                                          *canola.c
           {exit_if_last_buf} `nil|boolean` Exit vim if this canola buffer is the
                              last open buffer
 
+toggle({dir}, {opts}, {cb})                                        *canola.toggle*
+    Open canola browser for a directory, or close it if already open
+
+    Parameters:
+      {dir}  `nil|string` When nil, open the parent of the current buffer, or
+             the cwd if current buffer is not a file
+      {opts} `nil|canola.OpenOpts`
+          {preview} `nil|canola.OpenPreviewOpts` When present, open the preview
+                    window after opening canola
+              {vertical}   `nil|boolean` Open the buffer in a vertical split
+              {horizontal} `nil|boolean` Open the buffer in a horizontal split
+              {split}      `nil|"aboveleft"|"belowright"|"topleft"|"botright"` S
+                           plit modifier
+      {cb}   `nil|fun()` Called after the canola buffer is ready
+
 open_preview({opts}, {callback})                                *canola.open_preview*
     Preview the entry under the cursor in a split
 

doc/upstream.md

@@ -38,6 +38,7 @@ Bugs fixed in this fork that remain open upstream.
 | [#213](https://github.com/stevearc/oil.nvim/issues/213) | Max file size for preview            | [#85](https://github.com/barrettruth/canola.nvim/pull/85) ([`4b32ada`](https://github.com/barrettruth/canola.nvim/commit/4b32ada)) |
 | [#473](https://github.com/stevearc/oil.nvim/issues/473) | Show hidden when dir is all-hidden   | [#85](https://github.com/barrettruth/canola.nvim/pull/85) ([`2fe4e78`](https://github.com/barrettruth/canola.nvim/commit/2fe4e78)) |
 | [#486](https://github.com/stevearc/oil.nvim/issues/486) | Directory sizes show misleading 4.1k | [#87](https://github.com/barrettruth/canola.nvim/pull/87) ([`2aff22a`](https://github.com/barrettruth/canola.nvim/commit/2aff22a)) |
+| [#621](https://github.com/stevearc/oil.nvim/issues/621) | `toggle()` for regular windows       | [#88](https://github.com/barrettruth/canola.nvim/pull/88) ([`385bd82`](https://github.com/barrettruth/canola.nvim/commit/385bd82)) |
 
 ## Open upstream PRs
 
@@ -127,7 +128,7 @@ Bugs fixed in this fork that remain open upstream.
 | [#612](https://github.com/stevearc/oil.nvim/issues/612) | fixed          | Delete buffers on file delete — `cleanup_buffers_on_delete` option                                                                                                                    |
 | [#615](https://github.com/stevearc/oil.nvim/issues/615) | fixed          | Cursor at name column on o/O — [#72](https://github.com/barrettruth/canola.nvim/pull/72) ([`69d85b8`](https://github.com/barrettruth/canola.nvim/commit/69d85b8))                     |
 | [#617](https://github.com/stevearc/oil.nvim/issues/617) | open           | Filetype by actual filetype (P2)                                                                                                                                                      |
-| [#621](https://github.com/stevearc/oil.nvim/issues/621) | open           | Toggle function for regular windows (P2)                                                                                                                                              |
+| [#621](https://github.com/stevearc/oil.nvim/issues/621) | fixed          | `toggle()` for regular windows — [#88](https://github.com/barrettruth/canola.nvim/pull/88) ([`385bd82`](https://github.com/barrettruth/canola.nvim/commit/385bd82))                                                                                                                                              |
 | [#623](https://github.com/stevearc/oil.nvim/issues/623) | not actionable | bufferline.nvim interaction — cross-plugin                                                                                                                                            |
 | [#624](https://github.com/stevearc/oil.nvim/issues/624) | not actionable | Mutation race — no reliable repro                                                                                                                                                     |
 | [#625](https://github.com/stevearc/oil.nvim/issues/625) | not actionable | E19 mark invalid line — intractable without neovim API changes                                                                                                                        |

lua/canola/init.lua

@@ -526,6 +526,20 @@ M.close = function(opts)
   vim.api.nvim_buf_delete(canolabuf, { force = true })
 end
 
+---@param dir? string
+---@param opts? canola.OpenOpts
+---@param cb? fun()
+M.toggle = function(dir, opts, cb)
+  if vim.w.is_canola_win or vim.bo.filetype == 'canola' then
+    M.close()
+    if cb then
+      cb()
+    end
+  else
+    M.open(dir, opts, cb)
+  end
+end
+
 ---@class canola.OpenPreviewOpts
 ---@field vertical? boolean Open the buffer in a vertical split
 ---@field horizontal? boolean Open the buffer in a horizontal split