*slot.nvim.txt*	Persistent Adaptive Terminal Dock

Author: newbie <https://github.com/newbie/slot.nvim>
License: MIT


==============================================================================
CONTENTS                                                        *slot-contents*

  1. Introduction .............................. |slot-intro|
  2. Installation .............................. |slot-install|
  3. Configuration ............................. |slot-config|
  4. Usage ..................................... |slot-usage|
  5. API ....................................... |slot-api|
  6. Layout Logic .............................. |slot-layout|
  7. Keymaps ................................... |slot-keymaps|

==============================================================================
INTRODUCTION                                                    *slot-intro*

slot.nvim is a zero-dependency, persistent terminal dock for Neovim. It uses
Neovim's native `vim.fn.termopen()` — no external plugins required.

Think of it like expansion slots in a computer: each command (shell, reasonix,
lazygit, codex, btop, …) gets its own dedicated slot. Toggle a slot to bring
its terminal panel in/out of view; the process keeps running in the background.

Key features:

- **Persistent** — toggle hide/show, terminal process keeps running.
- **Adaptive split** — vertical vsplit on wide screens, horizontal split on
  tall screens; based on the current window, not the tabpage.
- **Main window mode** — when no file is open, the terminal occupies the
  current window directly instead of creating a split.
- **Dynamic commands** — add new tools with two lines of config; keymaps are
  auto-registered from `commands` and `keymaps` tables.
- **Single file** — ~220 lines of Lua.

==============================================================================
INSTALLATION                                                  *slot-install*

Using lazy.nvim >~
    {
      'newbie/slot.nvim',
      url = 'https://github.com/newbie/slot.nvim',
      config = function()
        require('slot').setup({})
      end,
    }

No dependencies required.

==============================================================================
CONFIGURATION                                                  *slot-config*

slot.setup({opts}) accepts the following options:

    require('slot').setup({
      size = {
        horizontal = nil,   -- terminal height in rows (nil = auto)
        vertical   = nil,   -- terminal width in columns (nil = auto)
      },
      commands = {
        reasonix = 'reasonix',
        lazygit  = 'lazygit',
        -- key = command name, value = shell command or function
      },
      keymaps = {
        shell    = { 'n', '<c-t>'        },
        shell_i  = { 'i', '<c-t>'        },
        reasonix = { 'n', '<C-i>'        },
        lazygit  = { 'n', '<leader>gg'   },
        -- key = must match a key in `commands`, value = {mode, lhs}
      },
      debug = false,   -- log layout decisions to :messages
    })

`commands` values can be strings or functions (lazy evaluation).

If `keymaps` is empty or omitted, no keymaps are registered. You can bind
everything manually via the API.

==============================================================================
USAGE                                                          *slot-usage*

                                                                *slot.shell*
slot.shell()~
    Open/close a persistent plain shell. Equivalent to `slot.open(nil)`.

                                                                *slot.open*
slot.open({cmd})~
    Open/close a persistent terminal running the given command. Each unique
    {cmd} gets its own cached terminal instance.

Examples: >
    local S = require('slot')
    S.shell()
    S.open('reasonix')
    S.open('lazygit')
    S.open('btop')
    S.open('yazi')

Inside any terminal, press <C-\><C-\> (Ctrl+\\ twice) to hide it.
The process keeps running in the background.

==============================================================================
API                                                              *slot-api*

slot.setup({opts})                                    *slot.setup*
    Configure and register keymaps. Call once, typically in your plugin
    manager's `config` function.

    Parameters: ~
      {opts} (table)  Configuration table, see |slot-config|.

slot.shell()                                          *slot.shell*
    Toggle a plain shell terminal. Shortcut for `slot.open(nil)`.

slot.open({cmd})                                      *slot.open*
    Toggle a persistent terminal for the given command.

    Parameters: ~
      {cmd} (string|nil)  Shell command to run, or nil for default shell.

==============================================================================
LAYOUT LOGIC                                                  *slot-layout*

The layout is determined automatically based on the current window dimensions:

    Condition                            Result
    -----------------------------------  -------------------------------
    Empty unnamed buffer, not modified   Main window (no split)
    width ≥ 110 and width > height × 2   Right vsplit, 40% width
    Otherwise                             Bottom split, 35% height (min 10)

Splits use `rightbelow`, meaning they open relative to the current window
without disrupting the rest of the tabpage layout.

Set `debug = true` to see layout decisions in `:messages`.

==============================================================================
KEYMAPS                                                        *slot-keymaps*

                                                           *slot-ctrl-backslash*
<C-\><C-\> (terminal mode)~
    Hide the current terminal. Bound automatically in every slot terminal
    buffer. Does not affect TUI programs that use Ctrl+\ for other purposes.

Custom keymaps are defined in the `keymaps` table passed to |slot.setup|.
Each entry is {mode, lhs}. Key names must match entries in `commands`.

The `shell` and `shell_i` keys are special and are not driven by `commands`.

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: