fix(keymap): disable preset keymaps with false (#1859)

Previously, setting a keymap to `{}` did not actually disable the
mapping. You can now set a keymap to `false` to explicitly disable
it. This is clearer and works as expected.

Closes #1855

---------

Co-authored-by: Liam Dyer <[email protected]>

Author: soifou

doc/configuration/keymap.md

@@ -21,7 +21,7 @@ keymap = {
   ['<Down>'] = { 'select_next', 'fallback' },
 
   -- disable a keymap from the preset
-  ['<C-e>'] = {},
+  ['<C-e>'] = false, -- or {}
 
   -- show with a list of providers
   ['<C-space>'] = { function(cmp) cmp.show({ providers = { 'snippets' } }) end },

lua/blink/cmp/config/keymap.lua

@@ -153,7 +153,7 @@
 --- When defining your own keymaps without a preset, no keybinds will be assigned automatically.
 --- @class (exact) blink.cmp.KeymapConfig
 --- @field preset? blink.cmp.KeymapPreset
---- @field [string] blink.cmp.KeymapCommand[] Table of keys => commands[]
+--- @field [string] blink.cmp.KeymapCommand[] | false Table of keys => commands[] or false to disable
 
 local keymap = {
   --- @type blink.cmp.KeymapConfig
@@ -210,12 +210,14 @@ function keymap.validate(config, is_mode)
       validation_schema[key] = {
         value,
         function(key_commands)
+          if key_commands == false then return true end
+          if type(key_commands) ~= 'table' then return false end
           for _, command in ipairs(key_commands) do
             if type(command) ~= 'function' and not vim.tbl_contains(commands, command) then return false end
           end
           return true
         end,
-        'commands must be one of: ' .. table.concat(commands, ', '),
+        'commands must be one of: ' .. table.concat(commands, ', ') .. ' or false to disable',
       }
     end
   end

lua/blink/cmp/keymap/apply.lua

@@ -12,8 +12,6 @@ function apply.keymap_to_current_buffer(keys_to_commands)
 
   -- insert mode: uses both snippet and insert commands
   for key, commands in pairs(keys_to_commands) do
-    if #commands == 0 then goto continue end
-
     local fallback = require('blink.cmp.keymap.fallback').wrap('i', key)
     apply.set('i', key, function()
       if not require('blink.cmp.config').enabled() then return fallback() end
@@ -33,13 +31,11 @@ function apply.keymap_to_current_buffer(keys_to_commands)
         end
       end
     end)
-
-    ::continue::
   end
 
   -- snippet mode: uses only snippet commands
   for key, commands in pairs(keys_to_commands) do
-    if not apply.has_snippet_commands(commands) or #commands == 0 then goto continue end
+    if not apply.has_snippet_commands(commands) then goto continue end
 
     local fallback = require('blink.cmp.keymap.fallback').wrap('s', key)
     apply.set('s', key, function()
@@ -88,7 +84,7 @@ function apply.term_keymaps(keys_to_commands)
 
   -- terminal mode: uses insert commands only
   for key, commands in pairs(keys_to_commands) do
-    if not apply.has_insert_command(commands) or #commands == 0 then goto continue end
+    if not apply.has_insert_command(commands) then goto continue end
 
     local fallback = require('blink.cmp.keymap.fallback').wrap('i', key)
     apply.set('t', key, function()
@@ -120,7 +116,7 @@ function apply.cmdline_keymaps(keys_to_commands)
 
   -- cmdline mode: uses only insert commands
   for key, commands in pairs(keys_to_commands) do
-    if not apply.has_insert_command(commands) or #commands == 0 then goto continue end
+    if not apply.has_insert_command(commands) then goto continue end
 
     local fallback = require('blink.cmp.keymap.fallback').wrap('c', key)
     apply.set('c', key, function()

lua/blink/cmp/keymap/init.lua

@@ -1,9 +1,9 @@
 local keymap = {}
 
 --- Lowercases all keys in the mappings table
---- @param existing_mappings table<string, blink.cmp.KeymapCommand[]>
---- @param new_mappings table<string, blink.cmp.KeymapCommand[]>
---- @return table<string, blink.cmp.KeymapCommand[]>
+--- @param existing_mappings table<string, blink.cmp.KeymapCommand[] | false>
+--- @param new_mappings table<string, blink.cmp.KeymapCommand[] | false>
+--- @return table<string, blink.cmp.KeymapCommand[] | false>
 function keymap.merge_mappings(existing_mappings, new_mappings)
   local merged_mappings = vim.deepcopy(existing_mappings)
   for new_key, new_mapping in pairs(new_mappings) do
@@ -28,13 +28,19 @@ end
 
 --- @param keymap_config blink.cmp.KeymapConfig
 --- @param mode blink.cmp.Mode
+--- @return table<string, blink.cmp.KeymapCommand[]>
 function keymap.get_mappings(keymap_config, mode)
   local mappings = vim.deepcopy(keymap_config)
 
-  -- Remove unused keys
+  -- Remove unused keys, but keep keys set to false or empty tables (to disable them)
   if mode ~= 'default' then
     for key, commands in pairs(mappings) do
-      if key ~= 'preset' and not require('blink.cmp.keymap.apply').has_insert_command(commands) and #commands ~= 0 then
+      if
+        key ~= 'preset'
+        and commands ~= false
+        and #commands ~= 0
+        and not require('blink.cmp.keymap.apply').has_insert_command(commands)
+      then
         mappings[key] = nil
       end
     end
@@ -51,6 +57,14 @@ function keymap.get_mappings(keymap_config, mode)
     -- User-defined keymaps overwrite the preset keymaps
     mappings = keymap.merge_mappings(preset_keymap, mappings)
   end
+  --- @cast mappings table<string, blink.cmp.KeymapCommand[] | false>
+
+  -- Remove keys explicitly disabled by user (set to false or no commands)
+  for key, commands in pairs(mappings) do
+    if commands == false or #commands == 0 then mappings[key] = nil end
+  end
+  --- @cast mappings table<string, blink.cmp.KeymapCommand[]>
+
   return mappings
 end
 

lua/blink/cmp/keymap/presets.lua

@@ -1,5 +1,7 @@
---- @type table<string, table<string, blink.cmp.KeymapCommand[]>>
-local presets = {
+local presets = {}
+
+--- @type table<string, table<string, blink.cmp.KeymapCommand[] | false>>
+local presets_keymaps = {
   none = {},
 
   default = {
@@ -86,9 +88,9 @@ local presets = {
 
 --- Gets the preset keymap for the given preset name
 --- @param name string
---- @return table<string, blink.cmp.KeymapCommand[]>
+--- @return table<string, blink.cmp.KeymapCommand[] | false>
 function presets.get(name)
-  local preset = presets[name]
+  local preset = presets_keymaps[name]
   if preset == nil then error('Invalid blink.cmp keymap preset: ' .. name) end
   return preset
 end