patch 9.1.1835: completion: not possible to style popup borders globally

Problem:  not possible to style popup borders globally
Solution: Add the 'pumborder' option (Girish Palya)

This commit introduces a new global option, 'pumborder' ('pb'), that
allows users to define borders and optional decorations for the
completion popup menu.

```
Defines a border and optional decorations for the popup menu in
completion.  The value is a comma-separated list of keywords.

Border styles (at most one):
"single"singleuse thin box-drawing characters
"double"doubleuse double-line box-drawing characters
"round"rounduse rounded corners
"ascii"asciiuse ASCII characters (-, |, +)
"custom:XXXXXXXX"
    use eight characters given after "custom:",
    in order: top, right, bottom, left,
    topleft, topright, botright, botleft

Additional flags:
"margin"marginadds one-cell spacing inside the left and right border
"shadow"shadowdraws a shadow at the right and bottom edges

Highlight groups:
|hl-PmenuBorder|hl-PmenuBorderused for the border characters
|hl-PmenuShadow|hl-PmenuShadowused for the shadow

Examples: >
  :set pumborder=single
  :set pumborder=double,margin,shadow
  :set pumborder=custom:─│─│┌┐┘└,shadow

Border styles using box-drawing characters ("single", "double",
"round") are only available when |'encoding'| is "utf-8" and
|'ambiwidth'| is "single".  "margin" requires a border style.
See also: |ins-completion-menu|.
```

fixes: vim/vim#18441 (comment)
closes: #18486
closes: #17091

Signed-off-by: Girish Palya <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>

Author: girishji

ci/hlgroups.ignore

@@ -33,6 +33,7 @@ Pmenu
 PmenuSbar
 PmenuSel
 PmenuThumb
+PmenuShadow
 Question
 Scrollbar
 Search

runtime/doc/options.txt

@@ -4683,7 +4683,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 				     =:PmenuSel, k:PmenuMatch,<:PmenuMatchSel,
 				     [:PmenuKind,]:PmenuKindSel,
 				     {:PmenuExtra,}:PmenuExtraSel,
-				     x:PmenuSbar,X:PmenuThumb,*:TabLine,
+				     x:PmenuSbar,X:PmenuThumb,j:PmenuBorder,
+				     H:PmenuShadow,*:TabLine,
 				     #:TabLineSel,_:TabLineFill,!:CursorColumn,
 				     .:CursorLine,o:ColorColumn,q:QuickFixLine,
 				     z:StatusLineTerm,Z:StatusLineTermNC,
@@ -4750,6 +4751,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	|hl-PmenuThumb|	 X  popup menu scrollbar thumb
 	|hl-PmenuMatch|	 k  popup menu matched text
 	|hl-PmenuMatchSel| <  popup menu matched text in selected line
+	|hl-PmenuBorder|   j  popup menu border characters
+	|hl-PmenuShadow|   H  popup menu shadow
 	|hl-PreInsert|	 I  text inserted when "preinsert" is in 'completeopt'
 
 	The display modes are:
@@ -6787,6 +6790,40 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global
 	When on a ":" prompt is used in Ex mode.
 
+						*'pumborder'* *'pb'*
+'pumborder' 'pb'	string	(default "")
+			global
+	Defines a border and optional decorations for the popup menu in
+	completion.  The value is a comma-separated list of keywords.
+
+	Border styles (at most one):
+	"single"	use thin box-drawing characters
+	"double"	use double-line box-drawing characters
+	"round"		use rounded corners
+	"ascii"		use ASCII characters (-, |, +)
+	"custom:X;X;X;X;X;X;X;X"
+			use eight characters separated by semicolons, in the
+			order: top, right, bottom, left,
+			topleft, topright, botright, botleft
+
+	Additional flags:
+	"margin"	adds one-cell spacing inside the left and right border
+	"shadow"	draws a shadow at the right and bottom edges
+
+	Highlight groups:
+	|hl-PmenuBorder|	used for the border characters
+	|hl-PmenuShadow|	used for the shadow
+
+	Examples: >
+		:set pumborder=single
+		:set pumborder=double,margin,shadow
+		:set pumborder=custom:─;│;─;│;┌;┐;┘;└,shadow
+<
+	Border styles using box-drawing characters ("single", "double",
+	"round") are only available when |'encoding'| is "utf-8" and
+	|'ambiwidth'| is "single".  "margin" requires a border style.
+	See also: |ins-completion-menu|.
+
 						*'pumheight'* *'ph'*
 'pumheight' 'ph'	number	(default 0)
 			global

runtime/doc/syntax.txt

@@ -6024,6 +6024,11 @@ PmenuMatch	Popup menu: Matched text in normal item. Applied in
 							*hl-PmenuMatchSel*
 PmenuMatchSel	Popup menu: Matched text in selected item. Applied in
 		combination with |hl-PmenuSel|.
