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/node/init.lua

@@ -2,6 +2,7 @@ local Class = require("nvim-tree.classic")
 
 ---Abstract Node class.
 ---@class (exact) Node: Class
+---@field uid_node number vim.loop.hrtime() at construction time
 ---@field type "file" | "directory" | "link" uv.fs_stat.result.type
 ---@field explorer Explorer
 ---@field absolute_path string
@@ -25,6 +26,7 @@ local Node = Class:extend()
 ---@protected
 ---@param args NodeArgs
 function Node:new(args)
+  self.uid_node      = vim.loop.hrtime()
   self.explorer      = args.explorer
   self.absolute_path = args.absolute_path
   self.executable    = false
@@ -112,21 +114,19 @@ end
 
 ---Highlighted name for the node
 ---Empty for base Node
----@return HighlightedString icon
+---@return HighlightedString name
 function Node:highlighted_name()
   return self:highlighted_name_empty()
 end
 
 ---Create a sanitized partial copy of a node, populating children recursively.
----@return Node cloned
-function Node:clone()
-  ---@type Explorer
-  local explorer_placeholder = nil
-
-  ---@type Node
+---@param api_nodes table<number, nvim_tree.api.Node>? optional map of uids to api node to populate
+---@return nvim_tree.api.Node cloned
+function Node:clone(api_nodes)
+  ---@type nvim_tree.api.Node
   local clone = {
+    uid_node      = self.uid_node,
     type          = self.type,
-    explorer      = explorer_placeholder,
     absolute_path = self.absolute_path,
     executable    = self.executable,
     fs_stat       = self.fs_stat,
@@ -134,10 +134,13 @@ function Node:clone()
     hidden        = self.hidden,
     name          = self.name,
     parent        = nil,
-    diag_status   = nil,
-    is_dot        = self.is_dot,
+    diag_severity = self.diag_status and self.diag_status.value or nil,
   }
 
+  if api_nodes then
+    api_nodes[self.uid_node] = clone
+  end
+
   return clone
 end