feat: config.view.entries.vertical_positioning = 'above'|'below'|'auto'

lua/cmp/config/default.lua

@@ -97,6 +97,7 @@ return function()
       entries = {
         name = 'custom',
         selection_order = 'top_down',
+        vertical_positioning = 'below',
         follow_cursor = false,
       },
       docs = {

lua/cmp/types/cmp.lua

@@ -184,6 +184,7 @@ cmp.ItemField = {
 ---@class cmp.CustomEntriesViewConfig
 ---@field name 'custom'
 ---@field selection_order 'top_down'|'near_cursor'
+---@field vertical_positioning 'auto'|'above'|'below'
 ---@field follow_cursor boolean
 
 ---@class cmp.NativeEntriesViewConfig

lua/cmp/view.lua

@@ -192,7 +192,8 @@ view.open_docs = function(self)
       if not self:visible() then
         return
       end
-      self.docs_view:open(e, self:_get_entries_view():info())
+      local bottom_up = self.custom_entries_view.bottom_up
+      self.docs_view:open(e, self:_get_entries_view():info(), bottom_up)
     end)))
   end
 end
@@ -289,7 +290,8 @@ view.on_entry_change = async.throttle(function(self)
         return
       end
       if self.is_docs_view_pinned or config.get().view.docs.auto_open then
-        self.docs_view:open(e, self:_get_entries_view():info())
+        local bottom_up = self.custom_entries_view.bottom_up
+        self.docs_view:open(e, self:_get_entries_view():info(), bottom_up)
       end
     end)))
   else

lua/cmp/view/custom_entries_view.lua

@@ -16,6 +16,7 @@ local DEFAULT_HEIGHT = 10 -- @see https://github.com/vim/vim/blob/master/src/pop
 ---@field private active boolean
 ---@field private entries cmp.Entry[]
 ---@field private column_width any
+---@field private bottom_up boolean
 ---@field public event cmp.Event
 local custom_entries_view = {}
 
@@ -117,7 +118,8 @@ custom_entries_view.is_direction_top_down = function(self)
 end
 
 custom_entries_view.open = function(self, offset, entries)
-  local completion = config.get().window.completion
+  local c = config.get()
+  local completion = c.window.completion
   assert(completion, 'config.get() must resolve window.completion with defaults')
 
   self.offset = offset
@@ -172,12 +174,25 @@ custom_entries_view.open = function(self, offset, entries)
   local border_info = window.get_border_info({ style = completion })
   local border_offset_row = border_info.top + border_info.bottom
   local border_offset_col = border_info.left + border_info.right
-  if math.floor(vim.o.lines * 0.5) <= row + border_offset_row and vim.o.lines - row - border_offset_row <= math.min(DEFAULT_HEIGHT, height) then
+
+  local prefers_above = c.view.entries.vertical_positioning == 'above'
+  local prefers_auto = c.view.entries.vertical_positioning == 'auto'
+  local cant_fit_at_bottom = vim.o.lines - row - border_offset_row <= math.min(DEFAULT_HEIGHT, height)
+  local cant_fit_at_top = row - border_offset_row <= math.min(DEFAULT_HEIGHT, height)
+  local is_in_top_half = math.floor(vim.o.lines * 0.5) > row + border_offset_row
+  local should_position_above =
+    cant_fit_at_bottom or
+    (prefers_above and not cant_fit_at_top) or
+    (prefers_auto and is_in_top_half)
+  if should_position_above then
+    self.bottom_up = true
     height = math.min(height, row - 1)
     row = row - height - border_offset_row - 1
     if row < 0 then
       height = height + row
     end
+  else
+    self.bottom_up = false
   end
   if math.floor(vim.o.columns * 0.5) <= col + border_offset_col and vim.o.columns - col - border_offset_col <= width then
     width = math.min(width, vim.o.columns - 1)
@@ -187,12 +202,6 @@ custom_entries_view.open = function(self, offset, entries)
     end
   end
 
-  if pos[1] > row then
-    self.bottom_up = true
-  else
-    self.bottom_up = false
-  end
-
   if not self:is_direction_top_down() then
     local n = #self.entries
     for i = 1, math.floor(n / 2) do
@@ -226,9 +235,9 @@ custom_entries_view.open = function(self, offset, entries)
 
   -- Always set cursor when starting. It will be adjusted on the call to _select
   vim.api.nvim_win_set_cursor(self.entries_win.win, { 1, 0 })
-  if preselect_index > 0 and config.get().preselect == types.cmp.PreselectMode.Item then
+  if preselect_index > 0 and c.preselect == types.cmp.PreselectMode.Item then
     self:_select(preselect_index, { behavior = types.cmp.SelectBehavior.Select, active = false })
-  elseif not string.match(config.get().completion.completeopt, 'noselect') then
+  elseif not string.match(c.completion.completeopt, 'noselect') then
     if self:is_direction_top_down() then
       self:_select(1, { behavior = types.cmp.SelectBehavior.Select, active = false })
     else

lua/cmp/view/docs_view.lua

@@ -25,7 +25,8 @@ end
 ---Open documentation window
 ---@param e cmp.Entry
 ---@param view cmp.WindowStyle
-docs_view.open = function(self, e, view)
+---@param bottom_up boolean|nil
+docs_view.open = function(self, e, view, bottom_up)
   local documentation = config.get().window.documentation
   if not documentation then
     return
@@ -99,6 +100,8 @@ docs_view.open = function(self, e, view)
     return self:close()
   end
 
+  local row = bottom_up and math.max(view.row - (height + border_info.vert - view.height), 1) or view.row
+
   -- Render window.
   self.window:option('winblend', documentation.winblend)
   self.window:option('winhighlight', documentation.winhighlight)
@@ -107,7 +110,7 @@ docs_view.open = function(self, e, view)
     style = 'minimal',
     width = width,
     height = height,
-    row = view.row,
+    row = row,
     col = col,
     border = documentation.border,
     zindex = documentation.zindex or 50,