feat: Add ability to provide closing note when marking TODO as DONE

Author: kristijanhusak

DOCS.md

@@ -9,10 +9,11 @@
    1. [Global mappings](#global-mappings)
    2. [Agenda mappings](#agenda-mappings)
    3. [Capture mappings](#capture-mappings)
-   4. [Org mappings](#org-mappings)
-   5. [Edit Src mappings](#edit-src)
-   6. [Text objects](#text-objects)
-   7. [Dot repeat](#dot-repeat)
+   4. [Note mappings](#note-mappings)
+   5. [Org mappings](#org-mappings)
+   6. [Edit Src mappings](#edit-src)
+   7. [Text objects](#text-objects)
+   8. [Dot repeat](#dot-repeat)
 4. [Document Diagnostics](#document-diagnostics)
 5. [Tables](#tables)
 6. [Hyperlinks](#hyperlinks)
@@ -209,8 +210,10 @@ Marker used to indicate a folded headline.
 #### **org_log_done**
 *type*: `string|nil`<br />
 *default value*: `time`<br />
-When set to `time`(default), adds `CLOSED` date when marking headline as done.<br />
-When set to `false`, it is disabled.
+Possible values:
+* `time` - adds `CLOSED` date when marking headline as done
+* `note` - adds `CLOSED` date as above, and prompts for closing note via capture window. Confirm note with `org_note_finalize` (Default `<C-c>`), or ignore providing note via `org_note_kill` (Default `<Leader>ok`)
+* `nil|false` - Disable any logging
 
 #### **org_highlight_latex_and_related**
 *type*: `string|nil`<br />
@@ -709,6 +712,36 @@ require('orgmode').setup({
 })
 ```
 
+### Closing note mappings
+
+Mappings used in closing note window.
+
+#### **org_note_finalize**
+*mapped to*: `<C-c>`<br />
+Save note window content as closing note for a headline. Ignores first comment (if exists)
+#### **org_note_kill**
+*mapped to*: `<Leader>ok`<br />
+Close note window without saving anything
+#### **org_capture_show_help**
+*mapped to*: `g?`<br />
+Show help popup with mappings
+
+These mappings live under `mappings.capture`, and can be changed like this:
+
+```lua
+require('orgmode').setup({
+  org_agenda_files = {'~/Dropbox/org/*', '~/my-orgs/**/*'},
+  org_default_notes_file = '~/Dropbox/org/refile.org',
+  mappings = {
+    capture = {
+      org_capture_finalize = '<Leader>w',
+      org_capture_refile = 'R',
+      org_capture_kill = 'Q'
+    }
+  }
+})
+```
+
 ### Org mappings
 
 Mappings for `org` files.

lua/orgmode/capture/closing_note.lua

@@ -0,0 +1,57 @@
+local utils = require('orgmode.utils')
+local config = require('orgmode.config')
+local Promise = require('orgmode.utils.promise')
+
+---@class ClosingNote
+local ClosingNote = {}
+
+function ClosingNote:new()
+  local data = {}
+  setmetatable(data, self)
+  self.__index = self
+  return data
+end
+
+function ClosingNote:open()
+  self._resolve_fn = nil
+  self._close_tmp = utils.open_tmp_org_window(16, config.win_split_mode)
+  config:setup_mappings('note')
+  vim.api.nvim_buf_set_var(0, 'org_note', true)
+  vim.api.nvim_buf_set_lines(0, 0, -1, false, { '# Insert note for closed todo item', '', '' })
+  vim.schedule(function()
+    vim.cmd('normal! G')
+    vim.cmd('startinsert')
+  end)
+
+  return Promise.new(function(resolve)
+    self._resolve_fn = resolve
+  end)
+end
+
+function ClosingNote:refile()
+  local content = vim.api.nvim_buf_get_lines(0, 0, -1, false)
+  if content[1] and content[1]:match('#%s+') then
+    content = { unpack(content, 2) }
+  end
+  if content[1] and vim.trim(content[1]) == '' then
+    content = { unpack(content, 2) }
+  end
+  local fn = self._resolve_fn
+  self._resolve_fn = nil
+  self:kill()
+  fn(content)
+end
+
+function ClosingNote:kill()
+  if self._close_tmp then
+    self._close_tmp()
+    self._close_tmp = nil
+    if self._resolve_fn then
+      local fn = self._resolve_fn
+      self._resolve_fn = nil
+      fn(nil)
+    end
+  end
+end
+
+return ClosingNote

lua/orgmode/capture/init.lua

@@ -3,16 +3,17 @@ local config = require('orgmode.config')
 local Files = require('orgmode.parser.files')
 local File = require('orgmode.parser.file')
 local Templates = require('orgmode.capture.templates')
-
-local capture_augroup = vim.api.nvim_create_augroup('OrgCapture', { clear = true })
+local ClosingNote = require('orgmode.capture.closing_note')
 
 ---@class Capture
 ---@field templates Templates
+---@field closing_note ClosingNote
 local Capture = {}
 
 function Capture:new()
   local data = {}
   data.templates = Templates:new()
+  data.closing_note = ClosingNote:new()
   setmetatable(data, self)
   self.__index = self
   return data
@@ -68,33 +69,15 @@ end
 ---@param template table
 function Capture:open_template(template)
   local content = self.templates:compile(template)
-  local winnr = vim.api.nvim_get_current_win()
-  utils.open_window(vim.fn.tempname(), 16, config.win_split_mode)
-  vim.cmd([[setf org]])
-  vim.cmd([[setlocal bufhidden=wipe nobuflisted nolist noswapfile nofoldenable]])
+  local on_close = function()
+    require('orgmode').action('capture.refile', true)
+  end
+  self._close_tmp = utils.open_tmp_org_window(16, config.win_split_mode, on_close)
   vim.api.nvim_buf_set_lines(0, 0, -1, true, content)
   self.templates:setup()
   vim.api.nvim_buf_set_var(0, 'org_template', template)
   vim.api.nvim_buf_set_var(0, 'org_capture', true)
-  vim.api.nvim_buf_set_var(0, 'org_prev_window', winnr)
   config:setup_mappings('capture')
-
-  vim.api.nvim_create_autocmd('BufWipeout', {
-    buffer = 0,
-    group = capture_augroup,
-    callback = function()
-      require('orgmode').action('capture.refile', true)
-    end,
-    once = true,
-  })
-  vim.api.nvim_create_autocmd('VimLeavePre', {
-    buffer = 0,
-    group = capture_augroup,
-    callback = function()
-      require('orgmode').action('capture.refile', true)
-    end,
-    once = true,
-  })
 end
 
 ---@param shortcut string
@@ -351,12 +334,9 @@ function Capture.autocomplete_refile(arg_lead)
 end
 
 function Capture:kill()
-  -- Clear all autocmds
-  vim.api.nvim_create_augroup('OrgCapture', { clear = true })
-  local prev_winnr = vim.api.nvim_buf_get_var(0, 'org_prev_window')
-  vim.api.nvim_win_close(0, true)
-  if prev_winnr and vim.api.nvim_win_is_valid(prev_winnr) then
-    vim.api.nvim_set_current_win(prev_winnr)
+  if self._close_tmp then
+    self._close_tmp()
+    self._close_tmp = nil
   end
 end
 

lua/orgmode/config/defaults.lua

@@ -94,6 +94,11 @@ return {
       org_capture_kill = '<prefix>k',
       org_capture_show_help = 'g?',
     },
+    note = {
+      org_note_finalize = '<C-c>',
+      org_note_kill = '<prefix>k',
+      org_note_show_help = 'g?',
+    },
     org = {
       org_refile = '<prefix>r',
       org_timestamp_up_day = '<S-UP>',

lua/orgmode/config/mappings/init.lua

@@ -48,6 +48,11 @@ return {
     org_capture_kill = m.action('capture.kill', { opts = { desc = 'org kill' } }),
     org_capture_show_help = m.action('org_mappings.show_help', { opts = { desc = 'org show help' } }),
   },
+  note = {
+    org_note_finalize = m.action('capture.closing_note.refile', { opts = { desc = 'org finalize note' } }),
+    org_note_kill = m.action('capture.closing_note.kill', { opts = { desc = 'org kill note' } }),
+    org_note_show_help = m.action('org_mappings.show_help', { opts = { desc = 'org show help' } }),
+  },
   org = {
     org_refile = m.action('capture.refile_headline_to_destination', { opts = { desc = 'org refile' } }),
     org_timestamp_up_day = m.action(

lua/orgmode/init.lua

@@ -145,9 +145,17 @@ local function action(cmd, opts)
     return
   end
   instance:init()
-  if instance[parts[1]] and instance[parts[1]][parts[2]] then
-    local item = instance[parts[1]]
-    local method = item[parts[2]]
+  local item = nil
+  for i = 1, #parts - 1 do
+    local part = parts[i]
+    if not item then
+      item = instance[part]
+    else
+      item = item[part]
+    end
+  end
+  if item and item[parts[#parts]] then
+    local method = item[parts[#parts]]
     local success, result = pcall(method, item, opts)
     if not success then
       if result.message then

lua/orgmode/objects/help.lua

@@ -94,6 +94,10 @@ local helps = {
     { key = 'org_capture_refile', description = 'Save to specific destination' },
     { key = 'org_capture_kill', description = 'Close without saving' },
   },
+  note = {
+    { key = 'org_note_finalize', description = 'Save note and close the window' },
+    { key = 'org_note_kill', description = 'Close without saving' },
+  },
   edit_src = {
     { key = 'org_edit_src_abort', description = 'Abort edit special buffer changes and discard content' },
     { key = 'org_edit_src_save', description = 'Apply changes from the special buffer to the source Org buffer' },
@@ -125,6 +129,11 @@ function Help._get_content_type(opts)
     return 'orgcapture'
   end
 
+  local has_note, is_note = pcall(vim.api.nvim_buf_get_var, 0, 'org_note')
+  if has_note and is_note then
+    return 'orgnote'
+  end
+
   local ft = vim.bo.filetype
   local prepare_func = '_prepare_' .. ft
   if Help[prepare_func] then
@@ -164,6 +173,27 @@ function Help._prepare_orgcapture(mappings, max_height)
   return content, false
 end
 
+function Help._prepare_orgnote(mappings, max_height)
+  local scroll_more_text = ''
+  if (#helps.note + #helps.org) > max_height then
+    scroll_more_text = ' (Scroll down for more)'
+  end
+
+  local content = { string.format(' **Orgmode mappings Note + Org:%s**', scroll_more_text), '', '  __Note__' }
+  for _, item in ipairs(helps.note) do
+    local maps = mappings.note[item.key]
+    if type(maps) == 'table' then
+      maps = table.concat(maps, ', ')
+    end
+
+    table.insert(content, string.format('  `%-12s` - %s', maps, item.description))
+  end
+
+  table.insert(content, '  __Org__')
+
+  return content, false
+end
+
 function Help._prepare_orgagenda(mappings, max_height)
   local scroll_more_text = ''
   if #helps.orgagenda > max_height then

lua/orgmode/org/mappings.lua

@@ -13,6 +13,7 @@ local utils = require('orgmode.utils')
 local ts_org = require('orgmode.treesitter')
 local ts_table = require('orgmode.treesitter.table')
 local EventManager = require('orgmode.events')
+local Promise = require('orgmode.utils.promise')
 local events = EventManager.event
 
 ---@class OrgMappings
@@ -395,13 +396,41 @@ function OrgMappings:_todo_change_state(direction)
     return dispatchEvent()
   end
 
+  local log_note = config.org_log_done == 'note'
+  local log_time = config.org_log_done == 'time'
+  local should_log_time = log_note or log_time
+  local indent = config:get_indent(item.level + 1)
+
+  local get_note = function(note)
+    if note == nil then
+      return
+    end
+
+    for i, line in ipairs(note) do
+      note[i] = indent .. '  ' .. line
+    end
+
+    table.insert(note, 1, ('%s- CLOSING NOTE %s \\\\'):format(indent, Date.now():to_wrapped_string(false)))
+    return note
+  end
+
   local repeater_dates = item:get_repeater_dates()
   if #repeater_dates == 0 then
-    local log_time = config.org_log_done == 'time'
-    if log_time and item:is_done() and not was_done then
+    if should_log_time and item:is_done() and not was_done then
       headline:add_closed_date()
+      item = Files.get_closest_headline()
+
+      if log_note then
+        dispatchEvent()
+        return self.capture.closing_note:open():next(function(note)
+          local valid_note = get_note(note)
+          if valid_note then
+            vim.fn.append(item:get_todo_note_line_number(), valid_note)
+          end
+        end)
+      end
     end
-    if log_time and not item:is_done() and was_done then
+    if should_log_time and not item:is_done() and was_done then
       headline:remove_closed_date()
     end
     return dispatchEvent()
@@ -413,19 +442,35 @@ function OrgMappings:_todo_change_state(direction)
 
   self:_change_todo_state('reset')
   local state_change =
-    string.format('- State "%s" from "%s" [%s]', item.todo_keyword.value, old_state, Date.now():to_string())
-
-  local data = item:add_properties({ LAST_REPEAT = '[' .. Date.now():to_string() .. ']' })
-  if data.is_new then
-    vim.fn.append(data.end_line, data.indent .. state_change)
-    return dispatchEvent()
-  end
-  item = Files.get_closest_headline()
+    string.format('%s- State "%s" from "%s" [%s]', indent, item.todo_keyword.value, old_state, Date.now():to_string())
 
-  if item.properties.valid then
-    vim.fn.append(item.properties.range.end_line, data.indent .. state_change)
-  end
   dispatchEvent()
+  return Promise.resolve()
+    :next(function()
+      if not log_note then
+        return state_change
+      end
+
+      return self.capture.closing_note:open():next(function(closing_note)
+        return get_note(closing_note)
+      end)
+    end)
+    :next(function(note)
+      local data = item:add_properties({ LAST_REPEAT = '[' .. Date.now():to_string() .. ']' })
+      if not note then
+        return
+      end
+
+      if data.is_new then
+        vim.fn.append(data.end_line, note)
+        return
+      end
+      item = Files.get_closest_headline()
+
+      if item.properties.valid then
+        vim.fn.append(item.properties.range.end_line, note)
+      end
+    end)
 end
 
 function OrgMappings:do_promote(whole_subtree)