feat(extmarks): add 'invalidate' property to extmarks

Problem:  No way to have extmarks automatically removed when the range it
          is attached to is deleted.
Solution: Add new 'invalidate' property that will hide a mark when the
          entirety of its range is deleted. When "undo_restore" is set
          to false, delete the mark from the buffer instead.

4 files changed, 19 insertions, 2 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 4430d97fc7..2f9e8228d2 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2707,6 +2707,12 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
                     the extmark end position (if it exists) will be shifted in
                     when new text is inserted (true for right, false for
                     left). Defaults to false.
+                  • undo_restore : Restore the exact position of the mark if
+                    text around the mark was deleted and then restored by
+                    undo. Defaults to true.
+                  • invalidate : boolean that indicates whether to hide the
+                    extmark if the entirety of its range is deleted. If
+                    "undo_restore" is false, the extmark is deleted instead.
                   • priority: a priority value for the highlight group or sign
                     attribute. For example treesitter highlighting uses a
                     value of 100.
@@ -2777,7 +2783,7 @@ nvim_set_decoration_provider({ns_id}, {*opts})
     |nvim_buf_set_extmark()| can be called to add marks on a per-window or
     per-lines basis. Use the `ephemeral` key to only use the mark for the
     current screen redraw (the callback will be called again for the next
-    redraw ).
+    redraw).
 
     Note: this function should not be called often. Rather, the callbacks
     themselves can be used to throttle unneeded callbacks. the `on_start`
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index e32e1aadb6..9ddb1e91b7 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -273,6 +273,9 @@ The following changes to existing APIs or features add new behavior.
 • Extmarks can opt-out of precise undo tracking using the new "undo_restore"
   flag to |nvim_buf_set_extmark()|
 
+• Extmarks can be automatically hidden or removed using the new "invalidate"
+  flag to |nvim_buf_set_extmark()|
+
 • LSP hover and signature help now use Treesitter for highlighting of Markdown
   content.
   Note that syntax highlighting of code examples requires a matching parser
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 691da62f4f..6c6e11a0d3 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -554,6 +554,12 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---                 the extmark end position (if it exists) will be shifted in
 ---                 when new text is inserted (true for right, false for
 ---                 left). Defaults to false.
+---               • undo_restore : Restore the exact position of the mark if
+---                 text around the mark was deleted and then restored by
+---                 undo. Defaults to true.
+---               • invalidate : boolean that indicates whether to hide the
+---                 extmark if the entirety of its range is deleted. If
+---                 "undo_restore" is false, the extmark is deleted instead.
 ---               • priority: a priority value for the highlight group or sign
 ---                 attribute. For example treesitter highlighting uses a
 ---                 value of 100.
@@ -1812,7 +1818,7 @@ function vim.api.nvim_set_current_win(window) end
 --- `nvim_buf_set_extmark()` can be called to add marks on a per-window or
 --- per-lines basis. Use the `ephemeral` key to only use the mark for the
 --- current screen redraw (the callback will be called again for the next
---- redraw ).
+--- redraw).
 --- Note: this function should not be called often. Rather, the callbacks
 --- themselves can be used to throttle unneeded callbacks. the `on_start`
 --- callback can return `false` to disable the provider until the next redraw.
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index 467409505e..f69e5a92c7 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -227,6 +227,7 @@ error('Cannot require a meta file')
 --- @field virt_text_hide? boolean
 --- @field hl_eol? boolean
 --- @field hl_mode? string
+--- @field invalidate? boolean
 --- @field ephemeral? boolean
 --- @field priority? integer
 --- @field right_gravity? boolean
@@ -243,6 +244,7 @@ error('Cannot require a meta file')
 --- @field conceal? string
 --- @field spell? boolean
 --- @field ui_watched? boolean
+--- @field undo_restore? boolean
 
 --- @class vim.api.keyset.user_command
 --- @field addr? any