dash-echartsx 0.1.0__tar.gz

dash_echartsx-0.1.0/.agent/skills/dash-duo-test-generator/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: dash-duo-test-generator
+description: "Use when adding Selenium/dash_duo browser tests for Dash EChartsX chart rendering, resizing, renderer/theme switching, or Dash prop callbacks."
+---
+
+# Generate Dash Browser Tests
+
+Use `dash[testing]` and the `dash_duo` fixture to verify behavior that Python unit tests cannot cover: the generated UMD bundle, React lifecycle, real chart rendering, and responsive layout.
+
+## Test Pattern
+
+```python
+from dash import Dash, html
+from dash_echartsx import DashEChartsX
+
+
+def test_chart_renders(dash_duo):
+    app = Dash(__name__)
+    app.layout = html.Div(
+        DashEChartsX(
+            id="chart",
+            option={
+                "xAxis": {"type": "category", "data": ["A", "B"]},
+                "yAxis": {"type": "value"},
+                "series": [{"type": "bar", "data": [2, 4]}],
+            },
+        ),
+        style={"width": "60vw"},
+    )
+    dash_duo.start_server(app)
+    dash_duo.wait_for_element("#chart canvas", timeout=30)
+    assert dash_duo.get_logs() == []
+```
+
+## Useful Assertions
+
+- Canvas renderer: wait for `#chart canvas`.
+- SVG renderer: wait for `#chart svg`.
+- Resize: change a parent width, wait for observer/frame work, then compare element and renderer dimensions.
+- Theme/renderer update: drive a Dash callback or button, verify the old renderer is disposed and the requested new renderer appears.
+- Capture browser console errors with `dash_duo.get_logs()`.
+- For Dash callback behavior, assert the Python output reflects the updated component prop, not only that a click occurred.
+
+Keep browser tests in `tests/` with clear names; the repository currently has a flat test layout. Ensure `dash[testing]` is installed with `uv sync --group dev`. Do not assume a separate `tests/integration` folder or Linux `xvfb-run` setup exists.
+
+`tests/conftest.py` is the shared Selenium setup: it installs a matching
+ChromeDriver, enables headless Chrome when `CI` is set, and configures
+WebGL/SwiftShader for Linux. CI runs tests on Ubuntu and Windows. Use its
+`dash_duo` fixture instead of installing or configuring a driver in an
+individual test. When a browser wait fails, inspect browser logs and the
+application's rendered state before increasing the timeout.

dash_echartsx-0.1.0/.agent/skills/dash-echartsx-test-runner/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: dash-echartsx-test-runner
+description: "Use when adding, running, or debugging tests for dash-echartsx. Covers the current flat pytest suite, uv commands, optional dash_duo browser tests, and build/type/lint checks."
+---
+
+# dash-echartsx Test Runner
+
+## Current Layout
+
+```text
+tests/
+├── conftest.py
+├── test_dispatch_actions.py
+├── test_events.py
+├── test_maps_gl.py
+└── test_options.py
+```
+
+Keep fast Python tests and `dash_duo` browser tests directly under `tests/`, and name them clearly so they can be selected with pytest. There are no `tests/unit/` or `tests/integration/` directories and no JavaScript test runner configured currently.
+
+`tests/conftest.py` installs a matching ChromeDriver, enables Dash's headless
+browser in CI, and supplies Linux WebGL/SwiftShader options. CI runs the
+Python/ECharts test matrix on both Ubuntu and Windows. Use the standard
+`uv run pytest` command; set `CI=true` to exercise the headless configuration
+locally.
+
+## Commands
+
+```sh
+uv sync --group dev
+npm run build
+npm run lint
+npm run typecheck
+uv run ruff check .
+uv run black --check dash_echartsx tests
+uv run pytest
+```
+
+For one file, run `uv run pytest tests/test_options.py`. For browser tests, install dependencies with `uv sync --group dev`. The shared
+conftest handles ChromeDriver and browser options; do not add per-test
+driver-installation code.
+
+## Debugging
+
+- Python import/wrapper failure: run `npm run build` and inspect generated files under `dash_echartsx/`.
+- Missing component in Dash: verify `dash_echartsx/__init__.py` exposes the class/version and registers the UMD asset.
+- Browser bundle runtime error: check that the Dash asset is UMD and React remains external in Vite.
+- Browser startup timeout: check the `dash_duo` setup in `tests/conftest.py`, the installed Chrome version, and the browser console before extending wait timeouts.
+- Resize failure: assert wrapper dimensions after layout changes and check observer cleanup/frame scheduling.
+- Renderer/theme failure: verify the component is remounted for theme/renderer changes and that options are reapplied afterward.

