TypeDialog/README.md

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

# TypeDialog

A powerful, standalone library and CLI tool for creating interactive forms and prompts using the `inquire` crate.

## Features

- **8 Prompt Types**: text, confirm, select, multi-select, password, custom, editor, date
- **Declarative Forms**: TOML-based UI definitions with fragments & composition
- **Dynamic Logic**: Conditional fields, smart defaults, real-time validation
- **Multi-Language Support**: Fluent (.ftl) translations with automatic locale detection
- **Multiple Output Formats**: JSON, YAML, TOML, and Nickel output
- **Zero Runtime Dependencies**: Core library runs anywhere, no external tools required
- **3 Backends**: CLI (inquire), TUI (ratatui), Web (axum)

### Integration Key

- **Type-Safe Schemas**: Bidirectional [Nickel](https://nickel-lang.org) integration to manage configurations and settings files.<br />
  It requires [Nickel CLI](https://nickel-lang.org/getting-started/)

## Quick Start

### Installation

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed setup.

Requirements:
- **Rust 1.70+** - [Install](https://rustup.rs/)
- **just** - `cargo install just` (or `brew install just`)

### Build & Run

```bash
# Clone
git clone https://github.com/anthropics/typedialog.git
cd typedialog

# Build
just build::default

# Test
just test::all

# Run example
cargo run --example form
```

## Backends at a Glance

### CLI Backend (inquire)
Interactive terminal prompts for scripting and automation.

```bash
# Simple prompt
typedialog text "Enter your name"

# With options
typedialog select "Choose role" Admin User Guest

# Output as JSON
typedialog text "Email" --format json
```

**Use for:** Scripts, CI/CD pipelines, server tools, piping between tools
**See:** [`examples/04-backends/cli/`](examples/04-backends/cli/)

### TUI Backend (ratatui)
Full terminal UI with keyboard navigation and mouse support.

```bash
cargo run -p typedialog-tui --example form_with_autocompletion
```

**Use for:** Interactive dashboards, system administration tools, complex forms
**See:** [`examples/04-backends/tui/`](examples/04-backends/tui/)

### Web Backend (axum)
HTTP server with browser-based forms.

```bash
cargo run -p typedialog-web -- --config config/web/dev.toml
# Open http://localhost:3000
```

**Use for:** SaaS platforms, public forms, mobile-friendly interfaces
**See:** [`examples/04-backends/web/`](examples/04-backends/web/)

**Complete backend guide:** [Backend-Specific Examples](examples/04-backends/)

## Nickel Integration

**Type-safe configuration management** with bidirectional Nickel schema support.

Generate interactive forms from Nickel schemas, collect user input, and produce validated configuration output:

```bash
# 1. Define schema in Nickel
nickel eval config.ncl > schema.toml

# 2. Run interactive form
typedialog form schema.toml --backend tui

# 3. Get validated output in any format
# JSON, YAML, TOML, or back to Nickel with type preservation
```

**Benefits:**
- Schema validation before/after collection
- Type contracts enforced throughout pipeline
- Documentation embedded in schemas
- Deterministic configuration generation

**Learn more:**
- [Nickel Integration Guide](docs/CONFIGURATION.md#nickel-integration)
- [Examples: 06-integrations/nickel/](examples/06-integrations/nickel/)
- [Nickel Lang Documentation](https://nickel-lang.org/)

## Documentation

Complete documentation in [`docs/`](docs/):

| Document | Purpose |
|----------|---------|
| [**INSTALLATION.md**](docs/INSTALLATION.md) | Prerequisites & setup |
| [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) | Development workflows |
| [**BUILD.md**](docs/BUILD.md) | Building & cross-compilation |
| [**RELEASE.md**](docs/RELEASE.md) | Release process |
| [**CONFIGURATION.md**](docs/CONFIGURATION.md) | Backend & Nickel configuration |

## Examples

Complete working examples in [`examples/`](examples/):

| Category | Path | Contents |
|----------|------|----------|
| **Getting Started** | [01-basic](examples/01-basic/) | Form syntax, sections, validation |
| **Advanced Features** | [02-advanced](examples/02-advanced/) | Conditional logic, dynamic fields |
| **Styling** | [03-styling](examples/03-styling/) | Themes, borders, visual design |
| **Backends** | [04-backends](examples/04-backends/) | CLI, TUI, Web implementations |
| **Composition** | [05-fragments](examples/05-fragments/) | Reusable components |
| **Integrations** | [06-integrations](examples/06-integrations/) | [Nickel](examples/06-integrations/nickel/), [i18n](examples/06-integrations/i18n/) |
| **Production** | [09-templates](examples/09-templates/) | Real-world use cases |

**Quick start:** [examples/README.md](examples/README.md)

## Development

Use `just` for all development tasks:

```bash
# Show available commands
just --list

# Format, lint, test
just check-all

# Build & package
just distro::build-release
just distro::create-package

# Full CI/CD
just ci::full
```

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for details.

## Building & Distribution

### Build from Source

```bash
just build::release
```

Binaries in `target/release/`

### Create Distribution Package

```bash
just distro::build-release
just distro::create-package
just distro::create-checksums
```

Package includes binaries, configs, and installers.

See [docs/BUILD.md](docs/BUILD.md) for complete guide.

### Install Distributed Release

```bash
# Linux/macOS
curl -fsSL https://github.com/anthropics/typedialog/releases/download/latest/install.sh | bash

# Windows PowerShell
irm https://github.com/anthropics/typedialog/releases/download/latest/install.ps1 | iex
```

See [docs/RELEASE.md](docs/RELEASE.md) for release workflow.

## Configuration

Pre-configured settings for each backend and environment:

```
config/
├── cli/         # default, dev, production
├── tui/         # default, dev, production
└── web/         # default, dev, production
```

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.

## Project Structure

```
typedialog/
├── crates/
│   ├── typedialog-core/       # Core library
│   ├── typedialog/            # CLI binary
│   ├── typedialog-tui/        # TUI binary
│   └── typedialog-web/        # Web binary
├── config/                      # Configuration files
├── examples/                    # Working examples
├── scripts/                     # Build automation
├── installers/                  # Installation scripts
├── docs/                        # Documentation
├── justfile                     # Command orchestration
└── Cargo.toml                   # Workspace manifest
```

## Key Technologies

- **Rust** - Type-safe systems language
- **inquire** - Interactive prompt library (CLI backend)
- **Ratatui** - Terminal UI framework (TUI backend)
- **Axum** - Web framework (Web backend)
- **Nickel** - Type-safe configuration language (schema integration)
- **TOML** - Form and configuration language
- **Fluent** - Multi-language translation system
- **just** - Command orchestration

## Commands at a Glance

```bash
# Development
just fmt                # Format code
just lint               # Lint code
just test::all          # Run tests
just dev::watch         # Watch & rebuild
just dev::docs          # Generate docs

# Building
just build::default     # Debug build
just build::release     # Release build
just distro::cross      # Cross-compile

# CI/CD
just ci::full           # Complete pipeline
just check-all          # Format + lint + test

# Distribution
just distro::build-release      # Release build
just distro::create-package     # Package
just distro::create-checksums   # Checksums
just distro::package-release    # Prepare release
```

## System Requirements

### Minimum
- Rust 1.70+
- 4GB RAM
- 2GB disk space

### For Cross-Compilation
- Docker (or cargo-cross)

### Optional Tools
- **Nickel CLI** - For developing type-safe Nickel schemas (used with `06-integrations/nickel/` examples)
- **cargo-watch** - For hot-reload during development
- **cargo-cross** - For cross-compilation to other platforms

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for setup.

## License & Compliance

- **Project License**: [MIT](LICENSE)
- **Dependency SBOM (SPDX)**: [SBOM.spdx.json](SBOM.spdx.json) - ISO/IEC 5962:2021
- **Dependency SBOM (CycloneDX)**: [SBOM.cyclonedx.json](SBOM.cyclonedx.json) - ECMA standard
- **Regenerate SBOMs**: `just distro::generate-sbom`

All dependencies are compatible with MIT license. Audit vulnerabilities: `just ci::audit`

## Getting Help

1. **Documentation** - Start with [docs/README.md](docs/)
2. **Examples** - Check [examples/README.md](examples/)
3. **Issues** - Open on [GitHub](https://github.com/anthropics/typedialog/issues)

## Contributing

Contributions welcome! See documentation for setup and guidelines.

---

**Ready to get started?** → [docs/INSTALLATION.md](docs/INSTALLATION.md)