docs(#3241): api exposes nvim_tree.api.decorator.Decorator interface, UserDecorator deprecated

Author: alex-courtis

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`)

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

lua/nvim-tree/_meta/api_decorator.lua

@@ -1,59 +1,57 @@
 ---@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
 
 ---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.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

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

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

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

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

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

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")