dash_echartsx-0.1.0/.agent/skills/echarts-option-validator/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: echarts-option-validator
+description: "Use when reviewing Apache ECharts options, chart series, themes, renderers, datasets, or registered maps for dash-echartsx. Checks ECharts 6 option structure, modular imports, Dash JSON compatibility, and unsafe JavaScript serialization."
+---
+
+# Validate ECharts Options
+
+Review Python-supplied options and React module registrations against ECharts 6 and the current component API.
+
+## Checks
+
+1. Identify each `series[].type`; verify its chart module is registered from `echarts/charts` in `src/lib/components/DashEChartsX.tsx`.
+2. Verify required axes/components (grid, title, legend, tooltip, visual map, data zoom, etc.) are registered from `echarts/components`.
+3. Verify the renderer is registered from `echarts/renderers`; accepted values are `canvas` and `svg`.
+4. Keep options and custom themes JSON-serializable. Do not promise plain JSON callbacks or execute Python strings as JavaScript.
+5. For geographic charts, verify map names are registered with ECharts. Do not assume coordinate/projection conventions without checking the map data contract.
+6. Preserve caller-owned data; document any normalization or defaulting.
+
+## Verification
+
+- Check installed ECharts 6 declarations for uncertain option fields.
+- Add focused Python helper tests as needed.
+- For runtime behavior, use a Dash `dash_duo` test and assert the expected canvas/SVG node and absence of browser errors.
+- Reuse the ChromeDriver and browser setup in `tests/conftest.py`; CI runs browser tests headlessly on Ubuntu and Windows.
+- Run `npm run build`, `npm run typecheck`, `npm run lint`, and `uv run pytest`.
+
+Report findings as `path | issue | evidence | correction`. Do not rewrite options during an audit-only request.

dash_echartsx-0.1.0/.agent/skills/scaffold-dash-echartsx-component/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: scaffold-dash-echartsx-component
+description: "Use when adding or expanding a Dash EChartsX React component or public prop. Scaffolds TSX props, Dash exports, generated Python metadata, tests, and a usage example using this repository's Vite and uv build flow."
+---
+
+# Scaffold a Dash EChartsX Component
+
+Use this workflow when adding a component or public prop. The primary component is `src/lib/components/DashEChartsX.tsx`.
+
+## Before Editing
+
+1. Read the current TSX component, `src/index.ts`, `package.json`, and `dash_echartsx/__init__.py`.
+2. Decide whether the request belongs in the existing chart wrapper or needs a distinct exported component.
+3. Confirm ECharts 6 type and modular import names from installed declarations; do not guess module paths.
+
+## Component Rules
+
+- Use functional React components with typed props and JSDoc descriptions for public props.
+- Create and dispose ECharts instances in effects with matching cleanup.
+- Register only required chart, component, and renderer modules.
+- For theme/renderer changes, reinitialize then apply the latest option.
+- Resize with `ResizeObserver`, a coalesced animation frame, a window fallback, and complete cleanup.
+- Keep Python-facing values JSON-compatible. Never evaluate arbitrary strings as code.
+- Do not hand-edit generated files in `dash_echartsx/`.
+
+## Build and Verify
+
+```sh
+npm run build
+npm run lint
+npm run typecheck
+uv run pytest
+```
+
+Inspect generated wrapper, metadata, PropTypes, and bundle diffs. Add a `dash_duo` test under `tests/` for browser-dependent behavior.
+
+Browser tests use the shared Selenium configuration in `tests/conftest.py`.
+The CI matrix exercises the Python and ECharts versions on both Ubuntu and
+Windows.

