feat: better preview with the heading line at the top of the window

[sankantsu]

Hello, thanks for an awesome plugin!

Currently, default previewer (typically telescope.previewers.vim_buffer_vimgrep) positions the selected line at the center of preview window.
This behavior is good for pickers like telescope's builtin live_grep, but I prefer selected line (heading line) is positioned at the top of preview window for the heading picker, because all contents relevant to the selected heading are after (and not before) the heading line.

So, I implemented custom previewer for this purpose.

local previewers = require "telescope.previewers"
local from_entry = require "telescope.from_entry"
local conf = require("telescope.config").values

local ns = vim.api.nvim_create_namespace("")

function make_heading_previewer()
  local jump_to_line = function (self, bufnr, entry)
    print(self.state.bufname)
    print(vim.inspect(entry))
    vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
    vim.api.nvim_buf_add_highlight(bufnr, ns, "TelescopePreviewLine", entry.lnum-1, 0, -1)
    vim.api.nvim_win_set_cursor(self.state.winid, { entry.lnum, 0 })
    vim.api.nvim_buf_call(bufnr, function()
      vim.cmd "norm! zt"
    end)
  end
  return previewers.new_buffer_previewer {
    title = "Heading Preview",
    get_buffer_by_name = function (self, entry)
      return from_entry.path(entry, false)
    end,
    define_preview = function (self, entry)
      local p = from_entry.path(entry, true)
      if p == nil or p == "" then
        return
      end
      conf.buffer_previewer_maker(p, self.state.bufnr, {
        bufname = self.state.bufname,
        winid = self.state.winid,
        callback = function(bufnr)
          jump_to_line(self, bufnr, entry)
        end,
      })
    end,
  }
end

And it shows preview like this.

This configuration can be controlled completely in user side, but I don't think all users of this plugin want to implement custom previewer. So I think it is nice to use this heading previewer as default if you would like, or at least provide this previewer as the part of this plugin.
If you like this idea, I will happily submit PR.

Thank you!

[crispgm]

@sankantsu Thanks for your great explanation.
Generally, I like the idea. But telescope-heading is a telescope picker not previewer yet. Is it better if we made it a standalone previewer extension or even push into telescope core?

[sankantsu]

I think it is convinient if the telescope.nvims builtin vim_buffer_vimgrep previewer itself supports this type of customization. But currently it seems that telescope.nvim team generally do not want addition or feature enhancement of builtin picker/previewers to avoid extra maintainance costs. So I think providing previewer as an extension would be better.
nvim-telescope/telescope.nvim#1228

The above previewer is actually (a little) improved version of what I wrote in this issue.
nvim-telescope/telescope.nvim#2786

I implemented this previewer basically only for this telescope-heading.nvim picker. So it seems natural to me that the specialized previewer would be bundled with the picker.
But if you like separate repository for the previewer, it also makes sense.