feat: allow configuring keymap descriptions

DOCS.md

@@ -847,13 +847,42 @@ require('orgmode').setup({
       org_agenda = false,
       org_capture = 'gC'
     },
-    agenda = {
-      org_agenda_later = false
+  }
+})
+```
+
+To change a key mapping's `lhs` but not its `desc`, provide a string or a table:
+
+```lua
+require('orgmode').setup({
+  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
+  org_default_notes_file = '~/Dropbox/org/refile.org',
+  mappings = {
+    global = {
+      -- providing a string
+      org_agenda = '<D-a>',
+      -- providing a table
+      org_capture = { '<D-c>' }
+    },
+  }
+})
+
+To change a key mapping's `lhs` and its `desc`, provide a table:
+
+```lua
+require('orgmode').setup({
+  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
+  org_default_notes_file = '~/Dropbox/org/refile.org',
+  mappings = {
+    global = {
+       org_capture = { '<D-c>', desc = 'Open Capture Prompt' }
     }
   }
 })
 ```
 
+(The `desc` value is displayed in tools like WhichKey.)
+
 You can find the configuration file that holds all default mappings [here](./lua/orgmode/config/mappings/init.lua)
 
 **NOTE**: All mappings are normal mode mappings (`nnoremap`) with exception of `org_return`

lua/orgmode/config/mappings/map_entry.lua

@@ -106,6 +106,12 @@ function MapEntry:attach(default_mapping, user_mapping, opts)
     map_opts.prefix = nil
   end
 
+  if user_mapping ~= nil then
+    if user_mapping.desc ~= nil then
+      map_opts.desc = user_mapping.desc
+    end
+  end
+
   for _, map in ipairs(mapping) do
     if prefix ~= '' then
       map = map:gsub('<prefix>', prefix)

tests/plenary/config/config_spec.lua

@@ -1,4 +1,28 @@
 local orgmode = require('orgmode')
+local config = require('orgmode.config')
+
+local get_normal_mode_mapping_in_org_buffer = function(lhs)
+  local current_buffer = vim.api.nvim_buf_get_name(0)
+
+  local refile_file = vim.fn.getcwd() .. '/tests/plenary/fixtures/refile.org'
+  vim.cmd('edit ' .. refile_file)
+
+  local normal_mode_mappings_in_org_buffer = vim.api.nvim_buf_get_keymap(0, 'n')
+
+  for _, keymap in ipairs(normal_mode_mappings_in_org_buffer) do
+    if keymap then
+      if keymap['lhs'] then
+        if keymap['lhs'] == lhs then
+          vim.cmd('edit ' .. current_buffer)
+          return keymap
+        end
+      end
+    end
+  end
+
+  vim.cmd('edit ' .. current_buffer)
+  return nil
+end
 
 describe('Config', function()
   local refile_file = vim.fn.getcwd() .. '/tests/plenary/fixtures/refile.org'
@@ -9,7 +33,6 @@ describe('Config', function()
       org_default_notes_file = refile_file,
       org_archive_location = vim.fn.getcwd() .. '/tests/plenary/fixtures/archive/%s_archive::',
     })
-    local config = require('orgmode.config')
     assert.are.same(
       config:parse_archive_location(refile_file),
       vim.fn.getcwd() .. '/tests/plenary/fixtures/archive/refile.org_archive'
@@ -22,10 +45,61 @@ describe('Config', function()
       org_default_notes_file = refile_file,
       org_archive_location = 'archives_relative/%s_archive::',
     })
-    local config = require('orgmode.config')
     assert.are.same(
       config:parse_archive_location(refile_file),
       vim.fn.getcwd() .. '/tests/plenary/fixtures/archives_relative/refile.org_archive'
     )
   end)
+
+  ---@diagnostic disable: need-check-nil
+  it('should use the default key mapping when no override is provided', function()
+    local org = orgmode.setup({})
+
+    local mapping = get_normal_mode_mapping_in_org_buffer('g{')
+    assert.are.same('<Cmd>lua require("orgmode").action("org_mappings.outline_up_heading")<CR>', mapping['rhs'])
+    assert.are.same('org goto parent headline', mapping['desc'])
+  end)
+
+  it('should use the provided key mapping when the override is provided as a string', function()
+    local org = orgmode.setup({
+      mappings = {
+        org = {
+          outline_up_heading = { 'gouh' },
+        },
+      },
+    })
+
+    local mapping = get_normal_mode_mapping_in_org_buffer('gouh')
+    assert.are.same('<Cmd>lua require("orgmode").action("org_mappings.outline_up_heading")<CR>', mapping['rhs'])
+    assert.are.same('org goto parent headline', mapping['desc'])
+  end)
+
+  it('should use the provided key mapping when the override is provided as a table', function()
+    local org = orgmode.setup({
+      mappings = {
+        org = {
+          outline_up_heading = { 'gouh' },
+        },
+      },
+    })
+
+    local mapping = get_normal_mode_mapping_in_org_buffer('gouh')
+    assert.are.same('<Cmd>lua require("orgmode").action("org_mappings.outline_up_heading")<CR>', mapping['rhs'])
+    assert.are.same('org goto parent headline', mapping['desc'])
+  end)
+
+  it('should use the provided key mapping when the override is provided as a table including a new desc', function()
+    local org = orgmode.setup({
+      mappings = {
+        org = {
+          outline_up_heading = { 'gouh', desc = 'Go To Parent Headline' },
+        },
+      },
+    })
+
+    local mapping = get_normal_mode_mapping_in_org_buffer('gouh')
+    assert.are.same('<Cmd>lua require("orgmode").action("org_mappings.outline_up_heading")<CR>', mapping['rhs'])
+    assert.are.same('Go To Parent Headline', mapping['desc'])
+  end)
+  ---@diagnostic enable: need-check-nil
 end)

tests/plenary/init_spec.lua

@@ -37,7 +37,7 @@ describe('Init', function()
   end)
 
   it('should append files to paths', function()
-    local fname = vim.fn.tempname() .. '.org'
+    local fname = vim.fn.resolve(vim.fn.tempname() .. '.org')
     vim.fn.writefile({ '* Appended' }, fname)
 
     assert.is.Nil(org.files.files[fname])