Add Lualine integration, update docs (#5)

* Add lualine integration, update README * Recalculate window sizing and positioning each time, to account for terminal window resizing * Allow for editing the name of the current stack * Update documentation - add API docs, update visual assets to encompass new work * Add note on where to find Lualine symbol * Add keymap comments * Resolve issue with preview rendering at certain screen dimensions * Add new gif after preview issue solved
EvWilson · Oct 29, 2024 · c862e1d · c862e1d
1 parent 5a0854d
commit c862e1d
Show file tree

Hide file tree

Showing 9 changed files with 324 additions and 99 deletions.
diff --git a/README.md b/README.md
@@ -7,25 +7,28 @@ Marks not cutting it? Create and manage bookmarks more easily, with an easy to u
 ## Design Goals
 Programming often involves navigating between similar points of interest. Additionally, layers of functionality are often composed together, and thus are often read and edited as part of a stack. `spelunk.nvim` leans into this mental model to allow you to manage bookmarks as related stacks.
 
+`spelunk.nvim` also seeks to take an opinionated approach to configuration. Default keymaps are provided to give the full experience out of the box, as opposed to a build-your-own, API-centric approach. API documentation is provided for those who would prefer to customize their experience.
+
 ## Features
 - Capture and manage bookmarks as stacks of line number locations
 - Opt-in persistence of bookmarks on a per-directory basis
 - Togglable UI, with contextual and rebindable controls
 - Cycle bookmarks via keybind
-- Telescope integration! Fuzzy find over all bookmarks, or those in the current stack
+- Telescope integration - fuzzy find over all bookmarks, or those in the current stack
+- Lualine integration - show the number of bookmarks in the current buffer
 
 ## Requirements
 Neovim (**stable** only) >= 0.10.0
 
 ## Installation/Configuration
 Via [lazy](https://github.com/folke/lazy.nvim):
 ```lua
-require("lazy").setup({
+require('lazy').setup({
 	{
 		'EvWilson/spelunk.nvim',
 		dependencies = {
-			'nvim-lua/plenary.nvim',        -- For window drawing utilities
-			'nvim-telescope/telescope.nvim' -- Optional: for fuzzy search capabilities
+			'nvim-lua/plenary.nvim',         -- For window drawing utilities
+			'nvim-telescope/telescope.nvim', -- Optional: for fuzzy search capabilities
 		},
 		config = function()
 			require('spelunk').setup({
@@ -41,31 +44,145 @@ Here's the default mapping object for reference:
 ```lua
 {
 	base_mappings = {
+		-- Toggle the UI open/closed
 		toggle = '<leader>bt',
+		-- Add a bookmark to the current stack
 		add = '<leader>ba',
+		-- Move to the next bookmark in the stack
 		next_bookmark = '<leader>bn',
+		-- Move to the previous bookmark in the stack
 		prev_bookmark = '<leader>bp',
+		-- Fuzzy-find all bookmarks
 		search_bookmarks = '<leader>bf',
+		-- Fuzzy-find bookmarks in current stack
 		search_current_bookmarks = '<leader>bc'
 	},
 	window_mappings = {
+		-- Move the UI cursor down
 		cursor_down = 'j',
+		-- Move the UI cursor up
 		cursor_up = 'k',
+		-- Move the current bookmark down in the stack
 		bookmark_down = '<C-j>',
+		-- Move the current bookmark up in the stack
 		bookmark_up = '<C-k',
+		-- Jump to the selected bookmark
 		goto_bookmark = '<CR>',
+		-- Delete the selected bookmark
 		delete_bookmark = 'd',
+		-- Navigate to the next stack
 		next_stack = '<Tab>',
+		-- Navigate to the previous stack
 		previous_stack = '<S-Tab>',
+		-- Create a new stack
 		new_stack = 'n',
+		-- Delete the current stack
 		delete_stack = 'D',
+		-- Rename the current stack
+		edit_stack = 'E',
+		-- Close the UI
 		close = 'q',
+		-- Open the help menu
 		help = 'h', -- Not rebindable
 	},
+	-- Flag to enable directory-scoped bookmark persistence
 	enable_persist = false,
+	-- Prefix for the Lualine integration
+	-- (Change this if your terminal emulator lacks emoji support)
+	statusline_prefix = '🔖',
 }
 ```
 
 Check the mentioned help screen to see current keybinds and their use:
 
 ![Help](assets/help.png)
+
+### Lualine integration
+A default integration with [lualine](https://github.com/nvim-lualine/lualine.nvim) is provided to show the number of active bookmarks in the current buffer. You may override the prefix for this string in the config map above. The result of the provided configuration here can be seen in the demo video above, in the bottom left of the screen.
+```lua
+  {
+    'nvim-lualine/lualine.nvim',
+    config = function()
+      require('lualine').setup {
+        sections = {
+          lualine_b = {
+            'spelunk'
+          },
+        },
+      }
+    end
+  },
+
+```
+
+## API Documentation
+Here be dragons! This plugin is designed with the default bindings in mind, so there is potential for misuse here. This list will be non-exhaustive to cover just the most useful available functions, with the least potential for sharp edges.
+
+All functions listed can be called like such from within Neovim Lua code:
+```lua
+require('spelunk').setup(opts)
+```
+
+If there is functionality you'd like to see added or exposed, please feel free to open an issue!
+
+- `setup(config)`
+	- Description: initialize the plugin, should be called to opt-in to default behavior
+	- Parameters:
+		- `config` - `table`: a table in the format given in the above Configuration section
+
+- `toggle_window()`
+	- Description: toggle the UI open/closed
+
+- `close_windows()`
+	- Description: close the UI, if open
+
+- `add_bookmark()`
+	- Description: add the line under the cursor as a bookmark
+
+- `move_cursor(direction)`
+	- Description: move the cursor in the UI (and underlying state) in the provided direction
+	- Parameters:
+		- `direction` - `integer` (1 | -1): direction to move the cursor, 1 is down, -1 is up
+
+- `move_bookmark(direction)`
+	- Description: move the bookmark in the UI (and underlying state) in the provided direction
+	- Parameters:
+		- `direction` - `integer` (1 | -1): direction to move the bookmark, 1 is down, -1 is up
+
+- `goto_selected_bookmark()`
+	- Description: navigate to the bookmark currently under the cursor in the UI
+
+- `delete_selected_bookmark()`
+	- Description: delete the bookmark currently under the cursor in the UI
+
+- `select_and_goto_bookmark(direction)`
+	- Description: move the cursor in the given direction, then go to that bookmark
+	- Parameters:
+		- `direction` - `integer` (1 | -1): direction to move the cursor, 1 is down, -1 is up
+
+- `delete_current_stack()`
+	- Description: delete the currently selected stack
+
+- `edit_current_stack()`
+	- Description: edit the name of the currently selected stack
+
+- `next_stack()`
+	- Description: move to the next stack
+
+- `prev_stack()`
+	- Description: move to the previous stack
+
+- `new_stack()`
+	- Description: create a new stack
+
+- `search_marks()`
+	- Description: fuzzy find over all bookmkarks using the Telescope integration
+
+- `search_current_marks()`
+	- Description: fuzzy find over bookmkarks in the current stack using the Telescope integration
+
+- `statusline()`
+	- Description: get the value that would be set in the status line for the Lualine integration
+	- Returns:
+		- `string`
+
diff --git a/assets/demo.gif b/assets/demo.gif
diff --git a/assets/help.png b/assets/help.png
diff --git a/lua/lualine/components/spelunk.lua b/lua/lualine/components/spelunk.lua
@@ -0,0 +1,20 @@
+local Component = require('lualine.component'):extend()
+
+function Component:init(opts)
+	Component.super:init(opts)
+end
+
+---@return string | nil
+function Component:update_status()
+	if package.loaded['spelunk'] == nil then
+		return
+	end
+	local ok, spelunk = pcall(require, 'spelunk')
+	if not ok then
+		return
+	end
+
+	return spelunk.statusline()
+end
+
+return Component
diff --git a/lua/spelunk/config.lua b/lua/spelunk/config.lua
@@ -20,9 +20,11 @@ local default_config = {
 		previous_stack = '<S-Tab>',
 		new_stack = 'n',
 		delete_stack = 'D',
+		edit_stack = 'E',
 		close = 'q',
 	},
 	enable_persist = false,
+	statusline_prefix = '🔖',
 }
 
 ---@param target table

diff --git a/lua/spelunk/init.lua b/lua/spelunk/init.lua
@@ -5,7 +5,7 @@ local M = {}
 
 ---@type BookmarkStack
 local default_stacks = {
-	{ name = "Default", bookmarks = {} }
+	{ name = 'Default', bookmarks = {} }
 }
 ---@type BookmarkStack
 local bookmark_stacks
@@ -19,6 +19,9 @@ local window_config
 ---@type boolean
 local enable_persist
 
+---@type string
+local statusline_prefix
+
 ---@param tbl table
 local function tbllen(tbl)
 	local count = 0
@@ -39,7 +42,7 @@ local function get_win_update_opts()
 	local lines = {}
 	for i, bookmark in ipairs(bookmark_stacks[current_stack_index].bookmarks) do
 		local prefix = i == cursor_index and '> ' or '  '
-		local display = string.format("%s%s:%d", prefix, vim.fn.fnamemodify(bookmark.file, ':~:.'), bookmark.line)
+		local display = string.format('%s%s:%d', prefix, vim.fn.fnamemodify(bookmark.file, ':~:.'), bookmark.line)
 		table.insert(lines, display)
 	end
 	return {
@@ -170,6 +173,17 @@ function M.delete_current_stack()
 	M.persist()
 end
 
+function M.edit_current_stack()
+	local stack = bookmark_stacks[current_stack_index]
+	if not stack then
+		return
+	end
+	local name = vim.fn.input('[spelunk.nvim] Enter new name for the stack: ', stack.name)
+	bookmark_stacks[current_stack_index].name = name
+	update_window()
+	M.persist()
+end
+
 function M.next_stack()
 	current_stack_index = current_stack_index % #bookmark_stacks + 1
 	cursor_index = 1
@@ -183,8 +197,8 @@ function M.prev_stack()
 end
 
 function M.new_stack()
-	local name = vim.fn.input("[spelunk.nvim] Enter name for new stack: ")
-	if name and name ~= "" then
+	local name = vim.fn.input('[spelunk.nvim] Enter name for new stack: ')
+	if name and name ~= '' then
 		table.insert(bookmark_stacks, { name = name, bookmarks = {} })
 		current_stack_index = #bookmark_stacks
 		cursor_index = 1
@@ -226,6 +240,20 @@ function M.search_current_marks()
 	require('spelunk.telescope').search_stacks('[spelunk.nvim] Current Stack', data, goto_position)
 end
 
+---@return string
+function M.statusline()
+	local count = 0
+	local path = vim.fn.expand('%:p')
+	for _, stack in ipairs(bookmark_stacks) do
+		for _, mark in ipairs(stack.bookmarks) do
+			if mark.file == path then
+				count = count + 1
+			end
+		end
+	end
+	return statusline_prefix .. ' ' .. count
+end
+
 function M.setup(c)
 	local conf = c or {}
 	local cfg = require('spelunk.config')
@@ -248,24 +276,29 @@ function M.setup(c)
 		bookmark_stacks = default_stacks
 	end
 
+	-- Configure the prefix to use for the lualine integration
+	statusline_prefix = conf.statusline_prefix or cfg.get_default('statusline_prefix')
+
 	local set = function(key, cmd, description)
 		vim.keymap.set('n', key, cmd,
 			{ desc = description, noremap = true, silent = true })
 	end
-	set(base_config.toggle, M.toggle_window, '')
-	set(base_config.add, M.add_bookmark, '')
-	set(base_config.next_bookmark, ':lua require("spelunk").select_and_goto_bookmark(1)<CR>', '')
-	set(base_config.prev_bookmark, ':lua require("spelunk").select_and_goto_bookmark(-1)<CR>', '')
+	set(base_config.toggle, M.toggle_window, '[spelunk.nvim] Toggle UI')
+	set(base_config.add, M.add_bookmark, '[spelunk.nvim] Add bookmark')
+	set(base_config.next_bookmark, ':lua require("spelunk").select_and_goto_bookmark(1)<CR>',
+		'[spelunk.nvim] Go to next bookmark')
+	set(base_config.prev_bookmark, ':lua require("spelunk").select_and_goto_bookmark(-1)<CR>',
+		'[spelunk.nvim] Go to previous bookmark')
 
 	-- Register telescope extension, only if telescope itself is loaded already
-	local telescope_loaded = pcall(require, 'telescope')
+	local telescope_loaded, tele = pcall(require, 'telescope')
 	if not telescope_loaded then
 		return
 	end
-	require("telescope").load_extension("spelunk")
-	set(base_config.search_bookmarks, require('telescope').extensions.spelunk.marks,
+	tele.load_extension('spelunk')
+	set(base_config.search_bookmarks, tele.extensions.spelunk.marks,
 		'[spelunk.nvim] Fuzzy find bookmarks')
-	set(base_config.search_current_bookmarks, require('telescope').extensions.spelunk.current_marks,
+	set(base_config.search_current_bookmarks, tele.extensions.spelunk.current_marks,
 		'[spelunk.nvim] Fuzzy find bookmarks in current stack')
 end