# Navbar Component

## Contents

- [Overview](#overview)
- [Decision: Simple Dropdown vs Megamenu](#decision-simple-dropdown-vs-megamenu)
- [Key Ecommerce Patterns](#key-ecommerce-patterns)
- [Layout Structure](#layout-structure)
- [Accessibility Essentials](#accessibility-essentials)
- [Common Ecommerce Mistakes](#common-ecommerce-mistakes)
- [Backend Integration](#backend-integration)
- [Checklist](#checklist)

## Overview

Primary navigation for ecommerce storefronts. Desktop: horizontal menu with category links. Mobile: hamburger drawer with accordion subcategories.

### ⚠️ CRITICAL: NEVER Hardcode Categories

**ALWAYS fetch categories dynamically from the backend. NEVER hardcode static category arrays.**

❌ **WRONG - DO NOT DO THIS:**
```typescript
// WRONG - Static hardcoded categories
const categories = [
  { name: "Women", href: "/categories/women" },
  { name: "Men", href: "/categories/men" },
  { name: "Accessories", href: "/categories/accessories" }
]
```

✅ **CORRECT - Fetch from backend:**
```typescript
// CORRECT - Fetch categories dynamically
const [categories, setCategories] = useState([])

useEffect(() => {
  fetch(`${apiUrl}/store/product-categories`)
    .then(res => res.json())
    .then(data => setCategories(data.product_categories))
}, [])
```

**Why this matters:**
- Categories change frequently (new categories, renamed, reordered)
- Hardcoded categories become outdated immediately
- Requires code changes every time categories change
- Cannot scale to stores with dynamic catalogs
- Defeats the purpose of headless commerce

### Key Requirements

- Desktop: Horizontal category links, cart/account/search right-aligned
- Mobile: Hamburger drawer, cart stays visible in header (not hidden in drawer)
- **CRITICAL: Fetch categories from backend dynamically (NEVER hardcode static arrays)**
- Sticky: Recommended for easy cart access while browsing
- Real-time updates: Cart count, login state, category changes

## Decision: Simple Dropdown vs Megamenu

**Use Simple Dropdown when:**
- <10 top-level categories
- Flat or shallow hierarchy (1-2 levels deep)
- Minimal subcategories per parent
- Focused/specialized product catalog

**Use Megamenu when:**
- 10+ top-level categories
- Deep hierarchy (3+ levels)
- Need to showcase featured products in navigation
- Complex product catalog
- Fashion, electronics, or large inventory

**Mobile**: Always use drawer with accordion pattern, never megamenu on mobile.

See [megamenu.md](megamenu.md) for megamenu implementation details.

## Key Ecommerce Patterns

### Cart Indicator (CRITICAL)

**Always visible on both desktop and mobile:**
- Desktop: Top-right, cart icon + count badge
- Mobile: Top-right in header (NOT hidden in hamburger drawer)
- This is non-negotiable - users expect cart always accessible

**Badge display:**
- Shows item count (NOT price - confusing when variants change)
- Only visible when cart has items (count > 0)
- Show actual count up to 99, then "99+"
- Position: Top-right corner of cart icon
- ARIA label: `aria-label="Shopping cart with 3 items"`

**Real-time updates:**
- Update count immediately when items added (optimistic UI)
- No page refresh required
- Sync with backend cart state
- Handle errors gracefully (restore count if add fails)

**Click behavior:**
- Option 1: Navigate to cart page
- Option 2: Open cart popup/drawer (see cart-popup.md)
- Choice depends on store type (see cart-popup.md for decision criteria)

✅ **CORRECT:**
- Cart icon visible in mobile header
- Badge shows count (not price)
- Updates in real-time without page refresh
- 44x44px touch target
- Links to cart or opens cart popup

❌ **WRONG:**
- Hiding cart in mobile hamburger drawer (users can't find it)
- Showing price in badge (€25.99) instead of count
- Cart count doesn't update until page refresh
- No visual feedback when items added

### Category Navigation

**CRITICAL: Fetch dynamically from backend (NEVER hardcode):**

❌ **WRONG - These are all incorrect approaches:**
```typescript
// WRONG - Hardcoded array
const categories = ["Women", "Men", "Kids", "Accessories"]

// WRONG - Static object array
const categories = [
  { id: 1, name: "Women", slug: "women" },
  { id: 2, name: "Men", slug: "men" }
]

// WRONG - Importing static data
import { categories } from "./categories.ts"
```

✅ **CORRECT - Fetch from backend API:**
- Medusa: Use SDK category list method (verify exact method with docs/MCP)
- Other backends: Call categories endpoint (check API documentation)
- Fetch on component mount or during server-side rendering

**Why dynamic fetching is mandatory:**
- Store owners add/remove/rename categories frequently
- Category order and hierarchy changes
- Multi-language stores need translated category names
- Featured categories rotate (seasonal, promotions)
- Hardcoded values require developer intervention for simple changes

**Caching strategy:**
- Cache categories (revalidate on interval or manual trigger)
- Use SWR, TanStack Query, or framework-level caching
- Revalidate every 5-10 minutes or on page navigation
- Update immediately when backend categories change

**Organization:**
- 4-7 top-level categories ideal (max 10 on desktop)
- Order comes from backend (respects admin's ordering)
- Keep "Sale" or "New Arrivals" prominent if backend provides it
- Maximum 2 levels in simple dropdown (category → subcategory)
- Deeper hierarchies: Use megamenu or separate category pages

**Desktop behavior:**
- Horizontal links with hover dropdowns for subcategories
- Slight hover delay to prevent accidental triggers
- Click parent to navigate to category page
- Click child to navigate to subcategory

**Mobile behavior:**
- All categories in hamburger drawer
- Accordion pattern for subcategories (expand/collapse)
- Close drawer on category click (except expanding accordion)
- Scrollable drawer if categories exceed viewport height

✅ **CORRECT:**
- Categories fetched from backend API on mount
- Cache with revalidation strategy
- Respects backend ordering and hierarchy
- 4-7 top-level items on desktop (based on what backend returns)
- Accordion for mobile subcategories
- Consistent ordering across devices

❌ **WRONG:**
- Hardcoded category array in component (NEVER DO THIS)
- Static categories imported from file (NEVER DO THIS)
- No cache invalidation (stale categories)
- Too many top-level items (>10, overwhelming)
- Different category order on desktop vs mobile
- Categories don't update when backend changes

### User Account Indicator

**Two states based on authentication:**

**Logged out:**
- Desktop: "Sign In" or "Log In" text + user icon
- Mobile: User icon only
- Click navigates to login page
- Clear call-to-action

**Logged in:**
- Desktop: User name, initials, or email + dropdown
- Mobile: User name/initials or icon → account page
- Dropdown menu (desktop): My Account, Orders, Wishlist, Sign Out
- Fetch current user from backend authentication state

**Authentication state management:**
- Check auth state from backend (not just localStorage)
- Update immediately on login/logout events
- Handle session expiration gracefully
- Sync across tabs if possible

✅ **CORRECT:**
- Shows "Sign In" when logged out
- Shows user identifier when logged in
- Dropdown with account actions
- Checks backend auth state (not just client state)

❌ **WRONG:**
- No indication of login state
- Relies solely on localStorage (can be stale)
- No dropdown for account actions when logged in
- Missing logout option

### Mobile Navigation Pattern

**Hamburger drawer:**
- Trigger: Hamburger icon (top-left)
- Drawer: Slides from left, 80-85% width, full height, scrollable
- Backdrop: Semi-transparent overlay, click to close
- Content: All categories with accordion subcategories

**CRITICAL: Keep cart in header:**
- Cart icon stays in mobile header (top-right)
- Don't hide cart inside drawer
- Users expect cart always accessible
- Same for search icon if using icon-only search

**Account in drawer:**
- Logged out: "Sign In" link in drawer header or top of menu
- Logged in: User name/initials in drawer header with link to account

**Close behavior:**
- Close button (X) in drawer header
- Click backdrop overlay
- Navigate to category (drawer closes)
- Escape key

✅ **CORRECT:**
- Cart stays in mobile header (visible)
- Hamburger opens drawer from left
- Backdrop overlay dims background
- Close on navigation or backdrop click
- Scrollable drawer for long menus

❌ **WRONG:**
- Cart hidden inside hamburger drawer (cardinal sin)
- Full-screen drawer (no backdrop)
- Drawer doesn't close on navigation
- Not scrollable (categories cut off)

### Bottom Navigation (Alternative for Mobile)

**When to use:**
- Store has 3-5 key sections (Home, Browse, Cart, Account, Search)
- App-like experience desired
- Frequent switching between sections
- Not suitable for complex category hierarchies

**Pattern:**
- Fixed bar at bottom of screen (mobile only)
- Icon + label for each section
- Highlight active section
- 5 items maximum
- Direct navigation, no dropdowns

## Layout Structure

**Desktop:**
- Left: Logo → Homepage
- Center: Category links (horizontal)
- Right: Search, Account, Cart

**Mobile:**
- Left: Hamburger
- Center: Logo
- Right: Cart (+ Search icon optional)

**Sticky recommended:**
- Keeps cart/account accessible while scrolling
- Use `position: sticky` or `position: fixed`
- Solid background color (hide scrolling content)
- Adequate z-index to stay above content

## Accessibility Essentials

**Ecommerce-specific ARIA:**
- Cart count: `aria-live="polite"` to announce changes (e.g., "3 items in cart")
- Mobile drawer: `role="dialog"`, `aria-modal="true"`
- Hamburger button: `aria-label="Open navigation menu"`, `aria-expanded="false"`
- Active page: `aria-current="page"` on current category link
- Dropdown indicators: `aria-expanded`, `aria-controls` for megamenu relationships

**Keyboard navigation:**
- Tab through all links/buttons
- Enter/Space to activate
- Escape to close mobile menu or dropdowns
- Visible focus indicators (outline/ring)

**Generic accessibility applies:**
- Semantic HTML (`<header>`, `<nav>`)
- Icon buttons need ARIA labels
- 4.5:1 color contrast minimum
- 44x44px touch targets on mobile

## Common Ecommerce Mistakes

❌ **CRITICAL: Hardcoded static categories** - NEVER create static category arrays like `const categories = ["Women", "Men"]` or import from static files. ALWAYS fetch from backend API. Categories change constantly - new categories added, names changed, ordering updated. Hardcoded categories require developer intervention for simple changes and defeat the purpose of dynamic commerce platforms. This is the #1 most common mistake.

❌ **Hiding cart in mobile drawer** - Users expect cart always visible. Keep cart icon in header (top-right), not hidden inside hamburger menu.

❌ **No real-time cart updates** - Update count immediately when items added (optimistic UI). Don't require page refresh.

❌ **Showing price in cart badge** - Show item count (number), not total price. Price display confuses when variants have different quantities.

❌ **No cache invalidation** - Categories become stale when backend changes. Revalidate periodically (5-10 min) or on manual trigger.

❌ **Hover-only dropdowns on mobile** - Use click/tap interactions. Hover doesn't work on touch devices.

❌ **Desktop navigation on mobile** - Use hamburger drawer pattern, not horizontal menu that doesn't fit.

❌ **Inconsistent category order** - Same order on desktop and mobile for consistency. Respect backend's category ordering.

## Backend Integration

### Category Fetching (CRITICAL - NEVER Hardcode)

**Implementation patterns:**

**Client-side fetching:**
- Fetch categories in useEffect on mount
- Store in state (use appropriate types for Medusa: StoreProductCategory)
- Handle loading and error states
- Map categories to navigation links
- Use category.id as key, category.handle for URL, category.name for display

**With caching (RECOMMENDED):**
- Use TanStack Query with queryKey ['categories']
- Set staleTime: 5-10 minutes (categories rarely change)
- Automatic loading/error states
- Request deduplication if multiple components need categories

**Server-side fetching:**
- Fetch in server component or load function
- No loading state needed (rendered on server)
- Better for SEO

**Cart state synchronization pattern:**
- Subscribe to global cart state (Context)
- Update navbar cart count when cart changes
- Handle optimistic updates (show new count immediately on add to cart)
- Sync with backend on events or interval

**Authentication state pattern:**
- Check auth state from backend on mount
- Listen for login/logout events
- Update account indicator immediately
- Handle session expiration gracefully

**Category update triggers:**
- On page load/navigation
- On manual refresh trigger
- On revalidation interval (5-10 minutes)
- After admin updates categories (webhook or polling)

## Checklist

**Essential navbar features:**

- [ ] **CRITICAL: Categories fetched dynamically from backend API (NOT hardcoded arrays)**
- [ ] **CRITICAL: No static category imports or hardcoded category lists**
- [ ] Desktop: Horizontal category links
- [ ] Mobile: Hamburger drawer with accordion
- [ ] Cart icon visible on both desktop and mobile header (NOT hidden in drawer)
- [ ] Cart badge shows item count (not price)
- [ ] Cart count updates in real-time
- [ ] Categories use backend ordering (not manual ordering)
- [ ] Account indicator shows login state
- [ ] Logo links to homepage
- [ ] 4-7 top-level categories displayed (max 10)
- [ ] Mobile drawer closes on navigation
- [ ] Sticky navigation (recommended)
- [ ] 44x44px minimum touch targets
- [ ] ARIA labels on icon buttons
- [ ] `aria-live` on cart count for screen readers
- [ ] Keyboard accessible with visible focus states
- [ ] Categories cached with revalidation strategy (5-10 min)
- [ ] Error handling for failed category fetch