TypeDialog/docs/tui/README.md

# TypeDialog TUI Backend

Terminal User Interface for TypeDialog powered by [Ratatui](https://ratatui.rs/).

## Overview

The TUI backend (`typedialog-tui`) provides a full-featured terminal UI with keyboard navigation, mouse support, and rich visual presentation. Built with Ratatui for interactive dashboards, system administration tools, and complex forms.

## Features

- **Full Terminal UI**: Rich interface with split panes, borders, and styling
- **Keyboard Navigation**: Vi-like bindings + arrow keys + Tab navigation
- **Mouse Support**: Click to select, scroll through options
- **Real-time Validation**: Inline error messages and field highlighting
- **RepeatingGroups**: Add/edit/delete array items with split-pane interface
- **Autocompletion**: Smart suggestions as you type
- **Custom Themes**: Color schemes and border styles

## Quick Start

### Installation

```bash
cargo build --release -p typedialog-tui
sudo cp target/release/typedialog-tui /usr/local/bin/

# Or use just
just build::tui
```

### Basic Usage

```bash
# Run a form
typedialog-tui examples/01-basic/simple_form.toml

# With specific theme
typedialog-tui --theme dark examples/form.toml

# Output to file
typedialog-tui form.toml > output.json
```

## Keyboard Shortcuts

### Global

| Key | Action |
 | ----- | -------- |
| `↑/k` | Move up |
| `↓/j` | Move down |
| `←/h` | Move left / Previous field |
| `→/l` | Move right / Next field |
| `Tab` | Next field |
| `Shift+Tab` | Previous field |
| `Enter` | Confirm / Submit |
| `Esc` | Cancel / Go back |
| `Ctrl+C` | Quit |

### Text Fields

| Key | Action |
 | ----- | -------- |
| `Ctrl+A` | Move to start |
| `Ctrl+E` | Move to end |
| `Ctrl+U` | Clear line |
| `Ctrl+K` | Delete to end |
| `Ctrl+W` | Delete word |

### Select Fields

| Key | Action |
 | ----- | -------- |
| `Space` | Toggle selection (multi-select) |
| `Enter` | Confirm selection |
| `/` | Filter options |

### RepeatingGroups

| Key | Action |
 | ----- | -------- |
| `a` | Add new item |
| `e` | Edit selected item |
| `d` | Delete selected item |
| `↑/↓` | Navigate items |
| `Enter` | Edit selected item |

## Visual Features

### Borders

```toml
[form]
border_style = "rounded"  # rounded, double, thick, or none
```

### Themes

```toml
[tui]
theme = "dark"  # dark, light, or custom
highlight_color = "cyan"
error_color = "red"
```

### Field Highlighting

- **Active field**: Highlighted border
- **Error**: Red border + error message below
- **Valid**: Green checkmark
- **Required**: Asterisk (*) after label

## Examples

### Simple Form

```toml
[[fields]]
name = "username"
field_type = "Text"
label = "Username"
required = true

[[fields]]
name = "role"
field_type = "Select"
label = "Role"
options = ["Admin", "User", "Guest"]
```

Run it:

```bash
typedialog-tui simple.toml
```

### Multi-Page Form

```toml
[[sections]]
title = "Personal Information"
[[sections.fields]]
name = "name"
field_type = "Text"

[[sections]]
title = "Account Settings"
[[sections.fields]]
name = "email"
field_type = "Text"
```

Navigate with `→/←` or `Tab`.

## RepeatingGroup features

```toml
[[fields]]
field_type = "RepeatingGroup"
name = "servers"
min_items = 1
max_items = 10

[[fields.item_fields]]
name = "hostname"
field_type = "Text"

[[fields.item_fields]]
name = "port"
field_type = "Text"
validation = "number"
```

Interface shows:

- Left pane: List of items
- Right pane: Selected item details
- Bottom: Commands (a=add, e=edit, d=delete)

## Configuration

Global TUI config in `~/.config/typedialog/tui.toml`:

```toml
[tui]
theme = "dark"
border_style = "rounded"
highlight_color = "cyan"
error_color = "red"
mouse_enabled = true

[keybindings]
submit = "Enter"
cancel = "Esc"
next_field = "Tab"
prev_field = "Shift+Tab"
```

Or per-form:

```bash
typedialog-tui form.toml --config config/tui/custom.toml
```

## Backend-Specific Features

### Split-Pane Layouts

For RepeatingGroups, the TUI uses a split-pane layout:

```text
┌─ Servers ─────┬─ Selected Server ───┐
│ • server-1    │ Hostname: server-1  │
│   server-2    │ Port: 8080          │
│   server-3    │ SSL: true           │
├───────────────┴─────────────────────┤
│ a=add  e=edit  d=delete  Enter=edit │
└──────────────────────────────────────┘
```

### Mouse Support

Click to:

- Select fields
- Toggle checkboxes
- Select from dropdowns
- Click buttons
- Scroll through long lists

Disable with:

```toml
[tui]
mouse_enabled = false
```

### Terminal Resize Handling

TUI automatically adapts to terminal size changes. Recommended minimum: 80x24.

## Use Cases

### 1. Interactive Dashboards

System monitoring dashboards with live data updates:

```bash
typedialog-tui monitoring.toml --watch
```

### 2. Configuration Wizards

Multi-step configuration with validation:

```bash
typedialog-tui setup-wizard.toml --output config.toml
```

### 3. Server Administration

SSH server management with terminal UI:

```bash
ssh admin@server 'typedialog-tui /etc/myapp/config.toml'
```

### 4. Development Tools

Interactive tools for developers:

```bash
typedialog-tui project-init.toml --format nickel > project.ncl
```

## More examples

See [examples/04-backends/tui/](../../examples/04-backends/tui/) for:

- Basic forms
- Multi-page wizards
- RepeatingGroups with split panes
- Custom themes
- Validation examples
- Integration with scripts

## Related Documentation

- [Installation](../installation.md) - Setup guide
- [Configuration](../configuration.md) - TUI configuration options
- [Field Types](../field_types.md) - Available field types
- [Examples](../../examples/04-backends/tui/) - Working examples

## Troubleshooting

### "Terminal not supported"

TUI requires a terminal with full control sequences. Most modern terminals work (iTerm2, Alacritty, Windows Terminal).

### "Display corruption"

Reset terminal:

```bash
reset
# Or
tput reset
```

### "Mouse not working"

Enable mouse support:

```toml
[tui]
mouse_enabled = true
```

### "Colors not showing"

Ensure 256-color terminal:

```bash
echo $TERM  # Should be something like xterm-256color
```

Set if needed:

```bash
export TERM=xterm-256color
```

### "Form too large for terminal"

Increase terminal size or reduce form content. Minimum recommended: 80x24.

---

**Ready to start?** See [examples/04-backends/tui/](../../examples/04-backends/tui/)