pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-27 08:07:04 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
00699d53b44a7a629c5c904474013a8c47b99523
thrillwiki_django_no_react/source_docs/COMPONENTS.md

967 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ThrillWiki Component Library
> Complete UI component documentation
---
## Table of Contents
1. [Layout Components](#layout-components)
2. [Navigation Components](#navigation-components)
3. [Display Components](#display-components)
4. [Form Components](#form-components)
5. [Feedback Components](#feedback-components)
6. [Data Display](#data-display)
7. [Entity Components](#entity-components)
8. [Specialty Components](#specialty-components)
---
## Component Architecture
```
Components
├── Layout
│ ├── Header
│ ├── Footer
│ ├── Sidebar
│ └── PageContainer
│
├── Navigation
│ ├── MainNav
│ ├── TabNav
│ ├── Breadcrumbs
│ └── Pagination
│
├── Display
│ ├── Card
│ ├── Badge
│ ├── Avatar
│ └── Image
│
├── Forms
│ ├── Input
│ ├── Select
│ ├── Checkbox
│ └── Button
│
├── Feedback
│ ├── Toast
│ ├── Alert
│ ├── Modal
│ └── Loading
│
├── Data
│ ├── Table
│ ├── List
│ ├── Stats
│ └── Charts
│
└── Entity
├── ParkCard
├── RideCard
├── ReviewCard
└── CreditCard
```
---
## Layout Components
### Header
The main navigation bar at the top of every page.
```
┌─────────────────────────────────────────────────────────────────┐
│ 🎢 ThrillWiki Parks Rides Companies 🔍 👤 🔔 │
└─────────────────────────────────────────────────────────────────┘
```
**Features:**
- Logo/brand link to homepage
- Primary navigation links
- Search button/input
- User menu (avatar dropdown)
- Notification bell
- Mobile hamburger menu
**Variants:**
- Default: Full navigation
- Minimal: Logo only (auth pages)
- Admin: Additional admin links
---
### Footer
Site-wide footer with links and information.
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ ThrillWiki Explore Community Legal │
│ The ultimate Parks Guidelines Terms │
│ theme park Rides Leaderboard Privacy │
│ database Companies Blog Contact │
│ Models Discord │
│ │
│ ───────────────────────────────────────────────────────────── │
│ © 2024 ThrillWiki [Twitter] [Discord] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Sections:**
- Brand info
- Navigation columns
- Social links
- Copyright
---
### PageContainer
Wrapper component for consistent page layout.
```
┌─────────────────────────────────────────────────────────────────┐
│ HEADER │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ PAGE CONTENT │ │
│ │ │ │
│ │ max-width: 1280px │ │
│ │ padding: responsive │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────┤
│ FOOTER │
└─────────────────────────────────────────────────────────────────┘
```
**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `maxWidth` | string | Container max width |
| `padding` | string | Content padding |
| `className` | string | Additional classes |
---
### Sidebar
Collapsible sidebar for settings and admin pages.
```
┌──────────────────┐
│ Section 1 │
│ ├── Item 1 │
│ ├── Item 2 ● │ ← Active
│ └── Item 3 │
│ │
│ Section 2 │
│ ├── Item 4 │
│ └── Item 5 │
│ │
│ [Collapse ◀] │
└──────────────────┘
```
---
## Navigation Components
### MainNav
Primary navigation in header.
```
┌────────────────────────────────────────────────────┐
│ Parks ▾ Rides ▾ Companies ▾ More ▾ │
└────────────────────────────────────────────────────┘
│
▼
┌────────────────────┐
│ All Parks │
│ Parks Nearby │
│ ───────────── │
│ Add New Park │
└────────────────────┘
```
**Features:**
- Dropdown menus on hover/click
- Mobile drawer navigation
- Active state highlighting
- Keyboard navigation
---
### TabNav
Horizontal tab navigation within pages.
```
┌─────────────────────────────────────────────────────────────┐
│ Overview Rides Reviews Photos History │
│ ═════════ │
└─────────────────────────────────────────────────────────────┘
```
**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `tabs` | Tab[] | Array of tab definitions |
| `activeTab` | string | Currently active tab |
| `onChange` | function | Tab change handler |
---
### Breadcrumbs
Hierarchical navigation path.
```
Home > Parks > Cedar Point > Steel Vengeance
```
**Features:**
- Clickable ancestors
- Current page (non-clickable)
- Truncation for long paths
- Schema.org markup
---
### Pagination
Navigate through paginated content.
```
┌─────────────────────────────────────────────────────┐
│ ◀ Previous 1 2 [3] 4 5 ... 12 Next ▶ │
└─────────────────────────────────────────────────────┘
```
**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `currentPage` | number | Current page |
| `totalPages` | number | Total page count |
| `onPageChange` | function | Page change handler |
---
## Display Components
### Card
Versatile container for content.
```
┌─────────────────────────────────────┐
│ ┌─────────────────────────────┐ │
│ │ │ │
│ │ IMAGE │ │
│ │ │ │
│ └─────────────────────────────┘ │
│ │
│ Title │
│ Subtitle or description │
│ │
│ [Action 1] [Action 2] │
│ │
└─────────────────────────────────────┘
```
**Variants:**
| Variant | Description |
|---------|-------------|
| Default | Basic card with border |
| Elevated | Shadow for depth |
| Interactive | Hover effects, clickable |
| Glass | Frosted glass (dark mode) |
---
### Badge
Small label for status or categories.
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Operating │ │ Coaster │ │ New! │
└──────────────┘ └──────────────┘ └──────────────┘
(green) (blue) (accent)
```
**Variants:**
| Variant | Usage |
|---------|-------|
| Default | General labels |
| Success | Operating, approved |
| Warning | Under construction |
| Destructive | Closed, error |
| Outline | Secondary importance |
---
### Avatar
User or entity image.
```
┌─────┐ ┌─────┐ ┌─────┐
│ │ │ │ │ AB │
│ 👤 │ │ IMG │ │ │
│ │ │ │ │ │
└─────┘ └─────┘ └─────┘
Icon Image Initials
```
**Sizes:**
- `sm`: 24px
- `md`: 40px (default)
- `lg`: 64px
- `xl`: 96px
---
### Image
Optimized image display with loading states.
```
┌─────────────────────────────────────┐
│ │
│ Loading... ░░░░░░░░░░░░░ │
│ │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ │
│ Loaded Image │
│ │
└─────────────────────────────────────┘
```
**Features:**
- Lazy loading
- Blur placeholder
- Error fallback
- Responsive sizes
- CloudFlare Images integration
---
## Form Components
### Input
Text input field.
```
┌─────────────────────────────────────────────────────┐
│ Label │
├─────────────────────────────────────────────────────┤
│ Placeholder text... │
└─────────────────────────────────────────────────────┘
Hint text or validation message
```
**States:**
| State | Appearance |
|-------|------------|
| Default | Standard border |
| Focused | Primary ring |
| Error | Red border + message |
| Disabled | Muted, non-interactive |
**Types:**
- Text, Email, Password, Number
- Search (with icon)
- Textarea (multiline)
---
### Select
Dropdown selection.
```
┌─────────────────────────────────────────────────────┐
│ Select an option... ▾ │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Option 1 │
│ Option 2 ✓ │
│ Option 3 │
│ ─────────────────────────── │
│ Group Header │
│ Option 4 │
│ Option 5 │
└─────────────────────────────────────────────────────┘
```
**Features:**
- Searchable options
- Option groups
- Multi-select variant
- Clear selection
---
### Checkbox
Boolean or multi-selection.
```
☐ Unchecked option
☑ Checked option
☐ Unchecked option
```
**Variants:**
- Single checkbox
- Checkbox group
- Indeterminate state
---
### Radio
Single selection from options.
```
○ Option 1
● Option 2 (selected)
○ Option 3
```
---
### Switch
Toggle between two states.
```
Off ○──────● On
●──────○
```
---
### Button
Clickable action trigger.
```
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Primary │ │ Secondary │ │ Outline │
└────────────────┘ └────────────────┘ └────────────────┘
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Ghost │ │ Destructive │ │ Loading │
└────────────────┘ └────────────────┘ └────────────────┘
```
**Variants:**
| Variant | Usage |
|---------|-------|
| Primary | Main actions |
| Secondary | Secondary actions |
| Outline | Bordered, less emphasis |
| Ghost | Minimal, icon buttons |
| Destructive | Delete, dangerous |
| Link | Text-only, inline |
**Sizes:**
- `sm`: Compact
- `default`: Standard
- `lg`: Large
- `icon`: Square, icon-only
---
### DatePicker
Date selection component.
```
┌─────────────────────────────────────────────────────┐
│ 📅 Select date... │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ ◀ December 2024 ▶ │
├─────────────────────────────────────────────────────┤
│ Su Mo Tu We Th Fr Sa │
│ 1 2 3 4 5 6 7 │
│ 8 9 10 11 12 13 14 │
│ 15 16 17 18 19 [20] 21 │
│ 22 23 24 25 26 27 28 │
│ 29 30 31 │
└─────────────────────────────────────────────────────┘
```
**Features:**
- Month/year navigation
- Date range selection
- Disabled dates
- Date precision selector
---
### Slider
Range value selection.
```
0 100
●───────────────────●────────────────────────────●
50
```
**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `min` | number | Minimum value |
| `max` | number | Maximum value |
| `step` | number | Value increment |
| `value` | number | Current value |
---
## Feedback Components
### Toast
Temporary notification message.
```
┌─────────────────────────────────────────────────────┐
│ ✓ Changes saved successfully ✕ │
└─────────────────────────────────────────────────────┘
```
**Variants:**
| Variant | Usage |
|---------|-------|
| Default | General info |
| Success | Positive confirmation |
| Warning | Caution notice |
| Error | Error occurred |
---
### Alert
Inline notification.
```
┌─────────────────────────────────────────────────────┐
│ ⚠️ Warning │
│ This action cannot be undone. │
└─────────────────────────────────────────────────────┘
```
**Variants:**
- Info, Success, Warning, Error
---
### Modal / Dialog
Overlay for focused content.
```
┌─────────────────────────────────────────────────────┐
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ Dialog Title ✕ │ │
│ ├───────────────────────────────────────────┤ │
│ │ │ │
│ │ Dialog content goes here │ │
│ │ │ │
│ ├───────────────────────────────────────────┤ │
│ │ [Cancel] [Confirm] │ │
│ └───────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
```
**Types:**
- Alert Dialog (confirmation)
- Form Dialog (input)
- Info Dialog (display)
- Full-screen Dialog
---
### Loading States
Various loading indicators.
**Spinner:**
```
◠◡◠
```
**Skeleton:**
```
┌─────────────────────────────────────────────────────┐
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ ░░░░░░░░░░░░░░░░ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░ │
└─────────────────────────────────────────────────────┘
```
**Progress:**
```
[████████████░░░░░░░░] 60%
```
---
### Empty State
No content placeholder.
```
┌─────────────────────────────────────────────────────┐
│ │
│ 🎢 │
│ │
│ No rides found │
│ Try adjusting your filters │
│ │
│ [Clear Filters] │
│ │
└─────────────────────────────────────────────────────┘
```
---
## Data Display
### Table
Tabular data display.
```
┌────────────────┬────────────────┬────────────────┬────────────┐
│ Name │ Type │ Status │ Actions │
├────────────────┼────────────────┼────────────────┼────────────┤
│ Cedar Point │ Theme Park │ Operating │ [View] │
│ Six Flags │ Theme Park │ Operating │ [View] │
│ Dreamworld │ Theme Park │ Operating │ [View] │
└────────────────┴────────────────┴────────────────┴────────────┘
```
**Features:**
- Sortable columns
- Row selection
- Pagination
- Filtering
- Column resizing
---
### Stats Card
Metric display.
```
┌─────────────────────────┐
│ Total Parks │
│ ──────────── │
│ 1,234 │
│ ↑ 12% from last month │
└─────────────────────────┘
```
---
### Rating Display
Star rating visualization.
```
★★★★☆ 4.2 (156 reviews)
```
**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `rating` | number | 0-5 rating value |
| `count` | number | Review count |
| `size` | string | Star size |
---
## Entity Components
### ParkCard
Park preview card.
```
┌─────────────────────────────────────┐
│ ┌─────────────────────────────┐ │
│ │ │ │
│ │ PARK IMAGE │ │
│ │ │ │
│ └─────────────────────────────┘ │
│ │
│ Cedar Point │
│ 📍 Sandusky, Ohio, USA │
│ 🎢 72 rides ★ 4.8 (156) │
│ │
│ [Operating] │
│ │
└─────────────────────────────────────┘
```
**Displays:**
- Park image
- Name
- Location
- Ride count
- Rating
- Status badge
---
### RideCard
Ride preview card.
```
┌─────────────────────────────────────┐
│ ┌─────────────────────────────┐ │
│ │ │ │
│ │ RIDE IMAGE │ │
│ │ │ │
│ └─────────────────────────────┘ │
│ │
│ Steel Vengeance │
│ Cedar Point │
│ ⚡ 121 km/h 📏 62.5m │
│ │
│ [Coaster] [Operating] │
│ │
└─────────────────────────────────────┘
```
**Displays:**
- Ride image
- Name
- Park name
- Key specs (speed, height)
- Category & status badges
---
### ReviewCard
User review display.
```
┌─────────────────────────────────────────────────────┐
│ ┌─────┐ username ★★★★★ │
│ │ │ Reviewed 2 days ago │
│ └─────┘ │
│ │
│ "Amazing coaster! The first drop is incredible │
│ and the airtime moments are relentless." │
│ │
│ 👍 24 👎 2 [Reply] [Report] │
│ │
└─────────────────────────────────────────────────────┘
```
---
### CreditCard
Ride credit display.
```
┌─────────────────────────────────────────────────────┐
│ ┌─────────────┐ Steel Vengeance │
│ │ │ Cedar Point │
│ │ IMG │ │
│ │ │ ×12 rides │
│ └─────────────┘ Last: August 2024 │
│ │
│ [−] 12 [+] [Edit] │
│ │
└─────────────────────────────────────────────────────┘
```
---
## Specialty Components
### UnitDisplay
Displays values with unit conversion.
```
Speed: 121 km/h (75 mph)
or
Speed: 75 mph
```
**Types:**
- Speed (km/h, mph)
- Distance (m, ft)
- Height (m, ft)
- Weight (kg, lbs)
---
### Map
Interactive Leaflet map.
```
┌─────────────────────────────────────────────────────┐
│ │
│ 📍 │
│ 📍 📍 │
│ 📍 │
│ 📍 │
│ 📍 │
│ │
│ [−][+] © OpenStreetMap │
└─────────────────────────────────────────────────────┘
```
**Features:**
- Marker clusters
- Custom markers
- Popups
- Zoom controls
- Full-screen toggle
---
### Timeline
Chronological event display.
```
│
├── 2024 ─── Renovation completed
│
├── 2022 ─── Major refurbishment
│
├── 2018 ─── Original opening
│
▼
```
---
### Diff Viewer
Side-by-side comparison.
```
┌────────────────────────┬────────────────────────┐
│ BEFORE │ AFTER │
├────────────────────────┼────────────────────────┤
│ Name: Old Name │ Name: New Name ← │
│ Status: Closed │ Status: Closed │
│ Rides: 50 │ Rides: 52 ← │
└────────────────────────┴────────────────────────┘
```
---
### ImageGallery
Photo gallery with lightbox.
```
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ │ │ │ │ │ │ │
│ 1 │ │ 2 │ │ 3 │ │ +24 │
│ │ │ │ │ │ │ │
└────────┘ └────────┘ └────────┘ └────────┘
```
**Features:**
- Grid layout
- Lightbox view
- Navigation (prev/next)
- Zoom
- Download
---
### SearchAutocomplete
Search with suggestions.
```
┌─────────────────────────────────────────────────────┐
│ 🔍 cedar │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 🏰 Cedar Point Park │
│ 🎢 Cedar Creek Mine Ride Ride │
│ 🏢 Cedar Fair Company │
└─────────────────────────────────────────────────────┘
```
---
### Tooltip
Hover information.
```
┌─────────────────────────┐
What is RMC? ───────│ Rocky Mountain │
│ Construction: A │
│ manufacturer known │
│ for hybrid coasters │
└─────────────────────────┘
```
---
### HoverCard
Rich preview on hover.
```
┌─────────────────────────┐
│ ┌─────────────────┐ │
│ │ IMAGE │ │
Cedar Point ────────────│ └─────────────────┘ │
│ Cedar Point │
│ Sandusky, Ohio │
│ 🎢 72 rides ★ 4.8 │
│ │
│ [View Park →] │
└─────────────────────────┘
```
---
## Related Documentation
- [Site Overview](./SITE_OVERVIEW.md)
- [Design System](./DESIGN_SYSTEM.md)
- [Pages](./PAGES.md)
- [User Flows](./USER_FLOWS.md)
Reference in New Issue View Git Blame Copy Permalink