TypeDialog/examples/README.md

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

# TypeDialog Examples

Complete example collection organized by feature category and backend implementation.

## Quick Start

### First Time?
Start here: [`01-basic/`](01-basic/)

```bash
# Run a simple form
cargo run --example form

# Or with a specific backend
cargo run -p typedialog-tui --example form_with_autocompletion
```

## Example Categories

### 1. **Basic Forms** → [`01-basic/`](01-basic/)
Simple form structures for getting started.
- Form fundamentals
- Sections and grouping
- Basic validation
- **Best for:** Learning the syntax, quick prototypes

### 2. **Advanced Features** → [`02-advanced/`](02-advanced/)
Conditional logic, dynamic fields, complex forms.
- Conditional visibility
- Required field rules
- State management
- **Best for:** Complex workflows, conditional UX

### 3. **Styling & Appearance** → [`03-styling/`](03-styling/)
Custom borders, themes, and visual design.
- Border styles
- Visual hierarchy
- Theme customization
- **Best for:** CLI aesthetics, branded interfaces

### 4. **Backend-Specific** → [`04-backends/`](04-backends/)
Implementation details for each backend.

| Backend | Path | Best For |
|---------|------|----------|
| **CLI** | [`04-backends/cli/`](04-backends/cli/) | Scripting, server tools, pipes |
| **TUI** | [`04-backends/tui/`](04-backends/tui/) | Interactive terminal apps, dashboards |
| **Web** | [`04-backends/web/`](04-backends/web/) | SaaS, public forms, browsers |

**Running forms by backend:**
```bash
# CLI (default)
cargo run --example form

# TUI
cargo run -p typedialog-tui --example form_with_autocompletion

# Web
cargo run -p typedialog-web -- --config form.toml
```

### 5. **Fragments & Composition** → [`05-fragments/`](05-fragments/)
Reusable components and form composition.
- Fragment templates
- Includes and inheritance
- Component libraries
- **Best for:** Large projects, DRY principle, multiple forms

### 6. **Integrations** → [`06-integrations/`](06-integrations/)
External tool integrations.

| Integration | Path |
|-------------|------|
| **Nickel** (Type-safe schemas) | [`06-integrations/nickel/`](06-integrations/nickel/) |
| **i18n** (Multi-language) | [`06-integrations/i18n/`](06-integrations/i18n/) |

### 9. **Real-World Templates** → [`09-templates/`](09-templates/)
Production-ready examples for common use cases.

| Template | Path | Use Case |
|----------|------|----------|
| **Employee Onboarding** | [`09-templates/employee_onboarding/`](09-templates/employee_onboarding/) | HR systems |
| **User Registration** | [`09-templates/user_registration/`](09-templates/user_registration/) | SaaS, apps |
| **Library Catalog** | [`09-templates/library_catalog/`](09-templates/library_catalog/) | Management systems |

## Learning Path

```
START HERE
    ↓
01-basic/ ← Understand form structure
    ↓
02-advanced/ ← Add conditional logic
    ↓
03-styling/ ← Customize appearance
    ↓
04-backends/ ← Choose your backend
    ├→ 04-backends/cli/ ← Scripting
    ├→ 04-backends/tui/ ← Interactive UX
    └→ 04-backends/web/ ← Web deployment
    ↓
05-fragments/ ← Scale to multiple forms
    ↓
06-integrations/ ← Advanced integrations
    ↓
09-templates/ ← Deploy to production
```

## Common Tasks

### Run a Basic Example
```bash
cargo run --example form
```

### Try Different Backends
```bash
# CLI
cargo run --example form

# TUI
cargo run -p typedialog-tui --example tui_survey_form

# Web
cargo run -p typedialog-web -- --config examples/04-backends/web/web_registration_form.toml
```

### Use with TOML Configuration
```bash
cargo run -p typedialog-web -- --config examples/01-basic/form_with_sections.toml
```

### Use with Rust Code
```bash
cargo run --example form_with_autocompletion
```

### Test Conditional Logic
```bash
cargo run --example conditional_required_demo
```

### Try Multi-Language Support
```bash
LANG=es cargo run --example test_i18n_form
```

## File Types

### TOML (`.toml`)
Configuration-driven forms - fastest iteration.
```bash
cargo run -p typedialog-web -- --config form.toml
```

### Rust (`.rs`)
Programmatic forms - maximum control.
```bash
cargo run --example form_example
```

### Nickel (`.ncl`)
Type-safe schema generation.
```bash
nickel eval schema.ncl > form.toml
```

## Backend Compatibility

| Feature | CLI | TUI | Web |
|---------|-----|-----|-----|
| TOML forms | ✓ | ✓ | ✓ |
| Rust code | ✓ | ✓ | - |
| Conditional fields | ✓ | ✓ | ✓ |
| Autocompletion | ✓ | ✓ | ✓ |
| Custom styling | - | ✓ | ✓ |
| Validation | ✓ | ✓ | ✓ |
| i18n support | ✓ | ✓ | ✓ |
| Fragments | ✓ | ✓ | ✓ |

## Tips

### For CLI Forms
- Use for scripts and automation
- Good for piping between tools
- Minimal dependencies

### For TUI Forms
- Create interactive dashboards
- Better UX than CLI
- Keyboard shortcuts available
- Mouse support

### For Web Forms
- Public-facing forms
- Rich styling options
- Browser validation
- Mobile-friendly
- RESTful API integration

## Troubleshooting

**"Example not found"**
- Check example is in `examples/` directory
- Use `--example` flag with cargo

**"Feature not compiled"**
- Run: `cargo build --all-features`
- Check feature flags in Cargo.toml

**"Form not displaying"**
- For web: Check terminal output for port
- For TUI: Ensure terminal supports the feature
- For CLI: Check input/output redirection

## Next Steps

1. Read the category README for your use case
2. Copy and modify an example form
3. Consult [`06-integrations/`](06-integrations/) for advanced features
4. Deploy a template from [`09-templates/`](09-templates/)
5. Integrate with your application

## Contributing Examples

To add new examples:
1. Create in appropriate category
2. Add README explaining the example
3. Include usage instructions
4. List features demonstrated
5. Provide expected output

---

**Start with:** [`01-basic/README.md`](01-basic/README.md)
**Need specific backend?** Check [`04-backends/`](04-backends/)
**Want real-world example?** See [`09-templates/`](09-templates/)