ProvChart Runtime

Progressive enhancement for ProvChart HTML/CSS charts.

Drop in one script. It finds [data-provchart] elements, skips pure SVG exports, and adds:

• Scroll reveal / enter animation
• Hover scale
• Legend - series highlight
• Per-point tooltips (line, area, combo, bar, scatter, hbar, gauge)
• Count-up on gauge / stat values
• MutationObserver for charts injected after load (SPA, fetch, hydration)

No changes to the ProvChart core renderer. Works with output from the visual builder and POST /api/v1/generate.

| | | |---|---| | npm | provchart-runtime | | GitHub | fscss-ttr/provchart-runtime | | License | MIT | | Charts site | chart.devtem.org |

Install

CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/provchart-runtime.min.js" defer></script>

CDN (unpkg)

<script src="https://unpkg.com/[email protected]/dist/provchart-runtime.min.js" defer></script>

npm

npm install provchart-runtime

import 'provchart-runtime';
// or
import 'provchart-runtime/dist/provchart-runtime.min.js';

Quick start (zero config)

1. Render a ProvChart chart (builder, API, or static HTML/CSS) so the root has data-provchart="...".
2. Load the runtime:

<div id="app">
  <!-- ProvChart HTML + CSS from /api/v1/generate or the dashboard -->
</div>

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/provchart-runtime.min.js" defer></script>

That’s it. On load the runtime scans the document and observes new nodes.

Optional configuration

Define before the runtime script:

<script>
  window.ProvChartRuntimeConfig = {
    animation: true,
    revealOnScroll: true,
    replay: false,
    hoverScale: 1.02,
    tooltips: true,
    perPointTooltips: true,
    countUp: true,
    countUpMs: 800,
    observe: true,
    selector: '[data-provchart]',
    excludeSvg: true,
    durationMs: 700,
    rootMargin: '40px',
    threshold: 0.15,
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/provchart-runtime.min.js" defer></script>

Options

| Option | Default | Description | |--------|---------|-------------| | animation | true | Enter transition when a chart is revealed | | revealOnScroll | true | Use IntersectionObserver before animating | | replay | false | Re-animate when scrolling away and back | | hoverScale | 1.02 | Scale on chart hover | | tooltips | true | Show tooltip layer | | perPointTooltips | true | Hit targets on points / bars / rings | | countUp | true | Animate gauge/stat numbers | | countUpMs | 800 | Count-up duration (ms) | | observe | true | MutationObserver for late DOM injects | | selector | '[data-provchart]' | Root chart selector | | excludeSvg | true | Skip pure SVG embeds from generate-svg | | durationMs | 700 | Motion duration | | rootMargin | '40px' | IO root margin | | threshold | 0.15 | IO threshold |

What gets enhanced

| data-provchart | Behavior | |------------------|----------| | line, area, combo | Point hit-targets from CSS vars --pc-{id}-sN-pK; legend dimming | | bar, stackedbar | Bar hover values from height % | | hbar | Row label + value tooltips | | scatter | Circle hover (value from cy) | | gauge | Ring/card tooltip; center % count-up (multi-ring HTML gauges included) | | stat | Value count-up when present |

Not enhanced (by design when excludeSvg: true):

• Standalone SVG from POST /api/v1/generate-svg (README/docs embeds)
• Raw <svg> roots without ProvChart HTML structure

HTML gauges that use data-provchart="gauge" are enhanced.

Markup contract

Runtime expects ProvChart-style roots, for example:

<div class="pc-chart-3-abcd" data-provchart="line">
  <div class="pc-chart-area">...</div>
  <div class="pc-chart-3-abcd-legend">...</div>
</div>

Point data for line/area tooltips is read from computed CSS variables:

--pc-{id}-s{series}-p{index}

(values as % from the top; runtime maps to a 0–100 style reading).

SPA / framework usage

The observer picks up most injects. After React/Vue/Svelte commits, you can force a scan:

window.ProvChartRuntime?.refresh();
// or scope:
window.ProvChartRuntime?.refresh(document.getElementById('dashboard'));

API

window.ProvChartRuntime.version;   // e.g. "2.2.0" (package may lag — check release)
window.ProvChartRuntime.scan();  // full document
window.ProvChartRuntime.enhance(el);
window.ProvChartRuntime.refresh(root?);
window.ProvChartRuntime.destroy(); // disconnect observers, remove tooltip

Accessibility & motion

• Tooltips use role="tooltip".
• prefers-reduced-motion: reduce disables transform/opacity transitions and hover scale.
• Prefer keeping a real data table next to charts for screen readers (Accessible charts guide).

ProvChart product links

• Site: chart.devtem.org
• Docs: chart.devtem.org/docs
• Gallery (runtime demo): chart.devtem.org/gallery
• Developer API: docs – API
• Open-source core: st-core.fscss

Generate charts:

POST https://provchart-api.devtem.org/api/v1/generate
X-API-Key: YOUR_API_KEY

Then enhance the returned HTML/CSS with this runtime on the client.

Browser support

Modern browsers with:

• MutationObserver
• IntersectionObserver (optional path if missing: reveal immediately)
• CSS custom properties

License

MIT © fscss-ttr / ProvChart ecosystem

ProvChart hosted product and API: DevTemple.

Contributing

Issues and PRs: github.com/fscss-ttr/provchart-runtime

Keep enhancements additive — do not require changes to ProvChart generate output unless coordinated with the core engine.