feat(#2948): extract _meta following nvim pattern

lua/nvim-tree/meta.lua → lua/nvim-tree/_meta/api.lua

@@ -1,9 +1,14 @@
 ---@meta
+error('Cannot require a meta file')
+
+-- TODO describe class
+-- TODO describe user decorator
 
 --
 -- Nodes
 --
 
+---Base Node, Abstract
 ---@class (exact) nvim_tree.api.Node: Class
 ---@field type "file" | "directory" | "link" uv.fs_stat.result.type
 ---@field absolute_path string
@@ -15,45 +20,41 @@
 ---@field parent nvim_tree.api.DirectoryNode?
 ---@field diag_severity lsp.DiagnosticSeverity?
 
+---File
 ---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
 ---@field extension string
 
+---Directory
 ---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
 ---@field has_children boolean
 ---@field nodes nvim_tree.api.Node[]
 ---@field open boolean
 
+---Root Directory
 ---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
 
+---Link mixin
 ---@class (exact) nvim_tree.api.LinkNode: Class
 ---@field link_to string
 ---@field fs_stat_target uv.fs_stat.result
 
+---File Link
 ---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
 
+---DirectoryLink
 ---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
 
 --
--- Decorators
+-- Various Types
 --
 
----Highlight group range as per nvim-tree.renderer.highlight_*
----@alias DecoratorHighlightRange "none" | "icon" | "name" | "all"
-
----Icon position as per renderer.icons.*_placement
----@alias DecoratorIconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
-
----Decorator Constructor Arguments
----@class (exact) DecoratorArgs
----@field enabled boolean
----@field highlight_range DecoratorHighlightRange
----@field icon_placement DecoratorIconPlacement
+---A string for rendering, with optional highlight groups to apply to it
+---@class (exact) nvim_tree.api.HighlightedString
+---@field str string
+---@field hl string[]
 
 --
--- Types
+-- Internal Aliases
 --
+---@alias HighlightedString nvim_tree.api.HighlightedString
 
----A string for rendering, with optional highlight groups to apply to it
----@class (exact) HighlightedString
----@field str string
----@field hl string[]

lua/nvim-tree/_meta/api_decorator.lua

@@ -0,0 +1,88 @@
+---@meta
+error('Cannot require a meta file')
+
+---Highlight group range as per nvim-tree.renderer.highlight_*
+---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
+
+---Icon position as per renderer.icons.*_placement
+---@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align"
+
+---UserDecorator Constructor Arguments
+---@class (exact) nvim_tree.api.decorator.UserDecoratorArgs
+---@field enabled boolean
+---@field highlight_range nvim_tree.api.decorator.HighlightRange
+---@field icon_placement nvim_tree.api.decorator.IconPlacement
+
+
+--
+-- Example UserDecorator
+--
+
+local UserDecorator = require("nvim-tree.renderer.decorator.user")
+
+---@class (exact) MyDecorator: UserDecorator
+---@field private my_icon nvim_tree.api.HighlightedString
+local MyDecorator = UserDecorator:extend()
+
+---Constructor
+function MyDecorator:new()
+
+  ---@type nvim_tree.api.decorator.UserDecoratorArgs
+  local args = {
+    enabled         = true,
+    highlight_range = "all",
+    icon_placement  = "signcolumn",
+  }
+
+  -- construct super with args
+  MyDecorator.super.new(self, args)
+
+  -- create your icon once, for convenience
+  self.my_icon = { str = "I", hl = { "MyIcon" } }
+
+  -- Define the icon sign only once
+  -- Only needed if you are using icon_placement = "signcolumn"
+  self:define_sign(self.my_icon)
+end
+
+---Overridde node icon
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.HighlightedString? icon_node
+function MyDecorator:icon_node(node)
+  if node.name == "example" then
+    return self.my_icon
+  else
+    return nil
+  end
+end
+
+---Return one icon for DecoratorIconPlacement
+---@param node nvim_tree.api.Node
+---@return nvim_tree.api.HighlightedString[]? icons
+function MyDecorator:icons(node)
+  if node.name == "example" then
+    return { self.my_icon }
+  else
+    return nil
+  end
+end
+
+---Exactly one highlight group for DecoratorHighlightRange
+---@param node nvim_tree.api.Node
+---@return string? highlight_group
+function MyDecorator:highlight_group(node)
+  if node.name == "example" then
+    return "MyHighlight"
+  else
+    return nil
+  end
+end
+
+return MyDecorator
+
+--
+-- Internal Aliases
+--
+---@alias DecoratorHighlightRange nvim_tree.api.decorator.HighlightRange
+---@alias DecoratorIconPlacement nvim_tree.api.decorator.IconPlacement
+

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

@@ -33,7 +33,7 @@ end
 
 ---Bookmark icon: renderer.icons.show.bookmarks and node is marked
 ---@param node Node
----@return HighlightedString[]|nil icons
+---@return HighlightedString[]? icons
 function DecoratorBookmarks:icons(node)
   if self.explorer.marks:get(node) then
     return { self.icon }
@@ -42,7 +42,7 @@ end
 
 ---Bookmark highlight: renderer.highlight_bookmarks and node is marked
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorBookmarks:highlight_group(node)
   if self.highlight_range ~= "none" and self.explorer.marks:get(node) then
     return "NvimTreeBookmarkHL"

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

@@ -24,7 +24,7 @@ end
 
 ---Copied highlight: renderer.highlight_clipboard and node is copied
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorCopied:highlight_group(node)
   if self.highlight_range ~= "none" and self.explorer.clipboard:is_copied(node) then
     return "NvimTreeCopiedHL"

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

@@ -24,7 +24,7 @@ end
 
 ---Cut highlight: renderer.highlight_clipboard and node is cut
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorCut:highlight_group(node)
   if self.highlight_range ~= "none" and self.explorer.clipboard:is_cut(node) then
     return "NvimTreeCutHL"

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

@@ -70,7 +70,7 @@ end
 
 ---Diagnostic icon: diagnostics.enable, renderer.icons.show.diagnostics and node has status
 ---@param node Node
----@return HighlightedString[]|nil icons
+---@return HighlightedString[]? icons
 function DecoratorDiagnostics:icons(node)
   if node and self.enabled and self.diag_icons then
     local diag_status = diagnostics.get_diag_status(node)
@@ -84,7 +84,7 @@ end
 
 ---Diagnostic highlight: diagnostics.enable, renderer.highlight_diagnostics and node has status
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorDiagnostics:highlight_group(node)
   if not node or not self.enabled or self.highlight_range == "none" then
     return nil

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

@@ -3,7 +3,7 @@ local notify = require("nvim-tree.notify")
 local Decorator = require("nvim-tree.renderer.decorator")
 local DirectoryNode = require("nvim-tree.node.directory")
 
----@class (exact) GitHighlightedString: HighlightedString
+---@class (exact) GitHighlightedString: nvim_tree.api.HighlightedString
 ---@field ord number decreasing priority
 
 ---@alias GitStatusStrings "deleted" | "ignored" | "renamed" | "staged" | "unmerged" | "unstaged" | "untracked"
@@ -147,7 +147,7 @@ end
 
 ---Git icons: git.enable, renderer.icons.show.git and node has status
 ---@param node Node
----@return HighlightedString[]|nil modified icon
+---@return HighlightedString[]? icons
 function DecoratorGit:icons(node)
   if not node or not self.enabled or not self.icons_by_xy then
     return nil
@@ -208,7 +208,7 @@ end
 
 ---Git highlight: git.enable, renderer.highlight_git and node has status
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorGit:highlight_group(node)
   if not node or not self.enabled or self.highlight_range == "none" then
     return nil

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

@@ -34,7 +34,7 @@ end
 
 ---Hidden icon: renderer.icons.show.hidden and node starts with `.` (dotfile).
 ---@param node Node
----@return HighlightedString[]|nil icons
+---@return HighlightedString[]? icons
 function DecoratorHidden:icons(node)
   if self.enabled and node:is_dotfile() then
     return { self.icon }
@@ -43,7 +43,7 @@ end
 
 ---Hidden highlight: renderer.highlight_hidden and node starts with `.` (dotfile).
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorHidden:highlight_group(node)
   if not self.enabled or self.highlight_range == "none" or not node:is_dotfile() then
     return nil

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

@@ -7,6 +7,11 @@ local Class = require("nvim-tree.classic")
 ---@field protected icon_placement DecoratorIconPlacement
 local Decorator = Class:extend()
 
+---@class (exact) DecoratorArgs
+---@field enabled boolean
+---@field highlight_range DecoratorHighlightRange
+---@field icon_placement DecoratorIconPlacement
+
 ---@protected
 ---@param args DecoratorArgs
 function Decorator:new(args)
@@ -105,7 +110,7 @@ end
 ---Maybe highlight group, optionally implemented
 ---@protected
 ---@param node Node
----@return string? group
+---@return string? highlight_group
 function Decorator:highlight_group(node)
   self:nop(node)
 end

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

@@ -40,7 +40,7 @@ end
 
 ---Modified icon: modified.enable, renderer.icons.show.modified and node is modified
 ---@param node Node
----@return HighlightedString[]|nil icons
+---@return HighlightedString[]? icons
 function DecoratorModified:icons(node)
   if self.enabled and buffers.is_modified(node) then
     return { self.icon }
@@ -49,7 +49,7 @@ end
 
 ---Modified highlight: modified.enable, renderer.highlight_modified and node is modified
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorModified:highlight_group(node)
   if not self.enabled or self.highlight_range == "none" or not buffers.is_modified(node) then
     return nil

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

@@ -27,7 +27,7 @@ end
 
 ---Opened highlight: renderer.highlight_opened_files and node has an open buffer
 ---@param node Node
----@return string|nil group
+---@return string? highlight_group
 function DecoratorOpened:highlight_group(node)
   if self.highlight_range ~= "none" and buffers.is_opened(node) then
     return "NvimTreeOpenedHL"