dash_echartsx-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,37 @@
+# CLAUDE.md — dash-echartsx
+
+## Project Shape
+
+- React component: `src/lib/components/DashEChartsX.tsx`; export: `src/index.ts`.
+- ECharts option, theme, renderer, and responsive lifecycle are managed by the functional React component.
+- `npm run build` generates UMD/ES bundles and Python wrapper metadata in `dash_echartsx/`.
+- Python helpers live in `dash_echartsx/utils.py`; tests live directly in `tests/`.
+
+## Invariants
+
+1. Initialize ECharts in an effect and dispose it in cleanup.
+2. Disconnect resize observers/listeners and cancel scheduled frames.
+3. Keep public prop docs in TSX; do not hand-edit generated wrappers/bundles.
+4. Guard every Dash `setProps` call and preserve Dash ownership of input props.
+5. Keep React external in the UMD build; register only the UMD bundle in `_js_dist`.
+6. Renderer values are `canvas`/`svg`; themes are `light`/`dark`/custom JSON. Do not evaluate arbitrary option strings.
+
+## Verification
+
+```sh
+uv sync --group dev
+npm ci
+npm run build
+npm run lint
+npm run typecheck
+uv run ruff check .
+uv run black --check dash_echartsx tests
+uv run pytest
+```
+
+Browser tests use the shared Selenium setup in `tests/conftest.py`, which
+installs a matching ChromeDriver, enables headless mode in CI, and configures
+Linux WebGL/SwiftShader. The CI matrix covers Ubuntu and Windows. Set `CI=true`
+when reproducing the headless CI test environment locally.
+
+Use task-specific recipes under `.agent/skills/` and architecture notes in [AI_CONTEXT.md](../.github/AI_CONTEXT.md).

dash_echartsx-0.1.0/.github/AI_CONTEXT.md

@@ -0,0 +1,73 @@
+# AI Context Map — dash-echartsx
+
+Architecture notes for agents working on the Dash/ECharts integration.
+
+## Data Flow
+
+```text
+Python Dash layout/callback
+        │ JSON component props
+        ▼
+Generated dash_echartsx.DashEChartsX wrapper
+        │ Dash renderer loads UMD component
+        ▼
+src/lib/components/DashEChartsX.tsx
+  ├─ effect initializes ECharts with option/theme/renderer
+  ├─ ResizeObserver schedules chart.resize()
+  └─ cleanup disconnects observers and disposes the chart
+        │
+        ▼
+ECharts Canvas or SVG renderer
+```
+
+Python supplies props through Dash. For any future browser-to-Python events, use guarded `setProps({ ... })` calls; never assume the Dash bridge exists outside the renderer.
+
+## File Boundaries
+
+| Path                                  | Responsibility                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `src/lib/components/DashEChartsX.tsx` | React lifecycle, ECharts initialization, option/theme/renderer props, resizing |
+| `src/index.ts`                        | Vite library exports                                                           |
+| `dash_echartsx/utils.py`              | Python option helpers                                                          |
+| `dash_echartsx/__init__.py`           | Python public export and Dash asset registration                               |
+| `dash_echartsx/metadata.json`         | Generated prop metadata                                                        |
+| `dash_echartsx/DashEChartsX.py`       | Generated Dash Python wrapper                                                  |
+| `dash_echartsx/dash_echartsx.es.js`   | Generated ESM bundle for bundler consumers                                     |
+| `dash_echartsx/dash_echartsx.umd.js`  | Generated UMD bundle loaded by Dash                                            |
+| `tests/`                              | Flat Python and `dash_duo` browser test suite                                  |
+| `tests/conftest.py`                   | Shared ChromeDriver, headless CI, and Linux WebGL/SwiftShader setup            |
+
+## Pitfalls
+
+| Avoid                                            | Prefer                                                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------ |
+| Initialize ECharts during React render           | Initialize in an effect and dispose in cleanup                           |
+| Reinitialize after every option update           | Call `setOption`; only recreate for theme/renderer changes               |
+| Run `chart.resize()` for every observer callback | Coalesce with an animation frame and cancel it on cleanup                |
+| Resize a collapsed, zero-size element            | Wait for positive width and height                                       |
+| Hardcode a pixel width/height                    | Use responsive defaults and caller-overridable `style`                   |
+| Mutate incoming option/theme objects             | Treat them as caller-owned, immutable props                              |
+| Pass option strings as executable callbacks      | Keep JSON serializable; add a reviewed explicit callback API if required |
+| Edit generated assets/wrappers directly          | Change TSX/Python source and run `npm run build`                         |
+| Add ESM to Dash `_js_dist`                       | Register only the UMD bundle                                             |
+| Bundle a second React runtime                    | Keep React external in Vite UMD output                                   |
+
+## Commands
+
+The current checks are `npm run build`, `npm test`, `npm run lint`, `npm run typecheck`, `uv run ruff check .`, `uv run black --check dash_echartsx tests scripts`, and `uv run pytest`. JavaScript utility unit tests live in `src/lib/utils/`; Python component and Selenium integration tests live in `tests/` and use the `integration` marker. `tests/conftest.py` installs a matching ChromeDriver, configures Linux SwiftShader for WebGL, and enables headless browser mode when `CI` is set. The CI workflow tests Python 3.10–3.14 and ECharts 5/6 on Ubuntu, macOS, and Windows, and builds wheel/source distribution artifacts for every OS/Python pair; pull request runs upload those artifacts for review. Firefox integration tests run separately on Ubuntu. Use `CI=true uv run pytest` to reproduce the headless Chrome suite locally.
+
+## AI option generation
+
+Use `.github/skills/echarts-option-generator/SKILL.md` and its prompt
+templates when translating Python dictionaries or Pandas data into chart
+options. Validate JSON before using it in a Dash callback:
+
+```sh
+npm run echarts:validate -- path/to/option.json
+```
+
+The validator checks against the pinned ECharts 5.6.0 option declarations and
+verifies that core series types are registered by `DashEChartsX`. ECharts-GL
+options require `--enable-gl`; their extension fields are not fully covered by
+the core ECharts type schema. The ECharts declarations are extensible and may
+accept unknown option keys, so this is not a complete JSON Schema validator.

