feat: scroll_signature_up/down keymap commands (#2057)

* add signature scrolling

* docs: signature scrolling

---------

Co-authored-by: Liam Dyer <[email protected]>

Author: brian-tran-dev

doc/configuration/keymap.md

@@ -70,6 +70,10 @@ keymap = {
   - Optionally use `function(cmp) cmp.scroll_documentation_down(4) end` to scroll by a specific number of lines
 - `show_signature`: Shows the signature help window
 - `hide_signature`: Hides the signature help window
+- `scroll_signature_up`: Scrolls the signature help window up by 4 lines
+  - Optionally use `function(cmp) cmp.scroll_signature_up(4) end` to scroll by a specific number of lines
+- `scroll_signature_down`: Scrolls the signature help window down by 4 lines
+  - Optionally use `function(cmp) cmp.scroll_signature_down(4) end` to scroll by a specific number of lines
 - `snippet_forward`: Jumps to the next snippet placeholder
 - `snippet_backward`: Jumps to the previous snippet placeholder
 - `fallback`: Runs the next non-blink keymap, or runs the built-in neovim binding

doc/configuration/signature.md

@@ -7,7 +7,7 @@ title: Signature
 This feature is _experimental_, [contributions welcome](https://github.com/Saghen/blink.cmp/issues/1071)!
 :::
 
-Blink supports signature help, automatically triggered when typing trigger characters, defined by the LSP, such as `(` for `lua`. The menu will be updated when pressing a retrigger character, such as `,`. Due to it being experimental, this feature is opt-in.
+Blink supports signature help by manually pressing `<C-k>` (by default) or automatically triggered when typing trigger characters, defined by the LSP, such as `(` for `lua`. The menu will be updated when pressing a retrigger character, such as `,`. Due to it being experimental, this feature is opt-in.
 
 ```lua
 signature = { enabled = true }
@@ -16,3 +16,17 @@ signature = { enabled = true }
 <img src="https://github.com/user-attachments/assets/9ab576c8-2a04-465f-88c0-9c130fef146c" />
 
 You may want to set `signature.window.show_documentation = false` to only show the signature, and not the documentation.
+
+## Keymap
+
+See the [keymap documentation](../modes/cmdline.md#keymap) for a full list of commands. By default, the `scroll_signature_up` and `scroll_signature_down` commands are not bound to any keys. You may bind them like so:
+
+```lua
+keymap = {
+  ['<C-u>'] = { 'scroll_signature_up', 'fallback' },
+  ['<C-d>'] = { 'scroll_signature_down', 'fallback' },
+
+  -- default in all keymap presets
+  ['<C-k>'] = { 'show_signature', 'hide_signature', 'fallback' },
+}
+```

lua/blink/cmp/config/keymap.lua

@@ -20,6 +20,8 @@
 --- | 'scroll_documentation_down' Scroll the documentation window down
 --- | 'show_signature' Show the signature help window
 --- | 'hide_signature' Hide the signature help window
+--- | 'scroll_signature_up' Scroll the signature window up
+--- | 'scroll_signature_down' Scroll the signature window down
 --- | 'snippet_forward' Move the cursor forward to the next snippet placeholder
 --- | 'snippet_backward' Move the cursor backward to the previous snippet placeholder
 --- | (fun(cmp: blink.cmp.API): boolean?) Custom function where returning true will prevent the next command from running
@@ -185,6 +187,8 @@ function keymap.validate(config, is_mode)
     'scroll_documentation_down',
     'show_signature',
     'hide_signature',
+    'scroll_signature_up',
+    'scroll_signature_down',
     'snippet_forward',
     'snippet_backward',
   }

lua/blink/cmp/init.lua

@@ -305,6 +305,26 @@ function cmp.hide_signature()
   return true
 end
 
+--- Scroll the documentation window up
+--- @param count? number
+function cmp.scroll_signature_up(count)
+  local sig = require('blink.cmp.signature.window')
+  if not sig.win:is_open() then return end
+
+  vim.schedule(function() sig.scroll_up(count or 4) end)
+  return true
+end
+
+--- Scroll the documentation window down
+--- @param count? number
+function cmp.scroll_signature_down(count)
+  local sig = require('blink.cmp.signature.window')
+  if not sig.win:is_open() then return end
+
+  vim.schedule(function() sig.scroll_down(count or 4) end)
+  return true
+end
+
 --- Check if a snippet is active, optionally filtering by direction
 --- @param filter? { direction?: number }
 function cmp.snippet_active(filter) return require('blink.cmp.config').snippets.active(filter) end

lua/blink/cmp/signature/window.lua

@@ -88,6 +88,7 @@ function signature.open_with_signature_help(context, signature_help)
 
   signature.win:open()
   signature.update_position()
+  signature.scroll_up(1)
 end
 
 function signature.close()
@@ -100,7 +101,7 @@ function signature.scroll_up(amount)
   local top_line = math.max(1, vim.fn.line('w0', winnr) - 1)
   local desired_line = math.max(1, top_line - amount)
 
-  vim.api.nvim_win_set_cursor(signature.win:get_win(), { desired_line, 0 })
+  signature.win:set_cursor({ desired_line, 0 })
 end
 
 function signature.scroll_down(amount)
@@ -109,7 +110,7 @@ function signature.scroll_down(amount)
   local bottom_line = math.max(1, vim.fn.line('w$', winnr) + 1)
   local desired_line = math.min(line_count, bottom_line + amount)
 
-  vim.api.nvim_win_set_cursor(signature.win:get_win(), { desired_line, 0 })
+  signature.win:set_cursor({ desired_line, 0 })
 end
 
 function signature.update_position()