Lantern

Appearance

Global Lantern Lighting & Scheduling — Implementation Summary ​

Implementation Date: January 3, 2026
Feature Status: ✅ Complete

Overview ​

Expanded the Lantern Hub with full multi-step flows for lighting lanterns globally (not just from venue detail view) and scheduling future lights. Refactored existing form components to be reusable and composable.

What Was Built ​

New Components ​

  1. VenuePicker - Venue selection interface

    • List and map view modes
    • Search and category filtering
    • Shows active lantern counts
    • Reusable for both immediate and scheduled lighting

  2. LightLanternForm - Interest & mood form

    • Extracted from Dashboard (was embedded)
    • Reusable for immediate or scheduled lighting
    • Optional venue information display
    • Character counter (140 chars)
    • Three mood options: Conversation, Quiet Company, Activity/Game

  3. ScheduleLightForm - Schedule future light

    • Multi-step wizard (Venue → Date/Time → Interest/Mood)
    • Step progress indicators
    • Date/time validation (up to 30 days ahead)
    • Preview of scheduled time
    • Connects to VenuePicker and LightLanternForm

Updated Components ​

  1. LanternHub

    • Now triggers full flows for "Light Lantern" and "Schedule a Light"
    • Added handlers for waves and chats (future navigation)
    • Updated props to support new interactions

  2. Dashboard

    • Removed embedded LightLanternForm (now imported)
    • Added state management for multi-step flows
    • Integrated all new components
    • Maintains existing venue detail → light flow
    • Added global flows via Lantern Hub

Storybook Stories ​

User Flows ​

Flow 1: Global Light Lantern (from Lantern Hub) ​

Tap Fire Icon → Lantern Hub Opens
     ↓
Tap "Light Lantern"
     ↓
Venue Picker → Select Venue
     ↓
Light Lantern Form → Set Interest & Mood
     ↓
Confirm → Lantern Lit ✨

Steps:

  1. User taps extinguished fire icon
  2. Lantern Hub opens (no active lantern view)
  3. User taps "Light Lantern" primary CTA
  4. VenuePicker opens showing all nearby venues
    • Can search, filter by category, switch list/map view
  5. User selects a venue
  6. LightLanternForm opens with venue info
    • User selects mood
    • User writes interest message (max 140 chars)
  7. User taps "Activate Lantern"
  8. Lantern is lit, fire icon glows
  9. User moved to ActiveLanternView

Flow 2: Schedule a Light (Future) ​

Tap Fire Icon → Lantern Hub Opens
     ↓
Tap "Schedule a Light"
     ↓
Schedule Form Step 1 → Select Venue
     ↓
Schedule Form Step 2 → Pick Date & Time
     ↓
Light Lantern Form → Set Interest & Mood
     ↓
Confirm → Scheduled Light Saved 📅

Steps:

  1. User taps fire icon
  2. Lantern Hub opens
  3. User taps "Schedule a Light"
  4. ScheduleLightForm opens (Step 1: Venue)
    • User taps "Select Venue"
    • VenuePicker opens
    • User selects venue
    • Returns to Schedule Form
  5. Step 2: Date & Time
    • User picks date (up to 30 days ahead)
    • User picks time
    • Preview shows formatted date/time
  6. User taps "Continue to Set Interest"
  7. LightLanternForm opens
    • User sets interest and mood
  8. User taps "Activate Lantern"
  9. Scheduled light saved to upcomingLights
  10. Shows in Lantern Hub "Upcoming" section
  11. TODO: Backend saves, push notification at scheduled time

Flow 3: Existing Venue Detail → Light (Unchanged) ​

Browse Venues → Tap Venue
     ↓
Venue Detail View
     ↓
Tap "Light My Lantern"
     ↓
Light Lantern Form → Set Interest & Mood
     ↓
Confirm → Lantern Lit ✨

This flow still works as before, now using the extracted LightLanternForm component.

Component Architecture ​

Component Hierarchy ​

