feat: get/set namespace properties #28728

ref https://github.com/neovim/neovim/pull/28432
ref https://github.com/neovim/neovim/issues/28469

3 files changed, 24 insertions, 39 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index bb27ee4269..d91b2d08bf 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -100,6 +100,25 @@ function vim.api.nvim__inspect_cell(grid, row, col) end
 function vim.api.nvim__invalidate_glyph_cache() end
 
 --- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Get the properties for namespace
+---
+--- @param ns_id integer Namespace
+--- @return vim.api.keyset.ns_opts
+function vim.api.nvim__ns_get(ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Set some properties for namespace
+---
+--- @param ns_id integer Namespace
+--- @param opts vim.api.keyset.ns_opts Optional parameters to set:
+---             • wins: a list of windows to be scoped in
+function vim.api.nvim__ns_set(ns_id, opts) end
+
+--- @private
 --- EXPERIMENTAL: this API may change in the future.
 ---
 --- Instruct Nvim to redraw various components.
@@ -144,36 +163,6 @@ function vim.api.nvim__stats() end
 --- @return any
 function vim.api.nvim__unpack(str) end
 
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Scopes a namespace to the a window, so extmarks in the namespace will be
---- active only in the given window.
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer Namespace
---- @return boolean
-function vim.api.nvim__win_add_ns(window, ns_id) end
-
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Unscopes a namespace (un-binds it from the given scope).
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer the namespace to remove
---- @return boolean
-function vim.api.nvim__win_del_ns(window, ns_id) end
-
---- @private
---- EXPERIMENTAL: this API will change in the future.
----
---- Gets the namespace scopes for a given window.
----
---- @param window integer Window handle, or 0 for current window
---- @return integer[]
-function vim.api.nvim__win_get_ns(window) end
-
 --- Adds a highlight to buffer.
 ---
 --- Useful for plugins that dynamically generate highlights to a buffer (like
@@ -686,8 +675,6 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---             • url: A URL to associate with this extmark. In the TUI, the
 ---               OSC 8 control sequence is used to generate a clickable
 ---               hyperlink to this URL.
----             • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
----               extmark. See `nvim__win_add_ns()`
 --- @return integer
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index f7cd92a3b2..2fe5c32faf 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -197,6 +197,9 @@ error('Cannot require a meta file')
 --- @field desc? string
 --- @field replace_keycodes? boolean
 
+--- @class vim.api.keyset.ns_opts
+--- @field wins? any[]
+
 --- @class vim.api.keyset.open_term
 --- @field on_input? function
 --- @field force_crlf? boolean
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index e972ffaa8c..233bc50237 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -31,8 +31,6 @@ M.priorities = {
 --- Indicates priority of highlight
 --- (default: `vim.highlight.priorities.user`)
 --- @field priority? integer
----
---- @field package _scoped? boolean
 
 --- Apply highlight group to range of text.
 ---
@@ -47,7 +45,6 @@ function M.range(bufnr, ns, higroup, start, finish, opts)
   local regtype = opts.regtype or 'v'
   local inclusive = opts.inclusive or false
   local priority = opts.priority or M.priorities.user
-  local scoped = opts._scoped or false
 
   local v_maxcol = vim.v.maxcol
 
@@ -114,7 +111,6 @@ function M.range(bufnr, ns, higroup, start, finish, opts)
       end_col = end_col,
       priority = priority,
       strict = false,
-      scoped = scoped,
     })
   end
 end
@@ -178,19 +174,18 @@ function M.on_yank(opts)
     yank_cancel()
   end
 
-  vim.api.nvim__win_add_ns(winid, yank_ns)
+  vim.api.nvim__ns_set(yank_ns, { wins = { winid } })
   M.range(bufnr, yank_ns, higroup, "'[", "']", {
     regtype = event.regtype,
     inclusive = event.inclusive,
     priority = opts.priority or M.priorities.user,
-    _scoped = true,
   })
 
   yank_cancel = function()
     yank_timer = nil
     yank_cancel = nil
     pcall(vim.api.nvim_buf_clear_namespace, bufnr, yank_ns, 0, -1)
-    pcall(vim.api.nvim__win_del_ns, winid, yank_ns)
+    pcall(vim.api.nvim__ns_set, { wins = {} })
   end
 
   yank_timer = vim.defer_fn(yank_cancel, timeout)