feat(api): nvim_echo(percent=nil) means "unknown" progress #39029

Problem:
No way to signal "unknown" or "indeterminate" progress percentage.

Solution:
Treat percent=nil as "indeterminate" percent.

3 files changed, 11 insertions, 7 deletions

diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua
index 84623726c7..80327e0fc7 100644
--- a/runtime/lua/vim/_core/defaults.lua
+++ b/runtime/lua/vim/_core/defaults.lua
@@ -1115,7 +1115,12 @@ do
       desc = 'Display native progress bars',
       callback = function(ev)
         if ev.data.status == 'running' then
-          vim.api.nvim_ui_send(string.format('\027]9;4;1;%d\027\\', ev.data.percent))
+          if ev.data.percent ~= nil then
+            vim.api.nvim_ui_send(string.format('\027]9;4;1;%d\027\\', ev.data.percent))
+          else
+            -- "Indeterminate" progress (unknown percent).
+            vim.api.nvim_ui_send(string.format('\027]9;4;3\027\\'))
+          end
         else
           vim.api.nvim_ui_send('\027]9;4;0;0\027\\')
         end
diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua
index 85e5912593..990ee81925 100644
--- a/runtime/lua/vim/_meta/api.gen.lua
+++ b/runtime/lua/vim/_meta/api.gen.lua
@@ -1139,7 +1139,7 @@ function vim.api.nvim_del_var(name) end
 ---   instead of creating a new message.
 --- - kind (`string?`) Decides the `ui-messages` kind in the emitted message. Set "progress"
 ---   to emit a `progress-message`.
---- - percent (`integer?`) `progress-message` percentage.
+--- - percent (`integer?`) `progress-message` percentage, or nil to signal "unknown progress".
 --- - source (`string?`) `progress-message` source.
 --- - status (`string?`) `progress-message` status:
 ---   - "success": Process completed successfully.
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
index 10b066b4d3..faa9d4246b 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -373,15 +373,14 @@ end
 
 ---Emit progress messages
 ---@param len integer
----@return fun(status: 'success'|'running', idx: integer, fmt: string, ...: any): nil
+---@return fun(status: 'success'|'running', idx: integer?, fmt: string, ...: any): nil
 local function progress_report(len)
   local progress = { kind = 'progress', source = 'vim.health', title = 'checkhealth' }
 
   return function(status, idx, fmt, ...)
     progress.status = status
-    progress.percent = status == 'success' and nil or math.floor(idx / len * 100)
-    -- percent=0 omits the reporting of percentage, so use 1% instead
-    -- progress.percent = progress.percent == 0 and 1 or progress.percent
+    local progress_percent = idx and math.floor(idx / len * 100) or nil
+    progress.percent = status == 'success' and nil or progress_percent
     progress.id = vim.api.nvim_echo({ { fmt:format(...) } }, false, progress)
     vim.cmd.redraw()
   end
@@ -500,7 +499,7 @@ function M._check(eap)
     vim.fn.append(vim.fn.line('$'), s_output)
   end
 
-  progress_msg('success', 0, 'checks done')
+  progress_msg('success', nil, 'checks done')
 
   -- Quit with 'q' inside healthcheck buffers.
   vim._with({ buf = bufnr }, function()