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.

{% 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.

{% 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.

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

Set breadcrumbs in your view:

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.

{% 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.

{% 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

{% 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

{% 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

{% 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

{% 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

{% 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.

{% 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.

{% 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.

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

Field Success

Display field validation success.

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

UI Components

Button

<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:

<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

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

Input

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

Status Badge

{% 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

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

Dialog (Alert Dialog)

{% 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

// 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

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

{% 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

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

HTMX Pagination

{% 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