feat(#2225): add renderer.hidden_display to show a summary of hidden files below the tree (#2856)

* feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

* feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

* feat(icon_placement): consolidate doc

* fix: extra namespace added to avoid colision between right_align and full_name features

* feat(hidden_display): Allow fine grained rendering of hidden files in
a folder

* feat(hidden_display): update defaults in Builder to allow rendering

* feat(hidden_display): Rename opts function name for the feature

* feat(#2349): add "right_align" option for renderer.icons.*_placement (#2846)

* feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

* feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

feat(icon_placement): Allow right_align icon_placemente for decorator using ext_marks nvim api

* feat(icon_placement): consolidate doc

* fix: extra namespace added to avoid colision between right_align and full_name features

* style: rename namespace_id

---------

Co-authored-by: Alexander Courtis <alex@courtis.org>

* docs: update docs

* feat(hidden_display): Simplification and better performance by not sorting and grouping virtual lines

* Update doc/nvim-tree-lua.txt

Co-authored-by: Alexander Courtis <alex@courtis.org>

* style: hidden_stats is better

* docs: change to hidden_stats

* add separate namespace for virtual lines

* help: add highlight group

---------

Co-authored-by: Alexander Courtis <alex@courtis.org>

doc/nvim-tree-lua.txt

@@ -423,6 +423,7 @@ Following is the default configuration. See |nvim-tree-opts| for details.
         root_folder_label = ":~:s?$?/..?",
         indent_width = 2,
         special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
+        hidden_display = "none",
         symlink_destination = true,
         highlight_git = "none",
         highlight_diagnostics = "none",
@@ -878,6 +879,49 @@ Number of spaces for an each tree nesting level. Minimum 1.
 A list of filenames that gets highlighted with `NvimTreeSpecialFile`.
   Type: `table`, Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`
 
+*nvim-tree.renderer.hidden_display*
+Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay
+  Type: `function | string`, Default: `"none"`
+
+  Possible string values are:
+    - `"none"`:   Doesn't inform anything about hidden files.
+    - `"simple"`: Shows how many hidden files are in a folder.
+    - `"all"`:    Shows how many files are hidden and the number of hidden
+                files per reason why they're hidden.
+
+  Example `"all"`:
+    If a folder has 14 hidden items for various reasons, the display might
+    show: >
+    (14 total git: 5, dotfile: 9)
+<
+  If a function is provided, it receives a table `hidden_stats` where keys are
+  reasons and values are the count of hidden files for that reason.
+
+  The `hidden_stats` argument is structured as follows, where <num> is the
+  number of hidden files related to the field: >
+    hidden_stats = {
+      bookmark = <num>,
+      buf = <num>,
+      custom = <num>,
+      dotfile = <num>,
+      git = <num>,
+      live_filter = <num>,
+    }
+<
+  Example of function that can be passed: >
+    function(hidden_stats)
+      local total_count = 0
+      for reason, count in pairs(hidden_stats) do
+        total_count = total_count + count
+      end
+
+      if total_count > 0 then
+        return "(" .. tostring(total_count) .. " hidden)"
+      end
+      return nil
+    end
+<
+
 *nvim-tree.renderer.symlink_destination*
 Whether to show the destination of the symlink.
   Type: `boolean`, Default: `true`
@@ -2461,6 +2505,9 @@ Hidden: >
     NvimTreeModifiedFileHL      NvimTreeHiddenIcon
     NvimTreeModifiedFolderHL    NvimTreeHiddenFileHL
 <
+Hidden Display: >
+    NvimTreeHiddenDisplay       Conceal
+<
 Opened: >
     NvimTreeOpenedHL            Special
 <
@@ -2872,6 +2919,7 @@ highlight group is not, hard linking as follows: >
 |nvim-tree.renderer.add_trailing|
 |nvim-tree.renderer.full_name|
 |nvim-tree.renderer.group_empty|
+|nvim-tree.renderer.hidden_display|
 |nvim-tree.renderer.highlight_bookmarks|
 |nvim-tree.renderer.highlight_clipboard|
 |nvim-tree.renderer.highlight_diagnostics|