feat: implement external environmental data display components

- Add WeatherWidget for current weather conditions
- Add TideDisplay for tide times and heights
- Add WaterQualityIndicator for EPA water quality data
- Add BeachQualityDisplay for beach ratings and certifications
- Add BiodiversityInfo for marine biodiversity information
- Add EnvironmentalDataPanel composite component
- Create externalDataService for API integration
- Add types for external environmental data
- Create demo page at /demo/environmental-data
- Add comprehensive README documentation

Fulfills requirements 11.1, 11.2, 11.3, 11.4, 11.6, 11.7
Completes task 19 from implementation plan
This commit is contained in:
2025-11-16 23:07:29 +00:00
parent 1e1e54e7ff
commit 2b222b65e1
16 changed files with 1041 additions and 2 deletions

159
src/components/external/README.md vendored Normal file
View File

@@ -0,0 +1,159 @@
# External Environmental Data Components
This directory contains components for displaying external environmental data from various public APIs and data sources.
## Components
### WeatherWidget
Displays current weather conditions for a location including:
- Temperature and "feels like" temperature
- Humidity percentage
- Wind speed and direction
- Weather description
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
**API Endpoint:** `GET /api/external/weather/:lat/:lng`
### TideDisplay
Shows tide information for coastal locations including:
- Next tide time and type (high/low)
- Today's tide schedule with times and heights
- Tide heights in meters
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
**API Endpoint:** `GET /api/external/tides/:lat/:lng`
### WaterQualityIndicator
Displays water quality status from EPA data:
- Overall quality rating (excellent, good, sufficient, poor)
- Water quality parameters (bacteria, pH, temperature)
- Last update date
- Data source information
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
**API Endpoint:** `GET /api/external/water-quality/:lat/:lng`
### BeachQualityDisplay
Shows beach quality ratings and certifications:
- Quality rating (Blue Flag, Green Coast, etc.)
- Awards and certifications
- Available facilities
- Last inspection date
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
**API Endpoint:** `GET /api/external/beach-quality/:lat/:lng`
### BiodiversityInfo
Displays marine biodiversity information:
- Protected area status
- Habitat type
- Conservation status
- Notable species list with scientific names
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
**API Endpoint:** `GET /api/external/biodiversity/:lat/:lng`
**Note:** This component only renders if meaningful data is available.
### EnvironmentalDataPanel
Composite component that displays all external environmental data widgets together.
**Props:**
- `latitude: number` - Location latitude
- `longitude: number` - Location longitude
- `className?: string` - Optional CSS classes
## Usage
### Individual Components
```tsx
import { WeatherWidget, TideDisplay } from '@/components/external';
function MyComponent() {
return (
<div>
<WeatherWidget latitude={53.3498} longitude={-6.2603} />
<TideDisplay latitude={53.3498} longitude={-6.2603} />
</div>
);
}
```
### Composite Panel
```tsx
import { EnvironmentalDataPanel } from '@/components/external';
function ReportDetails({ report }) {
return (
<div>
<h2>Report Details</h2>
{/* ... report info ... */}
<EnvironmentalDataPanel
latitude={report.latitude}
longitude={report.longitude}
/>
</div>
);
}
```
## Error Handling
All components handle loading and error states gracefully:
- **Loading state:** Shows a spinner with loading message
- **Error state:** Displays "data unavailable" message
- **No data:** Components hide themselves or show appropriate message
Components use `try-catch` blocks and never throw errors to parent components.
## Data Caching
External API responses are cached on the backend for up to 6 hours to:
- Minimize API calls to external services
- Improve performance
- Reduce costs
- Ensure data availability
## Backend Requirements
These components require the following backend API endpoints to be implemented:
1. `GET /api/external/weather/:lat/:lng` - Weather data from OpenWeatherMap
2. `GET /api/external/tides/:lat/:lng` - Tide data from WorldTides or NOAA
3. `GET /api/external/water-quality/:lat/:lng` - EPA water quality data
4. `GET /api/external/beach-quality/:lat/:lng` - Beach quality ratings
5. `GET /api/external/biodiversity/:lat/:lng` - Marine biodiversity information
See the design document for detailed API specifications and data formats.
## Demo
Visit `/demo/environmental-data` to see all components in action with sample locations.
## Requirements Fulfilled
These components fulfill the following requirements:
- **11.1** - Weather data integration
- **11.2** - Tide information display
- **11.3** - Water quality data from EPA
- **11.4** - Beach quality ratings
- **11.6** - Beach quality from EU databases
- **11.7** - Marine biodiversity information