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.

runtime/doc/lua.txt

@@ -5334,7 +5334,8 @@ vim.ui.input({opts}, {on_confirm})                            *vim.ui.input()*
     work until `on_confirm`.
 
     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)
 <
@@ -5349,6 +5350,14 @@ vim.ui.input({opts}, {on_confirm})                            *vim.ui.input()*
                       • {highlight}? (`function`) Function that will be used
                         for highlighting user inputs.
                       • {prompt}? (`string`) Text of the prompt
+                      • {scope}?
+                        (`'cursor'|'line'|'buffer'|'window'|'tabpage'|'editor'|'project'`)
+                        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.
       • {on_confirm}  (`fun(input?: string)`) Called once the user confirms or
                       abort the input. `input` is what the user typed (it
                       might be an empty string if nothing was entered), or

runtime/doc/news.txt

@@ -199,6 +199,7 @@ LUA
 • |vim.npcall()| calls the function `fn` in protected-mode like |pcall()|,
   but returns `nil` on error.
 • |vim.pos| can now convert between positions and buffer offsets.
+• |vim.ui.input()| now allows setting input scope.
 • |vim.log| for easily creating loggers.
 
 OPTIONS

runtime/lua/nvim/spellfile.lua

@@ -281,7 +281,7 @@ function M.get(lang)
       info.lang,
       info.encoding
     )
-    vim.ui.input({ prompt = prompt }, function(input)
+    vim.ui.input({ prompt = prompt, scope = 'editor' }, function(input)
       -- properly clear the message window
       vim.api.nvim_echo({ { ' ' } }, false, { kind = 'empty' })
       if not input or input:lower() ~= 'y' then

runtime/lua/vim/lsp/buf.lua

@@ -809,6 +809,7 @@ function M.rename(new_name, opts)
 
         local prompt_opts = {
           prompt = 'New Name: ',
+          scope = 'cursor',
         }
         if result.placeholder then
           prompt_opts.default = result.placeholder
@@ -839,6 +840,7 @@ function M.rename(new_name, opts)
       local prompt_opts = {
         prompt = 'New Name: ',
         default = cword,
+        scope = 'cursor',
       }
       vim.ui.input(prompt_opts, function(input)
         if not input or #input == 0 then

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)
 --- ```