initial commit

Author: StackInTheWild

.stylua.toml

@@ -0,0 +1,5 @@
+column_width = 80
+line_endings = "Unix"
+indent_type = "Spaces"
+indent_width = 4
+quote_style = "AutoPreferDouble"

Makefile

@@ -0,0 +1,5 @@
+.PHONY: test
+
+test:
+	nvim --headless -c "PlenaryBustedDirectory lua/tests/ { minimal_init = './scripts/minimal_init.lua', file_pattern = '*_spec.lua' }" -c "qa"
+

README.md

@@ -0,0 +1,178 @@
+# 🛗 elevator.nvim
+
+**Context-aware keymaps for Neovim.**  
+Think of it as an *elevator*: you move between “floors” (contexts), and your keymaps change automatically depending on where you are.
+
+---
+
+## ✨ Features
+
+- 🔑 Override existing keymaps **only when relevant**
+- 🎯 Contexts are defined with a `match` function and one or more events
+- ⏫ Supports **priority** (decide which context wins when multiple apply)
+- ♻️ Contexts can be added or removed **at runtime**
+- 🧩 Perfect for plugins that need temporary keymaps without conflicts
+
+---
+
+## 📦 Installation
+
+Using **lazy.nvim**:
+
+```lua
+{
+  "StackInTheWild/elevator.nvim",
+  config = function()
+    require("elevator").setup()
+  end,
+}
+```
+
+---
+
+## 🛠️ Usage
+
+### Define a context
+
+```lua
+local elevator = require("elevator")
+
+elevator.add_context("git_conflict", {
+  events = { "CursorMoved", "BufEnter" },
+  priority = 80,
+  match = function()
+    local line = vim.api.nvim_get_current_line()
+    return line:match("^<<<<<<<") or line:match("^=======") or line:match("^>>>>>>>")
+  end,
+  mappings = {
+    n = {
+      ["]x"] = "<cmd>HeadhunterNext<cr>",
+      ["[x"] = "<cmd>HeadhunterPrevious<cr>",
+      ["co"] = "<cmd>HeadhunterTakeHead<cr>",
+      ["ci"] = "<cmd>HeadhunterTakeOrigin<cr>",
+      ["cb"] = "<cmd>HeadhunterTakeBoth<cr>",
+    },
+  },
+})
+```
+
+👉 When your cursor is inside a Git conflict, these keymaps override your normal ones.  
+Move out of the conflict → your original keymaps come back automatically.
+
+---
+
+## 💡 More Examples
+
+### 🐞 Debugging with nvim-dap
+
+```lua
+elevator.add_context("dap", {
+  events = { "User" }, -- listens to User autocommands from nvim-dap
+  priority = 90,
+  match = function()
+    return vim.g.in_debug_session == true
+  end,
+  mappings = {
+    n = {
+      ["<F5>"]  = "<cmd>DapContinue<cr>",
+      ["<F10>"] = "<cmd>DapStepOver<cr>",
+      ["<F11>"] = "<cmd>DapStepInto<cr>",
+      ["<F12>"] = "<cmd>DapStepOut<cr>",
+    },
+  },
+})
+```
+
+➡️ Debug keymaps only exist **while debugging**. No pollution outside.
+
+---
+
+### 📜 Markdown Editing
+
+```lua
+elevator.add_context("markdown", {
+  events = { "BufEnter" },
+  priority = 10,
+  match = function()
+    return vim.bo.filetype == "markdown"
+  end,
+  mappings = {
+    n = {
+      ["<leader>p"] = "<cmd>MarkdownPreviewToggle<cr>",
+    },
+    i = {
+      ["<C-b>"] = "****<Esc>F*i",
+    },
+  },
+})
+```
+
+➡️ Editing Markdown gets special bindings, without touching other filetypes.
+
+---
+
+### 🔍 Telescope Inside Search
+
+```lua
+elevator.add_context("telescope", {
+  events = { "BufEnter" },
+  priority = 100,
+  match = function()
+    return vim.bo.filetype == "TelescopePrompt"
+  end,
+  mappings = {
+    i = {
+      ["<C-j>"] = "move_selection_next",
+      ["<C-k>"] = "move_selection_previous",
+    },
+  },
+})
+```
+
+➡️ Inside Telescope prompt, you override `<C-j>/<C-k>` just for navigation.
+
+---
+
+## ⚙️ Events
+
+`events` are the Neovim autocommands that trigger re-checking a context.  
+Common choices:
+
+- **BufEnter** → whenever you enter a buffer (great for filetype-specific contexts)  
+- **CursorMoved** → whenever you move around (great for “cursor is inside X” checks)  
+- **User** → custom plugin signals. For example:
+  - `nvim-dap` fires `User DapStarted`, `User DapStopped`, `User DapTerminated`
+  - You can listen for these to toggle debug keymaps
+
+👉 Pick the event(s) that best signal “my context might have changed.”
+
+---
+
+## 🔧 API
+
+- `require("elevator").setup(opts?)` → initialize plugin
+- `add_context(name, ctx)` → add a context at runtime
+- `remove_context(name)` → unregister a context
+- `contexts` → table of registered contexts
+- `active` → currently active contexts
+- `current_floor` → the one with highest priority right now
+
+---
+
+## ✅ Why?
+
+Without elevator.nvim:
+- Debug keymaps, Git conflict maps, or plugin shortcuts are always present
+- They pollute your global keymap space
+- They may conflict with your own bindings
+
+With elevator.nvim:
+- Keymaps only exist **when relevant**
+- Conflicts vanish — `<F5>` can mean “run tests” normally and “continue debug” during debugging
+- Your keyboard stays clean and consistent
+
+---
+
+## 📜 License
+
+MIT

