rename: QQdock.nvim → slot.nvim

Module: require('QQdock') → require('slot')
Class:  QdockTerm → SlotTerm
Plugin: plugin/QQdock.lua → plugin/slot.lua
Help:   :help QQdock → :help slot
Debug:  'QQdock:' prefix → 'slot:'

.gitignore

@@ -1 +1,2 @@
 AGENTS.md
+reasonix.toml

.luarc.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
+  "runtime.version": "LuaJIT",
+  "runtime.path": [
+    "lua/?.lua",
+    "lua/?/init.lua"
+  ],
+  "diagnostics.globals": [
+    "vim"
+  ],
+  "workspace.checkThirdParty": false,
+  "workspace.library": [
+    "$VIMRUNTIME/lua",
+    "$VIMRUNTIME"
+  ]
+}

README.md

@@ -1,7 +1,9 @@
-# QQdock.nvim
+# slot.nvim
 
 持久化自适应终端 Dock — 无外部依赖，基于 Neovim 原生终端。
 
+像电脑扩展槽一样：每个命令（shell、reasonix、lazygit、codex…）占用一个 slot，toggle 切换显隐，进程不中断。
+
 横屏自动右侧分屏，竖屏自动下方分屏。没打开文件时直接占用主窗口。`<C-\><C-\>` 隐藏，对话还在。
 
 ## 安装
@@ -9,10 +11,10 @@
 ```lua
 -- lazy.nvim
 {
-  'newbie/QQdock.nvim',
-  url = 'https://github.com/newbie/QQdock.nvim',
+  'newbie/slot.nvim',
+  url = 'https://github.com/newbie/slot.nvim',
   config = function()
-    require('QQdock').setup({
+    require('slot').setup({
       size = {
         horizontal = 10,   -- 竖屏下方终端高度（行数，nil = 自动）
         vertical   = 40,   -- 横屏右侧终端宽度（列数，nil = 自动）
@@ -37,7 +39,7 @@
 添加新工具只需在 `commands` 和 `keymaps` 各加一行，键名一致即可：
 
 ```lua
-require('QQdock').setup({
+require('slot').setup({
   commands = {
     reasonix = 'reasonix',
     lazygit  = 'lazygit',
@@ -68,10 +70,10 @@ commands = {
 不想用某个功能就不写对应字段。完全不传 `keymaps` 则不注册任何快捷键，可手动绑定：
 
 ```lua
-local Q = require('QQdock')
-vim.keymap.set('n', '<leader>s', Q.shell, { noremap = true })
-vim.keymap.set('n', '<leader>r', function() Q.open('reasonix') end)
-vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end)
+local S = require('slot')
+vim.keymap.set('n', '<leader>s', S.shell, { noremap = true })
+vim.keymap.set('n', '<leader>r', function() S.open('reasonix') end)
+vim.keymap.set('n', '<leader>cx', function() S.open('codex') end)
 ```
 
 ## 终端内隐藏键
@@ -93,9 +95,9 @@ vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end)
 
 | 函数 | 参数 | 作用 |
 |------|------|------|
-| `Q.setup(opts)` | opts | 配置尺寸、快捷键、命令映射 |
-| `Q.shell()` | — | 打开/关闭持久 shell |
-| `Q.open(cmd)` | cmd | 打开/关闭指定命令的持久终端 |
+| `S.setup(opts)` | opts | 配置尺寸、快捷键、命令映射 |
+| `S.shell()` | — | 打开/关闭持久 shell |
+| `S.open(cmd)` | cmd | 打开/关闭指定命令的持久终端 |
 
 ### setup 参数
 
@@ -114,7 +116,7 @@ vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end)
 - **零外部依赖** — 基于 `vim.fn.termopen` 原生终端
 - **持久化** — toggle 显隐，终端进程不中断
 - **自适应布局** — 横屏右分、竖屏下分、无文件占主窗
-- **单文件** — `lua/QQdock/init.lua` ~220 行
+- **单文件** — `lua/slot/init.lua` ~220 行
 
 ## 协议
 

doc/slot.txt

@@ -0,0 +1,155 @@
+*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:

lua/slot/init.lua

@@ -1,9 +1,9 @@
--- QQdock.nvim — Persistent adaptive terminal dock
+-- slot.nvim — Persistent adaptive terminal dock
 --
 -- 特性：持久化终端实例、自适应窗口方向（横屏右分屏/竖屏下分屏）、基于 Neovim 原生终端
 --
 -- 配置（可选）：
---   require('QQdock').setup({
+--   require('slot').setup({
 --     size = {
 --       horizontal = 10,  -- 竖屏下方终端高度（行数）
 --       vertical = 40,    -- 横屏右侧终端宽度（列数）
@@ -23,7 +23,7 @@
 --   })
 --
 -- 用法：
---   local Q = require('QQdock')
+--   local Q = require('slot')
 --   Q.shell()                -- 打开/关闭普通 shell
 --   Q.open('reasonix')       -- 打开/关闭 Reasonix
 --   Q.open('lazygit')        -- 打开/关闭 lazygit
@@ -43,7 +43,7 @@ local config = {
   debug = false,
 }
 
----@class QdockTerm
+---@class SlotTerm
 ---@field bufnr          integer
 ---@field winid          integer?
 ---@field job_id         integer
@@ -51,7 +51,7 @@ local config = {
 ---@field borrowed       boolean?
 ---@field original_bufnr integer?
 
----@type table<string, QdockTerm>
+---@type table<string, SlotTerm>>
 local terms = {} -- 缓存终端实例，key 是命令名（nil = 普通 shell  → '__shell__'）
 
 --- 基于当前窗口宽高返回 { direction, size }
@@ -118,7 +118,7 @@ function M.open(cmd)
       term.borrowed = nil
     else
       if config.debug then
-        vim.notify('QQdock: hide [' .. name .. ']', vim.log.levels.INFO)
+        vim.notify('slot: hide [' .. name .. ']', vim.log.levels.INFO)
       end
       if term.borrowed then
         -- 占了主窗口 → 换回原始空 buffer（如果还在的话，否则关窗）
@@ -150,7 +150,7 @@ function M.open(cmd)
     local height = vim.api.nvim_win_get_height(0)
     local mode = use_main and 'main' or direction
     vim.notify(
-      string.format('QQdock: %dx%d → %s %d [%s]', width, height, mode, size, name),
+      string.format('slot: %dx%d → %s %d [%s]', width, height, mode, size, name),
       vim.log.levels.INFO
     )
   end