TypeDialog/examples/README.md

<div align="center">
  <img src="../assets/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
- **Array management** with RepeatingGroup fields (add/edit/delete)
- **Unique item validation** - prevent duplicate entries in arrays (all backends: CLI, TUI, Web)
- **min/max items constraints** - enforce array size limits
- **Best for:** Large projects, DRY principle, multiple forms, collections with constraints

**Key examples:**
- [`array-trackers.toml`](05-fragments/array-trackers.toml) - UDP/HTTP tracker arrays with `unique = true`
- [`fragments/tracker-udp-item.toml`](05-fragments/fragments/tracker-udp-item.toml) - UDP listener item structure
- [`fragments/tracker-http-item.toml`](05-fragments/fragments/tracker-http-item.toml) - HTTP listener item structure

**Testing RepeatingGroups:**
```bash
# CLI - Interactive menu with add/edit/delete
cargo run --example array_trackers

# TUI - Split-pane interface with keyboard shortcuts
cargo run -p typedialog-tui --example array_trackers

# Web - Inline expandable cards with live counter
cargo run -p typedialog-web -- --config examples/05-fragments/array-trackers.toml
```

### 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/) |

### 7. **Nickel Schema Generation** → [`07-nickel-generation/`](07-nickel-generation/)
Nickel type-safe schemas with TypeDialog form integration.
- Array(Record) types for collections
- RepeatingGroup field mapping to Nickel arrays
- Complex schema structures
- **Best for:** Type-safe configuration, validation, schema-driven forms

**Key examples:**
- [`arrays-schema.ncl`](07-nickel-generation/arrays-schema.ncl) - Complete schema with Array types
- [`arrays-form.toml`](07-nickel-generation/arrays-form.toml) - Form with RepeatingGroup arrays
- Fragments for: `api-endpoint-item.toml`, `user-item.toml`

### 8. **Encryption & Sensitive Data** → [`08-encryption/`](08-encryption/)
Handling sensitive fields with encryption.
- Field encryption
- Sensitive data redaction
- Encrypted storage
- **Best for:** Security-sensitive forms, PII handling

### 9. **AI Backend** → [`10-ai-backend/`](10-ai-backend/)
RAG system, knowledge graphs, and embeddings.
- RAG (Retrieval-Augmented Generation) system
- Batch document operations
- Semantic + keyword search
- Performance optimization
- **Best for:** ML-powered search, knowledge management, semantic retrieval

**Running AI examples:**
```bash
# Build AI backend
just build::ai

# Run the AI backend example
cargo run --example main --features ai_backend

# Or test AI module
just test::ai
```

### 10. **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 |

### 11. **Provisioning Generation** → [`11-prov-gen/`](11-prov-gen/)
Infrastructure as Code and configuration generation.
- Infrastructure provisioning
- Configuration management
- Resource templates
- **Best for:** DevOps automation, cloud deployment

### 12. **Agent Execution** → [`12-agent-execution/`](12-agent-execution/)
AI agent execution with multi-provider LLM support.

| Example | LLM Provider | Use Case |
|---------|--------------|----------|
| **Basic Greeting** | Claude Haiku | Simple agent introduction |
| **Code Review** | Claude Sonnet | Security & performance analysis |
| **Documentation** | GPT-4o | Generate docs from code |
| **Task Planner** | Claude Sonnet | Project planning & breakdown |
| **Local Privacy** | Ollama (local) | Privacy-first data analysis |
| **Creative Writer** | Gemini 2.0 | Creative content generation |
| **Refactoring** | GPT-4o-mini | Code refactoring assistant |
| **Architect** | Claude Opus | High-level design & ADRs |

**Features:**
- Template variables & conditionals
- File imports with glob patterns
- Shell command integration
- Output validation
- 4 LLM providers (Claude, OpenAI, Gemini, Ollama)

**Running agent examples:**
```bash
# Run an agent
cargo run --package typedialog-ag -- examples/12-agent-execution/basic-greeting.agent.mdx

# See all examples
cat examples/12-agent-execution/README.md
```

**Related:**
- [Demos](../demos/agent/) - Multi-provider comparison demos
- [Tests](../tests/agent/) - Agent validation tests
- [Core Examples](../crates/typedialog-agent/typedialog-ag-core/examples/) - Rust API usage

## 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
    ├→ array-trackers.toml ← Manage collections with RepeatingGroup
    │
06-integrations/ ← Advanced integrations
    ├→ Nickel schemas
    └→ i18n translations
    ↓
07-nickel-generation/ ← Type-safe schemas with arrays
    ├→ arrays-schema.ncl ← Array(Record) types
    └→ arrays-form.toml ← RepeatingGroup fields
    ↓
08-encryption/ ← Secure sensitive fields
    │
10-ai-backend/ ← Add AI/ML features
    ├→ RAG system for semantic search
    ├→ Batch operations for efficiency
    └→ Knowledge graph integration
    ↓
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/)