feat: add toggle_doc functionality (#1647)

* feat: Add toggle_doc functionality

fix: Update docs view on entry change

* Replace toggle logic by open/close

* add docs and pinned flags

* add faq for disabling docs

* chore(git): ignore .DS_Store

---------

Co-authored-by: hrsh7th <629908+hrsh7th@users.noreply.github.com>

lua/cmp/config/default.lua

@@ -95,6 +95,9 @@ return function()
         name = 'custom',
         selection_order = 'top_down',
       },
+      docs = {
+        auto_open = true,
+      }
     },
 
     window = {

lua/cmp/config/mapping.lua

@@ -178,6 +178,24 @@ mapping.scroll_docs = function(delta)
   end
 end
 
+--- Opens the documentation window.
+mapping.open_docs = function()
+  return function(fallback)
+    if not require('cmp').open_docs() then
+      fallback()
+    end
+  end
+end
+
+--- Close the documentation window.
+mapping.close_docs = function()
+  return function(fallback)
+    if not require('cmp').close_docs() then
+      fallback()
+    end
+  end
+end
+
 ---Select next completion item.
 mapping.select_next_item = function(option)
   return function(fallback)

lua/cmp/init.lua

@@ -181,6 +181,31 @@ cmp.scroll_docs = cmp.sync(function(delta)
   end
 end)
 
+---Whether the documentation window is visible or not.
+cmp.visible_docs = cmp.sync(function()
+  return cmp.core.view.docs_view:visible()
+end)
+
+---Opens the documentation window.
+cmp.open_docs = cmp.sync(function()
+  if not cmp.visible_docs() then
+    cmp.core.view:open_docs()
+    return true
+  else
+    return false
+  end
+end)
+
+---Closes the documentation window.
+cmp.close_docs = cmp.sync(function()
+  if cmp.visible_docs() then
+    cmp.core.view:close_docs()
+    return true
+  else
+    return false
+  end
+end)
+
 ---Confirm completion
 cmp.confirm = cmp.sync(function(option, callback)
   option = option or {}

lua/cmp/types/cmp.lua

@@ -168,19 +168,23 @@ cmp.ItemField = {
 ---@field public entry_filter nil|function(entry: cmp.Entry, ctx: cmp.Context): boolean
 
 ---@class cmp.ViewConfig
----@field public entries cmp.EntriesConfig
+---@field public entries cmp.EntriesViewConfig
+---@field public docs cmp.DocsViewConfig
 
----@alias cmp.EntriesConfig cmp.CustomEntriesConfig|cmp.NativeEntriesConfig|cmp.WildmenuEntriesConfig|string
+---@alias cmp.EntriesViewConfig cmp.CustomEntriesViewConfig|cmp.NativeEntriesViewConfig|cmp.WildmenuEntriesViewConfig|string
 
----@class cmp.CustomEntriesConfig
+---@class cmp.CustomEntriesViewConfig
 ---@field name 'custom'
 ---@field selection_order 'top_down'|'near_cursor'
 
----@class cmp.NativeEntriesConfig
+---@class cmp.NativeEntriesViewConfig
 ---@field name 'native'
 
----@class cmp.WildmenuEntriesConfig
+---@class cmp.WildmenuEntriesViewConfig
 ---@field name 'wildmenu'
 ---@field separator string|nil
 
+---@class cmp.DocsViewConfig
+---@field public auto_open boolean
+
 return cmp

lua/cmp/view.lua

@@ -10,6 +10,7 @@ local ghost_text_view = require('cmp.view.ghost_text_view')
 
 ---@class cmp.View
 ---@field public event cmp.Event
+---@field private is_docs_view_pinned boolean
 ---@field private resolve_dedup cmp.AsyncDedup
 ---@field private native_entries_view cmp.NativeEntriesView
 ---@field private custom_entries_view cmp.CustomEntriesView
@@ -23,6 +24,7 @@ local view = {}
 view.new = function()
   local self = setmetatable({}, { __index = view })
   self.resolve_dedup = async.dedup()
+  self.is_docs_view_pinned = false
   self.custom_entries_view = custom_entries_view.new()
   self.native_entries_view = native_entries_view.new()
   self.wildmenu_entries_view = wildmenu_entries_view.new()
@@ -128,6 +130,7 @@ end
 ---Close menu
 view.close = function(self)
   if self:visible() then
+    self.is_docs_view_pinned = false
     self.event:emit('complete_done', {
       entry = self:_get_entries_view():get_selected_entry(),
     })
@@ -142,6 +145,9 @@ end
 
 ---Abort menu
 view.abort = function(self)
+  if self:visible() then
+    self.is_docs_view_pinned = false
+  end
   self:_get_entries_view():abort()
   self.docs_view:close()
   self.ghost_text_view:hide()
@@ -156,6 +162,28 @@ view.visible = function(self)
   return self:_get_entries_view():visible()
 end
 
+---Opens the documentation window.
+view.open_docs = function(self)
+  self.is_docs_view_pinned = true
+  local e = self:get_selected_entry()
+  if e then
+    e:resolve(vim.schedule_wrap(self.resolve_dedup(function()
+      if not self:visible() then
+        return
+      end
+      self.docs_view:open(e, self:_get_entries_view():info())
+    end)))
+  end
+end
+
+---Closes the documentation window.
+view.close_docs = function(self)
+  self.is_docs_view_pinned = false
+  if self:get_selected_entry() then
+    self.docs_view:close()
+  end
+end
+
 ---Scroll documentation window if possible.
 ---@param delta integer
 view.scroll_docs = function(self, delta)
@@ -239,7 +267,9 @@ view.on_entry_change = async.throttle(function(self)
       if not self:visible() then
         return
       end
-      self.docs_view:open(e, self:_get_entries_view():info())
+      if self.is_docs_view_pinned or config.get().view.docs.auto_open then
+        self.docs_view:open(e, self:_get_entries_view():info())
+      end
     end)))
   else
     self.docs_view:close()