docs: add book recipe page and example for funnel and waterfall

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

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)
+        - [Funnel Charts](./recipes/basic_charts/funnel_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)

docs/book/src/recipes/basic_charts.md

@@ -14,4 +14,5 @@ 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)
+Funnel Charts | [![Funnel Charts](./img/funnel.png)](./basic_charts/funnel_charts.md)
+Waterfall Charts | [![Waterfall Charts](./img/waterfall.png)](./basic_charts/waterfall_charts.md)

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

@@ -0,0 +1,33 @@
+# Funnel Charts
+
+A funnel chart shows how a quantity narrows as it passes through a sequence of stages. It is a
+*containment* form: each stage is understood to be a subset of the one above it, and the band
+widths carry that claim — so it suits pipelines that genuinely nest, such as a conversion funnel.
+
+Stages are fed **upstream-first**: plotly draws index 0 at the top, which is the opposite of a
+plain category axis.
+
+`text_info` takes a `+`-joined flaglist, so a band can show its own value alongside its conversion
+from the previous stage (`"value+percent previous"`), the share of the first stage
+(`"percent initial"`), or the share of the total (`"percent total"`).
+
+For a sequence whose steps do *not* nest — independent totals, or contributions that can be
+negative — see [Waterfall Charts](./waterfall_charts.md) instead.
+
+The following imports have been used to produce the plots below:
+
+```rust,no_run
+use plotly::color::NamedColor;
+use plotly::common::{Marker, Orientation};
+use plotly::funnel::Connector as FunnelConnector;
+use plotly::{Funnel, Plot};
+```
+
+The `to_inline_html` method is used to produce the html plot displayed in this page.
+
+## Basic Funnel
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:basic_funnel}}
+```
+
+{{#include ../../../../../examples/basic_charts/output/inline_basic_funnel.html}}

docs/book/src/recipes/img/funnel.png

@@ -7,6 +7,7 @@ use plotly::{
         ColorScale, ColorScalePalette, DashType, Domain, Fill, Font, HoverInfo, Line, LineShape,
         Marker, Mode, Orientation, Pattern, PatternShape,
     },
+    funnel::Connector as FunnelConnector,
     icicle::{
         BranchValues as IcicleBranchValues, Leaf as IcicleLeaf, Marker as IcicleMarker,
         PathBar as IciclePathBar, Side as IcicleSide, Tiling as IcicleTiling,
@@ -31,8 +32,8 @@ use plotly::{
     },
     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, Waterfall,
+    Bar, Funnel, Icicle, Indicator, Parcats, Pie, Plot, Sankey, Scatter, ScatterPolar, Sunburst,
+    Table, Treemap, Waterfall,
 };
 use plotly_utils::write_example_to_html;
 use rand_distr::{Distribution, Normal, Uniform};
@@ -812,6 +813,59 @@ fn bar_chart_with_pattern_fills(show: bool, file_name: &str) {
 }
 // ANCHOR_END: bar_chart_with_pattern_fills
 
+// Funnel Charts
+// ANCHOR: basic_funnel
+fn basic_funnel(show: bool, file_name: &str) {
+    let trace = Funnel::new(
+        vec![100, 60, 40, 25],
+        vec!["Visits", "Signups", "Trials", "Purchases"],
+    )
+    .text_info("value+percent previous")
+    .connector(FunnelConnector::new().visible(true))
+    .marker(Marker::new().color(NamedColor::SteelBlue));
+
+    let layout = Layout::new().title("Conversion Funnel");
+    let mut plot = Plot::new();
+    plot.set_layout(layout);
+    plot.add_trace(trace);
+
+    let path = write_example_to_html(&plot, file_name);
+    if show {
+        plot.show_html(path);
+    }
+}
+// ANCHOR_END: basic_funnel
+
+// Waterfall Charts
+// ANCHOR: basic_waterfall
+fn basic_waterfall(show: bool, file_name: &str) {
+    let trace = Waterfall::new(
+        vec!["Start", "Revenue", "Costs", "End"],
+        vec![100.0, 40.0, -25.0, 0.0],
+    )
+    .measure(vec![
+        Measure::Absolute,
+        Measure::Relative,
+        Measure::Relative,
+        Measure::Total,
+    ])
+    .text_info("label+delta")
+    .increasing(MeasureStyle::new().marker(WaterfallMarker::new().color(NamedColor::SeaGreen)))
+    .decreasing(MeasureStyle::new().marker(WaterfallMarker::new().color(NamedColor::Tomato)))
+    .totals(MeasureStyle::new().marker(WaterfallMarker::new().color(NamedColor::SteelBlue)));
+
+    let layout = Layout::new().title("Basic Waterfall");
+    let mut plot = Plot::new();
+    plot.set_layout(layout);
+    plot.add_trace(trace);
+
+    let path = write_example_to_html(&plot, file_name);
+    if show {
+        plot.show_html(path);
+    }
+}
+// ANCHOR_END: basic_waterfall
+
 // Sankey Diagrams
 // ANCHOR: basic_sankey_diagram
 fn basic_sankey_diagram(show: bool, file_name: &str) {
@@ -1508,6 +1562,12 @@ fn main() {
 
     bar_chart_with_pattern_fills(false, "bar_chart_with_pattern_fills");
 
+    // Funnel Charts
+    basic_funnel(true, "basic_funnel");
+
+    // Waterfall Charts
+    basic_waterfall(true, "basic_waterfall");
+
     // Sankey Diagrams
     basic_sankey_diagram(false, "basic_sankey_diagram");
     custom_node_sankey_diagram(false, "custom_node_sankey_diagram");