feat: modern menu (#549)

Author: danilshvalov

DOCS.md

@@ -20,7 +20,9 @@
 7. [Autocompletion](#autocompletion)
 8. [Abbreviations](#abbreviations)
 9. [Formatting](#formatting)
-10. [Colors](#colors)
+10. [User interface](#user-interface)
+    1. [Colors](#colors)
+    2. [Menu](#menu)
 11. [Advanced search](#advanced-search)
 12. [Notifications (experimental)](#notifications-experimental)
 13. [Clocking](#clocking)
@@ -745,7 +747,7 @@ require('orgmode').setup({
 })
 ```
 
-### Closing note mappings
+### Note mappings
 
 Mappings used in closing note window.
 
@@ -1135,7 +1137,9 @@ Currently, these things are formatted:
 * Tables are formatted (see [Tables](#Tables) for more info)
 * Clock entries total time is recalculated (see [Recalculating totals](#recalculating-totals) in [Clocking](#Clocking) section)
 
-## Colors
+## User interface
+
+### Colors
 Colors used for todo keywords and agenda states (deadline, schedule ok, schedule warning)
 are parsed from the current colorsheme from several highlight groups (Error, WarningMsg, DiffAdd, etc.).
 If those colors are not suitable you can override them like this:
@@ -1162,7 +1166,7 @@ endfunction
 
 For adding/changing TODO keyword colors see [org-todo-keyword-faces](#org_todo_keyword_faces)
 
-### Highlight Groups
+#### Highlight Groups
 
 * The following highlight groups are based on _Treesitter_ query results, hence when setting up _Orgmode_ these
   highlights must be enabled by removing `disable = {'org'}` from the default recommended _Treesitter_ configuration.
@@ -1197,6 +1201,76 @@ For adding/changing TODO keyword colors see [org-todo-keyword-faces](#org_todo_k
   * `OrgAgendaScheduled`: A scheduled item in the agenda view
   * `OrgAgendaScheduledPast`: A item past its scheduled date in the agenda view
 
+### Menu
+
+The menu is used when selecting further actions in `agenda`, `capture` and `export`. Here is an example of the menu you see when opening `agenda`:
+
+```
+Press key for an agenda command
+-------------------------------
+a Agenda for current week or day
+t List of all TODO entries
+m Match a TAGS/PROP/TODO query
+M Like m, but only for TODO entries
+s Search for keywords
+q Quit
+```
+Users have the option to change the appearance of this menu. To do this, you need to add a handler in the UI configuration section:
+```lua
+require("orgmode").setup({
+  ui = {
+    menu = {
+      handler = function(data)
+        -- your handler here, for example:
+        local options = {}
+        local options_by_label = {}
+
+        for _, item in ipairs(data.items) do
+          -- Only MenuOption has `key`
+          -- Also we don't need `Quit` option because we can close the menu with ESC
+          if item.key and item.label:lower() ~= "quit" then
+            table.insert(options, item.label)
+            options_by_label[item.label] = item
+          end
+        end
+
+        local handler = function(choice)
+          if not choice then
+            return
+          end
+
+          local option = options_by_label[choice]
+          if option.action then
+            option.action()
+          end
+        end
+
+        vim.ui.select(options, {
+          propmt = data.propmt,
+        }, handler)
+      end,
+    },
+  },
+})
+```
+When the menu is called, the handler receives a table `data` with the following fields as input:
+* `title` (`string`) — menu title
+* `items` (`table`) — array containing `MenuItem` (see below)
+* `prompt` (`string`) — prompt text used to prompt a keystroke
+
+Each menu item `MenuItem` is one of two types: `MenuOption` and `MenuSeparator`.
+
+`MenuOption` is a table containing the following fields:
+* `label` (`string`) — description of the action
+* `key` (`string`) — key that will be processed when the keys are pressed in the menu
+* `action` (`function` *optional*) — handler that will be called when the `key` is pressed in the menu.
+
+`MenuSeparator` is a table containing the following fields:
+* `icon` (`string` *optional*) — character used as separator. The default character is `-`
+* `length` (`number` *optional*) — number of repetitions of the separator character. The default length is 80
+
+In order for the menu to work as expected, the handler must call `action` from `MenuItem`.
+
 ## Advanced search
 Part of [Advanced search](https://orgmode.org/worg/org-tutorials/advanced-searching.html) functionality
 is implemented.

lua/orgmode/agenda/init.lua

@@ -9,6 +9,7 @@ local AgendaSearchView = require('orgmode.agenda.views.search')
 local AgendaTodosView = require('orgmode.agenda.views.todos')
 local AgendaTagsView = require('orgmode.agenda.views.tags')
 local AgendaView = require('orgmode.agenda.views.agenda')
+local Menu = require('orgmode.ui.menu')
 
 ---@class Agenda
 ---@field content table[]
@@ -88,45 +89,50 @@ end
 
 function Agenda:prompt()
   self.filters:reset()
-  return utils.menu('Press key for an agenda command', {
-    {
-      label = 'Agenda for current week or day',
-      key = 'a',
-      action = function()
-        return self:agenda()
-      end,
-    },
-    {
-      label = 'List of all TODO entries',
-      key = 't',
-      action = function()
-        return self:todos()
-      end,
-    },
-    {
-      label = 'Match a TAGS/PROP/TODO query',
-      key = 'm',
-      action = function()
-        return self:tags()
-      end,
-    },
-    {
-      label = 'Like m, but only TODO entries',
-      key = 'M',
-      action = function()
-        return self:tags({ todo_only = true })
-      end,
-    },
-    {
-      label = 'Search for keywords',
-      key = 's',
-      action = function()
-        return self:search()
-      end,
-    },
-    { label = 'Quit', key = 'q' },
-    { label = '', separator = ' ', length = 1 },
-  }, 'Press key for an agenda command')
+  local menu = Menu:new({
+    title = 'Press key for an agenda command',
+    prompt = 'Press key for an agenda command',
+  })
+
+  menu:add_option({
+    label = 'Agenda for current week or day',
+    key = 'a',
+    action = function()
+      return self:agenda()
+    end,
+  })
+  menu:add_option({
+    label = 'List of all TODO entries',
+    key = 't',
+    action = function()
+      return self:todos()
+    end,
+  })
+  menu:add_option({
+    label = 'Match a TAGS/PROP/TODO query',
+    key = 'm',
+    action = function()
+      return self:tags()
+    end,
+  })
+  menu:add_option({
+    label = 'Like m, but only TODO entries',
+    key = 'M',
+    action = function()
+      return self:tags({ todo_only = true })
+    end,
+  })
+  menu:add_option({
+    label = 'Search for keywords',
+    key = 's',
+    action = function()
+      return self:search()
+    end,
+  })
+  menu:add_option({ label = 'Quit', key = 'q' })
+  menu:add_separator({ icon = ' ', length = 1 })
+
+  return menu:open()
 end
 
 function Agenda:_render(skip_rebuild)

lua/orgmode/capture/init.lua

@@ -4,6 +4,7 @@ local Files = require('orgmode.parser.files')
 local File = require('orgmode.parser.file')
 local Templates = require('orgmode.capture.templates')
 local ClosingNote = require('orgmode.capture.closing_note')
+local Menu = require('orgmode.ui.menu')
 
 ---@class Capture
 ---@field templates Templates
@@ -37,13 +38,13 @@ function Capture:_create_menu_items(templates)
         key = key,
       }
       if type(template) == 'string' then
-        item['label'] = template .. '...'
-        item['action'] = function()
+        item.label = template .. '...'
+        item.action = function()
           self:_create_prompt(self:_get_subtemplates(key, templates))
         end
       else
-        item['label'] = template.description
-        item['action'] = function()
+        item.label = template.description
+        item.action = function()
           return self:open_template(template)
         end
       end
@@ -54,12 +55,15 @@ function Capture:_create_menu_items(templates)
 end
 
 function Capture:_create_prompt(templates)
-  local menu_items = self:_create_menu_items(templates)
-  table.insert(menu_items, { label = '', key = '', separator = '-' })
-  table.insert(menu_items, { label = 'Quit', key = 'q' })
-  table.insert(menu_items, { label = '', separator = ' ', length = 1 })
-
-  return utils.menu('Select a capture template', menu_items, 'Template key')
+  local menu = Menu:new({
+    title = 'Select a capture template',
+    items = self:_create_menu_items(templates),
+    prompt = 'Template key',
+  })
+  menu:add_separator()
+  menu:add_option({ label = 'Quit', key = 'q' })
+  menu:add_separator({ icon = ' ', length = 1 })
+  return menu:open()
 end
 
 function Capture:prompt()

lua/orgmode/config/defaults.lua

@@ -171,6 +171,11 @@ local DefaultConfig = {
     executable_path = 'emacs',
     config_path = '$HOME/.emacs.d/init.el',
   },
+  ui = {
+    menu = {
+      handler = nil,
+    },
+  },
 }
 
 return DefaultConfig

lua/orgmode/export/init.lua

@@ -1,5 +1,6 @@
 local utils = require('orgmode.utils')
 local config = require('orgmode.config')
+local Menu = require('orgmode.ui.menu')
 
 ---@class Export
 local Export = {}
@@ -32,17 +33,20 @@ function Export._exporter(cmd, target, on_success, on_error)
         return on_success(output)
       end
 
-      return utils.menu(string.format('Exported to %s', target), {
-        { label = '', separator = '-', length = 34 },
-        {
-          label = 'Yes',
-          key = 'y',
-          action = function()
-            return utils.open(target)
-          end,
-        },
-        { label = 'No', key = 'n' },
-      }, 'Open')
+      local menu = Menu:new({
+        title = string.format('Exported to %s', target),
+        prompt = 'Open?',
+      })
+      menu:add_separator({ length = 34 })
+      menu:add_option({
+        label = 'Yes',
+        key = 'y',
+        action = function()
+          return utils.open(target)
+        end,
+      })
+      menu:add_option({ label = 'No', key = 'n' })
+      return menu:open()
     end,
   })
 end
@@ -137,7 +141,11 @@ function Export.prompt()
     local action
     if #commands > 1 then
       action = function()
-        utils.menu(label .. ' via', commands, label .. ' via')
+        Menu:new({
+          title = label .. ' via',
+          items = commands,
+          prompt = label .. ' via',
+        }):open()
       end
 
       table.insert(commands, {
@@ -208,9 +216,13 @@ function Export.prompt()
   end
 
   table.insert(opts, { label = 'quit', key = 'q' })
-  table.insert(opts, { label = '', separator = ' ', length = 1 })
+  table.insert(opts, { icon = ' ', length = 1 })
 
-  return utils.menu('Export options', opts, 'Export command')
+  return Menu:new({
+    title = 'Export options',
+    items = opts,
+    prompt = 'Export command',
+  }):open()
 end
 
 return Export