docs: add plotly gallery examples for the experimental trace types

[jooyoungseo]

What

Adds gallery examples for the experimental plotly trace types. docs/examples-plotly.qmd previously had no experimental types at all — thirteen readings the package supports with nowhere a user could see them work.

New ## Experimental Plot Types section with 14 chunks across 12 subsections, carrying one prototype callout for the whole block rather than repeating it per type.

Section	Written as	Read as
Waterfall Chart	go.Waterfall	waterfall
Funnel Chart	go.Funnel	funnel
Gauge	go.Indicator	gauge
Sankey Diagram	go.Sankey	sankey
Hierarchy Charts	go.Treemap / go.Sunburst / go.Icicle	treemap / sunburst / icicle
Parallel Coordinates	go.Parcoords	parallel_coordinates
Alluvial Diagram	go.Parcats	alluvial
Choropleth Map	go.Choropleth	choropleth
Polar Area Chart	go.Barpolar	polar_area
Radar Chart	go.Scatterpolar	radar
100% Stacked Bar Chart	barnorm="percent"	stacked_normalized_bar
Contour Plot	go.Contour	contour

Not the usual x-against-y

Several of these have no series to walk in the ordinary sense, so each section says what a reader actually gets rather than assuming left/right over points. A gauge is one value against the range that bounds it. A sankey is flows between named nodes. A hierarchy is nodes each carrying a path of ancestors.

Measured, not asserted

Every chunk was extracted from the committed file and executed against an installed build:

Waterfall Chart        waterfall                n=5
Funnel Chart           funnel                   n=4
Gauge                  gauge                    n=5
Sankey Diagram         sankey                   n=4
Hierarchy Charts       treemap / sunburst / icicle   n=6 each
Parallel Coordinates   parallel_coordinates     n=4
Alluvial Diagram       alluvial                 n=3
Choropleth Map         choropleth               n=4
Polar Area Chart       polar_area               n=1
Radar Chart            radar                    n=1, n=1
100% Stacked Bar       stacked_normalized_bar   n=2
Contour Plot           contour                  n=11
FAILURES: 0

Two claims came out of that pass rather than from assumption:

• A waterfall's measure= is resolved to what the bar does. A relative bar is not announced as "relative" — it becomes an increase or a decrease from its sign, and each point carries start, end and delta. The section gives the measured five-bar table.

• Treemap, sunburst and icicle produce byte-identical readings. Same node list, same values, same path. They share one section because the choice between them is a visual one and should not change what a reader is told.

Also confirmed rather than assumed: barnorm="percent" really does announce shares — raw inputs of 30 against 10 come through as 75 and 25, not as the inputs.

Deliberately absent

The 100% stacked area is not here. A plotly groupnorm area emits raw values under a stacked_normalized_area type (#691), so an example would present that as intended behaviour. Worth adding once that is fixed.

Checked for overlap first

Before writing, I grepped the existing page's content — not just its headings — for every type below. The only near-hit was the word "percent" in the Pie section, which is about pie percentages. None of these duplicates existing coverage.

That check exists because the previous PR (#690) shipped a stacked area section that duplicated the existing "Area Plot" section, which I had missed by enumerating headings without reading them. The heading there is named for the function family rather than the type, so the name never matched.

This is a docs-only change; no package code is touched.

---

Generated by Claude Code

[github-actions]

Review

Went through the diff, cross-checked the doc's technical claims against the actual maidr/plotly/*.py extraction code (waterfall measure resolution, sankey label lookup, hierarchy path-building, parcats aggregation, barnorm math, gauge threshold/range, contour levels, radar/polar-area dispatch), and hand-traced every example's data through that code. This is unusually well-verified documentation — every one of those claims (the waterfall's 420→510→555→495 table, the alluvial's 5-rows-into-3-flows counts, the 75%/25% barnorm shares, the treemap path chain) matches the implementation exactly. Nice work grounding the prose in measured behavior rather than assumption, and checking the existing page's content (not just headings) to avoid the #690 duplication.

Bug: Choropleth example's locationmode doesn't match its locations

go.Choropleth(
    locations=["USA", "CAN", "MEX", "BRA"],
    z=[331, 38, 128, 214],
    locationmode="country names",
    colorbar={"title": "Population (m)"},
)

"USA", "CAN", "MEX", "BRA" are ISO-3 codes, but locationmode="country names" tells plotly to match locations against full English country names (e.g. "United States"), not ISO-3 codes. Under that mode these four strings won't resolve to any region, so the rendered map will most likely come back blank/unshaded — the opposite of what locationmode's default ("ISO-3") would have given for free.

The repo's own tests/plotly/test_plotly_choropleth.py:47-51 pairs this exact code style with locationmode="ISO-3":

COUNTRIES = go.Choropleth(
    locations=["USA", "CAN", "MEX"],
    z=[10, 20, 30],
    locationmode="ISO-3",
    ...
)

Since maidr's extraction reads trace.locations/trace.z directly (choropleth.py), the generated accessible JSON/sonification would still be correct regardless of locationmode — but the visual map next to it (what a sighted reader sees, and what the fig-alt describes as a shaded map of four countries) would likely render empty. Given the PR description's "measured, not asserted" standard for the rest of the examples, this one slipped through — probably because the schema-level test harness doesn't care about locationmode at all, so it wouldn't have surfaced there. Suggest either dropping locationmode (ISO-3 is the default and matches these codes) or switching to locationmode="ISO-3" explicitly to match the test convention.

Everything else

• All 14 code chunks use valid plotly graph_objects/express API shapes (measure/y length alignment on the waterfall, None sentinel for the total bar, gauge={"threshold": {...}} nesting, barnorm as a post-hoc update_layout call).
• docs/stability.qmd already lists all 23 experimental types used here — no drift introduced, no update needed there.
• Formatting conventions (#| warning: false, #| fig-alt:, #<< markers, single callout for the whole section) are consistent with the rest of examples-plotly.qmd and with stability.qmd's own "Prototypes" callout wording.
• Docs-only change, so no unit test coverage needed per the repo's conventions — but consider a quarto render pass (or at least eyeballing the rendered choropleth) before merge, since that's the one example likely to visually misrender.

Nice, thorough PR overall — just the one locationmode fix needed.