From 7486c2f6aa6d5fbed7845a8dc100bf797498782d Mon Sep 17 00:00:00 2001
From: Tiago Inaba <122808226+tiagoinaba@users.noreply.github.com>
Date: Thu, 12 Jun 2025 14:56:39 -0300
Subject: [PATCH] feat(lsp): <Plug> mapping for signature help cycling #34039

Replace direct function mappings with `<Plug>` mappings for cycling
through overloaded signatures, providing better customization options
for users. This change keeps the default mapping (`<C-s>`) for cycling
if `<Plug>(nvim.lsp.ctrl-s)` is not mapped.
---
 runtime/doc/lsp.txt         |  7 ++++++-
 runtime/lua/vim/lsp/buf.lua | 18 ++++++++++++++++--
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b955f8ebf8..72a2e01da0 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1845,7 +1845,12 @@ selection_range({direction})                   *vim.lsp.buf.selection_range()*
 
 signature_help({config})                        *vim.lsp.buf.signature_help()*
     Displays signature information about the symbol under the cursor in a
-    floating window.
+    floating window. Allows cycling through signature overloads with `<C-s>`,
+    which can be remapped via `<Plug>(nvim.lsp.ctrl-s)`
+
+    Example: >lua
+        vim.keymap.set('n', '<C-b>', '<Plug>(nvim.lsp.ctrl-s)')
+<
 
     Parameters: ~
       • {config}  (`vim.lsp.buf.signature_help.Opts?`) See
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index f07c6a5132..1aba0d8738 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -345,7 +345,15 @@ local sig_help_ns = api.nvim_create_namespace('nvim.lsp.signature_help')
 --- @field silent? boolean
 
 --- Displays signature information about the symbol under the cursor in a
---- floating window.
+--- floating window. Allows cycling through signature overloads with `<C-s>`,
+--- which can be remapped via `<Plug>(nvim.lsp.ctrl-s)`
+---
+--- Example:
+---
+--- ```lua
+--- vim.keymap.set('n', '<C-b>', '<Plug>(nvim.lsp.ctrl-s)')
+--- ```
+---
 --- @param config? vim.lsp.buf.signature_help.Opts
 function M.signature_help(config)
   local method = ms.textDocument_signatureHelp
@@ -420,12 +428,18 @@ function M.signature_help(config)
     local fbuf, fwin = show_signature()
 
     if can_cycle then
-      vim.keymap.set('n', '<C-s>', function()
+      vim.keymap.set('n', '<Plug>(nvim.lsp.ctrl-s)', function()
         show_signature(fwin)
       end, {
         buffer = fbuf,
         desc = 'Cycle next signature',
       })
+      if vim.fn.hasmapto('<Plug>(nvim.lsp.ctrl-s)', 'n') == 0 then
+        vim.keymap.set('n', '<C-s>', '<Plug>(nvim.lsp.ctrl-s)', {
+          buffer = fbuf,
+          desc = 'Cycle next signature',
+        })
+      end
     end
   end)
 end