feat(ui): vim.ui.input(opts.scope) #39570

Problem: There is no way for a `vim.ui.input` caller to indicate for
  which scope the input is. As in "This input is for something at cursor
  scope". This information can be useful for `vim.ui.input`
  implementation to tweak its behavior and presentation:
  - Show different floating window depending on the scope. For example:
    - Near cursor for "cursor" scope.
    - At line start for "line" scope.
    - In window corner for "buffer" and "window" scopes.
    - In whole editor corner for "tabpage", "editor", "project" scopes.
  - Navigate through history only for inputs with the same scope.

Solution: Document new `opts.scope` for `vim.ui.input`. Use it in the
  codebase.

1 files changed, 8 insertions, 1 deletions

diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index 665fd19e9e..fd065d1ad5 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -98,6 +98,12 @@ end
 ---Function that will be used for highlighting
 ---user inputs.
 ---@field highlight? function
+---
+---Input scope, as in "This input is for something at cursor/line/etc scope".
+---Can be used by `vim.ui.input` implementations to tweak behavior and presentation.
+---For example, the input may adjust the floating window position: near the cursor if
+---`cursor`, in window corner if `buffer` or `window`, etc.
+---@field scope? 'cursor'|'line'|'buffer'|'window'|'tabpage'|'editor'|'project'
 
 --- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
 --- `on_confirm`.
@@ -105,7 +111,8 @@ end
 --- Example:
 ---
 --- ```lua
---- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
+--- local opts = { prompt = 'Enter value for shiftwidth: ', scope = 'buffer' }
+--- vim.ui.input(opts, function(input)
 ---     vim.o.shiftwidth = tonumber(input)
 --- end)
 --- ```