dash_echartsx-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,58 @@
+---
+name: Bug report
+about: Create a report to help us improve (bugs, regressions)
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Description (required)
+
+<!--
+Provide a clear and concise description of the bug.
+-->
+
+## Acceptance Criteria
+
+- [ ] The bug is reproducible following the steps below
+- [ ] Clear expected vs actual behaviour is stated
+
+## Steps to reproduce (required)
+
+<!--
+1.
+2.
+3.
+-->
+
+## Expected behavior
+
+<!--
+Describe what you expected to happen.
+-->
+
+## Actual behavior
+
+<!--
+Describe what actually happened, include error messages and stack traces.
+-->
+
+## Environment
+
+<!--
+- dash-echartsx version:
+- Python version:
+- Browser / OS:
+-->
+
+## Proposed fix (optional)
+
+<!--
+If known, describe a possible fix.
+-->
+
+## Additional context
+
+<!--
+Add any other context, screenshots, or logs.
+-->

dash_echartsx-0.1.0/.github/ISSUE_TEMPLATE/issue_template.md

@@ -0,0 +1,53 @@
+---
+name: General issue
+about: Report a bug, request a feature, or propose maintenance work
+title: ""
+labels: ""
+assignees: ""
+---
+
+## Summary
+
+<!--
+Provide a concise summary of the issue or feature request.
+-->
+
+## Steps to reproduce (for bugs)
+
+<!--
+1. Go to '...'
+2. Click on '...'
+3. See error
+-->
+
+## Expected behavior
+
+<!--
+Describe what you expected to happen.
+-->
+
+## Actual behavior
+
+<!--
+Describe what actually happened, including any error messages and stack traces.
+-->
+
+## Proposed solution (optional)
+
+<!--
+If you have a suggested fix or approach, describe it here.
+-->
+
+## Environment
+
+<!--
+- dash-echartsx version:
+- Python version:
+- Browser / OS:
+-->
+
+## Additional context
+
+<!--
+Add any other context or screenshots about the issue here.
+-->

dash_echartsx-0.1.0/.github/ISSUE_TEMPLATE/story.md

@@ -0,0 +1,24 @@
+---
+name: Story / Feature request
+about: Describe a new feature or improvement
+title: "[STORY] "
+labels: enhancement
+assignees: ""
+---
+
+## Description (required)
+
+<!--
+Provide a clear and concise description of the requested feature or story.
+-->
+
+## Acceptance Criteria (required)
+
+- [ ] Clear success criteria for the story
+- [ ] Any constraints or compatibility notes
+
+## Additional context
+
+<!--
+Add any other context, mockups, or links.
+-->

