feat(input): Add async input (#871)

* feat(input): Add async input

* ci: Run docgen workflow only if docs or api is changed

Author: kristijanhusak

Diff for: .github/workflows/docgen.yml

@@ -4,6 +4,9 @@ on:
   push:
     branches:
       - master
+    paths:
+      - docs/**
+      - lua/orgmode/api/**
 
 jobs:
   docgen:

Diff for: docs/configuration.org

@@ -2838,3 +2838,25 @@ require('orgmode').setup({
   }
 })
 #+end_src
+
+*** Input
+:PROPERTIES:
+:CUSTOM_ID: input
+:END:
+- Type: =boolean=
+- Default: =false=
+
+By default, Vim's built-in =input()= function is used for input prompts.
+To use Neovim's =vim.ui.input()= function, add this to config:
+
+#+begin_src lua
+require('orgmode').setup({
+  ui = {
+    input = {
+      use_vim_ui = true
+    }
+  }
+})
+#+end_src
+
+📝 NOTE: If you are using a plugin for =vim.ui.input=, make sure it supports autocompletion for better experience. [[https://github.com/folke/snacks.nvim][snacks.nvim]] input module supports autocompletion.

Diff for: lua/orgmode/agenda/init.lua

@@ -7,6 +7,7 @@ local AgendaFilter = require('orgmode.agenda.filter')
 local Menu = require('orgmode.ui.menu')
 local Promise = require('orgmode.utils.promise')
 local AgendaTypes = require('orgmode.agenda.types')
+local Input = require('orgmode.ui.input')
 
 ---@class OrgAgenda
 ---@field highlights table[]
@@ -48,7 +49,25 @@ function Agenda:open_view(type, opts)
     return
   end
   self.views = { view }
-  return self:render()
+  return self:prepare_and_render()
+end
+
+function Agenda:prepare_and_render()
+  return Promise.map(function(view)
+    return view:prepare()
+  end, self.views):next(function(views)
+    local valid_views = vim.tbl_filter(function(view)
+      return view ~= false
+    end, views)
+
+    -- Some of the views returned false, abort render
+    if #valid_views ~= #self.views then
+      return
+    end
+
+    self.views = views
+    return self:render()
+  end)
 end
 
 function Agenda:render()
@@ -71,6 +90,10 @@ function Agenda:render()
       vim.w.org_window_pos = nil
     end
   end
+
+  if #self.views > 1 then
+    vim.fn.cursor({ 1, 0 })
+  end
 end
 
 function Agenda:agenda(opts)
@@ -151,11 +174,7 @@ function Agenda:_build_custom_commands()
           table.insert(views, AgendaTypes[agenda_type.type]:new(opts))
         end
         self.views = views
-        local result = self:render()
-        if #self.views > 1 then
-          vim.fn.cursor({ 1, 0 })
-        end
-        return result
+        return self:prepare_and_render()
       end,
     })
   end
@@ -271,16 +290,21 @@ end
 ---@param source? string
 function Agenda:redo(source, preserve_cursor_pos)
   self:_call_all_views('redo')
-  return self.files:load(true):next(vim.schedule_wrap(function()
-    local save_view = preserve_cursor_pos and vim.fn.winsaveview()
-    if source == 'mapping' then
-      self:_call_view_and_render('redraw')
-    end
-    self:render()
-    if save_view then
-      vim.fn.winrestview(save_view)
-    end
-  end))
+  local save_view = preserve_cursor_pos and vim.fn.winsaveview()
+  return self.files
+    :load(true)
+    :next(function()
+      if source == 'mapping' then
+        return self:_call_view_async('redraw')
+      end
+      return true
+    end)
+    :next(function()
+      self:render()
+      if save_view then
+        vim.fn.winrestview(save_view)
+      end
+    end)
 end
 
 function Agenda:advance_span(direction)
@@ -499,14 +523,15 @@ end
 function Agenda:filter()
   local this = self
   self.filters:parse_available_filters(self.views)
-  local filter_term = utils.input('Filter [+cat-tag/regexp/]: ', self.filters.value, function(arg_lead)
+  return Input.open('Filter [+cat-tag/regexp/]: ', self.filters.value, function(arg_lead)
     return utils.prompt_autocomplete(arg_lead, this.filters:get_completion_list(), { '+', '-' })
+  end):next(function(value)
+    if not value or value == self.filters.value then
+      return false
+    end
+    self.filters:parse(value)
+    return self:redo('filter', true)
   end)
-  if filter_term == self.filters.value then
-    return
-  end
-  self.filters:parse(filter_term)
-  return self:redo('filter', true)
 end
 
 ---@param opts table
@@ -576,6 +601,22 @@ function Agenda:_call_view(method, ...)
   return executed
 end
 
+function Agenda:_call_view_async(method, ...)
+  local args = { ... }
+  return Promise.map(function(view)
+    if view[method] and view.view:is_in_range() then
+      return view[method](view, unpack(args))
+    end
+  end, self.views):next(function(views)
+    for _, view in ipairs(views) do
+      if view then
+        return true
+      end
+    end
+    return false
+  end)
+end
+
 function Agenda:_call_all_views(method, ...)
   local executed = false
   for _, view in ipairs(self.views) do

Diff for: lua/orgmode/agenda/types/agenda.lua

@@ -9,13 +9,7 @@ local AgendaLineToken = require('orgmode.agenda.view.token')
 local ClockReport = require('orgmode.clock.report')
 local utils = require('orgmode.utils')
 local SortingStrategy = require('orgmode.agenda.sorting_strategy')
-
----@class OrgAgendaViewType
----@field render fun(self: OrgAgendaViewType, bufnr:number, current_line?: number): OrgAgendaView
----@field get_lines fun(self: OrgAgendaViewType): OrgAgendaLine | OrgAgendaLine[]
----@field get_line fun(self: OrgAgendaViewType, line_nr: number): OrgAgendaLine | nil
----@field rerender_agenda_line fun(self: OrgAgendaViewType, agenda_line: OrgAgendaLine, headline: OrgHeadline): OrgAgendaLine | nil
----@field view OrgAgendaView
+local Promise = require('orgmode.utils.promise')
 
 ---@class OrgAgendaTypeOpts
 ---@field files OrgFiles
@@ -97,6 +91,10 @@ function OrgAgendaType:new(opts)
   return this
 end
 
+function OrgAgendaType:prepare()
+  return Promise.resolve(self)
+end
+
 function OrgAgendaType:redo()
   if self.agenda_files then
     self.files:load_sync(true)

Diff for: lua/orgmode/agenda/types/init.lua

@@ -1,3 +1,13 @@
+---@class OrgAgendaViewType
+---@field render fun(self: OrgAgendaViewType, bufnr:number, current_line?: number): OrgAgendaView
+---@field get_lines fun(self: OrgAgendaViewType): OrgAgendaLine | OrgAgendaLine[]
+---@field get_line fun(self: OrgAgendaViewType, line_nr: number): OrgAgendaLine | nil
+---@field rerender_agenda_line fun(self: OrgAgendaViewType, agenda_line: OrgAgendaLine, headline: OrgHeadline): OrgAgendaLine | nil
+---@field view OrgAgendaView
+---@field prepare fun(self: OrgAgendaViewType): OrgPromise<OrgAgendaViewType>
+---@field redraw? fun(self: OrgAgendaViewType): OrgPromise<OrgAgendaViewType>
+---@field redo? fun(self: OrgAgendaViewType): OrgPromise<OrgAgendaViewType>
+
 ---@alias OrgAgendaTypes 'agenda' | 'todo' | 'tags' | 'tags_todo' | 'search'
 return {
   agenda = require('orgmode.agenda.types.agenda'),

Diff for: lua/orgmode/agenda/types/search.lua

@@ -1,6 +1,6 @@
-local utils = require('orgmode.utils')
 ---@diagnostic disable: inject-field
 local OrgAgendaTodosType = require('orgmode.agenda.types.todo')
+local Input = require('orgmode.ui.input')
 
 ---@class OrgAgendaSearchTypeOpts:OrgAgendaTodosTypeOpts
 ---@field headline_query? string
@@ -18,27 +18,35 @@ function OrgAgendaSearchType:new(opts)
   local obj = OrgAgendaTodosType:new(opts)
   setmetatable(obj, self)
   obj.headline_query = self.headline_query
-  if not opts.headline_query or opts.headline_query == '' then
-    obj.headline_query = self:get_search_term()
-  end
   return obj
 end
 
+function OrgAgendaSearchType:prepare()
+  if not self.headline_query or self.headline_query == '' then
+    return self:get_search_term()
+  end
+end
+
 function OrgAgendaSearchType:get_file_headlines(file)
   return file:find_headlines_matching_search_term(self.headline_query or '', false, true)
 end
 
 function OrgAgendaSearchType:get_search_term()
-  return utils.input('Enter search term: ', self.headline_query or '')
+  return Input.open('Enter search term: ', self.headline_query or ''):next(function(value)
+    if not value then
+      return false
+    end
+    self.headline_query = value
+    return self
+  end)
 end
 
 function OrgAgendaSearchType:redraw()
   -- Skip prompt for custom views
   if self.id then
     return self
   end
-  self.headline_query = self:get_search_term()
-  return self
+  return self:get_search_term()
 end
 
 return OrgAgendaSearchType

Diff for: lua/orgmode/agenda/types/tags.lua

@@ -4,6 +4,7 @@ local config = require('orgmode.config')
 local utils = require('orgmode.utils')
 local Search = require('orgmode.files.elements.search')
 local OrgAgendaTodosType = require('orgmode.agenda.types.todo')
+local Input = require('orgmode.ui.input')
 
 ---@alias OrgAgendaTodoIgnoreDeadlinesTypes 'all' | 'near' | 'far' | 'past' | 'future'
 ---@alias OrgAgendaTodoIgnoreScheduledTypes 'all' | 'past' | 'future'
@@ -27,24 +28,31 @@ function OrgAgendaTagsType:new(opts)
   if not opts.id then
     opts.subheader = 'Press "r" to update search'
   end
-  local match_query = opts.match_query
-  if not opts.id and (not match_query or match_query == '') then
-    match_query = self:get_tags(opts.files)
-    if not match_query then
-      return nil
-    end
-  end
-
   setmetatable(self, { __index = OrgAgendaTodosType })
   local obj = OrgAgendaTodosType:new(opts)
   setmetatable(obj, self)
-  obj.match_query = match_query or ''
+  obj.match_query = opts.match_query or ''
   obj.todo_ignore_deadlines = opts.todo_ignore_deadlines
   obj.todo_ignore_scheduled = opts.todo_ignore_scheduled
-  obj.header = opts.header or ('Headlines with TAGS match: ' .. obj.match_query)
   return obj
 end
 
+function OrgAgendaTagsType:_get_header()
+  if self.header then
+    return self.header
+  end
+
+  return 'Headlines with TAGS match: ' .. (self.match_query or '')
+end
+
+function OrgAgendaTagsType:prepare()
+  if self.id or self.match_query and self.match_query ~= '' then
+    return self
+  end
+
+  return self:get_tags()
+end
+
 function OrgAgendaTagsType:get_file_headlines(file)
   local headlines = file:apply_search(Search:new(self.match_query), self.todo_only)
   if self.todo_ignore_deadlines then
@@ -94,25 +102,28 @@ function OrgAgendaTagsType:get_file_headlines(file)
   return headlines
 end
 
----@param files? OrgFiles
-function OrgAgendaTagsType:get_tags(files)
-  local tags = utils.input('Match: ', self.match_query or '', function(arg_lead)
-    return utils.prompt_autocomplete(arg_lead, (files or self.files):get_tags())
+function OrgAgendaTagsType:get_tags()
+  return Input.open('Match: ', self.match_query or '', function(arg_lead)
+    return utils.prompt_autocomplete(arg_lead, self.files:get_tags())
+  end):next(function(tags)
+    if not tags then
+      return false
+    end
+    if vim.trim(tags) == '' then
+      utils.echo_warning('Invalid tag.')
+      return false
+    end
+    self.match_query = tags
+    return self
   end)
-  if vim.trim(tags) == '' then
-    return utils.echo_warning('Invalid tag.')
-  end
-  return tags
 end
 
 function OrgAgendaTagsType:redraw()
   -- Skip prompt for custom views
   if self.id then
     return self
   end
-  self.match_query = self:get_tags() or ''
-  self.header = 'Headlines with TAGS match: ' .. self.match_query
-  return self
+  return self:get_tags()
 end
 
 return OrgAgendaTagsType

Diff for: lua/orgmode/agenda/types/todo.lua

@@ -8,6 +8,7 @@ local utils = require('orgmode.utils')
 local agenda_highlights = require('orgmode.colors.highlights')
 local hl_map = agenda_highlights.get_agenda_hl_map()
 local SortingStrategy = require('orgmode.agenda.sorting_strategy')
+local Promise = require('orgmode.utils.promise')
 
 ---@class OrgAgendaTodosTypeOpts
 ---@field files OrgFiles
@@ -74,6 +75,10 @@ function OrgAgendaTodosType:new(opts)
   return this
 end
 
+function OrgAgendaTodosType:prepare()
+  return Promise.resolve(self)
+end
+
 function OrgAgendaTodosType:_setup_agenda_files()
   if not self.agenda_files then
     return
@@ -90,14 +95,21 @@ function OrgAgendaTodosType:redo()
   end
 end
 
+function OrgAgendaTodosType:_get_header()
+  if self.header then
+    return self.header
+  end
+  return 'Global list of TODO items of type: ALL'
+end
+
 ---@param bufnr? number
 function OrgAgendaTodosType:render(bufnr)
   self.bufnr = bufnr or 0
   local headlines, category_length = self:_get_headlines()
   local agendaView = AgendaView:new({ bufnr = self.bufnr, highlighter = self.highlighter })
 
   agendaView:add_line(AgendaLine:single_token({
-    content = self.header or 'Global list of TODO items of type: ALL',
+    content = self:_get_header(),
     hl_group = '@org.agenda.header',
   }))
   if self.subheader then