feat(completion)!: add snippet support

Detalis:
- Insert snippet completion items (both `Snippet` kind and
  `insertTextFormat`) respecting their snippet nature.
- Update `default_process_items` to not exclude items with snippet kind.

Resolve #886

Author: echasnovski

CHANGELOG.md

@@ -31,6 +31,8 @@
 
 ## mini.completion
 
+- BREAKING FEATURE: add snippet support. By default uses 'mini.snippets' to manage snippet session (if enabled, **highly recommended), falls back to `vim.snippet` on Neovim>=0.10. See "Snippets" section in `:h MiniCompletion` for more details.<br>
+  This is a breaking change mostly because items with `Snippet` kind are no longer filtered out by default.
 - FEATURE: add scrolling in info and signature window. By default can be done with `<C-f>` / `<C-b>` when target window is shown. Can be configured via `mappings.scroll_down` and `mappings.scroll_up` config options.
 - FEATURE: respect `isIncomplete` in LSP completion response and immediately force new completion request on the next key press.
 - FEATURE: both info and signature help windows now use tree-sitter highlighting:

doc/mini-completion.txt

@@ -11,7 +11,7 @@ Key design ideas:
   up) and if no result, fallback to custom action.
 
 - Managing completion is done as much with Neovim's built-in tools as
-  possible.
+  possible. |popupmenu-completion| is used to show completion suggetsions.
 
 Features:
 - Two-stage chain completion:
@@ -21,10 +21,10 @@ Features:
       LSP client (via 'textDocument/completion' request). Custom
       preprocessing of response items is possible (with
       `MiniCompletion.config.lsp_completion.process_items`), for example
-      with fuzzy matching. By default items which are not snippets and
-      directly start with completed word are kept and sorted according to
-      LSP specification. Supports `additionalTextEdits`, like auto-import
-      and others (see 'Notes').
+      with fuzzy matching. By default items directly starting with completed
+      word are kept and are sorted according to LSP specification.
+      Supports `additionalTextEdits`, like auto-import and others (see 'Notes'),
+      and snippet items (best results require |mini.snippets| dependency).
     - If first stage is not set up or resulted into no candidates, fallback
       action is executed. The most tested actions are Neovim's built-in
       insert completion (see |ins-completion|).
@@ -48,7 +48,6 @@ Features:
   (same meaning as in |complete-items|) to items.
 
 What it doesn't do:
-- Snippet expansion.
 - Many configurable sources.
 - Automatic mapping of `<CR>`, `<Tab>`, etc., as those tend to have highly
   variable user expectations. See 'Helpful mappings' for suggestions.
@@ -58,8 +57,12 @@ What it doesn't do:
 Suggested dependencies (provide extra functionality, will work without them):
 
 - Enabled |MiniIcons| module to highlight LSP kind (requires Neovim>=0.11).
-  Otherwise |MiniCompletion.default_process_items()| does not add highlighting.
+  If absent, |MiniCompletion.default_process_items()| does not add highlighting.
   Also take a look at |MiniIcons.tweak_lsp_kind()|.
+- Enabled |MiniSnippets| module for better snippet handling (much recommended).
+  If absent and custom snippet insert is not configured, |vim.snippet.expand()|
+  is used on Neovim>=0.10 (nothing extra is done on earlier versions).
+  See |MiniCompletion.default_snippet_insert()|.
 
 # Setup ~
 
@@ -74,33 +77,53 @@ You can override runtime config settings locally to buffer inside
 `vim.b.minicompletion_config` which should have same structure as
 `MiniCompletion.config`. See |mini.nvim-buffer-local-config| for more details.
 
+# Snippets ~
+
+As per LSP specification, some completion items can be supplied in the form of
+snippet - a template with both pre-defined text and places (called "tabstops")
+for user to interactively change/add text during snippet session.
+
+In 'mini.completion' items that will insert snippet have "S" symbol shown in
+the popup (as part of `menu` in |complete-items|). To actually insert a snippet:
+- Select an item via <C-n> / <C-p>. This will insert item's label (usually not
+  full snippet) first to reduce visual flicker. The full snippet text will be
+  shown in info window if LSP server doesn't provide its own info for an item.
+- Press <C-y> (|complete_CTRL-Y|) or attempt inserting a non-keyword character
+  (like <CR>; new character will be removed). It will clear text from previous
+  step, set cursor, and call `lsp_completion.snippet_insert` with snippet text.
+- Press <C-e> (|complete_CTRL-E|) to cancel snippet insert and properly end
+  completion.
+
+See |MiniCompletion.default_snippet_insert()| for overview of how to work with
+inserted snippets.
+
+Notes:
+- To stop LSP server from suggesting snippets, disable (set to `false`) the
+  following capability during LSP server start:
+  `textDocument.completion.completionItem.snippetSupport`.
+- If snippet body doesn't contain tabstops, `lsp_completion.snippet_insert`
+  is not called and text is inserted as is.
+
 # Notes ~
 
