[mini.clue] [Archived] Display bookmarks and g mappings from mini.files

[abeldekat]

mini_files_in_mini_clue.mp4

Recently, people asked if bookmarks and g mappings from MiniFiles could be shown in MiniClue.

The challenges:

1. MiniFiles must explicitly opt-in to MiniClue. MiniFiles works per tabpage.
2. Both MiniFiles and MiniClue add a buffer-local mapping for '
3. The g clues do include the ones from MiniFiles, but also from many others...

Solution:

1. Opt-in, and keep track of open explorers per tabpage. Manipulate the global MiniClue config accordingly
2. If explorer is active, add a global mapping, using ' for MiniFiles
3. Apply a hack, overriding vim.api.nvim_get_keys if needed...) v2: Remove the global g mappings that are not needed in MiniFiles, restore when the explorer closes v3: Instead of removing, change the description of global 'g' mappings when inside explorer

Note: For v4, the solution is different. See this comment.

v4, override two MiniClue triggers when inside explorer

---@diagnostic disable: undefined-global, inject-field
-- This 'extra' enables showing bookmarks and 'g' mappings from MiniFiles with MiniClue
-- See https://github.com/nvim-mini/mini.nvim/discussions/2519
-- Prerequisites: MiniFiles and MiniClue active. MiniFiles uses default mark_goto mapping
--
-- The descriptions of *global* 'g' mappings change temporarily when the explorer is open and
-- user presses 'g'. This workaround is needed because MiniClue always includes all mappings
--
-- Example usage:
--[[
   require('mini.files').setup()
  -- .. add bookmarks and 'g' mappings, see `:h MiniFiles-examples`
  require('mini.clue').setup()
  -- .. setup other plugins that have global 'g' mappings
  require('<this_file>').setup()
--]]

-- The description of a global 'g' mapping in open explorer, for better 'clues' readability
local g_dummy_description = '***'
-- Flag indicating that the descriptions of the global 'g' mappings have been modified
local g_mappings_are_modified = false
-- Cache. List with the dictionaries of the original global 'g' mappings
local g_originals = {}
-- Cache. List with the dictionaries of the global 'g' mappings with modified descriptions
local g_modified = {}
-- Cache. Deepcopy of global MiniClue config
local miniclue_config_deepcopy

-- Copied from MiniFiles in order to write a local "mark_goto"
local notify = function(msg, level_name) vim.notify('(FilesClued) ' .. msg, vim.log.levels[level_name]) end
local fs_is_imaginary_path = function(path) return path:sub(-1) == '\000' end
local fs_is_present_path = function(path) return vim.loop.fs_stat(path) ~= nil and not fs_is_imaginary_path(path) end
local fs_get_type = function(path)
  if path == nil or not (not fs_is_imaginary_path(path) and fs_is_present_path(path)) then return nil end
  return vim.fn.isdirectory(path) == 1 and 'directory' or 'file'
end
-- End copied from MiniFiles

-- MiniFiles->H.buffer_make_mappings->mark_goto uses its 'H.getcharstr' to obtain the id
-- FilesClued creates a buffer mapping from each bookmark, so mark_goto has to be changed slightly
local mark_goto = function(id)
  local state = MiniFiles.get_explorer_state()
  local data = state.bookmarks[id]
  if data == nil then return notify('No bookmark with id ' .. vim.inspect(id), 'WARN') end

  local path = data.path
  if vim.is_callable(path) then path = path() end
  local is_valid_path = type(path) == 'string' and fs_get_type(vim.fn.expand(path)) == 'directory'
  if not is_valid_path then return notify('Bookmark path should be a valid path to directory', 'WARN') end

  MiniFiles.set_bookmark("'", state.branch[state.depth_focus], { desc = 'Before latest jump' })
  MiniFiles.set_branch({ path })
end
local add_mark_mappings = function(buf_id)
  local state = MiniFiles.get_explorer_state()
  vim.iter(pairs(state.bookmarks)):each(function(id, bookmark)
    local opts = { buf = buf_id, desc = bookmark.desc }
    vim.keymap.set('n', "'" .. id, function() mark_goto(id) end, opts)
  end)
