thrillwiki_django_no_react/docs/ux/component-library.md

# ThrillWiki Component Library

This document catalogs all reusable UI components available in ThrillWiki.

## Layout Components

### Page Header

Standardized header for pages with optional actions and breadcrumbs.

```django
{% include 'components/layout/page_header.html' with
    title='Parks'
    subtitle='Browse theme parks worldwide'
    icon='fas fa-map-marker-alt'
    primary_action_url='/parks/create/'
    primary_action_text='Add Park'
    primary_action_icon='fas fa-plus'
%}
```

**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | string | Page title (required) |
| `subtitle` | string | Optional subtitle |
| `icon` | string | Icon class for title |
| `primary_action_url` | string | URL for primary action button |
| `primary_action_text` | string | Text for primary action |
| `primary_action_icon` | string | Icon for primary action |
| `secondary_action_url` | string | URL for secondary action |
| `secondary_action_text` | string | Text for secondary action |

### Action Bar

Container for action buttons with consistent layout.

```django
{% include 'components/ui/action_bar.html' with
    align='between'
    primary_action_text='Save'
    secondary_action_text='Preview'
    tertiary_action_text='Cancel'
    tertiary_action_url='/back/'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `align` | string | 'right' | 'left', 'right', 'center', 'between' |
| `mobile_stack` | boolean | true | Stack vertically on mobile |
| `show_border` | boolean | false | Show top border |
| `primary_action_*` | various | - | Primary button configuration |
| `secondary_action_*` | various | - | Secondary button configuration |
| `tertiary_action_*` | various | - | Tertiary button configuration |

## Navigation Components

### Breadcrumbs

Hierarchical navigation with Schema.org support.

```django
{% include 'components/navigation/breadcrumbs.html' %}
```

Set breadcrumbs in your view:

```python
from apps.core.utils import build_breadcrumb

def park_detail(request, slug):
    park = get_object_or_404(Park, slug=slug)
    request.breadcrumbs = [
        build_breadcrumb('Home', '/', icon='fas fa-home'),
        build_breadcrumb('Parks', reverse('parks:list')),
        build_breadcrumb(park.name, is_current=True),
    ]
    return render(request, 'parks/detail.html', {'park': park})
