chart · diff
v3.0.1 to v3.0.2
6 added, 2 removed. Audit A to A.
---
name: chart
- version: 3.0.1
- description: Interactive web-based charts for data analysis and business intelligence. Project-based output in output/chart-html/<project>/ with HTML + script + data + screenshot.
+ version: 3.0.2
+ description: |
+ Interactive web charts: line, bar, candle, scatter, with HTML and screenshot output.
+ Use when visualizing data for analysis or BI (e.g. plot BTC vs gold last year, bar chart of revenue by quarter, compare two return series).
+
metadata:
starchild:
emoji: "📊"
skillKey: chart
user-invocable: true
disable-model-invocation: false
+
---
# 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.