autumn-plugin-d3

D3.js charts for Autumn apps (autumn-web 0.10). Write charts in Rust. Get SVG charts that work with htmx, with the default CSP, and without JavaScript.

• No npm, no bundler, no inline script. The crate serves D3 7.9.0 with SRI.
• Typed builder: bar, line, area, scatter, pie/donut, custom kinds.
• Data table in every chart: it shows without JavaScript and stays for screen readers.
• Tooltips by pointer and keyboard. Legend. Light and dark palette.
• Live data: same-origin JSON with optional refresh.

Quickstart

[dependencies]
autumn-plugin-d3 = "0.3"

use autumn_plugin_d3::{Chart, D3Plugin, Format, d3_script, d3_stylesheet};
use autumn_web::prelude::*;

#[get("/")]
async fn index() -> Markup {
    html! {
        html {
            head { (d3_stylesheet()) (d3_script()) }
            body {
                (Chart::bar([("Apples", 30.0), ("Pears", 60.0), ("Plums", 15.0)])
                    .label("Fruit sold")
                    .y_label("Units")
                    .format(Format::integer()))
            }
        }
    }
}

#[autumn_web::main]
async fn main() {
    autumn_web::app()
        .plugin(D3Plugin::new())
        .routes(routes![index])
        .run()
        .await;
}

Chart kinds

Kind options compile only on their kinds. For example, Chart::bar(..).donut(0.5) does not compile. y_min and y_max apply to all kinds except pie. legend applies to line, area, scatter, and pie.

A non-finite value (NaN, ±∞) is a missing value. Bars skip it. Lines show a gap. With Scale::Time, x is Unix time in milliseconds. Repeated labels or series names draw as separate marks.

Common options

Format maps to d3-format: integer(), decimal(n), percent(n), si(n), currency(n), or d3("spec"). The runtime ignores a bad specifier or a width above 64.

Hand-written markup

The builder only writes attributes. This markup works too:

<figure data-d3="bar" data-d3-data='[["a", 1], ["b", 2]]' data-d3-label="Hand">
  <div class="d3-table"></div>
</figure>

An empty div.d3-table is optional. The runtime fills it with the data table, and updates it when the data changes.

Data shapes: [{"label": "a", "value": 1}] or [["a", 1]] for bar and pie; [{"name": "s", "points": [[x, y]]}] for line, area, and scatter. An x value can also be a numeric string or an ISO 8601 date string (no zone means UTC). null is a missing value.

htmx and live data

init.js starts charts after htmx swaps and frees charts that leave the page. A change to data-d3-data animates the chart to the new data. A change to another data-d3-* attribute rebuilds the chart.

// The handler returns Vec<Datum> or Vec<Series> as JSON.
#[get("/api/sales.json")]
async fn sales() -> Json<Vec<Datum>> { Json(load_sales()) }

// The chart loads it, then loads it again every 5 s.
(Chart::<Bar>::from_src("/api/sales.json").refresh(Duration::from_secs(5)))

Custom kinds and JavaScript

Load your script after d3_script(), with defer. Do not inline it.

(d3_script())
script src=(asset_url("js/charts.js")) defer {}
// ...
(Chart::custom("sparkline")?.json(&values)?.label("Trend"))

// static/js/charts.js
AutumnD3.register("sparkline", ({ d3, svg, width, height, data, color }) => {
  const x = d3.scaleLinear([0, data.length - 1], [0, width]);
  const y = d3.scaleLinear(d3.extent(data), [height, 0]);
  svg.append("path").attr("d", d3.line((_, i) => x(i), y)(data))
    .style("fill", "none").style("stroke", color(0));
});

The runtime clears the SVG before each draw of a custom kind. Use the style() method for styles (CSSOM). Do not set style attributes. Data can come from untrusted markup: write text with .text(), never .html().

Theme

Set these custom properties on the chart element, for example .sales { --d3-color-1: #0a7; }. The defaults use :where(), so your rules win.

Add class d3-show-table to keep the data table visible.

Accessibility

• Each chart has a data table. It shows without JavaScript and on error. When the chart is ready, it stays for screen readers only.
• The SVG has role="img" and a name. When it has values, it is a tab stop: arrow keys, Home, and End move a tooltip, and a live region reads the value. Escape closes the tooltip.
• A legend shows for two or more series. The palette has 8 colors.
• Reduced motion turns transitions off. Forced colors keep series colors.

Gotchas

• CSP. Do not inline <script> or <style>. Put page scripts in static/ and load them with defer after d3_script().
• One D3. Use window.d3. Do not load a second copy.
• htmx in nonce mode. htmx adds an inline <style>. Set <meta name="htmx-config" content='{"includeIndicatorStyles":false}'>.
• Big data. Large inline data makes large HTML. Use src.
• User content. Remove data-d3* attributes and id="AutumnD3" from user HTML. Else user markup can start charts and load same-origin URLs.
• Refresh. After a failure, the wait doubles (up to 5 min). While the tab is hidden, refresh stops.

Demo

cargo run --example d3_demo
# then open http://127.0.0.1:3000

Development

See CLAUDE.md for commands, and docs/plan.md and docs/adr/ for the design.

License

Apache-2.0 for the plugin. D3 is ISC (assets/D3-LICENSE).