dash_echartsx-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# GitHub Copilot Instructions — dash-echartsx
+
+These repository-wide rules describe the current Dash/EChartsX architecture.
+See [AI_CONTEXT.md](AI_CONTEXT.md) for data flow and `.agent/skills/` plus
+`.github/skills/` for task-specific workflows. Use the
+`echarts-option-generator` skill when generating or validating option payloads.
+
+## Project Invariants
+
+1. **Chart lifecycle:** Initialize ECharts only in `useEffect`; always dispose the instance in cleanup. Pair observers/listeners and scheduled frames with cleanup.
+2. **Dash bridge:** Send client state through `setProps({ ... })` only when `setProps` exists.
+3. **Prop documentation:** Document public TSX props with JSDoc. `npm run build` generates component metadata, Python wrappers, and PropTypes from TSX.
+4. **Options:** Keep option/theme data JSON-compatible. Never evaluate arbitrary Python strings as JavaScript callbacks.
+5. **Source of truth:** React source is `src/lib/components/`, exports are in `src/index.ts`, Python helpers are in `dash_echartsx/`, and tests are in `tests/`. Generated bundles, wrappers, metadata, and `proptypes.js` must be regenerated with `npm run build`, not hand-edited.
+6. **Dash assets:** Register only the UMD file in `dash_echartsx/__init__.py`; keep React external in the Vite UMD build.
+7. **Responsive sizing:** Do not hardcode pixel dimensions. Observe the wrapper, coalesce resize notifications, skip zero-sized containers, and clean up all pending work.
+8. **Engine props:** Supported renderer values are `canvas` and `svg`; supported themes are `light`, `dark`, or a custom JSON object.
+
+## Verification
+
+```sh
+uv sync --group dev
+npm ci
+npm run build
+npm run lint
+npm run typecheck
+uv run ruff check .
+uv run black --check dash_echartsx tests
+uv run pytest
+```
+
+`npm test` runs JavaScript utility tests. Browser tests use `dash_duo` from
+`dash[testing]` in `tests/`.
+The shared Selenium configuration is in `tests/conftest.py`: it installs a
+matching ChromeDriver, enables headless mode when `CI` is set, and configures
+Linux WebGL/SwiftShader. The CI matrix tests Python 3.10–3.14 with supported
+ECharts versions on Ubuntu, macOS, and Windows. Use the standard `uv run
+pytest` command; set `CI=true` to reproduce headless CI behavior locally.
+
+## Skills
+
+- `scaffold-dash-echartsx-component` for a new component or public prop.
+- `echarts-option-validator` for option/module/theme/map reviews.
+- `dash-duo-test-generator` for browser-level chart rendering and prop updates.
+- `dash-echartsx-test-runner` for the current Python and browser test layout.

dash_echartsx-0.1.0/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  # Node.js Ecosystem
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"
+      time: "02:00"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "security"
+      - "automated-pr"
+    commit-message:
+      prefix: "chore(deps)"
+
+  # Python Ecosystem
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "daily"
+      time: "02:00"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "security"
+      - "automated-pr"
+    commit-message:
+      prefix: "chore(deps-python)"

dash_echartsx-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Summary
+
+<!-- Describe the change and why it is needed. -->
+
+## Related issue
+
+<!-- Use Fixes #<number>, Closes #<number>, or Related to #<number>. -->
+
+- #
+
+## Change type
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Documentation
+- [ ] Build/CI maintenance
+
+## Verification
+
+- [ ] `npm run build`
+- [ ] `npm run lint`
+- [ ] `npm run typecheck`
+- [ ] `uv run ruff check .`
+- [ ] `uv run pytest`
+- [ ] Browser behavior checked when applicable
+
+## Notes for reviewers
+
+<!-- Include compatibility, generated-file, or behavior notes. -->

