feat(#2948): add custom decorators, :help nvim-tree-decorators (#2996)

* feat(#2948): add UserDecorator, proof of concept

* feat(#2948): add UserDecorator, proof of concept

* feat(#2948): add UserDecorator, proof of concept

* feat(#2948): add UserDecorator

* feat(#2948): add UserDecorator

* feat(#2948): add UserDecorator

* feat(#2948): add Decorator node icon override

* feat(#2948): add nvim_tree.api.* node classes

* feat(#2948): extract _meta following nvim pattern

* feat(#2948): extract _meta following nvim pattern

* feat(#2948): add decorator registry and order

* feat(#2948): add decorator registry and order

* feat(#2948): tidy

* feat(#2948): document API

* feat(#2948): document API

* feat(#2948): document API

* feat(#2948): pass api nodes to user decorators

* feat(#2948): document API

* feat(#2948): use renderer.decorators to define order and register

* feat(#2948): tidy decorator args and complete documentation

* feat(#2948): decorator classes specified by prefix rather than suffix

* feat(#2948): improve doc

* feat(#2948): improve doc

* feat(#2948): improve doc

* feat(#2948): additional user decorator safety

* feat(#2948): create nvim_tree.api.decorator.UserDecorator class in API, add :extend

* feat(#2948): improve doc

lua/nvim-tree/renderer/decorator/diagnostics.lua

@@ -30,58 +30,54 @@ local ICON_KEYS = {
   ["hint"] = vim.diagnostic.severity.HINT,
 }
 
----@class (exact) DecoratorDiagnostics: Decorator
----@field icons HighlightedString[]?
-local DecoratorDiagnostics = Decorator:extend()
+---@class (exact) DiagnosticsDecorator: Decorator
+---@field private explorer Explorer
+---@field private diag_icons HighlightedString[]?
+local DiagnosticsDecorator = Decorator:extend()
 
----@class DecoratorDiagnostics
----@overload fun(explorer: DecoratorArgs): DecoratorDiagnostics
+---@class DiagnosticsDecorator
+---@overload fun(args: DecoratorArgs): DiagnosticsDecorator
 
 ---@protected
 ---@param args DecoratorArgs
-function DecoratorDiagnostics:new(args)
-  Decorator.new(self, {
-    explorer       = args.explorer,
-    enabled        = true,
-    hl_pos         = args.explorer.opts.renderer.highlight_diagnostics or "none",
-    icon_placement = args.explorer.opts.renderer.icons.diagnostics_placement or "none",
-  })
+function DiagnosticsDecorator:new(args)
+  self.explorer        = args.explorer
 
-  if not self.enabled then
-    return
-  end
+  self.enabled         = true
+  self.highlight_range = self.explorer.opts.renderer.highlight_diagnostics or "none"
+  self.icon_placement  = self.explorer.opts.renderer.icons.diagnostics_placement or "none"
 
   if self.explorer.opts.renderer.icons.show.diagnostics then
-    self.icons = {}
+    self.diag_icons = {}
     for name, sev in pairs(ICON_KEYS) do
-      self.icons[sev] = {
+      self.diag_icons[sev] = {
         str = self.explorer.opts.diagnostics.icons[name],
         hl = { HG_ICON[sev] },
       }
-      self:define_sign(self.icons[sev])
+      self:define_sign(self.diag_icons[sev])
     end
   end
 end
 
 ---Diagnostic icon: diagnostics.enable, renderer.icons.show.diagnostics and node has status
 ---@param node Node
----@return HighlightedString[]|nil icons
-function DecoratorDiagnostics:calculate_icons(node)
-  if node and self.enabled and self.icons then
+---@return HighlightedString[]? icons
+function DiagnosticsDecorator:icons(node)
+  if node and self.diag_icons then
     local diag_status = diagnostics.get_diag_status(node)
     local diag_value = diag_status and diag_status.value
 
     if diag_value then
-      return { self.icons[diag_value] }
+      return { self.diag_icons[diag_value] }
     end
   end
 end
 
 ---Diagnostic highlight: diagnostics.enable, renderer.highlight_diagnostics and node has status
 ---@param node Node
----@return string|nil group
-function DecoratorDiagnostics:calculate_highlight(node)
-  if not node or not self.enabled or self.range == "none" then
+---@return string? highlight_group
+function DiagnosticsDecorator:highlight_group(node)
+  if self.highlight_range == "none" then
     return nil
   end
 
@@ -106,4 +102,4 @@ function DecoratorDiagnostics:calculate_highlight(node)
   end
 end
 
-return DecoratorDiagnostics
+return DiagnosticsDecorator