runtime(hlyank): add the hlyank package

closes: #16919
related: #16866

Signed-off-by: Christian Brabandt <cb@256bit.org>

Filelist

@@ -805,6 +805,7 @@ RT_ALL =	\
 		runtime/pack/dist/opt/editorconfig/plugin/editorconfig.vim \
 		runtime/pack/dist/opt/helptoc/autoload/helptoc.vim \
 		runtime/pack/dist/opt/helptoc/plugin/helptoc.vim \
+		runtime/pack/dist/opt/hlyank/plugin/hlyank.vim \
 		runtime/pack/dist/opt/justify/plugin/justify.vim \
 		runtime/pack/dist/opt/matchit/plugin/matchit.vim \
 		runtime/pack/dist/opt/matchit/doc/matchit.txt \

runtime/doc/builtin.txt

@@ -4998,6 +4998,8 @@ getregionpos({pos1}, {pos2} [, {opts}])            *getregionpos()*
 		Can also be used as a |method|: >
 			getpos('.')->getregionpos(getpos("'a"))
 <
+		For an example, see the highlight-yank plugin |52.6|
+
 		Return type: list<list<list<number>>>
 
 

runtime/doc/tags

@@ -8247,6 +8247,7 @@ hlexists()	builtin.txt	/*hlexists()*
 hlget()	builtin.txt	/*hlget()*
 hlsearch-variable	eval.txt	/*hlsearch-variable*
 hlset()	builtin.txt	/*hlset()*
+hlyank-install	usr_05.txt	/*hlyank-install*
 holy-grail	index.txt	/*holy-grail*
 home	intro.txt	/*home*
 home-replace	editing.txt	/*home-replace*
@@ -9411,6 +9412,7 @@ package-doc	repeat.txt	/*package-doc*
 package-documentation	repeat.txt	/*package-documentation*
 package-editorconfig	usr_05.txt	/*package-editorconfig*
 package-helptoc	helphelp.txt	/*package-helptoc*
+package-hlyank	usr_05.txt	/*package-hlyank*
 package-justify	usr_25.txt	/*package-justify*
 package-matchit	usr_05.txt	/*package-matchit*
 package-nohlsearch	usr_05.txt	/*package-nohlsearch*

runtime/doc/usr_05.txt

@@ -1,4 +1,4 @@
-*usr_05.txt*	For Vim version 9.1.  Last change: 2025 Jan 11
+*usr_05.txt*	For Vim version 9.1.  Last change: 2025 Mar 18
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -437,7 +437,7 @@ After restarting your Vim, the plugin is active and you can read about it at: >
 	:h editorconfig.txt
 
 
-Adding comment package			*comment-install* *package-comment*
+Adding the comment package		*comment-install* *package-comment*
 
 Load the plugin with this command: >
 	packadd comment
@@ -450,7 +450,7 @@ the package loaded.  Once the package is loaded, read about it at: >
 	:h comment.txt
 
 
-Adding nohlsearch package	*nohlsearch-install* *package-nohlsearch*
+Adding the nohlsearch package	*nohlsearch-install* *package-nohlsearch*
 
 Load the plugin with this command: >
 	packadd nohlsearch
@@ -464,6 +464,29 @@ To disable the effect of the plugin after it has been loaded: >
 	au! nohlsearch
 <
 
+Adding the highlight-yank package	*hlyank-install* *package-hlyank*
+
+Load the plugin with this command: >
+	packadd hlyank
+<
+This package briefly highlights the affected region of the last |yank|
+command. See |52.6| for a simplified implementation using the |getregionpos()|
+function.
+
+The plugin understands the following configuration variables (the settings
+show the default values).
+
+To specify a different highlighting group, use: >
+	:let g:hlyank_hlgroup = 'IncSearch'
+<
+To use a different highlighting duration, use: >
+	:let g:hlyank_duration = 300
+<
+To highlight in visual mode, use: >
+	:let g:hlyank_invisual = v:true
+
+To disable the effect of the plugin after it has been loaded: >
+	au! hlyank
 
 More information about packages can be found here: |packages|.
 

runtime/doc/usr_52.txt

@@ -1,4 +1,4 @@
-*usr_52.txt*	For Vim version 9.1.  Last change: 2025 Mar 12
+*usr_52.txt*	For Vim version 9.1.  Last change: 2025 Mar 17
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -346,11 +346,8 @@ Have a look at the package located at $VIMRUNTIME/pack/dist/opt/comment/
 
 HIGHLIGHT YANK PLUGIN
 
-Here is an example for highlighting the yanked region. It makes use of the
+Vim comes with the highlight-yank plugin, written in Vim9 script
-|getregionpos()| function, available since Vim 9.1.0446.
+|hlyank-install|, here is a simplified implementation: >vim
-
-Copy the following example into a new file and place it into your plugin directory
-and it will be active next time you start Vim.  |add-plugin|: >
 
 	vim9script
 
@@ -375,6 +372,9 @@ and it will be active next time you start Vim.  |add-plugin|: >
 
 	autocmd TextYankPost * HighlightedYank()
 <
+For the complete example, have a look into the package located at
+`$VIMRUNTIME/pack/dist/opt/hlyank/`
+
 ==============================================================================
 
 Next chapter: |usr_90.txt|  Installing Vim

runtime/doc/version9.txt

@@ -1,4 +1,4 @@
-*version9.txt*  For Vim version 9.1.  Last change: 2025 Mar 18
+*version9.txt*  For Vim version 9.1.  Last change: 2025 Mar 19
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -41556,7 +41556,8 @@ Support for protected _new() method
 							*new-other-9.2*
 Other new features ~
 ------------------
-The new plugins |comment-install| and |nohlsearch-install| are included.
+The new packages |package-comment|, |package-nohlsearch| and |package-hlyank|
+are included.
 
 Support for Wayland UI.
 

runtime/pack/dist/opt/hlyank/plugin/hlyank.vim

@@ -0,0 +1,38 @@
+vim9script
+
+# Highlight Yank plugin
+# Last Change: 2025 Mar 17
+
+def HighlightedYank()
+
+  var hlgroup = get(g:, "hlyank_hlgroup", "IncSearch")
+  var duration = get(g:, "hlyank_duration", 300)
+  var in_visual = get(g:, "hlyank_invisual", true)
+
+  if v:event.operator ==? 'y'
+    if !in_visual && visualmode() != null_string
+      visualmode(1)
+      return
+    endif
+    # if clipboard has autoselect (default on linux) exiting from Visual with ESC
+    # generates bogus event and this highlights previous yank
+    if &clipboard =~ 'autoselect' && v:event.regname == "*" && v:event.visual
+      return
+    endif
+    var [beg, end] = [getpos("'["), getpos("']")]
+    var type = v:event.regtype ?? 'v'
+    var pos = getregionpos(beg, end, {type: type, exclusive: false})
+    var m = matchaddpos(hlgroup, pos->mapnew((_, v) => {
+      var col_beg = v[0][2] + v[0][3]
+      var col_end = v[1][2] + v[1][3] + 1
+      return [v[0][1], col_beg, col_end - col_beg]
+    }))
+    var winid = win_getid()
+    timer_start(duration, (_) => m->matchdelete(winid))
+  endif
+enddef
+
+augroup hlyank
+  autocmd!
+  autocmd TextYankPost * HighlightedYank()
+augroup END