```

## Modal Components

### Modal Base

Base modal component with customizable content.

```django
{% include 'components/modals/modal_base.html' with
    modal_id='edit-modal'
    show_var='showEditModal'
    title='Edit Park'
    subtitle='Update park information'
    icon='fas fa-edit'
    size='lg'
    animation='scale'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `modal_id` | string | required | Unique identifier |
| `show_var` | string | required | Alpine.js show variable |
| `title` | string | - | Modal title |
| `subtitle` | string | - | Modal subtitle |
| `icon` | string | - | Title icon class |
| `size` | string | 'md' | 'sm', 'md', 'lg', 'xl', 'full' |
| `animation` | string | 'scale' | 'scale', 'slide-up', 'fade' |
| `close_on_backdrop` | boolean | true | Close when clicking backdrop |
| `close_on_escape` | boolean | true | Close on Escape key |
| `show_close_button` | boolean | true | Show X button |
| `prevent_scroll` | boolean | true | Prevent body scroll |

### Confirmation Modal

Pre-styled confirmation dialog.

```django
{% include 'components/modals/modal_confirm.html' with
    modal_id='delete-confirm'
    show_var='showDeleteModal'
    title='Delete Park'
    message='Are you sure? This cannot be undone.'
    confirm_text='Delete'
    confirm_variant='destructive'
    confirm_hx_delete='/parks/123/'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `modal_id` | string | required | Unique identifier |
| `show_var` | string | required | Alpine.js show variable |
| `title` | string | required | Modal title |
| `message` | string | required | Confirmation message |
| `icon` | string | auto | Icon class |
| `icon_variant` | string | 'warning' | 'destructive', 'warning', 'info', 'success' |
| `confirm_text` | string | 'Confirm' | Confirm button text |
| `confirm_variant` | string | 'primary' | 'destructive', 'primary', 'warning' |
| `cancel_text` | string | 'Cancel' | Cancel button text |
| `confirm_url` | string | - | URL for confirm (makes it a link) |
| `confirm_hx_post` | string | - | HTMX POST URL |
| `confirm_hx_delete` | string | - | HTMX DELETE URL |
| `on_confirm` | string | - | Alpine.js expression |

## Skeleton Components

### List Skeleton

```django
{% include 'components/skeletons/list_skeleton.html' with rows=5 %}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `rows` | number | 5 | Number of skeleton rows |
| `show_avatar` | boolean | false | Show avatar placeholder |
| `show_meta` | boolean | true | Show metadata line |
| `show_action` | boolean | true | Show action button placeholder |

### Card Grid Skeleton

```django
{% include 'components/skeletons/card_grid_skeleton.html' with cards=6 cols=3 %}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `cards` | number | 6 | Number of skeleton cards |
| `cols` | number | 3 | Grid columns (sm screens) |
| `show_image` | boolean | true | Show image placeholder |
| `show_badge` | boolean | false | Show badge placeholder |

### Detail Skeleton

```django
{% include 'components/skeletons/detail_skeleton.html' %}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `show_image` | boolean | true | Show hero image placeholder |
| `show_sidebar` | boolean | true | Show sidebar section |
| `content_lines` | number | 8 | Number of content lines |

### Table Skeleton

```django
{% include 'components/skeletons/table_skeleton.html' with rows=10 columns=5 %}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `rows` | number | 5 | Number of table rows |
| `columns` | number | 4 | Number of columns |
| `show_checkbox` | boolean | false | Show checkbox column |
| `show_actions` | boolean | true | Show actions column |

### Form Skeleton

```django
{% include 'components/skeletons/form_skeleton.html' with fields=4 %}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `fields` | number | 4 | Number of form fields |
| `show_textarea` | boolean | true | Include textarea field |
| `columns` | number | 1 | Form columns (1 or 2) |

## Form Components

### Form Field

Standardized form field with label, input, and validation.

```django
{% include 'forms/partials/form_field.html' with
    field=form.name
    help_text='Enter the full park name'
    size='lg'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `field` | Field | required | Django form field |
| `label` | string | field.label | Override label |
| `help_text` | string | field.help_text | Help text |
| `size` | string | 'md' | 'sm', 'md', 'lg' |
| `show_label` | boolean | true | Show label |
| `inline` | boolean | false | Inline layout |

### Form Actions

Form submission buttons.

```django
{% include 'forms/partials/form_actions.html' with
    submit_text='Save Park'
    cancel_url='/parks/'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `submit_text` | string | 'Submit' | Submit button text |
| `submit_icon` | string | - | Submit button icon |
| `cancel_url` | string | - | Cancel button URL |
| `cancel_text` | string | 'Cancel' | Cancel button text |
| `show_cancel` | boolean | true | Show cancel button |

### Field Error

Display field validation errors.

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

### Field Success

Display field validation success.

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

## UI Components

### Button

```html
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-outline">Outline</button>
<button class="btn btn-ghost">Ghost</button>
<button class="btn btn-link">Link</button>
<button class="btn btn-destructive">Destructive</button>
```

**Sizes:**
```html
<button class="btn btn-primary btn-sm">Small</button>
<button class="btn btn-primary">Default</button>
<button class="btn btn-primary btn-lg">Large</button>
```

### Card

```django
{% include 'components/ui/card.html' with
    title='Card Title'
    subtitle='Card subtitle'
%}
    <p>Card content goes here.</p>
{% endinclude %}
```

### Input

```django
{% include 'components/ui/input.html' with
    name='email'
    type='email'
    placeholder='Enter email'
    required=True
%}
```

### Status Badge

```django
{% include 'components/status_badge.html' with
    status='published'
    label='Published'
%}
```

**Status variants:**
- `published` / `active` / `approved` - Green
- `draft` / `pending` - Yellow
- `rejected` / `archived` - Red
- `review` - Blue

### Icon

```django
{% include 'components/ui/icon.html' with
    icon='fas fa-star'
    size='lg'
    color='primary'
%}
```

### Dialog (Alert Dialog)

```django
{% include 'components/ui/dialog.html' with
    dialog_id='alert-dialog'
    show_var='showAlert'
    title='Alert'
    message='This is an alert message.'
    confirm_text='OK'
%}
```

## Toast Notifications

### From JavaScript

```javascript
// Success toast
Alpine.store('toast').success('Saved successfully!');

// Error toast
Alpine.store('toast').error('Something went wrong');

// Warning toast
Alpine.store('toast').warning('Session expiring soon');

// Info toast
Alpine.store('toast').info('New features available');

// With custom duration (ms)
Alpine.store('toast').success('Quick message', 2000);

// With action button
Alpine.store('toast').success('Item deleted', 5000, {
    action: { label: 'Undo', onClick: () => undoAction() }
});
```

### From Django Views

```python
from apps.core.htmx_utils import htmx_success, htmx_error

# Success toast
return htmx_success('Park saved successfully!')

# Error toast
return htmx_error('Validation failed', status=422)

# With action
return htmx_success('Item deleted', action={
    'label': 'Undo',
    'onClick': 'undoDelete()'
})
```

## Loading Components

### Loading Indicator

```django
{% include 'htmx/components/loading_indicator.html' with
    id='my-loading'
    text='Loading...'
    size='md'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | string | - | Element ID for hx-indicator |
| `text` | string | 'Loading...' | Loading text |
| `size` | string | 'md' | 'sm', 'md', 'lg' |
| `type` | string | 'spinner' | 'spinner', 'dots', 'pulse' |

## Pagination

### Standard Pagination

```django
{% include 'components/pagination.html' with
    page_obj=page_obj
    show_first_last=True
%}
```

### HTMX Pagination

```django
{% include 'components/pagination.html' with
    page_obj=page_obj
    hx_target='#items-list'
    hx_swap='innerHTML'
    hx_push_url='true'
%}
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page_obj` | Page | required | Django paginator page |
| `show_first_last` | boolean | true | Show first/last buttons |
| `show_page_numbers` | boolean | true | Show page numbers |
| `max_pages` | number | 5 | Max visible page numbers |
| `hx_target` | string | - | HTMX target selector |
| `hx_swap` | string | - | HTMX swap method |
| `hx_push_url` | boolean | false | Push URL on navigation |