lua/elevator/init.lua

@@ -0,0 +1,189 @@
+local M = {}
+
+M.contexts = {}
+M.active = {}
+M.current_floor = nil
+
+-- =========================================================
+-- UTIL
+-- =========================================================
+local function tbl_contains(tbl, val)
+    for _, v in ipairs(tbl) do
+        if v == val then
+            return true
+        end
+    end
+    return false
+end
+
+-- =========================================================
+-- CONTEXT MANAGEMENT
+-- =========================================================
+function M.add_context(name, ctx)
+    M.contexts[name] = ctx
+    local group = vim.api.nvim_create_augroup("Elevator", { clear = false })
+
+    for _, event in ipairs(ctx.events or {}) do
+        vim.api.nvim_create_autocmd(event, {
+            group = group,
+            callback = function()
+                M.check_context(name, ctx)
+            end,
+        })
+    end
+end
+
+function M.remove_context(name)
+    if M.contexts[name] then
+        M.contexts[name] = nil
+        M.active[name] = nil
+        if M.current_floor == name then
+            M.current_floor = nil
+            M.resolve_floor()
+        end
+    end
+end
+
+-- =========================================================
+-- FLOOR RESOLUTION
+-- =========================================================
+function M.check_context(name, context)
+    local is_active = context.match and context.match() or false
+
+    -- Activate keymaps if the context matches and is not already active
+    if is_active and not context._active then
+        for mode, map in pairs(context.mappings or {}) do
+            for lhs, rhs in pairs(map) do
+                vim.keymap.set(
+                    mode,
+                    lhs,
+                    rhs,
+                    { noremap = true, silent = true }
+                )
+            end
+        end
+        context._active = true
+        M.active[name] = context
+        -- update current_floor if higher priority
+        if
+            not M.current_floor
+            or context.priority
+                > (M.contexts[M.current_floor] and M.contexts[M.current_floor].priority or 0)
+        then
+            M.current_floor = name
+        end
+
+    -- Deactivate keymaps if the context no longer matches but was active
+    elseif context._active and not is_active then
+        for mode, map in pairs(context.mappings or {}) do
+            for lhs, _ in pairs(map) do
+                vim.keymap.del(mode, lhs)
+            end
+        end
+        context._active = false
+        M.active[name] = nil
+
+        -- recalc current_floor if needed
+        M.current_floor = nil
+        for floor_name, ctx in pairs(M.active) do
+            if
+                not M.current_floor
+                or ctx.priority > M.active[M.current_floor].priority
+            then
+                M.current_floor = floor_name
+            end
+        end
+    end
+end
+
+function M.resolve_floor()
+    local top, top_prio = nil, -math.huge
+    for name, _ in pairs(M.active) do
+        local ctx = M.contexts[name]
+        if ctx.priority > top_prio then
+            top, top_prio = name, ctx.priority
+        end
+    end
+
+    if top ~= M.current_floor then
+        M.swap_mappings(M.current_floor, top)
+        M.current_floor = top
+    end
+end
+
+-- =========================================================
+-- MAPPINGS
+-- =========================================================
+function M.swap_mappings(old, new)
+    -- restore old
+    if old then
+        local ctx = M.contexts[old]
+        if ctx and ctx.mappings then
+            for mode, maps in pairs(ctx.mappings) do
+                for lhs, _ in pairs(maps) do
+                    pcall(vim.keymap.del, mode, lhs, { buffer = 0 })
+                end
+            end
+        end
+    end
+
+    -- apply new
+    if new then
+        local ctx = M.contexts[new]
+        if ctx and ctx.mappings then
+            for mode, maps in pairs(ctx.mappings) do
+                for lhs, rhs in pairs(maps) do
+                    vim.keymap.set(mode, lhs, rhs, { buffer = 0 })
+                end
+            end
+        end
+    end
+end
+
+-- =========================================================
+-- PUBLIC API
+-- =========================================================
+function M.setup(opts)
+    opts = opts or {}
+    M.contexts = {}
+
+    -- clear previous autocmds
+    vim.api.nvim_create_augroup("Elevator", { clear = true })
+
+    for name, ctx in pairs(opts.contexts or {}) do
+        M.add_context(name, ctx)
+    end
+
+    -- user commands
+    vim.api.nvim_create_user_command("ElevatorAddContext", function(args)
+        local ctx = load("return " .. args.args)()
+        M.add_context(ctx.name, ctx)
+    end, { nargs = 1 })
+
+    vim.api.nvim_create_user_command("ElevatorRemoveContext", function(args)
+        M.remove_context(args.args)
+    end, { nargs = 1 })
+
+    vim.api.nvim_create_user_command("ElevatorFloors", function()
+        print("Current floor: " .. (M.current_floor or "none"))
+        print("Active contexts:")
+        for name, _ in pairs(M.active) do
+            print("  - " .. name)
+        end
+    end, {})
+end
+
+function M.clear()
+    M.contexts = {}
+    M.active = {}
+    M.current_floor = nil
+end
+
+-- =========================================================
+-- STATUSLINE HELPER
+-- =========================================================
+function M.statusline()
+    return M.current_floor and ("[Elevator:" .. M.current_floor .. "]") or ""
+end
+
+return M