feat: mapping and options to sort entries in help window (#2482)

* feat: add option to sort entries in help window

* stylua

* Add keymap to toggle sorting methods

* Bug fix

---------

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

Author: Akmadan23

doc/nvim-tree-lua.txt

@@ -29,9 +29,10 @@ CONTENTS                                                           *nvim-tree*
   5.14 Opts: Trash                              |nvim-tree-opts-trash|
   5.15 Opts: Tab                                |nvim-tree-opts-tab|
   5.16 Opts: Notify                             |nvim-tree-opts-notify|
-  5.17 Opts: UI                                 |nvim-tree-opts-ui|
-  5.18 Opts: Experimental                       |nvim-tree-opts-experimental|
-  5.19 Opts: Log                                |nvim-tree-opts-log|
+  5.17 Opts: Help                               |nvim-tree-opts-help|
+  5.18 Opts: UI                                 |nvim-tree-opts-ui|
+  5.19 Opts: Experimental                       |nvim-tree-opts-experimental|
+  5.20 Opts: Log                                |nvim-tree-opts-log|
   6. API                                      |nvim-tree-api|
   6.1  API Tree                                 |nvim-tree-api.tree|
   6.2  API File System                          |nvim-tree-api.fs|
@@ -565,6 +566,9 @@ Following is the default configuration. See |nvim-tree-opts| for details.
         threshold = vim.log.levels.INFO,
         absolute_path = true,
       },
+      help = {
+        sort_by = "key",
+      },
       ui = {
         confirm = {
           remove = true,
@@ -1433,7 +1437,16 @@ Whether to use absolute paths or item names in fs action notifications.
   Type: `boolean`, Default: `true`
 
 ==============================================================================
- 5.17 OPTS: UI                                             *nvim-tree-opts-ui*
+ 5.17 OPTS: HELP                                        *nvim-tree-opts-help*
+
+*nvim-tree.help.sort_by*
+Defines how mappings are sorted in the help window.
+Can be `"key"` (sort alphabetically by keymap)
+or `"desc"` (sort alphabetically by description).
+  Type: `string`, Default: `"key"`
+
+==============================================================================
+ 5.18 OPTS: UI                                             *nvim-tree-opts-ui*
 
 *nvim-tree.ui.confirm*
 Confirmation prompts.
@@ -1447,14 +1460,14 @@ Confirmation prompts.
       Type: `boolean`, Default: `true`
 
 ==============================================================================
- 5.18 OPTS: EXPERIMENTAL                         *nvim-tree-opts-experimental*
+ 5.19 OPTS: EXPERIMENTAL                         *nvim-tree-opts-experimental*
 
 *nvim-tree.experimental*
 Experimental features that may become default or optional functionality.
 In the event of a problem please disable the experiment and raise an issue.
 
 ==============================================================================
- 5.19 OPTS: LOG                                           *nvim-tree-opts-log*
+ 5.20 OPTS: LOG                                           *nvim-tree-opts-log*
 
 Configuration for diagnostic logging.
 

lua/nvim-tree.lua

@@ -588,6 +588,9 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
     threshold = vim.log.levels.INFO,
     absolute_path = true,
   },
+  help = {
+    sort_by = "key",
+  },
   ui = {
     confirm = {
       remove = true,
@@ -667,6 +670,9 @@ local ACCEPTED_STRINGS = {
       bookmarks_placement = { "before", "after", "signcolumn" },
     },
   },
+  help = {
+    sort_by = { "key", "desc" },
+  },
 }
 
 local function validate_options(conf)

lua/nvim-tree/help.lua

@@ -84,17 +84,29 @@ end
 --- @return number maximum length of text
 local function compute()
   local head_lhs = "nvim-tree mappings"
-  local head_rhs = "exit: q"
+  local head_rhs1 = "exit: q"
+  local head_rhs2 = string.format("sort by %s: s", M.config.sort_by == "key" and "description" or "keymap")
 
   -- formatted lhs and desc from active keymap
   local mappings = vim.tbl_map(function(map)
     return { lhs = tidy_lhs(map.lhs), desc = tidy_desc(map.desc) }
   end, keymap.get_keymap())
 
-  -- sort roughly by lhs
-  table.sort(mappings, function(a, b)
-    return sort_lhs(a.lhs, b.lhs)
-  end)
+  -- sorter function for mappings
+  local sort_fn
+
+  if M.config.sort_by == "desc" then
+    sort_fn = function(a, b)
+      return a.desc:lower() < b.desc:lower()
+    end
+  else
+    -- by default sort roughly by lhs
+    sort_fn = function(a, b)
+      return sort_lhs(a.lhs, b.lhs)
+    end
+  end
+
+  table.sort(mappings, sort_fn)
 
   -- longest lhs and description
   local max_lhs = 0
@@ -105,11 +117,14 @@ local function compute()
   end
 
   -- increase desc if lines are shorter than the header
-  max_desc = math.max(max_desc, #head_lhs + #head_rhs - max_lhs)
+  max_desc = math.max(max_desc, #head_lhs + #head_rhs1 - max_lhs)
 
   -- header, not padded
   local hl = { { "NvimTreeRootFolder", 0, 0, #head_lhs } }
-  local lines = { ("%s%s%s"):format(head_lhs, string.rep(" ", max_desc + max_lhs - #head_lhs - #head_rhs + 2), head_rhs) }
+  local lines = {
+    head_lhs .. string.rep(" ", max_desc + max_lhs - #head_lhs - #head_rhs1 + 2) .. head_rhs1,
+    string.rep(" ", max_desc + max_lhs - #head_rhs2 + 2) .. head_rhs2,
+  }
   local width = #lines[1]
 
   -- mappings, left padded 1
@@ -121,7 +136,7 @@ local function compute()
     width = math.max(#line, width)
 
     -- highlight lhs
-    table.insert(hl, { "NvimTreeFolderName", i, 1, #l.lhs + 1 })
+    table.insert(hl, { "NvimTreeFolderName", i + 1, 1, #l.lhs + 1 })
   end
 
   return lines, hl, width
@@ -175,14 +190,25 @@ local function open()
   vim.wo[M.winnr].winhl = WIN_HL
   vim.wo[M.winnr].cursorline = M.config.cursorline
 
-  -- quit binding
-  vim.keymap.set("n", "q", close, {
-    desc = "nvim-tree: exit help",
-    buffer = M.bufnr,
-    noremap = true,
-    silent = true,
-    nowait = true,
-  })
+  local function toggle_sort()
+    M.config.sort_by = (M.config.sort_by == "desc") and "key" or "desc"
+    open()
+  end
+
+  local keymaps = {
+    q = { fn = close, desc = "nvim-tree: exit help" },
+    s = { fn = toggle_sort, desc = "nvim-tree: toggle sorting method" },
+  }
+
+  for k, v in pairs(keymaps) do
+    vim.keymap.set("n", k, v.fn, {
+      desc = v.desc,
+      buffer = M.bufnr,
+      noremap = true,
+      silent = true,
+      nowait = true,
+    })
+  end
 
   -- close window and delete buffer on leave
   vim.api.nvim_create_autocmd({ "BufLeave", "WinLeave" }, {
@@ -202,6 +228,7 @@ end
 
 function M.setup(opts)
   M.config.cursorline = opts.view.cursorline
+  M.config.sort_by = opts.help.sort_by
 end
 
 return M