fidget.txt

*fidget.txt* Extensible UI for Neovim notifications and LSP progress messages.

==============================================================================
Table of Contents                                   *fidget-table-of-contents*

1. Getting Started                                    |fidget-getting-started|
  - Requirements                         |fidget-getting-started-requirements|
  - Installation                         |fidget-getting-started-installation|
  - Versioning                             |fidget-getting-started-versioning|
2. Options                                                    |fidget-options|
3. Lua API                                                    |fidget-lua-api|
4. Commands                                                  |fidget-commands|
5. Highlights                                              |fidget-highlights|
6. Related Work                                          |fidget-related-work|
  - Acknowledgements                    |fidget-related-work-acknowledgements|

==============================================================================
1. Getting Started                                    *fidget-getting-started*


REQUIREMENTS                             *fidget-getting-started-requirements*

Fidget requires Neovim v0.9.0+.

If you would like to see progress notifications, you must have configured
Neovim with an LSP server that uses the `$/progress`
<https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#progress>
handler. For an up-to-date list of LSP servers this plugin is known to work
with, see this Wiki page
<https://github.com/j-hui/fidget.nvim/wiki/Known-compatible-LSP-servers>.


INSTALLATION                             *fidget-getting-started-installation*

Install this plugin using your favorite plugin manager.

See the |fidget-documentation| for `setup()` options.


LAZY ~

>lua
    {
      "j-hui/fidget.nvim",
      opts = {
        -- options
      },
    }
<


VIM-PLUG ~

>vim
    Plug 'j-hui/fidget.nvim'
    
    " Make sure the plugin is installed using :PlugInstall. Then, somewhere after plug#end():
    lua <<EOF
    require("fidget").setup {
      -- options
    }
    EOF
<


ROCKS.NVIM ~

>vim
    :Rocks install fidget.nvim
<


VERSIONING                                 *fidget-getting-started-versioning*

Fidget is actively developed on the `main` branch, and may occasionally undergo
breaking changes.

If you would like to ensure configuration/API stability, you can pin your tag
to one of the release tags <https://github.com/j-hui/fidget.nvim/releases/>.

For instance, using Lazy <https://github.com/folke/lazy.nvim>

>lua
    {
      "j-hui/fidget.nvim",
      tag = "v1.0.0", -- Make sure to update this to something recent!
      opts = {
        -- options
      },
    }
<


==============================================================================
2. Options                                                    *fidget-options*

Fidgetcan be configured by passing a table of options to the `setup()`.
Available options are shown below:

>lua
    {
      -- Options related to LSP progress subsystem
      progress = {
        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
        ignore_empty_message = false, -- Ignore new tasks that don't contain a message
        clear_on_detach =             -- Clear notification group when LSP server detaches
          function(client_id)
            local client = vim.lsp.get_client_by_id(client_id)
            return client and client.name or nil
          end,
        notification_group =          -- How to get a progress message's notification group key
          function(msg) return msg.lsp_client.name end,
        ignore = {},                  -- List of LSP servers to ignore
    
        -- Options related to how LSP progress messages are displayed as notifications
        display = {
          render_limit = 16,          -- How many LSP messages to show at once
          done_ttl = 3,               -- How long a message should persist after completion
          done_icon = "✔",            -- Icon shown when all LSP progress tasks are complete
          done_style = "Constant",    -- Highlight group for completed LSP tasks
          progress_ttl = math.huge,   -- How long a message should persist when in progress
          progress_icon =             -- Icon shown when LSP progress tasks are in progress
            { "dots" },
          progress_style =            -- Highlight group for in-progress LSP tasks
            "WarningMsg",
          group_style = "Title",      -- Highlight group for group name (LSP server name)
          icon_style = "Question",    -- Highlight group for group icons
          priority = 30,              -- Ordering priority for LSP notification group
          skip_history = true,        -- Whether progress notifications should be omitted from history
          format_message =            -- How to format a progress message
            require("fidget.progress.display").default_format_message,
          format_annote =             -- How to format a progress annotation
            function(msg) return msg.title end,
          format_group_name =         -- How to format a progress notification group's name
            function(group) return tostring(group) end,
          overrides = {               -- Override options from the default notification config
            rust_analyzer = { name = "rust-analyzer" },
          },
        },
    
        -- Options related to Neovim's built-in LSP client
        lsp = {
          progress_ringbuf_size = 0,  -- Configure the nvim's LSP progress ring buffer size
          log_handler = false,        -- Log `$/progress` handler invocations (for debugging)
        },
      },
    
      -- Options related to notification subsystem
      notification = {
        poll_rate = 10,               -- How frequently to update and render notifications
        filter = vim.log.levels.INFO, -- Minimum notifications level
        history_size = 128,           -- Number of removed messages to retain in history
        override_vim_notify = false,  -- Automatically override vim.notify() with Fidget
        configs =                     -- How to configure notification groups when instantiated
          { default = require("fidget.notification").default_config },
        redirect =                    -- Conditionally redirect notifications to another backend
          function(msg, level, opts)
            if opts and opts.on_open then
              return require("fidget.integration.nvim-notify").delegate(msg, level, opts)
            end
          end,
    
        -- Options related to how notifications are rendered as text
        view = {
          stack_upwards = true,       -- Display notification items from bottom to top
          icon_separator = " ",       -- Separator between group name and icon
          group_separator = "---",    -- Separator between notification groups
          group_separator_hl =        -- Highlight group used for group separator
            "Comment",
          render_message =            -- How to render notification messages
            function(msg, cnt)
              return cnt == 1 and msg or string.format("(%dx) %s", cnt, msg)
            end,
        },
    
        -- Options related to the notification window and buffer
        window = {
          normal_hl = "Comment",      -- Base highlight group in the notification window
          winblend = 100,             -- Background color opacity in the notification window
          border = "none",            -- Border around the notification window
          zindex = 45,                -- Stacking priority of the notification window
          max_width = 0,              -- Maximum width of the notification window
          max_height = 0,             -- Maximum height of the notification window
          x_padding = 1,              -- Padding from right edge of window boundary
          y_padding = 0,              -- Padding from bottom edge of window boundary
          align = "bottom",           -- How to align the notification window
          relative = "editor",        -- What the notification window position is relative to
        },
      },
    
      -- Options related to integrating with other plugins
      integration = {
        ["nvim-tree"] = {
          enable = true,              -- Integrate with nvim-tree/nvim-tree.lua (if installed)
        },
        ["xcodebuild-nvim"] = {
          enable = true,              -- Integrate with wojciech-kulik/xcodebuild.nvim (if installed)
        },
      },
    
      -- Options related to logging
      logger = {
        level = vim.log.levels.WARN,  -- Minimum logging level
        max_size = 10000,             -- Maximum log file size, in KB
        float_precision = 0.01,       -- Limit the number of decimals displayed for floats
        path =                        -- Where Fidget writes its logs to
          string.format("%s/fidget.nvim.log", vim.fn.stdpath("cache")),
      },
    }
