plugins/oil: switch to mkNeovimPlugin + update options

plugins/utils/oil.nix

@@ -5,224 +5,146 @@
   pkgs,
   ...
 }:
-with lib; let
+with lib;
-  cfg = config.plugins.oil;
+  helpers.neovim-plugin.mkNeovimPlugin config {
+    name = "oil";
+    originalName = "oil.nvim";
+    defaultPackage = pkgs.vimPlugins.oil-nvim;
 
-  fractionType = types.numbers.between 0.0 1.0;
+    maintainers = [maintainers.GaetanLepage];
 
-  mkSizeOption =
+    # TODO introduced 2024-03-18: remove 2024-05-18
-    helpers.defaultNullOpts.mkNullable
+    deprecateExtraOptions = true;
-    (with types;
+    optionsRenamedToSettings = [
+      "defaultFileExplorer"
+      ["bufOptions" "buflisted"]
+      ["bufOptions" "bufhidden"]
+      ["winOptions" "wrap"]
+      ["winOptions" "signcolumn"]
+      ["winOptions" "cursorcolumn"]
+      ["winOptions" "foldcolumn"]
+      ["winOptions" "spell"]
+      ["winOptions" "list"]
+      ["winOptions" "conceallevel"]
+      ["winOptions" "concealcursor"]
+      "deleteToTrash"
+      "skipConfirmForSimpleEdits"
+      "promptSaveOnSelectNewEntry"
+      "cleanupDelayMs"
+      "keymaps"
+      "useDefaultKeymaps"
+      ["viewOptions" "showHidden"]
+      ["viewOptions" "isHiddenFile"]
+      ["viewOptions" "isAlwaysHidden"]
+      ["float" "padding"]
+      ["float" "maxWidth"]
+      ["float" "maxHeight"]
+      ["float" "border"]
+      ["float" "winOptions" "winblend"]
+      ["preview" "maxWidth"]
+      ["preview" "minWidth"]
+      ["preview" "width"]
+      ["preview" "maxHeight"]
+      ["preview" "minHeight"]
+      ["preview" "height"]
+      ["preview" "border"]
+      ["preview" "winOptions" "winblend"]
+      ["progress" "maxWidth"]
+      ["progress" "minWidth"]
+      ["progress" "width"]
+      ["progress" "maxHeight"]
+      ["progress" "minHeight"]
+      ["progress" "height"]
+      ["progress" "border"]
+      ["progress" "winOptions" "winblend"]
+      ["progress" "minimizedBorder"]
+    ];
+    imports = let
+      basePluginPath = ["plugins" "oil"];
+      settingsPath = basePluginPath ++ ["settings"];
+    in [
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["columns"])
+        "Use `plugins.oil.settings.columns` instead but beware, the format has changed."
+      )
+      (
+        mkRenamedOptionModule
+        (basePluginPath ++ ["lspRenameAutosave"])
+        (settingsPath ++ ["lsp_file_method" "autosave_changes"])
+      )
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["trashCommand"])
+        "This option has been deprecated by upstream."
+      )
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["restoreWinOptions"])
+        "This option has been deprecated by upstream."
+      )
+    ];
+
+    settingsOptions = let
+      dimensionType = with types;
         oneOf [
-        int
+          ints.unsigned
-        fractionType
+          (numbers.between 0.0 1.0)
-        (listOf (either int fractionType))
+          (
-      ]);
+            listOf
-
+            (
-  commonWindowOptions = {
+              either
-    maxWidth = mkSizeOption "0.9" ''
+              ints.unsigned
-      Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+              (numbers.between 0.0 1.0)
-      Can be a single value or a list of mixed integer/float types.
+            )
-      maxWidth = [100 0.8] means "the lesser of 100 columns or 80% of total".
+          )
-    '';
+        ];
-
-    minWidth = mkSizeOption "[40 0.4]" ''
-      Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
-      Can be a single value or a list of mixed integer/float types.
-      minWidth = [40 0.4] means "the greater of 40 columns or 40% of total".
-    '';
-
-    width =
-      helpers.mkNullOrOption (with types; either int fractionType)
-      "Optionally define an integer/float for the exact width of the preview window.";
-
-    maxHeight = mkSizeOption "0.9" ''
-      Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
-      Can be a single value or a list of mixed integer/float types.
-      maxHeight = [80 0.9] means "the lesser of 80 columns or 90% of total".
-    '';
-
-    minHeight = mkSizeOption "[5 0.1]" ''
-      Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
-      Can be a single value or a list of mixed integer/float types.
-      minHeight = [5 0.1] means "the greater of 5 columns or 10% of total".
-    '';
-
-    height =
-      helpers.mkNullOrOption (with types; either int fractionType)
-      "Optionally define an integer/float for the exact height of the preview window.";
-
-    border = helpers.defaultNullOpts.mkBorder "rounded" "oil" "";
-
-    winOptions = {
-      winblend = helpers.defaultNullOpts.mkInt 0 "";
-    };
-  };
     in {
-  options.plugins.oil =
+      default_file_explorer = helpers.defaultNullOpts.mkBool true ''
-    helpers.neovim-plugin.extraOptionsOptions
+        Oil will take over directory buffers (e.g. `vim .` or `:e src/`).
-    // {
+        Set to false if you still want to use netrw.
-      enable = mkEnableOption "oil";
-
-      package = helpers.mkPackageOption "oil" pkgs.vimPlugins.oil-nvim;
-
-      columns = let
-        highlightsOption = helpers.mkNullOrOption (with types; either str helpers.nixvimTypes.rawLua) ''
-          A string or a lua function (`fun(value: string): string`).
-          Highlight group, or function that returns a highlight group.
       '';
 
-        formatOption = helpers.mkNullOrOption types.str "Format string (see :help strftime)";
+      columns = mkOption {
-      in {
+        type = with helpers.nixvimTypes;
-        type = {
+          listOf
-          enable = mkOption {
+          (
-            type = types.bool;
+            oneOf
-            default = false;
+            [
+              str
+              (attrsOf anything)
+              rawLua
+            ]
+          );
+        default = [];
         description = ''
-              Whether to enable the type column.
+          Columns can be specified as a string to use default arguments (e.g. `"icon"`),
-              The type of the entry (file, directory, link, etc).
+          or as a table to pass parameters (e.g. `{"size", highlight = "Special"}`)
 
-              Adapters: *
+          Default: `["icon"]`
         '';
-          };
+        example = [
-
+          "type"
-          highlight = highlightsOption;
+          {
-
+            __unkeyed = "icon";
-          icons = helpers.mkNullOrOption (with types; attrsOf str) ''
+            highlight = "Foo";
-            Mapping of entry type to icon.
+            default_file = "bar";
-          '';
+            directory = "dir";
-        };
+          }
-
+          "size"
-        icon = {
+          "permissions"
-          enable = mkOption {
+        ];
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the icon column.
-              An icon for the entry's type (requires nvim-web-devicons).
-
-              Adapters: *
-            '';
-          };
-
-          highlight = highlightsOption;
-
-          defaultFile = helpers.mkNullOrOption types.str ''
-            Fallback icon for files when nvim-web-devicons returns nil.
-          '';
-
-          directory = helpers.mkNullOrOption types.str "Icon for directories.";
-        };
-
-        size = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the size column.
-              The size of the file.
-
-              Adapters: files, ssh
-            '';
-          };
-
-          highlight = highlightsOption;
-        };
-
-        permissions = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the perimissions column.
-              Access permissions of the file.
-
-              Adapters: files, ssh
-              Editable: this column is read/write
-            '';
-          };
-
-          highlight = highlightsOption;
-        };
-
-        ctime = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the ctime column.
-              Change timestamp of the file.
-
-              Adapters: files
-            '';
-          };
-
-          highlight = highlightsOption;
-
-          format = formatOption;
-        };
-
-        mtime = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the mtime column.
-              Last modified time of the file.
-
-              Adapters: files
-            '';
-          };
-
-          highlight = highlightsOption;
-
-          format = formatOption;
-        };
-
-        atime = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the atime column.
-              Last access time of the file.
-
-              Adapters: files
-            '';
-          };
-
-          highlight = highlightsOption;
-
-          format = formatOption;
-        };
-
-        birthtime = {
-          enable = mkOption {
-            type = types.bool;
-            default = false;
-            description = ''
-              Whether to enable the birthtime column.
-              The time the file was created.
-
-              Adapters: files
-            '';
-          };
-
-          highlight = highlightsOption;
-
-          format = formatOption;
-        };
       };
 
       # Buffer-local options to use for oil buffers