Dashboard
├── LanternHub (modal)
│   └── Triggers flows →
│       ├── VenuePicker
│       ├── LightLanternForm
│       └── ScheduleLightForm
│           ├── VenuePicker (nested)
│           └── LightLanternForm (nested)
├── VenuePicker (full-screen)
├── LightLanternForm (full-screen)
├── ScheduleLightForm (full-screen)
└── ... existing components

State Management in Dashboard ​

javascript
// Form flow states
const [showVenuePicker, setShowVenuePicker] = useState(false)
const [showLightForm, setShowLightForm] = useState(false)
const [showScheduleForm, setShowScheduleForm] = useState(false)
const [venueForLight, setVenueForLight] = useState(null)
const [scheduleData, setScheduleData] = useState(null)

// Upcoming scheduled lights
const [upcomingLights, setUpcomingLights] = useState([])

Component Props ​

VenuePicker:

typescript
{
  venues: Venue[]
  onSelectVenue: (venue: Venue) => void
  onCancel: () => void
  title?: string
  description?: string
}

LightLanternForm:

typescript
{
  venue?: Venue | null
  onCancel: () => void
  onConfirm: (data: { interest, mood, moodId }) => void
  showVenueInfo?: boolean
  initialInterest?: string
  initialMood?: string
}

ScheduleLightForm:

typescript
{
  onCancel: () => void
  onConfirm: (data: { date, time }) => void
  onSelectVenue: () => void
  selectedVenue?: Venue | null
}

Key Features ​

✅ VenuePicker ​

  • Dual view modes: List and map (radar style)
  • Search: Real-time filtering by venue name/type
  • Category filters: All, Cafe, Bar, Food, Activities
  • Visual indicators: Shows active lantern counts
  • Map visualization: Radar-style with venue dots
  • Responsive: Full-screen mobile optimized

✅ LightLanternForm ​

  • Reusable: Works for immediate or scheduled lighting
  • Optional venue info: Can hide venue details
  • Three moods: Conversation, Quiet Company, Activity/Game
  • Character limit: 140 characters with counter
  • Auto-focus: Interest textarea focused on open
  • Validation: Disables submit until interest is entered

✅ ScheduleLightForm ​

  • Multi-step wizard: Clear progress indicators
  • Venue selection: Integrates with VenuePicker
  • Date validation: Min = today, Max = 30 days
  • Time picker: HTML5 time input
  • Preview: Shows formatted scheduled time
  • Flexible: Can change venue during flow

✅ Integration ​

  • Seamless transitions: Components open/close smoothly
  • Preserved state: Venue selection carries through flow
  • Context-aware: Forms know if immediate or scheduled
  • Backend-ready: TODOs marked for API integration

Future Enhancements ​

