feat(snippet): set snippet keymaps permanent instead of dynamic (#31887)

Problem:

Given that `vim.snippet.expand()` sets temporary `<tab>`/`<s-tab>`
keymaps there is no way to build "smart-tab" functionality where `<tab>`
chooses the next completion candidate if the popup menu is visible.

Solution:

Set the keymap permanent in `_defaults`.

The downside of this approach is that users of multiple snippet engine's
need to adapt their keymaps to handle all their engines that are in use.
For example:

    vim.keymap.set({ 'i', 's' }, "<Tab>", function()
      if foreign_snippet.active() then
        return "<Cmd>lua require('foreign_snippet').jump()<CR>"
      elseif vim.snippet.active({ direction = 1 }) then
        return "<Cmd>lua vim.snippet.jump(1)<CR>"
      else
        return key
      end
    end, { expr = true })

Upside is that using `vim.keymap.set` to override keymaps is a well
established pattern and `vim.snippet.expand` calls made by nvim itself
or plugins have working keymaps out of the box.


Co-authored-by: Maria José Solano <majosolano99@gmail.com>

1 files changed, 3 insertions, 12 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6705768aeb..a99b050195 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -4551,16 +4551,6 @@ vim.snippet.active({filter})                            *vim.snippet.active()*
     Returns `true` if there's an active snippet in the current buffer,
     applying the given filter if provided.
 
-    You can use this function to navigate a snippet as follows: >lua
-        vim.keymap.set({ 'i', 's' }, '<Tab>', function()
-           if vim.snippet.active({ direction = 1 }) then
-             return '<Cmd>lua vim.snippet.jump(1)<CR>'
-           else
-             return '<Tab>'
-           end
-         end, { expr = true })
-<
-
     Parameters: ~
       • {filter}  (`vim.snippet.ActiveFilter?`) Filter to constrain the search
                   with:
@@ -4585,14 +4575,15 @@ vim.snippet.jump({direction})                             *vim.snippet.jump()*
     Jumps to the next (or previous) placeholder in the current snippet, if
     possible.
 
-    For example, map `<Tab>` to jump while a snippet is active: >lua
+    By default `<Tab>` is setup to jump if a snippet is active. The default
+    mapping looks like: >lua
         vim.keymap.set({ 'i', 's' }, '<Tab>', function()
            if vim.snippet.active({ direction = 1 }) then
              return '<Cmd>lua vim.snippet.jump(1)<CR>'
            else
              return '<Tab>'
            end
-         end, { expr = true })
+         end, { descr = '...', expr = true, silent = true })
 <
 
     Parameters: ~