<

For more details, see |fidget-option.txt|.


==============================================================================
3. Lua API                                                    *fidget-lua-api*

See |fidget-api.txt|.


==============================================================================
4. Commands                                                  *fidget-commands*

*fidget-:Fidget* *:Fidget*

Fidget exposes some of its Lua API functions through `:Fidget` sub-commands
(e.g., `:Fidget clear`), which support shell-like arguments and completion.
These sub-commands are documented below.

:Fidget clear                                           *fidget-:Fidget-clear*

    Clear active notifications

    Positional arguments: ~
        {group_key}                    (any)        group to clear


:Fidget clear_history                           *fidget-:Fidget-clear_history*

    Clear notifications history

    Flags: ~
        --before {seconds}             (number)     filter history for items updated at least this long ago
        --group_key {group_key}        (any)        clear history by group key
        --include_active {true|false}  (boolean)    whether to clear items that have not been removed (default: true)
        --include_removed {true|false} (boolean)    whether to clear items that have have been removed (default: true)
        --since {seconds}              (number)     filter history for items updated at most this long ago

    Positional arguments: ~
        {group_key}                    (any)        clear history by group key


:Fidget history                                       *fidget-:Fidget-history*

    Show notifications history

    Flags: ~
        --before {seconds}             (number)     filter history for items updated at least this long ago
        --group_key {group_key}        (any)        filter history by group key
        --include_active {true|false}  (boolean)    whether to clear items that have not been removed (default: `true`)
        --include_removed {true|false} (boolean)    whether to clear items that have have been removed (default: `true`)
        --since {seconds}              (number)     filter history for items updated at most this long ago

    Positional arguments: ~
        {group_key}                    (any)        filter history by group key


:Fidget lsp_suppress                             *fidget-:Fidget-lsp_suppress*

    Suppress LSP progress notifications

    Positional arguments: ~
        {suppress}                     (boolean)    whether to suppress (omitting this argument toggles suppression)


:Fidget suppress                                     *fidget-:Fidget-suppress*

    Suppress notification window

    Positional arguments: ~
        {suppress}                     (boolean)    whether to suppress (omitting this argument toggles suppression)



==============================================================================
5. Highlights                                              *fidget-highlights*

Rather than defining its own highlights, Fidget’s default configuration uses
built-in highlight groups that are typically overridden by custom Vim color
schemes. With any luck, these will look reasonable when rendered, but the
visual outcome will really depend on what your color scheme decided to do with
those highlight groups.

You can override these highlight groups (e.g., `icon_style`) using the
|fidget-options| shown above.


==============================================================================
6. Related Work                                          *fidget-related-work*

rcarriga/nvim-notify <https://github.com/rcarriga/nvim-notify> is first and
foremost a `vim.notify()` backend, and it also supports LSP progress
notifications
<https://github.com/rcarriga/nvim-notify/wiki/Usage-Recipes#lsp-status-updates>
(with the integration seems to have been packaged up in mrded/nvim-lsp-notify
<https://github.com/mrded/nvim-lsp-notify>).

vigoux/notifier.nvim <https://github.com/vigoux/notifier.nvim> is a
`vim.notify()` backend that comes with first-class LSP notification support.

neoclide/coc.nvim <https://github.com/neoclide/coc.nvim> provides a nice LSP
progress UI in the status line, which first inspired my desire to have this
feature for nvim-lsp.

arkav/lualine-lsp-progress <https://github.com/arkav/lualine-lsp-progress> was
the original inspiration for Fidget, and funnels LSP progress messages into
nvim-lualine/lualine.nvim <https://github.com/nvim-lualine/lualine.nvim>. I
once borrowed some of its code (though much of that code has since been
rewritten).

nvim-lua/lsp-status.nvim <https://github.com/nvim-lua/lsp-status.nvim> also
supports showing progress text, though it requires some configuration to
integrate that into their status line.


ACKNOWLEDGEMENTS                        *fidget-related-work-acknowledgements*

Most of the Fidget spinner patterns were adapted from the npm package
sindresorhus/cli-spinners <https://github.com/sindresorhus/cli-spinners>.

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: