feat(commands): Support bang on commands to force retain focus

See readme

.github/workflows/panvimdoc.yml

@@ -12,6 +12,7 @@ jobs:
         uses: kdheepak/panvimdoc@main
         with:
           vimdoc: symbols-outline
+          version: "NVIM v0.7.0"
       - uses: stefanzweifel/git-auto-commit-action@v4
         with:
           commit_message: "Auto generate vim docs"

README.md

@@ -239,13 +239,17 @@ local opts = {
   position = 'right',
   relative_width = true,
   width = 25,
+
   -- Behaviour changed in this fork:
   -- Auto close the outline window if goto_location is triggered and not for
   -- focus_location
   auto_close = false,
+
+  -- Vim options for the outline window
   show_numbers = false,
   show_relative_numbers = false,
   show_cursorline = true,
+
   show_symbol_details = true,
   -- Highlight group for the preview background
   preview_bg_highlight = 'Pmenu',
@@ -253,11 +257,13 @@ local opts = {
   auto_unfold_hover = true,
   fold_markers = { '', '' },
   wrap = false,
+
   -- Only in this fork:
   -- Whether to focus on the outline window when it is opened.
   -- Set to false to remain focus on your previous buffer when opening
   -- symbols-outline.
   focus_on_open = true,
+
   keymaps = { -- These keymaps can be a string or a table for multiple keys
     close = {"<Esc>", "q"},
     -- Jump to symbol under cursor
@@ -278,8 +284,10 @@ local opts = {
     unfold_all = "E",
     fold_reset = "R",
   },
+
   lsp_blacklist = {},
   symbol_blacklist = {},
+
   symbols = {
     -- Changed in this fork
     File = { icon = "󰈔", hl = "@text.uri" },
@@ -345,14 +353,34 @@ local opts = {
 
 ## Commands
 
-| Command                       | Description                      |
-| ----------------------------- | -------------------------------- |
-| `:SymbolsOutline`             | Toggle symbols outline           |
-| `:SymbolsOutlineOpen`         | Open symbols outline             |
-| `:SymbolsOutlineClose`        | Close symbols outline            |
-| `:SymbolsOutlineFocus`        | Toggle focus on symbols outline  |
-| `:SymbolsOutlineFocusOutline` | Focus on symbols outline         |
-| `:SymbolsOutlineFocusCode`    | Focus on source window           |
+- **:SymbolsOutline[!]**
+
+Toggle symbols outline. With bang (`!`) the cursor focus stays in your original
+window after opening the outline window. Set `focus_on_win = true` to always use
+this behaviour.
+
+- **:SymbolsOutlineOpen[!]**
+
+Open symbols outline. With bang (`!`) the cursor focus stays in your original
+window after opening the outline window. Set `focus_on_win = true` to always use
+this behaviour.
+
+- **:SymbolsOutlineClose**
+
+Close symbols outline
+
+- **:SymbolsOutlineFocus**
+
+Toggle focus on symbols outline
+
+- **:SymbolsOutlineFocusOutline**
+
+Focus on symbols outline
+
+- **:SymbolsOutlineFocusCode**
+
+Focus on source window
+
 
 ### Lua API
 
@@ -360,13 +388,40 @@ local opts = {
 require'symbols-outline'
 ```
 - setup(opts)
-- toggle_outline()
-- open_outline()
+
+- toggle_outline(opts)
+
+Toggle opening/closing of outline window.
+
+If `opts.bang` is true, keep focus on previous window.
+
+- open_outline(opts)
+
+Open the outline window.
+
+If `opts.bang` is true, keep focus on previous window.
+
 - close_outline()
+
+Close the outline window
+
 - focus_toggle()
+
+Toggle cursor focus between code and outline window
+
 - focus_outline()
+
+Focus cursor on the outline window.
+
 - focus_code()
 
+Focus cursor on the window which the outline is derived from.
+
+- is_open()
+
+Return whether the outline window is open
+
+
 ## Default keymaps
 
 | Key        | Action                                             |
@@ -379,8 +434,8 @@ require'symbols-outline'
 | r          | Rename symbol                                      |
 | a          | Code actions                                       |
 | h          | fold symbol                                        |
-| tab        | toggle fold under cursor                           |
-| shift+tab  | toggle all folds                                   |
+| Tab        | toggle fold under cursor                           |
+| Shift+Tab  | toggle all folds                                   |
 | l          | Unfold symbol                                      |
 | W          | Fold all symbols                                   |
 | E          | Unfold all symbols                                 |

lua/symbols-outline.lua

@@ -54,12 +54,13 @@ local function setup_buffer_autocmd()
 end
 
 local function setup_commands()
-  vim.api.nvim_create_user_command('SymbolsOutline', M.toggle_outline, { nargs = 0 })
-  vim.api.nvim_create_user_command('SymbolsOutlineOpen', M.open_outline, { nargs = 0 })
-  vim.api.nvim_create_user_command('SymbolsOutlineClose', M.close_outline, { nargs = 0 })
-  vim.api.nvim_create_user_command('SymbolsOutlineFocusOutline', M.focus_outline, { nargs = 0 })
-  vim.api.nvim_create_user_command('SymbolsOutlineFocusCode', M.focus_code, { nargs = 0 })
-  vim.api.nvim_create_user_command('SymbolsOutlineFocus', M.focus_toggle, { nargs = 0 })
+  local cmd = function(n, c, o) vim.api.nvim_create_user_command('SymbolsOutline'..n, c, o) end
+  cmd('', M.toggle_outline, { nargs = 0, bang = true })
+  cmd('Open', M.open_outline, { nargs = 0, bang = true })
+  cmd('Close', M.close_outline, { nargs = 0 })
+  cmd('FocusOutline', M.focus_outline, { nargs = 0 })
+  cmd('FocusCode', M.focus_code, { nargs = 0 })
+  cmd('Focus', M.focus_toggle, { nargs = 0 })
 end
 
 -------------------------
@@ -69,10 +70,11 @@ M.state = {
   outline_items = {},
   flattened_outline_items = {},
   code_win = 0,
+  opts = {}
 }
 
 local function wipe_state()
-  M.state = { outline_items = {}, flattened_outline_items = {}, code_win = 0 }
+  M.state = { outline_items = {}, flattened_outline_items = {}, code_win = 0, opts = {} }
 end
 
 local function _update_lines()
@@ -341,21 +343,22 @@ local function handler(response)
 
   M._highlight_current_item(M.state.code_win)
 
-  if not config.options.focus_on_open then
+  if not config.options.focus_on_open or (M.state.opts and M.state.opts.bang) then
     vim.fn.win_gotoid(M.state.code_win)
   end
 end
 
-function M.toggle_outline()
+function M.toggle_outline(opts)
   if M.view:is_open() then
     M.close_outline()
   else
-    M.open_outline()
+    M.open_outline(opts)
   end
 end
 
-function M.open_outline()
+function M.open_outline(opts)
   if not M.view:is_open() then
+    M.state.opts = opts
     providers.request_symbols(handler)
   end
 end
@@ -387,6 +390,10 @@ function M.focus_toggle()
   end
 end
 
+function M.is_open()
+  return M.view:is_open()
+end
+
 function M.setup(opts)
   config.setup(opts)
   ui.setup_highlights()