modules/commands: support command preview

Expose nvim_create_user_command preview callbacks through userCommands so command previews can be configured declaratively instead of requiring raw setup Lua.

modules/commands.nix

@@ -48,7 +48,26 @@ let
       force = lib.nixvim.defaultNullOpts.mkBool false "Overwrite an existing user command.";
       desc = lib.nixvim.defaultNullOpts.mkStr "" "A description of the command.";
 
-      # TODO: command-preview, need to grab a function here.
+      preview = lib.nixvim.mkNullOrLuaFn' {
+        description = ''
+          Preview handler for `'inccommand'`, see `:h command-preview`.
+
+          The function is called with `opts`, `ns`, and `buf` arguments. `opts` has the same form as
+          `nvim_create_user_command()` callbacks, `ns` is the preview highlight namespace, and `buf`
+          is the preview buffer for `inccommand=split` or `nil` for `inccommand=nosplit`.
+
+          Return `0` to show no preview, `1` to show a preview without opening the preview window, or
+          `2` to open the preview window when `inccommand=split`.
+        '';
+        example = ''
+          function(opts, ns, buf)
+            if buf then
+              vim.api.nvim_buf_set_lines(buf, 0, -1, false, { opts.args })
+            end
+            return 2
+          end
+        '';
+      };
     };
   };
 in

tests/test-sources/modules/commands.nix

@@ -1,22 +1,44 @@
+{ lib }:
 {
-  example = {
-    userCommands = {
-      "W" = {
-        command = ":w<CR>";
-        desc = "Write file";
-        nargs = 0;
-      };
-      "Z" = {
-        command = ":echo fooo<CR>";
-      };
-      "InsertHere" = {
-        command.__raw = ''
-          function(opts)
-            vim.api.nvim_put({opts.args}, 'c', true, true)
-          end
-        '';
-        nargs = 1;
+  example =
+    { config, ... }:
+    {
+      userCommands = {
+        "W" = {
+          command = ":w<CR>";
+          desc = "Write file";
+          nargs = 0;
+        };
+        "Z" = {
+          command = ":echo fooo<CR>";
+        };
+        "InsertHere" = {
+          command.__raw = ''
+            function(opts)
+              vim.api.nvim_put({opts.args}, 'c', true, true)
+            end
+          '';
+          nargs = 1;
+        };
+        "PreviewHere" = {
+          command = ":echo fooo<CR>";
+          nargs = 1;
+          preview = ''
+            function(opts, ns, buf)
+              if buf then
+                vim.api.nvim_buf_set_lines(buf, 0, -1, false, { opts.args })
+              end
+              return 2
+            end
+          '';
+        };
       };
+
+      assertions = [
+        {
+          assertion = lib.hasInfix "preview = function(opts, ns, buf)" config.extraConfigLua;
+          message = "`userCommands.PreviewHere.preview` should be emitted as a lua function.";
+        }
+      ];
     };
-  };
 }