feat: input validators

Author: chenasraf

README.md

@@ -139,6 +139,92 @@ All inputs share `name` (string, required — the key in the result table) and
 
 `value()` returns the selected `id` (not the label).
 
+## Validation
+
+Each input spec accepts an optional `validator` function:
+
+```lua
+validator = fun(value: any): string|nil
+```
+
+Return a non-empty error message string to mark the input invalid, or `nil` /
+`""` when valid. The error message is shown in the input's bottom border
+(red), and the border + label turn red too. Validation runs:
+
+- **On blur** — the first time the user leaves the field it is marked
+  "touched" and the validator runs. Nothing is shown before that.
+- **On change** — once touched, each buffer change re-runs the validator.
+- **On submit** — `form:submit()` force-validates every input (touched or
+  not). If any input has an error, submission is blocked, all errors are
+  rendered, and focus moves to the first invalid input.
+
+### Built-in validators
+
+```lua
+local V = require("input-form").validators
+
+V.non_empty([msg])                  -- require a non-empty value
+V.min_length(n, [msg])              -- at least `n` characters
+V.max_length(n, [msg])              -- at most `n` characters
+V.matches(lua_pattern, [msg])       -- match a Lua pattern
+V.is_number([msg])                  -- tonumber() must succeed
+V.one_of({ "a", "b", ... }, [msg])  -- value must be in the list
+V.custom(predicate, msg)            -- wrap a `fun(v): boolean` predicate
+V.chain(v1, v2, ...)                -- run validators in order, first error wins
+```
+
+Example:
+
+```lua
+local f = require("input-form")
+local V = f.validators
+
+f.create_form({
+  inputs = {
+    {
+      name = "id",
+      label = "Enter ID",
+      type = "text",
+      validator = V.chain(
+        V.non_empty(),
+        V.min_length(3),
+        V.matches("^[%w_-]+$", "Only letters, digits, - and _")
+      ),
+    },
+    {
+      name = "age",
+      label = "Age",
+      type = "text",
+      validator = V.chain(V.non_empty(), V.is_number()),
+    },
+  },
+  on_submit = function(results)
+    vim.print(results) -- only runs if every validator passes
+  end,
+}):show()
+```
+
+Custom validators are just functions — no need to use the builder helpers if
+you'd rather write one inline:
+
+```lua
+validator = function(value)
+  if value == "admin" then
+    return "Username 'admin' is reserved"
+  end
+end
+```
+
+### Highlight groups
+
+Error rendering uses three highlight groups. Override them to re-theme:
+
+```lua
+vim.api.nvim_set_hl(0, "InputFormFieldError",       { fg = "#ff5555" })
+vim.api.nvim_set_hl(0, "InputFormFieldErrorBorder", { fg = "#ff5555" })
+vim.api.nvim_set_hl(0, "InputFormFieldErrorTitle",  { fg = "#ff5555", bold = true })
+```
+
 ## Configuration
 
 Defaults:

doc/input-form.txt

@@ -69,6 +69,11 @@ Expose the Form class for advanced use.
                                    `M.config`
 Expose the config module.
 
+------------------------------------------------------------------------------
+                                                                  *M.validators*
+                                 `M.validators`
+Expose the built-in validator library. See |input-form.validators|.
+
 
 ==============================================================================
 ------------------------------------------------------------------------------
@@ -137,4 +142,98 @@ Return ~
 `(table)`
 
 
