From a616272f568a9492580abfd22ab460457ecdbfa3 Mon Sep 17 00:00:00 2001
From: Famiu Haque <famiuhaque@protonmail.com>
Date: Fri, 24 May 2024 15:57:46 +0600
Subject: feat(complete): specify reason for CompleteDone

Problem: `CompleteDone` currently does not specify the reason for why completion was done, which is problematic for completion plugins as they cannot know whether the event was triggered due to the completion being canceled, accepted, or for some other reason.

Solution: Add a `reason` key to `v:event`, which is set by `CompleteDone` to indicate why completion ended.
---
 runtime/doc/autocmd.txt         | 10 ++++++++++
 runtime/doc/news.txt            |  3 +++
 runtime/doc/vvars.txt           |  1 +
 runtime/lua/vim/_meta/vvars.lua |  1 +
 4 files changed, 15 insertions(+)

(limited to 'runtime')

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index bb84966228..ca816851dd 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -466,6 +466,16 @@ CompleteDone			After Insert mode completion is done.  Either
 				CompleteDonePre if you need it.
 				|v:completed_item| gives the completed item.
 
+				Sets these |v:event| keys:
+				    reason	Reason for completion being
+						done. Can be one of:
+						- "accept": completion was
+						  accepted using |complete_CTRL-Y|.
+						- "cancel": completion was cancelled
+						  using |complete_CTRL-E|, pressing
+						  a non-keyword character, or
+						  triggering a new completion.
+
 							*CursorHold*
 CursorHold			When the user doesn't press a key for the time
 				specified with 'updatetime'.  Not triggered
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index f8bc983441..03f6f7f8fd 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -130,6 +130,9 @@ UI
 • TODO
 
 
+• |CompleteDone| now sets the `reason` key in `v:event` which specifies the reason
+  for completion being done.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index de7f23a34d..15d836a83d 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -187,6 +187,7 @@ v:event
 		  changed_window   Is |v:true| if the event fired while
 		                   changing window  (or tab) on |DirChanged|.
 		  status           Job status or exit code, -1 means "unknown". |TermClose|
+		  reason           Reason for completion being done. |CompleteDone|
 
 				*v:exception* *exception-variable*
 v:exception
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 1660d1dd6c..e00402ab3f 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -195,6 +195,7 @@ vim.v.errors = ...
 ---   changed_window   Is `v:true` if the event fired while
 ---                    changing window  (or tab) on `DirChanged`.
 ---   status           Job status or exit code, -1 means "unknown". `TermClose`
+---   reason           Reason for completion being done. `CompleteDone`
 --- @type any
 vim.v.event = ...
 
-- 
cgit