# Interactive Data Visualization Specification

## Overview

Generate interactive data visualizations that demonstrate state management capabilities. Each iteration should fetch real data from web APIs, create unique visualizations, and integrate seamlessly with the stateful infinite loop system.

## Output Requirements

### File Naming

Pattern: `visualization_[iteration_number].html`

Examples:
- `visualization_1.html`
- `visualization_2.html`
- `visualization_15.html`

### File Structure

Each output must be a self-contained HTML file:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>[Unique Title] - Iteration [N]</title>
    <style>
        /* Embedded CSS */
    </style>
</head>
<body>
    <!-- Visualization container -->
    <div id="viz-container"></div>

    <!-- Metadata section (required for state tracking) -->
    <div id="metadata" style="display:none;">
        {
            "iteration": [N],
            "web_source": "[URL]",
            "techniques_learned": ["technique1", "technique2"],
            "data_source": "[API URL]",
            "created": "[ISO timestamp]"
        }
    </div>

    <!-- External libraries (D3, Chart.js, etc) -->
    <script src="https://d3js.org/d3.v7.min.js"></script>

    <script>
        // Visualization code
    </script>
</body>
</html>
```

## Content Requirements

### 1. Unique Visualization Type

Each iteration must implement a different visualization approach:

**Examples:**
- Bar chart with transitions
- Network graph with force simulation
- Geographic map with data overlay
- Timeline with interactive zoom
- Scatter plot with clustering
- Hierarchical tree diagram
- Sunburst chart
- Parallel coordinates
- Sankey diagram
- Chord diagram

### 2. Real Data Integration

Must fetch data from public APIs:

**Recommended APIs:**
- OpenWeather API (weather data)
- World Bank API (economic indicators)
- NASA API (space data)
- GitHub API (repository statistics)
- COVID-19 API (pandemic data)
- UN Data API (development indicators)
- Carbon Intensity API (environmental data)
- Random User API (demographic data)

### 3. Web Learning Integration

Each iteration should:
1. Fetch assigned web URL (from URL strategy)
2. Extract 1-3 specific visualization techniques
3. Apply learned techniques to implementation
4. Document learning in metadata

**Example:**
```javascript
// Learned from: https://observablehq.com/@d3/learn-d3-scales
// Technique 1: Using scaleSequential for color gradients
// Technique 2: Implementing ordinal scales for categorical data
const colorScale = d3.scaleSequential(d3.interpolateViridis)
    .domain([0, maxValue]);
```

### 4. Interactivity

Include at least 2 interactive features:
- Hover tooltips
- Click to filter
- Zoom/pan controls
- Animation toggles
- Data updates
- Selection highlighting

### 5. Responsive Design

Must work on different screen sizes:
- Mobile (320px+)
- Tablet (768px+)
- Desktop (1024px+)

### 6. Accessibility

Include:
- ARIA labels
- Keyboard navigation
- Color contrast compliance
- Screen reader support

## Quality Standards

### Visual Quality

- Clean, professional appearance
- Thoughtful color palette
- Appropriate chart type for data
- Clear axis labels and legends
- Readable text at all sizes

### Code Quality

- Well-commented code
- Modular structure
- Error handling
- Loading states
- Fallback for API failures

### Performance

- Load time < 3 seconds
- Smooth animations (60fps)
- Efficient data processing
- Proper resource cleanup

### Documentation

Each file must include:
- Header comment with iteration number
- Web source URL in comment
- Techniques learned listed
- Data source documented
- API attribution

**Example:**
```javascript
/**
 * Interactive Climate Data Visualization - Iteration 7
 *
 * Web Source: https://observablehq.com/@d3/choropleth
 * Techniques Learned:
 *   1. Choropleth mapping with TopoJSON
 *   2. Color scale normalization for geographic data
 *   3. Interactive legend with highlighting
 *
 * Data Source: Carbon Intensity API (https://api.carbonintensity.org.uk)
 *
 * Created: 2025-03-10T14:30:00Z
 * Run ID: run_20250310_143022
 */
