Lantern Hub Feature Documentation

Overview

The Lantern Hub is the central interface for managing a user's lantern status, viewing connection activity, and accessing social features. Accessible via the fire icon in the bottom navigation, it provides context-aware actions based on whether the user has an active lantern.

Visual Design

Fire Icon States

The fire icon in the bottom navigation bar has two distinct states:

1. Extinguished (No Active Lantern)

   • Gray/white outline appearance
   • Subtle presence in navigation
   • Indicates user is not currently visible for connections

2. Lit (Active Lantern)

   • Glowing amber/orange color
   • Pulsing animation (2s cycle)
   • Shadow glow effect
   • Indicates user has an active lantern and is visible

Interaction Pattern

Tap the fire icon → Opens Lantern Hub panel (bottom sheet modal)

The hub content changes dynamically based on lantern status, showing relevant actions and information.

---

Lantern Hub Views

View 1: No Active Lantern

When the user does not have a lantern lit, the hub displays:

Primary Actions

1. 🔥 Light Lantern (Primary CTA)

   • Gradient amber/orange button with glow effect
   • Opens venue selection or lights lantern at current location
   • Must be venue-specific for safety and merchant partnership model

2. 📅 Schedule a Light

   • Plan ahead for events or activities (yoga class, happy hour, etc.)
   • Sets up future lantern activation at specific venue/time
   • Future feature - currently shows placeholder

3. 📊 Recent Activity

   • View past connections, waves received, venues visited
   • Access connection history
   • Future feature - currently shows placeholder

Additional Sections

• Upcoming Scheduled Lights (if any exist)

  • Shows list of planned lantern activations
  • Displays venue name, scheduled time, countdown

• Nearby Venues Preview

  • Shows up to 3 nearby venues with active lanterns
  • Quick preview of where people are currently connecting
  • Each venue shows lantern count and distance

---

View 2: Active Lantern

When the user has a lantern lit, the hub displays:

Current Status Card

• Venue name with location icon
• Time remaining (e.g., "1h 45m")
• Interest/message that was set
• Mood indicator
• Amber gradient background with glow effect
• "Active" badge with sparkle icon

Activity Cards

1. 👋 Waves Received (if any pending)

   • Shows count of people who waved
   • Badge indicator for new waves
   • Tap to view wave details and respond

2. 💬 Active Chats (if any ongoing)

   • Shows count of active conversations
   • Badge indicator
   • Tap to jump to chats

3. 📅 Upcoming Lights (if any scheduled)

   • Preview of future scheduled lantern activations
   • Can manage/edit scheduled lights

Actions

• Extinguish Lantern button (subtle, secondary style)
  • Turns off active lantern
  • Returns to "No Active Lantern" state
  • Removes user from venue's active lantern list

---

Technical Implementation

Component Structure

src/components/LanternHub.jsx         # Main component
src/components/LanternHub.stories.jsx # Storybook stories

Integration Points

Dashboard Integration (src/dashboard/Dashboard.jsx):

1. State management:

   const [showLanternHub, setShowLanternHub] = useState(false)
   const [upcomingLights, setUpcomingLights] = useState([])

2. Navigation fire icon:

   • Connected to handleOpenLanternHub
   • Visual state reflects !!myLantern
   • Pulsing glow when lit

3. Props passed to LanternHub:

   • myLantern: Current active lantern data
   • waves: Array of incoming waves
   • activeChats: Array of active connections
   • upcomingLights: Array of scheduled lights
   • nearbyVenues: Nearby venues with active lanterns

Component Props

interface LanternHubProps {
  isOpen: boolean
  onClose: () => void
  myLantern?: {
    interest: string
    mood: string
    venueName: string
    timeRemaining: string
  }
  onLightLantern: () => void
  onScheduleLight: () => void
  onViewActivity: () => void
  onExtinguish: () => void
  waves?: Wave[]
  activeChats?: Connection[]
  upcomingLights?: ScheduledLight[]
  nearbyVenues?: Venue[]
}

Animations

• slideUp: Panel slides up from bottom (0.3s cubic-bezier)
• fadeIn: Backdrop fades in (0.2s ease-out)
• pulseGlow: Fire icon glow pulse when lit (2s infinite)

Styling

• Bottom sheet modal design
• Dark theme (zinc-900 background)
• Backdrop blur overlay
• Responsive max-width (md: 448px)
• Max height 70vh with scroll

---

User Flows

Flow 1: Lighting a Lantern

1. User taps extinguished fire icon
2. Lantern Hub opens showing "No Active Lantern" view
3. User taps "Light Lantern"
4. Hub closes, user can select venue (existing venue selection flow)
5. After lighting lantern, fire icon becomes lit with glow

