nvf/lib/binds.nix

{lib}: let
  inherit (lib.options) mkOption;
  inherit (lib.modules) mkIf mkDefault;
  inherit (lib.types) nullOr str;
  inherit (lib.attrsets) isAttrs mapAttrs;

  binds = rec {
    /**
    Create a silent Lua keybinding wrapped in `mkIf` to guard against null keys.

    # Type

    ```
    mkLuaBinding :: String | Null -> String -> String -> AttrSet
    ```

    # Arguments

    - `key`: The key sequence to bind, or `null` to disable.
    - `action`: Lua expression to execute on keypress.
    - `desc`: Human-readable description of the binding.

    # Example

    ```nix
    mkLuaBinding "<leader>f" "require('telescope').find_files" "Find files"
    => { "<leader>f" = { action = "require('telescope').find_files"; desc = "Find files"; lua = true; silent = true; }; }
    ```
    */
    mkLuaBinding = key: action: desc:
      mkIf (key != null) {
        "${key}" = {
          inherit action desc;
          lua = true;
          silent = true;
        };
      };

    /**
    Create a silent expression-mode Lua keybinding wrapped in `mkIf`.

    # Type

    ```
    mkExprBinding :: String | Null -> String -> String -> AttrSet
    ```

    # Arguments

    - `key`: The key sequence to bind, or `null` to disable.
    - `action`: Lua expression evaluated as a Vim expression.
    - `desc`: Human-readable description of the binding.

    # Example

    ```nix
    mkExprBinding "<C-n>" "v:count == 0 ? 'j' : 'gj'" "Smart down"
    => { "<C-n>" = { action = "v:count == 0 ? 'j' : 'gj'"; desc = "Smart down"; lua = true; silent = true; expr = true; }; }
    ```
    */
    mkExprBinding = key: action: desc:
      mkIf (key != null) {
        "${key}" = {
          inherit action desc;
          lua = true;
          silent = true;
          expr = true;
        };
      };

    /**
    Create a silent (non-Lua) keybinding wrapped in `mkIf` to guard against null keys.

    # Type

    ```
    mkBinding :: String | Null -> String -> String -> AttrSet
    ```

    # Arguments

    - `key`: The key sequence to bind, or `null` to disable.
    - `action`: Vimscript command or mapping string to execute.
    - `desc`: Human-readable description of the binding.

    # Example

    ```nix
    mkBinding "<leader>w" ":w<CR>" "Save file"
    => { "<leader>w" = { action = ":w<CR>"; desc = "Save file"; silent = true; }; }
    ```
    */
    mkBinding = key: action: desc:
      mkIf (key != null) {
        "${key}" = {
          inherit action desc;
          silent = true;
        };
      };

    /**
    Build a nullable string NixOS option suitable for storing a keybinding value.

    # Type

    ```
    mkMappingOption :: String -> String | Null -> Option
    ```

    # Arguments

    - `description`: Documentation string for the option.
    - `default`: Default key value, or `null` for no binding.

    # Example

    ```nix
    mkMappingOption "Toggle file tree" "<leader>e"
    => mkOption { type = nullOr str; default = "<leader>e"; description = "Toggle file tree"; }
    ```
    */
    mkMappingOption = description: default:
      mkOption {
        type = nullOr str;
        inherit default description;
      };

    /**
    Merge actual mapping values with their description metadata.

    Takes two attribute sets: one mapping keys to values and another mapping
    keys to `{ description }` records. Produces an attribute set mapping
    keys to `{ value; description }` records. Nesting is handled recursively.

    # Type

    ```
    addDescriptionsToMappings :: AttrSet -> AttrSet -> AttrSet
    ```

    # Arguments

    - `actualMappings`: Attribute set of key → value pairs.
    - `mappingDefinitions`: Attribute set of key → `{ description }` pairs.

    # Example

    ```nix
    addDescriptionsToMappings { someKey = "some_value"; } { someKey = { description = "Some Description"; }; }
    => { someKey = { value = "some_value"; description = "Some Description"; }; }
    ```
    */
    addDescriptionsToMappings = actualMappings: mappingDefinitions:
      mapAttrs (name: value: let
        isNested = isAttrs value;
        returnedValue =
          if isNested
          then addDescriptionsToMappings actualMappings."${name}" mappingDefinitions."${name}"
          else {
            inherit value;
            inherit (mappingDefinitions."${name}") description;
          };
      in
        returnedValue)
      actualMappings;

    /**
    Create a non-Lua keybinding from a structured binding record produced by `mkMappingOption`.

    # Type

    ```
    mkSetBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
    ```

    # Arguments

    - `binding`: Binding record with `value` (key) and `description` fields.
    - `action`: Vimscript command or mapping string to execute.

    # Example

    ```nix
    mkSetBinding { value = "<leader>w"; description = "Save file"; } ":w<CR>"
    => mkBinding "<leader>w" ":w<CR>" "Save file"
    ```
    */
    mkSetBinding = binding: action:
      mkBinding binding.value action binding.description;

    /**
    Create an expression-mode Lua keybinding from a structured binding record.

    # Type

    ```
    mkSetExprBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
    ```

    # Arguments

    - `binding`: Binding record with `value` (key) and `description` fields.
    - `action`: Lua expression evaluated as a Vim expression.

    # Example

    ```nix
    mkSetExprBinding { value = "<C-n>"; description = "Smart down"; } "v:count == 0 ? 'j' : 'gj'"
    => mkExprBinding "<C-n>" "v:count == 0 ? 'j' : 'gj'" "Smart down"
    ```
    */
    mkSetExprBinding = binding: action:
      mkExprBinding binding.value action binding.description;

    /**
    Create a silent Lua keybinding from a structured binding record.

    # Type

    ```
    mkSetLuaBinding :: { value :: String | Null; description :: String } -> String -> AttrSet
    ```

    # Arguments

    - `binding`: Binding record with `value` (key) and `description` fields.
    - `action`: Lua expression to execute on keypress.

    # Example

    ```nix
    mkSetLuaBinding { value = "<leader>f"; description = "Find files"; } "require('telescope').find_files"
    => mkLuaBinding "<leader>f" "require('telescope').find_files" "Find files"
    ```
    */
    mkSetLuaBinding = binding: action:
      mkLuaBinding binding.value action binding.description;

    /**
    Apply `mkDefault` to every value in an attribute set.

    Useful for lowering the priority of a set of option defaults so they can
    be overridden by user configuration.

    # Type

    ```
    pushDownDefault :: AttrSet -> AttrSet
    ```

    # Arguments

    - `attr`: Attribute set whose values should be wrapped with `mkDefault`.

    # Example

    ```nix
    pushDownDefault { a = true; b = "hello"; }
    => { a = mkDefault true; b = mkDefault "hello"; }
    ```
    */
    pushDownDefault = attr: mapAttrs (_: mkDefault) attr;

    /**
    Build a keymap record by merging extra options with mode, key, and action fields.

    # Type

    ```
    mkKeymap :: String -> String -> String -> AttrSet -> AttrSet
    ```

    # Arguments

    - `mode`: Vim mode string (e.g. `"n"`, `"v"`, `"i"`).
    - `key`: Key sequence to bind.
    - `action`: Action to execute on keypress.
    - `opt`: Extra options merged into the resulting record.

    # Example

    ```nix
    mkKeymap "n" "<leader>w" ":w<CR>" { silent = true; }
    => { mode = "n"; key = "<leader>w"; action = ":w<CR>"; silent = true; }
    ```
    */
    mkKeymap = mode: key: action: opt: opt // {inherit mode key action;};
  };
in
  binds