Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX

2025-12-23 12:51:09 -05:00 · 2025-12-22 16:56:27 -05:00
parent 2e35f8c5d9
commit ae31e889d7
144 changed files with 25792 additions and 4440 deletions
--- a/backend/templates/components/navigation/README.md
+++ b/backend/templates/components/navigation/README.md
@@ -0,0 +1,133 @@
+# Navigation Components
+
+This directory contains navigation-related template components.
+
+## Components
+
+### breadcrumbs.html
+
+Semantic breadcrumb navigation with Schema.org structured data support.
+
+#### Features
+
+- Accessible navigation with proper ARIA attributes
+- Schema.org BreadcrumbList JSON-LD for SEO
+- Responsive design with mobile-friendly collapse
+- Customizable separators and icons
+- Truncation for long labels
+
+#### Basic Usage
+
+```django
+{# Breadcrumbs are automatically included from context processor #}
+{% include 'components/navigation/breadcrumbs.html' %}
+```
+
+#### Setting Breadcrumbs in Views
+
+```python
+from apps.core.utils.breadcrumbs import build_breadcrumb, BreadcrumbBuilder
+from django.urls import reverse
+
+def park_detail(request, slug):
+    park = get_object_or_404(Park, slug=slug)
+
+    # Option 1: Build breadcrumbs manually
+    request.breadcrumbs = [
+        build_breadcrumb('Home', '/', icon='fas fa-home'),
+        build_breadcrumb('Parks', reverse('parks:list')),
+        build_breadcrumb(park.name, is_current=True),
+    ]
+
+    # Option 2: Use the builder pattern
+    request.breadcrumbs = (
+        BreadcrumbBuilder()
+        .add_home()
+        .add('Parks', reverse('parks:list'))
+        .add_current(park.name)
+        .build()
+    )
+
+    return render(request, 'parks/detail.html', {'park': park})
+```
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `items` | list | `breadcrumbs` | List of Breadcrumb objects |
+| `show_schema` | bool | `True` | Include Schema.org JSON-LD |
+| `show_home_icon` | bool | `True` | Show icon on home breadcrumb |
+| `separator` | str | chevron | Custom separator character |
+| `max_visible` | int | `3` | Max items before mobile collapse |
+| `container_class` | str | `""` | Additional CSS classes |
+
+#### Accessibility
+
+- Uses `<nav>` element with `aria-label="Breadcrumb"`
+- Ordered list (`<ol>`) for semantic structure
+- `aria-current="page"` on current page item
+- Hidden separators for screen readers
+
+#### Examples
+
+**Custom separator:**
+```django
+{% include 'components/navigation/breadcrumbs.html' with separator='/' %}
+```
+
+**Without Schema.org:**
+```django
+{% include 'components/navigation/breadcrumbs.html' with show_schema=False %}
+```
+
+**Custom breadcrumbs:**
+```django
+{% include 'components/navigation/breadcrumbs.html' with items=custom_crumbs %}
+```
+
+## Breadcrumb Utilities
+
+### BreadcrumbBuilder
+
+Fluent builder for constructing breadcrumbs:
+
+```python
+from apps.core.utils.breadcrumbs import BreadcrumbBuilder
+
+breadcrumbs = (
+    BreadcrumbBuilder()
+    .add_home()
+    .add_from_url('parks:list', 'Parks')
+    .add_model(park)
+    .add_from_url('rides:list', 'Rides', {'park_slug': park.slug})
+    .add_model_current(ride)
+    .build()
+)
+```
+
+### get_model_breadcrumb
+
+Generate breadcrumbs for model instances with parent relationships:
+
+```python
+from apps.core.utils.breadcrumbs import get_model_breadcrumb
+
+# For a Ride that belongs to a Park
+breadcrumbs = get_model_breadcrumb(
+    ride,
+    parent_attr='park',
+    list_url_name='rides:list',
+    list_label='Rides',
+)
+# Returns: [Home, Parks, Cedar Point, Rides, Millennium Force]
+```
+
+## Context Processor
+
+The `breadcrumbs` context processor (`apps.core.context_processors.breadcrumbs`) provides:
+
+- `breadcrumbs`: List of Breadcrumb objects from view
+- `breadcrumbs_json`: Schema.org JSON-LD string
+- `BreadcrumbBuilder`: Builder class for templates
+- `build_breadcrumb`: Helper function for creating items