feat(files): add content.highlight to customize entry highlighting

Resolve #1790

Author: echasnovski

CHANGELOG.md

@@ -105,6 +105,10 @@ There are following change types:
 
 - Ensure preview window is never hidden, even if cursor is on the line for a not (yet) existing file system entry. This reduces flickering of preview window when creating new files in Insert mode.
 
+### Expand
+
+- Add `config.content.highlight` to customize how file system entry is highlighted. Defaults to a new `default_highlight()`.
+
 ## mini.hues
 
 ### Evolve

doc/mini-files.txt

@@ -567,9 +567,11 @@ Defaults ~
     content = {
       -- Predicate for which file system entries to show
       filter = nil,
-      -- What prefix to show to the left of file system entry
+      -- Highlight group to use for a file system entry
+      highlight = nil,
+      -- Prefix text and highlight to show to the left of file system entry
       prefix = nil,
-      -- In which order to show file system entries
+      -- Order in which to show file system entries
       sort = nil,
     },
 
@@ -625,6 +627,10 @@ A file system entry data is a table with the following fields:
   - <name> `(string)` - basename of an entry (including extension).
   - <path> `(string)` - full path of an entry.
 
+`content.highlight` describes how file system entry name should be highlighted.
+Takes file system entry data as input and returns a highlight group name.
+Uses |MiniFiles.default_highlight()| by default.
+
 `content.prefix` describes what text (prefix) to show to the left of file
 system entry name (if any) and how to highlight it. It also takes file
 system entry data as input and returns tuple of text and highlight group
@@ -968,5 +974,21 @@ Parameters ~
 Return ~
 `(table)` Sorted array of file system entries.
 
+------------------------------------------------------------------------------
+                                                 *MiniFiles.default_highlight()*
+                   `MiniFiles.default_highlight`({fs_entry})
+Default file system entry highlight
+
+Returns `'MiniFilesDirectory'` for directory and `'MiniFilesFile'` otherwise.
+
+Parameters ~
+{fs_entry} `(table)` Table with the following fields:
+  - <fs_type> `(string)` - one of "file" or "directory".
+  - <name> `(string)` - basename of an entry (including extension).
+  - <path> `(string)` - full path of an entry.
+
+Return ~
+`(string)` Highlight group name.
+
 
  vim:tw=78:ts=8:noet:ft=help:norl:

lua/mini/files.lua

@@ -591,6 +591,10 @@ end
 --- A file system entry data is a table with the following fields:
 --- __minifiles_fs_entry_data_fields
 ---
+--- `content.highlight` describes how file system entry name should be highlighted.
+--- Takes file system entry data as input and returns a highlight group name.
+--- Uses |MiniFiles.default_highlight()| by default.
+---
 --- `content.prefix` describes what text (prefix) to show to the left of file
 --- system entry name (if any) and how to highlight it. It also takes file
 --- system entry data as input and returns tuple of text and highlight group