end

local override_global_g_mappings = function(g_dictionaries, is_override)
  local still_present = function(_, m) return vim.fn.maparg(m.lhs, 'n', false, false) ~= '' end
  vim.iter(ipairs(g_dictionaries)):filter(still_present):each(function(_, m) vim.fn.mapset(m) end)
  g_mappings_are_modified = is_override
end

local map_trigger = function(trigger_char, buf_id, trigger_fn)
  -- See MiniClue->H.map_trigger
  local opts = { nowait = true, buf = buf_id, desc = 'FilesClued for "' .. trigger_char .. '"' }
  vim.keymap.set('n', trigger_char, trigger_fn, opts)
end
local decorate = function(trigger_char, buf_id, cb_before, cb_after)
  local miniclue_mapping_info = vim.fn.maparg(trigger_char, 'n', false, true)
  -- Early return when mapping is not buffer local
  if miniclue_mapping_info.buffer ~= 1 then return end

  local trigger_fn
  trigger_fn = function()
    -- Keep a reference to the original global 'config clues'
    local clues_orig = MiniClue.config.clues
    -- During this invocation of 'trigger-char', don't show global 'config clues'
    MiniClue.config.clues = {}
    -- Perform any necessary action to enable MiniClue to show the expected clues
    cb_before()
    -- Execute the MiniClue trigger
    miniclue_mapping_info.callback()
    -- If needed, undo the actions from 'cb_before_trigger'
    if cb_after then cb_after() end
    -- Restore the global 'config clues'
    MiniClue.config.clues = clues_orig

    -- MiniClue unmaps on exec and schedules the mapping to be recreated. See MiniClue, H.state_exec
    vim.schedule(function() map_trigger(trigger_char, buf_id, trigger_fn) end)
  end
  map_trigger(trigger_char, buf_id, trigger_fn)
end

local decorate_triggers = vim.schedule_wrap(function(buf_id)
  -- Ensure that bookmarks created dynamically are also included
  local cb_before = function() add_mark_mappings(buf_id) end
  decorate("'", buf_id, cb_before)

  -- Ensure that the descriptions of MiniFiles 'g' mappings stand out when explorer is open
  cb_before = function() override_global_g_mappings(g_modified, true) end
  local cb_after = function() override_global_g_mappings(g_originals, false) end
  decorate('g', buf_id, cb_before, cb_after)
end)

local attach = function(buf_id)
  -- Triggers: Restricted to "'" and 'g'
  -- Solution from discussion: https://github.com/nvim-mini/mini.nvim/discussions/1195#discussioncomment-10542838
  local triggers_orig = MiniClue.config.triggers
  MiniClue.config.triggers = { { mode = { 'n' }, keys = "'" }, { mode = { 'n' }, keys = 'g' } }
  MiniClue.enable_buf_triggers(buf_id)
  MiniClue.config.triggers = triggers_orig

  -- Clues: Decorate triggers to manipulate the clues displayed when explorer is open
  decorate_triggers(buf_id)
end

local ensure_correct_state = function()
  -- Only when a 'g' or "'" action fails in open explorer, inconsistent state is expected:
  -- 1. global MiniClue.config.clues would remain incorrect
  -- 2. if 'g', the global 'g' mappings still have modified descriptions
  -- Solution: Always restore when explorer closes
  MiniClue.config = miniclue_config_deepcopy
  if g_mappings_are_modified then override_global_g_mappings(g_originals, false) end
end

local attach_to_already_open = function()
  local list_bufs, is_loaded = vim.api.nvim_list_bufs, vim.api.nvim_buf_is_loaded
  local is_files = function(buf_id) return vim.bo[buf_id].filetype == 'minifiles' end
  vim.iter(list_bufs()):filter(is_loaded):filter(is_files):each(function(buf_id) attach(buf_id) end)
end

