feat(ui): add backdrop (#1759)

Adds a backdrop for the Mason window. Can be disabled by setting the `ui.backdrop` option:

```lua
require("mason").setup {
  ui = {
    backdrop = 100
  }
}
```

The backdrop is not displayed if `'termguicolors'` is not enabled or if Neovim is transparent.

Co-authored-by: William Boman <william@redwill.se>

5 files changed, 64 insertions, 18 deletions

diff --git a/README.md b/README.md
index 9e33b653..b64d671d 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +269,10 @@ local DEFAULT_SETTINGS = {
         -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
         border = "none",
 
+        ---@since 1.11.0
+        -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
+        backdrop = 60,
+
         ---@since 1.0.0
         -- Width of the window. Accepts:
         -- - Integer greater than 1 for fixed width.
diff --git a/doc/mason.txt b/doc/mason.txt
index e7a2d3bf..dd0eea7e 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -331,6 +331,10 @@ Example:
             -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
             border = "none",
 
+            ---@since 1.11.0
+            -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
+            backdrop = 60,
+
             ---@since 1.0.0
             -- Width of the window. Accepts:
             -- - Integer greater than 1 for fixed width.
diff --git a/lua/mason-core/ui/display.lua b/lua/mason-core/ui/display.lua
index 3b616085..ebd33203 100644
--- a/lua/mason-core/ui/display.lua
+++ b/lua/mason-core/ui/display.lua
@@ -207,11 +207,24 @@ local function create_popup_window_opts(opts, sizes_only)
     return popup_layout
 end
 
+local function create_backdrop_window_opts()
+    return {
+        relative = "editor",
+        width = vim.o.columns,
+        height = vim.o.lines,
+        row = 0,
+        col = 0,
+        style = "minimal",
+        focusable = false,
+        zindex = 44,
+    }
+end
+
 ---@param name string Human readable identifier.
 ---@param filetype string
 function M.new_view_only_win(name, filetype)
     local namespace = vim.api.nvim_create_namespace(("installer_%s"):format(name))
-    local bufnr, renderer, mutate_state, get_state, unsubscribe, win_id, window_mgmt_augroup, autoclose_augroup, registered_keymaps, registered_keybinds, registered_effect_handlers, sticky_cursor
+    local bufnr, backdrop_bufnr, renderer, mutate_state, get_state, unsubscribe, win_id, backdrop_win_id, window_mgmt_augroup, autoclose_augroup, registered_keymaps, registered_keybinds, registered_effect_handlers, sticky_cursor
     local has_initiated = false
     ---@type WindowOpts
     local window_opts = {}
@@ -228,7 +241,7 @@ function M.new_view_only_win(name, filetype)
         virtual_lines = false,
     }, namespace)
 
-    local function delete_win_buf()
+    local function close_window()
         -- We queue the win_buf to be deleted in a schedule call, otherwise when used with folke/which-key (and
         -- set timeoutlen=0) we run into a weird segfault.
         -- It should probably be unnecessary once https://github.com/neovim/neovim/issues/15548 is resolved
@@ -237,10 +250,6 @@ function M.new_view_only_win(name, filetype)
                 log.trace "Deleting window"
                 vim.api.nvim_win_close(win_id, true)
             end
-            if bufnr and vim.api.nvim_buf_is_valid(bufnr) then
-                log.trace "Deleting buffer"
-                vim.api.nvim_buf_delete(bufnr, { force = true })
-            end
         end)
     end
 
@@ -373,6 +382,21 @@ function M.new_view_only_win(name, filetype)
         bufnr = vim.api.nvim_create_buf(false, true)
         win_id = vim.api.nvim_open_win(bufnr, true, create_popup_window_opts(window_opts, false))
 
