feat(#2948): user decorators

[alex-courtis]

fixes #2948

fixes #902

fixes #284

[b0o]

Looks great, awesome work! One thing is that I am getting some LuaLS type checker warnings when defining my decorator:

---@class (exact) DecoratorQuickfix: nvim_tree.api.decorator.UserDecorator
---@field private qf_icon nvim_tree.api.HighlightedString
local DecoratorQuickfix = require('nvim-tree.api').decorator.UserDecorator:extend()
-- ^ Undefined field `extend`.

local augroup = vim.api.nvim_create_augroup('nvim-tree-decorator-quickfix', { clear = true })

local autocmds_setup = false
local function setup_autocmds()
  if autocmds_setup then
    return
  end
  autocmds_setup = true
  vim.api.nvim_create_autocmd('QuickfixCmdPost', {
    group = augroup,
    callback = function() require('nvim-tree.api').tree.reload() end,
  })

  vim.api.nvim_create_autocmd('FileType', {
    pattern = 'qf',
    group = augroup,
    callback = function(evt)
      vim.api.nvim_create_autocmd('TextChanged', {
        buffer = evt.buf,
        group = augroup,
        callback = function() require('nvim-tree.api').tree.reload() end,
      })
    end,
  })
end

function DecoratorQuickfix:new()
  self.enabled = true
  self.highlight_range = 'all'
  self.icon_placement = 'signcolumn'
  self.qf_icon = { str = '', hl = { 'QuickFixLine' } }
  self:define_sign(self.qf_icon)
  -- ^ Undefined field `define_sign`.
  setup_autocmds()
end

---Helper function to check if a node is in quickfix list
---@param node nvim_tree.api.Node
---@return boolean
local function is_qf_item(node)
  if node.name == '..' or node.type == 'directory' then
    return false
  end
  local bufnr = vim.fn.bufnr(node.absolute_path)
  return bufnr ~= -1 and vim.iter(vim.fn.getqflist()):any(function(qf) return qf.bufnr == bufnr end)
end

---Return quickfix icons for the node
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString[]? icons
function DecoratorQuickfix:icons(node)
  if is_qf_item(node) then
    return { self.qf_icon }
  end
  return nil
end

---Return highlight group for the node
---@param node nvim_tree.api.Node
---@return string? highlight_group
function DecoratorQuickfix:highlight_group(node)
  if is_qf_item(node) then
    return 'QuickFixLine'
  end
  return nil
end

return DecoratorQuickfix

[alex-courtis]

LuaLS type checker warnings when defining my decorator:

Many thanks! It seems that luals needs the actual class table to exist. Hopefully that resolves the warnings.

I'll dogfood this for a week before releasing a new minor version.

I like QF; I'll be using that one. I've created a Decorators wiki page and I'd be most grateful if you shared it there.

[b0o]

Types are working now, and I added to the wiki!

[alex-courtis]

Types are working now, and I added to the wiki!

Lovely, thank you!

I added your name back if that's OK - everyone gets credited in the wiki...