# fed-field-editor

**Terminal form fields as subprocess building blocks.** A suite of Python
curses components — discrete inline field editors plus a form manager, a
mockup-to-form converter, and a non-interactive text companion — designed to be
called from shell scripts to build terminal UIs. No dependencies beyond the
Python 3 standard library. No build step. No package manager.

Each editor is invoked with positional arguments and CLI flags. On exit it
writes the edited value to **stdout** and an exit-reason mnemonic to **stderr**,
and returns an exit code (1–9). The calling script positions the cursor, draws
the surrounding UI, and interprets the result — the editors are components, not
applications.

## The tools

| Tool | What it is |
|------|------------|
| `fed line`  | Single-line editor with horizontal viewport scrolling. |
| `fed area`  | Multi-line editor with word wrap and vertical scrolling. |
| `fed mask`  | Masked input — pattern masks (phone/date/SSN/custom) and filter masks (int/float/hex/alpha). |
| `fed list`  | Scrollable single-select list; inline or file-based items, with character-jump search. |
| `fed check` | Checkbox group (multi-select); `Space` toggles, returns a pipe-delimited list. |
| `fed radio` | Radio group (single-select); `Space` selects, `Enter` selects-and-exits. |
| `fed form`  | Form manager hosting many fields in one process; dBASE-style `@SAY/@GET` or JSON; outputs kv / json / shell. |
| `fed make`  | Converts a visual `[...]` mockup into a `fed form` definition. |
| `fed say`   | Non-interactive positioned, colored text (the label/decoration companion; ANSI to stdout, like `tput`). |
| `fed box`   | Non-interactive box/frame/panel drawing (the frame companion to `fed say`; ANSI to stdout). |

`fed <tool> [args]` runs the matching tool. The whole suite ships as **one
self-contained `fed` file**; `fed --versions` lists the bundle and every tool.

## Two kinds of tool

This distinction is load-bearing:

- **Discrete field editors** (`line`, `area`, `mask`, `list`, `check`, `radio`)
  are **inline-only**. They draw their own field over the caller's existing
  screen and never clear or restore it — the calling script owns the surrounding
  display.
- **`fed form`** owns the whole screen: it clears on start and restores the
  caller's screen on exit (`--no-restore` keeps the final form on screen).

## Install

Download a release bundle (`.tgz` or `.zip`), unpack it, and run the bundled
installer (it needs `sudo` to write under the prefix):

```sh
tar xzf fed-field-editor-YYYYMMDD.tgz
cd fed-field-editor-YYYYMMDD
sudo ./install.sh            # installs under /usr/local by default
```

This installs the single `fed` into `<prefix>/bin/`, man pages into
`share/man/man1/`, and tldr pages into `share/tldr/pages/common/`. Override the
prefix with `PREFIX=/opt/fed ./install.sh`.

## Quick examples

```sh
# A labelled single-line field: draw the label with `fed say`, then the field.
fed say 2 0 "Name:" --color bright-white,blue
fed line 2 7 30 60 -v "Ada Lovelace"

# A phone-mask field, returning the typed digits.
fed mask 0 0 phone:classic -v "5551234567"

# A select list, returning the chosen item.
fed list 0 0 22 6 -i "Sales|Support|Engineering|Finance"

# A whole form from a definition, emitting eval-safe shell assignments.
fed form customer.def -o shell

# Turn a visual mockup into a form definition.
fed make customer.mockup
```

Every tool supports `-h` (brief usage), `--help` (full help), and `--version`.
Common flags include `-v/--val`, `-e/--exit`, `--color FG,BG`, `-r/--reverse`,
`-c/--cursor`, and `-m/--mode`. See each tool's `--help` and man page for the
full set.

## Requirements

- Python 3 (standard library only; uses `curses`).
- A real TTY — the interactive editors will not run on a pipe. (`fed say` and
  `fed make` are non-interactive and run anywhere.)

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 smisco.