autumn_plugin_d3/
lib.rs

1//! This crate adds D3.js charts to Autumn apps. It works with Maud and
2//! htmx.
3//!
4//! Add [`D3Plugin`] to the app. Put [`d3_stylesheet()`] and [`d3_script()`]
5//! in the page `<head>`. Then render a [`Chart`]:
6//!
7//! ```rust,no_run
8//! use autumn_plugin_d3::{Chart, D3Plugin, Format, Scale, Series, d3_script, d3_stylesheet};
9//! use autumn_web::prelude::*;
10//!
11//! #[get("/")]
12//! async fn index() -> Markup {
13//!     html! {
14//!         html {
15//!             head { (d3_stylesheet()) (d3_script()) }
16//!             body {
17//!                 (Chart::bar([("Apples", 30.0), ("Pears", 60.0)])
18//!                     .label("Fruit sold")
19//!                     .format(Format::integer()))
20//!                 (Chart::line([Series::new("Visits", [(0.0, 3.0), (1.0, 5.0)])])
21//!                     .label("Visits"))
22//!             }
23//!         }
24//!     }
25//! }
26//!
27//! # async fn run() {
28//! autumn_web::app()
29//!     .plugin(D3Plugin::new())
30//!     .routes(routes![index])
31//!     .run()
32//!     .await;
33//! # }
34//! ```
35//!
36//! # How it works
37//!
38//! - The crate contains [D3](https://d3js.org) 7.9.0 (ISC). It does not use
39//!   npm or a bundler. [`D3_ASSETS`] serves it under `/static/_plugins/d3/`
40//!   at hashed URLs with SRI.
41//! - The builder renders a `<figure data-d3="KIND">` with `data-d3-*`
42//!   attributes and a data table. `init.js` reads the attributes and draws
43//!   an SVG. You can also write the attributes by hand.
44//! - Without JavaScript, the table shows. When the chart is ready, the table
45//!   stays for screen readers only. The runtime updates it with the data.
46//! - `init.js` starts charts on load, after htmx swaps, and on each DOM
47//!   insertion. It redraws on resize and on attribute changes. It frees a
48//!   chart when its element leaves the document.
49//! - Your own scripts get `window.d3`, the `d3:ready` event, the
50//!   `el.autumnD3` handle, and `AutumnD3.register` for custom kinds.
51//!
52//! # Limits
53//!
54//! - Built-in kinds: bar, line, area, scatter, pie. Write other kinds in
55//!   JavaScript with `AutumnD3.register`.
56//! - The palette has 8 colors. More series repeat colors (the runtime
57//!   warns). Keep to 8 or fewer, or set [`Chart::colors`].
58//! - Bars and areas do not stack. There is one value axis.
59//! - `data-d3-src` loads same-origin URLs only.
60//! - Do not let user content keep `data-d3-*` attributes or
61//!   `id="AutumnD3"`. User markup could then start charts and load
62//!   same-origin URLs.
63
64mod assets;
65mod chart;
66mod data;
67mod error;
68mod plugin;
69mod script;
70
71pub use assets::{ASSETS_NAMESPACE, D3_ASSETS, D3_JS_INTEGRITY, D3_SOURCE, D3_VERSION};
72pub use chart::{
73    Area, Axes, Bar, BuiltIn, Chart, Curved, Custom, Kind, Legend, Line, Pie, Scatter, Xy,
74};
75pub use data::{Color, Curve, Datum, Format, Point, Scale, Series};
76pub use error::Error;
77pub use plugin::{D3Plugin, PLUGIN_NAME};
78pub use script::{d3_script, d3_stylesheet};
autumn_plugin_d3/lib.rs

autumn_plugin_d3/
lib.rs
