Merge pull request #6 from mhiro2/feat/stack-view-modules-position

feat(ui): Modularize stack view and harden config validation

Author: mhiro2

README.md

@@ -177,6 +177,9 @@ Configure via `require("peekstack").setup({ ... })`.
       base = "repo", -- "repo" | "cwd" | "absolute"
       max_width = 80,
     },
+    stack_view = {
+      position = "right", -- "left" | "right" | "bottom"
+    },
     inline_preview = {
       enabled = true,
       max_lines = 10,

doc/peekstack.txt

@@ -54,6 +54,9 @@ With options:
         base = "repo", -- "repo" | "cwd" | "absolute"
         max_width = 80,
       },
+      stack_view = {
+        position = "right", -- "left" | "right" | "bottom"
+      },
       inline_preview = {
         enabled = true,
         max_lines = 10,
@@ -162,6 +165,8 @@ Commands are registered after `setup()` is called.
 
 :PeekstackStack                              *:PeekstackStack*
     Open the stack view panel listing all active popups.
+    Position is configurable via `ui.stack_view.position`
+    (`left` / `right` / `bottom`).
     The focused popup is highlighted with a `▶` marker.
     Tree guides are shown for nested popup depth:
       `├` / `└` for sibling relation under the same parent.
@@ -342,6 +347,15 @@ BUFFER MODES                                           *peekstack-buffer-modes*
              `ui.popup.source.confirm_on_close` prompts on close if modified
              `ui.popup.source.prevent_auto_close_if_modified` blocks auto-close
 
+==============================================================================
+STACK VIEW                                             *peekstack-stack-view*
+
+`ui.stack_view.position` controls where the stack view panel opens:
+
+    "right"  (default) right-side panel
+    "left"             left-side panel
+    "bottom"           bottom panel across full editor width
+
 ==============================================================================
 EVENTS                                                   *peekstack-events*
 

lua/peekstack/commands.lua

@@ -182,9 +182,14 @@ function M.setup()
         "lsp.implementation",
         "lsp.references",
         "lsp.type_definition",
+        "lsp.declaration",
         "diagnostics.under_cursor",
+        "diagnostics.in_buffer",
         "file.under_cursor",
         "grep.search",
+        "marks.buffer",
+        "marks.global",
+        "marks.all",
       }
     end,
   })

lua/peekstack/config.lua

@@ -22,13 +22,22 @@ local KNOWN_MARK_SCOPES = { "buffer", "global", "all" }
 ---@type string[]
 local KNOWN_PATH_BASES = { "repo", "cwd", "absolute" }
 
+---@type string[]
+local KNOWN_STACK_VIEW_POSITIONS = { "left", "right", "bottom" }
+
 ---@param path string
 ---@param expected_type string
 ---@param value any
-local function validate_type(path, expected_type, value)
+---@param default any
+---@return any
+local function validate_type(path, expected_type, value, default)
   if type(value) ~= expected_type then
-    notify.warn(string.format("%s must be a %s, got %s", path, expected_type, type(value)))
+    notify.warn(
+      string.format("%s must be a %s, got %s. Falling back to %s", path, expected_type, type(value), tostring(default))
+    )
+    return default
   end
+  return value
 end
 
 ---@param path string
@@ -103,6 +112,9 @@ M.defaults = {
       base = "repo",
       max_width = 80,
     },
