[mini.pick] How to dynamically resize window based on view_state after custom action?

[edisj]

Contributing guidelines

• I have read CODE_OF_CONDUCT.md

Module(s)

mini.pick

Question

What I'm trying to accomplish: I want to create a custom action that previews the current match when view_state ~= "preview" (i.e. not a toggle) and increase window size of the picker, then decrease back to normal after exiting preview

I eventually got this work, but it involved modifying some code in 'mini.pick' to allow custom action callbacks to accept a picker argument the same way the builtins do. (see dropdown 4)

first iteration looks like this:

minipick_preview_grow.mp4

Is there an extremely simple solution to this that I'm missing?

first try - set callable `window.config` in config

The idea here was to see if a MiniFiles.refresh() is called after the preview is shown in the window. Didn't work

---whether the main window is currently hosting a preview
---@return boolean
local preview_in_main = function()
    local state = MiniPick.get_picker_state()
    if state == nil then return false end

    local preview_buf = state.buffers.preview
    if preview_buf == nil then
        return false
    end
    local buf_in_main = vim.api.nvim_win_get_buf(state.windows.main)

    return preview_buf == buf_in_main
end

require("mini.pick").setup({

	...,

    window = {
      config = function()
          local default = {
              width = math.floor(0.45 * vim.o.columns),
              height = math.floor(0.4 * vim.o.lines),
          }
          if not preview_in_main() then
              return default
          end

          return {
              width = math.floor(0.5 * vim.o.columns),
              height = math.floor(0.75 * vim.o.lines),
          }
      end,

	...,

}

second try - autocmd that detects `BufWinEnter` for preview buf

vim.api.nvim_create_autocmd("BufWinEnter", {
	callback = function(ev)
        local state = MiniPick.get_picker_state()
        if state == nil then return end

        vim.notify("ev.buf: " .. tostring(ev.buf), vim.log.levels.INFO, {})
        vim.notify("state.buffers.preview: " .. tostring(state.buffers.preview), vim.log.levels.INFO, {})
        if ev.buf ~= state.buffers.preview then return end
        MiniPick.refresh()
    end
})

The idea here was to call MiniPick.refresh() after the preview buffer is loaded into the window, but that didn't work either. After some testing it seems that picker.view_state and picker.buffers.preview are not set until after the event has fired. I tried to show what I mean in the video below:

minipick_bufwinenter.mp4

You can see that the value stored in pickers.buffers.preview is behind what's currently in the window

third try - create custom action and manually set win config

So here, I looked at the source code for the builtin toggle_preview action and basically lsp goto definition'd my way through the call stack and created a custom action that did all the same things:

---whether the main window is currently hosting a preview
---@return boolean
local preview_in_main = function()
    local state = MiniPick.get_picker_state()
    if state == nil then return false end

    local preview_buf = state.buffers.preview
    if preview_buf == nil then
        return false
    end
    local buf_in_main = vim.api.nvim_win_get_buf(state.windows.main)

    return preview_buf == buf_in_main
end

-- H.create_scratch_buf(name)
local create_scratch_buf = function(name)
    local buf_id = vim.api.nvim_create_buf(false, true)

    -- inlining H.set_buf_name(buf_id, name)
    vim.api.nvim_buf_set_name(buf_id, "minipick://" .. buf_id .. "/" .. name)
    -- end inline

    vim.bo[buf_id].matchpairs = ''
    vim.b[buf_id].minicursorword_disable = true
    vim.b[buf_id].miniindentscope_disable = true
    return buf_id
end

-- H.picker_show_preview
local custom_picker_show_preview = function(picker)
    local opts = MiniPick.get_picker_opts()
    if opts == nil then return end

    -- using matches instead of H.picker_get_current_item(picker)...
    -- possible issue with that?
    local item = MiniPick.get_picker_matches().current
    if item == nil then return end

    local win_id, buf_id = picker.windows.main, create_scratch_buf("preview")
    vim.bo[buf_id].bufhidden = "wipe"

    -- inlining H.set_winbuf(win_id, buf_id)
    vim.api.nvim_win_set_buf(win_id, buf_id)
    -- end inline

    MiniPick.default_preview(buf_id, item)
    -- setting these fields doesn't really do anything as this `picker` is just
    -- a copy from MiniPick.get_picker_state()
    picker.buffers.preview = buf_id
    picker.view_state = "preview"

    local win_config = {
		width = math.floor(0.5 * vim.o.columns),
        height = math.floor(0.75 * vim.o.lines),
    }
    vim.api.nvim_win_set_config(win_id, win_config)
end

require("mini.pick").setup({

    ...,

    mappings = {

		...,

        custom_show_preview = {
            char = "<C-l>",
            func = function()
                local picker = MiniPick.get_picker_state()
                if picker == nil then return end

                vim.notify("PREVIEW IN MAIN: " .. tostring(preview_in_main()), vim.log.levels.INFO, {})
                vim.notify("picker.buffers.preview: " .. tostring(picker.buffers.preview), vim.log.levels.INFO, {})
                if preview_in_main() then return end
                custom_picker_show_preview(picker)
            end,
        },
	}
})

Of course, as opposed to the H.* helpers in the actual 'mini.pick', the picker argument isn't actually a reference to the picker, but just a copy of what's returned by MiniPick.get_picker_state(). So while I could modify the size of the window in this custom action, the core issue was that, when calling MiniPick.default_preview(), picker.buffers.preview and picker.view_state are not actually set in the internal picker object, meaning there's some behavior that's not quite right for example the input prompt does not switch to the filename as it does for the builtin preview action, whereas the builtin toggle_preview has access to a reference to the real picker.

This leads to the issue that, even though I MiniPick.default_preview(), the picker is not in the normal "preview" state where it has a valid picker.buffers.preview field

custom_action_test.mp4

fourth try - solved, but had to modify `H.normalize_mappings`

So, after coming to the conclusion that what I want to happen is for my custom action to also be able to set view_state = "preview" and set a buffer number in picker.buffers.preview just like the builtin action.

I added an additional argument picker to H.normalize_mappings so that custom actions may also have a reference to the picker passed. As in, I changed line 2527 to

H.normalize_mappings = function(mappings, skip_alternatives, picker)

and line 2544 to

local data = { char = char, name = name, func = is_custom and function() rhs.func(picker) end or H.actions[name], is_custom = is_custom }

Then, everywhere H.normalize_mappings was called, I passed the picker as an additional argument

This allowed me to write the following custom action (note that the picker passed to custom actions is now a true reference):

---whether the main window is currently hosting a preview
---@return boolean
local preview_in_main = function()
    local state = MiniPick.get_picker_state()
    if state == nil then return false end

    local preview_buf = state.buffers.preview
    if preview_buf == nil then
        return false
    end
    local buf_in_main = vim.api.nvim_win_get_buf(state.windows.main)

    return preview_buf == buf_in_main
end

-- H.create_scratch_buf(name)
local create_scratch_buf = function(name)
    local buf_id = vim.api.nvim_create_buf(false, true)

    -- inlining H.set_buf_name(buf_id, name)
    vim.api.nvim_buf_set_name(buf_id, "minipick://" .. buf_id .. "/" .. name)
    -- end inline

    vim.bo[buf_id].matchpairs = ''
    vim.b[buf_id].minicursorword_disable = true
    vim.b[buf_id].miniindentscope_disable = true
    return buf_id
end

-- H.picker_show_preview
local custom_picker_show_preview = function(picker)
    local opts = MiniPick.get_picker_opts()
    if opts == nil then return end

    -- using matches instead of H.picker_get_current_item(picker)...
    -- possible issue with that?
    local item = MiniPick.get_picker_matches().current
    if item == nil then return end

    local win_id, buf_id = picker.windows.main, create_scratch_buf("preview")
    vim.bo[buf_id].bufhidden = "wipe"

    -- inlining H.set_winbuf(win_id, buf_id)
    vim.api.nvim_win_set_buf(win_id, buf_id)
    -- end inline

    MiniPick.default_preview(buf_id, item)
    picker.buffers.preview = buf_id
    picker.view_state = "preview"

    MiniPick.refresh()
end

-- H.picker_show_main(picker)
local custom_picker_show_main = function(picker)
    -- inlining H.set_winbuf(win_id, buf_id)
    vim.api.nvim_win_set_buf(picker.windows.main, picker.buffers.main)
    -- end inline

    picker.view_state = "main"

    MiniPick.refresh()
end

require("mini.pick").setup({

    ...,

    mappings = {
		...,
        custom_show_preview = {
            char = "<C-l>",
            func = function(picker)
                if picker == nil then return end

                if preview_in_main() then return end
                custom_picker_show_preview(picker)
            end,
        },
		custom_show_main = {
            char = "<C-h>",
            func = function(picker)
                if picker == nil then return end

                if preview_in_main() then
                    custom_picker_show_main(picker)
                end
            end,
        },
	},

	...,

    window = {
        config = function()
            local default = {
                width = math.floor(0.45 * vim.o.columns),
                height = math.floor(0.4 * vim.o.lines),
            }
            if not preview_in_main() then
                return default
            end

            return {
                width = math.floor(0.5 * vim.o.columns),
                height = math.floor(0.75 * vim.o.lines),
            }
        end,
        prompt_caret = "▏",
        prompt_prefix = "> ",
    },
})

where now I can write the window size logic directly in the window.config callable and just call MiniPick.refresh() in my custom actions. So it finally works as I wanted :)

This all leads me to a question: why is picker not passed as an argument to custom action callbacks the same way it is to the builtin actions?

Also, would you be open to accepting this change (passing picker reference to custom action callbacks) officially in 'mini.pick'? I think it's a nice feature and allows a lot more customizability

[echasnovski]

That's an interesting idea!

The BufWinEnter idea together with callable window config is what I'd use. The picker's state data is indeed not updated at the time BufWinEnter is triggered, but that can be solved by scheduling the callback to execute "on the next event loop". Here is something that seems to work:

-- Make window config that chooses height based on the view in main window
local win_config = function()
  local state = MiniPick.get_picker_state()
  local is_preview = state ~= nil and state.buffers.preview == vim.api.nvim_win_get_buf(state.windows.main)
  return { height = is_preview and 50 or 20 }
end
require('mini.pick').setup({ window = { config = win_config } })

-- Ensure that window is updated every time a new buffer is shown in it.
-- Schedule since state data is not yet updated when the buffer is shown.
local refresh_picker = vim.schedule_wrap(function()
  if not MiniPick.is_picker_active() then return end
  MiniPick.refresh()
end)
vim.api.nvim_create_autocmd('BufWinEnter', { callback = refresh_picker })

Couple of notes:

• Built-in help picker doesn't follow the source.preview requirement that it must use the given buf_id. This is something that stems from the difficulty of showing the help tag, but ideally should be fixed in the future. I'll take a look.
• Probably exporting something like set_picker_view() might have merit. Just don't want to increase already the biggest module there is in 'mini.nvim'.

This all leads me to a question: why is picker not passed as an argument to custom action callbacks the same way it is to the builtin actions?

Also, would you be open to accepting this change (passing picker reference to custom action callbacks) officially in 'mini.pick'? I think it's a nice feature and allows a lot more customizability

The picker is not passed since there are various {get,set}_picker_xxx() functions that are meant to interact with the picker in a more controlled manner. The picker object itself has many implicit assumptions about its structure. Exporting it to the user directly would mean to 1) documenting it; 2) following documented structure in a backward compatible way; 3) add extra checks all around the code about structural assumptions (since users can alter them, knowingly or not).

