Meal Planning Calendar

[wtfzdotnet]

User Story: Meal Planning Calendar

Epic: Recipe Management & Meal Planning

Story ID: RECIPEER-003
Priority: High
Story Points: 13
Sprint: 2025.2

---

User Story

As a home cook who wants to plan meals in advance
I want an interactive calendar to schedule and organize my meals
So that I can efficiently plan my weekly/monthly meals, reduce food waste, and streamline grocery shopping

---

Acceptance Criteria

Primary Features

1. Calendar Display & Navigation

• Given I access the meal planning feature
• When I view the calendar
• Then I should see:
  • Monthly view with clear date cells
  • Navigation controls (previous/next month, today button)
  • Current date highlighted
  • Weekend dates visually distinguished
  • Clean, European-inspired design following project design tokens

2. Meal Scheduling

• Given I want to plan a meal
• When I click on a date cell
• Then I should be able to:
  • Add meals for breakfast, lunch, dinner, and snacks
  • Search and select from my saved recipes
  • Add quick meal notes without full recipes
  • Set serving sizes and portions
  • Mark meals as "planned", "prepared", or "completed"

3. Recipe Integration

• Given I have saved recipes in my collection
• When I schedule a meal
• Then I should be able to:
  • Browse my recipe collection in a modal/dropdown
  • Search recipes by name, category, or cuisine type
  • See recipe thumbnails, ratings, and cook time
  • Auto-populate meal details from selected recipe
  • Link to full recipe view for details

4. Meal Management

• Given I have scheduled meals
• When I interact with planned meals
• Then I should be able to:
  • Edit meal details (time, servings, notes)
  • Move meals to different dates (drag & drop)
  • Duplicate meals to other dates
  • Delete/remove planned meals
  • Mark meals as completed with checkboxes

5. Visual Indicators

• Given I have a populated meal calendar
• When I view the calendar
• Then I should see:
  • Color-coded meal types (breakfast=yellow, lunch=blue, dinner=red, snack=green)
  • Meal count indicators on each date
  • Visual distinction for past vs. future dates
  • Progress indicators for completed meals
  • Overflow handling for dates with many meals

6. Responsive Design

• Given I access the calendar on different devices
• When I view the interface
• Then it should:
  • Adapt to mobile, tablet, and desktop screens
  • Provide touch-friendly interactions on mobile
  • Maintain usability across all breakpoints
  • Follow atomic design principles with proper component composition

---

Technical Implementation

Component Architecture (Atomic Design)

Organism: MealPlanningCalendar

Location: src/components/organisms/meal-planning-calendar/

Dependencies:

• shadcn/ui Calendar: Base calendar component
• Molecules:
  • MealScheduler - Meal planning interface
  • RecipeSelector - Recipe selection modal
  • MealCard - Individual meal display
• Atoms:
  • Button, Badge, Input, Select
  • Calendar (from shadcn/ui)

Props Interface

interface MealPlanningCalendarProps {
  /** Current selected date */
  selectedDate?: Date;
  
  /** Planned meals data */
  meals: MealPlan[];
  
  /** Available recipes for selection */
  recipes: Recipe[];
  
  /** Calendar display mode */
  view?: 'month' | 'week';
  
  /** Enable drag and drop functionality */
  enableDragDrop?: boolean;
  
  /** Meal types to display */
  mealTypes?: MealType[];
  
  /** Callbacks */
  onDateSelect?: (date: Date) => void;
  onMealAdd?: (meal: MealPlan) => void;
  onMealEdit?: (mealId: string, updates: Partial<MealPlan>) => void;
  onMealDelete?: (mealId: string) => void;
  onMealComplete?: (mealId: string, completed: boolean) => void;
  
  /** Styling */
  className?: string;
  disabled?: boolean;
}

interface MealPlan {
  id: string;
  date: Date;
  mealType: MealType;
  recipeId?: string;
  recipeName: string;
  servings: number;
  notes?: string;
  status: 'planned' | 'prepared' | 'completed';
  estimatedTime?: number;
}

type MealType = 'breakfast' | 'lunch' | 'dinner' | 'snack';

State Management Options

Option A: React State + Context (Recommended)

// Create MealPlanningContext for app-wide meal state
const MealPlanningContext = createContext<{
  meals: MealPlan[];
  addMeal: (meal: MealPlan) => void;
  updateMeal: (id: string, updates: Partial<MealPlan>) => void;
  deleteMeal: (id: string) => void;
  getMealsForDate: (date: Date) => MealPlan[];
}>();

Option B: Redux Toolkit (For Complex Apps)

// Slice for meal planning state
const mealPlanningSlice = createSlice({
  name: 'mealPlanning',
  initialState: {
    meals: [],
    selectedDate: new Date(),
    isLoading: false,
  },
  reducers: {
    addMeal: (state, action) => { /* ... */ },
    updateMeal: (state, action) => { /* ... */ },
    deleteMeal: (state, action) => { /* ... */ },
    setSelectedDate: (state, action) => { /* ... */ },
  },
});

---

User Interface Design

Layout Structure

┌─────────────────────────────────────────┐
│ Meal Planning Calendar                   │
├─────────────────────────────────────────┤
│ [← Prev]  [March 2025]  [Next →]       │
│                              [Today]    │
├─────────────────────────────────────────┤
│ Su Mo Tu We Th Fr Sa                    │
│                    1  2                 │
│  3  4  5  6  7  8  9                    │
│ 10 11 12 13 14 15 16                    │
│ 17 18 19 20 21 22 23                    │
│ 24 25 26 27 28 29 30                    │
│ 31                                      │
├─────────────────────────────────────────┤
│ Selected: March 15, 2025                │
│ ┌─────────────────────────────────────┐ │
│ │ Breakfast: Avocado Toast         ✓ │ │
│ │ Lunch: Mediterranean Bowl          │ │
│ │ Dinner: [+ Add Meal]               │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

Meal Planning Modal

┌─────────────────────────────────────────┐
│ Plan Meal - March 15, 2025              │
├─────────────────────────────────────────┤
│ Meal Type: [Dinner ▼]                   │
│ Recipe: [Search recipes...]             │
│ ┌─────────────────────────────────────┐ │
│ │ 🍝 Creamy Garlic Pasta    4.8⭐    │ │
│ │ 🥗 Caesar Salad          4.5⭐    │ │
│ │ 🍖 Grilled Chicken       4.7⭐    │ │
│ └─────────────────────────────────────┘ │
│ Servings: [4 ▼]                        │
│ Notes: [Optional notes...]              │
│                                         │
│ [Cancel]              [Save Meal]       │
└─────────────────────────────────────────┘

---

Implementation Tasks

Phase 1: Core Calendar (5 points)

• Install and configure shadcn/ui Calendar component
• Create base MealPlanningCalendar organism component
• Implement date selection and navigation
• Add responsive design and European styling
• Create Storybook stories for calendar states

Phase 2: Meal Scheduling (5 points)

• Create MealScheduler molecule component
• Implement meal addition modal/interface
• Add meal type selection (breakfast/lunch/dinner/snack)
• Create meal display within calendar cells
• Add meal editing and deletion functionality

Phase 3: Recipe Integration (3 points)

• Create RecipeSelector molecule component
• Integrate with existing recipe collection
• Add recipe search and filtering
• Implement recipe-to-meal data mapping
• Add recipe thumbnail display

Phase 4: Advanced Features (Optional)

• Drag and drop meal rescheduling
• Meal completion tracking
• Weekly view option
• Grocery list generation from planned meals
• Meal plan templates and quick scheduling