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/