Near-Term ​

  • [ ] Backend API integration for scheduled lights
  • [ ] Push notifications at scheduled time
  • [ ] Edit/delete scheduled lights
  • [ ] Auto-light lantern at scheduled time (with confirmation)
  • [x] Geofence check before lighting ✅ Implemented 2026-01-18 (Issue #28)

Mid-Term ​

  • [ ] Recurring scheduled lights ("Every Tuesday at 6 PM")
  • [ ] Scheduled light reminders (30 min before)
  • [ ] Friend suggestions for scheduled lights
  • [ ] Venue event integration (auto-fill from venue events)

Long-Term ​

  • [ ] Group scheduled lights (meetup planning)
  • [ ] Calendar app integration (export to Google/Apple Calendar)
  • [ ] Merchant-sponsored scheduled events
  • [ ] AI suggestions for schedule times based on activity

Testing ​

Manual Testing Checklist ​

VenuePicker:

  • [ ] List view displays all venues
  • [ ] Map view shows venue dots correctly
  • [ ] Search filters venues in real-time
  • [ ] Category filters work (All, Cafe, Bar, Food, Activities)
  • [ ] Selecting venue triggers callback
  • [ ] Cancel closes picker
  • [ ] View mode toggle works

LightLanternForm:

  • [ ] Venue info displays correctly
  • [ ] Mood selection works (visual feedback)
  • [ ] Interest textarea accepts input
  • [ ] Character counter updates
  • [ ] Submit disabled when interest empty
  • [ ] Form submits with correct data structure
  • [ ] Cancel triggers callback

ScheduleLightForm:

  • [ ] Step 1: Venue selection works
  • [ ] Can change venue after selection
  • [ ] Step 2: Date/time inputs work
  • [ ] Date validation (min/max)
  • [ ] Preview shows formatted time
  • [ ] Progress indicators update correctly
  • [ ] Continue button enables when valid

Integration:

  • [ ] Hub → Light Lantern → Venue Picker → Form → Confirm
  • [ ] Hub → Schedule → Venue → Date/Time → Form → Save
  • [ ] Scheduled lights show in "Upcoming" section
  • [ ] Existing venue detail flow still works
  • [ ] Fire icon glows when lantern lit
  • [ ] All cancel buttons properly close flows

Storybook Testing ​

bash
npm run storybook

Navigate to:

  • Components → VenuePicker (4 stories)
  • Components → LightLanternForm (4 stories)
  • Components → ScheduleLightForm (3 stories)

Code Organization & Refactoring ​

Before vs. After ​

Before:

  • LightLanternForm embedded in Dashboard.jsx
  • No global light lantern flow
  • No schedule light functionality
  • Lantern Hub just placeholders

After:

  • LightLanternForm extracted to /components
  • VenuePicker new reusable component
  • ScheduleLightForm new multi-step wizard
  • Lantern Hub triggers complete flows
  • Dashboard orchestrates all flows

Benefits of Refactoring ​

  1. Reusability: Components used in multiple contexts
  2. Testability: Individual components in Storybook
  3. Maintainability: Single source of truth for each form
  4. Scalability: Easy to add new flows (e.g., edit scheduled light)
  5. Separation of Concerns: Dashboard orchestrates, components render

API Integration (Future) ​

Endpoints Needed ​

POST   /api/lanterns/schedule     # Schedule a lantern
GET    /api/lanterns/scheduled    # Get user's scheduled lights
PUT    /api/lanterns/scheduled/:id # Edit scheduled light
DELETE /api/lanterns/scheduled/:id # Cancel scheduled light
POST   /api/lanterns/schedule/:id/activate  # Manually activate early

Data Structure for Scheduled Light ​

javascript
{
  id: string,
  userId: string,
  venueId: string,
  venueName: string,
  scheduledDateTime: ISO8601,
  interest: string,
  mood: string,
  moodId: string,
  status: 'pending' | 'active' | 'cancelled' | 'completed',
  createdAt: ISO8601,
  notificationSent: boolean
}

Backend Tasks ​

  • Scheduled task processor (check for lights due to activate)
  • Push notification service (remind user 30min before)
  • Geofence validation (ensure user is near venue)
  • Auto-activate or prompt user at scheduled time

Files Changed ​

New Files Created (7) ​

  • src/components/VenuePicker.jsx
  • src/components/VenuePicker.stories.jsx
  • src/components/LightLanternForm.jsx
  • src/components/LightLanternForm.stories.jsx
  • src/components/ScheduleLightForm.jsx
  • src/components/ScheduleLightForm.stories.jsx
  • docs/features/GLOBAL_LANTERN_FLOWS.md (this file)

Modified Files (2) ​

  • src/components/LanternHub.jsx - Added navigation handlers
  • src/dashboard/Dashboard.jsx - Integrated new components, refactored flows

Conclusion ​

The Lantern Hub now provides complete, production-ready flows for:

  • ✅ Global lantern lighting (not tied to specific venue detail view)
  • ✅ Scheduling future lights
  • ✅ Reusable components for all lighting scenarios

Users can now access all lantern features from the fire icon, making the app more intuitive and the navigation cleaner. The multi-step flows guide users smoothly through venue selection, interest/mood setup, and confirmation.

Next steps include backend integration, push notifications, and advanced features like recurring schedules and friend suggestions.

Built with VitePress

Copyright © 2026 Lantern