chart

What this skill does

# Chart — Project-Based Interactive Charting

Generate interactive chart pages with Apache ECharts. Each chart lives in a dedicated project folder under `output/chart-html/`, making it easy to reuse and iterate.

## When to Use

Any time the user wants a visual chart: price charts, comparisons, dashboards, business analytics, etc.

## Architecture

- **ECharts** (CDN) for rendering
- **ECharts native export (`getDataURL`) + canvas merge** for reliable PNG output
- **Project-based storage**: one folder per chart project
- **No gallery mode**: all artifacts stay in the project folder

## Project Structure (Required)

Each chart project should follow:

```
output/chart-html/
  <project-name>/
    index.html        # chart page
    generate.py       # generation script (for reproducibility)
    README.md         # title / description / data source notes
    data.json         # data snapshot
    screenshot.png    # saved image
```

Example folder name: `btc-90d-20260401`

## Workflow

### Step 1: Pick template or custom layout

Available templates:

| Template | Best for |
|---|---|
| `line.html` | Time-series trends, multi-series comparisons |
| `bar.html` | Category comparisons, rankings |
| `pie.html` | Composition / share breakdown |
| `candlestick.html` | OHLCV price charts |
| `scatter.html` | Correlation, distribution |
| `dashboard.html` | KPI cards + 2×2 multi-chart grid |
| `radar.html` | Multi-dimension scoring |
| `heatmap.html` | Matrix / calendar intensity |
| `dual-axis.html` | Two series with very different scales (e.g. market cap vs stablecoin supply) — left and right Y axes, each with its own label color |
| `multi-panel.html` | Stacked panels sharing one X axis (e.g. price + volume + RSI) — single ECharts instance, tooltip/zoom synced across all panels |
| `waterfall.html` | Incremental contribution breakdown (e.g. P&L attribution, budget variance) — positive/negative bars stacked on a floating base |

### Step 2: Create project folder

Use `create_project(name, description, data_sources)` from `scripts/build_chart.py`.

### Step 3: Build and save chart page

Use either:
- `build_chart(template_name, ...)`
- `build_chart_custom(...)`

Then save as `index.html` in the project folder:
- `save_chart(html, project_dir=project_dir)`

### Step 4: Save reproducible assets

Also save:
- `save_generate_script(script_content, project_dir)` → `generate.py`
- `save_data(data, project_dir)` → `data.json`
- project README is created by `create_project(...)`

### Step 5: Serve preview

Use project-root serving (recommended):

```python
preview_serve(
  title="Chart Preview",
  dir="skills/chart/scripts",
  command="python3 chart_server.py /data/workspace/output/chart-html 7860",
  port=7860
)
```

Then open: `/preview/<id>/<project-name>/index.html`

Important behavior in v3.0.1:
- `chart_server.py` now rewrites preview-prefixed static paths internally (`/preview/<id>/...` → `/...`) before filesystem lookup.
- This guarantees the preview iframe resolves the real project `index.html` instead of falling back to root directory listing.
- Keep project pages under `output/chart-html/<project>/index.html` (do not serve `output/chart-html` directly as a static preview without `chart_server.py`).

### Step 6: Export image

Two modes:
1. **User wants web page + image**: click "💾 Save Image" in page toolbar, saves to current project as `screenshot.png`
2. **User wants image only**: call `screenshot_chart(project_dir)` (Playwright) and send `screenshot.png` directly

## Toolbar Requirements

Every chart page must include these buttons:

```html
<div class="actions">
  <button onclick="downloadPNG(this)">📥 Download PNG</button>
  <button onclick="copyToClipboard(this)">📋 Copy Image</button>
  <button onclick="saveToProject(this)">💾 Save Image</button>
</div>
```

Do not include gallery entry.

## Key Files

| File | Purpose |
|------|---------|
| `skills/chart/scripts/base-styles.css` | Base dark theme CSS |
| `skills/chart/scripts/base-export.js` | Export helpers: download/copy/save-to-project |
| `skills/chart/scripts/build_chart.py` | Project creation, HTML build, data/script save, screenshot |
| `skills/chart/scripts/chart_server.py` | Static server + `/save-chart` API |
| `skills/chart/templates/*.html` | Reusable chart templates |
| `output/chart-html/<project>/*` | All generated chart artifacts |

## Notes

- Embed data directly in HTML (`const DATA = ...`) to avoid iframe CORS issues.
- For multi-chart pages, register all chart instances in `window.CHART_INSTANCES`.
- Use meaningful project names (`topic-range-date`) for easy lookup.