+							*hl-PmenuBorder*
+PmenuBorder	Popup menu: Border characters.
+		Linked to |hl-Pmenu| by default.
+							*hl-PmenuShadow*
+PmenuShadow	Popup menu: Used for shadow.
 							*hl-ComplMatchIns*
 ComplMatchIns	Matched text of the currently inserted completion.
 							*hl-PreInsert*

runtime/doc/tags

@@ -858,6 +858,7 @@ $quote	eval.txt	/*$quote*
 'patchexpr'	options.txt	/*'patchexpr'*
 'patchmode'	options.txt	/*'patchmode'*
 'path'	options.txt	/*'path'*
+'pb'	options.txt	/*'pb'*
 'pdev'	options.txt	/*'pdev'*
 'penc'	options.txt	/*'penc'*
 'perldll'	options.txt	/*'perldll'*
@@ -887,6 +888,7 @@ $quote	eval.txt	/*$quote*
 'printoptions'	options.txt	/*'printoptions'*
 'prompt'	options.txt	/*'prompt'*
 'pt'	options.txt	/*'pt'*
+'pumborder'	options.txt	/*'pumborder'*
 'pumheight'	options.txt	/*'pumheight'*
 'pummaxwidth'	options.txt	/*'pummaxwidth'*
 'pumwidth'	options.txt	/*'pumwidth'*
@@ -8384,6 +8386,7 @@ hl-MsgArea	syntax.txt	/*hl-MsgArea*
 hl-NonText	syntax.txt	/*hl-NonText*
 hl-Normal	syntax.txt	/*hl-Normal*
 hl-Pmenu	syntax.txt	/*hl-Pmenu*
+hl-PmenuBorder	syntax.txt	/*hl-PmenuBorder*
 hl-PmenuExtra	syntax.txt	/*hl-PmenuExtra*
 hl-PmenuExtraSel	syntax.txt	/*hl-PmenuExtraSel*
 hl-PmenuKind	syntax.txt	/*hl-PmenuKind*
@@ -8392,6 +8395,7 @@ hl-PmenuMatch	syntax.txt	/*hl-PmenuMatch*
 hl-PmenuMatchSel	syntax.txt	/*hl-PmenuMatchSel*
 hl-PmenuSbar	syntax.txt	/*hl-PmenuSbar*
 hl-PmenuSel	syntax.txt	/*hl-PmenuSel*
+hl-PmenuShadow	syntax.txt	/*hl-PmenuShadow*
 hl-PmenuThumb	syntax.txt	/*hl-PmenuThumb*
 hl-PopupNotification	syntax.txt	/*hl-PopupNotification*
 hl-PopupSelected	syntax.txt	/*hl-PopupSelected*

runtime/doc/version9.txt

@@ -41838,9 +41838,11 @@ Highlighting: ~
 |hl-ComplMatchIns|	matched text of the currently inserted completion
 |hl-DiffTextAdd|	added text within a changed line
 |hl-MsgArea|		highlighting of the Command-line and messages area
+|hl-PmenuBorder|	Popup menu: highlighting of popup border characters
 |hl-PmenuMatch|		Popup menu: highlighting of matched text
 |hl-PmenuMatchSel|	Popup menu: highlighting of matched text in selected
 			line
+|hl-PmenuShadow|	Popup menu: highlighting of the popup shadow
 |hl-PreInsert|		highlighting for completion preinserted text
 |hl-TabPanel|		|tabpanel|: not active tab page label
 |hl-TabPanelFill|	|tabpanel|: filler space
@@ -41880,6 +41882,7 @@ Options: ~
 'lhistory'		Size of the location list stack |quickfix-stack|
 'maxsearchcount'	Set the maximum number for search-stat |shm-S|
 'messagesopt'		configure |:messages| and |hit-enter| prompt
+'pumborder'		define popup border and decorations
 'pummaxwidth'		maximum width for the completion popup menu
 'showtabpanel'		When to show the |tabpanel|
 'tabclose'		Which tab page to focus after closing a tab page

runtime/optwin.vim

@@ -1,7 +1,7 @@
 " These commands create the option window.
 "
 " Maintainer:	The Vim Project <https://github.com/vim/vim>
-" Last Change:	2025 Sep 30
+" Last Change:	2025 Oct 07
 " Former Maintainer:	Bram Moolenaar <[email protected]>
 
 " If there already is an option window, jump to that one.
@@ -900,6 +900,8 @@ if has("insert_expand")
   call <SID>OptionG("pw", &pw)
   call <SID>AddOption("pummaxwidth", gettext("maximum width of the popup menu"))
   call <SID>OptionG("pmw", &pmw)
+  call <SID>AddOption("pumborder", gettext("popup border style"))
+  call <SID>OptionG("pb", &pb)
   call <SID>AddOption("completefunc", gettext("user defined function for Insert mode completion"))
   call append("$", "\t" .. s:local_to_buffer)
   call <SID>OptionL("cfu")