feat(api): set nvim_echo() kind for ext_messages (#33998)

Problem:  Unable to emit a message with arbitrary kind.
Solution: Add a "kind" opts field to nvim_echo().
          Use it to set the "list_cmd" kind for vim.show_pos().

runtime/doc/api.txt

@@ -653,6 +653,8 @@ nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
       • {opts}     Optional parameters.
                    • err: Treat the message like `:echoerr`. Sets `hl_group`
                      to |hl-ErrorMsg| by default.
+                   • kind: Set the |ui-messages| kind with which this message
+                     will be emitted.
                    • verbose: Message is controlled by the 'verbose' option.
                      Nvim invoked with `-V3log` will write the message to the
                      "log" file instead of standard output.

runtime/doc/news.txt

@@ -111,6 +111,7 @@ API
   actually trusted.
 • Added |vim.lsp.is_enabled()| to check if a given LSP config has been enabled
   by |vim.lsp.enable()|.
+• |nvim_echo()| can set the |ui-messages| kind with which to emit the message.
 
 BUILD
 

runtime/lua/vim/_inspector.lua

@@ -270,5 +270,5 @@ function vim.show_pos(bufnr, row, col, filter)
       },
     }
   end
-  vim.api.nvim_echo(chunks, false, {})
+  vim.api.nvim_echo(chunks, false, { kind = 'list_cmd' })
 end

runtime/lua/vim/_meta/api.lua

@@ -1101,6 +1101,7 @@ function vim.api.nvim_del_var(name) end
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
 --- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
+--- - kind: Set the `ui-messages` kind with which this message will be emitted.
 --- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
 ---   will write the message to the "log" file instead of standard output.
 function vim.api.nvim_echo(chunks, history, opts) end

runtime/lua/vim/_meta/api_keysets.lua

@@ -90,6 +90,7 @@ error('Cannot require a meta file')
 --- @class vim.api.keyset.echo_opts
 --- @field err? boolean
 --- @field verbose? boolean
+--- @field kind? string
 
 --- @class vim.api.keyset.empty
 

src/nvim/api/keysets_defs.h

@@ -332,8 +332,10 @@ typedef struct {
 } Dict(cmd_opts);
 
 typedef struct {
+  OptionalKeys is_set__echo_opts_;
   Boolean err;
   Boolean verbose;
+  String kind;
 } Dict(echo_opts);
 
 typedef struct {

src/nvim/api/vim.c

@@ -758,6 +758,7 @@ void nvim_set_vvar(String name, Object value, Error *err)
 /// @param history  if true, add to |message-history|.
 /// @param opts  Optional parameters.
 ///          - err: Treat the message like `:echoerr`. Sets `hl_group` to |hl-ErrorMsg| by default.
+///          - kind: Set the |ui-messages| kind with which this message will be emitted.
 ///          - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
 ///            will write the message to the "log" file instead of standard output.
 void nvim_echo(Array chunks, Boolean history, Dict(echo_opts) *opts, Error *err)
@@ -768,11 +769,13 @@ void nvim_echo(Array chunks, Boolean history, Dict(echo_opts) *opts, Error *err)
     goto error;
   }
 
+  char *kind = opts->kind.data;
   if (opts->verbose) {
     verbose_enter();
+  } else if (kind == NULL) {
+    kind = opts->err ? "echoerr" : history ? "echomsg" : "echo";
   }
 
-  char *kind = opts->verbose ? NULL : opts->err ? "echoerr" : history ? "echomsg" : "echo";
   msg_multihl(hl_msg, kind, history, opts->err);
 
   if (opts->verbose) {

test/functional/ui/messages_spec.lua

@@ -313,6 +313,23 @@ describe('ui/ext_messages', function()
       },
     })
 
+    feed(':call nvim_echo([["Foo"]], 1, #{ kind:"list_cmd" })<CR>')
+    screen:expect({
+      grid = [[
+        line 1                   |
+        line^                     |
+        {1:~                        }|*3
+      ]],
+      cmdline = { { abort = false } },
+      messages = {
+        {
+          content = { { 'Foo' } },
+          history = true,
+          kind = 'list_cmd',
+        },
+      },
+    })
+
     -- kind=verbose for :verbose messages
     feed(':1verbose filter Diff[AC] hi<CR>')
     screen:expect({