TypeDialog/docs/tui/README.md

TypeDialog TUI Backend

Terminal User Interface for TypeDialog powered by Ratatui.

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

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

# Or use just
just build::tui

Basic Usage

# 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

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

Themes

[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

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

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

Run it:

typedialog-tui simple.toml

Multi-Page Form

[[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

[[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:

[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:

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

Backend-Specific Features

Split-Pane Layouts

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

┌─ 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:

[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:

typedialog-tui monitoring.toml --watch

2. Configuration Wizards

Multi-step configuration with validation:

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

3. Server Administration

SSH server management with terminal UI:

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

4. Development Tools

Interactive tools for developers:

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

More examples

See examples/04-backends/tui/ for:

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

Related Documentation

• Installation - Setup guide
• Configuration - TUI configuration options
• Field Types - Available field types
• Examples - 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:

reset
# Or
tput reset

"Mouse not working"

Enable mouse support:

[tui]
mouse_enabled = true

"Colors not showing"

Ensure 256-color terminal:

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

Set if needed:

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/