feat(traces): add Waterfall trace type

plotly.js has shipped the `waterfall` trace since well before the bundled
3.7.0 build — only the Rust wrapper was missing. It registers with the
same categories as `funnel` (bar-like, cartesian, svg, oriented), so it
composes with subplot grids and static image export. The layout-level
`waterfallmode`/`waterfallgap`/`waterfallgroupgap` attributes and the
`WaterfallMode` enum already existed; this fills in the trace.

Field set is exactly the attributes plotly.js declares in `waterfall`'s
own block, plus the base-trace attributes `Bar` already carries, minus
the date-axis period family — `xperiodalignment` needs a
`PeriodAlignment` enum that does not exist yet, and waterfall's position
axis is categorical in practice. Consequently `base` is scalar
(`arrayOk: false` here, unlike `Bar`), there is no top-level `marker`,
and error bars, calendars and point selection are absent.

`measure` is a typed enum but `textinfo` stays a plain `String`, and the
difference is the schema's: `textinfo` is a `flaglist`, an open-ended
`+`-joined set, so it follows the existing `pie.rs`/`funnel.rs`
precedent. `measure` is a `data_array` whose entries plotly.js validates
against a closed set, silently treating anything it does not recognise
as `relative` — a typo there renders a different chart rather than
raising an error, which is what earns it a type.

Bar colours come from `increasing`/`decreasing`/`totals` rather than a
per-point array, because plotly.js declares every attribute in those
blocks `arrayOk: false`; all three share one `MeasureStyle`/`Marker`
pair since the schema generates them from a single helper. `Connector`
is waterfall's own — it has no `fillcolor` and gains a `ConnectorMode`,
so `funnel::Connector` is not reusable.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrei Gherghescu <8067229+andrei-ng@users.noreply.github.com>