local make_cache = function()
  miniclue_config_deepcopy = vim.deepcopy(MiniClue.config)
  g_originals, g_modified = {}, {}

  local g_only = function(_, info) return info.lhs:sub(1, 1) == 'g' end
  vim.iter(ipairs(vim.api.nvim_get_keymap('n'))):filter(g_only):each(function(_, mapping_info)
    table.insert(g_originals, vim.deepcopy(mapping_info))
    mapping_info.desc = g_dummy_description
    table.insert(g_modified, mapping_info)
  end)
end

local FilesClued = {}
FilesClued.setup = function()
  if MiniFiles == nil or MiniClue == nil then return end
  if MiniFiles.config.mappings.mark_goto ~= "'" then return end
  _G.FilesClued = FilesClued

  make_cache()
  attach_to_already_open()
  local augroup = vim.api.nvim_create_augroup('FilesClued', {})
  local au = function(event, pattern, callback, desc)
    vim.api.nvim_create_autocmd(event, { group = augroup, pattern = pattern, callback = callback, desc = desc })
  end
  au('User', 'MiniFilesBufferCreate', function(args) attach(args.data.buf_id) end, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerClose', function() ensure_correct_state() end, 'Ensure state')
end
return FilesClued

v3, change description of global 'g' mappings when inside explorer

---@diagnostic disable: undefined-global
-- This 'extra' makes it possible to show bookmarks and g mappings from MiniFiles in MiniClue
-- See https://github.com/nvim-mini/mini.nvim/discussions/2519
-- Prerequisites: MiniFiles and MiniClue active. MiniFiles uses default mark_goto mapping
-- The description of global 'g' mappings changes when the explorer is open,
-- because the mappings cannot be removed from the clues window in a reasonable way
-- Example usage:
--[[
   require('mini.files').setup()
  -- .. add bookmarks and 'g' mappings, see `:h MiniFiles-examples`
  require('mini.clue').setup()
  -- .. setup other plugins that have global 'g' mappings
  require('<this_file>').setup()
--]]

-- MiniClue triggers for MiniFiles
local clue_triggers = { { mode = { 'n' }, keys = "'" }, { mode = { 'n' }, keys = 'g' } }
-- The description of a global 'g' mapping when explorer, for better 'clues' readability
local g_dummy_description = '***'
-- Flag indicating that 'g' mappings have been modified
local g_has_been_modified = false
-- Cache. List with the dictionaries of the original global 'g' mappings
local g_originals = {}
-- Cache. List with the dictionaries of the modified global 'g' mappings
local g_modified = {}
-- Cache. A copy of MiniClue's global config
local miniclue_config_deepcopy = nil
-- Id of previous tabpage
local tab_prev = nil
-- Table with key: tabpage id, value: boolean(true if tab has open explorer)
local tabs = {}
-- A reference to the mark_goto function in MiniFiles. See its H.buffer_make_mappings
local mark_goto_rhs = nil

local get_config_override = function()
  if miniclue_config_deepcopy == nil then miniclue_config_deepcopy = vim.deepcopy(MiniClue.config) end
  return MiniClue.config
end

local explorer_is_open = function(tabpage)
  if tabpage == nil then tabpage = vim.api.nvim_get_current_tabpage() end
  return tabs[tabpage]
end
local explorer_set_open = function(is_open) tabs[vim.api.nvim_get_current_tabpage()] = is_open end

local mapset_global_g = function(g_dictionaries, is_modified)
  local is_present = function(_, m) return vim.fn.maparg(m.lhs, 'n', false, false) ~= '' end
  vim.iter(ipairs(g_dictionaries)):filter(is_present):each(function(_, m) vim.fn.mapset(m) end)
  g_has_been_modified = is_modified
end

local restore_globally = function()
  -- Restore the global MiniClue config
  MiniClue.config = miniclue_config_deepcopy
  -- Ensure a fresh deepcopy on next override
  miniclue_config_deepcopy = nil
  -- Remove the global 'open bookmark' mapping for MiniFiles
  vim.keymap.del('n', "'")
  -- Restore the descriptions of the global 'g' mappings
  if g_has_been_modified then mapset_global_g(g_originals, false) end
end

local bm_to_clue = function(id, b) return { mode = 'n', keys = "'" .. id, desc = b.desc } end
local override_globally = function()
  -- Never show the original config clues
  get_config_override().clues = {}
  -- Early return
  local state = MiniFiles.get_explorer_state()
  if not (state and mark_goto_rhs) then return end

  -- Change the description of global 'g' mappings
  if not g_has_been_modified then mapset_global_g(g_modified, true) end
  -- Override 'config clues' to only contain bookmarks from MiniFiles
  get_config_override().clues = vim.iter(pairs(state.bookmarks)):map(bm_to_clue):totable()
  -- Ensure global "'" mapping for MiniFiles
  vim.keymap.set('n', "'", mark_goto_rhs, { desc = 'MiniFiles open bookmark' })
end

local enable = function(buf_id)
  -- Activate MiniClue with a restricted set of triggers
  local miniclue_config = get_config_override()
  miniclue_config.triggers = clue_triggers
  MiniClue.enable_buf_triggers(buf_id)
end

local explorer_buffer_create = function(args)
  if not explorer_is_open() then return end

  enable(args.data.buf_id)
  -- NOTE: Update bookmarks. There is no MiniFilesBookmarkAdded event...
  override_globally()
end

local explorer_open = function()
  if explorer_is_open() then return end

  -- The "'" mapping must be from MiniFiles, as MiniClue is not yet enabled on explorer's buffers
  if mark_goto_rhs == nil then mark_goto_rhs = vim.fn.maparg("'", 'n', false, true).callback end
  -- Enable MiniClue in all buffers
  local state = MiniFiles.get_explorer_state()
  vim.iter(ipairs(state.windows)):each(function(_, w) enable(vim.api.nvim_win_get_buf(w.win_id)) end)
  override_globally()
  explorer_set_open(true)
end

local explorer_close = function()
  if not explorer_is_open() then return end

  restore_globally()
  explorer_set_open(false)
end

local buf_enter = function()
  if tab_prev == nil then tab_prev = vim.api.nvim_get_current_tabpage() end
  local tab_current = vim.api.nvim_get_current_tabpage()
  if tab_prev == tab_current then return end

  if explorer_is_open(tab_prev) then restore_globally() end
  if explorer_is_open(tab_current) then override_globally() end
  tab_prev = tab_current
end

local handle_already_opened_explorers = function()
  local list_bufs, is_loaded = vim.api.nvim_list_bufs, vim.api.nvim_buf_is_loaded
  local is_files = function(buf_id) return vim.bo[buf_id].filetype == 'minifiles' end
  vim.iter(list_bufs()):filter(is_loaded):filter(is_files):each(function() explorer_open() end)
end

local build_g_cache = function()
  g_originals, g_modified = {}, {}
  local g_only = function(_, info) return info.lhs:sub(1, 1) == 'g' end
  vim.iter(ipairs(vim.api.nvim_get_keymap('n'))):filter(g_only):each(function(_, mapping_info)
    table.insert(g_originals, vim.deepcopy(mapping_info))
    mapping_info.desc = g_dummy_description
    table.insert(g_modified, mapping_info)
  end)
end

local FilesClued = {}
FilesClued.setup = function()
  if MiniFiles == nil or MiniClue == nil then return end
  if MiniFiles.config.mappings.mark_goto ~= "'" then return end
  _G.FilesClued = FilesClued

  build_g_cache()
  handle_already_opened_explorers()
  local augroup = vim.api.nvim_create_augroup('FilesClued', {})
  local au = function(event, pattern, callback, desc)
    vim.api.nvim_create_autocmd(event, { group = augroup, pattern = pattern, callback = callback, desc = desc })
  end
  au('BufEnter', '*', buf_enter, 'Administer MiniClue per tabpage')
  au('User', 'MiniFilesBufferCreate', explorer_buffer_create, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerOpen', explorer_open, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerClose', explorer_close, 'Restore regular MiniClue')
end
return FilesClued

v2, without the hack

---@diagnostic disable: undefined-global
-- This 'extra' makes it possible to show bookmarks and g mappings from MiniFiles in MiniClue
-- See https://github.com/nvim-mini/mini.nvim/discussions/2519
-- Prerequisites: MiniFiles and MiniClue active. MiniFiles uses default mark_goto mapping
-- Example usage:
--[[
   require('mini.files').setup()
  -- .. add bookmarks and 'g' mappings, see `:h MiniFiles-examples`
  require('mini.clue').setup()
  -- .. setup other plugins that have 'g' mappings not needed in MiniFiles
  require('<this_file>').setup()
--]]

-- MiniClue triggers for MiniFiles: open bookmarks and g key
local mark_goto = "'"
local clue_triggers = { { mode = { 'n' }, keys = mark_goto }, { mode = { 'n' }, keys = 'g' } }
-- The 'g' clues contain global mappings not needed in MiniFiles. See MiniClue H.clues_get_all
-- stylua: ignore
local g_to_delete = {
  'ga', 'gA', 'gc', 'gcc', 'gh', 'gH', 'go', 'gO', 'gS', 'gV', 'g%', 'g=', 'g==', 'g[', 'g]'
}
-- List with the dictionaries of the deleted mappings so they can be restored
local g_to_restore = nil
-- Cache a copy of MiniClue global config
local miniclue_config_deepcopy = nil
-- Id of previous tabpage
local tab_prev = nil
-- Table with key: tabpage id, value: boolean(true if tab has active explorer)
local tabs = {}
-- A reference to the mark_goto function in MiniFiles. See its H.buffer_make_mappings
local mark_goto_rhs = nil

local get_config_override = function()
  if miniclue_config_deepcopy == nil then miniclue_config_deepcopy = vim.deepcopy(MiniClue.config) end
  return MiniClue.config
end

local explorer_is_open = function(tabpage)
  if tabpage == nil then tabpage = vim.api.nvim_get_current_tabpage() end
  return tabs[tabpage]
end
local explorer_set_open = function(is_open) tabs[vim.api.nvim_get_current_tabpage()] = is_open end

local restore_globally = function()
  -- Restore the global MiniClue config
  MiniClue.config = miniclue_config_deepcopy
  -- Ensure a fresh deepcopy on next override
  miniclue_config_deepcopy = nil
  -- Remove the global open bookmark mapping
  vim.keymap.del('n', "'")
  -- Restore global g mappings which were deleted when explorer opened
  if g_to_restore ~= nil then vim.iter(ipairs(g_to_restore)):each(function(_, m) vim.fn.mapset(m) end) end
  g_to_restore = nil
end

local delete_g_mappings = function()
  -- Bind global next to local next for performance...
  local next = next
  local to_mapping_info = function(_, lhs) return vim.fn.maparg(lhs, 'n', false, true) end
  local not_empty = function(mapping_info) return next(mapping_info) ~= nil end
  local restore = {}
  vim.iter(ipairs(g_to_delete)):map(to_mapping_info):filter(not_empty):each(function(mapping_info)
    table.insert(restore, mapping_info)
    vim.keymap.del('n', mapping_info.lhs)
  end)
  return restore
end
local bookmark_to_clue = function(id, b) return { mode = 'n', keys = mark_goto .. id, desc = b.desc } end
local override_globally = function()
  -- Never show the original config clues
  get_config_override().clues = {}
  -- Early return
  local state = MiniFiles.get_explorer_state()
  if not (state and mark_goto_rhs) then return end

  -- Override 'config clues' to only contain bookmarks from MiniFiles
  get_config_override().clues = vim.iter(pairs(state.bookmarks)):map(bookmark_to_clue):totable()
  -- Ensure global "'" mapping to local "mark_goto" handler in MiniFiles
  vim.keymap.set('n', mark_goto, mark_goto_rhs, { desc = 'MiniFiles open bookmark' })
  -- Delete global mappings that are not needed in MiniFiles
  g_to_restore = g_to_restore == nil and delete_g_mappings() or g_to_restore
end

local enable = function(buf_id)
  -- Activate MiniClue with a restricted set of triggers
  local miniclue_config = get_config_override()
  miniclue_config.triggers = clue_triggers
  MiniClue.enable_buf_triggers(buf_id)
end

local explorer_buffer_create = function(args)
  if not explorer_is_open() then return end

  enable(args.data.buf_id)
  -- NOTE: Update bookmarks. There is no MiniFilesBookmarkAdded event...
  override_globally()
end

local explorer_open = function()
  if explorer_is_open() then return end

  -- MiniClue is not yet enabled on explorer's buffers. The "'" mapping must be from MiniFiles
  if mark_goto_rhs == nil then mark_goto_rhs = vim.fn.maparg("'", 'n', false, true).callback end
  -- Enable MiniClue in all buffers
  local state = MiniFiles.get_explorer_state()
  vim.iter(ipairs(state.windows)):each(function(_, w) enable(vim.api.nvim_win_get_buf(w.win_id)) end)
  override_globally()
  explorer_set_open(true)
end

local explorer_close = function()
  if not explorer_is_open() then return end

  restore_globally()
  explorer_set_open(false)
end

local buf_enter = function()
  if tab_prev == nil then tab_prev = vim.api.nvim_get_current_tabpage() end
  local tab_current = vim.api.nvim_get_current_tabpage()
  if tab_prev == tab_current then return end

  if explorer_is_open(tab_prev) then restore_globally() end
  if explorer_is_open(tab_current) then override_globally() end
  tab_prev = tab_current
end

local FilesClued = {}
FilesClued.setup = function()
  -- Early returns
  if MiniFiles == nil or MiniClue == nil then return end
  if MiniFiles.config.mappings.mark_goto ~= mark_goto then return end
  _G.FilesClued = FilesClued

  -- Handle explorers that are already open
  local b = vim.tbl_filter(vim.api.nvim_buf_is_loaded, vim.api.nvim_list_bufs())
  b = vim.tbl_filter(function(buf_id) return vim.bo[buf_id].filetype == 'minifiles' end, b)
  vim.iter(ipairs(b)):each(function() explorer_open() end)

  -- Setup autocommands
  local augroup = vim.api.nvim_create_augroup('FilesClued', {})
  local au = function(event, pattern, callback, desc)
    vim.api.nvim_create_autocmd(event, { group = augroup, pattern = pattern, callback = callback, desc = desc })
  end
  au('BufEnter', '*', buf_enter, 'Administer MiniClue per tabpage')
  au('User', 'MiniFilesBufferCreate', explorer_buffer_create, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerOpen', explorer_open, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerClose', explorer_close, 'Restore regular MiniClue')
end
return FilesClued

Initial version

---@diagnostic disable: undefined-global
-- This 'extra' makes it possible to show bookmarks and g mappings from MiniFiles in MiniClue
-- See https://github.com/nvim-mini/mini.nvim/discussions/2519
-- Prerequisites: MiniFiles and MiniClue active. MiniFiles uses default mark_goto mapping
-- Example usage:
--[[
   require('mini.files').setup()
  -- add bookmarks and 'g' mappings, see `:h MiniFiles-examples`
  require('mini.clue').setup()
  require('<this_file>').setup()
--]]

-- MiniClue triggers for MiniFiles: open bookmarks and g key
local mark_goto = "'"
local clue_triggers = { { mode = { 'n' }, keys = mark_goto }, { mode = { 'n' }, keys = 'g' } }
-- Cache a copy of MiniClue global config
local miniclue_config_deepcopy = nil
-- Id of previous tabpage
local tab_prev = nil
-- Table with key: tabpage id, value: boolean(true if tab has active explorer)
local tabs = {}
-- A reference to the mark_goto function in MiniFiles. See its H.buffer_make_mappings
local mark_goto_rhs = nil
-- The 'g' clues contain global mappings not specific to MiniFiles. See MiniClue, its H.clues_get_all
local nvim_get_keymap = vim.api.nvim_get_keymap

local get_config_override = function()
  if miniclue_config_deepcopy == nil then miniclue_config_deepcopy = vim.deepcopy(MiniClue.config) end
  return MiniClue.config
end

local explorer_is_open = function(tabpage)
  if tabpage == nil then tabpage = vim.api.nvim_get_current_tabpage() end
  return tabs[tabpage]
end
local explorer_set_open = function(is_open) tabs[vim.api.nvim_get_current_tabpage()] = is_open end

local restore_globally = function()
  vim.api.nvim_get_keymap = nvim_get_keymap
  -- Restore the global MiniClue config
  MiniClue.config = miniclue_config_deepcopy
  -- Ensure a fresh deepcopy on next override
  miniclue_config_deepcopy = nil
  -- Remove the global open bookmark mapping
  vim.keymap.del('n', "'")
end

local bookmark_to_clue = function(id, b) return { mode = 'n', keys = mark_goto .. id, desc = b.desc } end
local override_globally = function()
  -- Never show the original config clues
  get_config_override().clues = {}
  -- Return early
  local state = MiniFiles.get_explorer_state()
  if not (state and mark_goto_rhs) then return end

  -- HACK: Manipulate nvim_get_keymap in order to only include 'g' clues from MiniFiles
  ---@diagnostic disable-next-line: duplicate-set-field
  vim.api.nvim_get_keymap = function(mode)
    if mode == 'n' and explorer_is_open() then return {} end
    return nvim_get_keymap(mode)
  end

  -- Override 'config clues' to only contain bookmarks from MiniFiles
  get_config_override().clues = vim.iter(pairs(state.bookmarks)):map(bookmark_to_clue):totable()

  -- Ensure global "'" mapping to local "mark_goto" handler in minifiles
  vim.keymap.set('n', mark_goto, mark_goto_rhs, { desc = 'MiniFiles open bookmark' })
end

local enable = function(buf_id)
  -- Activate MiniClue with only the restricted set of triggers
  local miniclue_config = get_config_override()
  miniclue_config.triggers = clue_triggers
  MiniClue.enable_buf_triggers(buf_id)
end

local explorer_buffer_create = function(args)
  -- If explorer is not yet open, enable buffer later
  if not explorer_is_open() then return end

  -- Explorer is open, enable buffer here
  enable(args.data.buf_id)
  -- NOTE: Update bookmarks. There is no MiniFilesBookmarkAdded event...
  override_globally()
end

local explorer_open = function()
  -- MiniClue is not yet enabled on explorer's buffers. The "'" mapping must be from MiniFiles
  if mark_goto_rhs == nil then mark_goto_rhs = vim.fn.maparg("'", 'n', false, true).callback end

  -- Enable MiniClue in all buffers
  local state = MiniFiles.get_explorer_state()
  vim.iter(ipairs(state.windows)):each(function(_, w) enable(vim.api.nvim_win_get_buf(w.win_id)) end)
  override_globally()
  explorer_set_open(true)
end

local explorer_close = function()
  restore_globally()
  explorer_set_open(false)
end

local buf_enter = function()
  if tab_prev == nil then tab_prev = vim.api.nvim_get_current_tabpage() end
  local tab_current = vim.api.nvim_get_current_tabpage()
  if tab_prev == tab_current then return end

  if explorer_is_open(tab_prev) then restore_globally() end
  if explorer_is_open(tab_current) then override_globally() end
  tab_prev = tab_current
end

local FilesClued = {}
FilesClued.setup = function()
  if MiniFiles == nil or MiniClue == nil then return end
  if MiniFiles.config.mappings.mark_goto ~= mark_goto then return end
  _G.FilesClued = FilesClued

  local augroup = vim.api.nvim_create_augroup('FilesClued', {})
  local au = function(event, pattern, callback, desc)
    vim.api.nvim_create_autocmd(event, { group = augroup, pattern = pattern, callback = callback, desc = desc })
  end
  au('BufEnter', '*', buf_enter, 'Administer MiniClue per tabpage')
  au('User', 'MiniFilesBufferCreate', explorer_buffer_create, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerOpen', explorer_open, 'Show MiniFiles in MiniClue')
  au('User', 'MiniFilesExplorerClose', explorer_close, 'Restore regular MiniClue')
end
return FilesClued

The path to the code in my config: lua/akextra/files_clued.lua

The layout of the explorer in the video: See this discussion

[echasnovski]

Nice! Thanks for sharing!

Solution:

1. Opt-in, and keep track of open explorers per tabpage. Manipulate the global MiniClue config accordingly
2. If explorer is active, add a global mapping, using ' for MiniFiles
3. Apply a hack, overriding vim.api.nvim_get_keys if needed...)

As you know, I am not a big fan of monkey-patching global "module tables" and vim.api.nvim_get_keymaps even more.

My initial reaction to reading "Manipulate the global MiniClue config accordingly" is that it should be possible to use vim.b.miniclue_config in ever 'mini.files' buffer. Like by computing and setting appropriate clues. Or maybe creating many buffer local mappings for 'm, 'c, etc. with appropriate descriptions would be enough.

[abeldekat]

Thanks for the feedback!

As you know, I am not a big fan of monkey-patching global "module tables" and vim.api.nvim_get_keymaps even more.

Me neither, not anymore...))) I tried several approaches, all without success.
Do note that the monkey patching is only for the g mappings. It works without, but is less useful, as the global g mappings clutter the view.

