[mini.files] Better/scrollable preview

[drowning-cat]

Related

• [mini.files] Auto resize preview window width when resize terminal windows. #1564 (comment)
• Mini.files to toggle preview on demand #936 (reply in thread)
• [mini.files] configurability of max lines shown in file preview #1695 (comment)

Features

Multi-topic enhancement for mini.files preview with frequently requested features:

• Adjust preview width to fit the screen
• Toggle preview with <M-p>
• Scroll preview with <C-f>, <C-b>, <C-g>
• Numbered preview lines
• Custom preview error messages

Video

files-preview.mp4

Code

Click me

local MiniFiles = require("mini.files")
MiniFiles.setup({
  windows = {
    preview = false,
    width_preview = 100,
  },
})

local open_buf_file = function(buf)
  buf = buf or 0
  MiniFiles.open(vim.bo[buf].buftype == "" and vim.api.nvim_buf_get_name(buf) or nil, true)
end
-- stylua: ignore start
vim.keymap.set("n", "<Leader>F", function() MiniFiles.open() end, { desc = "Open files" })
vim.keymap.set("n", "<Leader>.F", function() open_buf_file() end, { desc = "Open files (current buf)" })
vim.keymap.set("n", "<Leader>@F", function() MiniFiles.open(vim.fn.getcwd()) end, { desc = "Open files (cwd)" })
vim.keymap.set("n", "<Leader>~F", function() MiniFiles.open("~") end, { desc = "Open files (system home)" })
-- stylua: ignore end

local files_au = vim.api.nvim_create_augroup("minifiles", { clear = true })

local files_get_path = function(buf)
  local path = vim.api.nvim_buf_get_name(buf):match("^minifiles://%d+/(.*)$")
  local stat = vim.uv.fs_stat(path)
  return path, stat
end