+==============================================================================
+------------------------------------------------------------------------------
+                                                         *input-form.validators*
+Validators for form inputs.
+
+A validator is a function `fun(value): string|nil`. It receives the
+current input value and returns a non-empty error message string when
+invalid, or `nil` / `""` when valid.
+
+This module exposes factory functions for common validators plus a
+`chain` combinator that runs several validators in order and returns the
+first error.
+
+------------------------------------------------------------------------------
+                                                                 *M.non_empty()*
+                              `M.non_empty`({msg})
+Require the field to have a non-empty value.
+Parameters ~
+{msg} `(string|nil)` Override error message.
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                *M.min_length()*
+                           `M.min_length`({n}, {msg})
+Require the value's length to be at least `n` characters.
+Parameters ~
+{n} `(integer)`
+{msg} `(string|nil)`
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                *M.max_length()*
+                           `M.max_length`({n}, {msg})
+Require the value's length to be at most `n` characters.
+Parameters ~
+{n} `(integer)`
+{msg} `(string|nil)`
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                   *M.matches()*
+                         `M.matches`({pattern}, {msg})
+Require the value to match a Lua pattern.
+Parameters ~
+{pattern} `(string)` Lua pattern (not PCRE).
+{msg} `(string|nil)`
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                 *M.is_number()*
+                              `M.is_number`({msg})
+Require the value to parse as a number.
+Parameters ~
+{msg} `(string|nil)`
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                    *M.one_of()*
+                          `M.one_of`({choices}, {msg})
+Require the value to be one of the given choices (useful for text inputs
+that must match a fixed allowlist; select inputs should use their
+`options` list instead).
+Parameters ~
+{choices} `(table)` List of allowed values.
+{msg} `(string|nil)`
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                    *M.custom()*
+                         `M.custom`({predicate}, {msg})
+Wrap a predicate `fun(value): boolean` as a validator.
+Parameters ~
+{predicate} `(function)`
+{msg} `(string)` Error message to return when the predicate is false.
+Return ~
+`(function)`
+
+------------------------------------------------------------------------------
+                                                                     *M.chain()*
+                                `M.chain`({...})
+Combine multiple validators. Runs them in order and returns the first
+non-empty error. Accepts either a list table or a varargs list.
+Parameters ~
+{...} `(function|table)`
+Return ~
+`(function)`
+
+
  vim:tw=78:ts=8:noet:ft=help:norl:

doc/tags

@@ -1,10 +1,20 @@
 Default	input-form.txt	/*Default*
 M.Form	input-form.txt	/*M.Form*
+M.chain()	input-form.txt	/*M.chain()*
 M.config	input-form.txt	/*M.config*
+M.custom()	input-form.txt	/*M.custom()*
+M.is_number()	input-form.txt	/*M.is_number()*
+M.matches()	input-form.txt	/*M.matches()*
+M.max_length()	input-form.txt	/*M.max_length()*
+M.min_length()	input-form.txt	/*M.min_length()*
+M.non_empty()	input-form.txt	/*M.non_empty()*
+M.one_of()	input-form.txt	/*M.one_of()*
+M.validators	input-form.txt	/*M.validators*
 input-form.config	input-form.txt	/*input-form.config*
 input-form.config.setup	input-form.txt	/*input-form.config.setup*
 input-form.create_form	input-form.txt	/*input-form.create_form*
 input-form.nvim	input-form.txt	/*input-form.nvim*
 input-form.setup	input-form.txt	/*input-form.setup*
+input-form.validators	input-form.txt	/*input-form.validators*
 register_helptags()	input-form.txt	/*register_helptags()*
 values:	input-form.txt	/*values:*

lua/input-form/form.lua

@@ -235,15 +235,51 @@ function M:results()
   return out
 end
 
---- Submit the form: gather values, close windows, invoke `on_submit(results)`.
+--- Submit the form: gather values, run validators, and invoke
+--- `on_submit(results)` only if everything validates. If any input has an
+--- error, submission is blocked, all inputs are force-validated (so the user
+--- sees every error, including ones on untouched fields), and focus moves to
+--- the first invalid input.
 function M:submit()
+  if self._visible and self:_validate_all() then
+    -- Validation failed — do not close, do not invoke on_submit.
+    return
+  end
   local results = self:results()
   self:hide()
   if self._on_submit then
     self._on_submit(results)
   end
 end
 
+--- Run every input's validator (marking each as touched first) and render
+--- results. Returns `true` if any input has an error.
+function M:_validate_all()
+  local any_error = false
+  local first_bad = nil
+  for i, input in ipairs(self._inputs) do
+    if input.validator then
+      input._touched = true
+      local err = input.validator(input:value())
+      if err == "" then
+        err = nil
+      end
+      input._error = err
+      self:_render_validation(input)
+      if err and not first_bad then
+        first_bad = i
+      end
+      if err then
+        any_error = true
+      end
+    end
+  end
+  if first_bad then
+    self:_focus(first_bad)
+  end
+  return any_error
+end
+
 --- Cancel the form: close windows, invoke `on_cancel()` if provided.
 function M:cancel()
   self:hide()
@@ -252,6 +288,112 @@ function M:cancel()
   end
 end
 
+--- Install validation autocmds for an input. No-op if the input has no
+--- validator. Validation runs:
+---   - on `WinLeave` (blurring the field marks it touched and validates)
+---   - on `TextChanged` / `TextChangedI` IF the input is already touched
+---
+--- For `select` inputs, the user "touches" the field by picking an option;
+--- `_render_display`'s `nvim_buf_set_lines` call also fires `TextChanged`
+--- so the same path handles re-validation there.
+function M:_install_validation(input)
+  if not input.validator then
+    return
+  end
+  local buf = input.buf
+  if not buf then
+    return
+  end
+  local form = self
+  local group = vim.api.nvim_create_augroup("InputFormValidate_" .. tostring(buf), { clear = true })
+  input._val_group = group
+
+  vim.api.nvim_create_autocmd("WinLeave", {
+    group = group,
+    buffer = buf,
+    callback = function()
+      input._touched = true
+      form:_validate_input(input)
+    end,
+  })
+
+  vim.api.nvim_create_autocmd({ "TextChanged", "TextChangedI" }, {
+    group = group,
+    buffer = buf,
+    callback = function()
+      if input._touched then
+        form:_validate_input(input)
+      end
+    end,
+  })
+
+  -- For `select` inputs, changes happen while the dropdown buffer is current,
+  -- so `TextChanged` on the display buffer doesn't fire. The input exposes an
+  -- `_on_change` hook that we use to mark it touched and re-validate.
+  input._on_change = function()
+    input._touched = true
+    form:_validate_input(input)
+  end
+end
+
+--- Run the validator for one input and update its visual error state.
+function M:_validate_input(input)
+  if not input.validator then
+    return
+  end
+  local err = input.validator(input:value())
+  if err == "" then
+    err = nil
+  end
+  input._error = err
+  self:_render_validation(input)
+end
+
+--- Apply/clear the red border, title, and footer error message on an input's
+--- floating window based on its current `_error` state.
+function M:_render_validation(input)
+  local win = input.win
+  if not (win and vim.api.nvim_win_is_valid(win)) then
+    return
+  end
+  local has_error = input._error ~= nil
+
+  if has_error then
+    vim.wo[win].winhl = table.concat({
+      "NormalFloat:InputFormField",
+      "FloatBorder:InputFormFieldErrorBorder",
+      "FloatTitle:InputFormFieldErrorTitle",
+      "FloatFooter:InputFormFieldError",
+    }, ",")
+  else
+    vim.wo[win].winhl = table.concat({
+      "NormalFloat:InputFormField",
+      "FloatBorder:InputFormFieldBorder",
+      "FloatTitle:InputFormFieldTitle",
+    }, ",")
+  end
+
+  -- Footer (error message) requires nvim 0.10+.
+  if vim.fn.has("nvim-0.10") == 1 then
+    local ok, cfg = pcall(vim.api.nvim_win_get_config, win)
+    if ok and cfg and cfg.relative ~= "" then
+      if has_error then
+        -- Truncate to window width with an ellipsis.
+        local max_w = (cfg.width or 0) - 2
+        local msg = input._error
+        if max_w > 3 and vim.fn.strdisplaywidth(msg) > max_w then
+          msg = vim.fn.strcharpart(msg, 0, max_w - 1) .. "…"
+        end
+        cfg.footer = " " .. msg .. " "
+        cfg.footer_pos = "left"
+      else
+        cfg.footer = ""
+      end
+      pcall(vim.api.nvim_win_set_config, win, cfg)
+    end
+  end
+end
+
 --- Build a help-line string describing the active keymaps.
 function M:_help_line()
   local km = config.options.keymaps