← back to Wine Finder Next
COMPONENT_REFERENCE.md
522 lines
# Wine Finder - Component Reference Guide
## Component Hierarchy
```
App Root
│
├── Homepage (/)
│ ├── Header
│ │ ├── Logo/Icon (🍷)
│ │ ├── Title
│ │ └── SearchBar
│ ├── Stats Grid (4 cards)
│ ├── FeaturedSection (Hot Deals)
│ │ └── WineCard[] (grid)
│ ├── FeaturedSection (New Vintages)
│ │ └── WineCard[] (grid)
│ ├── FeaturedSection (Featured Selections)
│ │ └── WineCard[] (grid)
│ ├── Features Section
│ └── Footer
│
├── Search Results (/search?q={query})
│ ├── Header (sticky)
│ │ ├── Back Button
│ │ └── SearchBar
│ ├── Results Header
│ │ ├── Result Count
│ │ ├── SortDropdown
│ │ └── Reset Button
│ ├── FilterBar (expandable on mobile)
│ │ ├── Source Filters
│ │ ├── Price Range
│ │ ├── Rating Slider
│ │ ├── Wine Type
│ │ └── Region Search
│ ├── States (conditional)
│ │ ├── SkeletonLoader[] (loading)
│ │ ├── EmptyState (no results)
│ │ └── WineCard[] (results)
│ └── Load More Info
│
└── Wine Detail (/wine/[id])
├── Header
│ └── Back Button
├── Two-Column Layout
│ ├── Left Column (sticky)
│ │ ├── Wine Image
│ │ └── Rating Badge
│ └── Right Column
│ ├── Title & Price Card
│ ├── Description Card
│ ├── Tasting Notes Card
│ └── Food Pairings Card
├── WhereToBuy Section
│ └── Retailer Card[] (sorted by price)
├── PriceChart Section
└── RelatedWines Section
└── WineCard[] (grid)
```
---
## Mobile Layout Patterns (320px - 640px)
### Homepage Mobile Layout
```
┌─────────────────────────────────┐
│ 🍷 │ ← Logo (centered)
│ │
│ Red Thunder Wine Tracker │ ← Title (large, centered)
│ Discover 500,000+ Wines... │ ← Subtitle
│ │
│ ┌───────────────────────────┐ │
│ │ Search wines... 🔍 │ │ ← Search Bar (full width)
│ └───────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 500K+ │ │ 3+ │ │ ← Stats (2 cols)
│ │ Wines │ │ Sources │ │
│ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Live │ │ 24/7 │ │
│ │ Updates │ │ Tracking │ │
│ └──────────┘ └──────────┘ │
│ │
│ 🔥 Hot Deals │ ← Section Header
│ Limited time offers... │
│ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card] │ │ ← Full width card
│ │ Image │ │
│ │ Name, Price, Rating │ │
│ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card] │ │
│ └──────────────────────────┘ │
│ │
│ [View All (12 wines) →] │ ← View All Button
│ │
│ 🍇 New Vintages... │ ← Next Section
│ ... │
└─────────────────────────────────┘
```
---
### Search Results Mobile Layout
```
┌─────────────────────────────────┐
│ ← Back Wine Search │ ← Sticky Header
│ │
│ ┌───────────────────────────┐ │
│ │ Search wines... 🔍 │ │ ← Search Bar
│ └───────────────────────────┘ │
└─────────────────────────────────┘ ← End sticky section
┌─────────────────────────────────┐
│ 12 Wines Found │ ← Result Count
│ Results for "cabernet" │
│ │
│ [Sort: Price ▼] [Reset] │ ← Sort & Reset
│ │
│ ▼ Filters ▼ │ ← Expandable Filter
│ ┌──────────────────────────┐ │ Toggle (collapsed)
│ │ DATA SOURCES (3 selected)│ │
│ │ ┌────┐ ┌────┐ ┌────┐ │ │
│ │ │🍇 │ │🏪 │ │🍷 │ │ │ ← Source Pills
│ │ │Viv.│ │TW │ │K&L │ │ │
│ │ └────┘ └────┘ └────┘ │ │
│ │ │ │
│ │ PRICE RANGE │ │
│ │ ┌────┐ ┌────┐ │ │
│ │ │All │ │<$20│ [$20-$50] │ │ ← Price Buttons
│ │ └────┘ └────┘ │ │ (grid 2 cols)
│ │ │ │
│ │ MINIMUM RATING: 80/100 │ │
│ │ ────────●─────────── │ │ ← Slider
│ │ 0 50 100 │ │
│ │ │ │
│ │ WINE TYPE │ │
│ │ [All Types ▼] │ │ ← Dropdown
│ │ │ │
│ │ REGION │ │
│ │ [e.g. Napa Valley...] │ │ ← Text Input
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card 1] │ │ ← Results
│ │ Image │ │ (1 column)
│ │ 🆕 New Vintage │ │ (staggered fade)
│ │ Caymus Cab 2021 │ │
│ │ $89.99 ⭐ 92 │ │
│ │ [View Details →] │ │
│ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card 2] │ │
│ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card 3] │ │
│ └──────────────────────────┘ │
│ │
│ Showing 12 of 12 results │
└─────────────────────────────────┘
```
---
### Wine Detail Mobile Layout
```
┌─────────────────────────────────┐
│ ← Back │ ← Sticky Header
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ │ │
│ │ Bottle │ │ ← Wine Image
│ │ Image │ │ (large)
│ │ │ │
│ └──────────┘ │
│ │
│ ┌──────────────┐ │
│ │ ⭐ 92 │ │ ← Rating Badge
│ │ 45,231 rev. │ │
│ └──────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ Caymus Cabernet Sauvignon│ │ ← Title & Price Card
│ │ [2021] $89.99 │ │
│ │ │ │
│ │ 🏛️ Caymus Vineyards │ │
│ │ 📍 Napa Valley, USA │ │
│ │ │ │
│ │ ┌────┐ ┌────┐ │ │
│ │ │Red │ │Cab │ [14.5%] │ │ ← Quick Info
│ │ └────┘ └────┘ │ │
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ About This Wine │ │ ← Description Card
│ │ │ │
│ │ Rich and concentrated... │ │
│ │ [Read more] │ │ ← Expandable
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ Tasting Notes │ │
│ │ │ │
│ │ [Blackberry] [Cherry] │ │ ← Chips
│ │ [Vanilla] [Oak] [Pepper] │ │ (wrap)
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ 🍽️ Perfect Pairings │ │
│ │ │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │ Steak │ │ Lamb │ │ │ ← Grid 2 cols
│ │ └────────┘ └────────┘ │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │ Cheese │ │ Ribs │ │ │
│ │ └────────┘ └────────┘ │ │
│ └──────────────────────────┘ │
│ │
│ Where to Buy │ ← Section Header
│ Compare prices from trusted... │
│ │
│ ┌──────────────────────────┐ │
│ │ 🏆 Best Price │ │ ← Gold gradient
│ │ │ │ background
│ │ 🍇 Vivino │ │
│ │ [✓ In Stock] │ │
│ │ │ │
│ │ $89.99 │ │
│ │ [Buy Now →] │ │ ← Gold button
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ 🏪 Total Wine & More │ │
│ │ [✓ In Stock] │ │
│ │ │ │
│ │ $94.99 │ │
│ │ [Buy Now →] │ │ ← Wine button
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ 🍷 K&L Wine Merchants │ │
│ │ [⚠ Limited Stock] │ │
│ │ │ │
│ │ $92.99 │ │
│ │ [Buy Now →] │ │
│ └──────────────────────────┘ │
│ │
│ 💡 Price difference: $5.00 │ ← Summary
│ │
│ Price History │ ← Chart Section
│ ┌──────────────────────────┐ │
│ │ Current: $89.99 │ │
│ │ 🔥 Deal Score: 75 │ │
│ │ 📉 Falling │ │
│ │ │ │
│ │ ┌───────┐ │ │
│ │ ───┤ Chart ├─── │ │ ← Area Chart
│ │ └───────┘ │ │
│ │ │ │
│ │ Avg $93 | Low $90 | Hi $95│ │
│ │ 4 price points tracked │ │
│ └──────────────────────────┘ │
│ │
│ You Might Also Like │ ← Related Section
│ Similar wines from Napa... │
│ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card 1] │ │ ← 1 col on mobile
│ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
│ │ [Wine Card 2] │ │
│ └──────────────────────────┘ │
└─────────────────────────────────┘
```
---
## Tablet Layout (640px - 1024px)
### Search Results (2-column grid)
```
┌────────────────────────────────────────────────┐
│ ← Back Wine Search │
│ ┌──────────────────────────────────────────┐ │
│ │ Search wines... 🔍 [Search] │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 12 Wines Found [Sort ▼] [Reset]│
│ Results for "cabernet" │
│ │
│ Filters (always visible) │
│ ┌────────────────────────────────────────┐ │
│ │ Sources: [🍇 Vivino] [🏪 TW] [🍷 K&L] │ │
│ │ Price: [All] [<$20] [$20-$50]... │ │
│ │ Rating: ────●──────── 80/100 │ │
│ │ Type: [All Types ▼] Region: [...] │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ [Wine Card] │ │ [Wine Card] │ │ 2 columns
│ │ Image │ │ Image │ │
│ │ Details │ │ Details │ │
│ └────────────────┘ └────────────────┘ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ [Wine Card] │ │ [Wine Card] │ │
│ └────────────────┘ └────────────────┘ │
└────────────────────────────────────────────────┘
```
---
## Desktop Layout (1024px+)
### Homepage (4-column grid)
```
┌──────────────────────────────────────────────────────────────┐
│ 🍷 Red Thunder Wine Tracker │
│ Discover 500,000+ Wines • Track Prices... │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Search wines... 🔍 [Search] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │500K+ │ │ 3+ │ │ Live │ │ 24/7 │ │ 4 cols
│ │Wines │ │Source│ │Update│ │Track │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ 🔥 Hot Deals │
│ Limited time offers and price drops │
│ │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │Wine│ │Wine│ │Wine│ │Wine│ │ 4 cols
│ │Card│ │Card│ │Card│ │Card│ │
│ └────┘ └────┘ └────┘ └────┘ │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │Wine│ │Wine│ │Wine│ │Wine│ │
│ │Card│ │Card│ │Card│ │Card│ │
│ └────┘ └────┘ └────┘ └────┘ │
│ │
│ [View All (12 wines) →] │
└──────────────────────────────────────────────────────────────┘
```
### Wine Detail (2-column sticky)
```
┌──────────────────────────────────────────────────────────────┐
│ ← Back │
│ │
│ ┌────────────────────┐ ┌────────────────────────────────┐ │
│ │ │ │ Caymus Cabernet Sauvignon │ │
│ │ │ │ [2021] $89.99 │ │
│ │ Bottle │ │ │ │
│ │ Image │ │ 🏛️ Caymus Vineyards │ │
│ │ (sticky) │ │ 📍 Napa Valley, USA │ │
│ │ │ │ │ │
│ │ │ │ [Red] [Cabernet] [14.5%] │ │
│ │ ┌──────────────┐ │ │─────────────────────────────── │ │
│ │ │ ⭐ 92 │ │ │ │ │
│ │ │ 45,231 rev. │ │ │ About This Wine │ │
│ │ └──────────────┘ │ │ Rich and concentrated... │ │
│ │ │ │ │ │
│ └────────────────────┘ │ Tasting Notes │ │
│ │ [Blackberry] [Cherry]... │ │
│ │ │ │
│ │ 🍽️ Perfect Pairings │ │
│ │ [Steak] [Lamb] [Cheese] [Ribs] │ │
│ └────────────────────────────────┘ │
│ │
│ Where to Buy │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🏆 Best Price │ │
│ │ 🍇 Vivino [✓ In Stock] $89.99 [Buy Now →] │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 🏪 Total Wine [✓ In Stock] $94.99 [Buy Now →] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ You Might Also Like │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │Wine│ │Wine│ │Wine│ │Wine│ │ 4 cols
│ └────┘ └────┘ └────┘ └────┘ │
└──────────────────────────────────────────────────────────────┘
```
---
## Component States
### WineCard States
```
Default Hover (desktop) Active (mobile) Loading
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│Image │ │Image │ │Image │ │░░░░░░│
│ │ → │ ↗️ │ → │ ↘️ │ → │░░░░░░│
│Name │ mouse │Name │ tap │Name │ │░░░░░░│
│$99 │ over │$99 │ │$99 │ │░░░░░░│
└──────┘ └──────┘ └──────┘ └──────┘
shadow-md scale(1.05) scale(0.98) pulse
shadow-wine-lg
```
### Button States
```
Default Hover Focus Disabled
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│Buy Now →│ → │Buy Now →│ → │Buy Now →│ │Buy Now →│
└──────────┘ └──────────┘ └──────────┘ └──────────┘
wine-600 wine-700 gold outline opacity-50
shadow-lg no pointer
```
### Input States
```
Default Focus Error Success
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│Search... │ → │Search... │ │Search... │ │Search... │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
border-gray-200 border-wine-600 border-red-500 border-green-500
ring-wine-200
```
---
## Animation Timing
```
Component Animation Duration Easing
─────────────────────────────────────────────────────────
Page Load fade-in 0.5s ease-in-out
Section Entry slide-up 0.4s ease-out
Wine Card scale-in 0.3s ease-out
Staggered Cards slide-up 0.4s +0.05s delay
Button Hover transform 0.3s ease
Filter Toggle slide-down 0.4s ease-out
Loading Skeleton shimmer 2s linear infinite
Price Badge bounce-subtle 2s infinite
```
---
## Accessibility Annotations
### Focus Order
```
1. Skip to main content (future)
2. Logo/Home link
3. Search input
4. Search button
5. Filter toggles
6. Wine cards (in reading order)
7. Footer links
```
### Screen Reader Announcements
```
Search completed → "Found 12 wines for cabernet"
Filter applied → "Filtered to 8 wines"
Sort changed → "Sorted by price: low to high"
Loading → "Loading wine results"
Error → "Error: Unable to load wines. Try again."
```
### Keyboard Shortcuts (Future)
```
/ → Focus search bar
Esc → Close modals/filters
Tab → Navigate forward
Shift+Tab → Navigate backward
Enter → Activate focused element
Space → Toggle checkboxes
Arrow Keys → Navigate within dropdowns
```
---
## File Paths Reference
All component files are located in:
```
/root/Projects/wine-finder-next/components/
```
All page files are located in:
```
/root/Projects/wine-finder-next/app/
```
## Quick Component Import Examples
```tsx
// Homepage
import SearchBar from '@/components/SearchBar'
import FeaturedSection from '@/components/FeaturedSection'
import WineCard from '@/components/WineCard'
// Search Page
import FilterBar from '@/components/FilterBar'
import SortDropdown from '@/components/SortDropdown'
import SkeletonLoader from '@/components/SkeletonLoader'
import EmptyState from '@/components/EmptyState'
// Wine Detail Page
import PriceChart from '@/components/PriceChart'
import WhereToBuy from '@/components/WhereToBuy'
import RelatedWines from '@/components/RelatedWines'
```
---
Last Updated: 2025-11-15