Flow 2: Viewing Waves While Active

1. User has active lantern (fire icon is lit and glowing)
2. User receives wave (backend notification)
3. Fire icon could show badge indicator (future enhancement)
4. User taps lit fire icon
5. Lantern Hub opens showing "Active Lantern" view
6. "Waves Received" card shows count badge
7. User taps card to view and respond to waves

Flow 3: Scheduling Future Light

1. User taps extinguished fire icon
2. User taps "Schedule a Light"
3. (Future) Schedule form opens with venue and time selection
4. User schedules lantern for "Yoga Studio - Tomorrow 6 PM"
5. Scheduled light appears in "Upcoming" section
6. At scheduled time, lantern auto-lights (or prompts user)

Flow 4: Extinguishing Active Lantern

1. User has active lantern (fire icon lit)
2. User taps lit fire icon
3. Lantern Hub shows current status
4. User taps "Extinguish Lantern"
5. Lantern is removed from venue
6. Fire icon returns to extinguished state
7. Hub closes

---

Safety & Privacy

Venue-Specific Requirement

Lanterns must be tied to specific venues for:

• User safety: Physical accountability at known locations
• Merchant partnerships: Drives foot traffic to partner businesses
• Community trust: Venues can partner for on-site safety support

Auto-Extinguish Conditions

Lanterns should automatically extinguish when:

• User leaves venue vicinity (geofence)
• Time limit reached (2 hours default)
• User manually extinguishes
• User successfully meets connection partner

---

Future Enhancements

Near-Term (Phase 1)

• [ ] Schedule light form/modal UI
• [ ] Recent activity view with connection history
• [ ] Badge notifications on fire icon for new waves
• [ ] Time remaining calculation (countdown from activation)
• [ ] Geofence monitoring for auto-extinguish

Mid-Term (Phase 2)

• [ ] Edit/manage scheduled lights
• [ ] Recurring scheduled lights (e.g., "Every Tuesday yoga")
• [ ] Quick venue switcher without extinguishing
• [ ] Mood change while lantern is active
• [ ] Activity intensity visualization (more waves = brighter glow)

Long-Term (Phase 3)

• [ ] Friend suggestions based on scheduled lights
• [ ] Group lantern lighting for events
• [ ] Merchant-sponsored scheduled lights
• [ ] Integration with calendar apps
• [ ] Push notifications for scheduled lights reminder

---

Testing

Storybook Stories

Run Storybook to view all component states:

npm run storybook

Available stories:

• No Active Lantern: Default empty state
• No Active Lantern With Upcoming: Shows scheduled lights
• Active Lantern Basic: Minimal active state
• Active Lantern With Waves: Shows pending waves
• Active Lantern With Chats: Shows active conversations
• Active Lantern Full Activity: All features active
• Closed: Hub in closed state
• Playground: Interactive controls for all props

Manual Testing Checklist

• [ ] Fire icon visual state (extinguished vs lit)
• [ ] Fire icon glow animation when lit
• [ ] Hub opens/closes smoothly
• [ ] Backdrop dismisses hub on click
• [ ] Close button works
• [ ] All action buttons log correctly
• [ ] Nearby venues display when available
• [ ] Waves count badge displays correctly
• [ ] Chats count badge displays correctly
• [ ] Scheduled lights display in both views
• [ ] Extinguish button removes lantern
• [ ] Mobile responsive (max-width 448px)
• [ ] Scrolling works when content exceeds 70vh

Integration Testing

Test with Dashboard:

1. Light a lantern → Fire icon should glow
2. Extinguish lantern → Fire icon should dim
3. Simulate incoming wave → Hub should show wave count
4. Accept wave → Hub should show active chat count

---

API Integration (Future)

Endpoints Needed

POST   /api/lanterns              # Light a lantern
DELETE /api/lanterns/:id          # Extinguish lantern
POST   /api/lanterns/schedule     # Schedule a light
GET    /api/lanterns/scheduled    # Get upcoming lights
PUT    /api/lanterns/scheduled/:id # Update scheduled light
DELETE /api/lanterns/scheduled/:id # Cancel scheduled light
GET    /api/activity/history      # Get user connection history

Real-time Updates

• WebSocket connection for wave notifications
• Geofence monitoring service for location-based auto-extinguish
• Time-based background tasks for scheduled lights
• Push notifications for scheduled light reminders

---

Accessibility

• Semantic HTML structure
• ARIA labels for icon buttons
• Keyboard navigation support (Tab, Enter, Esc)
• Screen reader announcements for state changes
• Sufficient color contrast (WCAG AA)
• Focus management when opening/closing

---

Related Documentation

• Wave-to-Meet Feature
• Dashboard Component
• API Documentation
• Security Guidelines
• TODO List