# Sprint 3-4: Product Catalog & Cart

**Duration:** Sprint 3-4 (2 weeks)  
**Status:** 🚀 Ready to Start  
**Prerequisites:** ✅ Sprint 1-2 Complete

---

## Objectives

Build out the complete product catalog experience and shopping cart functionality.

### Sprint 3: Product Catalog Enhancement
1. **Product Detail Page** - Full product view with variations
2. **Product Filters** - Category, price, attributes
3. **Product Search** - Real-time search with debouncing
4. **Product Sorting** - Price, popularity, rating, date

### Sprint 4: Shopping Cart
1. **Cart Page** - View and manage cart items
2. **Cart Sidebar** - Quick cart preview
3. **Cart API Integration** - Sync with WooCommerce cart
4. **Coupon Application** - Apply and remove coupons

---

## Sprint 3: Product Catalog Enhancement

### 1. Product Detail Page (`/product/:id`)

**File:** `customer-spa/src/pages/Product/index.tsx`

**Features:**
- Product images gallery with zoom
- Product title, price, description
- Variation selector (size, color, etc.)
- Quantity selector
- Add to cart button
- Related products
- Product reviews (if enabled)

**API Endpoints:**
- `GET /shop/products/:id` - Get product details
- `GET /shop/products/:id/related` - Get related products (optional)

**Components to Create:**
- `ProductGallery.tsx` - Image gallery with thumbnails
- `VariationSelector.tsx` - Select product variations
- `QuantityInput.tsx` - Quantity selector
- `ProductMeta.tsx` - SKU, categories, tags
- `RelatedProducts.tsx` - Related products carousel

---

### 2. Product Filters

**File:** `customer-spa/src/components/Shop/Filters.tsx`

**Features:**
- Category filter (tree structure)
- Price range slider
- Attribute filters (color, size, brand, etc.)
- Stock status filter
- On sale filter
- Clear all filters button

**State Management:**
- Use URL query parameters for filters
- Persist filters in URL for sharing

**Components:**
- `CategoryFilter.tsx` - Hierarchical category tree
- `PriceRangeFilter.tsx` - Price slider
- `AttributeFilter.tsx` - Checkbox list for attributes
- `ActiveFilters.tsx` - Show active filters with remove buttons

---

### 3. Product Search Enhancement

**Current:** Basic search input  
**Enhancement:** Real-time search with suggestions

**Features:**
- Search as you type
- Search suggestions dropdown
- Recent searches
- Popular searches
- Product thumbnails in results
- Keyboard navigation (arrow keys, enter, escape)

**File:** `customer-spa/src/components/Shop/SearchBar.tsx`

---

### 4. Product Sorting

**Features:**
- Sort by: Default, Popularity, Rating, Price (low to high), Price (high to low), Latest
- Dropdown selector
- Persist in URL

**File:** `customer-spa/src/components/Shop/SortDropdown.tsx`

---

## Sprint 4: Shopping Cart

### 1. Cart Page (`/cart`)

**File:** `customer-spa/src/pages/Cart/index.tsx`

**Features:**
- Cart items list with thumbnails
- Quantity adjustment (+ / -)
- Remove item button
- Update cart button
- Cart totals (subtotal, tax, shipping, total)
- Coupon code input
- Proceed to checkout button
- Continue shopping link
- Empty cart state

**Components:**
- `CartItem.tsx` - Single cart item row
- `CartTotals.tsx` - Cart totals summary
- `CouponForm.tsx` - Apply coupon code
- `EmptyCart.tsx` - Empty cart message

---

### 2. Cart Sidebar/Drawer

**File:** `customer-spa/src/components/Cart/CartDrawer.tsx`

**Features:**
- Slide-in from right
- Mini cart items (max 5, then scroll)
- Cart totals
- View cart button
- Checkout button
- Close button
- Backdrop overlay

**Trigger:**
- Click cart icon in header
- Auto-open when item added (optional)

---

### 3. Cart API Integration

**Endpoints:**
- `GET /cart` - Get current cart
- `POST /cart/add` - Add item to cart
- `PUT /cart/update` - Update item quantity
- `DELETE /cart/remove` - Remove item
- `POST /cart/apply-coupon` - Apply coupon
- `DELETE /cart/remove-coupon` - Remove coupon

**State Management:**
- Zustand store already created (`customer-spa/src/lib/cart/store.ts`)
- Sync with WooCommerce session
- Persist cart in localStorage
- Handle cart conflicts (server vs local)

---

### 4. Coupon System

**Features:**
- Apply coupon code
- Show discount amount
- Show coupon description
- Remove coupon button
- Error handling (invalid, expired, usage limit)

**Backend:**
- Already implemented in `CartController.php`
- `POST /cart/apply-coupon`
- `DELETE /cart/remove-coupon`

---

## Technical Considerations

### Performance
- Lazy load product images
- Implement infinite scroll for product grid (optional)
- Cache product data with TanStack Query
- Debounce search and filter inputs

### UX Enhancements
- Loading skeletons for all states
- Optimistic updates for cart actions
- Toast notifications for user feedback
- Smooth transitions and animations
- Mobile-first responsive design

### Error Handling
- Network errors
- Out of stock products
- Invalid variations
- Cart conflicts
- API timeouts

### Accessibility
- Keyboard navigation
- Screen reader support
- Focus management
- ARIA labels
- Color contrast

---

## Implementation Order

### Week 1 (Sprint 3)
1. **Day 1-2:** Product Detail Page
   - Basic layout and product info
   - Image gallery
   - Add to cart functionality

2. **Day 3:** Variation Selector
   - Handle simple and variable products
   - Update price based on variation
   - Validation

3. **Day 4-5:** Filters & Search
   - Category filter
   - Price range filter
   - Search enhancement
   - Sort dropdown

### Week 2 (Sprint 4)
1. **Day 1-2:** Cart Page
   - Cart items list
   - Quantity adjustment
   - Cart totals
   - Coupon application

2. **Day 3:** Cart Drawer
   - Slide-in sidebar
   - Mini cart items
   - Quick actions

3. **Day 4:** Cart API Integration
   - Sync with backend
   - Handle conflicts
   - Error handling

4. **Day 5:** Polish & Testing
   - Responsive design
   - Loading states
   - Error states
   - Cross-browser testing

---

## Success Criteria

### Sprint 3
- ✅ Product detail page displays all product info
- ✅ Variations can be selected and price updates
- ✅ Filters work and update product list
- ✅ Search returns relevant results
- ✅ Sorting works correctly

### Sprint 4
- ✅ Cart page displays all cart items
- ✅ Quantity can be adjusted
- ✅ Items can be removed
- ✅ Coupons can be applied and removed
- ✅ Cart drawer opens and closes smoothly
- ✅ Cart syncs with WooCommerce backend
- ✅ Cart persists across page reloads

---

## Next Steps

1. Review this plan
2. Confirm priorities
3. Start with Product Detail Page
4. Implement features incrementally
5. Test each feature before moving to next

**Ready to start Sprint 3?** 🚀