TypeDialog/docs/configuration.md

<div align="center">
  <img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

# Configuration Files

Pre-configured settings for each TypeDialog backend and environment.

## Overview

Configuration files are organized by **backend** (CLI, TUI, Web) and **environment** (default, dev, production).

```text
config/
├── cli/
│   ├── default.toml       # Standard CLI settings
│   ├── dev.toml           # Development (debugging enabled)
│   └── production.toml    # Production (optimized, hardened)
├── tui/
│   ├── default.toml       # Standard TUI settings
│   ├── dev.toml           # Development features enabled
│   └── production.toml    # Optimized for deployment
└── web/
    ├── default.toml       # Standard web server settings
    ├── dev.toml           # Development (hot reload)
    └── production.toml    # Hardened for production
```

## Backend Configurations

### CLI Backend

**command-line interface** - Simple text-based forms for scripts and automation.

| Config | Purpose | Debug | Colors | Timeout |
 | -------- | --------- | ------- | -------- | --------- |
| default | Standard | No | Yes | 300 s |
| dev | Development | Yes | Yes | 300 s |
| production | Production | No | Yes | 3600 s |

**Usage:**

```bash
typedialog --config config/cli/production.toml form.toml
```

**Features:**

- Inline validation
- Optional mouse support
- Placeholder text display
- Help text display

### TUI Backend

**terminal user interface** - Interactive multi-panel forms with navigation.

| Config | Purpose | Borders | Animations | Render |
 | -------- | --------- | --------- | ----------- | -------- |
| default | Standard | Rounded | Enabled | Auto |
| dev | Development | Double | Enabled | Debug |
| production | Production | Rounded | Disabled | Optimized |

**Usage:**

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

**Features:**

- 3-panel layout (fields, input, buttons)
- Mouse support
- Keyboard navigation
- Real-time field updates

### Web Backend

**HTTP server** - Browser-based forms with REST API.

| Config | Purpose | CORS | HTTPS | Rate Limit |
 | -------- | --------- | ------ | ------- | ----------- |
| default | Standard | Localhost | No | Unlimited |
| dev | Development | Enabled | No | Unlimited |
| production | Production | Restricted | Required | 100/min |

**Basic Usage:**

```bash
typedialog-web form.toml
# Server starts on http://localhost:8080
```

**With Options:**

```bash
# Load defaults from .ncl file
typedialog-web form.toml --defaults values.ncl

# Save results to file after form submission
typedialog-web form.toml --output result.json

# Combine with custom locale
typedialog-web form.toml --defaults config.ncl --output result.json --locale es-ES

# Run on custom port
typedialog-web form.toml --port 9000
```

**Features:**

- HTML/CSS rendering
- CSRF protection
- Response caching
- Gzip compression
- Array field management (RepeatingGroup)
- Default value loading from Nickel (.ncl) or JSON
- Output to file (JSON format)

## Configuration by Environment

### Development Configuration

Enabled features for development and debugging:

```toml
# CLI Dev
debug_output = true
log_level = "debug"
show_field_types = true

# TUI Dev
show_field_indices = true
trace_rendering = false

# Web Dev
hot_reload = true
debug = true
logs = "/tmp/typedialog-web.log"
```

**Usage:**

```bash
typedialog --config config/cli/dev.toml form.toml
typedialog-tui --config config/tui/dev.toml form.toml
typedialog-web --config config/web/dev.toml
```

### Production Configuration

Hardened settings optimized for deployment:

```toml
# CLI Production
debug_output = false
log_level = "error"
show_placeholders = false
timeout = 3600

# TUI Production
enable_animations = false
render_throttle = 16ms
max_fps = 60

# Web Production
require_https = true
csrf_enabled = true
rate_limit = 100
cache_ttl = 3600
```

**Usage:**

```bash
typedialog --config config/cli/production.toml form.toml
typedialog-tui --config config/tui/production.toml form.toml
typedialog-web --config config/web/production.toml
```

## Common Settings

### Form Configuration

```toml
[form]
title = "Form Title"
description = "Optional description"

[form.validation]
validate_on_change = true
show_errors_inline = true
strict_validation = true
```

### Output Configuration

```toml
[output]
format = "json"          # json, yaml, toml, text
pretty_print = true
debug_output = false
```

### Logging

```toml
[logging]
level = "info"           # debug, info, warn, error
file = "/var/log/typedialog/app.log"
```

## Custom Configuration

### Creating Custom Configurations