Author: 2 people

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 - [[#414](https://github.com/plotly/plotly.rs/issues/414)] Add `DensityMap` (MapLibre `map` subplot) trace type — density heatmaps with full color-scale and hover support
 - [[#417](https://github.com/plotly/plotly.rs/issues/417)] Add `ScatterMap` (MapLibre `map` subplot) trace type — the modern counterpart to `ScatterMapbox`
 - Add `Funnel` trace type (bar-like, cartesian) with `Connector` and `FunnelHoverInfo` options, plus the layout-level `funnelmode`/`funnelgap`/`funnelgroupgap` attributes and a `FunnelMode` enum
+- Add `Waterfall` trace type (bar-like, cartesian) with a typed `Measure` enum (`absolute`/`relative`/`total`), per-class `increasing`/`decreasing`/`totals` styling via `MeasureStyle`, a `Connector` with `ConnectorMode`, and a `WaterfallHoverInfo` enum. The layout-level `waterfallmode`/`waterfallgap`/`waterfallgroupgap` attributes and the `WaterfallMode` enum already existed
 - [[#418](https://github.com/plotly/plotly.rs/issues/418)] Add native point clustering to `ScatterMap` via a `Cluster` option
 - [[#421](https://github.com/plotly/plotly.rs/pull/421)] Backfill trace attributes for trace types to bring them to parity with  plotly.js 3.7 
 - [[#422](https://github.com/plotly/plotly.rs/issues/422)] Add `Indicator`, `Histogram2d`, `Icicle` trace types 

docs/book/src/SUMMARY.md

@@ -19,6 +19,7 @@
         - [Parallel Categories](./recipes/basic_charts/parcats_charts.md)
         - [Treemap Charts](./recipes/basic_charts/treemap_charts.md)
         - [Sunburst Charts](./recipes/basic_charts/sunburst_charts.md)
+        - [Waterfall Charts](./recipes/basic_charts/waterfall_charts.md)
         - [Icicle Charts](./recipes/basic_charts/icicle_charts.md)
         - [Indicator Charts](./recipes/basic_charts/indicator_charts.md)
     - [Statistical Charts](./recipes/statistical_charts.md)

docs/book/src/recipes/basic_charts.md

@@ -14,3 +14,4 @@ Treemap Charts | [![Treemap Charts](./img/treemap.png)](./basic_charts/treemap_c
 Sunburst Charts | [![Sunburst Charts](./img/sunburst.png)](./basic_charts/sunburst_charts.md)
 Icicle Charts | [![Icicle Charts](./img/icicle.png)](./basic_charts/icicle_charts.md)
 Indicator Charts | [![Indicator Charts](./img/indicator.png)](./basic_charts/indicator_charts.md)
+Waterfall Charts | [Waterfall Charts](./basic_charts/waterfall_charts.md)

docs/book/src/recipes/basic_charts/waterfall_charts.md

@@ -0,0 +1,28 @@
+# Waterfall Charts
+
+A waterfall chart shows how a running total is built up from a starting value and a
+sequence of signed contributions. Each bar's role is set by its `Measure`:
+
+- `Measure::Absolute` resets the running total and draws a bar from zero to it,
+- `Measure::Relative` adds a signed delta, drawn as a floating bar,
+- `Measure::Total` draws the running total accumulated so far.
+
+The value supplied for a `Total` bar is ignored — plotly.js re-derives it — but the slot
+must still be present, because the label, value and `measure` arrays are read positionally.
+
+The following imports have been used to produce the plots below:
+
+```rust,no_run
+use plotly::color::NamedColor;
+use plotly::waterfall::{Marker as WaterfallMarker, Measure, MeasureStyle};
+use plotly::{Plot, Waterfall};
+```
+
+The `to_inline_html` method is used to produce the html plot displayed in this page.
+
+## Basic Waterfall
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:basic_waterfall}}
+```
+
+{{#include ../../../../../examples/basic_charts/output/inline_basic_waterfall.html}}

examples/basic_charts/src/main.rs

@@ -30,8 +30,9 @@ use plotly::{
         Align as TableAlign, Cells, Fill as TableFill, Font as TableFont, Header, Line as TableLine,
     },
     treemap::{BranchValues, Marker as TreemapMarker, Packing, PathBar, Side, Tiling},
+    waterfall::{Marker as WaterfallMarker, Measure, MeasureStyle},
     Bar, Icicle, Indicator, Parcats, Pie, Plot, Sankey, Scatter, ScatterPolar, Sunburst, Table,
-    Treemap,
+    Treemap, Waterfall,
 };
 use plotly_utils::write_example_to_html;
 use rand_distr::{Distribution, Normal, Uniform};

plotly/src/common/mod.rs

@@ -243,6 +243,7 @@ pub enum PlotType {
     Treemap,
     Sunburst,
     Violin,
+    Waterfall,
 }
 
 #[derive(Serialize, Clone, Debug)]

plotly/src/lib.rs

@@ -62,14 +62,14 @@ pub use plot::{Plot, Trace, Traces};
 pub use traces::{
     box_plot, choropleth, choropleth_map, contour, density_map, funnel, heat_map, histogram, histogram2d,
     icicle, image, indicator, mesh3d, parcats, sankey, scatter, scatter3d, scatter_map,
-    scatter_mapbox, splom, sunburst, surface, treemap, violin,
+    scatter_mapbox, splom, sunburst, surface, treemap, violin, waterfall,
 };
 // Bring the different trace types into the top-level scope
 pub use traces::{
     Bar, BoxPlot, Candlestick, Choropleth, ChoroplethMap, Contour, DensityMap, DensityMapbox,
     Funnel, HeatMap, Histogram, Histogram2d, Icicle, Image, Indicator, Mesh3D, Ohlc, Parcats, Pie, Sankey,
     Scatter, Scatter3D, ScatterGeo, ScatterMap, ScatterMapbox, ScatterPolar, Splom, Sunburst,
-    Surface, Table, Treemap, Violin,
+    Surface, Table, Treemap, Violin, Waterfall,
 };
 
 pub trait Restyle: serde::Serialize {}

plotly/src/traces/mod.rs

@@ -32,6 +32,7 @@ pub mod surface;
 pub mod table;
 pub mod treemap;
 pub mod violin;
+pub mod waterfall;
 
 pub use bar::Bar;
 pub use box_plot::BoxPlot;
@@ -64,5 +65,6 @@ pub use surface::Surface;
 pub use table::Table;
 pub use treemap::Treemap;
 pub use violin::Violin;
+pub use waterfall::Waterfall;
 
 pub use self::image::Image;