Currently, a user can manipulate 'config clues', but has no say in the addition of global mappings and buffer mappings. Would it be an idea to extend mini.clue, with for example an extra field per trigger:

mode = { 'n', 'x' }, keys = 'g', no_global_mappings = true },        -- `g` key

Or, alternatively, add a custom filter, to filter clues that are not relevant in a 'show buffer mapping' context.

Also, I think this comment regarding precedence is not correct. Buffer mappings apply last.

My initial reaction to reading "Manipulate the global MiniClue config accordingly" is that it should be possible to use vim.b.miniclue_config in ever 'mini.files' buffer.

I tried that, still needing to manipulate the global config, as merging does not remove unwanted global triggers or clues.

Or maybe creating many buffer local mappings for 'm, 'c, etc. with appropriate descriptions would be enough.

I think that would work, but a bit less efficiently. Also, that approach cannot hook into map_goto. I don't think the code would be (much) cleaner, as opposed to converting the bookmarks to manual clues, using a global ' mapping.
It is definitely a better approach though if the entire solution can be implemented without manipulating the global MiniClue config. In that case, "tab" administration would not be necessary, as all changes are buffer local...

[echasnovski]

Would it be an idea to extend mini.clue, with for example an extra field per trigger:

I don't think I like that, as one of the core behavior cases of 'mini.clue' is that it shows all active mappings. This avoids the "The clue window doesn't show the the key but it still acts if I press it", which looks very problematic to me.