+    stack_view = {
+      position = "right",
+    },
     inline_preview = {
       enabled = true,
       max_lines = 10,
@@ -240,7 +252,8 @@ local function validate(cfg)
   end
 
   if cfg.ui and cfg.ui.popup and cfg.ui.popup.editable ~= nil then
-    validate_type("ui.popup.editable", "boolean", cfg.ui.popup.editable)
+    cfg.ui.popup.editable =
+      validate_type("ui.popup.editable", "boolean", cfg.ui.popup.editable, M.defaults.ui.popup.editable)
   end
 
   if cfg.ui and cfg.ui.path then
@@ -258,6 +271,25 @@ local function validate(cfg)
     end
   end
 
+  if cfg.ui and cfg.ui.stack_view ~= nil then
+    if type(cfg.ui.stack_view) ~= "table" then
+      notify.warn(
+        string.format("ui.stack_view must be a table, got %s. Falling back to defaults", type(cfg.ui.stack_view))
+      )
+      cfg.ui.stack_view = vim.deepcopy(M.defaults.ui.stack_view)
+    else
+      local stack_view = cfg.ui.stack_view
+      if stack_view.position ~= nil then
+        stack_view.position = validate_enum(
+          "ui.stack_view.position",
+          stack_view.position,
+          KNOWN_STACK_VIEW_POSITIONS,
+          M.defaults.ui.stack_view.position
+        )
+      end
+    end
+  end
+
   -- Validate buffer_mode
   if cfg.ui and cfg.ui.popup and cfg.ui.popup.buffer_mode then
     cfg.ui.popup.buffer_mode = validate_enum(
@@ -272,10 +304,20 @@ local function validate(cfg)
   if cfg.ui and cfg.ui.popup and cfg.ui.popup.source then
     local source = cfg.ui.popup.source
     if source.prevent_auto_close_if_modified ~= nil then
-      validate_type("ui.popup.source.prevent_auto_close_if_modified", "boolean", source.prevent_auto_close_if_modified)
+      source.prevent_auto_close_if_modified = validate_type(
+        "ui.popup.source.prevent_auto_close_if_modified",
+        "boolean",
+        source.prevent_auto_close_if_modified,
+        M.defaults.ui.popup.source.prevent_auto_close_if_modified
+      )
     end
     if source.confirm_on_close ~= nil then
-      validate_type("ui.popup.source.confirm_on_close", "boolean", source.confirm_on_close)
+      source.confirm_on_close = validate_type(
+        "ui.popup.source.confirm_on_close",
+        "boolean",
+        source.confirm_on_close,
+        M.defaults.ui.popup.source.confirm_on_close
+      )
     end
   end
 
@@ -303,7 +345,12 @@ local function validate(cfg)
   if cfg.ui and cfg.ui.inline_preview then
     local inline_preview = cfg.ui.inline_preview
     if inline_preview.enabled ~= nil then
-      validate_type("ui.inline_preview.enabled", "boolean", inline_preview.enabled)
+      inline_preview.enabled = validate_type(
+        "ui.inline_preview.enabled",
+        "boolean",
+        inline_preview.enabled,
+        M.defaults.ui.inline_preview.enabled
+      )
     end
     if inline_preview.max_lines ~= nil then
       inline_preview.max_lines = validate_number_range(
@@ -314,7 +361,12 @@ local function validate(cfg)
       )
     end
     if inline_preview.hl_group ~= nil then
-      validate_type("ui.inline_preview.hl_group", "string", inline_preview.hl_group)
+      inline_preview.hl_group = validate_type(
+        "ui.inline_preview.hl_group",
+        "string",
+        inline_preview.hl_group,
+        M.defaults.ui.inline_preview.hl_group
+      )
     end
     if inline_preview.close_events ~= nil then
       validate_event_list("ui.inline_preview.close_events", inline_preview.close_events)
@@ -336,7 +388,8 @@ local function validate(cfg)
     elseif type(cfg.ui.title.icons) == "table" then
       local icons = cfg.ui.title.icons
       if icons.enabled ~= nil then
-        validate_type("ui.title.icons.enabled", "boolean", icons.enabled)
+        icons.enabled =
+          validate_type("ui.title.icons.enabled", "boolean", icons.enabled, M.defaults.ui.title.icons.enabled)
       end
       if icons.map ~= nil and type(icons.map) ~= "table" then
         notify.warn("ui.title.icons.map must be a table, got " .. type(icons.map) .. ". Falling back to defaults")
@@ -425,10 +478,16 @@ local function validate(cfg)
         validate_enum("providers.marks.scope", marks.scope, KNOWN_MARK_SCOPES, M.defaults.providers.marks.scope)
     end
     if marks.include ~= nil then
-      validate_type("providers.marks.include", "string", marks.include)
+      marks.include =
+        validate_type("providers.marks.include", "string", marks.include, M.defaults.providers.marks.include)
     end
     if marks.include_special ~= nil then
-      validate_type("providers.marks.include_special", "boolean", marks.include_special)
+      marks.include_special = validate_type(
+        "providers.marks.include_special",
+        "boolean",
+        marks.include_special,
+        M.defaults.providers.marks.include_special
+      )
     end
   end
 
@@ -440,10 +499,20 @@ local function validate(cfg)
   if cfg.persist and cfg.persist.session then
     local session = cfg.persist.session
     if session.default_name ~= nil then
-      validate_type("persist.session.default_name", "string", session.default_name)
+      session.default_name = validate_type(
+        "persist.session.default_name",
+        "string",
+        session.default_name,
+        M.defaults.persist.session.default_name
+      )
     end
     if session.prompt_if_missing ~= nil then
-      validate_type("persist.session.prompt_if_missing", "boolean", session.prompt_if_missing)
+      session.prompt_if_missing = validate_type(
+        "persist.session.prompt_if_missing",
+        "boolean",
+        session.prompt_if_missing,
+        M.defaults.persist.session.prompt_if_missing
+      )
     end
   end
 
@@ -453,25 +522,37 @@ local function validate(cfg)
     else
       local auto = cfg.persist.auto
       if auto.enabled ~= nil then
-        validate_type("persist.auto.enabled", "boolean", auto.enabled)
+        auto.enabled = validate_type("persist.auto.enabled", "boolean", auto.enabled, M.defaults.persist.auto.enabled)
       end
       if auto.session_name ~= nil then
-        validate_type("persist.auto.session_name", "string", auto.session_name)
+        auto.session_name =
+          validate_type("persist.auto.session_name", "string", auto.session_name, M.defaults.persist.auto.session_name)
       end
       if auto.restore ~= nil then
-        validate_type("persist.auto.restore", "boolean", auto.restore)
+        auto.restore = validate_type("persist.auto.restore", "boolean", auto.restore, M.defaults.persist.auto.restore)
       end
       if auto.save ~= nil then
-        validate_type("persist.auto.save", "boolean", auto.save)
+        auto.save = validate_type("persist.auto.save", "boolean", auto.save, M.defaults.persist.auto.save)
       end
       if auto.restore_if_empty ~= nil then
-        validate_type("persist.auto.restore_if_empty", "boolean", auto.restore_if_empty)
+        auto.restore_if_empty = validate_type(
+          "persist.auto.restore_if_empty",
+          "boolean",
+          auto.restore_if_empty,
+          M.defaults.persist.auto.restore_if_empty
+        )
       end
       if auto.debounce_ms ~= nil then
-        validate_type("persist.auto.debounce_ms", "number", auto.debounce_ms)
+        auto.debounce_ms =
+          validate_type("persist.auto.debounce_ms", "number", auto.debounce_ms, M.defaults.persist.auto.debounce_ms)
       end
       if auto.save_on_leave ~= nil then
-        validate_type("persist.auto.save_on_leave", "boolean", auto.save_on_leave)
+        auto.save_on_leave = validate_type(
+          "persist.auto.save_on_leave",
+          "boolean",
+          auto.save_on_leave,
+          M.defaults.persist.auto.save_on_leave
+        )
       end
     end
   end

lua/peekstack/core/popup.lua

@@ -132,6 +132,10 @@ function M.create(location, opts)
   end
 
   local source_bufnr = vim.fn.bufadd(fname)
+  if source_bufnr == 0 then
+    vim.notify("Failed to add buffer: " .. fname, vim.log.levels.WARN)
+    return nil
+  end
   local ok_load = pcall(vim.fn.bufload, source_bufnr)
   if not ok_load then
     vim.notify("Failed to load buffer: " .. fname, vim.log.levels.WARN)

lua/peekstack/core/stack.lua

@@ -180,9 +180,6 @@ function M.current(winid)
   return stack.popups[#stack.popups]
 end
 
----@param id integer
----@param winid? integer
----@return boolean
 ---@param stack PeekstackStackModel
 ---@param idx integer
 ---@param item PeekstackPopupModel

lua/peekstack/init.lua

@@ -328,14 +328,16 @@ function M.setup(opts)
   persist_auto.setup()
 end
 
----@return table
+---Proxy table for `peekstack.core.stack`.
+---@type table
 M.stack = setmetatable({}, {
   __index = function(_, k)
     return require("peekstack.core.stack")[k]
   end,
 })
 
----@return table
+---Proxy table for `peekstack.persist`.
+---@type table
 M.persist = setmetatable({}, {
   __index = function(_, k)
     return require("peekstack.persist")[k]

lua/peekstack/persist/init.lua

@@ -22,7 +22,6 @@ local function update_cache(data)
 end
 
 ---Check if persistence is enabled, notify if not
----@return boolean
 ---@param silent? boolean
 ---@return boolean
 local function ensure_enabled(silent)

lua/peekstack/types.lua

@@ -142,6 +142,19 @@
 ---@field root_winid integer
 ---@field from_popup boolean
 
+---@class PeekstackStackViewState
+---@field bufnr integer?
+---@field winid integer?
+---@field root_winid integer?
+---@field line_to_id table<integer, integer>
+---@field filter string?
+---@field header_lines integer
+---@field help_bufnr integer?
+---@field help_winid integer?
+---@field help_augroup integer?
+---@field autoclose_group integer?
+---@field autoclose_suspended integer
+
 -- Config type definitions
 
 ---@class PeekstackConfigLayoutOffset
@@ -184,6 +197,9 @@
 ---@field base "repo"|"cwd"|"absolute"
 ---@field max_width integer
 
+---@class PeekstackConfigStackView
+---@field position "left"|"right"|"bottom"
+
 ---@class PeekstackConfigInlinePreview
 ---@field enabled boolean
 ---@field max_lines integer
@@ -233,6 +249,7 @@
 ---@field layout PeekstackConfigLayout
 ---@field title PeekstackConfigTitle
 ---@field path PeekstackConfigPath
+---@field stack_view PeekstackConfigStackView
 ---@field inline_preview PeekstackConfigInlinePreview
 ---@field quick_peek PeekstackConfigQuickPeek
 ---@field popup PeekstackConfigPopup