Lantern

Appearance

Lantern Hub — Implementation Summary ​

Implementation Date: January 3, 2026 Feature Status: ✅ Complete (MVP with future enhancements planned)

What Was Built ​

A complete Lantern Hub interface accessible via the fire icon in the bottom navigation. The hub provides centralized access to lantern management, connection activity, and social features.

Files Created ​

Core Component ​

Documentation ​

Modified Files ​

  • src/dashboard/Dashboard.jsx
    • Added LanternHub component import and integration
    • Updated Navigation component with fire icon click handler
    • Added fire icon visual state (lit/unlit with pulsing glow)
    • Added state management for hub visibility and upcoming lights
    • Added handler functions for all hub actions
    • Added pulseGlow animation for lit state

How It Works ​

Fire Icon Visual States ​

┌─────────────────┐         ┌──────────────────┐
│  Extinguished   │         │       Lit        │
│  (Gray/White)   │  ────>  │  (Amber Glow)    │
│  No Activity    │  Light  │  Pulsing Anim    │
└─────────────────┘         └──────────────────┘

User Flow ​

Tap Fire Icon
      │
      ├──> No Active Lantern
      │    ├── Light Lantern (Primary CTA)
      │    ├── Schedule a Light
      │    ├── Recent Activity
      │    └── Nearby Venues Preview
      │
      └──> Active Lantern
           ├── Current Status Card
           ├── Waves Received (badge)
           ├── Active Chats (badge)
           ├── Upcoming Lights
           └── Extinguish Button

The fire icon is the center button in the bottom navigation:

LeftCenterRight
Places (MapPin)Fire IconMe (Users)

Fire icon behavior:

  • No lantern: Gray outline, opens hub to light lantern
  • Active lantern: Glowing amber with pulse, opens hub to view status

Key Features Implemented ​

✅ Dual State Design ​

  • Unlit state: Shows actions to light lantern, schedule, or view activity
  • Lit state: Shows current lantern status, waves, chats, and extinguish option

✅ Visual Feedback ​

  • Fire icon changes appearance based on lantern status
  • Pulsing glow animation when lantern is active
  • Smooth slide-up panel animation
  • Backdrop blur overlay

✅ Context-Aware Actions ​

  • Different action cards based on lantern state
  • Badge indicators for new waves and active chats
  • Nearby venues preview when unlit
  • Current status card when lit

✅ Interaction Handlers ​

  • All action buttons connected to Dashboard state
  • Proper open/close flow
  • Backdrop dismissal
  • Close button

✅ Responsive Design ​

  • Mobile-optimized bottom sheet
  • Max-width container (448px)
  • Scrollable content area (max 70vh)
  • Touch-friendly button sizes

✅ Storybook Integration ​

  • 8 comprehensive stories covering all states
  • Interactive playground with all props
  • Visual documentation of component behavior

Future Enhancements (TODO) ​

Phase 1 (Near-Term) ​

  • [ ] Schedule light form/modal UI
  • [ ] Recent activity view with history
  • [ ] Badge notifications on fire icon for new waves
  • [ ] Real time remaining calculation
  • [ ] Geofence auto-extinguish

Phase 2 (Mid-Term) ​

  • [ ] Edit/manage scheduled lights
  • [ ] Recurring scheduled lights
  • [ ] Quick venue switcher
  • [ ] Mood change while active
  • [ ] Activity intensity glow

Phase 3 (Long-Term) ​

  • [ ] Friend suggestions based on schedules
  • [ ] Group lantern lighting
  • [ ] Merchant-sponsored events
  • [ ] Calendar app integration
  • [ ] Push notifications for scheduled lights

See docs/TODO.md for complete task list.

Testing ​

Manual Testing Steps ​

  1. Fire Icon State

    • [ ] Default state is gray (extinguished)
    • [ ] Lights when lantern is active
    • [ ] Pulsing animation plays smoothly
    • [ ] Click opens Lantern Hub

  2. Hub - No Active Lantern

    • [ ] Opens with correct actions
    • [ ] "Light Lantern" is prominent (gradient)
    • [ ] Schedule and Activity buttons present
    • [ ] Nearby venues show (if data available)
    • [ ] Backdrop closes hub
    • [ ] Close button works

  3. Hub - Active Lantern

    • [ ] Status card shows venue, time, interest, mood
    • [ ] Waves card appears if waves exist
    • [ ] Chats card appears if chats exist
    • [ ] Badge counts are correct
    • [ ] Extinguish button removes lantern
    • [ ] Fire icon updates after extinguish

  4. Animations

    • [ ] Panel slides up smoothly
    • [ ] Backdrop fades in
    • [ ] No jank or stuttering
    • [ ] Closing is smooth

Storybook Testing ​

bash
npm run storybook

Navigate to Components → LanternHub and test all stories:

  • No Active Lantern
  • No Active Lantern With Upcoming
  • Active Lantern Basic
  • Active Lantern With Waves
  • Active Lantern With Chats
  • Active Lantern Full Activity
  • Closed
  • Playground (interactive controls)

Integration with Existing Features ​

Wave-to-Meet ​

  • Hub shows wave count when waves are received
  • Badge indicator for new pending waves
  • Quick navigation to wave management (future)

Chat ​

  • Hub shows active chat count
  • Quick navigation to chats (future)

Venue Selection ​

  • "Light Lantern" action connects to existing venue flow
  • Nearby venues preview uses existing venue data

Dashboard State ​

  • Uses myLantern state from Dashboard
  • Shares wave and connection state
  • Integrates with existing extinguish logic

API Endpoints (Future Backend Integration) ​

When connecting to backend, implement:

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

See docs/engineering/API.md for full API documentation.

Design Decisions ​

Why a Hub Instead of Direct Actions? ​

Scalability: The hub pattern allows for future expansion without cluttering the navigation. We can add new features (scheduled lights, activity history, friend suggestions) without changing the bottom nav.

Context: Users need to see their current state before taking actions. The hub provides this overview.

Safety: Keeps venue-specific requirement front-and-center by showing venue selection as part of the flow.

Why Lit/Unlit Visual States? ​

Clarity: Users instantly know if they're visible or not.

Privacy: Clear visual feedback about social visibility state.

Engagement: The glowing, pulsing fire is inviting and draws attention to activity.

Why Bottom Sheet Instead of Full Screen? ​

Mobile-First: Bottom sheets are easier to reach on phones.

Context Preservation: User can still see map/venue context behind the sheet.

Quick Actions: Designed for fast in-and-out interactions.

Accessibility ​

  • Semantic HTML structure
  • Keyboard navigation support
  • Screen reader compatible
  • Sufficient color contrast
  • Focus management
  • ARIA labels on icon buttons

Conclusion ​

The Lantern Hub provides a scalable, user-friendly interface for managing lantern status and connection activity. The fire icon serves as both a status indicator and action button, with context-aware content that adapts to user state.

Future enhancements will add scheduled lights, activity history, and deeper integration with merchant partnerships and community features.

Built with VitePress

Copyright © 2026 Lantern