docs(extui): rename box->msg, more->pager, prompt->dialog

Includes breaking changes to the `opts` layout. "box" doesn't really
describe anything other than a floating window so was an unwanted synonym.

1 files changed, 87 insertions, 88 deletions

diff --git a/runtime/lua/vim/_extui/messages.lua b/runtime/lua/vim/_extui/messages.lua
index 1a02c1b3ae..1812b778dd 100644
--- a/runtime/lua/vim/_extui/messages.lua
+++ b/runtime/lua/vim/_extui/messages.lua
@@ -3,13 +3,13 @@ local ext = require('vim._extui.shared')
 
 ---@class vim._extui.messages
 local M = {
-  -- Message box window. Used for regular messages with 'cmdheight' == 0 or,
-  -- cfg.msg.pos == 'box'. Also used for verbose messages regardless of
-  -- cfg.msg.pos. Automatically resizes to the text dimensions up to a point,
+  -- Message window. Used for regular messages with 'cmdheight' == 0 or,
+  -- cfg.msg.target == 'msg'. Also used for verbose messages regardless of
+  -- cfg.msg.target. Automatically resizes to the text dimensions up to a point,
   -- at which point only the most recent messages will fit and be shown.
   -- A timer is started for each message whose callback will remove the message
   -- from the window again.
-  box = {
+  msg = {
     count = 0, -- Number of messages currently in the message window.
     width = 1, -- Current width of the message window.
     timer = nil, ---@type uv.uv_timer_t Timer that removes the most recent message.
@@ -36,12 +36,12 @@ local M = {
   },
 }
 
-function M.box:close()
+function M.msg:close()
   self.width, M.virt.msg = 1, { {}, {} }
-  M.prev_msg = ext.cfg.msg.pos == 'box' and '' or M.prev_msg
-  api.nvim_buf_clear_namespace(ext.bufs.box, -1, 0, -1)
-  if api.nvim_win_is_valid(ext.wins.box) then
-    api.nvim_win_set_config(ext.wins.box, { hide = true })
+  M.prev_msg = ext.cfg.msg.target == 'msg' and '' or M.prev_msg
+  api.nvim_buf_clear_namespace(ext.bufs.msg, -1, 0, -1)
+  if api.nvim_win_is_valid(ext.wins.msg) then
+    api.nvim_win_set_config(ext.wins.msg, { hide = true })
   end
 end
 
@@ -49,20 +49,20 @@ end
 ---
 ---@param buf integer Buffer the message was written to.
 ---@param len integer Number of rows that should be removed.
-function M.box:start_timer(buf, len)
+function M.msg:start_timer(buf, len)
   self.timer = vim.defer_fn(function()
     if self.count == 0 or not api.nvim_buf_is_valid(buf) then
-      return -- Messages moved to more or buffer was closed.
+      return -- Messages moved to pager or buffer was closed.
     end
     api.nvim_buf_set_lines(buf, 0, len, false, {})
     self.count = self.count - 1
-    -- Resize or hide message box for removed message.
+    -- Resize or hide message window for removed message.
     if self.count > 0 then
-      M.set_pos('box')
+      M.set_pos('msg')
     else
       self:close()
     end
-  end, ext.cfg.msg.box.timeout)
+  end, ext.cfg.msg.timeout)
 end
 
 --- Place or delete a virtual text mark in the cmdline or message window.
@@ -88,11 +88,11 @@ local function set_virttext(type)
     M.virt.ids[type] = nil
     M.cmd.last_col = type == 'last' and o.columns or M.cmd.last_col
   elseif #chunks > 0 then
-    local tar = type == 'msg' and ext.cfg.msg.pos or 'cmd'
+    local tar = type == 'msg' and ext.cfg.msg.target or 'cmd'
     local win = ext.wins[tar]
     local max = api.nvim_win_get_height(win)
     local erow = tar == 'cmd' and M.cmd.msg_row or nil
-    local srow = tar == 'box' and fn.line('w0', ext.wins.box) - 1 or nil
+    local srow = tar == 'msg' and fn.line('w0', ext.wins.msg) - 1 or nil
     local h = api.nvim_win_text_height(win, { start_row = srow, end_row = erow, max_height = max })
     local row = h.end_row ---@type integer
     local col = fn.virtcol2col(win, row + 1, h.end_vcol)
@@ -102,17 +102,17 @@ local function set_virttext(type)
       -- Calculate at which column to place the virt_text such that it is at the end
       -- of the last visible message line, overlapping the message text if necessary,
       -- but not overlapping the 'last' virt_text.
-      local offset = tar ~= 'box' and 0
+      local offset = tar ~= 'msg' and 0
         or api.nvim_win_get_position(win)[2] + (api.nvim_win_get_config(win).border and 1 or 0)
 
-      -- Check if adding the virt_text on this line will exceed the current 'box' width.
-      local boxwidth = math.max(M.box.width, math.min(o.columns, scol - offset + width))
-      if tar == 'box' and api.nvim_win_get_width(win) < boxwidth then
-        api.nvim_win_set_width(win, boxwidth)
-        M.box.width = boxwidth
+      -- Check if adding the virt_text on this line will exceed the current window width.
+      local maxwidth = math.max(M.msg.width, math.min(o.columns, scol - offset + width))
+      if tar == 'msg' and api.nvim_win_get_width(win) < maxwidth then
+        api.nvim_win_set_width(win, maxwidth)
+        M.msg.width = maxwidth
       end
 
-      local mwidth = tar == 'box' and M.box.width or M.cmd.last_col
+      local mwidth = tar == 'msg' and M.msg.width or M.cmd.last_col
       if scol - offset + width > mwidth then
         col = fn.virtcol2col(win, row + 1, h.end_vcol - (scol - offset + width - mwidth))
       end
@@ -174,45 +174,45 @@ end
 
 -- We need to keep track of the current message column to be able to
 -- append or overwrite messages for :echon or carriage returns.
-local col, will_more, hlopts = 0, false, { undo_restore = false, invalidate = true, priority = 1 }
---- Move message to more buffer, appending if window was already open.
-local function msg_to_more(tar)
-  if will_more then
+local col, will_pager, hlopts = 0, false, { undo_restore = false, invalidate = true, priority = 1 }
+--- Move message to pager, appending if window was already open.
+local function msg_to_pager(tar)
+  if will_pager then
     return
   end
-  will_more, M.prev_msg = true, ''
+  will_pager, M.prev_msg = true, ''
 
   vim.schedule(function()
-    local hidden = api.nvim_win_get_config(ext.wins.more).hide
+    local hidden = api.nvim_win_get_config(ext.wins.pager).hide
     local marks = api.nvim_buf_get_extmarks(ext.bufs[tar], -1, 0, -1, { details = true })
     local lines = api.nvim_buf_get_lines(ext.bufs[tar], 0, -1, false)
-    api.nvim_buf_set_lines(ext.bufs.more, hidden and 0 or -1, -1, false, lines)
-    local rows = api.nvim_buf_line_count(ext.bufs.more) - #lines
+    api.nvim_buf_set_lines(ext.bufs.pager, hidden and 0 or -1, -1, false, lines)
+    local rows = api.nvim_buf_line_count(ext.bufs.pager) - #lines
     api.nvim_buf_set_lines(ext.bufs[tar], 0, -1, false, {})
     for _, mark in ipairs(marks) do
       hlopts.end_col, hlopts.hl_group = mark[4].end_col, mark[4].hl_group
-      api.nvim_buf_set_extmark(ext.bufs.more, ext.ns, mark[2] + rows, mark[3], hlopts)
+      api.nvim_buf_set_extmark(ext.bufs.pager, ext.ns, mark[2] + rows, mark[3], hlopts)
     end
-    M.box:close()
-    M.set_pos('more')
+    M.msg:close()
+    M.set_pos('pager')
     if not hidden then
       api.nvim_command('norm! G')
     end
-    M[tar].count, col, will_more = 0, 0, false
+    M[tar].count, col, will_pager = 0, 0, false
   end)
 end
 
----@param tar 'box'|'cmd'|'more'|'prompt'
+---@param tar 'cmd'|'dialog'|'msg'|'pager'
 ---@param content MsgContent
 ---@param replace_last boolean
 ---@param append boolean
----@param more boolean? If true, route messages that exceed the target window to more window.
-function M.show_msg(tar, content, replace_last, append, more)
+---@param pager boolean? If true, route messages that exceed the target window to the pager.
+function M.show_msg(tar, content, replace_last, append, pager)
   local msg, restart, cr, dupe, count = '', false, false, 0, 0
   append = append and col > 0
 
-  if M[tar] then -- tar == 'box'|'cmd'
-    if tar == ext.cfg.msg.pos then
+  if M[tar] then -- tar == 'cmd'|'msg'
+    if tar == ext.cfg.msg.target then
       -- Save the concatenated message to identify repeated messages.
       for _, chunk in ipairs(content) do
         msg = msg .. chunk[2]
@@ -233,10 +233,10 @@ function M.show_msg(tar, content, replace_last, append, more)
   local line_count = api.nvim_buf_line_count(ext.bufs[tar])
   ---@type integer Start row after last line in the target buffer, unless
   ---this is the first message, or in case of a repeated or replaced message.
-  local row = M[tar] and count <= 1 and not will_more and (tar == 'cmd' and ext.cmd.row or 0)
+  local row = M[tar] and count <= 1 and not will_pager and (tar == 'cmd' and ext.cmd.row or 0)
     or line_count - ((replace_last or restart or cr or append) and 1 or 0)
   local curline = (cr or append) and api.nvim_buf_get_lines(ext.bufs[tar], row, row + 1, false)[1]
-  local start_row, width = row, M.box.width
+  local start_row, width = row, M.msg.width
   col = append and not cr and math.min(col, #curline) or 0
 
   -- Accumulate to be inserted and highlighted message chunks for a non-repeated message.
@@ -254,7 +254,7 @@ function M.show_msg(tar, content, replace_last, append, more)
         api.nvim_buf_set_text(ext.bufs[tar], row, col, row, ecol, { repl })
       end
       curline = api.nvim_buf_get_lines(ext.bufs[tar], row, row + 1, false)[1]
-      width = tar == 'box' and math.max(width, api.nvim_strwidth(curline)) or 0
+      width = tar == 'msg' and math.max(width, api.nvim_strwidth(curline)) or 0
 
       if chunk[3] > 0 then
         hlopts.end_col, hlopts.hl_group = end_col, chunk[3]
@@ -269,22 +269,22 @@ function M.show_msg(tar, content, replace_last, append, more)
     end
   end
 
-  if tar == 'box' then
-    api.nvim_win_set_width(ext.wins.box, width)
-    local h = api.nvim_win_text_height(ext.wins.box, { start_row = start_row })
-    if more and h.all > 1 then
-      msg_to_more(tar)
+  if tar == 'msg' then
+    api.nvim_win_set_width(ext.wins.msg, width)
+    local h = api.nvim_win_text_height(ext.wins.msg, { start_row = start_row })
+    if pager and h.all > 1 then
+      msg_to_pager(tar)
       return
     end
 
-    M.set_pos('box')
-    M.box.width = width
+    M.set_pos('msg')
+    M.msg.width = width
     if restart then
-      M.box.timer:stop()
-      M.box.timer:set_repeat(4000)
-      M.box.timer:again()
+      M.msg.timer:stop()
+      M.msg.timer:set_repeat(4000)
+      M.msg.timer:again()
     else
-      M.box:start_timer(ext.bufs.box, row - start_row + 1)
+      M.msg:start_timer(ext.bufs.msg, row - start_row + 1)
     end
   elseif tar == 'cmd' and dupe == 0 then
     fn.clearmatches(ext.wins.cmd) -- Clear matchparen highlights.
@@ -296,8 +296,9 @@ function M.show_msg(tar, content, replace_last, append, more)
       api.nvim__redraw({ flush = true, cursor = true, win = ext.wins.cmd })
     else
       local h = api.nvim_win_text_height(ext.wins.cmd, {})
-      if (more or not api.nvim_win_get_config(ext.wins.cmd).hide) and h.all > ext.cmdheight then
-        msg_to_more(tar)
+      local want_pager = pager or will_pager or not api.nvim_win_get_config(ext.wins.pager).hide
+      if want_pager and h.all > ext.cmdheight then
+        msg_to_pager(tar)
         return
       end
 
@@ -312,7 +313,7 @@ function M.show_msg(tar, content, replace_last, append, more)
 
   if M[tar] then
     -- Place (x) indicator for repeated messages. Mainly to mitigate unnecessary
-    -- resizing of the message box window, but also placed in the cmdline.
+    -- resizing of the message window, but also placed in the cmdline.
     M.virt.msg[M.virt.idx.dupe][1] = dupe > 0 and { 0, ('(%d)'):format(dupe) } or nil
     M.prev_msg, M.dupe, M[tar].count = msg, dupe, count
     set_virttext('msg')
@@ -350,16 +351,15 @@ function M.msg_show(kind, content, _, _, append)
     vim.api.nvim_feedkeys(vim.keycode('<CR>'), 'n', false)
   elseif kind == 'verbose' then
     -- Verbose messages are sent too often to be meaningful in the cmdline:
-    -- always route to box regardless of cfg.msg.pos.
-    M.show_msg('box', content, false, append)
+    -- always route to message window regardless of cfg.msg.target.
+    M.show_msg('msg', content, false, append)
   elseif ext.cmd.prompt then
-    -- Route to prompt that stays open so long as the cmdline prompt is active.
-    api.nvim_buf_set_lines(ext.bufs.prompt, 0, -1, false, { '' })
-    M.show_msg('prompt', content, true, append)
-    M.set_pos('prompt')
+    -- Route to dialog that stays open so long as the cmdline prompt is active.
+    M.show_msg('dialog', content, api.nvim_win_get_config(ext.wins.dialog).hide, append)
+    M.set_pos('dialog')
   else
     -- Set the entered search command in the cmdline (if available).
-    local tar = kind == 'search_cmd' and 'cmd' or ext.cfg.msg.pos
+    local tar = kind == 'search_cmd' and 'cmd' or ext.cfg.msg.target
     if tar == 'cmd' then
       if ext.cmdheight == 0 or (ext.cmd.level > 0 and ext.cmd.row == 0) then
         return -- Do not overwrite an active cmdline unless in block mode.
@@ -372,10 +372,10 @@ function M.msg_show(kind, content, _, _, append)
       M.msg_showcmd({})
     end
 
-    -- Typed "inspection" messages should be routed to the more window.
-    local typed_more = { 'echo', 'echomsg', 'lua_print' }
-    local more = kind == 'list_cmd' or (ext.cmd.level >= 0 and vim.tbl_contains(typed_more, kind))
-    M.show_msg(tar, content, replace_bufwrite, append, more)
+    -- Typed "inspection" messages should be routed to the pager.
+    local inspect = { 'echo', 'echomsg', 'lua_print' }
+    local pager = kind == 'list_cmd' or (ext.cmd.level >= 0 and vim.tbl_contains(inspect, kind))
+    M.show_msg(tar, content, replace_bufwrite, append, pager)
     -- Replace message for every second bufwrite message.
     replace_bufwrite = not replace_bufwrite and kind == 'bufwrite'
     -- Don't remember search_cmd message as actual message.
@@ -415,7 +415,7 @@ function M.msg_ruler(content)
 end
 
 ---@alias MsgHistory [string, MsgContent]
---- Open the message history in the more window.
+--- Open the message history in the pager.
 ---
 ---@param entries MsgHistory[]
 function M.msg_history_show(entries)
@@ -423,19 +423,19 @@ function M.msg_history_show(entries)
     return
   end
 
-  api.nvim_buf_set_lines(ext.bufs.more, 0, -1, false, {})
+  api.nvim_buf_set_lines(ext.bufs.pager, 0, -1, false, {})
   for i, entry in ipairs(entries) do
-    M.show_msg('more', entry[2], i == 1, false)
+    M.show_msg('pager', entry[2], i == 1, false)
   end
 
-  M.set_pos('more')
+  M.set_pos('pager')
 end
 
 function M.msg_history_clear() end
 
 --- Adjust dimensions of the message windows after certain events.
 ---
----@param type? 'box'|'cmd'|'more'|'prompt' Type of to be positioned window (nil for all).
+---@param type? 'cmd'|'dialog'|'msg'|'pager' Type of to be positioned window (nil for all).
 function M.set_pos(type)
   local function win_set_pos(win)
     local texth = type and api.nvim_win_text_height(win, {}) or 0
@@ -444,18 +444,18 @@ function M.set_pos(type)
       hide = false,
       relative = 'laststatus',
       height = height,
-      row = win == ext.wins.box and 0 or 1,
+      row = win == ext.wins.msg and 0 or 1,
       col = 10000,
     }
 
-    if type == 'box' then
+    if type == 'msg' then
       -- Ensure last line is visible and first line is at top of window.
       local row = (texth.all > height and texth.end_row or 0) + 1
-      api.nvim_win_set_cursor(ext.wins.box, { row, 0 })
-    elseif type == 'more' and api.nvim_win_get_config(win).hide then
-      -- Cannot leave the cmdwin to enter the "more" window, so close it.
+      api.nvim_win_set_cursor(ext.wins.msg, { row, 0 })
+    elseif type == 'pager' and api.nvim_win_get_config(win).hide then
+      -- Cannot leave the cmdwin to enter the pager, so close it.
       -- NOTE: regression w.r.t. the message grid, which allowed this. Resolving
-      -- that would require somehow bypassing textlock for the "more" window.
+      -- that would require somehow bypassing textlock for the pager.
       if fn.getcmdwintype() ~= '' then
         api.nvim_command('quit')
       end
@@ -465,18 +465,17 @@ function M.set_pos(type)
         api.nvim_set_current_win(win)
         api.nvim_create_autocmd({ 'WinEnter', 'CmdwinEnter', 'CmdwinLeave' }, {
           callback = function(ev)
-            if ev.event == 'CmdwinEnter' then
-              api.nvim_win_set_config(win, { relative = 'win', win = 0, row = 0, col = 0 })
-            elseif ev.event == 'CmdwinLeave' then
+            -- Make pager relative to cmdwin when it is opened, restore when it is closed.
+            config = ev.event == 'CmdwinLeave' and config
+              or ev.event == 'WinEnter' and { hide = true }
+              or { relative = 'win', win = 0, row = 0, col = 0 }
+            if api.nvim_win_is_valid(win) then
               api.nvim_win_set_config(win, config)
-            else
-              if api.nvim_win_is_valid(win) then
-                api.nvim_win_set_config(win, { hide = true })
-              end
-              return true
             end
+            -- Delete autocmd when a window other than the cmdwin is entered.
+            return ev.event == 'WinEnter'
           end,
-          desc = 'Hide inactive "more" window.',
+          desc = 'Hide inactive pager window.',
         })
       end)
     end