feat!: Switch to event-driven LSP progress polling by default

Event-driven polling seems to be the "right" way to address #167;
see also neovim/neovim#26098.

Periodic polling is still supported, and useful for issues like #73, but
since Neovim's built-in ringbuf configuration is not designed for the
periodic use case, it doesn't make sense for this to be Fidget's default
behavior.

doc/fidget.md

@@ -26,7 +26,7 @@ The following table shows the default options for this plugin:
 {
   -- Options related to LSP progress subsystem
   progress = {
-    poll_rate = 5,                -- How frequently to poll for progress messages
+    poll_rate = 0,                -- How and when to poll for progress messages
     suppress_on_insert = false,   -- Suppress new messages while in insert mode
     ignore_done_already = false,  -- Ignore new tasks that are already complete
     notification_group =          -- How to get a progress message's notification group key
@@ -66,7 +66,7 @@ The following table shows the default options for this plugin:
 
   -- Options related to notification subsystem
   notification = {
-    poll_rate = 10,               -- How frequently to poll and render notifications
+    poll_rate = 10,               -- How frequently to update and render notifications
     filter = vim.log.levels.INFO, -- Minimum notifications level
     override_vim_notify = false,  -- Automatically override vim.notify() with Fidget
     configs =                     -- How to configure notification groups when instantiated
@@ -107,14 +107,25 @@ The following table shows the default options for this plugin:
 ```
 
 progress.poll_rate
-: How frequently to poll for progress messages
+: How and when to poll for progress messages
 
-Set to 0 to disable polling; you can still manually poll progress messages
-by calling `fidget.progress.poll()`.
+Set to `0` to immediately poll on each `LspProgress` event.
 
-Measured in Hertz (frames per second).
+Set to a positive number to poll for progress messages at the specified
+frequency (Hz, i.e., polls per second). Combining a slow `poll_rate`
+(e.g., `0.5`) with the `ignore_done_already` setting can be used to filter
+out short-lived progress tasks, de-cluttering notifications.
+
+Note that if too many LSP progress messages are sent between polls,
+Neovim's progress ring buffer will overflow and messages will be
+overwritten (dropped), possibly causing stale progress notifications.
+Workarounds include using the `progress.lsp.progress_ringbuf_size` option,
+or manually calling `fidget.notification.reset()` (see #167).
+
+Set to `false` to disable polling altogether; you can still manually poll
+progress messages by calling `fidget.progress.poll()`.
 
-Type: `number` (default: `5`)
+Type: `number | false` (default: `0`)
 
 progress.suppress_on_insert
 : Suppress new messages while in insert mode

lua/fidget/notification.lua

@@ -81,7 +81,7 @@ M.default_config = {
 
 --- Options related to notification subsystem
 require("fidget.options").declare(M, "notification", {
-  --- How frequently to poll and render notifications
+  --- How frequently to update and render notifications
   ---
   --- Measured in Hertz (frames per second).
   ---

lua/fidget/progress.lua

@@ -12,15 +12,26 @@ local autocmd_id   = nil
 
 --- Options related to LSP progress notification subsystem
 require("fidget.options").declare(M, "progress", {
-  --- How frequently to poll for progress messages
+  --- How and when to poll for progress messages
   ---
-  --- Set to 0 to disable polling; you can still manually poll progress messages
-  --- by calling `fidget.progress.poll()`.
+  --- Set to `0` to immediately poll on each `LspProgress` event.
   ---
-  --- Measured in Hertz (frames per second).
+  --- Set to a positive number to poll for progress messages at the specified
+  --- frequency (Hz, i.e., polls per second). Combining a slow `poll_rate`
+  --- (e.g., `0.5`) with the `ignore_done_already` setting can be used to filter
+  --- out short-lived progress tasks, de-cluttering notifications.
   ---
-  ---@type number
-  poll_rate = 5,
+  --- Note that if too many LSP progress messages are sent between polls,
+  --- Neovim's progress ring buffer will overflow and messages will be
+  --- overwritten (dropped), possibly causing stale progress notifications.
+  --- Workarounds include using the `progress.lsp.progress_ringbuf_size` option,
+  --- or manually calling `fidget.notification.reset()` (see #167).
+  ---
+  --- Set to `false` to disable polling altogether; you can still manually poll
+  --- progress messages by calling `fidget.progress.poll()`.
+  ---
+  ---@type number|false
+  poll_rate = 0,
 
   --- Suppress new messages while in insert mode
   ---
@@ -75,9 +86,13 @@ require("fidget.options").declare(M, "progress", {
     vim.api.nvim_del_autocmd(autocmd_id)
     autocmd_id = nil
   end
-  if M.options.poll_rate > 0 then
+  if M.options.poll_rate ~= false then
     autocmd_id = M.lsp.on_progress_message(function()
-      M.poller:start_polling(M.options.poll_rate)
+      if M.options.poll_rate > 0 then
+        M.poller:start_polling(M.options.poll_rate)
+      else
+        M.poller:poll_once()
+      end
     end)
   end
 end)