---

On a side note, I am very surprised by the high quality of your approaches and this write-up itself. Very nice 👍

[edisj]

Ahh I didn't consider scheduling the refresh. This works perfectly for me thank you!

On a technical note (because I'm still learning a lot of this and am extremely curious) -
this works because there's a time delay between the event firing and the callback being executed, right?
So, suppose the event fires at t₀. This will schedule the execution of refresh_picker for a later time, t₁. At t₁, refresh_picker will call MiniPick.refresh(), at which point the state will have updated such that is_preview will return true, so the correct win_config is applied. If this is true, this all assumes that the time it takes to update the view_state, call it t_{view_state_updated}, will always be LESS than the delay time of the callback execution, that is t_{view_state_updated} - t₀ < t₁ - t₀ always.

Intuitively I'd think that it's always the case, but do you know on what order the average delay is before a scheduled callback is executed? In other words, suppose I put a sleep command in 'mini.pick' in the line right AFTER the buffer is loaded in the window, but BEFORE the picker state is updated. How long would that sleep have to be to cause problems? Or maybe this isn't how it works and I'm confused somewhere

In any case, I'm very happy with the solution and will just use this autocmd plus the toggle mappings :)

[echasnovski]

Scheduling only a workaround for the internal order: "registering" the preview buffer is done after showing buffer in the main window.
Technically, it is possible to first fully prepare a buffer (set preview lines in it and "register") and only then show in the window. But for some user facing tasks that custom source.preview can do, having the buffer shown in its eventual window might be beneficial. Swapping two lines around would make vim.schedule_wrap() not needed, but it will conflict with other update (allowing source.preview to set its own buffer).

---

Regarding the scheduling stuff... It is not very intuitive at first, but basically all vim.schedule does is it remembers to execute the function "as soon as possible, but not now". It means that the function will be executed after all "immediate code" is executed. The actual time delay is usually very negligible and you can measure it yourself by calling vim.uv.hrtime() before calling vim.schedule and inside its callback.

The vim.schedule_wrap is basically function(f) return function() vim.schedule(f) end end that also allows passing arguments.

So as long as "internal register" of the preview buffer is a part of an "immediate code", it will always be executed before any vim.scheduled code.

In other words, suppose I put a sleep command in 'mini.pick' in the line right AFTER the buffer is loaded in the window, but BEFORE the picker state is updated. How long would that sleep have to be to cause problems? Or maybe this isn't how it works and I'm confused somewhere

If sleeping is blocking the "immediate code", which is usually does since Lua is single threaded, then the answer is never. Scheduled function is always executed after "immediate code". You can test it yourself with a snippet something like this:

_G.log = {}

_G.f = function()
  table.insert(_G.log, 'one')
  vim.schedule(function() table.insert(_G.log, 'two') end)
  vim.uv.sleep(1000)
  table.insert(_G.log, 'three')
end

Executing :lua f() will sleep for one second. Then executing :=log will show { 'one', 'three', 'two' }.

[edisj]

Exporting it to the user directly would mean to 1) documenting it; 2) following documented structure in a backward compatible way; 3) add extra checks all around the code about structural assumptions (since users can alter them, knowingly or not).