+        local normal_hl = vim.api.nvim_get_hl and vim.api.nvim_get_hl(0, { name = "Normal" })
+        local is_nvim_transparent = normal_hl and normal_hl.bg == nil
+
+        if settings.current.ui.backdrop ~= 100 and vim.o.termguicolors and not is_nvim_transparent then
+            backdrop_bufnr = vim.api.nvim_create_buf(false, true)
+            backdrop_win_id = vim.api.nvim_open_win(backdrop_bufnr, false, create_backdrop_window_opts())
+
+            vim.wo[backdrop_win_id].winhighlight = "Normal:MasonBackdrop"
+            vim.wo[backdrop_win_id].winblend = settings.current.ui.backdrop
+            vim.bo[backdrop_bufnr].buftype = "nofile"
+            -- https://github.com/folke/lazy.nvim/issues/1399
+            vim.bo[backdrop_bufnr].filetype = "mason_backdrop"
+            vim.bo[backdrop_bufnr].bufhidden = "wipe"
+        end
+
         vim.api.nvim_create_autocmd("CmdLineEnter", {
             buffer = bufnr,
             callback = function()
@@ -440,27 +464,36 @@ function M.new_view_only_win(name, filetype)
             group = window_mgmt_augroup,
             buffer = bufnr,
             callback = function()
-                if vim.api.nvim_win_is_valid(win_id) then
+                if win_id and vim.api.nvim_win_is_valid(win_id) then
                     draw(renderer(get_state()))
                     vim.api.nvim_win_set_config(win_id, create_popup_window_opts(window_opts, true))
                 end
+                if backdrop_win_id and vim.api.nvim_win_is_valid(backdrop_win_id) then
+                    vim.api.nvim_win_set_config(backdrop_win_id, create_backdrop_window_opts())
+                end
+            end,
+        })
+
+        vim.api.nvim_create_autocmd({ "WinClosed" }, {
+            once = true,
+            pattern = tostring(win_id),
+            callback = function()
+                if backdrop_win_id and vim.api.nvim_win_is_valid(backdrop_win_id) then
+                    vim.api.nvim_win_close(backdrop_win_id, true)
+                end
             end,
         })
 
         vim.api.nvim_create_autocmd({ "BufHidden", "BufUnload" }, {
             group = autoclose_augroup,
             buffer = bufnr,
-            callback = function()
-                -- Schedule is done because otherwise the window won't actually close in some cases (for example if
-                -- you're loading another buffer into it)
-                vim.schedule(function()
-                    if vim.api.nvim_win_is_valid(win_id) then
-                        vim.api.nvim_win_close(win_id, true)
-                    end
-                end)
-            end,
+            -- This is for instances where the window remains but the buffer is no longer visible, for example when
+            -- loading another buffer into it (this is basically imitating 'winfixbuf', which was added in 0.10.0).
+            callback = close_window,
         })
 
+        -- This autocmd is responsible for closing the Mason window(s) when the user focuses another window. It
+        -- essentially behaves as WinLeave except it keeps the Mason window(s) open under certain circumstances.
         local win_enter_aucmd
         win_enter_aucmd = vim.api.nvim_create_autocmd({ "WinEnter" }, {
             group = autoclose_augroup,
@@ -469,7 +502,7 @@ function M.new_view_only_win(name, filetype)
                 local buftype = vim.api.nvim_buf_get_option(0, "buftype")
                 -- This allows us to keep the floating window open for things like diagnostic popups, UI inputs á la dressing.nvim, etc.
                 if buftype ~= "prompt" and buftype ~= "nofile" then
-                    delete_win_buf()
+                    close_window()
                     vim.api.nvim_del_autocmd(win_enter_aucmd)
                 end
             end,
@@ -527,7 +560,7 @@ function M.new_view_only_win(name, filetype)
             assert(has_initiated, "Display has not been initiated, cannot close.")
             unsubscribe(true)
             log.fmt_trace("Closing window win_id=%s, bufnr=%s", win_id, bufnr)
-            delete_win_buf()
+            close_window()
             vim.api.nvim_del_augroup_by_id(window_mgmt_augroup)
             vim.api.nvim_del_augroup_by_id(autoclose_augroup)
         end),
diff --git a/lua/mason/settings.lua b/lua/mason/settings.lua
index 56fbcfb9..895dfd0c 100644
--- a/lua/mason/settings.lua
+++ b/lua/mason/settings.lua
@@ -77,6 +77,10 @@ local DEFAULT_SETTINGS = {
         -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
         border = "none",
 
+        ---@since 1.11.0
+        -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
+        backdrop = 60,
+
         ---@since 1.0.0
         -- Width of the window. Accepts:
         -- - Integer greater than 1 for fixed width.
diff --git a/lua/mason/ui/colors.lua b/lua/mason/ui/colors.lua
index cdae3f28..0ac5753a 100644
--- a/lua/mason/ui/colors.lua
+++ b/lua/mason/ui/colors.lua
@@ -1,4 +1,5 @@
 local hl_groups = {
+    MasonBackdrop = { bg = "#000000", default = true },
     MasonNormal = { link = "NormalFloat", default = true },
     MasonHeader = { bold = true, fg = "#222222", bg = "#DCA561", default = true },
     MasonHeaderSecondary = { bold = true, fg = "#222222", bg = "#56B6C2", default = true },