feat(lua): pass keys before mapping to vim.on_key() callback (#28098)

Keys before mapping (i.e. typed keys) are passed as the second argument.

3 files changed, 18 insertions, 10 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index e02ed20644..d967e2b313 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1640,12 +1640,14 @@ vim.on_key({fn}, {ns_id})                                       *vim.on_key()*
     Note: ~
       • {fn} will be removed on error.
       • {fn} will not be cleared by |nvim_buf_clear_namespace()|
-      • {fn} will receive the keys after mappings have been evaluated
 
     Parameters: ~
-      • {fn}     (`fun(key: string)?`) Function invoked on every key press.
-                 |i_CTRL-V| Passing in nil when {ns_id} is specified removes
-                 the callback associated with namespace {ns_id}.
+      • {fn}     (`fun(key: string, typed: string)?`) Function invoked on
+                 every key press. |i_CTRL-V| {key} is the key after mappings
+                 have been applied, and {typed} is the key(s) before mappings
+                 are applied, which may be empty if {key} is produced by
+                 non-typed keys. When {fn} is nil and {ns_id} is specified,
+                 the callback associated with namespace {ns_id} is removed.
       • {ns_id}  (`integer?`) Namespace ID. If nil or 0, generates and returns
                  a new |nvim_create_namespace()| id.
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 1aee5c656b..e39cf95da9 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -354,6 +354,9 @@ The following changes to existing APIs or features add new behavior.
 
 • |vim.region()| can use a string accepted by |getpos()| as position.
 
+• |vim.on_key()| callbacks receive a second argument for keys typed before
+  mappings are applied.
+
 • |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix
   option, which allows for rendering e.g., diagnostic severities differently.
 
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index f527fc194c..18f6cfa4ba 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -654,11 +654,14 @@ local on_key_cbs = {} --- @type table<integer,function>
 ---
 ---@note {fn} will be removed on error.
 ---@note {fn} will not be cleared by |nvim_buf_clear_namespace()|
----@note {fn} will receive the keys after mappings have been evaluated
 ---
----@param fn fun(key: string)? Function invoked on every key press. |i_CTRL-V|
----                   Passing in nil when {ns_id} is specified removes the
----                   callback associated with namespace {ns_id}.
+---@param fn fun(key: string, typed: string)?
+---                   Function invoked on every key press. |i_CTRL-V|
+---                   {key} is the key after mappings have been applied, and
+---                   {typed} is the key(s) before mappings are applied, which
+---                   may be empty if {key} is produced by non-typed keys.
+---                   When {fn} is nil and {ns_id} is specified, the callback
+---                   associated with namespace {ns_id} is removed.
 ---@param ns_id integer? Namespace ID. If nil or 0, generates and returns a
 ---                     new |nvim_create_namespace()| id.
 ---
@@ -684,11 +687,11 @@ end
 
 --- Executes the on_key callbacks.
 ---@private
-function vim._on_key(char)
+function vim._on_key(buf, typed_buf)
   local failed_ns_ids = {}
   local failed_messages = {}
   for k, v in pairs(on_key_cbs) do
-    local ok, err_msg = pcall(v, char)
+    local ok, err_msg = pcall(v, buf, typed_buf)
     if not ok then
       vim.on_key(nil, k)
       table.insert(failed_ns_ids, k)