dash_echartsx-0.1.0/.github/skills/echarts-option-generator/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: echarts-option-generator
+description: Generate and validate ECharts 5 option objects for DashEChartsX from Python dictionaries or Pandas DataFrames.
+---
+
+# ECharts Option Generator
+
+Use this skill when creating, transforming, optimizing, or reviewing an ECharts
+option payload for this repository.
+
+## Required context
+
+1. Read `.github/AI_CONTEXT.md` and `.github/copilot-instructions.md`.
+2. Use the current Python component API: `from dash_echartsx import
+DashEChartsX`. Do not generate legacy `dash_echarts.DashECharts` code or
+   deprecated `app.run_server` calls.
+3. Check `src/lib/components/DashEChartsX.tsx` before selecting chart types.
+   Core series types must have their ECharts chart module registered there.
+   ECharts-GL series additionally require `enable_gl=True`.
+4. Keep the option JSON-compatible. Use only documented `js_function(...)`
+   markers for developer-authored callbacks; never translate arbitrary
+   Python strings into executable JavaScript.
+
+## Generation procedure
+
+1. Preserve the meaning, units, ordering, and caller-owned input data. Do not
+   silently discard columns, rows, nulls, or categories.
+2. If chart type, axis mapping, units, aggregation, missing-value behavior, or
+   downsampling policy is ambiguous, ask before choosing.
+3. Generate the option as a plain JSON object. Normalize NumPy/Pandas scalar
+   values and timestamps into JSON-compatible values without changing their
+   meaning. Keep large data payloads bounded only when the user requests or
+   approves a limit.
+4. For a map, verify every `series[].map` name is registered by the component's
+   `maps=[{"name": ..., "geoJSON": ...}]` property. Do not assume a projection
+   or map provider.
+5. Validate the option before placing it in or returning it from a Dash
+   callback:
+
+   ```console
+   npm run echarts:validate -- path/to/option.json
+   ```
+
+   Pipe generated JSON to the validator when no file is needed:
+
+   ```console
+   python generate_option.py | npm run echarts:validate
+   ```
+
+   For ECharts-GL options, pass `--enable-gl` and set `enable_gl=True` on
+   `DashEChartsX`. The validator checks the option against the pinned official
+   ECharts 5.6.0 `EChartsOption` declarations and checks core series against
+   modules actually registered by this component. GL-specific nested fields
+   are not fully covered by the ECharts core declarations. The declarations
+   are extensible and may accept unknown option keys, so this is not a complete
+   JSON Schema validator; state these limits.
+
+6. Only after validation succeeds, use the option as the `option` prop or
+   return it from a callback with `Output("chart", "option")`.
+
+## Output format
+
+Return:
+
+1. The validated JSON option.
+2. A concise DashEChartsX usage snippet, including `maps` or `enable_gl` when
+   needed.
+3. The exact validation command and its result.
+4. Any remaining caveat, such as ECharts-GL extension typing or a chart module
+   not currently registered by the component.
+
+Prompt templates are in `prompts/`.

dash_echartsx-0.1.0/.github/skills/echarts-option-generator/prompts/pandas-dataframe-to-option.md

@@ -0,0 +1,50 @@
+# Convert a Pandas DataFrame into a DashEChartsX option
+
+You are generating an Apache ECharts 5 option and Python callback example for
+this repository's `DashEChartsX` component.
+
+## Input
+
+```text
+{{DATAFRAME_DESCRIPTION}}
+```
+
+```python
+{{DATAFRAME_CREATION_OR_SAMPLE}}
+```
+
+## Requirements
+
+- Confirm which column is the category/time axis, which columns are measures,
+  and whether a row represents a sample, aggregate, or series. Ask if unclear.
+- Preserve column names, row order, units, and timestamp meaning. Do not infer
+  aggregation, timezone, null handling, sorting, or downsampling policy.
+- Keep the callback payload JSON-compatible. Convert Pandas/NumPy scalar
+  values explicitly and handle missing values only according to the user's
+  stated policy.
+- Select only chart series whose ECharts modules are registered in
+  `src/lib/components/DashEChartsX.tsx`. Keep series data aligned with the
+  declared axes and categories.
+- Avoid copying large frames on every callback. For streaming data, prefer a
+  bounded update or `append_data` only when the chosen ECharts series type
+  supports ECharts `appendData`.
+- Do not encode JavaScript callbacks as strings. If requested, show the
+  explicit `js_function(...)` marker separately and identify it as executable
+  developer-authored code.
+- If the option uses ECharts-GL, state that `enable_gl=True` is required.
+
+## Deliverables
+
+1. The ECharts option JSON.
+2. The Python conversion/callback snippet, with every data transformation
+   explained.
+3. The exact `DashEChartsX` callback wiring.
+4. The output option validated before callback use with:
+
+   ```console
+   python make_option.py | npm run echarts:validate
+   ```
+
+   Add `--enable-gl` for ECharts-GL options.
+
+5. Validation results and any assumptions or remaining schema limitations.