```

## State Management Integration

### Required Metadata

Each output MUST include embedded metadata for state tracking:

```html
<div id="metadata" style="display:none;">
{
    "iteration": 7,
    "web_source": "https://observablehq.com/@d3/choropleth",
    "techniques_learned": [
        "Choropleth mapping with TopoJSON",
        "Color scale normalization",
        "Interactive legend highlighting"
    ],
    "data_source": "https://api.carbonintensity.org.uk",
    "created": "2025-03-10T14:30:00Z",
    "validation_hash": "computed_by_system"
}
</div>
```

This metadata enables:
- State reconstruction from files
- URL deduplication
- Quality validation
- Learning tracking

### Web Source Attribution

Include visible attribution:

```html
<div class="attribution">
    <p>Visualization inspired by: <a href="[web_source]">[source_title]</a></p>
    <p>Data from: <a href="[api_url]">[api_name]</a></p>
</div>
```

## Progressive Difficulty

Iterations should increase in sophistication:

### Foundation (Iterations 1-3)
- Simple chart types (bar, line, pie)
- Single data source
- Basic interactivity
- Standard D3 patterns

### Intermediate (Iterations 4-7)
- Complex chart types (network, map, hierarchy)
- Multiple data sources
- Advanced interactivity
- Custom D3 techniques

### Advanced (Iterations 8-12)
- Novel visualizations
- Real-time data updates
- Complex interactions
- Performance optimizations

### Expert (Iterations 13+)
- Cutting-edge techniques
- Multi-view coordination
- Advanced animations
- Research-level implementations

## Uniqueness Requirements

No two iterations should:
- Use the same visualization type
- Fetch from the same API endpoint
- Implement identical interaction patterns
- Have the same visual style

Ensure variety across:
- Chart types
- Color schemes
- Layout approaches
- Animation styles
- Data domains

## Web Learning Strategy

If URL strategy provided, use progressive learning:

```json
{
  "foundation": [
    "https://observablehq.com/@d3/learn-d3",
    "https://www.d3-graph-gallery.com/intro_d3js.html"
  ],
  "intermediate": [
    "https://observablehq.com/@d3/force-directed-graph",
    "https://observablehq.com/@d3/choropleth"
  ],
  "advanced": [
    "https://observablehq.com/@d3/hierarchical-edge-bundling",
    "https://observablehq.com/@d3/calendar-view"
  ],
  "expert": [
    "https://observablehq.com/@d3/streamgraph",
    "https://observablehq.com/@d3/voronoi-stippling"
  ]
}
```

Each iteration:
1. Fetches appropriate URL for difficulty level
2. Extracts specific techniques
3. Applies to unique data visualization
4. Documents learning path

## Success Criteria

An excellent visualization:

1. **Functional**: Works correctly with real data
2. **Unique**: Different from all previous iterations
3. **Educational**: Demonstrates clear web learning
4. **Interactive**: Engages users meaningfully
5. **Professional**: Production-quality code and design
6. **Accessible**: Usable by diverse audiences
7. **Documented**: Clear metadata and attribution
8. **Performant**: Fast load and smooth interaction

## Example Output Summary

**Iteration 5: Global Temperature Anomaly Timeline**
- Visualization: Animated line chart with brush zoom
- Data: NASA GISS Surface Temperature Analysis API
- Web Source: https://observablehq.com/@d3/brush-zoom
- Techniques: Brush selection, zoom transforms, animated transitions
- Interactivity: Zoom to timeframe, hover for exact values
- File: visualization_5.html (self-contained, 45KB)

## Testing Your Output

Before considering an iteration complete:

1. Open in browser (all major browsers)
2. Verify data loads successfully
3. Test all interactive features
4. Check mobile responsiveness
5. Validate accessibility with screen reader
6. Confirm metadata is present and valid
7. Ensure web attribution is visible
8. Verify uniqueness from previous iterations

## State System Integration

The state management system will:
- Track your output file path
- Extract and store web_source from metadata
- Compute validation hash of file content
- Prevent URL duplication in future iterations
- Enable rebuild of state from your metadata
- Validate your output exists

Therefore, ALWAYS include:
- Complete metadata div with valid JSON
- Accurate web_source URL
- Proper iteration number
- ISO timestamp

This enables the full power of stateful operation.
