Skip to content

2025-10-07: Add reusable backdrop utility and enhance scooter terminal #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
john-mutuma merged 2 commits into from
Oct 7, 2025
Merged

2025-10-07: Add reusable backdrop utility and enhance scooter terminal #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f2add5e
feat(windows): add reusable backdrop utility and integrate with scooter
Oct 7, 2025
f4e2d75
docs: initialize AGENTS.md with backdrop utility project history
Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Project History

Brief, concise history of AI-assisted development tasks.

---

## 2025-10-07: Backdrop Utility & Scooter Terminal

**PR #64** | `continous-development` → `develop`

- Created reusable `create_backdrop()` in `windows.lua`
- Refactored `with_win_backdrop()` (eliminated ~35 lines duplication)
- Integrated backdrop with scooter terminal (on_open/on_close lifecycle)
- Config updates: scooter winblend=12, width=175; lazygit scale 0.85→0.8

**Files:** `windows.lua`, `scooter.lua`, `lazygit.lua`, `scooter.config.toml`

---
2 changes: 1 addition & 1 deletion nvim/lua/nairovim/plugins/lazygit.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ return {
local window_utils = require("nairovim.utils.windows")

g.lazygit_floating_window_winblend = 4 -- transparency of floating window
g.lazygit_floating_window_scaling_factor = 0.85 -- scaling factor for floating window
g.lazygit_floating_window_scaling_factor = 0.8 -- scaling factor for floating window

-- Keymaps for LazyGit
local common_utils = require("nairovim.utils.common")
Expand Down
27 changes: 27 additions & 0 deletions nvim/lua/nairovim/plugins/scooter.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
local M = {}
local Terminal = require("toggleterm.terminal").Terminal
local window_utils = require("nairovim.utils.windows")
local scooter_term = nil
local scooter_backdrop = nil

--- Open existing scooter terminal if one is available, otherwise create a new one
local open_scooter = function()
Expand All @@ -9,11 +11,25 @@ local open_scooter = function()
cmd = "scooter",
direction = "float",
close_on_exit = true,
display_name = "Find and Replace",
on_open = function()
-- Create backdrop with z-index lower than terminal (default: 40)
scooter_backdrop = window_utils.create_backdrop("ScooterBackdrop", 60, 39)
end,
on_close = function()
-- Clean up backdrop when terminal closes
if scooter_backdrop then
scooter_backdrop.cleanup()
scooter_backdrop = nil
end
end,
highlights = {
FloatBorder = { link = "FloatBorder" },
},
float_opts = {
border = "rounded",
winblend = 12,
width = 175,
},
on_exit = function()
scooter_term = nil
Expand Down Expand Up @@ -50,6 +66,17 @@ _G.OpenScooterSearchText = function(search_text)
cmd = "scooter --search-text " .. escaped_text,
direction = "float",
close_on_exit = true,
on_open = function()
-- Create backdrop with z-index lower than terminal (default: 40)
scooter_backdrop = window_utils.create_backdrop("ScooterBackdrop", 60, 39)
end,
on_close = function()
-- Clean up backdrop when terminal closes
if scooter_backdrop then
scooter_backdrop.cleanup()
scooter_backdrop = nil
end
end,
on_exit = function()
scooter_term = nil
end,
Expand Down
91 changes: 56 additions & 35 deletions nvim/lua/nairovim/utils/windows.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,60 @@
local vim = vim
local M = {}

-- Creates a semi-transparent backdrop for popup windows
----------------------------------------------------------------------
-- 1. with_win_backdrop: Add a semi-transparent backdrop to a window
-- 1. create_backdrop: Create a backdrop window
----------------------------------------------------------------------
--- Creates a backdrop window with the specified styling.
--- @param backdrop_name (string) The highlight group name for the backdrop.
--- @param blend (number) The transparency level (0-100).
--- @param zindex (number) The z-index for the backdrop window.
--- @return table A table containing backdrop_bufnr, backdrop_winid, and cleanup function.
--- @usage
--- local backdrop = require('nairovim.utils.windows').create_backdrop('MyBackdrop', 60, 39)
--- -- Later, call backdrop.cleanup() to remove the backdrop
M.create_backdrop = function(backdrop_name, blend, zindex)
-- Set highlight for the backdrop if not already set
if not vim.api.nvim_get_hl(0, { name = backdrop_name, link = false }) then
vim.api.nvim_set_hl(0, backdrop_name, { bg = "#000000", default = true })
end

-- Create a scratch buffer for the backdrop
local backdrop_bufnr = vim.api.nvim_create_buf(false, true)
local backdrop_winid = vim.api.nvim_open_win(backdrop_bufnr, false, {
relative = "editor",
row = 0,
col = 0,
width = vim.o.columns,
height = vim.o.lines,
focusable = false,
style = "minimal",
zindex = zindex,
})

-- Style the backdrop window
vim.wo[backdrop_winid].winhighlight = "Normal:" .. backdrop_name
vim.wo[backdrop_winid].winblend = blend
vim.bo[backdrop_bufnr].buftype = "nofile"

-- Cleanup function to close backdrop window and buffer
local function cleanup()
if vim.api.nvim_win_is_valid(backdrop_winid) then
vim.api.nvim_win_close(backdrop_winid, true)
end
if vim.api.nvim_buf_is_valid(backdrop_bufnr) then
vim.api.nvim_buf_delete(backdrop_bufnr, { force = true })
end
end

return {
backdrop_bufnr = backdrop_bufnr,
backdrop_winid = backdrop_winid,
cleanup = cleanup,
}
end

----------------------------------------------------------------------
-- 2. with_win_backdrop: Add a semi-transparent backdrop to a window
----------------------------------------------------------------------
---- Adds a semi-transparent backdrop behind a target floating window.
--- This function creates a scratch buffer and opens it as a floating window
Expand All @@ -24,11 +75,6 @@ function M.with_win_backdrop(target_win)
local backdrop_name = target_win .. "_backdrop"
local augroup_name = "WinBackdrop_" .. target_win

-- Set highlight for the backdrop once (if not already set)
if not vim.api.nvim_get_hl(0, { name = backdrop_name, link = false }) then
vim.api.nvim_set_hl(0, backdrop_name, { bg = "#000000", default = true })
end

-- Create or clear the augroup for this target_win
local group = vim.api.nvim_create_augroup(augroup_name, { clear = true })

Expand All @@ -38,40 +84,15 @@ function M.with_win_backdrop(target_win)
callback = function(ctx)
local ref_bufnr = ctx.buf

-- Create a scratch buffer for the backdrop
local backdrop_bufnr = vim.api.nvim_create_buf(false, true)
local backdrop_winid = vim.api.nvim_open_win(backdrop_bufnr, false, {
relative = "editor",
row = 0,
col = 0,
width = vim.o.columns,
height = vim.o.lines,
focusable = false,
style = "minimal",
zindex = default_zIndex - 1, -- ensure it's below the reference window
})

-- Style the backdrop window
vim.wo[backdrop_winid].winhighlight = "Normal:" .. backdrop_name
vim.wo[backdrop_winid].winblend = blend
vim.bo[backdrop_bufnr].buftype = "nofile"

-- Cleanup function to close backdrop window and buffer
local function cleanup()
if vim.api.nvim_win_is_valid(backdrop_winid) then
vim.api.nvim_win_close(backdrop_winid, true)
end
if vim.api.nvim_buf_is_valid(backdrop_bufnr) then
vim.api.nvim_buf_delete(backdrop_bufnr, { force = true })
end
end
-- Create backdrop using the reusable function
local backdrop = M.create_backdrop(backdrop_name, blend, default_zIndex - 1)

-- Close backdrop when the reference buffer is closed or left
vim.api.nvim_create_autocmd({ "WinClosed", "BufLeave" }, {
once = true,
buffer = ref_bufnr,
group = group,
callback = cleanup,
callback = backdrop.cleanup,
})
end,
})
Expand Down
8 changes: 4 additions & 4 deletions scooter.config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
[editor_open]
command = "nvim %file +%line"
# [editor_open]
# command = "nvim"

[preview]
syntax_highlighting = true
syntax_highlighting_theme = "Catppuccin Macchiato"
# syntax_highlighting_theme = "Catppuccin Macchiato"
# syntax_highlighting_theme = "Catppuccin Mocha"
# syntax_highlighting_theme = "Catppuccin Frappe"
# syntax_highlighting_theme = "Catppuccin Latte"
syntax_highlighting_theme = "Catppuccin Macchiato"