-      bufOptions = {
+      buf_options = {
         buflisted = helpers.defaultNullOpts.mkBool false "";
 
         bufhidden = helpers.defaultNullOpts.mkStr "hide" "";
       };
 
       # Window-local options to use for oil buffers
-      winOptions = {
+      win_options = {
         wrap = helpers.defaultNullOpts.mkBool false "";
 
         signcolumn = helpers.defaultNullOpts.mkStr "no" "";
@@ -235,75 +157,123 @@ in {
 
         list = helpers.defaultNullOpts.mkBool false "";
 
-        conceallevel = helpers.defaultNullOpts.mkInt 3 "";
+        conceallevel = helpers.defaultNullOpts.mkUnsignedInt 3 "";
 
-        concealcursor = helpers.defaultNullOpts.mkStr "n" "";
+        concealcursor = helpers.defaultNullOpts.mkStr "nvic" "";
       };
 
-      defaultFileExplorer =
+      delete_to_trash = helpers.defaultNullOpts.mkBool false ''
-        helpers.defaultNullOpts.mkBool true
+        Deleted files will be removed with the trash_command (below).
-        "Oil will take over directory buffers (e.g. `vim .` or `:e src/`.";
-
-      restoreWinOptions =
-        helpers.defaultNullOpts.mkBool true
-        "Restore window options to previous values when leaving an oil buffer";
-
-      skipConfirmForSimpleEdits =
-        helpers.defaultNullOpts.mkBool false
-        "Skip the confirmation popup for simple operations.";
-
-      deleteToTrash =
-        helpers.defaultNullOpts.mkBool false
-        "Deleted files will be removed with the trash_command (below).";
-
-      trashCommand =
-        helpers.defaultNullOpts.mkStr "trash-put"
-        "Change this to customize the command used when deleting to trash.";
-
-      promptSaveOnSelectNewEntry =
-        helpers.defaultNullOpts.mkBool true
-        "Selecting a new/moved/renamed file or directory will prompt you to save changes first.";
-
-      cleanupDelayMs =
-        helpers.defaultNullOpts.mkNullable
-        (types.either types.int (types.enum [false]))
-        "2000" ''
-          Oil will automatically delete hidden buffers after this delay.
-          You can set the delay to false to disable cleanup entirely.
-          Note that the cleanup process only starts when none of the oil buffers are currently displayed
       '';
 
-      lspRenameAutosave =
+      skip_confirm_for_simple_edits = helpers.defaultNullOpts.mkBool false ''
+        Skip the confirmation popup for simple operations.
+      '';
+
+      prompt_save_on_select_new_entry = helpers.defaultNullOpts.mkBool true ''
+        Selecting a new/moved/renamed file or directory will prompt you to save changes first.
+      '';
+
+      cleanup_delay_ms =
         helpers.defaultNullOpts.mkNullable
-        (types.either types.bool (types.enum ["unmodified"]))
+        (
-        "false"
+          with types;
-        "Set to true to autosave buffers that are updated with LSP willRenameFiles. Set to \"unmodified\" to only save unmodified buffers";
+            either
+            types.ints.unsigned
+            (enum [false])
+        )
+        "2000"
+        ''
+          Oil will automatically delete hidden buffers after this delay.
+          You can set the delay to false to disable cleanup entirely.
+          Note that the cleanup process only starts when none of the oil buffers are currently
+          displayed.
+        '';
+
+      lsp_file_method = {
+        timeout_ms = helpers.defaultNullOpts.mkUnsignedInt 1000 ''
+          Time to wait for LSP file operations to complete before skipping.
+        '';
+
+        autosave_changes = helpers.defaultNullOpts.mkNullable (with types; either bool str) "false" ''
+          Set to true to autosave buffers that are updated with LSP `willRenameFiles`.
+          Set to "unmodified" to only save unmodified buffers.
+        '';
+      };
+
+      constrain_cursor =
+        helpers.defaultNullOpts.mkNullable
+        (
+          with types;
+            either
+            str
+            (enum [false])
+        )
+        "editable"
+        ''
+          Constrain the cursor to the editable parts of the oil buffer.
+          Set to `false` to disable, or "name" to keep it on the file names.
+        '';
+
+      experimental_watch_for_changes = helpers.defaultNullOpts.mkBool false ''
+        Set to true to watch the filesystem for changes and reload oil.
+      '';
 
       keymaps =
-        helpers.defaultNullOpts.mkNullable
+        helpers.defaultNullOpts.mkAttrsOf
-        types.attrs
+        (
-        "see documentation"
+          with types;
+            oneOf
+            [
+              str
+              (attrsOf anything)
+              (enum [false])
+            ]
+        )
+        ''
+          {
+            "g?" = "actions.show_help";
+            "<CR>" = "actions.select";
+            "<C-s>" = "actions.select_vsplit";
+            "<C-h>" = "actions.select_split";
+            "<C-t>" = "actions.select_tab";
+            "<C-p>" = "actions.preview";
+            "<C-c>" = "actions.close";
+            "<C-l>" = "actions.refresh";
+            "-" = "actions.parent";
+            "_" = "actions.open_cwd";
+            "`" = "actions.cd";
+            "~" = "actions.tcd";
+            "gs" = "actions.change_sort";
+            "gx" = "actions.open_external";
+            "g." = "actions.toggle_hidden";
+            "g\\" = "actions.toggle_trash";
+          }
+        ''
         ''
           Keymaps in oil buffer.
           Can be any value that `vim.keymap.set` accepts OR a table of keymap options with a
-          `callback` (e.g. { callback = function() ... end, desc = "", nowait = true })
+          `callback` (e.g. `{ callback = function() ... end, desc = "", mode = "n" }`).
           Additionally, if it is a string that matches "actions.<name>", it will use the mapping at
-          require("oil.actions").<name>
+          `require("oil.actions").<name>`.
-
           Set to `false` to remove a keymap.
-          See :help oil-actions for a list of all available actions.
+          See `:help oil-actions` for a list of all available actions.
         '';
 
-      useDefaultKeymaps = helpers.defaultNullOpts.mkBool true ''
+      keymaps_help = helpers.defaultNullOpts.mkAttrsOf types.anything ''{border = "rounded";}'' ''
-        Set to false to disable all of the default keymaps.
+        Configuration for the floating keymaps help window.
       '';
 
-      viewOptions = {
+      use_default_keymaps = helpers.defaultNullOpts.mkBool true ''
-        showHidden = helpers.defaultNullOpts.mkBool false ''
+        Set to false to disable all of the above keymaps.
+      '';
+
+      view_options = {
+        show_hidden = helpers.defaultNullOpts.mkBool false ''
           Show files and directories that start with "."
         '';
 
-        isHiddenFile =
+        is_hidden_file =
           helpers.defaultNullOpts.mkLuaFn
           ''
             function(name, bufnr)
@@ -312,7 +282,7 @@ in {
           ''
           "This function defines what is considered a 'hidden' file.";
 
-        isAlwaysHidden =
+        is_always_hidden =
           helpers.defaultNullOpts.mkLuaFn
           ''
             function(name, bufnr)
@@ -320,127 +290,189 @@ in {
             end
           ''
           "This function defines what will never be shown, even when `show_hidden` is set.";
+
+        natural_order = helpers.defaultNullOpts.mkBool true ''
+          Sort file names in a more intuitive order for humans.
+          Is less performant, so you may want to set to `false` if you work with large directories.
+        '';
+
+        sort =
+          helpers.defaultNullOpts.mkListOf (with types; listOf str)
+          ''
+            [
+              ["type" "asc"]
+              ["name" "asc"]
+            ]
+          ''
+          ''
+            Sort order can be "asc" or "desc".
+            See `:help oil-columns` to see which columns are sortable.
+          '';
       };
 
-      # Configuration for the floating window in oil.open_float
       float = {
-        padding = helpers.defaultNullOpts.mkInt 2 "Padding around the floating window.";
+        padding = helpers.defaultNullOpts.mkUnsignedInt 2 "Padding around the floating window.";
 
-        maxWidth = helpers.defaultNullOpts.mkInt 0 "";
+        max_width = helpers.defaultNullOpts.mkUnsignedInt 0 "";
 
-        maxHeight = helpers.defaultNullOpts.mkInt 0 "";
+        max_height = helpers.defaultNullOpts.mkUnsignedInt 0 "";
 
         border = helpers.defaultNullOpts.mkBorder "rounded" "oil.open_float" "";
 
-        winOptions = {
-          winblend = helpers.defaultNullOpts.mkInt 10 "";
-        };
-      };
-
-      # Configuration for the actions floating preview window
-      preview = commonWindowOptions;
-
-      # Configuration for the floating progress window
-      progress =
-        commonWindowOptions
-        // {
-          minimizedBorder = helpers.defaultNullOpts.mkBorder "none" "oil floating progress window" "";
-        };
-    };
-
-  config = let
-    options =
-      {
-        columns = with cfg.columns;
-          (optional type.enable {
-            "__unkeyed" = "type";
-            inherit (type) highlight icons;
-          })
-          ++ (optional icon.enable {
-            "__unkeyed" = "icon";
-            inherit (icon) highlight defaultFile directory;
-          })
-          ++ (optional size.enable {
-            "__unkeyed" = "size";
-            inherit (size) highlight;
-          })
-          ++ (optional permissions.enable {
-            "__unkeyed" = "permissions";
-            inherit (permissions) highlight;
-          })
-          ++ (optional ctime.enable {
-            "__unkeyed" = "ctime";
-            inherit (ctime) highlight format;
-          })
-          ++ (optional mtime.enable {
-            "__unkeyed" = "mtime";
-            inherit (mtime) highlight format;
-          })
-          ++ (optional atime.enable {
-            "__unkeyed" = "atime";
-            inherit (atime) highlight format;
-          })
-          ++ (optional birthtime.enable {
-            "__unkeyed" = "birthtime";
-            inherit (birthtime) highlight format;
-          });
-        buf_options = cfg.bufOptions;
-        win_options = cfg.winOptions;
-        default_file_explorer = cfg.defaultFileExplorer;
-        restore_win_options = cfg.restoreWinOptions;
-        skip_confirm_for_simple_edits = cfg.skipConfirmForSimpleEdits;
-        delete_to_trash = cfg.deleteToTrash;
-        trash_command = cfg.trashCommand;
-        prompt_save_on_select_new_entry = cfg.promptSaveOnSelectNewEntry;
-        lsp_file_methods.autosave_changes = cfg.lspRenameAutosave;
-        cleanup_delay_ms = cfg.cleanupDelayMs;
-        inherit (cfg) keymaps;
-        use_default_keymaps = cfg.useDefaultKeymaps;
-        view_options = with cfg.viewOptions; {
-          show_hidden = showHidden;
-          is_hidden_file = isHiddenFile;
-          is_always_hidden = isAlwaysHidden;
-        };
-        float = with cfg.float; {
-          inherit padding;
-          max_width = maxWidth;
-          max_height = maxHeight;
-          inherit border;
-          win_options = with winOptions; {
-            inherit winblend;
-          };
-        };
-        preview = with cfg.preview; {
-          max_width = maxWidth;
-          min_width = minWidth;
-          inherit width;
-          max_height = maxHeight;
-          min_height = maxHeight;
-          inherit height border;
         win_options = {
-            inherit (winOptions) winblend;
+          winblend = helpers.defaultNullOpts.mkUnsignedInt 0 "";
         };
-        };
-        progress = with cfg.progress; {
-          max_width = maxWidth;
-          min_width = minWidth;
-          inherit width;
-          max_height = maxHeight;
-          min_height = maxHeight;
-          inherit height border;
-          minimized_border = minimizedBorder;
-          win_options = {
-            inherit (winOptions) winblend;
-          };
-        };
-      }
-      // cfg.extraOptions;
-  in
-    mkIf cfg.enable {
-      extraPlugins = [cfg.package];
 
-      extraConfigLua = ''
+        override =
-        require('oil').setup(${helpers.toLuaObject options})
+          helpers.defaultNullOpts.mkLuaFn
+          ''
+            function(conf)
+              return conf
+            end
+          ''
+          ''
+            This is the config that will be passed to `nvim_open_win`.
+            Change values here to customize the layout.
           '';
       };
+
+      preview = {
+        max_width = helpers.defaultNullOpts.mkNullable dimensionType "0.9" ''
+          Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `max_width = [100 0.8]` means "the lesser of 100 columns or 80% of total".
+        '';
+
+        min_width = helpers.defaultNullOpts.mkNullable dimensionType "[40 0.4]" ''
+          Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `min_width = [40 0.4]` means "the greater of 40 columns or 40% of total".
+        '';
+
+        width =
+          helpers.mkNullOrOption
+          (
+            with types;
+              either
+              int
+              (numbers.between 0.0 1.0)
+          )
+          "Optionally define an integer/float for the exact width of the preview window.";
+
+        max_height = helpers.defaultNullOpts.mkNullable dimensionType "0.9" ''
+          Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `max_height = [80 0.9]` means "the lesser of 80 columns or 90% of total".
+        '';
+
+        min_height = helpers.defaultNullOpts.mkNullable dimensionType "[5 0.1]" ''
+          Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `min_height = [5 0.1]` means "the greater of 5 columns or 10% of total".
+        '';
+
+        height =
+          helpers.mkNullOrOption
+          (
+            with types;
+              either
+              int
+              (numbers.between 0.0 1.0)
+          )
+          "Optionally define an integer/float for the exact height of the preview window.";
+
+        border = helpers.defaultNullOpts.mkStr "rounded" "";
+
+        win_options = {
+          winblend = helpers.defaultNullOpts.mkUnsignedInt 0 "";
+        };
+
+        update_on_cursor_moved = helpers.defaultNullOpts.mkBool true ''
+          Whether the preview window is automatically updated when the cursor is moved.
+        '';
+      };
+
+      progress = {
+        max_width = helpers.defaultNullOpts.mkNullable dimensionType "0.9" ''
+          Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `max_width = [100 0.8]` means "the lesser of 100 columns or 80% of total".
+        '';
+
+        min_width = helpers.defaultNullOpts.mkNullable dimensionType "[40 0.4]" ''
+          Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `min_width = [40 0.4]` means "the greater of 40 columns or 40% of total".
+        '';
+
+        width =
+          helpers.mkNullOrOption
+          (
+            with types;
+              either
+              int
+              (numbers.between 0.0 1.0)
+          )
+          "Optionally define an integer/float for the exact width of the preview window.";
+
+        max_height = helpers.defaultNullOpts.mkNullable dimensionType "0.9" ''
+          Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `max_height = [80 0.9]` means "the lesser of 80 columns or 90% of total".
+        '';
+
+        min_height = helpers.defaultNullOpts.mkNullable dimensionType "[5 0.1]" ''
+          Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%).
+          Can be a single value or a list of mixed integer/float types.
+          `min_height = [5 0.1]` means "the greater of 5 columns or 10% of total".
+        '';
+
+        height =
+          helpers.mkNullOrOption
+          (
+            with types;
+              either
+              int
+              (numbers.between 0.0 1.0)
+          )
+          "Optionally define an integer/float for the exact height of the preview window.";
+
+        border = helpers.defaultNullOpts.mkStr "rounded" "";
+
+        minimized_border = helpers.defaultNullOpts.mkStr "none" "";
+
+        win_options = {
+          winblend = helpers.defaultNullOpts.mkUnsignedInt 0 "";
+        };
+      };
+
+      ssh = {
+        border = helpers.defaultNullOpts.mkStr "rounded" ''
+          Configuration for the floating SSH window.
+        '';
+      };
+    };
+
+    settingsExample = {
+      columns = ["icon"];
+      view_options.show_hidden = false;
+      win_options = {
+        wrap = false;
+        signcolumn = "no";
+        cursorcolumn = false;
+        foldcolumn = "0";
+        spell = false;
+        list = false;
+        conceallevel = 3;
+        concealcursor = "ncv";
+      };
+      keymaps = {
+        "<C-c>" = false;
+        "<leader>qq" = "actions.close";
+        "<C-l>" = false;
+        "<C-r>" = "actions.refresh";
+        "y." = "actions.copy_entry_path";
+      };
+      skip_confirm_for_simple_edits = true;
+    };
   }

tests/test-sources/plugins/utils/oil.nix

@@ -3,56 +3,14 @@
     plugins.oil.enable = true;
   };
 
