From d960ae676073354b7a844cf59cfe534ac1392aa6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 25 Apr 2026 19:39:35 +0200 Subject: [PATCH] docs: vim.ui.select, misc --- runtime/doc/api.txt | 2 +- runtime/doc/lua.txt | 55 ++++++++++++++++++------------- runtime/lua/vim/_meta/api.gen.lua | 2 +- runtime/lua/vim/ui.lua | 42 +++++++++++------------ src/nvim/api/extmark.c | 2 +- 5 files changed, 57 insertions(+), 46 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 60ef807a8a..af470547c7 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3226,7 +3226,7 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts}) • id : id of the extmark to edit. • end_row : ending line of the mark, 0-based inclusive. • end_col : ending col of the mark, 0-based exclusive, or -1 - to extend the range to end of line. + to extend the range to end of line (if strict=false). • hl_group : highlight group used for the text range. This and below highlight groups can be supplied either as a string or as an integer, the latter of which can be diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index c0b7b32b27..0a5017e1c5 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -5166,6 +5166,13 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous) work until `on_choice`. + Plugins may override `vim.ui.select` to provide a custom "picker" + interface; they are expected to call the `format_item` and `preview_item` + handlers (if any) provided by the caller. They may also use the `kind` + hint (if provided by the caller) to decide how to handle some items. + + Note: the default `vim.ui.select` currently doesn't support preview. + Example: >lua vim.ui.select({ 'tabs', 'spaces' }, { prompt = 'Select tabs or spaces:', @@ -5187,31 +5194,35 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* Parameters: ~ • {items} (`any[]`) Arbitrary items - • {opts} (`table`) Additional options - • {prompt}? (`string`) Text of the prompt. Defaults to - `Select one of:` - • {format_item}? (`fun(item: any):string`) Function to - format an individual item from `items`. Defaults to - `tostring`. - • {preview_item}? (`fun(item: any):table`) Function to - preview an individual item from `items`. If missing, no - special preview is used. Should ensure a buffer with - contents (text, highlighting) providing details about - an item. Should return a table with information that - `vim.ui.select` implementations may use to show the - preview buffer in the way they see fit: - • {buf}? (`integer`) - buffer id with preview. If - missing, no preview should be shown. - • {pos}? (`[integer, integer]`) - (1,0)-indexed tuple - of where to position cursor in the preview buffer. If - missing, should be treated as `{ 1, 0 }`. + • {opts} (`table`) Options + • {prompt}? (`string`, default: `"Select one of:"`) + Prompt text. + • {format_item}? (`fun(item: any):string`, default: + `tostring`) Decides how to format items when displayed + in the picker. + • {preview_item}? + (`fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}`) + Decides how to preview an item by preparing a scratch + buffer with the item details (including text, + highlighting, etc.). When the picker decides to + "preview" an item, it should call this function. Must + return a table with these keys: + • {buf}? (`integer`) Buffer containing the previewed + item details, or nil if no preview should be shown. + • {pos}? (`[integer, integer]`) Specifies the + (1,0)-indexed cursor position in the preview buffer. + If nil, should be treated as `{ 1, 0 }`. + • {pos_end}? (`[integer, integer]`) Specifies the + (1,0)-indexed (end-exclusive) end position of the + preview range. If nil, no range is intended for a + preview. • {kind}? (`string`) Arbitrary hint string indicating the - item shape. Plugins reimplementing `vim.ui.select` may - wish to use this to infer the structure or semantics of - `items`, or the context in which select() was called. + item shape. The picker may wish to use this to infer + the structure or semantics of `items`, or the context + in which select() was called. • {on_choice} (`fun(item: T?, idx: integer?)`) Called once the user made a choice. `idx` is the 1-based index of `item` - within `items`. `nil` if the user aborted the dialog. + within `items`, or `nil` if the user aborted the dialog. ============================================================================== diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index 42e962ad64..c9a953bce8 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -597,7 +597,7 @@ function vim.api.nvim_buf_line_count(buf) end --- @param opts vim.api.keyset.set_extmark Optional parameters. --- - id : id of the extmark to edit. --- - end_row : ending line of the mark, 0-based inclusive. ---- - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line. +--- - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false). --- - hl_group : highlight group used for the text range. This and below --- highlight groups can be supplied either as a string or as an integer, --- the latter of which can be obtained using `nvim_get_hl_id_by_name()`. diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index bf4728c4d8..e4f18b9b3a 100644 --- a/runtime/lua/vim/ui.lua +++ b/runtime/lua/vim/ui.lua @@ -3,33 +3,35 @@ local M = {} ---@class vim.ui.select.Opts ---@inlinedoc --- ---- Text of the prompt. ---- (default: `Select one of:`) +--- Prompt text. +--- (default: `"Select one of:"`) ---@field prompt? string --- ---- Formats an individual item from `items`. +--- Decides how to format items when displayed in the picker. --- (default: `tostring`) ---@field format_item? fun(item: any):string --- ---- Function to preview an individual item from `items`. ---- If missing, no special preview is used. ---- Should ensure a buffer with contents (text, highlighting) providing details about an item. ---- Should return a table with information that `vim.ui.select` implementations may ---- use to show the preview buffer in the way they see fit: ---- - {buf}? (`integer`) - buffer id with preview. If missing, no preview should be shown. ---- - {pos}? (`[integer, integer]`) - (1,0)-indexed tuple of where to position cursor ---- in the preview buffer. If missing, should be treated as `{ 1, 0 }`. ----@field preview_item? fun(item: any):table +--- Decides how to preview an item by preparing a scratch buffer with the item details (including text, highlighting, etc.). +--- When the picker decides to "preview" an item, it should call this function. +--- Must return a table with these keys: +--- - {buf}? (`integer`) Buffer containing the previewed item details, or nil if no preview should be shown. +--- - {pos}? (`[integer, integer]`) Specifies the (1,0)-indexed cursor position in the preview buffer. If nil, should be treated as `{ 1, 0 }`. +--- - {pos_end}? (`[integer, integer]`) Specifies the (1,0)-indexed (end-exclusive) end position of the preview range. If nil, no range is intended for a preview. +---@field preview_item? fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]} --- ---- Arbitrary hint string indicating the item shape. ---- Plugins reimplementing `vim.ui.select` may wish to ---- use this to infer the structure or semantics of ---- `items`, or the context in which select() was called. +--- Arbitrary hint string indicating the item shape. The picker may wish to use this to infer the +--- structure or semantics of `items`, or the context in which select() was called. ---@field kind? string --- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous) --- work until `on_choice`. --- +--- Plugins may override `vim.ui.select` to provide a custom "picker" interface; they are expected +--- to call the `format_item` and `preview_item` handlers (if any) provided by the caller. They may +--- also use the `kind` hint (if provided by the caller) to decide how to handle some items. +--- +--- Note: the default `vim.ui.select` currently doesn't support preview. +--- --- Example: --- --- ```lua @@ -53,11 +55,9 @@ local M = {} --- ---@generic T ---@param items T[] Arbitrary items ----@param opts vim.ui.select.Opts Additional options ----@param on_choice fun(item: T|nil, idx: integer|nil) ---- Called once the user made a choice. ---- `idx` is the 1-based index of `item` within `items`. ---- `nil` if the user aborted the dialog. +---@param opts vim.ui.select.Opts Options +---@param on_choice fun(item: T|nil, idx: integer|nil) Called once the user made a choice. +--- `idx` is the 1-based index of `item` within `items`, or `nil` if the user aborted the dialog. function M.select(items, opts, on_choice) vim.validate('items', items, 'table') vim.validate('on_choice', on_choice, 'function') diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c index 45285b1b9f..af3fa8dbdb 100644 --- a/src/nvim/api/extmark.c +++ b/src/nvim/api/extmark.c @@ -402,7 +402,7 @@ ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buf, Integer ns_i /// @param opts Optional parameters. /// - id : id of the extmark to edit. /// - end_row : ending line of the mark, 0-based inclusive. -/// - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line. +/// - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false). /// - hl_group : highlight group used for the text range. This and below /// highlight groups can be supplied either as a string or as an integer, /// the latter of which can be obtained using |nvim_get_hl_id_by_name()|.