feat(search): you can now toggle flash while using regular search

README.md

@@ -58,6 +58,8 @@ Install the plugin with your preferred package manager:
 
 [lazy.nvim](https://github.com/folke/lazy.nvim):
 
+<!-- setup:start -->
+
 ```lua
 {
   "folke/flash.nvim",
@@ -69,7 +71,6 @@ Install the plugin with your preferred package manager:
       "s",
       mode = { "n", "x", "o" },
       function()
-        -- default options: exact mode, multi window, all directions, with a backdrop
         require("flash").jump()
       end,
       desc = "Flash",
@@ -78,7 +79,6 @@ Install the plugin with your preferred package manager:
       "S",
       mode = { "n", "o", "x" },
       function()
-        -- show labeled treesitter nodes around the cursor
         require("flash").treesitter()
       end,
       desc = "Flash Treesitter",
@@ -87,24 +87,32 @@ Install the plugin with your preferred package manager:
       "r",
       mode = "o",
       function()
-        -- jump to a remote location to execute the operator
         require("flash").remote()
       end,
       desc = "Remote Flash",
     },
     {
       "R",
-      mode = { "n", "o", "x" },
+      mode = { "o", "x" },
       function()
-        -- show labeled treesitter nodes around the search matches
         require("flash").treesitter_search()
       end,
-      desc = "Treesitter Search",
-    }
+      desc = "Flash Treesitter Search",
+    },
+    {
+      "<c-s>",
+      mode = { "c" },
+      function()
+        require("flash").toggle()
+      end,
+      desc = "Toggle Flash Search",
+    },
   },
 }
 ```
 
+<!-- setup:end -->
+
 ## ⚙️ Configuration
 
 **flash.nvim** is highly configurable. Please refer to the default settings below.
@@ -248,7 +256,9 @@ Install the plugin with your preferred package manager:
     -- options used when flash is activated through
     -- a regular search with `/` or `?`
     search = {
-      enabled = true, -- enable flash for search
+      -- when `true`, flash will be activated during regular search by default.
+      -- You can always toggle when searching with `require("flash").toggle()`
+      enabled = true,
       highlight = { backdrop = false },
       jump = { history = true, register = true, nohlsearch = true },
       search = {
@@ -336,6 +346,8 @@ Install the plugin with your preferred package manager:
   - You can also go to the next match with `;` or previous match with `,`
   - Any highlights clear automatically when moving, changing buffers,
     or pressing `<esc>`.
+- **toggle Search**: `require("flash").toggle(boolean?)`
+  - toggles **flash** on or off while using regular search
 - **Treesitter Search**: `require("flash").treesitter_search(opts?)` opens **flash** in **Treesitter Search** mode
   - combination of **Treesitter** and **Search** modes
   - do something like `yR`

lua/flash/commands.lua

@@ -27,4 +27,10 @@ function M.remote(opts)
   return M.jump(opts)
 end
 
+---@param enabled? boolean
+function M.toggle(enabled)
+  local Search = require("flash.plugins.search")
+  return Search.toggle(enabled)
+end
+
 return M

lua/flash/config.lua

@@ -139,7 +139,9 @@ local defaults = {
     -- options used when flash is activated through
     -- a regular search with `/` or `?`
     search = {
-      enabled = true, -- enable flash for search
+      -- when `true`, flash will be activated during regular search by default.
+      -- You can always toggle when searching with `require("flash").toggle()`
+      enabled = true,
       highlight = { backdrop = false },
       jump = { history = true, register = true, nohlsearch = true },
       search = {
@@ -219,9 +221,7 @@ function M.setup(opts)
   options = {}
   options = M.get(opts)
 
-  if options.modes.search.enabled then
-    require("flash.plugins.search").setup()
-  end
+  require("flash.plugins.search").setup()
   if options.modes.char.enabled then
     require("flash.plugins.char").setup()
   end

lua/flash/docs.lua

@@ -7,8 +7,60 @@ function M.update()
   config = config:gsub("%s*debug = false.\n", "\n")
   Docs.save({
     config = config,
+    setup = Docs.extract("lua/flash/docs.lua", "function M%.suggested%(%)\n%s*return (.-)\nend"),
   })
 end
+
+function M.suggested()
+  return {
+    "folke/flash.nvim",
+    event = "VeryLazy",
+    ---@type Flash.Config
+    opts = {},
+    keys = {
+      {
+        "s",
+        mode = { "n", "x", "o" },
+        function()
+          require("flash").jump()
+        end,
+        desc = "Flash",
+      },
+      {
+        "S",
+        mode = { "n", "o", "x" },
+        function()
+          require("flash").treesitter()
+        end,
+        desc = "Flash Treesitter",
+      },
+      {
+        "r",
+        mode = "o",
+        function()
+          require("flash").remote()
+        end,
+        desc = "Remote Flash",
+      },
+      {
+        "R",
+        mode = { "o", "x" },
+        function()
+          require("flash").treesitter_search()
+        end,
+        desc = "Flash Treesitter Search",
+      },
+      {
+        "<c-s>",
+        mode = { "c" },
+        function()
+          require("flash").toggle()
+        end,
+        desc = "Toggle Flash Search",
+      },
+    },
+  }
+end
 M.update()
 
 return M

lua/flash/plugins/search.lua

@@ -2,12 +2,72 @@ local require = require("flash.require")
 
 local Jump = require("flash.jump")
 local State = require("flash.state")
+local Util = require("flash.util")
+local Config = require("flash.config")
 
 local M = {}
 
 ---@type Flash.State?
 M.state = nil
 M.op = false
+M.enabled = true
+
+---@param enabled? boolean
+function M.toggle(enabled)
+  if enabled == nil then
+    enabled = not M.enabled
+  end
+
+  if M.enabled == enabled then
+    return M.enabled
+  end
+
+  M.enabled = enabled
+
+  if State.is_search() then
+    if M.enabled then
+      M.start()
+      M.update(false)
+    elseif M.state then
+      M.state:hide()
+      M.state = nil
+    end
+    -- redraw to show the change
+    vim.cmd("redraw")
+    -- trigger incsearch to update the matches
+    vim.api.nvim_feedkeys(" " .. Util.BS, "n", true)
+  end
+  return M.enabled
+end
+
+---@param check_jump? boolean
+function M.update(check_jump)
+  if not M.state then
+    return
+  end
+
+  local pattern = vim.fn.getcmdline()
+
+  -- when doing // or ??, get the pattern from the search register
+  -- See :h search-commands
+  if pattern:sub(1, 1) == vim.fn.getcmdtype() then
+    pattern = vim.fn.getreg("/") .. pattern:sub(2)
+  end
+  M.state:update({ pattern = pattern, check_jump = check_jump })
+end
+
+function M.start()
+  M.state = State.new({
+    mode = "search",
+    action = M.jump,
+    search = {
+      forward = vim.fn.getcmdtype() == "/",
+      mode = "search",
+      incremental = vim.go.incsearch,
+      multi_window = not M.op,
+    },
+  })
+end
 
 function M.setup()
   local group = vim.api.nvim_create_augroup("flash", { clear = true })
@@ -23,14 +83,7 @@ function M.setup()
   vim.api.nvim_create_autocmd("CmdlineChanged", {
     group = group,
     callback = wrap(function()
-      local pattern = vim.fn.getcmdline()
-
-      -- when doing // or ??, get the pattern from the search register
-      -- See :h search-commands
-      if pattern:sub(1, 1) == vim.fn.getcmdtype() then
-        pattern = vim.fn.getreg("/") .. pattern:sub(2)
-      end
-      M.state:update({ pattern = pattern })
+      M.update()
     end),
   })
 
@@ -44,16 +97,9 @@ function M.setup()
   vim.api.nvim_create_autocmd("CmdlineEnter", {
     group = group,
     callback = function()
-      if State.is_search() then
-        M.state = State.new({
-          mode = "search",
-          action = M.jump,
-          search = {
-            forward = vim.fn.getcmdtype() == "/",
-            mode = "search",
-            incremental = vim.go.incsearch,
-          },
-        })
+      M.enabled = Config.modes.search.enabled or false
+      if State.is_search() and M.enabled then
+        M.start()
         M.set_op(vim.fn.mode() == "v")
       end
     end,
@@ -62,9 +108,9 @@ function M.setup()
   vim.api.nvim_create_autocmd("ModeChanged", {
     pattern = "*:c",
     group = group,
-    callback = wrap(function()
+    callback = function()
       M.set_op(vim.v.event.old_mode:sub(1, 2) == "no" or vim.fn.mode() == "v")
-    end),
+    end,
   })
 end
 

lua/flash/state.lua

@@ -183,6 +183,10 @@ end
 -- Checks if the given pattern is a jump label and jumps to it.
 ---@param pattern string
 function M:check_jump(pattern)
+  if not self.visible then
+    return
+  end
+
   if self.opts.search.trigger ~= "" and self.pattern():sub(-1) ~= self.opts.search.trigger then
     return
   end
@@ -197,14 +201,14 @@ function M:check_jump(pattern)
   end
 end
 
----@param opts? {pattern:string, force:boolean}
+---@param opts? {pattern:string, force:boolean, check_jump:boolean}
 ---@return boolean? abort `true` if the search was aborted
 function M:update(opts)
   opts = opts or {}
 
   if opts.pattern then
     -- abort if pattern is a jump label
-    if self:check_jump(opts.pattern) then
+    if opts.check_jump ~= false and self:check_jump(opts.pattern) then
       return true
     end
     self.pattern:set(opts.pattern)