local get_preview_win = function()
  if not MiniFiles.config.windows.preview then
    return
  end
  local ok, state = pcall(MiniFiles.get_explorer_state)
  if not ok or not state then
    return
  end
  local rightmost_win = state.windows[#state.windows].win_id
  if rightmost_win == vim.api.nvim_get_current_win() then
    return
  end
  return rightmost_win
end

local preview_win_call = function(callback)
  local win = get_preview_win()
  if win then
    vim.api.nvim_win_call(win, callback)
  end
end

-- Set preview 'number'

vim.api.nvim_create_autocmd("User", {
  pattern = "MiniFilesWindowUpdate",
  desc = "Define `mini.files` window options",
  group = files_au,
  callback = function(e)
    local win = e.data.win_id
    local buf = e.data.buf_id
    local _, stat = files_get_path(buf)
    if stat and stat.type ~= "directory" then
      vim.wo[win].number = true
    end
  end,
})

-- Resize preview

local refresh_preview = function()
  local width_focus = MiniFiles.config.windows.width_focus
  local width_preview = MiniFiles.config.windows.width_preview
  local preview_width = math.min(vim.o.columns - width_focus - 4, width_preview)
  MiniFiles.refresh({ windows = { width_preview = preview_width } })
end
local resize_autocmd = function(event, opts)
  vim.api.nvim_create_autocmd(
    event,
    vim.tbl_extend("keep", opts, { desc = "Resize `mini.files` preview to be always visible", group = files_au })
  )
end
resize_autocmd("VimResized", { callback = refresh_preview })
resize_autocmd("User", { pattern = "MiniFilesWindowOpen", callback = vim.schedule_wrap(refresh_preview) })

-- Buf keymaps

-- NOTE: Toggle preview with <M-p>
--       Scroll preview with <C-f>, <C-b>, <C-g>

local toggle_preview = function()
  local is_preview = MiniFiles.config.windows.preview
  local is_preview_next = not is_preview
  MiniFiles.config.windows.preview = is_preview_next
  MiniFiles.trim_right()
  MiniFiles.refresh({ windows = { preview = is_preview_next } })
  if is_preview then
    local branch = MiniFiles.get_explorer_state().branch
    table.remove(branch)
    MiniFiles.set_branch(branch)
  end
end
local norm_in_preview = function(keys)
  preview_win_call(function()
    local key = vim.api.nvim_replace_termcodes(keys, true, false, true)
    vim.cmd.norm({ key, bang = true })
  end)
end
local jump_edges = function()
  preview_win_call(function()
    local last = vim.fn.line(".") == vim.fn.line("$")
    vim.cmd.norm({ last and "gg" or "G", bang = true })
  end)
end

vim.api.nvim_create_autocmd("User", {
  pattern = "MiniFilesBufferCreate",
  desc = "Set `mini.files` buffer keymaps",
  group = files_au,
  callback = function(e)
    local buf_map = function(mode, lhs, rhs, opts)
      opts = vim.tbl_extend("keep", opts or {}, { buffer = e.data.buf_id })
      vim.keymap.set(mode, lhs, rhs, opts)
    end
    -- stylua: ignore start
    buf_map("n", "<M-p>", function() toggle_preview() end, { desc = "Toggle preview" })
    buf_map("n", "<C-b>", function() norm_in_preview("<C-u>") end, { desc = "Scroll preview backwards" })
    buf_map("n", "<C-f>", function() norm_in_preview("<C-d>") end, { desc = "Scroll preview upwards" })
    buf_map("n", "<C-g>", function() jump_edges() end, { desc = "Jump edges" })
  end,
})

-- Custom preview: extend lines

-- NOTE: For performance reasons, MiniFiles limits the preview to the visible screen (vim.o.lines).
--       To enable scrolling, we need to manually set the number of lines for the preview.
--       Without this code, using scrolling keymaps (`<C-b>`,`<C-f>`,`<C-g>`) doesn't make sense.

-- https://github.com/nvim-mini/mini.nvim/blob/c163117900c17d4abf30bc09452a261c8536060c/lua/mini/files.lua#L2310-L2314
local validate_file = function(path)
  local fd, _, err = vim.uv.fs_open(path, "r", 1)
  if not fd then
    return err, nil
  end
  local is_binary = vim.uv.fs_read(fd, 1024):find("\0") ~= nil
  vim.uv.fs_close(fd)
  return false, is_binary
end

local files_preview_ns = vim.api.nvim_create_namespace("minifiles")

vim.api.nvim_create_autocmd("User", {
  pattern = "MiniFilesBufferUpdate",
  desc = "Extend `mini.files` preview lines; adjust preview error display",
  callback = function(args)
    local buf = args.data.buf_id
    local path, stat = files_get_path(buf)
    if not stat or stat.type == "directory" then
      return
    end
    local extm_id = 1
    local error = function(msg)
      local hl = "Text"
      vim.treesitter.stop(buf)
      vim.api.nvim_buf_set_lines(buf, 0, -1, true, {})
      vim.api.nvim_buf_set_extmark(buf, files_preview_ns, 0, 0, {
        id = extm_id,
        virt_text_pos = "overlay",
        virt_text = { { msg, hl } },
      })
    end
    local warn = function(msg)
      local hl = "WarningMsg"
      vim.api.nvim_buf_set_extmark(buf, files_preview_ns, 0, 0, {
        id = extm_id,
        virt_text_pos = "right_align",
        virt_text = { { msg, hl } },
      })
    end
    local no_access, is_binary = validate_file(path)
    local format_msg = function(msg)
      msg = " " .. msg .. string.rep(" ", MiniFiles.config.windows.width_preview)
      return string.gsub(msg, " ", "-")
    end
    if no_access then
      error(format_msg("No access"))
      return
    end
    if is_binary then
      error(format_msg("Non text file"))
      return
    end
    if stat.size > 512 * 1024 then
      warn("Large file detected (>512KB)")
      return
    end
    local read_ok, read_lines = pcall(vim.fn.readfile, path, "")
    if read_ok then
      local lines = vim.split(table.concat(read_lines, "\n"), "\n")
      vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
    end
  end,
})

[echasnovski]

Ooof. That's a lot of code :) Thanks for sharing!

I'll address couple of points:

• There is no scroll preview mostly because it reads only very limited portion at the start of the file. For better performance.
• Other customizations will probably be easier to do if/when I have made up my mind with the small config redesign. But not yet sure about specifics, so won't make it public yet.

[drowning-cat]

It would also be great to be able to focus the preview window, at least with the mouse.

[echasnovski]

Also probably not something that is aligned with how previews are treated in 'mini.files'. Again, mostly because there is a limited portion of the file shown for performance reasons.

[drowning-cat]

I understand, but I want to throw a few thoughts into the void that crossed my mind earlier:

1. I would use a different filetype for the preview buffer (or vim.b.minifiles_preview = true) to make it easier to distinguish it in autocmds.
2. I would allow focusing the preview window (disable cursor tracking when the preview window is focused).

I think changing focus from the preview window is kind of a bad side effect. It might be partially solvable in user space by using eventignore or by removing MiniFiles events, but I doubt these solutions will even work.

There might still be issues, such as the preview window sharing the same keymaps as other windows (for example, h jumps over one window). However, this can be easily fixed in the user configuration by adjusting keymaps manually in an autocmd.

Ideally, preview behavior should be supported at the configuration level, similar to how it works in mini.pick. This would make things like ZIP previews or scrollable previews much easier to implement.

But I consider point 2 especially important, because there's currently no way to address it through user configuration, as far as I know.