feat(#2544): add api.tree.winid (#2545)

* feat(#2544): add API for querying win ID, api.tree.winid()

* Document winid() opts

Co-authored-by: Alexander Courtis <[email protected]>

* Fix winid() docs

Co-authored-by: Alexander Courtis <[email protected]>

* Handle case where tabpage = 0

---------

Co-authored-by: Alexander Courtis <[email protected]>

Author: j-hui

doc/nvim-tree-lua.txt

@@ -1698,6 +1698,18 @@ tree.is_visible({opts})                      *nvim-tree-api.tree.is_visible()*
     Return: ~
       (boolean) nvim-tree is visible
 
+tree.winid({opts})                              *nvim-tree-api.tree.winid()*
+    Retrieve the winid of the open tree.
+
+    Parameters: ~
+      • {opts} (table) optional parameters
+
+    Options: ~
+      • {tabpage}        (number|nil)  tabpage, 0 or nil for current, default nil
+
+    Return: ~
+      (number) winid or nil if tree is not visible
+
 ==============================================================================
  6.2 API FILE SYSTEM                                        *nvim-tree-api.fs*
 

lua/nvim-tree/api.lua

@@ -145,6 +145,11 @@ Api.tree.is_tree_buf = wrap(require("nvim-tree.utils").is_nvim_tree_buf)
 
 Api.tree.is_visible = wrap(require("nvim-tree.view").is_visible)
 
+---@class ApiTreeWinIdOpts
+---@field tabpage number|nil default nil
+
+Api.tree.winid = wrap(require("nvim-tree.view").winid)
+
 Api.fs.create = wrap_node_or_nil(require("nvim-tree.actions.fs.create-file").fn)
 Api.fs.remove = wrap_node(require("nvim-tree.actions.fs.remove-file").fn)
 Api.fs.trash = wrap_node(require("nvim-tree.actions.fs.trash").fn)

lua/nvim-tree/view.lua

@@ -427,6 +427,21 @@ function M.focus(winnr, open_if_closed)
   vim.api.nvim_set_current_win(wnr)
 end
 
+--- Retrieve the winid of the open tree.
+--- @param opts ApiTreeWinIdOpts|nil
+--- @return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
+function M.winid(opts)
+  local tabpage = opts and opts.tabpage
+  if tabpage == 0 then
+    tabpage = vim.api.nvim_get_current_tabpage()
+  end
+  if M.is_visible { tabpage = tabpage } then
+    return M.get_winnr(tabpage)
+  else
+    return nil
+  end
+end
+
 --- Restores the state of a NvimTree window if it was initialized before.
 function M.restore_tab_state()
   local tabpage = vim.api.nvim_get_current_tabpage()