# Form Templates

This directory contains form-related templates for ThrillWiki.

## Directory Structure

```
forms/
├── partials/           # Individual form components
│   ├── form_field.html     # Complete form field
│   ├── field_error.html    # Error messages
│   ├── field_success.html  # Success indicator
│   └── form_actions.html   # Submit/cancel buttons
├── layouts/            # Form layout templates
│   ├── stacked.html        # Vertical layout
│   ├── inline.html         # Horizontal layout
│   └── grid.html           # Multi-column grid
└── README.md           # This file
```

## Form Layouts

### Stacked Layout (Default)

Vertical layout with full-width fields:

```django
{% include 'forms/layouts/stacked.html' with form=form %}

{# With options #}
{% include 'forms/layouts/stacked.html' with
    form=form
    submit_text='Save Changes'
    show_cancel=True
    cancel_url='/parks/'
%}
```

### Inline Layout

Horizontal layout with labels beside inputs:

```django
{% include 'forms/layouts/inline.html' with form=form %}

{# Custom label width #}
{% include 'forms/layouts/inline.html' with form=form label_width='w-1/4' %}
```

### Grid Layout

Multi-column responsive grid:

```django
{# 2-column grid #}
{% include 'forms/layouts/grid.html' with form=form cols=2 %}

{# 3-column grid #}
{% include 'forms/layouts/grid.html' with form=form cols=3 %}

{# Full-width description field #}
{% include 'forms/layouts/grid.html' with form=form cols=2 full_width='description' %}
```

## Layout Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `form` | Django form object | Required |
| `exclude` | Comma-separated fields to exclude | None |
| `fields` | Comma-separated fields to include | All |
| `show_help` | Show help text | True |
| `show_required` | Show required indicator | True |
| `submit_text` | Submit button text | 'Submit' |
| `submit_class` | Submit button CSS class | 'btn-primary' |
| `show_cancel` | Show cancel button | False |
| `cancel_url` | URL for cancel link | None |
| `cancel_text` | Cancel button text | 'Cancel' |
| `show_actions` | Show action buttons | True |

## Individual Components

### Form Field

Complete field with label, input, help, and errors:

```django
{% include 'forms/partials/form_field.html' with field=form.email %}

{# Custom label #}
{% include 'forms/partials/form_field.html' with field=form.email label='Your Email' %}

{# Without label #}
{% include 'forms/partials/form_field.html' with field=form.search show_label=False %}

{# Inline layout #}
{% include 'forms/partials/form_field.html' with field=form.email layout='inline' %}

{# HTMX validation #}
{% include 'forms/partials/form_field.html' with
    field=form.username
    hx_validate=True
    hx_validate_url='/api/validate/username/'
%}
```

### Field Error

Error message display:

```django
{% include 'forms/partials/field_error.html' with errors=field.errors %}

{# Without icon #}
{% include 'forms/partials/field_error.html' with errors=field.errors show_icon=False %}

{# Different size #}
{% include 'forms/partials/field_error.html' with errors=field.errors size='md' %}
```

### Field Success

Success indicator for validation:

```django
{% include 'forms/partials/field_success.html' with message='Username available' %}

{# Just checkmark #}
{% include 'forms/partials/field_success.html' %}
```

### Form Actions

Submit and cancel buttons:

```django
{% include 'forms/partials/form_actions.html' %}

{# With cancel #}
{% include 'forms/partials/form_actions.html' with show_cancel=True cancel_url='/list/' %}

{# With loading state #}
{% include 'forms/partials/form_actions.html' with show_loading=True %}

{# Left-aligned #}
{% include 'forms/partials/form_actions.html' with align='left' %}

{# Custom icon #}
{% include 'forms/partials/form_actions.html' with submit_icon='fas fa-check' %}
```

## HTMX Integration

### Inline Validation

```django
<form hx-post="/submit/" hx-target="#form-results">
    {% for field in form %}
        {% include 'forms/partials/form_field.html' with
            field=field
            hx_validate=True
            hx_validate_url='/validate/'
        %}
    {% endfor %}
    {% include 'forms/partials/form_actions.html' with show_loading=True %}
</form>
```

### Validation Endpoint Response

```django
{# Success #}
{% include 'forms/partials/field_success.html' with message='Valid!' %}

{# Error #}
{% include 'forms/partials/field_error.html' with errors=errors %}
```

## Custom Form Rendering

For complete control, use the components directly:

```django
<form method="post" action="{% url 'submit' %}">
    {% csrf_token %}

    {# Non-field errors #}
    {% if form.non_field_errors %}
    <div class="mb-4 p-4 bg-red-50 rounded-lg" role="alert">
        {% for error in form.non_field_errors %}
            <p>{{ error }}</p>
        {% endfor %}
    </div>
    {% endif %}

    {# Custom field layout #}
    <div class="grid grid-cols-2 gap-4">
        {% include 'forms/partials/form_field.html' with field=form.first_name %}
        {% include 'forms/partials/form_field.html' with field=form.last_name %}
    </div>

    {% include 'forms/partials/form_field.html' with field=form.email %}

    {% include 'forms/partials/form_actions.html' with submit_text='Create Account' %}
</form>
```

## CSS Classes

The form components use these CSS classes (defined in `components.css`):

- `.btn-primary` - Primary action button
- `.btn-secondary` - Secondary action button
- `.form-field` - Field wrapper
- `.field-error` - Error message styling

## Accessibility

All form components include:

- Labels properly associated with inputs (`for`/`id`)
- Required field indicators with screen reader text
- Error messages with `role="alert"`
- Help text linked via `aria-describedby`
- Invalid state with `aria-invalid`