TypeDialog/templates/nickel/README.md

# Nickel Template Library

Reutilizable template library for generating Nickel configuration schemas from TypeDialog forms.

## Structure

### Fields (`fields/`)

Basic field templates for different data types. Each template generates a single field definition.

- **string_field.ncl.j2** - String field with optional doc and contract
- **number_field.ncl.j2** - Number field with validation
- **boolean_field.ncl.j2** - Boolean flag field
- **optional_field.ncl.j2** - Optional field wrapper (any type)
- **enum_field.ncl.j2** - Enumerated field with predefined options

### Forms (`forms/`)

Complete schema templates for specific use cases. Each generates a full configuration structure.

- **config_schema.ncl.j2** - General application configuration
- **service_spec.ncl.j2** - Kubernetes service specification
- **deployment.ncl.j2** - Deployment configuration with environment and health checks

### Macros (`macros/`)

Reusable macro definitions for common patterns.

- **contracts.ncl.j2** - Validation contract definitions (NonEmpty, port ranges, etc.)
- **validation.ncl.j2** - Predicate macros (length, range, etc.)
- **metadata.ncl.j2** - Documentation and type annotation helpers

## Usage

### Field Templates

Use in form templates with Tera include syntax:

```jinja2
{% include "fields/string_field.ncl.j2" with {
  name: "app_name",
  doc: "Application name",
  contract: "std.string.NonEmpty",
  default: "myapp"
} %}
```

### Form Templates

Render a complete schema:

```bash
typedialog nickel-template forms/config_schema.ncl.j2 form_results.json -o config.ncl
```

### Macro Templates

Include macros in custom templates:

```jinja2
{% include "macros/contracts.ncl.j2" %}
{% include "macros/validation.ncl.j2" %}
```

Then use the defined macros:

```jinja2
{{ non_empty_string("username", "User login name") }}
{{ port_number("server_port", "HTTP port") }}
```

## Template Context Variables

Templates expect the following context from form results:

```json
{
  "name": "field_name",
  "doc": "field description",
  "contract": "std.string.NonEmpty",
  "default": "default_value",
  "field_type": "String|Number|Bool",
  "options": ["option1", "option2"],
  "groups_by_section": { "section_name": [...fields...] }
}
```

## Examples

### Simple Configuration Schema

Create a form with fields for app name, version, and debug mode:

```toml
[[fields]]
name = "app_name"
type = "text"
prompt = "Application name"
required = true

[[fields]]
name = "app_version"
type = "text"
prompt = "Version"
default = "1.0.0"

[[fields]]
name = "debug_mode"
type = "confirm"
prompt = "Enable debug mode"
```

Render with template:

```bash
typedialog nickel-template forms/config_schema.ncl.j2 results.json -o config.ncl
```

Output:

```nickel
{
  app = {
    name | doc "Application name" : String = "myapp",
    version | doc "Version" : String = "1.0.0",
    debug_mode | doc "Enable debug mode" : Bool = true,
  },
}
```

### Service Specification

Use for Kubernetes or containerized deployments:

```bash
typedialog form forms/service_spec.ncl.j2 \
  -o service_results.json

typedialog nickel-template forms/service_spec.ncl.j2 \
  service_results.json -o service.ncl

nickel export service.ncl
```

## Extending

Create new templates following these conventions:

1. **Single-field templates** → `fields/{type}_field.ncl.j2`
2. **Schema templates** → `forms/{purpose}_schema.ncl.j2`
3. **Macro libraries** → `macros/{category}.ncl.j2`

All templates use Jinja2 syntax. Refer to Tera documentation for available filters and functions.

## Best Practices

- Use meaningful variable names in templates
- Document required context variables with comments
- Keep templates DRY by using macros for common patterns
- Validate generated Nickel with `nickel typecheck`
- Version templates with your forms for consistency