@@ -661,9 +665,11 @@ MiniFiles.config = {
   content = {
     -- Predicate for which file system entries to show
     filter = nil,
-    -- What prefix to show to the left of file system entry
+    -- Highlight group to use for a file system entry
+    highlight = nil,
+    -- Prefix text and highlight to show to the left of file system entry
     prefix = nil,
-    -- In which order to show file system entries
+    -- Order in which to show file system entries
     sort = nil,
   },
 
@@ -1223,6 +1229,18 @@ MiniFiles.default_sort = function(fs_entries)
   return vim.tbl_map(function(x) return { name = x.name, fs_type = x.fs_type, path = x.path } end, res)
 end
 
+--- Default file system entry highlight
+---
+--- Returns `'MiniFilesDirectory'` for directory and `'MiniFilesFile'` otherwise.
+---
+---@param fs_entry table Table with the following fields:
+--- __minifiles_fs_entry_data_fields
+---
+---@return string Highlight group name.
+MiniFiles.default_highlight = function(fs_entry)
+  return fs_entry.fs_type == 'directory' and 'MiniFilesDirectory' or 'MiniFilesFile'
+end
+
 -- Helper data ================================================================
 -- Module default config
 H.default_config = vim.deepcopy(MiniFiles.config)
@@ -1270,6 +1288,7 @@ H.setup_config = function(config)
 
   H.check_type('content', config.content, 'table')
   H.check_type('content.filter', config.content.filter, 'function', true)
+  H.check_type('content.highlight', config.content.highlight, 'function', true)
   H.check_type('content.prefix', config.content.prefix, 'function', true)
   H.check_type('content.sort', config.content.sort, 'function', true)
 
@@ -1348,6 +1367,7 @@ end
 H.normalize_opts = function(explorer_opts, opts)
   opts = vim.tbl_deep_extend('force', H.get_config(), explorer_opts or {}, opts or {})
   opts.content.filter = opts.content.filter or MiniFiles.default_filter
+  opts.content.highlight = opts.content.highlight or MiniFiles.default_highlight
   opts.content.prefix = opts.content.prefix or MiniFiles.default_prefix
   opts.content.sort = opts.content.sort or MiniFiles.default_sort
 
@@ -2241,7 +2261,8 @@ H.buffer_update_directory = function(buf_id, path, opts, is_preview)
 
   -- Compute lines
   local lines, icon_hl, name_hl = {}, {}, {}
-  local prefix_fun, n_computed_prefixes = opts.content.prefix, is_preview and vim.o.lines or math.huge
+  local prefix_fun, hl_fun = opts.content.prefix, opts.content.highlight
+  local n_computed_prefixes = is_preview and vim.o.lines or math.huge
   for i, entry in ipairs(fs_entries) do
     local prefix, hl, name
     -- Compute prefix only in visible preview (for performance).
@@ -2253,7 +2274,7 @@ H.buffer_update_directory = function(buf_id, path, opts, is_preview)
     prefix, hl, name = prefix or '', hl or '', H.sanitize_string(entry.name)
     table.insert(lines, string.format(line_format, H.path_index[entry.path], prefix, name))
     table.insert(icon_hl, hl)
-    table.insert(name_hl, entry.fs_type == 'directory' and 'MiniFilesDirectory' or 'MiniFilesFile')
+    table.insert(name_hl, hl_fun(entry) or 'MiniFilesNormal')
   end
 
   -- Set lines

readmes/mini-files.md

@@ -172,9 +172,11 @@ Here are code snippets for some common installation methods (use only one):
   content = {
     -- Predicate for which file system entries to show
     filter = nil,
-    -- What prefix to show to the left of file system entry
+    -- Highlight group to use for a file system entry
+    highlight = nil,
+    -- Prefix text and highlight to show to the left of file system entry
     prefix = nil,
-    -- In which order to show file system entries
+    -- Order in which to show file system entries
     sort = nil,
   },
 

tests/screenshots/tests-test_files.lua---open()---respects-`content.highlight`

@@ -0,0 +1,33 @@
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|┌MOCK_ROOT/tests/dir-files/common ─────────────────┐                            
+02|│ .a-dir                                          │                            
+03|│ a-dir                                           │                            
+04|│ b-dir                                           │                            
+05|│ .a-file                                         │                            
+06|│ a-file                                          │                            
+07|│ A-file-2                                        │                            
+08|│ b-file                                          │                            
+09|└──────────────────────────────────────────────────┘                            
+10|~                                                                               
+11|~                                                                               
+12|~                                                                               
+13|~                                                                               
+14|~                                                                               
+15|                                                              1,9-7         All 
+
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|01111111111111111111111111111111110000000000000000002222222222222222222222222222
+02|03344444455555555555555555555555555555555555555555506666666666666666666666666666
+03|07744444444444444444444444444444444444444444444444406666666666666666666666666666
+04|07744444444444444444444444444444444444444444444444406666666666666666666666666666
+05|04444444444444444444444444444444444444444444444444406666666666666666666666666666
+06|04444444444444444444444444444444444444444444444444406666666666666666666666666666
+07|04444444444444444444444444444444444444444444444444406666666666666666666666666666
+08|04444444444444444444444444444444444444444444444444406666666666666666666666666666
+09|00000000000000000000000000000000000000000000000000006666666666666666666666666666
+10|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+11|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+12|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+13|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+14|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+15|22222222222222222222222222222222222222222222222222222222222222222222222222222222

tests/screenshots/tests-test_files.lua---open()---respects-`content.highlight`-002

@@ -0,0 +1,33 @@
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|┌MOCK_ROOT/tests/dir-files/common ─────────────────┐                            
+02|│ .a-dir                                          │                            
+03|│ a-dir                                           │                            
+04|│ b-dir                                           │                            
+05|│ .a-file                                         │                            
+06|│ a-file                                          │                            
+07|│ A-file-2                                        │                            
+08|│ b-file                                          │                            
+09|└──────────────────────────────────────────────────┘                            
+10|~                                                                               
+11|~                                                                               
+12|~                                                                               
+13|~                                                                               
+14|~                                                                               
+15|                                                              1,9-7         All 
+
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|01111111111111111111111111111111110000000000000000002222222222222222222222222222
+02|03344444455555555555555555555555555555555555555555506666666666666666666666666666
+03|07788888999999999999999999999999999999999999999999906666666666666666666666666666
+04|077:::::999999999999999999999999999999999999999999906666666666666666666666666666
+05|099:::::::9999999999999999999999999999999999999999906666666666666666666666666666
+06|09988888899999999999999999999999999999999999999999906666666666666666666666666666
+07|099::::::::999999999999999999999999999999999999999906666666666666666666666666666
+08|099::::::99999999999999999999999999999999999999999906666666666666666666666666666
+09|00000000000000000000000000000000000000000000000000006666666666666666666666666666
+10|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+11|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+12|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+13|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+14|66666666666666666666666666666666666666666666666666666666666666666666666666666666
+15|22222222222222222222222222222222222222222222222222222222222222222222222222222222

tests/test_files.lua

@@ -238,6 +238,7 @@ T['setup()']['creates `config` field'] = function()
   local expect_config = function(field, value) eq(child.lua_get('MiniFiles.config.' .. field), value) end
 
   expect_config('content.filter', vim.NIL)
+  expect_config('content.highlight', vim.NIL)
   expect_config('content.prefix', vim.NIL)
   expect_config('content.sort', vim.NIL)
 
@@ -279,6 +280,7 @@ T['setup()']['validates `config` argument'] = function()
   expect_config_error('a', 'config', 'table')
   expect_config_error({ content = 'a' }, 'content', 'table')
   expect_config_error({ content = { filter = 1 } }, 'content.filter', 'function')
+  expect_config_error({ content = { highlight = 1 } }, 'content.highlight', 'function')
   expect_config_error({ content = { prefix = 1 } }, 'content.prefix', 'function')
   expect_config_error({ content = { sort = 1 } }, 'content.sort', 'function')
 
@@ -646,6 +648,33 @@ T['open()']['respects `content.filter`'] = function()
   child.expect_screenshot()
 end
 
+T['open()']['respects `content.highlight`'] = function()
+  child.lua([[
+    _G.highlight_arg = {}
+    MiniFiles.config.content.highlight = function(fs_entry)
+      _G.highlight_arg = fs_entry
+      -- Should use 'MiniFilesNormal' as a fallback
+      return nil
+    end
+  ]])
+
+  open(test_dir_path)
+  child.expect_screenshot()
+  validate_fs_entry(child.lua_get('_G.highlight_arg'))
+
+  -- Local value from argument should take precedence
+  child.lua([[_G.highlight_starts_from_a = function(fs_entry)
+    return vim.startswith(fs_entry.name, 'a') and 'String' or 'Comment'
+  end]])
+
+  local lua_cmd = string.format(
+    'MiniFiles.open(%s, false, { content = { highlight = _G.highlight_starts_from_a } })',
+    vim.inspect(test_dir_path)
+  )
+  child.lua(lua_cmd)
+  child.expect_screenshot()
+end
+
 T['open()']['respects `content.prefix`'] = function()
   child.set_size(15, 60)