feat(explorer): custom keymaps

[richardgill]

Adds keymaps.explorer.custom for lifecycle-owned, buffer-local Explorer mappings.

require("codediff").setup({
  keymaps = {
    explorer = {
      custom = {
        {
          key = "gy",
          desc = "Copy explorer path",
          callback = function(ctx)
            if ctx.entry.path then
              vim.fn.setreg("+", ctx.entry.path)
            end
          end,
        },
      },
    },
  },
})

Callbacks receive this context:

{
  entry = selected_entry,
  redraw = function() end,
  refresh = function() end,
}

ctx.entry has exactly one of these shapes, based on the selected row:

{ kind = "file", path, old_path, group, status, stats }
{ kind = "directory", name, path, group, stats, files }
{ kind = "group", name, group, stats, files }

Directory and group files use the normalized { path, old_path, group, status, stats } shape. stats is nil when line statistics are disabled.

• redraw() renders the existing tree without rebuilding nodes, changing selection or fold state, or running Git.
• refresh() uses the normal asynchronous Explorer refresh.
• Custom mappings are lifecycle registry claims on the Explorer panel and intentionally override matching built-ins.
• Registry teardown restores any previous buffer-local mapping and safely removes CodeDiff-owned mappings.
• Custom mappings appear in the g? keymap help with their configured descriptions.
• Both callback functions safely become no-ops after the Explorer closes.

Testing

• Added focused coverage for registry ownership, suspension, restoration, built-in collision precedence, and g? visibility.
• Retained callback coverage for file, directory, and group entries, line statistics, redraw, refresh, and post-teardown safety.
• Ran the complete C and Lua suites with an isolated NVIM_APPNAME.

Manual testing

Used this configuration with one modified file at src/example.lua:

require("codediff").setup({
  explorer = {
    view_mode = "tree",
    flatten_dirs = false,
    auto_refresh = false,
  },
  keymaps = {
    explorer = {
      custom = {
        {
          key = "gp",
          desc = "Print explorer callback context",
          callback = function(ctx)
            vim.notify(vim.inspect(ctx))
          end,
        },
      },
    },
  },
})

Invoked gp on the file, its parent directory, and the Changes group. Each message shows the corresponding entry metadata and the shared redraw and refresh functions.

Without line statistics

custom-explorer-keymaps-without-line-stats.mp4

With line statistics

custom-explorer-keymaps-with-line-stats.mp4

Supersedes part of #448.

Fixes #455.
Fixes #388.

[richardgill]

@esmuellert I’ve rebased this onto the latest main and adapted it to the lifecycle keymap registry introduced in #505. Custom Explorer mappings now use lifecycle-owned panel claims, restore correctly on teardown, preserve override behavior, and appear in g? help. All tests and checks pass. Ready for another look when convenient!