This is all very reasonable. I didn't really consider the extra maintenance costs or even the backwards compatibility of documentation at all...

3. add extra checks all around the code about structural assumptions (since users can alter them, knowingly or not)

This point made me think a little bit. Can I ask you: should everything the user can touch be validated for correctness?

What I mean is, if the custom action callback is hooking into a code path where the data is expected to have a specific structure that has already been validated, why isn't it the user's responsibility to adhere to those specifications? And if the custom action transforms the picker in breakable ways, why isn't that the user's responsibility as well, just as it is the responsibility of the maintainer not break things internally?

On the other hand I can see this could be a very large maintainer burden as the likelihood users break 'mini.pick' using custom actions would increase and you'd get much more issues. Plus, I don't know how you'd even document everything fully, as it'd basically be explaining the whole code base implementation which is a bit much...

There's probably a lot I'm missing here but just thinking out loud...

---

And as a side note to you -
The 'mini' plugins are a fantastic piece of work and extremely tasteful. It was so easy to read and understand your code. After my pleasant experience playing around with 'mini.files', I'm just now experimenting with 'mini.pick' because I'm finding 'snacks.picker' a bit too "fluffy" and over the top for my use case, and it's great. I really like the small details like the "refine" feature. Now I have to try your other work like 'mini.cmdline' and 'mini.completion' ...

[echasnovski]

This point made me think a little bit. Can I ask you: should everything the user can touch be validated for correctness?

What I mean is, if the custom action callback is hooking into a code path where the data is expected to have a specific structure that has already been validated, why isn't it the user's responsibility to adhere to those specifications? And if the custom action transforms the picker in breakable ways, why isn't that the user's responsibility as well, just as it is the responsibility of the maintainer not break things internally?

The answer is usually "it depends". It is the price to pay for a dynamically typed and "interactive" language:

• If you don't want users to accidentally break something internal, do not allow them to directly modify it. Hide it behind get() and set() methods.
• If you need something to match certain conditions, you'd have to match them yourself. The simplification may come in a form of a dedicated "validation function", like validate_config, etc. Usually useful in set() methods.
• Another not very obvious thing is that in get() methods it is usually a better choice to return a copy of internal tables (since they can be modified by reference).

The 'mini' plugins are a fantastic piece of work and extremely tasteful.

Thank you so much! Hope you'll like other modules as well :)