TypeDialog/examples/05-fragments/README.md

# Form Fragments & Composition

Reusable form components, modular form building, and constraint management.

## Files

### Fragments (Reusable Components)
- **header.toml** - Header/intro section
- **custom_border_section.toml** - Styled section template
- **fancy_border_section.toml** - Advanced border styling
- **employee_info_section.toml** - Employee data fields
- **agreement_section.toml** - Legal/policy acceptance
- **support_section.toml** - Support tier selection
- **premium_section.toml** - Premium features section
- **enterprise_section.toml** - Enterprise tier section

### Examples Using Fragments
- **form_with_groups_includes.toml** - Demonstrates fragment inclusion
- **array-trackers.toml** - RepeatingGroup arrays with constraint interpolation

### Constraint Configuration
- **constraints.toml** - Single source of truth for array validation limits

## Usage Pattern

### Include Fragments in Your Forms

```toml
# main_form.toml
[includes]
header = "fragments/header.toml"
employee = "fragments/employee_info_section.toml"
agreement = "fragments/agreement_section.toml"

[sections.main]
title = "Employee Onboarding"
```

### Build Complex Forms from Reusable Parts

```bash
# Each fragment can be tested independently
cargo run --example form_with_groups_includes
```

## Constraint Interpolation Example

### What is Constraint Interpolation?

Instead of hardcoding validation limits in forms, you can use constraint variables:

```toml
# array-trackers.toml
[[elements]]
name = "udp_trackers"
type = "repeatinggroup"
max_items = "${constraint.tracker.udp.max_items}"  # ← Dynamic constraint reference
```

### Single Source of Truth

All validation limits are defined in **one file**:

```toml
# constraints.toml
[tracker.udp]
max_items = 4    # Change this value, form auto-updates!
```

### How It Works

1. **Form loads** - `array-trackers.toml` contains `"${constraint.tracker.udp.max_items}"`
2. **Parser resolves** - Form parser finds `constraints.toml` in same directory
3. **Value injected** - The constraint value (4) replaces the placeholder
4. **Form validates** - User can add up to 4 UDP trackers

### Try It

```bash
# Run the example
cargo run --example array-trackers

# The form will allow:
# - 0-4 UDP trackers (from constraints.tracker.udp.max_items)
# - 0-4 HTTP trackers (from constraints.tracker.http.max_items)

# Change constraints.toml:
#   [tracker.udp]
#   max_items = 6    # ← Change from 4 to 6
#
# Re-run the example - form now allows 0-6 UDP trackers!
```

### Key Files

- **constraints.toml** - Defines validation limits
- **array-trackers.toml** - References constraints via `${constraint.path}`
- Form parser automatically resolves interpolations at load time

## Benefits of Constraints

- **DRY** - Write common sections once
- **Maintainability** - Update fragments in one place
- **Reusability** - Share across multiple forms
- **Modularity** - Compose complex forms from simple parts
- **Consistency** - Unified styling and structure
- **Constraint Sync** - Single place to change validation limits (all layers auto-sync)

## Fragment Library

Use these as templates for your own fragments:

| Fragment | Purpose | Fields |
|----------|---------|--------|
| header | Form introduction | Title, description |
| employee_info | Standard employee data | Name, email, phone |
| agreement | Policy acceptance | Checkbox, text |
| support | Tier selection | Radio buttons |
| border_section | Custom styled container | Any fields |