# Weather Feature Guide

## Overview

The weather feature has been fully implemented on the `/map` page, providing real-time weather data, air quality information, and skateability scoring for all skate spots.

## How to Use

### 1. View Weather on Map

#### Enable Weather Layer

1. Navigate to `/map` page
2. Look for the "Weather Off" button in the toolbar (next to Map/List toggle)
3. Click the button to enable weather - it will change to "Weather On" and turn blue
4. Wait a few seconds for weather data to load

#### View Weather-Colored Markers

Once enabled, you'll see:
- **Color-coded markers**: Spot markers change color based on skating conditions
  - 🟢 Green = Perfect conditions (85-100 score)
  - 🟡 Yellow = Good conditions (70-84 score)
  - 🟠 Orange = Okay conditions (50-69 score)
  - 🔴 Red = Poor/bad conditions (0-49 score)
- **Weather icons**: Small weather emoji appears on each marker (☀️, ⛅, 🌧️, etc.)

### 2. View Weather on Spot Detail Pages

Weather information is **automatically displayed** on every spot detail page (`/spot/:pubkey/:identifier`):

1. Click any spot on the map or navigate to a spot detail page
2. Look for the **Weather Conditions** card in the sidebar (blue gradient design)
3. View comprehensive weather information including:
   - Current temperature and conditions
   - Skateability score with color-coded indicator
   - Wind speed and direction
   - Humidity percentage
   - UV index (sun protection guidance)
   - Air quality index (if available)
   - 3-day forecast with daily temps and precipitation
   - Feels-like temperature

**No toggle required** - weather data loads automatically on all spot pages!

### 3. View Detailed Weather in Map Popups

Click any spot marker on the map to see a popup with:
- Current temperature (°F) and feels-like
- Weather conditions and icon
- Skateability score and label
- Wind speed and direction
- Humidity percentage
- Air quality index (if available)
- 3-day forecast with high/low temps
- Precipitation probability

### 4. Filter by Weather

When weather is enabled, three additional filter buttons appear:
- **All Weather** (blue): Show all spots regardless of weather
- **Good Weather (70+)** (yellow): Show only spots with good or better conditions
- **Perfect Weather (85+)** (green): Show only spots with perfect skating weather

## Where Weather Appears

Weather information is displayed in **three places**:

1. **Map View** (`/map` with weather toggle enabled):
   - Color-coded spot markers
   - Weather icons on markers
   - Quick weather info in popups

2. **Spot Detail Pages** (`/spot/:pubkey/:identifier`):
   - Full weather card in sidebar
   - Comprehensive weather details
   - 3-day forecast
   - Always visible (no toggle needed)

3. **Map Popups** (when weather enabled):
   - Current conditions summary
   - Temperature and feels-like
   - Skateability score
   - 3-day forecast preview

## Features

### Weather Data Includes
- ✅ Temperature (°F and °C)
- ✅ Feels-like temperature
- ✅ Weather conditions (sunny, cloudy, rainy, etc.)
- ✅ Precipitation and probability
- ✅ Wind speed and direction
- ✅ Humidity
- ✅ UV index
- ✅ Air quality (AQI, PM2.5, PM10)
- ✅ 3-day forecast

### Skateability Scoring

The app calculates a 0-100 score based on:
- ❌ **Dealbreakers** (score = 0):
  - Currently raining/snowing
  - Thunderstorms
  - Active precipitation

- **Score Penalties**:
  - Freezing temps (<0°C): -50 points
  - Very cold (<5°C): -30 points
  - Extreme heat (>38°C): -40 points
  - Very hot (>32°C): -20 points
  - Strong wind (>25 km/h): -25 points
  - Very humid (>90%): -15 points
  - Poor air quality (AQI >150): -25 points

### API Details

- **Provider**: Open-Meteo (free, no API key required)
- **Coverage**: Worldwide
- **Cache**: 10 minutes stale time, 30 minutes garbage collection
- **Retry**: 2 automatic retries on failure

## Troubleshooting

If weather data isn't showing:

1. **Check Console Logs**:
   - Open browser DevTools (F12)
   - Look for logs starting with `[MapPage]` or `[useMultipleSpotWeather]`
   - Check for geohash extraction: `[MapPage] Spot geohashes: [...]`
   - Check for weather fetch: `[useMultipleSpotWeather] Fetching weather for geohashes: [...]`

2. **Verify Weather Toggle**:
   - Button should change from "Weather Off" (gray) to "Weather On" (blue)
   - State should be saved and persist across page refreshes

3. **Check Network Tab**:
   - Look for requests to `api.open-meteo.com`
   - Verify requests complete successfully (status 200)

4. **Verify Spot Data**:
   - Spots must have valid geohash values
   - Check console log: `[MapPage] Spot geohashes` should show array of geohashes
   - If array is empty, spots don't have geohash data

5. **Browser Support**:
   - Modern browsers (Chrome, Firefox, Safari, Edge)
   - JavaScript enabled
   - No ad blockers blocking Open-Meteo API

## Technical Implementation

### Files Created/Modified

**New Files**:
- `/src/lib/weather.ts` - Weather API service and skateability calculations
- `/src/hooks/useSpotWeather.ts` - React hooks for weather data
- `/src/components/WeatherToggle.tsx` - Weather toggle button component
- `/src/components/PWAInstallPrompt.tsx` - PWA install prompt (bonus feature)

**Modified Files**:
- `/src/pages/MapPage.tsx` - Added weather state and filtering
- `/src/components/SpotMap.tsx` - Added weather marker colors and popups
- `/src/pages/SpotDetailPage.tsx` - Added weather card to sidebar

### Key Components

1. **Weather Service** (`lib/weather.ts`):
   - `fetchWeather()` - Get current weather for lat/lng
   - `fetchAirQuality()` - Get air quality data
   - `fetchWeatherForecast()` - Get 3-day forecast
   - `calculateSkateability()` - Calculate 0-100 score

2. **React Hooks** (`hooks/useSpotWeather.ts`):
   - `useSpotWeather()` - Single spot weather
   - `useMultipleSpotWeather()` - Batch weather for all spots

3. **UI Components**:
   - `WeatherToggle` - Toggle button with state
   - `SpotMap` - Weather-colored markers and detailed popups

## Next Steps

Possible enhancements:
- Weather-based notifications ("Perfect skating weather at X spot!")
- Historical weather data
- Best time to skate recommendations
- Weather radar overlay
- Wind direction visualization
- Precipitation forecasts with timing

## Credits

- Weather data: [Open-Meteo](https://open-meteo.com/)
- Air quality data: Open-Meteo Air Quality API
- Map: OpenStreetMap