-  example = {
+  short-example = {
     plugins.oil = {
       enable = true;
 
-      columns = {
+      settings = {
-        type = {
+        columns = ["icon"];
-          enable = true;
+        view_options.show_hidden = false;
-          highlight = "Foo";
+        win_options = {
-          icons = {};
-        };
-        icon = {
-          enable = true;
-          highlight = "Foo";
-          defaultFile = "bar";
-          directory = "dir";
-        };
-        size = {
-          enable = true;
-          highlight = "Foo";
-        };
-        permissions = {
-          enable = true;
-          highlight = "Foo";
-        };
-        ctime = {
-          enable = true;
-          highlight = "Foo";
-          format = "format";
-        };
-        mtime = {
-          enable = true;
-          highlight = "Foo";
-          format = "format";
-        };
-        atime = {
-          enable = true;
-          highlight = "Foo";
-          format = "format";
-        };
-        birthtime = {
-          enable = true;
-          highlight = "Foo";
-          format = "format";
-        };
-      };
-      bufOptions = {
-        buflisted = false;
-        bufhidden = "hide";
-      };
-      winOptions = {
           wrap = false;
           signcolumn = "no";
           cursorcolumn = false;
@@ -60,16 +18,92 @@
           spell = false;
           list = false;
           conceallevel = 3;
-        concealcursor = "n";
+          concealcursor = "ncv";
         };
-      defaultFileExplorer = true;
+        keymaps = {
-      restoreWinOptions = true;
+          "<C-c>" = false;
-      skipConfirmForSimpleEdits = false;
+          "<leader>qq" = "actions.close";
-      deleteToTrash = false;
+          "<C-l>" = false;
-      trashCommand = "trash-put";
+          "<C-r>" = "actions.refresh";
-      promptSaveOnSelectNewEntry = true;
+          "y." = "actions.copy_entry_path";
-      lspRenameAutosave = true;
+        };
-      cleanupDelayMs = 500;
+        skip_confirm_for_simple_edits = true;
+      };
+    };
+  };
+
+  example = {
+    plugins.oil = {
+      enable = true;
+
+      settings = {
+        default_file_explorer = true;
+        columns = [
+          {
+            __unkeyed = "type";
+            highlight = "Foo";
+            icons = {};
+          }
+
+          {
+            __unkeyed = "icon";
+            highlight = "Foo";
+            defaultFile = "bar";
+            directory = "dir";
+          }
+          {
+            __unkeyed = "size";
+            highlight = "Foo";
+          }
+          {
+            __unkeyed = "permissions";
+            highlight = "Foo";
+          }
+          {
+            __unkeyed = "ctime";
+            highlight = "Foo";
+            format = "format";
+          }
+          {
+            __unkeyed = "mtime";
+            highlight = "Foo";
+            format = "format";
+          }
+          {
+            __unkeyed = "atime";
+            highlight = "Foo";
+            format = "format";
+          }
+          {
+            __unkeyed = "birthtime";
+            highlight = "Foo";
+            format = "format";
+          }
+        ];
+        buf_options = {
+          buflisted = false;
+          bufhidden = "hide";
+        };
+        win_options = {
+          wrap = false;
+          signcolumn = "no";
+          cursorcolumn = false;
+          foldcolumn = "0";
+          spell = false;
+          list = false;
+          conceallevel = 3;
+          concealcursor = "nvic";
+        };
+        delete_to_trash = false;
+        skip_confirm_for_simple_edits = false;
+        prompt_save_on_select_new_entry = true;
+        cleanup_delay_ms = 2000;
+        lsp_file_method = {
+          timeout_ms = 1000;
+          autosave_changes = true;
+        };
+        constrain_cursor = "editable";
+        experimental_watch_for_changes = false;
         keymaps = {
           "g?" = "actions.show_help";
           "<CR>" = "actions.select";
@@ -85,54 +119,72 @@
           "~" = "actions.tcd";
           "g." = "actions.toggle_hidden";
         };
-      useDefaultKeymaps = true;
+        keymaps_help = {
-      viewOptions = {
+          border = "rounded";
-        showHidden = false;
+        };
-        isHiddenFile = ''
+        use_default_keymaps = true;
+        view_options = {
+          show_hidden = false;
+          is_hidden_file = ''
             function(name, bufnr)
               return vim.startswith(name, ".")
             end
           '';
-        isAlwaysHidden = ''
+          is_always_hidden = ''
             function(name, bufnr)
               return false
             end
           '';
+          natural_order = true;
+          sort = [
+            ["type" "asc"]
+            ["name" "asc"]
+          ];
         };
         float = {
           padding = 2;
-        maxWidth = 0;
+          max_width = 0;
-        maxHeight = 0;
+          max_height = 0;
           border = "rounded";
-        winOptions = {
+          win_options = {
-          winblend = 10;
+            winblend = 0;
           };
+          override = ''
+            function(conf)
+              return conf
+            end
+          '';
         };
         preview = {
-        maxWidth = 0.9;
+          max_width = 0.9;
-        minWidth = [40 0.4];
+          min_width = [40 0.4];
           width = null;
-        maxHeight = 0.9;
+          max_height = 0.9;
-        minHeight = [5 0.1];
+          min_height = [5 0.1];
           height = null;
           border = "rounded";
-        winOptions = {
+          win_options = {
             winblend = 0;
           };
+          update_on_cursor_moved = true;
         };
         progress = {
-        maxWidth = 0.9;
+          max_width = 0.9;
-        minWidth = [40 0.4];
+          min_width = [40 0.4];
           width = null;
-        maxHeight = 0.9;
+          max_height = 0.9;
-        minHeight = [5 0.1];
+          min_height = [5 0.1];
           height = null;
           border = "rounded";
-        minimizedBorder = "none";
+          minimized_border = "none";
-        winOptions = {
+          win_options = {
             winblend = 0;
           };
         };
+        ssh = {
+          border = "rounded";
+        };
+      };
     };
   };
 }