From e53ff5ba71e0bd02e015f4a3e55749aaceba0281 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 31 Jan 2026 17:36:20 +1100 Subject: [PATCH 1/9] docs(#3241): namespace decorator types --- lua/nvim-tree/_meta/api_decorator.lua | 18 +++++++++--------- lua/nvim-tree/_meta/config/renderer.lua | 1 + lua/nvim-tree/api.lua | 6 +++++- lua/nvim-tree/api/impl/post.lua | 2 ++ lua/nvim-tree/api/impl/pre.lua | 2 ++ lua/nvim-tree/renderer/builder.lua | 6 +++--- lua/nvim-tree/renderer/decorator/git.lua | 2 +- lua/nvim-tree/renderer/decorator/init.lua | 6 ++++-- 8 files changed, 27 insertions(+), 16 deletions(-) diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index 4acca3a9acf..71ca352270d 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -4,16 +4,16 @@ error("Cannot require a meta file") local nvim_tree = { api = { decorator = {} } } ---Highlight group range as per nvim-tree.renderer.highlight_* ----@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all" +---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight ---Icon position as per renderer.icons.*_placement ----@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align" +---@alias nvim_tree.api.decorator.icon_placement "none"|nvim_tree.config.renderer.icons.placement ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority. ----@alias nvim_tree.api.decorator.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.UserDecorator +---@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.UserDecorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" ---A string for rendering, with optional highlight groups to apply to it ----@class (exact) nvim_tree.api.HighlightedString +---@class (exact) nvim_tree.api.decorator.highlighted_string ---@field str string ---@field hl string[] @@ -21,8 +21,8 @@ local nvim_tree = { api = { decorator = {} } } --- ---@class (exact) nvim_tree.api.decorator.UserDecorator ---@field protected enabled boolean ----@field protected highlight_range nvim_tree.api.decorator.HighlightRange ----@field protected icon_placement nvim_tree.api.decorator.IconPlacement +---@field protected highlight_range nvim_tree.api.decorator.highlight_range +---@field protected icon_placement nvim_tree.api.decorator.icon_placement nvim_tree.api.decorator.UserDecorator = {} ---Create your decorator class @@ -37,13 +37,13 @@ function nvim_tree.api.decorator.UserDecorator:new() end ---Abstract: optionally implement to set the node's icon --- ---@param node nvim_tree.api.Node ----@return nvim_tree.api.HighlightedString? icon_node +---@return nvim_tree.api.decorator.highlighted_string? icon_node function nvim_tree.api.decorator.UserDecorator:icon_node(node) end ---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. --- ---@param node nvim_tree.api.Node ----@return nvim_tree.api.HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function nvim_tree.api.decorator.UserDecorator:icons(node) end ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range. @@ -55,5 +55,5 @@ function nvim_tree.api.decorator.UserDecorator:highlight_group(node) end ---Define a sign. This should be called in the constructor. --- ---@protected ----@param icon nvim_tree.api.HighlightedString? +---@param icon nvim_tree.api.decorator.highlighted_string? function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index e1ba26cbb91..cf7826fe240 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -61,6 +61,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- +---TODO #3241 add an alias for builtins ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index e88b19d1f0a..be02d764994 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -96,10 +96,14 @@ local api = { -- --- Map before-setup implementations, most throw an error notification "nvim-tree setup not called". +-- Map before-setup function implementations, most throw an error notification "nvim-tree setup not called". -- require("nvim-tree.api.impl.pre")(api) +---#TODO 3241 +---Public API classes +-- api.decorator = require("nvim-tree.api.decorator") + return api diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua index 2aa5a3caec3..5c2d15de3d3 100644 --- a/lua/nvim-tree/api/impl/post.lua +++ b/lua/nvim-tree/api/impl/post.lua @@ -254,6 +254,8 @@ local function hydrate_post(api) api.map.keymap.current = keymap.get_keymap end +---#TODO 3241 hydrate function, for clarity + ---Re-hydrate api ---@param api table not properly typed to prevent LSP from referencing implementations return function(api) diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua index 7ad25ecb41f..4736d88da55 100644 --- a/lua/nvim-tree/api/impl/pre.lua +++ b/lua/nvim-tree/api/impl/pre.lua @@ -65,6 +65,8 @@ local function hydrate_pre(api) api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]] end +---#TODO 3241 hydrate function, for clarity + ---Hydrate api ---@param api table not properly typed to prevent LSP from referencing implementations return function(api) diff --git a/lua/nvim-tree/renderer/builder.lua b/lua/nvim-tree/renderer/builder.lua index 819660e5306..d3d06f86c07 100644 --- a/lua/nvim-tree/renderer/builder.lua +++ b/lua/nvim-tree/renderer/builder.lua @@ -14,14 +14,14 @@ local GitDecorator = require("nvim-tree.renderer.decorator.git") local HiddenDecorator = require("nvim-tree.renderer.decorator.hidden") local ModifiedDecorator = require("nvim-tree.renderer.decorator.modified") local OpenDecorator = require("nvim-tree.renderer.decorator.opened") -local UserDecorator = require("nvim-tree.renderer.decorator.user") +local UserDecorator = require("nvim-tree.api").decorator.UserDecorator local pad = require("nvim-tree.renderer.components.padding") ----@alias HighlightedString nvim_tree.api.HighlightedString +---@alias HighlightedString nvim_tree.api.decorator.highlighted_string -- Builtin Decorators ----@type table +---@type table local BUILTIN_DECORATORS = { Git = GitDecorator, Open = OpenDecorator, diff --git a/lua/nvim-tree/renderer/decorator/git.lua b/lua/nvim-tree/renderer/decorator/git.lua index c117b16959d..37fac2dcbed 100644 --- a/lua/nvim-tree/renderer/decorator/git.lua +++ b/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: nvim_tree.api.HighlightedString +---@class (exact) GitHighlightedString: nvim_tree.api.decorator.highlighted_string ---@field ord number decreasing priority ---@alias GitStatusStrings "deleted" | "ignored" | "renamed" | "staged" | "unmerged" | "unstaged" | "untracked" diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index cc7ab0ad305..82e2040de3e 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -1,10 +1,12 @@ local Class = require("nvim-tree.classic") +--- #TODO 3241 split this into abstract interface for API and concrete to return to user + ---Abstract Decorator ---@class (exact) Decorator: Class ---@field protected enabled boolean ----@field protected highlight_range nvim_tree.api.decorator.HighlightRange ----@field protected icon_placement nvim_tree.api.decorator.IconPlacement +---@field protected highlight_range nvim_tree.api.decorator.highlight_range +---@field protected icon_placement nvim_tree.api.decorator.icon_placement local Decorator = Class:extend() ---@class (exact) DecoratorArgs From c90ac64774e7f61f3693a115a50ae487df9b4f6b Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 10:41:19 +1100 Subject: [PATCH 2/9] docs(#3241): namespace decorator types --- doc/nvim-tree-lua.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index fcf0ef1bf3e..3a0cfd3a95e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -891,9 +891,9 @@ Require and register it during |nvim-tree-setup|: Contents of `my-decorator.lua`: >lua ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator - ---@field private my_icon1 nvim_tree.api.HighlightedString - ---@field private my_icon2 nvim_tree.api.HighlightedString - ---@field private my_icon_node nvim_tree.api.HighlightedString + ---@field private my_icon1 nvim_tree.api.decorator.highlighted_string + ---@field private my_icon2 nvim_tree.api.decorator.highlighted_string + ---@field private my_icon_node nvim_tree.api.decorator.highlighted_string ---@field private my_highlight_group string local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend() @@ -917,7 +917,7 @@ Contents of `my-decorator.lua`: ---Override node icon ---@param node nvim_tree.api.Node - ---@return nvim_tree.api.HighlightedString? icon_node + ---@return nvim_tree.api.decorator.highlighted_string? icon_node function MyDecorator:icon_node(node) if node.name == "example" then return self.my_icon_node @@ -928,7 +928,7 @@ Contents of `my-decorator.lua`: ---Return two icons for DecoratorIconPlacement "after" ---@param node nvim_tree.api.Node - ---@return nvim_tree.api.HighlightedString[]? icons + ---@return nvim_tree.api.decorator.highlighted_string[]? icons function MyDecorator:icons(node) if node.name == "example" then return { self.my_icon1, self.my_icon2, } From 5a2e12885fedfa9227c76617b610c161522a61db Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 11:04:29 +1100 Subject: [PATCH 3/9] docs(#3241): namespace decorator types --- lua/nvim-tree/_meta/config/renderer.lua | 1 - lua/nvim-tree/api.lua | 6 +++--- lua/nvim-tree/node/directory-link.lua | 4 ++-- lua/nvim-tree/node/directory.lua | 4 ++-- lua/nvim-tree/node/file-link.lua | 4 ++-- lua/nvim-tree/node/file.lua | 4 ++-- lua/nvim-tree/node/init.lua | 8 ++++---- lua/nvim-tree/renderer/builder.lua | 18 +++++++++--------- lua/nvim-tree/renderer/components/padding.lua | 4 ++-- lua/nvim-tree/renderer/decorator/bookmarks.lua | 4 ++-- .../renderer/decorator/diagnostics.lua | 4 ++-- lua/nvim-tree/renderer/decorator/git.lua | 2 +- lua/nvim-tree/renderer/decorator/hidden.lua | 4 ++-- lua/nvim-tree/renderer/decorator/init.lua | 12 ++++++------ lua/nvim-tree/renderer/decorator/modified.lua | 4 ++-- lua/nvim-tree/renderer/decorator/opened.lua | 2 +- 16 files changed, 42 insertions(+), 43 deletions(-) diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index cf7826fe240..e1ba26cbb91 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -61,7 +61,6 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- ----TODO #3241 add an alias for builtins ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index be02d764994..04182a1b745 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -101,9 +101,9 @@ local api = { require("nvim-tree.api.impl.pre")(api) ----#TODO 3241 ----Public API classes --- api.decorator = require("nvim-tree.api.decorator") +--#TODO 3241 +--Public API classes +--api.decorator = require("nvim-tree.api.decorator") return api diff --git a/lua/nvim-tree/node/directory-link.lua b/lua/nvim-tree/node/directory-link.lua index 6d503ad6d40..b1c19f54172 100644 --- a/lua/nvim-tree/node/directory-link.lua +++ b/lua/nvim-tree/node/directory-link.lua @@ -38,7 +38,7 @@ function DirectoryLinkNode:update_git_status(parent_ignored, project) self.git_status = git_utils.git_status_dir(parent_ignored, project, self.link_to, self.absolute_path) end ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function DirectoryLinkNode:highlighted_icon() if not self.explorer.opts.renderer.icons.show.folder then return self:highlighted_icon_empty() @@ -58,7 +58,7 @@ function DirectoryLinkNode:highlighted_icon() end ---Maybe override name with arrow ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function DirectoryLinkNode:highlighted_name() local name = DirectoryNode.highlighted_name(self) diff --git a/lua/nvim-tree/node/directory.lua b/lua/nvim-tree/node/directory.lua index d53718085f9..9b376e7b6f6 100644 --- a/lua/nvim-tree/node/directory.lua +++ b/lua/nvim-tree/node/directory.lua @@ -198,7 +198,7 @@ function DirectoryNode:expand_or_collapse(toggle_group) self.explorer.renderer:draw() end ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function DirectoryNode:highlighted_icon() if not self.explorer.opts.renderer.icons.show.folder then return self:highlighted_icon_empty() @@ -243,7 +243,7 @@ function DirectoryNode:highlighted_icon() return { str = str, hl = { hl } } end ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function DirectoryNode:highlighted_name() local str, hl diff --git a/lua/nvim-tree/node/file-link.lua b/lua/nvim-tree/node/file-link.lua index 6cb83e0343a..7130897ddec 100644 --- a/lua/nvim-tree/node/file-link.lua +++ b/lua/nvim-tree/node/file-link.lua @@ -31,7 +31,7 @@ function FileLinkNode:update_git_status(parent_ignored, project) self.git_status = git_utils.git_status_file(parent_ignored, project, self.link_to, self.absolute_path) end ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function FileLinkNode:highlighted_icon() if not self.explorer.opts.renderer.icons.show.file then return self:highlighted_icon_empty() @@ -46,7 +46,7 @@ function FileLinkNode:highlighted_icon() return { str = str, hl = { hl } } end ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function FileLinkNode:highlighted_name() local str = self.name if self.explorer.opts.renderer.symlink_destination then diff --git a/lua/nvim-tree/node/file.lua b/lua/nvim-tree/node/file.lua index bba1621e21b..2b0ea0362c9 100644 --- a/lua/nvim-tree/node/file.lua +++ b/lua/nvim-tree/node/file.lua @@ -50,7 +50,7 @@ function FileNode:get_git_xy() return self.git_status.file and { self.git_status.file } end ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function FileNode:highlighted_icon() if not self.explorer.opts.renderer.icons.show.file then return self:highlighted_icon_empty() @@ -79,7 +79,7 @@ function FileNode:highlighted_icon() return { str = str, hl = { hl } } end ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function FileNode:highlighted_name() local hl if vim.tbl_contains(self.explorer.opts.renderer.special_files, self.absolute_path) or vim.tbl_contains(self.explorer.opts.renderer.special_files, self.name) then diff --git a/lua/nvim-tree/node/init.lua b/lua/nvim-tree/node/init.lua index 5aaf4fb094a..4c8d5c81daa 100644 --- a/lua/nvim-tree/node/init.lua +++ b/lua/nvim-tree/node/init.lua @@ -93,28 +93,28 @@ end ---Empty highlighted icon ---@protected ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function Node:highlighted_icon_empty() return { str = "", hl = {} } end ---Highlighted icon for the node ---Empty for base Node ----@return HighlightedString icon +---@return nvim_tree.api.decorator.highlighted_string icon function Node:highlighted_icon() return self:highlighted_icon_empty() end ---Empty highlighted name ---@protected ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function Node:highlighted_name_empty() return { str = "", hl = {} } end ---Highlighted name for the node ---Empty for base Node ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string name function Node:highlighted_name() return self:highlighted_name_empty() end diff --git a/lua/nvim-tree/renderer/builder.lua b/lua/nvim-tree/renderer/builder.lua index d3d06f86c07..d74ed2c7d64 100644 --- a/lua/nvim-tree/renderer/builder.lua +++ b/lua/nvim-tree/renderer/builder.lua @@ -18,7 +18,7 @@ local UserDecorator = require("nvim-tree.api").decorator.UserDecorator local pad = require("nvim-tree.renderer.components.padding") ----@alias HighlightedString nvim_tree.api.decorator.highlighted_string +---TODO #3241 add an alias for builtins or document the enum -- Builtin Decorators ---@type table @@ -106,7 +106,7 @@ function Builder:insert_highlight(groups, start, end_) end ---@private ----@param highlighted_strings HighlightedString[] +---@param highlighted_strings nvim_tree.api.decorator.highlighted_string[] ---@return string function Builder:unwrap_highlighted_strings(highlighted_strings) if not highlighted_strings then @@ -126,12 +126,12 @@ function Builder:unwrap_highlighted_strings(highlighted_strings) end ---@private ----@param indent_markers HighlightedString[] ----@param arrows HighlightedString[]|nil ----@param icon HighlightedString ----@param name HighlightedString +---@param indent_markers nvim_tree.api.decorator.highlighted_string[] +---@param arrows? nvim_tree.api.decorator.highlighted_string[] +---@param icon nvim_tree.api.decorator.highlighted_string +---@param name nvim_tree.api.decorator.highlighted_string ---@param node table ----@return HighlightedString[] +---@return nvim_tree.api.decorator.highlighted_string[] function Builder:format_line(indent_markers, arrows, icon, name, node) local added_len = 0 local function add_to_end(t1, t2) @@ -231,8 +231,8 @@ end ---A highlight group is always calculated and upserted for the case of highlights changing. ---@private ---@param node Node ----@return HighlightedString icon ----@return HighlightedString name +---@return nvim_tree.api.decorator.highlighted_string icon +---@return nvim_tree.api.decorator.highlighted_string name function Builder:icon_name_decorated(node) -- use the api node for user decorators local api_node = self.api_nodes and self.api_nodes[node.uid_node] --[[@as Node]] diff --git a/lua/nvim-tree/renderer/components/padding.lua b/lua/nvim-tree/renderer/components/padding.lua index a33525cc437..a8289b4d4e1 100644 --- a/lua/nvim-tree/renderer/components/padding.lua +++ b/lua/nvim-tree/renderer/components/padding.lua @@ -64,7 +64,7 @@ end ---@param node Node ---@param markers table ---@param early_stop integer? ----@return HighlightedString +---@return nvim_tree.api.decorator.highlighted_string function M.get_indent_markers(depth, idx, nodes_number, node, markers, early_stop) local str = "" @@ -83,7 +83,7 @@ function M.get_indent_markers(depth, idx, nodes_number, node, markers, early_sto end ---@param node Node ----@return HighlightedString[]|nil +---@return nvim_tree.api.decorator.highlighted_string[]? function M.get_arrows(node) if not M.config.icons.show.folder_arrow then return diff --git a/lua/nvim-tree/renderer/decorator/bookmarks.lua b/lua/nvim-tree/renderer/decorator/bookmarks.lua index c661748ef21..5c6bff438e2 100644 --- a/lua/nvim-tree/renderer/decorator/bookmarks.lua +++ b/lua/nvim-tree/renderer/decorator/bookmarks.lua @@ -2,7 +2,7 @@ local Decorator = require("nvim-tree.renderer.decorator") ---@class (exact) BookmarkDecorator: Decorator ---@field private explorer Explorer ----@field private icon HighlightedString? +---@field private icon nvim_tree.api.decorator.highlighted_string? local BookmarkDecorator = Decorator:extend() ---@class BookmarkDecorator @@ -28,7 +28,7 @@ end ---Bookmark icon: renderer.icons.show.bookmarks and node is marked ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function BookmarkDecorator:icons(node) if self.explorer.marks:get(node) then return { self.icon } diff --git a/lua/nvim-tree/renderer/decorator/diagnostics.lua b/lua/nvim-tree/renderer/decorator/diagnostics.lua index 56598ef9418..fd7ceba6446 100644 --- a/lua/nvim-tree/renderer/decorator/diagnostics.lua +++ b/lua/nvim-tree/renderer/decorator/diagnostics.lua @@ -32,7 +32,7 @@ local ICON_KEYS = { ---@class (exact) DiagnosticsDecorator: Decorator ---@field private explorer Explorer ----@field private diag_icons HighlightedString[]? +---@field private diag_icons nvim_tree.api.decorator.highlighted_string[]? local DiagnosticsDecorator = Decorator:extend() ---@class DiagnosticsDecorator @@ -73,7 +73,7 @@ end ---Diagnostic icon: diagnostics.enable, renderer.icons.show.diagnostics and node has status ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function DiagnosticsDecorator:icons(node) if node and self.diag_icons then local diag_status = diagnostics.get_diag_status(node) diff --git a/lua/nvim-tree/renderer/decorator/git.lua b/lua/nvim-tree/renderer/decorator/git.lua index 37fac2dcbed..bcd83df99a2 100644 --- a/lua/nvim-tree/renderer/decorator/git.lua +++ b/lua/nvim-tree/renderer/decorator/git.lua @@ -142,7 +142,7 @@ end ---Git icons: git.enable, renderer.icons.show.git and node has status ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function GitDecorator:icons(node) if not self.icons_by_xy then return nil diff --git a/lua/nvim-tree/renderer/decorator/hidden.lua b/lua/nvim-tree/renderer/decorator/hidden.lua index 87168ceb82b..bffd82c370b 100644 --- a/lua/nvim-tree/renderer/decorator/hidden.lua +++ b/lua/nvim-tree/renderer/decorator/hidden.lua @@ -3,7 +3,7 @@ local DirectoryNode = require("nvim-tree.node.directory") ---@class (exact) HiddenDecorator: Decorator ---@field private explorer Explorer ----@field private icon HighlightedString? +---@field private icon nvim_tree.api.decorator.highlighted_string? local HiddenDecorator = Decorator:extend() ---@class HiddenDecorator @@ -29,7 +29,7 @@ end ---Hidden icon: renderer.icons.show.hidden and node starts with `.` (dotfile). ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function HiddenDecorator:icons(node) if node:is_dotfile() then return { self.icon } diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index 82e2040de3e..013ab0cba28 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -14,7 +14,7 @@ local Decorator = Class:extend() ---Abstract icon override, optionally implemented ---@param node Node ----@return HighlightedString? icon_node +---@return nvim_tree.api.decorator.highlighted_string? icon_node function Decorator:icon_node(node) return self:nop(node) end @@ -22,7 +22,7 @@ end ---Abstract icons, optionally implemented ---@protected ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function Decorator:icons(node) self:nop(node) end @@ -72,7 +72,7 @@ end ---Icons when "before" ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function Decorator:icons_before(node) if not self.enabled or self.icon_placement ~= "before" then return @@ -83,7 +83,7 @@ end ---Icons when "after" ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function Decorator:icons_after(node) if not self.enabled or self.icon_placement ~= "after" then return @@ -94,7 +94,7 @@ end ---Icons when "right_align" ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function Decorator:icons_right_align(node) if not self.enabled or self.icon_placement ~= "right_align" then return @@ -105,7 +105,7 @@ end ---Define a sign ---@protected ----@param icon HighlightedString? +---@param icon nvim_tree.api.decorator.highlighted_string? function Decorator:define_sign(icon) if icon and #icon.hl > 0 then local name = icon.hl[1] diff --git a/lua/nvim-tree/renderer/decorator/modified.lua b/lua/nvim-tree/renderer/decorator/modified.lua index c182e300afc..ee41d7d90cd 100644 --- a/lua/nvim-tree/renderer/decorator/modified.lua +++ b/lua/nvim-tree/renderer/decorator/modified.lua @@ -5,7 +5,7 @@ local DirectoryNode = require("nvim-tree.node.directory") ---@class (exact) ModifiedDecorator: Decorator ---@field private explorer Explorer ----@field private icon HighlightedString? +---@field private icon nvim_tree.api.decorator.highlighted_string? local ModifiedDecorator = Decorator:extend() ---@class ModifiedDecorator @@ -31,7 +31,7 @@ end ---Modified icon: modified.enable, renderer.icons.show.modified and node is modified ---@param node Node ----@return HighlightedString[]? icons +---@return nvim_tree.api.decorator.highlighted_string[]? icons function ModifiedDecorator:icons(node) if buffers.is_modified(node) then return { self.icon } diff --git a/lua/nvim-tree/renderer/decorator/opened.lua b/lua/nvim-tree/renderer/decorator/opened.lua index 240dce4948a..094a893211c 100644 --- a/lua/nvim-tree/renderer/decorator/opened.lua +++ b/lua/nvim-tree/renderer/decorator/opened.lua @@ -4,7 +4,7 @@ local Decorator = require("nvim-tree.renderer.decorator") ---@class (exact) OpenDecorator: Decorator ---@field private explorer Explorer ----@field private icon HighlightedString|nil +---@field private icon? nvim_tree.api.decorator.highlighted_string local OpenDecorator = Decorator:extend() ---@class OpenDecorator From 9f969030b3ee3715af5afc017197966593310159 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 13:23:05 +1100 Subject: [PATCH 4/9] docs(#3241): api exposes nvim_tree.api.decorator.Decorator interface, UserDecorator deprecated --- doc/nvim-tree-lua.txt | 20 +++---- lua/nvim-tree.lua | 2 +- lua/nvim-tree/_meta/api_decorator.lua | 38 ++++++------- lua/nvim-tree/_meta/config/renderer.lua | 2 +- lua/nvim-tree/api.lua | 26 +++------ lua/nvim-tree/api/impl/legacy.lua | 8 ++- lua/nvim-tree/api/impl/post.lua | 19 +++---- lua/nvim-tree/api/impl/pre.lua | 68 ++++++++--------------- lua/nvim-tree/renderer/builder.lua | 2 +- lua/nvim-tree/renderer/decorator/init.lua | 32 +---------- 10 files changed, 78 insertions(+), 139 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 3a0cfd3a95e..651de1096bd 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -890,31 +890,31 @@ Require and register it during |nvim-tree-setup|: < Contents of `my-decorator.lua`: >lua - ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator + ---@class (exact) MyDecorator: nvim_tree.api.decorator.Decorator ---@field private my_icon1 nvim_tree.api.decorator.highlighted_string ---@field private my_icon2 nvim_tree.api.decorator.highlighted_string ---@field private my_icon_node nvim_tree.api.decorator.highlighted_string ---@field private my_highlight_group string - local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend() - + local MyDecorator = require("nvim-tree.api").decorator.Decorator:extend() + ---Mandatory constructor :new() will be called once per tree render, with no arguments. function MyDecorator:new() self.enabled = true self.highlight_range = "name" self.icon_placement = "after" - + -- create your icons and highlights once, applied to every node self.my_icon1 = { str = "1", hl = { "DiffAdd" } } self.my_icon2 = { str = "2", hl = { "DiffText" } } self.my_icon_node = { str = "N", hl = { "Error" } } self.my_highlight_group = "IncSearch" - + -- Define the icon signs only once -- Only needed if you are using icon_placement = "signcolumn" -- self:define_sign(self.my_icon1) -- self:define_sign(self.my_icon2) end - + ---Override node icon ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string? icon_node @@ -925,7 +925,7 @@ Contents of `my-decorator.lua`: return nil end end - + ---Return two icons for DecoratorIconPlacement "after" ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string[]? icons @@ -936,7 +936,7 @@ Contents of `my-decorator.lua`: return nil end end - + ---Exactly one highlight group for DecoratorHighlightRange "name" ---@param node nvim_tree.api.Node ---@return string? highlight_group @@ -947,7 +947,7 @@ Contents of `my-decorator.lua`: return nil end end - + return MyDecorator < ============================================================================== @@ -1366,7 +1366,7 @@ Config: renderer *nvim-tree-config-renderer* • {symlink_destination}? (`boolean`, default: `true`) Appends an arrow followed by the target of the symlink. - • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + • {decorators}? (`(string|nvim_tree.api.decorator.Decorator)[]`) (default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) • {highlight_git}? (`nvim_tree.config.renderer.highlight`) diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua index 4d4dad7b1f3..7d3a79b46de 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -813,7 +813,7 @@ function M.setup(conf) vim.g.NvimTreeSetup = 1 vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" }) - require("nvim-tree.api.impl.post")(api) + require("nvim-tree.api.impl.post").hydrate(api) end vim.g.NvimTreeRequired = 1 diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index 71ca352270d..787c0e0f557 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -1,8 +1,9 @@ ---@meta -error("Cannot require a meta file") - +--- local nvim_tree = { api = { decorator = {} } } +local Class = require("nvim-tree.classic") + ---Highlight group range as per nvim-tree.renderer.highlight_* ---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight @@ -10,50 +11,47 @@ local nvim_tree = { api = { decorator = {} } } ---@alias nvim_tree.api.decorator.icon_placement "none"|nvim_tree.config.renderer.icons.placement ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority. ----@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.UserDecorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" +---@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" ---A string for rendering, with optional highlight groups to apply to it ---@class (exact) nvim_tree.api.decorator.highlighted_string ---@field str string ---@field hl string[] ----Custom decorator, see :help nvim-tree-decorators +---Abstract Decorator interface --- ----@class (exact) nvim_tree.api.decorator.UserDecorator +---@class (exact) nvim_tree.api.decorator.Decorator: Class ---@field protected enabled boolean ---@field protected highlight_range nvim_tree.api.decorator.highlight_range ---@field protected icon_placement nvim_tree.api.decorator.icon_placement -nvim_tree.api.decorator.UserDecorator = {} - ----Create your decorator class ---- -function nvim_tree.api.decorator.UserDecorator:extend() end - ----Abstract: no-args constructor must be implemented and will be called once per tree render. ----Must set all fields. ---- -function nvim_tree.api.decorator.UserDecorator:new() end +nvim_tree.api.decorator.Decorator = Class:extend() ---Abstract: optionally implement to set the node's icon --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string? icon_node -function nvim_tree.api.decorator.UserDecorator:icon_node(node) end +function nvim_tree.api.decorator.Decorator:icon_node(node) end ---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string[]? icons -function nvim_tree.api.decorator.UserDecorator:icons(node) end +function nvim_tree.api.decorator.Decorator:icons(node) end ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range. --- ---@param node nvim_tree.api.Node ---@return string? highlight_group -function nvim_tree.api.decorator.UserDecorator:highlight_group(node) end +function nvim_tree.api.decorator.Decorator:highlight_group(node) end ----Define a sign. This should be called in the constructor. +---Defines a sign. This should be called in the constructor. --- ---@protected ---@param icon nvim_tree.api.decorator.highlighted_string? -function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end +function nvim_tree.api.decorator.Decorator:define_sign(icon) end + +---@deprecated use `nvim_tree.api.decorator.Decorator` +---@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.decorator.Decorator +nvim_tree.api.decorator.UserDecorator = nvim_tree.api.decorator.Decorator + +return nvim_tree.api.decorator diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index e1ba26cbb91..ab9d6c5505e 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -62,7 +62,7 @@ error("Cannot require a meta file") ---@field symlink_destination? boolean --- ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ----@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +---@field decorators? (string|nvim_tree.api.decorator.Decorator)[] --- ---(default: `"none"`) ---@field highlight_git? nvim_tree.config.renderer.highlight diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index 04182a1b745..6c0be191624 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -69,16 +69,14 @@ --- --- Load the (empty) meta definitions --- -local deprecated = require("nvim-tree._meta.api.deprecated") - +--- ---nvim-tree Public API +--- ---@class nvim_tree.api ---@nodoc local api = { commands = require("nvim-tree._meta.api.commands"), + decorator = require("nvim-tree._meta.api_decorator"), events = require("nvim-tree._meta.api.events"), filter = require("nvim-tree._meta.api.filter"), fs = require("nvim-tree._meta.api.fs"), @@ -89,21 +87,11 @@ local api = { node = require("nvim-tree._meta.api.node"), tree = require("nvim-tree._meta.api.tree"), - config = deprecated.config, ---@deprecated - diagnostics = deprecated.diagnostics, ---@deprecated - live_filter = deprecated.live_filter, ---@deprecated + config = require("nvim-tree._meta.api.deprecated").config, ---@deprecated + diagnostics = require("nvim-tree._meta.api.deprecated").diagnostics, ---@deprecated + live_filter = require("nvim-tree._meta.api.deprecated").live_filter, ---@deprecated } - --- --- Map before-setup function implementations, most throw an error notification "nvim-tree setup not called". --- -require("nvim-tree.api.impl.pre")(api) - - ---#TODO 3241 ---Public API classes ---api.decorator = require("nvim-tree.api.decorator") - +require("nvim-tree.api.impl.pre").hydrate(api) return api diff --git a/lua/nvim-tree/api/impl/legacy.lua b/lua/nvim-tree/api/impl/legacy.lua index 51924b4f365..bcab89322d2 100644 --- a/lua/nvim-tree/api/impl/legacy.lua +++ b/lua/nvim-tree/api/impl/legacy.lua @@ -1,6 +1,8 @@ +local M = {} + ---Silently create new api entries pointing legacy functions to current ---@param api table not properly typed to prevent LSP from referencing implementations -return function(api) +function M.hydrate(api) api.config = api.config or {} api.config.mappings = api.config.mappings or {} api.config.mappings.get_keymap = api.map.keymap.current @@ -22,4 +24,8 @@ return function(api) api.diagnostics = api.diagnostics or {} api.diagnostics.hi_test = api.health.hi_test + + api.decorator.UserDecorator = api.decorator.Decorator end + +return M diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua index 5c2d15de3d3..5d772387e6a 100644 --- a/lua/nvim-tree/api/impl/post.lua +++ b/lua/nvim-tree/api/impl/post.lua @@ -16,6 +16,8 @@ local DirectoryNode = require("nvim-tree.node.directory") local FileLinkNode = require("nvim-tree.node.file-link") local RootNode = require("nvim-tree.node.root") +local M = {} + ---Invoke a method on the singleton explorer. ---Print error when setup not called. ---@param explorer_method string explorer method name @@ -133,9 +135,9 @@ local function open_or_expand_or_dir_up(mode, toggle_group) end end ----Hydrate all implementations barring those that were called during hydrate_pre +---Re-Hydrate api functions and classes post-setup ---@param api table not properly typed to prevent LSP from referencing implementations -local function hydrate_post(api) +function M.hydrate(api) api.tree.open = actions.tree.open.fn api.tree.focus = api.tree.open @@ -252,16 +254,9 @@ local function hydrate_post(api) api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select") api.map.keymap.current = keymap.get_keymap -end - ----#TODO 3241 hydrate function, for clarity - ----Re-hydrate api ----@param api table not properly typed to prevent LSP from referencing implementations -return function(api) - -- All concrete implementations - hydrate_post(api) -- (Re)hydrate any legacy by mapping to function set above - require("nvim-tree.api.impl.legacy")(api) + require("nvim-tree.api.impl.legacy").hydrate(api) end + +return M diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua index 4736d88da55..0eed8f6b884 100644 --- a/lua/nvim-tree/api/impl/pre.lua +++ b/lua/nvim-tree/api/impl/pre.lua @@ -1,6 +1,7 @@ ---Hydrates meta api empty definition functions with a new function: --- - Default: error notification "nvim-tree setup not called". --- - Exceptions: concrete implementation for API that can be called before setup. +--Hydrates meta api empty definitions pre-setup: +-- - Pre-setup functions will be hydrated with their concrete implementation. +-- - Post-setup functions will notify error: "nvim-tree setup not called" +-- - All classes will be hydrated with their implementations. -- --Call it once when api is first required -- @@ -15,67 +16,44 @@ local notify = require("nvim-tree.notify") -- already required by events and local UserDecorator = require("nvim-tree.renderer.decorator.user") ----Walk the api, hydrating all functions with the error notification ----@param t table api root or sub-module +local M = {} + +---Walk the api, hydrating all functions with the error notification. +---Do not hydrate classes: anything with a metatable. +---@param t table local function hydrate_error(t) for k, v in pairs(t) do if type(v) == "function" then t[k] = function() notify.error("nvim-tree setup not called") end - elseif type(v) == "table" then + elseif type(v) == "table" and not getmetatable(v) then hydrate_error(v) end end end ----Hydrate implementations that may be called pre setup +---Hydrate api functions and classes pre-setup ---@param api table not properly typed to prevent LSP from referencing implementations -local function hydrate_pre(api) - -- - -- Essential - -- +function M.hydrate(api) + -- default to the error message + hydrate_error(api) + + -- eager functions api.events.Event = events.Event api.events.subscribe = events.subscribe - api.map.on_attach.default = keymap.on_attach_default - - - -- - -- May be lazily requried on execution - -- - api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end - - - -- - -- Already required elsewhere - -- api.commands.get = commands.get - api.map.keymap.default = keymap.get_keymap_default + -- lazy functions + api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end - -- - -- TODO #3241 - -- - api.decorator = {} - ---Create a decorator class by calling :extend() - ---See :help nvim-tree-decorators - ---@type nvim_tree.api.decorator.UserDecorator - api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]] -end - ----#TODO 3241 hydrate function, for clarity - ----Hydrate api ----@param api table not properly typed to prevent LSP from referencing implementations -return function(api) - -- Default: error - hydrate_error(api) - - -- Exceptions: may be called - hydrate_pre(api) + -- classes + api.decorator.Decorator = UserDecorator:extend() -- Hydrate any legacy by mapping to function set above - require("nvim-tree.api.impl.legacy")(api) + require("nvim-tree.api.impl.legacy").hydrate(api) end + +return M diff --git a/lua/nvim-tree/renderer/builder.lua b/lua/nvim-tree/renderer/builder.lua index d74ed2c7d64..d38d64c2873 100644 --- a/lua/nvim-tree/renderer/builder.lua +++ b/lua/nvim-tree/renderer/builder.lua @@ -14,7 +14,7 @@ local GitDecorator = require("nvim-tree.renderer.decorator.git") local HiddenDecorator = require("nvim-tree.renderer.decorator.hidden") local ModifiedDecorator = require("nvim-tree.renderer.decorator.modified") local OpenDecorator = require("nvim-tree.renderer.decorator.opened") -local UserDecorator = require("nvim-tree.api").decorator.UserDecorator +local UserDecorator = require("nvim-tree.renderer.decorator.user") local pad = require("nvim-tree.renderer.components.padding") diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index 013ab0cba28..7552ed4b3ab 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -1,40 +1,14 @@ -local Class = require("nvim-tree.classic") - ---- #TODO 3241 split this into abstract interface for API and concrete to return to user - ----Abstract Decorator +---Abstract Decorator implementation ---@class (exact) Decorator: Class ---@field protected enabled boolean ---@field protected highlight_range nvim_tree.api.decorator.highlight_range ---@field protected icon_placement nvim_tree.api.decorator.icon_placement -local Decorator = Class:extend() +local Decorator = require("nvim-tree._meta.api_decorator").Decorator:extend() +---TODO #3241 maybe create an internal decorator class and lose the UserDecorator ---@class (exact) DecoratorArgs ---@field explorer Explorer ----Abstract icon override, optionally implemented ----@param node Node ----@return nvim_tree.api.decorator.highlighted_string? icon_node -function Decorator:icon_node(node) - return self:nop(node) -end - ----Abstract icons, optionally implemented ----@protected ----@param node Node ----@return nvim_tree.api.decorator.highlighted_string[]? icons -function Decorator:icons(node) - self:nop(node) -end - ----Abstract highlight group, optionally implemented ----@protected ----@param node Node ----@return string? highlight_group -function Decorator:highlight_group(node) - self:nop(node) -end - ---Maybe highlight groups for icon and name ---@param node Node ---@return string? icon highlight group From dac8aee04cf8170ad5df09c54c8d2f14fde1f192 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 13:25:53 +1100 Subject: [PATCH 5/9] docs(#3241): move decorator meta into place --- lua/nvim-tree/_meta/{api_decorator.lua => api/decorator.lua} | 0 lua/nvim-tree/api.lua | 2 +- lua/nvim-tree/renderer/decorator/init.lua | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename lua/nvim-tree/_meta/{api_decorator.lua => api/decorator.lua} (100%) diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api/decorator.lua similarity index 100% rename from lua/nvim-tree/_meta/api_decorator.lua rename to lua/nvim-tree/_meta/api/decorator.lua diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index 6c0be191624..67d06e688b4 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -76,7 +76,7 @@ ---@nodoc local api = { commands = require("nvim-tree._meta.api.commands"), - decorator = require("nvim-tree._meta.api_decorator"), + decorator = require("nvim-tree._meta.api.decorator"), events = require("nvim-tree._meta.api.events"), filter = require("nvim-tree._meta.api.filter"), fs = require("nvim-tree._meta.api.fs"), diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index 7552ed4b3ab..feff51d10c8 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -3,7 +3,7 @@ ---@field protected enabled boolean ---@field protected highlight_range nvim_tree.api.decorator.highlight_range ---@field protected icon_placement nvim_tree.api.decorator.icon_placement -local Decorator = require("nvim-tree._meta.api_decorator").Decorator:extend() +local Decorator = require("nvim-tree._meta.api.decorator").Decorator:extend() ---TODO #3241 maybe create an internal decorator class and lose the UserDecorator ---@class (exact) DecoratorArgs From e466a371c536058c555f8e6795761c440b4cadbd Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 16:59:31 +1100 Subject: [PATCH 6/9] docs(#3241): generate decorator help --- doc/nvim-tree-lua.txt | 119 +++++++++++++++++++++- lua/nvim-tree/_meta/api/decorator.lua | 38 ++++--- lua/nvim-tree/_meta/config/default.lua | 1 + lua/nvim-tree/api/impl/post.lua | 2 +- lua/nvim-tree/api/impl/pre.lua | 2 +- lua/nvim-tree/classic.lua | 6 +- lua/nvim-tree/renderer/decorator/init.lua | 2 +- scripts/gen_vimdoc_config.lua | 90 +++++++++++----- 8 files changed, 215 insertions(+), 45 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 651de1096bd..a9e40615426 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -2362,9 +2362,6 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua }, } < - - - ============================================================================== API *nvim-tree-api* @@ -3200,4 +3197,120 @@ winid({opts}) *nvim_tree.api.tree.winid()* (`integer?`) |window-ID|, nil if tree is not visible. +============================================================================== +API: Decorator *nvim-tree-api-decorator* + +*nvim_tree.api.decorator.Decorator* + Extends: |nvim_tree.Class| + + Abstract Decorator interface + + Fields: ~ + • {enabled} (`boolean`) + • {highlight_range} (`nvim_tree.api.decorator.highlight_range`) + • {icon_placement} (`nvim_tree.api.decorator.icon_placement`) + • {icon_node} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`) + See + |nvim_tree.api.decorator.Decorator:icon_node()|. + • {icons} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string[]?`) + See |nvim_tree.api.decorator.Decorator:icons()|. + • {highlight_group} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): string?`) + See + |nvim_tree.api.decorator.Decorator:highlight_group()|. + • {define_sign} (`fun(self: nvim_tree.api.decorator.Decorator, icon: nvim_tree.api.decorator.highlighted_string?)`) + See + |nvim_tree.api.decorator.Decorator:define_sign()|. + + + *nvim_tree.api.decorator.Decorator:define_sign()* +Decorator:define_sign({icon}) + Defines a sign. This should be called in the constructor. + + Parameters: ~ + • {icon} (`nvim_tree.api.decorator.highlighted_string?`) + + *nvim_tree.api.decorator.Decorator:highlight_group()* +Decorator:highlight_group({node}) + Abstract: optionally implement to provide one highlight group to apply to + your highlight_range. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`string?`) highlight_group + + *nvim_tree.api.decorator.Decorator:icon_node()* +Decorator:icon_node({node}) + Abstract: optionally implement to set the node's icon + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.decorator.highlighted_string?`) icon_node + +Decorator:icons({node}) *nvim_tree.api.decorator.Decorator:icons()* + Abstract: optionally implement to provide icons and the highlight groups + for your icon_placement. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.decorator.highlighted_string[]?`) icons + + +============================================================================== +API: Class *nvim-tree-api-class* + +*nvim_tree.Class* + + Fields: ~ + • {super} (`Class`) + • {extend} (`fun(self: nvim_tree.Class)`) See + |nvim_tree.Class:extend()|. + • {implement} (`fun(self: nvim_tree.Class, mixin: Class)`) See + |nvim_tree.Class:implement()|. + • {is} (`fun(self: nvim_tree.Class, class: T): boolean`) See + |nvim_tree.Class:is()|. + • {as} (`fun(self: nvim_tree.Class, class: T): T?`) See + |nvim_tree.Class:as()|. + • {nop} (`fun(self: nvim_tree.Class, ...: any)`) See + |nvim_tree.Class:nop()|. + + +Class:as({class}) *nvim_tree.Class:as()* + Return object if :is otherwise nil + + Parameters: ~ + • {class} (`any`) + + Return: ~ + (`T?`) + +Class:extend() *nvim_tree.Class:extend()* + Extend a class, setting .super + +Class:implement({mixin}) *nvim_tree.Class:implement()* + Implement the functions of a mixin Add the mixin to .implements + + Parameters: ~ + • {mixin} (`Class`) + +Class:is({class}) *nvim_tree.Class:is()* + Object is an instance of class or implements a mixin + + Parameters: ~ + • {class} (`any`) + + Return: ~ + (`boolean`) + +Class:nop({...}) *nvim_tree.Class:nop()* + + Parameters: ~ + • {...} (`any`) + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree/_meta/api/decorator.lua b/lua/nvim-tree/_meta/api/decorator.lua index 787c0e0f557..de347c7a7f0 100644 --- a/lua/nvim-tree/_meta/api/decorator.lua +++ b/lua/nvim-tree/_meta/api/decorator.lua @@ -1,57 +1,71 @@ ---@meta ---- local nvim_tree = { api = { decorator = {} } } local Class = require("nvim-tree.classic") +--- ---Highlight group range as per nvim-tree.renderer.highlight_* +--- ---@alias nvim_tree.api.decorator.highlight_range nvim_tree.config.renderer.highlight ---Icon position as per renderer.icons.*_placement +--- ---@alias nvim_tree.api.decorator.icon_placement "none"|nvim_tree.config.renderer.icons.placement +--- ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority. +--- ---@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" +--- ---A string for rendering, with optional highlight groups to apply to it +--- ---@class (exact) nvim_tree.api.decorator.highlighted_string ---@field str string ---@field hl string[] +--- ---Abstract Decorator interface --- ----@class (exact) nvim_tree.api.decorator.Decorator: Class ----@field protected enabled boolean ----@field protected highlight_range nvim_tree.api.decorator.highlight_range ----@field protected icon_placement nvim_tree.api.decorator.icon_placement -nvim_tree.api.decorator.Decorator = Class:extend() +---@class nvim_tree.api.decorator.Decorator: nvim_tree.Class +---@field enabled boolean +---@field highlight_range nvim_tree.api.decorator.highlight_range +---@field icon_placement nvim_tree.api.decorator.icon_placement +local Decorator = Class:extend() +nvim_tree.api.decorator.Decorator = Decorator +--- ---Abstract: optionally implement to set the node's icon --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string? icon_node -function nvim_tree.api.decorator.Decorator:icon_node(node) end +function Decorator:icon_node(node) end +--- ---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.decorator.highlighted_string[]? icons -function nvim_tree.api.decorator.Decorator:icons(node) end +function Decorator:icons(node) end +--- ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range. --- ---@param node nvim_tree.api.Node ---@return string? highlight_group -function nvim_tree.api.decorator.Decorator:highlight_group(node) end +function Decorator:highlight_group(node) end +--- ---Defines a sign. This should be called in the constructor. --- ----@protected ---@param icon nvim_tree.api.decorator.highlighted_string? -function nvim_tree.api.decorator.Decorator:define_sign(icon) end +function Decorator:define_sign(icon) end ----@deprecated use `nvim_tree.api.decorator.Decorator` +--- ---@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.decorator.Decorator +---@nodoc +---@deprecated use `nvim_tree.api.decorator.Decorator` +--- nvim_tree.api.decorator.UserDecorator = nvim_tree.api.decorator.Decorator return nvim_tree.api.decorator diff --git a/lua/nvim-tree/_meta/config/default.lua b/lua/nvim-tree/_meta/config/default.lua index 1f1252f7483..710c6cb3502 100644 --- a/lua/nvim-tree/_meta/config/default.lua +++ b/lua/nvim-tree/_meta/config/default.lua @@ -9,3 +9,4 @@ ---} ---``` --- +---placeholder for next section [nvim-tree-api]() diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua index 5d772387e6a..181753a34ce 100644 --- a/lua/nvim-tree/api/impl/post.lua +++ b/lua/nvim-tree/api/impl/post.lua @@ -255,7 +255,7 @@ function M.hydrate(api) api.map.keymap.current = keymap.get_keymap - -- (Re)hydrate any legacy by mapping to function set above + -- (Re)hydrate any legacy by mapping to concrete set above require("nvim-tree.api.impl.legacy").hydrate(api) end diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua index 0eed8f6b884..1bdf4dfaf0b 100644 --- a/lua/nvim-tree/api/impl/pre.lua +++ b/lua/nvim-tree/api/impl/pre.lua @@ -52,7 +52,7 @@ function M.hydrate(api) -- classes api.decorator.Decorator = UserDecorator:extend() - -- Hydrate any legacy by mapping to function set above + -- Hydrate any legacy by mapping to concrete set above require("nvim-tree.api.impl.legacy").hydrate(api) end diff --git a/lua/nvim-tree/classic.lua b/lua/nvim-tree/classic.lua index 6e856bc90c0..08a05c1ee44 100644 --- a/lua/nvim-tree/classic.lua +++ b/lua/nvim-tree/classic.lua @@ -9,7 +9,11 @@ -- https://github.com/rxi/classic -- ----@class (exact) Class +---TODO #3241 document and rename +---@class Class: nvim_tree.Class +---@nodoc + +---@class nvim_tree.Class ---@field super Class ---@field private implements table local Class = {} diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index feff51d10c8..e3cbe4b6666 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -5,7 +5,7 @@ ---@field protected icon_placement nvim_tree.api.decorator.icon_placement local Decorator = require("nvim-tree._meta.api.decorator").Decorator:extend() ----TODO #3241 maybe create an internal decorator class and lose the UserDecorator +---TODO #3241 create an internal decorator class with explorer member and lose the UserDecorator ---@class (exact) DecoratorArgs ---@field explorer Explorer diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index d5d7bf4636f..03d8f706bce 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -10,6 +10,14 @@ ---@field section string arbitrary ---@field path string relative to root +---TODO #3241 do this for all classes, moving decorator up to nvim_tree.api.Decorator + +---Module overrides +---@type table +local module_overrides = { + ["nvim_tree.classic"] = "nvim_tree" +} + local pre = "runtime/lua/nvim_tree/" ---@type Src[] @@ -39,24 +47,24 @@ local srcs_config = { { helptag = "nvim-tree-config-log", section = "Config: log", path = pre .. "_meta/config/log.lua", }, { helptag = "nvim-tree-config-default", section = "Config: Default", path = pre .. "_meta/config/default.lua", }, - - { helptag = "nvim-tree-api", section = "placeholder for next Config", path = pre .. "api.lua", }, } ---@type Src[] local srcs_api = { - { helptag = "nvim-tree-api", section = "API", path = pre .. "api.lua", }, - - { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", }, - { helptag = "nvim-tree-api-events", section = "API: events", path = pre .. "_meta/api/events.lua", }, - { helptag = "nvim-tree-api-filter", section = "API: filter", path = pre .. "_meta/api/filter.lua", }, - { helptag = "nvim-tree-api-fs", section = "API: fs", path = pre .. "_meta/api/fs.lua", }, - { helptag = "nvim-tree-api-git", section = "API: git", path = pre .. "_meta/api/git.lua", }, - { helptag = "nvim-tree-api-health", section = "API: health", path = pre .. "_meta/api/health.lua", }, - { helptag = "nvim-tree-api-map", section = "API: map", path = pre .. "_meta/api/map.lua", }, - { helptag = "nvim-tree-api-marks", section = "API: marks", path = pre .. "_meta/api/marks.lua", }, - { helptag = "nvim-tree-api-node", section = "API: node", path = pre .. "_meta/api/node.lua", }, - { helptag = "nvim-tree-api-tree", section = "API: tree", path = pre .. "_meta/api/tree.lua", }, + { helptag = "nvim-tree-api", section = "API", path = pre .. "api.lua", }, + + { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", }, + { helptag = "nvim-tree-api-events", section = "API: events", path = pre .. "_meta/api/events.lua", }, + { helptag = "nvim-tree-api-filter", section = "API: filter", path = pre .. "_meta/api/filter.lua", }, + { helptag = "nvim-tree-api-fs", section = "API: fs", path = pre .. "_meta/api/fs.lua", }, + { helptag = "nvim-tree-api-git", section = "API: git", path = pre .. "_meta/api/git.lua", }, + { helptag = "nvim-tree-api-health", section = "API: health", path = pre .. "_meta/api/health.lua", }, + { helptag = "nvim-tree-api-map", section = "API: map", path = pre .. "_meta/api/map.lua", }, + { helptag = "nvim-tree-api-marks", section = "API: marks", path = pre .. "_meta/api/marks.lua", }, + { helptag = "nvim-tree-api-node", section = "API: node", path = pre .. "_meta/api/node.lua", }, + { helptag = "nvim-tree-api-tree", section = "API: tree", path = pre .. "_meta/api/tree.lua", }, + { helptag = "nvim-tree-api-decorator", section = "API: Decorator", path = pre .. "_meta/api/decorator.lua", }, + { helptag = "nvim-tree-api-class", section = "API: Class", path = pre .. "classic.lua", }, } ---Map paths to file names @@ -92,6 +100,17 @@ local function src_by_name(name, srcs) error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs))) end +---HACK +---Problem: +--- Generator generates fields for a class' methods. +--- This is a problem as method fields don't have a module and aren't transformed. +--- Method field fun only contains: classvar, desc, name and (function) type +---Solution: +--- Collect a map of "class:method" to modules when the real method passes through fn_xform +--- This works as the real method function is processed before the field method. +---@type table +local modules_by_method = {} + -- @type nvim.gen_vimdoc.Config[] return { -- Config @@ -110,23 +129,42 @@ return { section_fmt = function(name) return src_by_name(name, srcs_api).section end, helptag_fmt = function(name) return src_by_name(name, srcs_api).helptag end, - -- optional, no default xform to override fn_xform = function(fun) - if (fun.module) then - -- generator doesn't strip meta - -- also cascades into fn_helptag_fmt - local module = fun.module:gsub("._meta", "", 1) - - -- remove the API prefix from the left aligned function name - -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway - local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1) + -- generator doesn't strip _meta; this propagates to fn_helptag_fmt + fun.module = fun.module:gsub("._meta", "", 1) + fun.module = module_overrides[fun.module] or fun.module + + if not fun.class then + -- functions require the module to be stripped from the name, classes do not + local name, replaced = fun.name:gsub("^" .. fun.module .. "%.", "", 1) if (replaced ~= 1) then - error(string.format("\n\nfun.name='%s' does not start with _meta stripped module='%s'\nfun=%s", fun.name, module, vim.inspect(fun))) + error(string.format("\n\nfn_xform: fun.name='%s' does not start with _meta stripped \nfun=%s", + fun.name, vim.inspect(fun))) end - - fun.module = module fun.name = name + elseif fun.class and fun.classvar and fun.name then + -- note the module for use by method fields + modules_by_method[fun.classvar .. ":" .. fun.name] = fun.module + end + end, + + -- fn_helptag_fmt_common modified: + -- module prepended to classes + -- module is fetched from modules_by_method when fun.module unavailable + fn_helptag_fmt = function(fun) + local fn_sfx = fun.table and "" or "()" + if fun.classvar then + local module = fun.module or modules_by_method[fun.classvar .. ":" .. fun.name] + if not module then + error(string.format("\n\nfn_helptag_fmt: no module:\nfun=%s\nmodules_by_method=%s", + vim.inspect(fun), vim.inspect(modules_by_method))) + end + return string.format("%s.%s:%s%s", module, fun.classvar, fun.name, fn_sfx) + end + if fun.module then + return string.format("%s.%s%s", fun.module, fun.name, fn_sfx) end + return fun.name .. fn_sfx end, } } From b30b2706e4a57f85a85000e63275dab9793697dc Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 1 Feb 2026 17:53:15 +1100 Subject: [PATCH 7/9] docs(#3241): separate api and class generation configs, namespace classes without their filename, nicer generation placeholder --- doc/nvim-tree-lua.txt | 46 +++++----- lua/nvim-tree/_meta/api/decorator.lua | 17 ++-- lua/nvim-tree/_meta/api/deprecated.lua | 6 ++ lua/nvim-tree/_meta/config/default.lua | 2 - lua/nvim-tree/_meta/config/renderer.lua | 2 +- lua/nvim-tree/api.lua | 4 +- lua/nvim-tree/api/impl/legacy.lua | 2 +- lua/nvim-tree/api/impl/pre.lua | 2 +- lua/nvim-tree/classic.lua | 4 +- lua/nvim-tree/renderer/decorator/init.lua | 2 +- scripts/gen_vimdoc.sh | 3 + scripts/gen_vimdoc_config.lua | 102 +++++++++++----------- 12 files changed, 97 insertions(+), 95 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index a9e40615426..a5ebc95061a 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -890,12 +890,12 @@ Require and register it during |nvim-tree-setup|: < Contents of `my-decorator.lua`: >lua - ---@class (exact) MyDecorator: nvim_tree.api.decorator.Decorator + ---@class (exact) MyDecorator: nvim_tree.api.Decorator ---@field private my_icon1 nvim_tree.api.decorator.highlighted_string ---@field private my_icon2 nvim_tree.api.decorator.highlighted_string ---@field private my_icon_node nvim_tree.api.decorator.highlighted_string ---@field private my_highlight_group string - local MyDecorator = require("nvim-tree.api").decorator.Decorator:extend() + local MyDecorator = require("nvim-tree.api").Decorator:extend() ---Mandatory constructor :new() will be called once per tree render, with no arguments. function MyDecorator:new() @@ -1366,7 +1366,7 @@ Config: renderer *nvim-tree-config-renderer* • {symlink_destination}? (`boolean`, default: `true`) Appends an arrow followed by the target of the symlink. - • {decorators}? (`(string|nvim_tree.api.decorator.Decorator)[]`) + • {decorators}? (`(string|nvim_tree.api.Decorator)[]`) (default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) • {highlight_git}? (`nvim_tree.config.renderer.highlight`) @@ -2362,6 +2362,9 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua }, } < + + + ============================================================================== API *nvim-tree-api* @@ -3200,7 +3203,7 @@ winid({opts}) *nvim_tree.api.tree.winid()* ============================================================================== API: Decorator *nvim-tree-api-decorator* -*nvim_tree.api.decorator.Decorator* +*nvim_tree.api.Decorator* Extends: |nvim_tree.Class| Abstract Decorator interface @@ -3209,27 +3212,23 @@ API: Decorator *nvim-tree-api-decorator* • {enabled} (`boolean`) • {highlight_range} (`nvim_tree.api.decorator.highlight_range`) • {icon_placement} (`nvim_tree.api.decorator.icon_placement`) - • {icon_node} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`) - See - |nvim_tree.api.decorator.Decorator:icon_node()|. - • {icons} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string[]?`) - See |nvim_tree.api.decorator.Decorator:icons()|. - • {highlight_group} (`fun(self: nvim_tree.api.decorator.Decorator, node: nvim_tree.api.Node): string?`) - See - |nvim_tree.api.decorator.Decorator:highlight_group()|. - • {define_sign} (`fun(self: nvim_tree.api.decorator.Decorator, icon: nvim_tree.api.decorator.highlighted_string?)`) - See - |nvim_tree.api.decorator.Decorator:define_sign()|. - - - *nvim_tree.api.decorator.Decorator:define_sign()* -Decorator:define_sign({icon}) + • {icon_node} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string?`) + See |nvim_tree.api.Decorator:icon_node()|. + • {icons} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.decorator.highlighted_string[]?`) + See |nvim_tree.api.Decorator:icons()|. + • {highlight_group} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): string?`) + See |nvim_tree.api.Decorator:highlight_group()|. + • {define_sign} (`fun(self: nvim_tree.api.Decorator, icon: nvim_tree.api.decorator.highlighted_string?)`) + See |nvim_tree.api.Decorator:define_sign()|. + + +Decorator:define_sign({icon}) *nvim_tree.api.Decorator:define_sign()* Defines a sign. This should be called in the constructor. Parameters: ~ • {icon} (`nvim_tree.api.decorator.highlighted_string?`) - *nvim_tree.api.decorator.Decorator:highlight_group()* + *nvim_tree.api.Decorator:highlight_group()* Decorator:highlight_group({node}) Abstract: optionally implement to provide one highlight group to apply to your highlight_range. @@ -3240,8 +3239,7 @@ Decorator:highlight_group({node}) Return: ~ (`string?`) highlight_group - *nvim_tree.api.decorator.Decorator:icon_node()* -Decorator:icon_node({node}) +Decorator:icon_node({node}) *nvim_tree.api.Decorator:icon_node()* Abstract: optionally implement to set the node's icon Parameters: ~ @@ -3250,7 +3248,7 @@ Decorator:icon_node({node}) Return: ~ (`nvim_tree.api.decorator.highlighted_string?`) icon_node -Decorator:icons({node}) *nvim_tree.api.decorator.Decorator:icons()* +Decorator:icons({node}) *nvim_tree.api.Decorator:icons()* Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. @@ -3281,7 +3279,7 @@ API: Class *nvim-tree-api-class* Class:as({class}) *nvim_tree.Class:as()* - Return object if :is otherwise nil + Return object if |nvim_tree.Class:is()| otherwise nil Parameters: ~ • {class} (`any`) diff --git a/lua/nvim-tree/_meta/api/decorator.lua b/lua/nvim-tree/_meta/api/decorator.lua index de347c7a7f0..9ebb9954ab2 100644 --- a/lua/nvim-tree/_meta/api/decorator.lua +++ b/lua/nvim-tree/_meta/api/decorator.lua @@ -1,5 +1,5 @@ ---@meta -local nvim_tree = { api = { decorator = {} } } +local nvim_tree = { api = {} } local Class = require("nvim-tree.classic") @@ -15,7 +15,7 @@ local Class = require("nvim-tree.classic") --- ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority. --- ----@alias nvim_tree.api.decorator.types nvim_tree.api.decorator.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" +---@alias nvim_tree.api.decorator.types nvim_tree.api.Decorator|"Git"|"Opened"|"Hidden"|"Modified"|"Bookmarks"|"Diagnostics"|"Copied"|"Cut" --- ---A string for rendering, with optional highlight groups to apply to it @@ -27,12 +27,12 @@ local Class = require("nvim-tree.classic") --- ---Abstract Decorator interface --- ----@class nvim_tree.api.decorator.Decorator: nvim_tree.Class +---@class nvim_tree.api.Decorator: nvim_tree.Class ---@field enabled boolean ---@field highlight_range nvim_tree.api.decorator.highlight_range ---@field icon_placement nvim_tree.api.decorator.icon_placement local Decorator = Class:extend() -nvim_tree.api.decorator.Decorator = Decorator +nvim_tree.api.Decorator = Decorator --- ---Abstract: optionally implement to set the node's icon @@ -61,11 +61,4 @@ function Decorator:highlight_group(node) end ---@param icon nvim_tree.api.decorator.highlighted_string? function Decorator:define_sign(icon) end ---- ----@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.decorator.Decorator ----@nodoc ----@deprecated use `nvim_tree.api.decorator.Decorator` ---- -nvim_tree.api.decorator.UserDecorator = nvim_tree.api.decorator.Decorator - -return nvim_tree.api.decorator +return nvim_tree.api.Decorator diff --git a/lua/nvim-tree/_meta/api/deprecated.lua b/lua/nvim-tree/_meta/api/deprecated.lua index fdd4b88e85a..f9f37852225 100644 --- a/lua/nvim-tree/_meta/api/deprecated.lua +++ b/lua/nvim-tree/_meta/api/deprecated.lua @@ -30,4 +30,10 @@ nvim_tree.api.diagnostics = {} ---@deprecated use `nvim_tree.api.health.hi_test()` function nvim_tree.api.diagnostics.hi_test() end +nvim_tree.api.decorator = {} + +---@class nvim_tree.api.decorator.UserDecorator: nvim_tree.api.Decorator +---@deprecated use `nvim_tree.api.Decorator` +nvim_tree.api.decorator.UserDecorator = nvim_tree.api.Decorator + return nvim_tree.api diff --git a/lua/nvim-tree/_meta/config/default.lua b/lua/nvim-tree/_meta/config/default.lua index 710c6cb3502..6566a1ed4ab 100644 --- a/lua/nvim-tree/_meta/config/default.lua +++ b/lua/nvim-tree/_meta/config/default.lua @@ -8,5 +8,3 @@ ---default-config-injection-placeholder ---} ---``` ---- ----placeholder for next section [nvim-tree-api]() diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index ab9d6c5505e..8979eb8614e 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -62,7 +62,7 @@ error("Cannot require a meta file") ---@field symlink_destination? boolean --- ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ----@field decorators? (string|nvim_tree.api.decorator.Decorator)[] +---@field decorators? (string|nvim_tree.api.Decorator)[] --- ---(default: `"none"`) ---@field highlight_git? nvim_tree.config.renderer.highlight diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index 67d06e688b4..81250fe5fca 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -76,7 +76,6 @@ ---@nodoc local api = { commands = require("nvim-tree._meta.api.commands"), - decorator = require("nvim-tree._meta.api.decorator"), events = require("nvim-tree._meta.api.events"), filter = require("nvim-tree._meta.api.filter"), fs = require("nvim-tree._meta.api.fs"), @@ -87,7 +86,10 @@ local api = { node = require("nvim-tree._meta.api.node"), tree = require("nvim-tree._meta.api.tree"), + Decorator = require("nvim-tree._meta.api.decorator"), + config = require("nvim-tree._meta.api.deprecated").config, ---@deprecated + decorator = require("nvim-tree._meta.api.deprecated").decorator, ---@deprecated diagnostics = require("nvim-tree._meta.api.deprecated").diagnostics, ---@deprecated live_filter = require("nvim-tree._meta.api.deprecated").live_filter, ---@deprecated } diff --git a/lua/nvim-tree/api/impl/legacy.lua b/lua/nvim-tree/api/impl/legacy.lua index bcab89322d2..66f817f6669 100644 --- a/lua/nvim-tree/api/impl/legacy.lua +++ b/lua/nvim-tree/api/impl/legacy.lua @@ -25,7 +25,7 @@ function M.hydrate(api) api.diagnostics = api.diagnostics or {} api.diagnostics.hi_test = api.health.hi_test - api.decorator.UserDecorator = api.decorator.Decorator + api.decorator.UserDecorator = api.Decorator end return M diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua index 1bdf4dfaf0b..5ce5f67ac05 100644 --- a/lua/nvim-tree/api/impl/pre.lua +++ b/lua/nvim-tree/api/impl/pre.lua @@ -50,7 +50,7 @@ function M.hydrate(api) api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end -- classes - api.decorator.Decorator = UserDecorator:extend() + api.Decorator = UserDecorator:extend() -- Hydrate any legacy by mapping to concrete set above require("nvim-tree.api.impl.legacy").hydrate(api) diff --git a/lua/nvim-tree/classic.lua b/lua/nvim-tree/classic.lua index 08a05c1ee44..1431e5bb38c 100644 --- a/lua/nvim-tree/classic.lua +++ b/lua/nvim-tree/classic.lua @@ -72,7 +72,7 @@ function Class:is(class) return false end ----Return object if :is otherwise nil +---Return object if [nvim_tree.Class:is()] otherwise nil ---@generic T ---@param class T ---@return T|nil @@ -80,7 +80,7 @@ function Class:as(class) return self:is(class) and self or nil end ----Constructor to create instance, call :new and return +---Constructor to create instance, call [nvim_tree.Class:new()] and return function Class:__call(...) local obj = setmetatable({}, self) obj:new(...) diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index e3cbe4b6666..d5d2b1a7931 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -3,7 +3,7 @@ ---@field protected enabled boolean ---@field protected highlight_range nvim_tree.api.decorator.highlight_range ---@field protected icon_placement nvim_tree.api.decorator.icon_placement -local Decorator = require("nvim-tree._meta.api.decorator").Decorator:extend() +local Decorator = require("nvim-tree._meta.api.decorator"):extend() ---TODO #3241 create an internal decorator class with explorer member and lose the UserDecorator ---@class (exact) DecoratorArgs diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh index 93d7e171708..8f190a532f3 100755 --- a/scripts/gen_vimdoc.sh +++ b/scripts/gen_vimdoc.sh @@ -65,6 +65,9 @@ export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua" mkdir -pv "${DIR_WORK}/runtime/lua" ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/runtime/lua/nvim_tree" +# leave a generic placeholder to bridge between nvim.gen_vimdoc.Config +echo "---@brief placeholder" > "${DIR_WORK}/runtime/lua/placeholder.lua" + # generate cd "${DIR_WORK}" && pwd ./gen_vimdoc.lua diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 03d8f706bce..73ac9d19c60 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -10,14 +10,6 @@ ---@field section string arbitrary ---@field path string relative to root ----TODO #3241 do this for all classes, moving decorator up to nvim_tree.api.Decorator - ----Module overrides ----@type table -local module_overrides = { - ["nvim_tree.classic"] = "nvim_tree" -} - local pre = "runtime/lua/nvim_tree/" ---@type Src[] @@ -47,22 +39,30 @@ local srcs_config = { { helptag = "nvim-tree-config-log", section = "Config: log", path = pre .. "_meta/config/log.lua", }, { helptag = "nvim-tree-config-default", section = "Config: Default", path = pre .. "_meta/config/default.lua", }, + + { helptag = "nvim-tree-api", section = "PLACEHOLDER", path = "runtime/lua/placeholder.lua", }, } ---@type Src[] local srcs_api = { - { helptag = "nvim-tree-api", section = "API", path = pre .. "api.lua", }, - - { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", }, - { helptag = "nvim-tree-api-events", section = "API: events", path = pre .. "_meta/api/events.lua", }, - { helptag = "nvim-tree-api-filter", section = "API: filter", path = pre .. "_meta/api/filter.lua", }, - { helptag = "nvim-tree-api-fs", section = "API: fs", path = pre .. "_meta/api/fs.lua", }, - { helptag = "nvim-tree-api-git", section = "API: git", path = pre .. "_meta/api/git.lua", }, - { helptag = "nvim-tree-api-health", section = "API: health", path = pre .. "_meta/api/health.lua", }, - { helptag = "nvim-tree-api-map", section = "API: map", path = pre .. "_meta/api/map.lua", }, - { helptag = "nvim-tree-api-marks", section = "API: marks", path = pre .. "_meta/api/marks.lua", }, - { helptag = "nvim-tree-api-node", section = "API: node", path = pre .. "_meta/api/node.lua", }, - { helptag = "nvim-tree-api-tree", section = "API: tree", path = pre .. "_meta/api/tree.lua", }, + { helptag = "nvim-tree-api", section = "API", path = pre .. "api.lua", }, + + { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", }, + { helptag = "nvim-tree-api-events", section = "API: events", path = pre .. "_meta/api/events.lua", }, + { helptag = "nvim-tree-api-filter", section = "API: filter", path = pre .. "_meta/api/filter.lua", }, + { helptag = "nvim-tree-api-fs", section = "API: fs", path = pre .. "_meta/api/fs.lua", }, + { helptag = "nvim-tree-api-git", section = "API: git", path = pre .. "_meta/api/git.lua", }, + { helptag = "nvim-tree-api-health", section = "API: health", path = pre .. "_meta/api/health.lua", }, + { helptag = "nvim-tree-api-map", section = "API: map", path = pre .. "_meta/api/map.lua", }, + { helptag = "nvim-tree-api-marks", section = "API: marks", path = pre .. "_meta/api/marks.lua", }, + { helptag = "nvim-tree-api-node", section = "API: node", path = pre .. "_meta/api/node.lua", }, + { helptag = "nvim-tree-api-tree", section = "API: tree", path = pre .. "_meta/api/tree.lua", }, + + { helptag = "nvim-tree-api-decorator", section = "PLACEHOLDER", path = "runtime/lua/placeholder.lua", }, +} + +---@type Src[] +local srcs_class = { { helptag = "nvim-tree-api-decorator", section = "API: Decorator", path = pre .. "_meta/api/decorator.lua", }, { helptag = "nvim-tree-api-class", section = "API: Class", path = pre .. "classic.lua", }, } @@ -100,6 +100,11 @@ local function src_by_name(name, srcs) error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs))) end +-- generator doesn't strip _meta +local function normalise_module(fun) + fun.module = fun.module and fun.module:gsub("._meta", "", 1) or nil +end + ---HACK ---Problem: --- Generator generates fields for a class' methods. @@ -129,42 +134,39 @@ return { section_fmt = function(name) return src_by_name(name, srcs_api).section end, helptag_fmt = function(name) return src_by_name(name, srcs_api).helptag end, + -- strip module from the name fn_xform = function(fun) - -- generator doesn't strip _meta; this propagates to fn_helptag_fmt - fun.module = fun.module:gsub("._meta", "", 1) - fun.module = module_overrides[fun.module] or fun.module - - if not fun.class then - -- functions require the module to be stripped from the name, classes do not - local name, replaced = fun.name:gsub("^" .. fun.module .. "%.", "", 1) - if (replaced ~= 1) then - error(string.format("\n\nfn_xform: fun.name='%s' does not start with _meta stripped \nfun=%s", - fun.name, vim.inspect(fun))) - end - fun.name = name - elseif fun.class and fun.classvar and fun.name then - -- note the module for use by method fields - modules_by_method[fun.classvar .. ":" .. fun.name] = fun.module - end + normalise_module(fun) + fun.name = fun.name:gsub("^" .. fun.module .. "%.", "", 1) end, + }, + -- Classes + { + filename = "nvim-tree-lua.txt", + section_order = section_order(srcs_class), + files = files(srcs_class), + section_fmt = function(name) return src_by_name(name, srcs_class).section end, + helptag_fmt = function(name) return src_by_name(name, srcs_class).helptag end, + + fn_xform = function(fun) + -- strip module from name and record the module for the method + normalise_module(fun) - -- fn_helptag_fmt_common modified: + -- strip the class file from the module + fun.module = fun.module:gsub("%.[^%.]*$", "", 1) + + -- strip module from name and record the module for the method + modules_by_method[fun.classvar .. ":" .. fun.name] = fun.module + print(vim.inspect(modules_by_method)) + end, + + -- fn_helptag_fmt_common derived -- module prepended to classes -- module is fetched from modules_by_method when fun.module unavailable fn_helptag_fmt = function(fun) local fn_sfx = fun.table and "" or "()" - if fun.classvar then - local module = fun.module or modules_by_method[fun.classvar .. ":" .. fun.name] - if not module then - error(string.format("\n\nfn_helptag_fmt: no module:\nfun=%s\nmodules_by_method=%s", - vim.inspect(fun), vim.inspect(modules_by_method))) - end - return string.format("%s.%s:%s%s", module, fun.classvar, fun.name, fn_sfx) - end - if fun.module then - return string.format("%s.%s%s", fun.module, fun.name, fn_sfx) - end - return fun.name .. fn_sfx + local module = fun.module or modules_by_method[fun.classvar .. ":" .. fun.name] + return string.format("%s.%s:%s%s", module, fun.classvar, fun.name, fn_sfx) end, - } + }, } From c0e3964c8a137c8fecc32aa4412aca013ca20740 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 2 Feb 2026 16:13:19 +1100 Subject: [PATCH 8/9] docs(#3241): fix potential bug in builder: passing a nil node to a user decorator --- lua/nvim-tree/renderer/builder.lua | 47 ++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/lua/nvim-tree/renderer/builder.lua b/lua/nvim-tree/renderer/builder.lua index d38d64c2873..0c76ab515f5 100644 --- a/lua/nvim-tree/renderer/builder.lua +++ b/lua/nvim-tree/renderer/builder.lua @@ -155,23 +155,39 @@ function Builder:format_line(indent_markers, arrows, icon, name, node) -- use the api node for user decorators local api_node = self.api_nodes and self.api_nodes[node.uid_node] --[[@as Node]] + local u local line = { indent_markers, arrows } add_to_end(line, { icon }) for _, d in ipairs(self.decorators) do - add_to_end(line, d:icons_before(not d:is(UserDecorator) and node or api_node)) + u = d:as(UserDecorator) + if not u then + add_to_end(line, d:icons_before(node)) + elseif api_node then + add_to_end(line, u:icons_before(api_node)) + end end add_to_end(line, { name }) for _, d in ipairs(self.decorators) do - add_to_end(line, d:icons_after(not d:is(UserDecorator) and node or api_node)) + u = d:as(UserDecorator) + if not u then + add_to_end(line, d:icons_after(node)) + elseif api_node then + add_to_end(line, u:icons_after(api_node)) + end end local rights = {} for _, d in ipairs(self.decorators) do - add_to_end(rights, d:icons_right_align(not d:is(UserDecorator) and node or api_node)) + u = d:as(UserDecorator) + if not u then + add_to_end(line, d:icons_right_align(node)) + elseif api_node then + add_to_end(line, u:icons_right_align(api_node)) + end end if #rights > 0 then self.extmarks[self.index] = rights @@ -187,10 +203,17 @@ function Builder:build_signs(node) local api_node = self.api_nodes and self.api_nodes[node.uid_node] --[[@as Node]] -- first in priority order - local d, sign_name + local d, u, sign_name for i = #self.decorators, 1, -1 do d = self.decorators[i] - sign_name = d:sign_name(not d:is(UserDecorator) and node or api_node) + + u = d:as(UserDecorator) + if not u then + sign_name = d:sign_name(node) + elseif api_node then + sign_name = u:sign_name(api_node) + end + if sign_name then self.signs[self.index] = sign_name break @@ -245,11 +268,17 @@ function Builder:icon_name_decorated(node) local icon_groups = {} local name_groups = {} local hl_icon, hl_name + local u for _, d in ipairs(self.decorators) do - -- maybe overridde icon - icon = d:icon_node((not d:is(UserDecorator) and node or api_node)) or icon - - hl_icon, hl_name = d:highlight_group_icon_name((not d:is(UserDecorator) and node or api_node)) + -- maybe override icon + u = d:as(UserDecorator) + if not u then + icon = d:icon_node(node) or icon + hl_icon, hl_name = d:highlight_group_icon_name(node) + elseif api_node then + icon = u:icon_node(api_node) or icon + hl_icon, hl_name = u:highlight_group_icon_name(api_node) + end table.insert(icon_groups, hl_icon) table.insert(name_groups, hl_name) From 212bf52bfb146116a8f72e16bbc551e3b8dc52ec Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 2 Feb 2026 16:43:51 +1100 Subject: [PATCH 9/9] docs(#3241): nvim-tree-api-decorator brief --- doc/nvim-tree-lua.txt | 46 ++++++++++++++++++++++--- lua/nvim-tree/_meta/api/decorator.lua | 29 ++++++++++++++++ lua/nvim-tree/_meta/config/renderer.lua | 1 + lua/nvim-tree/classic.lua | 1 - scripts/gen_vimdoc_config.lua | 1 - 5 files changed, 72 insertions(+), 6 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index a5ebc95061a..5e327ae72cf 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -487,7 +487,7 @@ for files and and directories. Highlighting is additive, with higher precedence overriding lower. |nvim_tree.config.renderer| {decorators} controls which highlighting is -applied and its precedence. See |nvim-tree-decorators| for information on +applied and its precedence. See |nvim-tree-api-decorator| for information on creating custom decorators. < `ICON` @@ -1366,9 +1366,10 @@ Config: renderer *nvim-tree-config-renderer* • {symlink_destination}? (`boolean`, default: `true`) Appends an arrow followed by the target of the symlink. - • {decorators}? (`(string|nvim_tree.api.Decorator)[]`) - (default: - `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + • {decorators}? (`(string|nvim_tree.api.Decorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + Ordered list of builtin and user decorators + to enable, see |nvim-tree-api-decorator| + and |nvim-tree-icons-highlighting| • {highlight_git}? (`nvim_tree.config.renderer.highlight`) (default: `"none"`) • {highlight_opened_files}? (`nvim_tree.config.renderer.highlight`) @@ -3203,6 +3204,38 @@ winid({opts}) *nvim_tree.api.tree.winid()* ============================================================================== API: Decorator *nvim-tree-api-decorator* +Highlighting and icons for nodes are provided by Decorators, see +|nvim-tree-icons-highlighting|. You may provide your own in addition to the +builtin decorators. + +Decorators may: +• Add icons +• Set highlight group for the name or icons +• Override node icon + +To register your decorator: +• Create a class that extends |nvim_tree.api.Decorator| +• Register it by adding the class to |nvim_tree.config.renderer| {decorators} + +Your class must: +• |nvim_tree.Class:extend()| the interface |nvim_tree.api.Decorator| +• Provide a no-arguments constructor |nvim_tree.Class:new()| that sets the + mandatory fields: + • {enabled} + • {highlight_range} + • {icon_placement} + +Your class may: +• Implement methods to provide decorations: + • |nvim_tree.api.Decorator:highlight_group()| + • |nvim_tree.api.Decorator:icon_node()| + • |nvim_tree.api.Decorator:icons()| + +Your class must: +• Call |nvim_tree.api.Decorator:define_sign()| in your constructor if using + `"signcolumn"` {icon_placement} + + *nvim_tree.api.Decorator* Extends: |nvim_tree.Class| @@ -3266,6 +3299,8 @@ API: Class *nvim-tree-api-class* Fields: ~ • {super} (`Class`) + • {new} (`fun(self: nvim_tree.Class)`) See + |nvim_tree.Class:new()|. • {extend} (`fun(self: nvim_tree.Class)`) See |nvim_tree.Class:extend()|. • {implement} (`fun(self: nvim_tree.Class, mixin: Class)`) See @@ -3305,6 +3340,9 @@ Class:is({class}) *nvim_tree.Class:is()* Return: ~ (`boolean`) +Class:new() *nvim_tree.Class:new()* + Default constructor + Class:nop({...}) *nvim_tree.Class:nop()* Parameters: ~ diff --git a/lua/nvim-tree/_meta/api/decorator.lua b/lua/nvim-tree/_meta/api/decorator.lua index 9ebb9954ab2..c4643325572 100644 --- a/lua/nvim-tree/_meta/api/decorator.lua +++ b/lua/nvim-tree/_meta/api/decorator.lua @@ -1,4 +1,33 @@ ---@meta + +---@brief +---Highlighting and icons for nodes are provided by Decorators, see [nvim-tree-icons-highlighting]. You may provide your own in addition to the builtin decorators. +--- +---Decorators may: +---- Add icons +---- Set highlight group for the name or icons +---- Override node icon +--- +---To register your decorator: +---- Create a class that extends [nvim_tree.api.Decorator] +---- Register it by adding the class to [nvim_tree.config.renderer] {decorators} +--- +---Your class must: +---- [nvim_tree.Class:extend()] the interface [nvim_tree.api.Decorator] +---- Provide a no-arguments constructor [nvim_tree.Class:new()] that sets the mandatory fields: +--- - {enabled} +--- - {highlight_range} +--- - {icon_placement} +--- +---Your class may: +---- Implement methods to provide decorations: +--- - [nvim_tree.api.Decorator:highlight_group()] +--- - [nvim_tree.api.Decorator:icon_node()] +--- - [nvim_tree.api.Decorator:icons()] +--- +---Your class must: +---- Call [nvim_tree.api.Decorator:define_sign()] in your constructor if using `"signcolumn"` {icon_placement} + local nvim_tree = { api = {} } local Class = require("nvim-tree.classic") diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 8979eb8614e..b18c0b0d319 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -61,6 +61,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- +---Ordered list of builtin and user decorators to enable, see [nvim-tree-api-decorator] and [nvim-tree-icons-highlighting] ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.Decorator)[] --- diff --git a/lua/nvim-tree/classic.lua b/lua/nvim-tree/classic.lua index 1431e5bb38c..d7a072c10da 100644 --- a/lua/nvim-tree/classic.lua +++ b/lua/nvim-tree/classic.lua @@ -20,7 +20,6 @@ local Class = {} Class.__index = Class ---@diagnostic disable-line: inject-field ---Default constructor ----@protected function Class:new(...) --luacheck: ignore 212 end diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 73ac9d19c60..674b1609aa4 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -157,7 +157,6 @@ return { -- strip module from name and record the module for the method modules_by_method[fun.classvar .. ":" .. fun.name] = fun.module - print(vim.inspect(modules_by_method)) end, -- fn_helptag_fmt_common derived