diff options
| author | Evgeni Chasnovski <evgeni.chasnovski@gmail.com> | 2026-04-25 20:03:55 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-04-25 13:03:55 -0400 |
| commit | c44df255aa095525647efaeaba2bc41ed1d538f5 (patch) | |
| tree | e0ef76375f7fb7386b6f40902050e0c08b6ec37f /runtime/lua | |
| parent | 775c7d1b538275ccb560c4cdd806ef1db322164d (diff) | |
| download | rneovim-c44df255aa095525647efaeaba2bc41ed1d538f5.tar.gz rneovim-c44df255aa095525647efaeaba2bc41ed1d538f5.tar.bz2 rneovim-c44df255aa095525647efaeaba2bc41ed1d538f5.zip | |
docs(vim.ui): "preview" interface for vim.ui.select() #37360
Problem: Plugins may want to have a way to show more details about items
when using `vim.ui.select`. This is a fairly common problem that
prompts plugin authors to implement dedicated sources/pickers for
fuzzy picker plugins that are popular at the moment.
Solution: Document a way for `vim.ui.select` to provide preview:
- `vim.ui.select` users can provide `opts.preview_item` function that
creates/uses a buffer and its contents at certain position to show
more details about an item.
- `vim.ui.select` implementations may use `opts.preview_item` in the
way they see fit (like show the buffer in a separate/same window
interactively/on-demand or do nothing) if they have a way to show
more information about an item.
Diffstat (limited to 'runtime/lua')
| -rw-r--r-- | runtime/lua/vim/ui.lua | 17 |
1 files changed, 17 insertions, 0 deletions
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index fe670893e5..89133697b3 100644 --- a/runtime/lua/vim/ui.lua +++ b/runtime/lua/vim/ui.lua @@ -10,6 +10,16 @@ local M = {} --- individual item from `items`. Defaults to `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 +--- --- Arbitrary hint string indicating the item shape. --- Plugins reimplementing `vim.ui.select` may wish to --- use this to infer the structure or semantics of @@ -27,6 +37,13 @@ local M = {} --- format_item = function(item) --- return ('I choose %s!'):format(item) --- end, +--- preview_item = function(item) +--- local lines = { 'This is ' .. vim.inspect(item) } +--- local buf = vim.api.nvim_create_buf(false, true) +--- vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines) +--- vim.bo[buf].bufhidden = 'wipe' +--- return { buf = buf } +--- end, --- }, function(choice) --- vim.o.expandtab = choice == 'spaces' --- vim.print(('Selected "%s" => expandtab=%s'):format(choice, vim.o.expandtab)) |