-- More appropriate, albeit slightly advanced, LSP completion setup is to set
-  it not on every `BufEnter` event (default), but on every attach of LSP
+- More appropriate (albeit slightly advanced) LSP completion setup is to set
+  it not on every |BufEnter| event (default), but on every attach of LSP
   client. To do that:
     - Use in initial config:
-    `lsp_completion = {source_func = 'omnifunc', auto_setup = false}`.
+    `lsp_completion = { source_func = 'omnifunc', auto_setup = false }`.
     - In `on_attach()` of every LSP client set 'omnifunc' option to exactly
       `v:lua.MiniCompletion.completefunc_lsp`.
 
+- The `additionalTextEdits` data can come from LSP server only in response for
+  "textDocument/resolve". For these servers select completion item and wait
+  for `config.delay.info` time plus server response time to process the request.
+
 - Uses `vim.lsp.protocol.CompletionItemKind` map in LSP step to show a readable
   version of item's kind. Modify it directly to change what is displayed.
   If you have |mini.icons| enabled, take a look at |MiniIcons.tweak_lsp_kind()|.
 
-- If you have trouble using custom (overridden) |vim.ui.input| (like from
-  'stevearc/dressing.nvim'), make automated disable of 'mini.completion'
-  for input buffer. For example, currently for 'dressing.nvim' it can be
-  with `au FileType DressingInput lua vim.b.minicompletion_disable = true`.
-
-- Support of `additionalTextEdits` tries to handle both types of servers:
-    - When `additionalTextEdits` are supplied in response to
-      'textDocument/completion' request (like currently in 'pyright').
-    - When `additionalTextEdits` are supplied in response to
-      'completionItem/resolve' request (like currently in
-      'typescript-language-server'). In this case to apply edits user needs
-      to trigger such request, i.e. select completion item and wait for
-      `MiniCompletion.config.delay.info` time plus server response time.
+- If you have trouble using custom (overridden) |vim.ui.input|, disable
+  'mini.completion' for input buffer (usually based on its 'filetype').
 
 # Comparisons ~
 
@@ -214,6 +237,11 @@ Default values:
       -- input items. Common use case is custom filter/sort.
       -- Default: `default_process_items`
       process_items = nil,
+
+      -- A function which takes a snippet as string and inserts it at cursor.
+      -- Default: `default_snippet_insert` which tries to use 'mini.snippets'
+      -- and falls back to `vim.snippet.expand` (on Neovim>=0.10).
+      snippet_insert = nil,
     },
 
     -- Fallback action as function/string. Executed in Insert mode.
@@ -301,7 +329,7 @@ No need to use it directly, everything is setup in |MiniCompletion.setup|.
 Default processing of LSP items
 
 Steps:
-- Filter out items not matching `base` and snippet items.
+- Filter out items not starting with `base`.
 - Sort by LSP specification.
 - If |MiniIcons| is enabled, add <kind_hlgroup> based on the "lsp" category.
 
@@ -312,5 +340,35 @@ Parameters ~
 Return ~
 `(table)` Array of processed items from LSP response.
 
+------------------------------------------------------------------------------
+                                       *MiniCompletion.default_snippet_insert()*
+               `MiniCompletion.default_snippet_insert`({snippet})
+Default snippet insert
+
+Order of preference:
+- Use |MiniSnippets| if set up (i.e. there is `require('mini.snippets').setup()`).
+- Use |vim.snippet.expand()| on Neovim>=0.10
+- Add snippet text at cursor as is.
+
+After snippet is inserted, user is expected to navigate/jump between dedicated
+places (tabstops) to adjust inserted text as needed:
+- |MiniSnippets| by default uses <C-l> / <C-h> to jump to next/previous tabstop.
+  Can be adjusted in `mappings` of |MiniSnippets.config|.
+- |vim.snippet| on Neovim=0.10 requires manually created mappings for jumping
+  between tabstops (see |vim.snippet.jump()|). Neovim>=0.11 sets them up
+  automatically to <Tab> / <S-Tab> (if not overridden by user).
+
+End session by navigating all the way to the last tabstop. In 'mini.snippets':
+- Also make any text edit or exit Insert mode to end the session. This allows
+  smoother navigation to previous tabstops in case of a lately spotted typo.
+- Press `<C-c>` to force session stop.
+
+Parameters ~
+{snippet} `(string)` Snippet body to insert at cursor.
+
+See also ~
+|MiniSnippets-session| if 'mini.snippets' is set up.
+|vim.snippet| for Neovim's built-in snippet engine.
+
 
  vim:tw=78:ts=8:noet:ft=help:norl: