feat: keymaps window instead of help line

Author: chenasraf

README.md

@@ -1,23 +1,26 @@
 # input-form.nvim
 
-A small Neovim plugin for building bordered, keyboard-navigable **forms** in a
-floating window. Create a single window containing multiple typed inputs
-(single-line text, multiline text, select dropdowns), collect results via an
-`on_submit` callback.
+A small Neovim plugin for building bordered, keyboard-navigable **forms** in a floating window.
+Create a single window containing multiple typed inputs (single-line text, multiline text, select
+dropdowns, checkboxes), collect results via an `on_submit` callback.
 
 ![input form example](/input-form.gif)
 
 ## Features
 
 - Bordered floating window with optional title
 - Keyboard-navigable: `<Tab>` / `<S-Tab>` to move between inputs
-- Input types: `text`, `multiline`, `select`, `checkbox`
+- Input types: `text`, `multiline`, `select`, `checkbox`, plus `spacer` (visual-only gap between
+  fields)
 - Select dropdowns open with `<CR>`; arrows navigate; `<CR>` confirms
+- Checkbox toggles with `<Space>` or `<CR>`
 - Submit with `<C-s>` — results delivered as a `{ [name] = value }` table
-- Cancel with `<Esc>`
+- Cancel with `<Esc>` or `q`
+- Built-in toggleable help popup (`?`) listing every active keymap — updates automatically when you
+  remap keys
 - Lazy: `create_form` builds the form; `:show()` renders it when you want
 - `:hide()` / `:show()` re-open a form while preserving in-progress values
-- Fully configurable keymaps, border, width, title
+- Fully configurable keymaps (strings or lists), border, width, title
 - Auto-generated help doc (`:h input-form`)
 - Tested with `mini.test`
 
@@ -83,9 +86,8 @@ local form = f.create_form({
 form:show()
 ```
 
-`create_form` returns a form object. Nothing is rendered until you call
-`form:show()`. This lets you construct the form in one place and open it from a
-keymap, autocommand, or anywhere else:
+`create_form` returns a form object. Nothing is rendered until you call `form:show()`. This lets you
+construct the form in one place and open it from a keymap, autocommand, or anywhere else:
 
 ```lua
 vim.keymap.set("n", "<leader>xf", function()
@@ -95,19 +97,19 @@ end)
 
 ### Form methods
 
-| Method         | Description                                                      |
-| -------------- | ---------------------------------------------------------------- |
-| `form:show()`  | Open the form. No-op if already visible.                         |
-| `form:hide()`  | Close windows but keep values so `:show()` resumes where you left off. |
-| `form:close()` | Permanently tear down the form.                                  |
-| `form:submit()`| Gather values, close, and invoke `on_submit(results)`.           |
-| `form:cancel()`| Close and invoke `on_cancel()` if provided.                      |
-| `form:results()`| Return `{ [name] = value }` without closing.                    |
+| Method           | Description                                                            |
+| ---------------- | ---------------------------------------------------------------------- |
+| `form:show()`    | Open the form. No-op if already visible.                               |
+| `form:hide()`    | Close windows but keep values so `:show()` resumes where you left off. |
+| `form:close()`   | Permanently tear down the form.                                        |
+| `form:submit()`  | Gather values, close, and invoke `on_submit(results)`.                 |
+| `form:cancel()`  | Close and invoke `on_cancel()` if provided.                            |
+| `form:results()` | Return `{ [name] = value }` without closing.                           |
 
 ### Input spec reference
 
-All inputs share `name` (string, required — the key in the result table) and
-`label` (string, shown above the field).
+Most inputs share `name` (string, required — the key in the result table) and `label` (string, shown
+above the field). `spacer` is the only exception: it's visual-only and needs no `name`.
 
 #### `text`
 
@@ -121,8 +123,7 @@ All inputs share `name` (string, required — the key in the result table) and
 { name = "body", label = "Notes", type = "multiline", default = "", height = 5 }
 ```
 
-- `height` (optional) — number of rows for the input; falls back to
-  `config.multiline.height`.
+- `height` (optional) — number of rows for the input; falls back to `config.multiline.height`.
 
 #### `select`
 
@@ -147,23 +148,43 @@ All inputs share `name` (string, required — the key in the result table) and
 { name = "agree", label = "I agree", type = "checkbox", default = false }
 ```
 
-Unlike text/multiline/select, checkboxes render **inline** — no border, no
-separate label row. The glyph sits immediately next to the label, and any
-validation error is appended on the same line:
+Unlike text/multiline/select, checkboxes render **inline** — no border, no separate label row. The
+glyph sits immediately next to the label, and any validation error is appended on the same line:
 
 ```
 ☐ I agree (must be checked)
 ```
 
 - `default` (optional) — boolean (defaults to `false`).
 - `value()` returns a boolean.
-- Toggled with the configured `keymaps.toggle` key (default `<Space>`) or
-  the `keymaps.open_select` key (default `<CR>`) — both work so users get
-  a consistent "interact with this field" key.
-- Glyphs come from `style.checkbox.{checked, unchecked}` (defaults
-  `"☑"` / `"☐"`).
-- Pair with `validators.checked()` to require the box to be ticked (see
-  [Validation](#validation)).
+- Toggled with the configured `keymaps.toggle` key (default `<Space>`) or the `keymaps.open_select`
+  key (default `<CR>`) — both work so users get a consistent "interact with this field" key.
+- Glyphs come from `style.checkbox.{checked, unchecked}` (defaults `"☑"` / `"☐"`).
+- A blank row is rendered above and below each checkbox to visually separate it from adjacent
+  bordered inputs. Tune via `style.checkbox.padding` (default `1`, set to `0` to pack tight).
+- Pair with `validators.checked()` to require the box to be ticked (see [Validation](#validation)).
+
+#### `spacer`
+
+```lua
+{ type = "spacer" }             -- 1 blank row
+{ type = "spacer", height = 2 } -- 2 blank rows
+```
+
+A visual-only faux input that reserves blank rows in the layout. It has no window, no focus, no
+validator, and never appears in `results()`. Use it to group related inputs visually:
+
+```lua
+inputs = {
+  { name = "first", label = "First name", type = "text" },
+  { name = "last",  label = "Last name",  type = "text" },
+  { type = "spacer" },
+  { name = "email", label = "Email",      type = "text" },
+}
+```
+
+- `height` (optional) — number of blank rows (default `1`).
+- `<Tab>` / `<S-Tab>` skip over spacers automatically.
 
 ## Validation
 
@@ -173,16 +194,15 @@ Each input spec accepts an optional `validator` function:
 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:
+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 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.
+- **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
 
@@ -234,8 +254,8 @@ f.create_form({
 }):show()
 ```
 
-Custom validators are just functions — no need to use the builder helpers if
-you'd rather write one inline:
+Custom validators are just functions — no need to use the builder helpers if you'd rather write one
+inline:
 
 ```lua
 validator = function(value)
@@ -245,7 +265,7 @@ validator = function(value)
 end
 ```
 
-### Checkbox glyphs
+### Checkbox glyphs and padding
 
 Override the characters rendered by `checkbox` inputs via `style.checkbox`:
 
@@ -255,18 +275,30 @@ require("input-form").setup({
     checkbox = {
       checked   = "☑", -- default
       unchecked = "☐", -- default
+      padding   = 1,   -- default: blank rows above/below each checkbox
     },
   },
 })
 ```
 
-Alternatives that render well in most fonts: `[x]` / `[ ]`, `✔` / `·`,
-`●` / `○`.
+Alternatives that render well in most fonts: `[x]` / `[ ]`, `✔` / `·`, `●` / `○`. Set `padding = 0`
+to pack checkboxes flush against adjacent bordered inputs.
+
+### Help popup
+
+The form's bottom border shows a compact `? help` hint on the right. Press `?` (configurable via
+`keymaps.help`) to toggle a floating popup below the form that lists **every active keymap** — it
+reads from `config.keymaps` at render time, so if you remap `submit` to `<C-Enter>` the popup
+reflects that automatically. The popup matches the form's width, wraps long descriptions, and flips
+above the form if it would overflow the editor bottom. It only lists keys relevant to the current
+form (e.g. `toggle checkbox` only appears when a checkbox is present).
+
+Set `keymaps.help = false` to disable both the popup and the footer hint.
 
 ### Select chevrons
 
-The glyphs shown on the right side of `select` inputs to indicate the
-dropdown state are configurable under `style.chevron`:
+The glyphs shown on the right side of `select` inputs to indicate the dropdown state are
+configurable under `style.chevron`:
 
 ```lua
 require("input-form").setup({
@@ -279,22 +311,19 @@ require("input-form").setup({
 })
 ```
 
-Use whatever you like — e.g. ASCII fallbacks for terminals without good
-Unicode support:
+Use whatever you like — e.g. ASCII fallbacks for terminals without good Unicode support:
 
 ```lua
 style = { chevron = { closed = " v", open = " ^" } }
 ```
 
-A leading space is recommended so the glyph doesn't sit flush against the
-label.
+A leading space is recommended so the glyph doesn't sit flush against the label.
 
 ### Highlight groups
 
-All highlight groups the plugin uses are listed under `style.highlights` in
-the config and can be overridden via `setup()`. Each entry is passed directly
-to `vim.api.nvim_set_hl(0, name, spec)`, so anything `nvim_set_hl` accepts
-works (`fg`, `bg`, `link`, `bold`, `italic`, `default`, etc.).
+All highlight groups the plugin uses are listed under `style.highlights` in the config and can be
+overridden via `setup()`. Each entry is passed directly to `vim.api.nvim_set_hl(0, name, spec)`, so
+anything `nvim_set_hl` accepts works (`fg`, `bg`, `link`, `bold`, `italic`, `default`, etc.).
 
 ```lua
 require("input-form").setup({
@@ -320,7 +349,7 @@ Available groups:
 | `InputFormNormal`           | Parent form window background                |
 | `InputFormBorder`           | Parent form border                           |
 | `InputFormTitle`            | Parent form title                            |
-| `InputFormHelp`             | Footer help line (key hints)                 |
+| `InputFormHelp`             | Footer `? help` hint on the form border      |
 | `InputFormField`            | Individual input field background            |
 | `InputFormFieldBorder`      | Individual input field border                |
 | `InputFormFieldTitle`       | Individual input field label (on top border) |
@@ -330,11 +359,10 @@ Available groups:
 | `InputFormDropdown`         | Select dropdown background                   |
 | `InputFormDropdownActive`   | Highlighted dropdown row                     |
 
-User overrides fully **replace** the default spec per group (they are not
-deep-merged at the field level), so you don't need to re-specify
-`default = true`. Highlights are re-applied on every `form:show()`, so a
-`setup({ style = { highlights = ... } })` call that happens after the first
-form has been rendered still takes effect on the next open.
+User overrides fully **replace** the default spec per group (they are not deep-merged at the field
+level), so you don't need to re-specify `default = true`. Highlights are re-applied on every
+`form:show()`, so a `setup({ style = { highlights = ... } })` call that happens after the first form
+has been rendered still takes effect on the next open.
 
 ## Configuration
 
@@ -352,37 +380,48 @@ require("input-form").setup({
     gap = 0,               -- blank rows between adjacent inputs
   },
   keymaps = {
+    -- Every keymap accepts either a single key string or a list of keys.
+    -- Set any value to `false` to disable.
     next = "<Tab>",
     prev = "<S-Tab>",
     submit = "<C-s>",
-    cancel = "<Esc>",
+    cancel = { "<Esc>", "q" }, -- list form: both keys cancel the form
     open_select = "<CR>",
     toggle = "<Space>",
+    help = "?",                -- toggle the help popup (set `false` to hide)
   },
   select = {
     max_height = 10,
   },
   multiline = {
     height = 5,
   },
+  style = {
+    checkbox = {
+      checked   = "☑",
+      unchecked = "☐",
+      padding   = 1, -- blank rows above/below each checkbox
+    },
+    -- ...chevron, highlights, etc. — see sections above.
+  },
 })
 ```
 
 Per-form overrides: pass `title` and/or `width` in the `create_form` spec.
 
 ## Help
 
-Help tags are registered automatically on the first `require('input-form')`,
-so `setup()` is not required for them either:
+Help tags are registered automatically on the first `require('input-form')`, so `setup()` is not
+required for them either:
 
 ```
 :h input-form
 ```
 
 ## For plugin developers — using input-form.nvim as a dependency
 
-You can depend on `input-form.nvim` from another plugin without forcing your
-users to call `setup()`. The module is safe to use immediately after require:
+You can depend on `input-form.nvim` from another plugin without forcing your users to call
+`setup()`. The module is safe to use immediately after require:
 
 ```lua
 -- In your plugin's code:
@@ -400,19 +439,18 @@ input_form.create_form({
 
 Key points:
 
-- **No `setup()` required.** Defaults are loaded at module-load time and
-  `create_form` / `form:show()` work on a bare `require('input-form')`. End
-  users of your plugin don't need to know input-form.nvim exists.
-- **Per-form overrides.** Pass `title`, `width`, `on_cancel`, etc. directly in
-  the `create_form` spec — no need to mutate global config for one-off tweaks.
-- **Baseline config.** If your plugin wants a different baseline (say, a
-  non-default border style for all forms it opens), call
-  `require('input-form').setup({ ... })` once during your plugin's own
-  initialization. This is idempotent and safe to call even if the end user
-  has already called setup — later calls deep-merge over earlier ones.
-- **Respect the user.** Prefer per-form overrides over global `setup()` when
-  possible so you don't stomp on a user who has configured input-form.nvim
-  for their own keymaps or other plugins that use it.
+- **No `setup()` required.** Defaults are loaded at module-load time and `create_form` /
+  `form:show()` work on a bare `require('input-form')`. End users of your plugin don't need to know
+  input-form.nvim exists.
+- **Per-form overrides.** Pass `title`, `width`, `on_cancel`, etc. directly in the `create_form`
+  spec — no need to mutate global config for one-off tweaks.
+- **Baseline config.** If your plugin wants a different baseline (say, a non-default border style
+  for all forms it opens), call `require('input-form').setup({ ... })` once during your plugin's own
+  initialization. This is idempotent and safe to call even if the end user has already called setup
+  — later calls deep-merge over earlier ones.
+- **Respect the user.** Prefer per-form overrides over global `setup()` when possible so you don't
+  stomp on a user who has configured input-form.nvim for their own keymaps or other plugins that use
+  it.
 - **Declaring the dep.** With lazy.nvim, add it to your `dependencies`:
   ```lua
   {

doc/input-form.txt

@@ -113,12 +113,16 @@ Default configuration for |input-form|.
       prev = "<S-Tab>",
       --- Submit the form and invoke `on_submit(results)`.
       submit = "<C-s>",
-      --- Cancel the form and invoke `on_cancel()` if provided.
-      cancel = "<Esc>",
+      --- Cancel the form and invoke `on_cancel()` if provided. Accepts a
+      --- single key string or a list of keys — all listed keys trigger cancel.
+      cancel = { "<Esc>", "q" },
       --- Open the dropdown when focused on a `select` input.
       open_select = "<CR>",
       --- Toggle the value of a `checkbox` input.
       toggle = "<Space>",
+      --- Toggle a help popup listing every active keymap. The popup opens
+      --- directly below the form window and closes on the same key.
+      help = "?",
     },
     --- Options for `select` inputs.
     select = {

lua/input-form/config.lua

@@ -37,12 +37,16 @@ M.defaults = {
     prev = "<S-Tab>",
     --- Submit the form and invoke `on_submit(results)`.
     submit = "<C-s>",
-    --- Cancel the form and invoke `on_cancel()` if provided.
-    cancel = "<Esc>",
+    --- Cancel the form and invoke `on_cancel()` if provided. Accepts a
+    --- single key string or a list of keys — all listed keys trigger cancel.
+    cancel = { "<Esc>", "q" },
     --- Open the dropdown when focused on a `select` input.
     open_select = "<CR>",
     --- Toggle the value of a `checkbox` input.
     toggle = "<Space>",
+    --- Toggle a help popup listing every active keymap. The popup opens
+    --- directly below the form window and closes on the same key.
+    help = "?",
   },
   --- Options for `select` inputs.
   select = {