From b8a017dfcf02f498baed92a3231858cdd7682b18 Mon Sep 17 00:00:00 2001
From: Grzegorz Milka <grzegorzmilka@gmail.com>
Date: Mon, 8 Jun 2026 09:18:59 +0200
Subject: [PATCH] feat: add labels to surrounds

Add labels to surrounds. This will be useful to plugins that show key
hints. For discussion, see
https://github.com/kylechui/nvim-surround/pull/447.
---
 doc/nvim-surround.txt             |  4 ++++
 lua/nvim-surround/annotations.lua |  2 ++
 lua/nvim-surround/config.lua      | 16 ++++++++++++++++
 3 files changed, 22 insertions(+)

diff --git a/doc/nvim-surround.txt b/doc/nvim-surround.txt
index 30b1a9c..ceadd86 100644
--- a/doc/nvim-surround.txt
+++ b/doc/nvim-surround.txt
@@ -401,6 +401,7 @@ surrounds, for example setting up a `$` surround, but only in bash files:
                 add = { "${", "}" },
                 find = "$%b{}",
                 delete = "^(..)().-(.)()$",
+                label = "${…}",
             },
         },
     })
@@ -540,6 +541,9 @@ containing the following keys:
     are directly used as the replacement pair. For example, when changing HTML
     tag types, only `cst` is needed, instead of `cstt`.
 
+                                         *nvim-surround.setup.surrounds.label*
+    label: ~
+        An optional string that represents the label for the surround.
 
                           *nvim-surround.setup.surrounds.invalid_key_behavior*
 `invalid_key_behavior` is a special key in the `surrounds` table that defines
diff --git a/lua/nvim-surround/annotations.lua b/lua/nvim-surround/annotations.lua
index 86aa088..2936d52 100644
--- a/lua/nvim-surround/annotations.lua
+++ b/lua/nvim-surround/annotations.lua
@@ -29,6 +29,7 @@
 ---@field find find_func
 ---@field delete delete_func
 ---@field change change_table
+---@field label? string
 
 ---@class options
 ---@field surrounds table<string, surround>
@@ -51,6 +52,7 @@
 ---@field find? user_find
 ---@field delete? user_delete
 ---@field change? user_change
+---@field label? string
 
 ---@class user_options
 ---@field surrounds? table<string, false|user_surround>
diff --git a/lua/nvim-surround/config.lua b/lua/nvim-surround/config.lua
index efdb127..2d85deb 100644
--- a/lua/nvim-surround/config.lua
+++ b/lua/nvim-surround/config.lua
@@ -9,6 +9,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a(" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "( ... )",
         },
         [")"] = {
             add = { "(", ")" },
@@ -16,6 +17,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a)" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "(...)",
         },
         ["{"] = {
             add = { "{ ", " }" },
@@ -23,6 +25,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a{" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "{ ... }",
         },
         ["}"] = {
             add = { "{", "}" },
@@ -30,6 +33,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a}" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "{...}",
         },
         ["<"] = {
             add = { "< ", " >" },
@@ -37,6 +41,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a<" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "< ... >",
         },
         [">"] = {
             add = { "<", ">" },
@@ -44,6 +49,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a>" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "<...>",
         },
         ["["] = {
             add = { "[ ", " ]" },
@@ -51,6 +57,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a[" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "[ ... ]",
         },
         ["]"] = {
             add = { "[", "]" },
@@ -58,6 +65,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a]" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "[...]",
         },
         ["'"] = {
             add = { "'", "'" },
@@ -65,6 +73,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a'" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "'...'",
         },
         ['"'] = {
             add = { '"', '"' },
@@ -72,6 +81,7 @@ M.default_opts = {
                 return M.get_selection({ motion = 'a"' })
             end,
             delete = "^(.)().-(.)()$",
+            label = '"..."',
         },
         ["`"] = {
             add = { "`", "`" },
@@ -79,6 +89,7 @@ M.default_opts = {
                 return M.get_selection({ motion = "a`" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "`...`",
         },
         ["i"] = { -- TODO: Add find/delete/change functions
             add = function()
@@ -90,6 +101,7 @@ M.default_opts = {
             end,
             find = function() end,
             delete = function() end,
+            label = "?...?",
         },
         ["t"] = {
             add = function()
@@ -123,6 +135,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "<tag>...</tag>",
         },
         ["T"] = {
             add = function()
@@ -156,6 +169,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "<tag>...</tag>",
         },
         ["f"] = {
             add = function()
@@ -188,6 +202,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "function(...)",
         },
         invalid_key_behavior = {
             -- By default, we ignore control characters for adding/finding because they are more likely typos than
@@ -485,6 +500,7 @@ M.translate_surround = function(char, user_surround)
         find = M.translate_find(user_surround.find),
         delete = M.translate_delete(char, user_surround.delete),
         change = M.translate_change(char, user_surround.change),
+        label = user_surround.label,
     }
 end