feat: add wezterm navigation (#18)

This PR attempts to add wezterm navigation to the plugin in addition to tmux navigation. And also introduces

- a general interface to integrate different multiplexers. This interface needs two methods: `:zoomed()` and `:navigate()`
- `mux` config option to automatically detects and use the correct multiplexer implementation. It defaults to `auto` which uses the default priority/fallback behavior, which is tmux, followed by wezterm. If nothing is found, it'll fallback to neovim window navigation. It can also be set to lua class which implements general interface.

Author: marty-oehme

README.md

@@ -1,8 +1,10 @@
 <h1 align='center'>Navigator.nvim</h1>
-<p align="center"><sup>✨ Smoothly navigate between splits and panes ✨</sup></p>
+<p align="center"><sup>✨ Smoothly navigate between neovim and multiplexer ✨</sup></p>
 
 ![Navigator](https://user-images.githubusercontent.com/24727447/157040356-1f44323a-c7b6-4955-8207-5e6cade08c9e.gif "Navigating to the moon")
 
+This plugin provides a set of [functions](#lua-api) and [commands](#commands) that allows you to seemlessly navigate between neovim and different [terminal multiplexers](#multiplexers).
+
 ### 🚀 Installation
 
 #### Neovim
@@ -27,68 +29,74 @@ Plug 'numToStr/Navigator.nvim'
 lua require('Navigator').setup()
 ```
 
-#### Tmux
-
-This plugin doesn't provides any configuration for `tmux`. You can read [here](https://github.com/christoomey/vim-tmux-navigator#tmux) to how to setup your tmux.
-
-Or, you can use [tmux-tilish](https://github.com/jabirali/tmux-tilish) which is an excellent tmux plugin.
-
 ### ⚒️ Setup
 
+#### Neovim
+
 ```lua
--- Configuration
 require('Navigator').setup()
+```
+
+- Keybindings
+
+> **Note** - This plugin doesn't provide any keybindings by default, feel free to use (and modify) the following or create your own keybindings.
 
--- Keybindings
-vim.keymap.set('n', "<A-h>", '<CMD>NavigatorLeft<CR>')
-vim.keymap.set('n', "<A-l>", '<CMD>NavigatorRight<CR>')
-vim.keymap.set('n', "<A-k>", '<CMD>NavigatorUp<CR>')
-vim.keymap.set('n', "<A-j>", '<CMD>NavigatorDown<CR>')
-vim.keymap.set('n', "<A-p>", '<CMD>NavigatorPrevious<CR>')
+```lua
+vim.keymap.set('n', '<A-h>', '<CMD>NavigatorLeft<CR>')
+vim.keymap.set('n', '<A-l>', '<CMD>NavigatorRight<CR>')
+vim.keymap.set('n', '<A-k>', '<CMD>NavigatorUp<CR>')
+vim.keymap.set('n', '<A-j>', '<CMD>NavigatorDown<CR>')
+vim.keymap.set('n', '<A-p>', '<CMD>NavigatorPrevious<CR>')
 ```
 
+#### Multiplexer(s)
+
+> **Note** - This plugin doesn't provide any configuration for multiplexers, feel free to use (and modify) the snippet for multiplexer of your choice by following the links below.
+
+- [Tmux](https://github.com/numToStr/Navigator.nvim/wiki/Tmux-Integration)
+- [Wezterm](https://github.com/numToStr/Navigator.nvim/wiki/WezTerm-Integration)
+
 #### Configuration (optional)
 
 Following options can be given when calling `setup({config})`. Below is the default configuration
 
 ```lua
 {
-    -- When you want to save the modified buffers when moving to tmux
+    -- Save modified buffer(s) when moving to mux
     -- nil - Don't save (default)
     -- 'current' - Only save the current modified buffer
     -- 'all' - Save all the buffers
     auto_save = nil,
 
-    -- Disable navigation when tmux is zoomed in
+    -- Disable navigation when the current mux pane is zoomed in
     disable_on_zoom = false
+
+    -- Multiplexer to use
+    -- 'auto' - Chooses mux based on priority (default)
+    -- table - Custom mux to use
+    mux = 'auto'
 }
 ```
 
+> Read: [How to create and integrate custom multiplexer?](https://github.com/numToStr/Navigator.nvim/wiki/Custom-Multiplexer)
+
 ### 🔥 Usage
 
 #### Commands
 
 - `NavigatorLeft` - Go to left split/pane
-
 - `NavigatorRight` - Go to right split/pane
-
 - `NavigatorUp` - Go to upper split/pane
-
 - `NavigatorDown` - Go to down split/pane
-
 - `NavigatorPrevious` - Go to previous split/pane
 
 #### Lua API
 
 ```lua
 require('Navigator').left()
-
 require('Navigator').right()
-
 require('Navigator').up()
-
 require('Navigator').down()
-
 require('Navigator').previous()
 ```
 

lua/Navigator/mux/tmux.lua

@@ -0,0 +1,44 @@
+---@class Tmux: Vi
+---@field private pane string
+---@field private direction table<Direction, string>
+---@field private execute fun(arg: string): unknown
+local Tmux = require('Navigator.mux.vi'):new()
+
+---Creates a new Tmux navigator instance
+---@return Tmux
+function Tmux:new()
+    local instance = os.getenv('TMUX')
+    local pane = os.getenv('TMUX_PANE')
+
+    assert(instance and pane, '[Navigator] Tmux is not running!')
+
+    local socket = string.match(instance, '^(.-),')
+    local cmd = instance:find('^.*tmate') and 'tmate' or 'tmux'
+
+    ---@type Tmux
+    local state = {
+        pane = pane,
+        execute = function(arg)
+            return require('Navigator.utils').execute(string.format('%s -S %s %s', cmd, socket, arg))
+        end,
+        direction = { p = 'l', h = 'L', k = 'U', l = 'R', j = 'D' },
+    }
+    self.__index = self
+    return setmetatable(state, self)
+end
+
+---Checks if tmux is zoomed in
+---@return boolean
+function Tmux:zoomed()
+    return self.execute("display-message -p '#{window_zoomed_flag}'") == '1'
+end
+
+---Switch pane in tmux
+---@param direction Direction
+---@return Tmux
+function Tmux:navigate(direction)
+    self.execute(string.format("select-pane -t '%s' -%s", self.pane, self.direction[direction]))
+    return self
+end
+
+return Tmux

lua/Navigator/mux/vi.lua

@@ -0,0 +1,27 @@
+---@class Vi
+local Vi = {}
+
+---Creates new Neovim navigator instance
+---NOTE: This can be used as a base for other navigators
+---@return Vi
+function Vi:new()
+    self.__index = self
+    return setmetatable({}, self)
+end
+
+---Checks whether neovim is maximized
+---NOTE: This is only useful for `tmux`, for other mux(s) return false would suffice
+---@return boolean
+function Vi.zoomed()
+    return false
+end
+
+---Navigate inside neovim
+---@param direction Direction
+---@return Vi
+function Vi:navigate(direction)
+    vim.api.nvim_command('wincmd ' .. direction)
+    return self
+end
+
+return Vi

lua/Navigator/mux/wezterm.lua

@@ -0,0 +1,33 @@
+---@class WezTerm: Vi
+---@field private direction table<Direction, string>
+---@field private execute fun(arg: string): unknown
+local WezTerm = require('Navigator.mux.vi'):new()
+
+---Creates a new WezTerm navigator instance
+---@return WezTerm
+function WezTerm:new()
+    assert(os.getenv('TERM_PROGRAM') == 'WezTerm', '[Navigator] WezTerm is not running!')
+
+    local U = require('Navigator.utils')
+    local suffix = U.suffix()
+
+    ---@type WezTerm
+    local state = {
+        execute = function(arg)
+            return U.execute(string.format('wezterm%s cli %s', suffix, arg))
+        end,
+        direction = { p = 'Prev', h = 'Left', k = 'Up', l = 'Right', j = 'Down' },
+    }
+    self.__index = self
+    return setmetatable(state, self)
+end
+
+---Switch pane in wezterm
+---@param direction Direction
+---@return WezTerm
+function WezTerm:navigate(direction)
+    self.execute(string.format('activate-pane-direction %s', self.direction[direction]))
+    return self
+end
+
+return WezTerm

lua/Navigator/navigate.lua

@@ -1,34 +1,57 @@
-local tmux = require('Navigator.tmux')
 local A = vim.api
 local cmd = A.nvim_command
 
+---Loads mux
+---@return Vi
+local function load_mux()
+    local ok_tmux, tmux = pcall(function()
+        return require('Navigator.mux.tmux'):new()
+    end)
+    if ok_tmux then
+        return tmux
+    end
+    local ok_wezterm, wezterm = pcall(function()
+        return require('Navigator.mux.wezterm'):new()
+    end)
+    if ok_wezterm then
+        return wezterm
+    end
+    return require('Navigator.mux.vi'):new()
+end
+
+---@alias Direction 'p'|'h'|'k'|'l'|'j'
+
 ---@class Config
----@field auto_save '"current"'|'"all"' When you want to save the modified buffers when moving to tmux
----@field disable_on_zoom boolean Disable navigation when tmux is zoomed in
+---@field auto_save? '"current"'|'"all"' Save modified buffer(s) when moving to mux
+---@field disable_on_zoom boolean Disable navigation when the current mux pane is zoomed in
+---@field mux 'auto'|Vi Multiplexer to use
 
----Just some state and defaults
+---State and defaults
 ---@class Nav
 ---@field last_pane boolean
----@field config Config
+---@field config? Config
 local N = {
     last_pane = false,
     config = nil,
 }
 
-local function wincmd(way)
-    cmd(('wincmd %s'):format(way))
-end
-
 ---For setting up the plugin with the user provided options
 ---@param opts Config
 function N.setup(opts)
-    N.config = {
+    local config = {
         disable_on_zoom = false,
         auto_save = nil,
+        mux = 'auto',
     }
 
     if opts ~= nil then
-        N.config = vim.tbl_extend('keep', opts, N.config)
+        N.config = vim.tbl_extend('keep', opts, config)
+    else
+        N.config = config
+    end
+
+    if N.config.mux == 'auto' then
+        N.config.mux = load_mux()
     end
 
     A.nvim_create_autocmd('WinEnter', {
@@ -39,45 +62,37 @@ function N.setup(opts)
     })
 end
 
----Checks whether we need to move to the nearby tmux pane
+---Checks whether we need to move to the nearby mux pane
 ---@param at_edge boolean
 ---@return boolean
-function N.back_to_tmux(at_edge)
-    if N.config.disable_on_zoom and tmux.is_zoomed() then
+function N.back_to_mux(at_edge)
+    if N.config.disable_on_zoom and N.config.mux:zoomed() then
         return false
     end
-
     return N.last_pane or at_edge
 end
 
----For smoothly navigating through neovim splits and tmux panes
+---For smoothly navigating through neovim splits and mux panes
 ---@param direction string
 function N.navigate(direction)
-    -- For moments when you have this plugin installed
-    -- but for some reason you didn't bother to install tmux
-    if not tmux.is_tmux then
-        return wincmd(direction)
-    end
-
     -- window id before navigation
     local cur_win = A.nvim_get_current_win()
-    local tmux_last_pane = direction == 'p' and N.last_pane
 
-    if not tmux_last_pane then
-        wincmd(direction)
+    local mux_last_pane = direction == 'p' and N.last_pane
+    if not mux_last_pane then
+        cmd('wincmd ' .. direction)
     end
 
     -- After navigation, if the old window and new window matches
     local at_edge = cur_win == A.nvim_get_current_win()
 
     -- then we can assume that we hit the edge
-    -- there is tmux pane besided the edge
-    -- So we can navigate to the tmux pane
-    if N.back_to_tmux(at_edge) then
-        tmux.change_pane(direction)
+    -- there is mux pane besided the edge
+    -- So we can navigate to the mux pane
+    if N.back_to_mux(at_edge) then
+        N.config.mux:navigate(direction)
 
         local save = N.config.auto_save
-
         if save == 'current' then
             cmd('update')
         elseif save == 'all' then