superdesign

.superdesign/init/extractable-components.md

@@ -0,0 +1,386 @@
+# Extractable UI Components
+
+This document identifies reusable UI components that could be extracted, packaged, and reused across other projects.
+
+---
+
+## Form Components
+
+### 1. Search Input with Debounce
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 8-16)  
+**Category:** Forms  
+**Complexity:** Low
+
+**Props:**
+- `name`: Input field name
+- `wire:model`: Livewire property binding
+- `label`: Display label
+- `placeholder`: Placeholder text
+
+**Features:**
+- Flux form styling
+- Wire model binding support
+- Error message display
+
+**Extractable:** Yes - Generic search input wrapper
+
+---
+
+### 2. Multi-Option Select Dropdown
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 20-28, 34-42, 44-52)  
+**Category:** Forms  
+**Complexity:** Low
+
+**Props:**
+- `wire:model.live` or `wire:model`: Binding
+- `name`: Field name
+- `label`: Label text
+- Options as slot
+
+**Features:**
+- Reactive updates via `wire:model.live`
+- Error display
+- Multiple select options
+
+**Variants:**
+- Fuel type selector (6 options)
+- Radius selector (5 options)
+- Sort selector (5 options)
+
+**Extractable:** Yes - Reusable select component wrapper
+
+---
+
+### 3. Form Submission Button with Loading State
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 54-59)  
+**Category:** Forms  
+**Complexity:** Low
+
+**Props:**
+- `type`: button type
+- `variant`: "primary", etc.
+- `wire:loading.attr`: Disabled state during loading
+- `wire:target`: Target action
+
+**Features:**
+- Dynamic text based on loading state
+- Wire loading indicators
+- Primary variant styling
+
+**Extractable:** Yes - Generic loading button component
+
+---
+
+## Data Display Components
+
+### 4. Station Result Card
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 94-128)  
+**Category:** Data Display  
+**Complexity:** Medium
+
+**Props:**
+- `station`: Object with station data
+  - `name`: Station name
+  - `address`: Street address
+  - `postcode`: Postcode
+  - `distance_km`: Distance in kilometers
+  - `price`: Fuel price in pence
+  - `price_classification`: One of (current, recent, stale, outdated)
+  - `price_classification_label`: Human label
+  - `price_updated_at`: ISO date string
+  - `is_supermarket`: Boolean
+
+**Features:**
+- Responsive layout (flex items-center justify-between)
+- Color-coded price based on freshness
+- Supermarket badge display
+- Distance/address display
+- Time-ago formatting
+
+**Extractable:** Yes - Could be standalone component for displaying station data
+
+---
+
+### 5. Results Count Summary
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 72-76)  
+**Category:** Data Display  
+**Complexity:** Low
+
+**Props:**
+- `count`: Total stations found
+- `lowest_pence`: Lowest price in pence
+- `avg_pence`: Average price in pence
+
+**Features:**
+- Formatted currency display
+- Singular/plural handling
+- Stats display on one line
+
+**Extractable:** Yes - Generic stats summary component
+
+---
+
+### 6. Classification Legend/Color Code Guide
+**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 84-90)  
+**Category:** Data Display  
+**Complexity:** Low
+
+**Props:**
+- Array of classification items with colors and labels
+
+**Features:**
+- Inline color swatches
+- Legend item labels
+- Responsive flex layout
+
+**Extractable:** Yes - Reusable legend component
+
+---
+
+## Navigation Components
+
+### 7. Settings Sidebar Navigation
+**Source:** `resources/views/pages/settings/layout.blade.php` (lines 3-7)  
+**Category:** Navigation  
+**Complexity:** Low
+
+**Props:**
+- Navigation items array with:
+  - `label`: Display text
+  - `route`: Route name
+  - `icon`: Optional icon name
+
+**Features:**
+- flux:navlist component
+- wire:navigate support
+- Active state detection
+- Mobile/desktop responsive
+
+**Extractable:** Yes - Generic sidebar nav for multi-section pages
+
+---
+
+### 8. User Profile Dropdown Menu
+**Source:** `resources/views/components/desktop-user-menu.blade.php`  
+**Category:** Navigation  
+**Complexity:** Medium
+
+**Props:**
+- User object with:
+  - `name`: User name
+  - `email`: User email
+  - `initials()`: Method to get initials
+
+**Features:**
+- Flux dropdown + menu
+- Avatar display with initials
+- Settings link
+- Logout form with CSRF
+- Test attributes for QA
+
+**Extractable:** Yes - Standalone user menu component for authenticated apps
+
+---
+
+## Layout Components
+
+### 9. Centered Authentication Layout Container
+**Source:** `resources/views/layouts/auth/simple.blade.php`  
+**Category:** Layouts  
+**Complexity:** Low
+
+**Props:**
+- None (slot-based)
+
+**Features:**
+- Centered flex layout
+- Max-width constraint (sm)
+- Dark gradient background
+- Logo link at top
+- Responsive padding
+
+**Extractable:** Yes - Generic centered auth layout
+
+---
+
+### 10. Card-Based Form Container
+**Source:** `resources/views/layouts/auth/card.blade.php`  
+**Category:** Layouts  
+**Complexity:** Low
+
+**Props:**
+- None (slot-based)
+
+**Features:**
+- White card on dark background
+- Rounded borders with shadow
+- Dark mode support
+- Centered with max-width
+- Padding inside card
+
+**Extractable:** Yes - Modal/card wrapper component
+
+---
+
+### 11. Split-Screen Auth Layout
+**Source:** `resources/views/layouts/auth/split.blade.php`  
+**Category:** Layouts  
+**Complexity:** Medium
+
+**Props:**
+- Quote display (generated from Inspiring::quotes)
+
+**Features:**
+- Two-column grid (desktop only)
+- Dark sidebar with quote/branding
+- Form content on right
+- Mobile-friendly (single column)
+- Absolute background fill
+
+**Extractable:** Yes - Premium auth layout component
+
+---
+
+## Status/Feedback Components
+
+### 12. Temporary Action Message
+**Source:** `resources/views/components/action-message.blade.php`  
+**Category:** Feedback  
+**Complexity:** Low
+
+**Props:**
+- `on`: Livewire event to listen to
+- Slot for custom message (defaults to "Saved.")
+
+**Features:**
+- Alpine.js event listener
+- Auto-hide after 2 seconds
+- Fade transition
+- Livewire integration
+
+**Extractable:** Yes - Generic toast/message component
+
+---
+
+### 13. Session Status Message
+**Source:** `resources/views/components/auth-session-status.blade.php`  
+**Category:** Feedback  
+**Complexity:** Low
+
+**Props:**
+- `status`: Status message text
+
+**Features:**
+- Conditional rendering
+- Green success styling
+- Used in auth forms
+
+**Extractable:** Yes - Simple status display component
+
+---
+
+## Map/Visualization Components
+
+### 14. Leaflet Map Integration
+**Source:** `resources/js/maps/station-map.js`  
+**Category:** Map/Visualization  
+**Complexity:** High
+
+**Props:**
+- `results`: Array of station data with lat/lng/classifications
+
+**Features:**
+- Leaflet map initialization
+- OpenStreetMap tiles
+- Custom circle markers with colors
+- Popup on marker click
+- Auto-fit bounds
+- Reactive to data changes
+
+**Extractable:** Yes - Could be abstracted into reusable Leaflet component
+
+**Note:** Currently tightly coupled to Alpine.js and station data structure. Would require prop mapping for reuse.
+
+---
+
+## Typography/Header Components
+
+### 15. Auth Page Header
+**Source:** `resources/views/components/auth-header.blade.php`  
+**Category:** Typography  
+**Complexity:** Low
+
+**Props:**
+- `title`: Main heading
+- `description`: Subheading
+
+**Features:**
+- Centered text
+- Flux typography (heading + subheading)
+- Used on all auth pages
+
+**Extractable:** Yes - Generic header for centered pages
+
+---
+
+### 16. Settings Page Header
+**Source:** `resources/views/partials/settings-heading.blade.php`  
+**Category:** Typography  
+**Complexity:** Low
+
+**Props:**
+- None (hardcoded for settings)
+
+**Features:**
+- Page title "Settings"
+- Subheading text
+- Separator line
+
+**Extractable:** Maybe - Specific to settings but pattern is reusable
+
+---
+
+## Reusability Summary Table
+
+| Component | Type | Complexity | Reusable | Dependencies | Extraction Cost |
+|-----------|------|-----------|----------|---|---|
+| Search Input | Form | Low | High | Flux | Very Low |
+| Select Dropdown | Form | Low | High | Flux | Very Low |
+| Loading Button | Form | Low | High | Flux, Livewire | Very Low |
+| Station Card | Display | Medium | High | Flux | Low |
+| Stats Summary | Display | Low | High | None | Very Low |
+| Legend | Display | Low | High | Tailwind | Very Low |
+| Settings Nav | Nav | Low | High | Flux | Very Low |
+| User Menu | Nav | Medium | High | Flux, Auth | Low |
+| Simple Auth Layout | Layout | Low | High | Tailwind | Very Low |
+| Card Container | Layout | Low | High | Tailwind | Very Low |
+| Split Layout | Layout | Medium | High | Tailwind | Low |
+| Action Message | Feedback | Low | High | Alpine, Livewire | Very Low |
+| Status Message | Feedback | Low | High | None | Very Low |
+| Leaflet Map | Visualization | High | Medium | Leaflet, Alpine | Medium |
+| Auth Header | Typography | Low | High | Flux | Very Low |
+| Settings Header | Typography | Low | Medium | Flux | Very Low |
+
+---
+
+## Top Candidates for Extraction
+
+1. **Search Input Component** - Generic, simple, widely useful
+2. **Station Card Component** - Good showcase of complex data display
+3. **User Menu Component** - Authentication pattern, widely needed
+4. **Loading Button Component** - Form UX pattern, commonly needed
+5. **Simple Auth Layout** - Authentication flows are common
+
+---
+
+## Framework Package Recommendations
+
+If extracting these components into a package:
+
+1. Make them framework-agnostic (or have adapters)
+2. Ensure Flux/Livewire are peer dependencies
+3. Document required Alpine.js versions
+4. Provide TypeScript declarations for props
+5. Include Storybook examples
+6. Consider CSS-in-JS vs Tailwind integration
+