Create a new TOML file based on an environment template:

```bash
# Copy production config as base
cp config/cli/production.toml config/cli/custom.toml

# Edit for your needs
nano config/cli/custom.toml

# Use it
typedialog --config config/cli/custom.toml form.toml
```

### Override Specific Settings

Use environment variables to override config:

```bash
# CLI Backend
export TYPEDIALOG_DEBUG=1
export TYPEDIALOG_LOG_LEVEL=debug
typedialog --config config/cli/default.toml form.toml

# TUI Backend
export TYPEDIALOG_TUI_BORDER=double
typedialog-tui --config config/tui/default.toml form.toml

# Web Backend
export TYPEDIALOG_WEB_PORT=3000
export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com"
typedialog-web --config config/web/default.toml

# Fragment Search Paths (All Backends)
export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path/fragments"
# On Windows use semicolon separator:
# set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments
typedialog form.toml
```

**TYPEDIALOG_FRAGMENT_PATH:**

Colon-separated list (semicolon on Windows) of directories to search for fragment files.
Fragments are reusable form components loaded via `includes` directive in group definitions.

Search order:

1. Form's directory (backward compatible)
2. Directories in TYPEDIALOG_FRAGMENT_PATH (left to right)

Example:

```bash
export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.typedialog/fragments"
typedialog form.toml
```

**For complete documentation on fragment search paths, see:**
[Fragment Search Paths](./fragment-search-paths.md) - Cascading search, use cases, troubleshooting

## CLI Backend Configuration Details

```toml
[terminal]
use_raw_mode = true          # Enable raw terminal mode
enable_mouse = false         # Mouse support
use_color = true             # Colored output

[appearance]
theme = "default"            # Color theme
show_help = true             # Display field help
show_placeholders = true     # Show placeholder text

[validation]
validate_on_change = true    # Real-time validation
show_errors_inline = true    # Inline error messages

[timeout]
max_duration = 3600          # Max form time (seconds)
input_timeout = 300          # Field input timeout
```

## TUI Backend Configuration Details

```toml
[terminal]
use_raw_mode = true
enable_mouse = true
enable_scrolling = true
height = -1                  # -1 = auto
width = -1                   # -1 = auto

[ui]
show_borders = true
show_focus = true
highlight_on_hover = true
enable_animations = true

[appearance]
theme = "default"
border_style = "rounded"     # rounded, double, simple
color_scheme = "default"

[keyboard]
vi_mode = false
emacs_mode = false

[performance]
render_throttle = 16         # milliseconds
max_fps = 60                 # frames per second
```

## Web Backend Configuration Details

```toml
[server]
host = "0.0.0.0"
port = 8080
workers = 4

[html]
css_framework = "none"       # bootstrap, tailwind, none
inline_styles = false
responsive = true
dark_mode = true

[submission]
method = "post"
webhook_url = "https://api.example.com/forms"
redirect_on_success = true
redirect_url = "https://example.com/thank-you"

[security]
csrf_enabled = true
rate_limit = 100             # requests per minute
require_https = true
add_security_headers = true

[performance]
cache_static = true
cache_ttl = 3600
enable_compression = true
compression_threshold = 1024
```

## Distribution Configurations

When creating release distributions, all configurations are included:

```bash
# Build and package
just distro::build-release
just distro::create-package

# Result includes all configs
distribution/typedialog-0.1.0/
├── config/
│   ├── cli/
│   ├── tui/
│   └── web/
└── ...
```

Users can then choose configs during installation:

```bash
# Extract distribution
tar -xzf typedialog-0.1.0.tar.gz
cd typedialog-0.1.0

# Install
bash installers/install.sh

# Use specific config
typedialog --config ~/.config/typedialog/cli/production.toml form.toml
```

## Best Practices

### Development

- Use `dev` configurations for local development
- Enable debugging and verbose logging
- Use shorter timeouts for faster iteration

### Testing

- Use `default` configurations for testing
- Run integration tests with all environments

### Production

- Always use `production` configurations
- Verify HTTPS is enabled (web backend)
- Set appropriate rate limits
- Configure logging to persistent location
- Test thoroughly in staging first

## Related Documentation

- [BUILD_AND_DISTRIBUTION.md](../BUILD_AND_DISTRIBUTION.md) - Build guide
- [DISTRIBUTION_WORKFLOW.md](../DISTRIBUTION_WORKFLOW.md) - Release workflow
- [README.md](../README.md) - Main documentation