Support for `vim.ui.select` with a new `preview` option

[neo451]

Problem

vim.ui.select is designed to not care about the structure of the item, but that leads to plugins that enhance it being unable to properly infer how to do previewing, which happens to be the great value that all the picker plugins are adding, and lead to plugins authors directly go calling the specific plugin's API when they want to give users a list to choose from, instead of vim.ui.select interface, which become maintenance burden.

The only effort so far is the kind field introduced here: #15838

But going through the popular fuzzy finder's custom ui select handler, I think only fzf-lua treated this field with extra care if kind is codeaction. So an arbitrary string is simply not enough, and trying to make this a enum will fall into the trap of caring too much about the structure of the item and not being a generic interface.

Expected behavior

Add a preview field with signature fun(item, item_idx): buf

so a minimal buffer picker will look like:

vim.ui.select(vim.api.nvim_list_bufs(), {
	preview = function(buf)
		return buf
	end,
	format_item = function(buf)
		return vim.api.nvim_buf_get_name(buf)
	end,
}, function(buf)
	vim.cmd.buffer(buf)
end)

The advantage of this approach is that it vim.ui.select still don't need to know that it is rendering or the structure of the item, the caller decides whether they want to render a diff, a help file, a normal buffer, or a term buffer.

I have tried adding support for this kind of simple preview field for the mainstream pickers, and they work pretty well, and are just minor changes, so I believe we can add this "contract", so that plugin authors will call vim.ui.select for 80% of the time, and not care about what handler the users are using.

I can draft a PR if this makes sense.

p.s. Here's where I got the idea: #35943 (reply in thread)
But I have not found the discussions mentioned on how this relates to bringing vim.ui closer to LSP capabilities

p.s. preview_item might be a better name, to be more consistent with format_item, and it seems to be what mini.pick is using internally.

[justinmk]

The explanation is good but I'm still missing which event or user action this is related to. I assume it is related to the user "highlighting"/"hovering" an item but not selecting/accepting it.

Add a preview field with signature fun(item, item_idx): buf

Is the actual problem that "hover" does not have a hook currently? I.e. we have on_choice which says when something was selected/accepted but we don't have something that says an item was "hovered"/"highlighted" but not selected/accepted.

So rather than a preview hook it seems more like a on_hover hook is needed.

Related:

• unified interface for cmdline, fuzzy find/picker, completion #35456

[neo451]

yes, indeed a "highlighting"/"hovering" item hook, that gets the item and returns a rendered buffer is what I am proposing.

[neo451]

ok, I guess thinking about the difference between on_hover and preview makes me think I am not knowledgeable enough on this issue.

Basically my initial idea is that preview is not a on_hover action that you just fire the callback and forget about it, you return a buffer with rendered content, just like format_item evaluates item and return a string, which now think about it could be bad for performance because it asks for synchronous operation? (this kind of question where my knowledge ends so correct me if I am wrong), and I think mini.pick use preview option with signature fun(buf_id, item), so that is more close to what on_hover means?

[echasnovski]

Is the actual problem that "hover" does not have a hook currently? I.e. we have on_choice which says when something was selected/accepted but we don't have something that says an item was "hovered"/"highlighted" but not selected/accepted.

So rather than a preview hook it seems more like a on_hover hook is needed.

This looks more like a semantics question. The main idea is to document an interface through which vim.ui.select implementations can show more information about an item. Fuzzy pickers tend to name this "item preview".

The term on_hover can also be a thing (i.e. act on when an item is made "current" but not yet chosen), but this is not necessarily the same as a preview. Hovering on an item might result in its preview (if there are two windows with item list and preview), but it also might not (if preview window/content is shown on demand).

'mini.pick' implementation of vim.ui.select indeed respects the opts.preview_item, which can be fun(item: any):string[]. A more general signature might better be one of:

1. fun(buf: integer, item: any):nil - preview modifies a given buffer with text and/or highlighting.
2. fun(item: any):integer - preview itself creates a buffer with a previewed content and returns its id.

---

Agreeing and adding some sort of preview interface into vim.ui.select will indeed greatly help with plugins. Currently for a custom "fuzzy select" functionality plugin authors usually end up creating separate implementations for all popular (at the moment) pickers. Partly because vim.ui.select() is not that popularized, but I think mostly because it does not provide flexible enough interface. The preview_item option should be a great improvement here.

[justinmk]

Hovering on an item might result in its preview (if there are two windows with item list and preview), but it also might not (if preview window/content is shown on demand).

Makes sense, but still wondering how does vim.ui.select know when to call the preview handler? Doesn't this imply the need for a hover/current hook?

[echasnovski]

Makes sense, but still wondering how does vim.ui.select know when to call the preview handler? Doesn't this imply the need for a hover/current hook?

Each implementation can make its own decision. More or less similar to how opts.format_item is used: yes, it can use it inside some item list, or it can decide to use in some other fashion.

The opts.preview_item() can be used something like this:

• When there is side-by-side preview, it is indeed called to setup content whenever "current/active/selected item" is changed. This is how vim.ui.select implementations based on current fuzzy pickers with default window layouts will probably use it.
• When there is an on-demand preview, there is a separate key that is associated with "show preview". The opts.preview_item will be used then. This is how 'mini.pick' and layouts without side-by-side preview will use it.

The idea is to document an interface for both vim.ui.select users and implementations:

• Users can have something like opts.preview_item = functiion(buf_id, item) vim.api.nvim_buf_set_lines(buf_id, 0, -1, false, vim.split(vim.inspect(item), '\n')) end.
• Implementations can have something like vim.api.nvim_win_set_buf(preview_win_id, buf_id); opts.preview_item(buf_id, item).

[justinmk]

Ok I think this is unblocked.