Also, I think this comment regarding precedence is not correct. Buffer mappings apply last.

Yeah, most likely. If that part will get useful refactor or fixes, that'll have to be fixed. Don't really want to make a commit to fix one local developer-only comment.

[abeldekat]

I don't think I like that, as one of the core behavior cases of 'mini.clue' is that it shows all active mappings. This avoids the "The clue window doesn't show the the key but it still acts if I press it", which looks very problematic to me.

Instead of the hack, I now explicitly remove all global g mappings not needed in MiniFiles(for example, gc and gh). When the explorer closes, or a new tab is opened, I restore those mappings.
Also, the code is a bit more robust. I took some time to make the clues work when vim is opened with a directory argument.

I added the code as "v2".

[abeldekat]

I updated the code("v3"). Instead of removing selected global g mappings when the explorer is open, I update the descriptions. That improves the readability of the clues window as well.

[abeldekat]

I arrived at "v4".

The new code overrides the g and ' trigger-mappings from MiniClue, only when inside explorer.
This has the following benefits:

1. "Extra" actions are only performed when the user actually presses g or ' when inside explorer
2. As a consequence, any change to global MiniClue.config.clues lives much shorter. The approach is similar to the accepted approach to restrict triggers.
3. Maintaining "tabpage state" is not needed anymore

I also applied your suggestion to create buffer mappings from the bookmarks. This has the benefit that the global ' mapping when inside explorer is not needed anymore.

[abeldekat]

I created a new show and tell