reactor-charts

Reactor Charts

The chart surface lives in Reactor.D3.Charts (full guide: docs/guide/charting.md). This skill is the AI-agent quick reference — chart-choice rules, the new *View extension points, and the a11y/accuracy rails you should keep on by default.

Choose the right chart first

Most "my chart looks bad" problems are wrong-chart problems, not styling problems. Cleveland & McGill's perceptual ranking (1984) — accuracy of graphical judgment, best to worst:

position on a common scale > position on non-aligned scales > length / direction / angle > area > volume > shading / color saturation

That ordering is why bars and dots win and why pies lose. Translate it into rules of thumb:

When the user asks for a pie chart, push back unless all four pie conditions hold. A sorted bar chart usually wins. (Few/Tufte say "almost never pie"; Cairo/Wilke allow the narrow case above. Default to "no" and concede when the conditions are met.)

Charts not yet exposed as top-level factories: Sankey, Treemap, Cluster dendrograms, partition/sunburst, stratified hierarchies. The math primitives exist in src/Reactor.Advanced/Charting/D3/Layout/ (Sankey.cs, Treemap.cs, Cluster.cs, Stratify.cs, TreeLayout.cs) and can be composed with D3Canvas + the d3 shape generators. If a user asks for one of these and isn't comfortable assembling D3 primitives directly, suggest filing a factory request rather than hand-rolling — the resulting chart will lack the shared accessibility surface.

The DSL — quick reference

LineChart (data, x, y)              // continuous line
BarChart  (data, x, y)              // vertical bars (always anchored at zero — see pitfalls)
AreaChart (data, x, y)              // filled area
PieChart  (data, value)             // slices summing to 100%
PieChart  (data, value)             // donut variant: chain .InnerRadius(40+)
    .InnerRadius(60)
TreeChart (root, children)          // hierarchical (org chart, file tree, taxonomy)
ForceGraph(nodes, links)            // network graph (dependencies, relationships)

Common fluent knobs (chain-call any subset):

.Title("Monthly Revenue")
.SeriesName("Revenue")
.Units(xUnits: "months", yUnits: "USD")
.AxisLabel(ChartAxisType.X, "Month")
.AxisLabel(ChartAxisType.Y, "Revenue (USD)")
.Width(600).Height(250)
.Stroke("#0078D4").StrokeWidth(2.5)
.Fill("#50C878")                                  // bars / area / pie slice baseline
.ShowGrid(true).ShowAxes(true)
.DataLabel((point, idx) => $"{point.Revenue:C}")  // string label per point
.Palette(ChartPalette.Categorical)                // Tier 1 curated palette (a11y-scanned)
.ChartBackground("#1E1E1E")                        // declare active bg → scopes A11Y_CHART_011

AxisLabel text and Title are reserved for labeling the chart, not labeling individual data points or ticks — for those, see the next two sections.

Make D3 do the work

Charts compose D3-style scales and generators internally. When you reach under the DSL hood (or hand-roll Canvas drawings), follow these:

• Scales map domain → range — never compute pixel positions by hand. A LinearScale from [min, max] to [plotLeft, plotRight] is the boundary between "data" and "pixels". Mixing them is the #1 source of "off by 5px" bugs.
• Pick the right scale type for the data. Linear for quantitative, log for exponential, time for dates, ordinal/band for categories. Linear- on-exponential hides patterns; log-on-linear inflates them.
• Always .nice() quantitative domains. Axis bounds should round to human-friendly numbers (0/100/200, not 13.7/187.4). Pair with .ticks(n) as a suggestion, not a hard count — D3 picks readable intervals.
• Reserve margins. Long y-axis labels and multi-line tick *View elements need gutter. The Bostock margin convention ({top, right, bottom, left}) is the safe default; if you customize tick labels (next section), measure the longest one and grow the margin.
• Don't reinvent the axis. The built-in axis generator handles tick selection, formatting, alignment, label rotation. Custom tick code is where charts go to die.

When string labels aren't enough — *View

Three cases the string-label APIs (DataLabel, AxisLabel, LabelAccessor) can't handle:

1. The label needs an icon next to or inside the text.
2. The label needs multi-line text, wrapping, or different colors / weights per fragment.
3. The label needs to render a mini sub-tree (badge, sparkline, mini button, anything Reactor can build).

For these, reach for the *View extensions. They take a render delegate and substitute its returned Element for the built-in TextBlock at the same anchor position:

// Pie slice: replace text label with arbitrary element rendered at the slice centroid
PieChart(data, d => d.Value)
    .LabelView((d, layout) => HStack(
        FontIcon(IconForCategory(d.Category)).FontSize(12),
        TextBlock($"{layout.Fraction:P0}").FontWeight(FontWeights.SemiBold)));

// Axis tick: replace numeric tick label with arbitrary element
LineChart(data, x, y)
    .XTickLabelView(t => VStack(
        TextBlock(MonthName((int)t)).FontSize(11),
        TextBlock("month").FontSize(8).Foreground(Theme.SecondaryText)))
    .YTickLabelView(t => TextBlock($"${t:N0}").FontFamily("Cascadia Mono"));

PieChartElement<T>.LabelView(Func<T, PieSliceLayout, Element>)

The render delegate receives:

• T data — the slice's source data item.
• PieSliceLayout layout — a readonly record struct with everything you need to render a label that knows its slice geometry:
  • Index, Value, Fraction (0..1 of total)
  • CentroidX, CentroidY (absolute canvas coords — already applied via CenterAt, you don't need to apply them yourself)
  • StartAngle, EndAngle (radians, clockwise from 12 o'clock — d3 semantics)
  • InnerRadius, OuterRadius
  • Color — the resolved D3Color from the chart's palette, so your label can echo the slice color without a separate lookup.

The returned element is auto-anchored at the centroid via CenterAt. You do not need a known size at construction time; the reconciler recomputes position after layout from ActualWidth/ActualHeight.

ChartElement<T>.XTickLabelView(Func<double, Element>) and YTickLabelView

Same pattern for axis ticks. The delegate receives the tick's domain value (double); X labels are anchored horizontally centered on the tick mark, Y labels right-anchored to the axis edge and vertically centered.

Direct labeling vs legend vs tooltip

A label-placement decision tree (Tufte, Cleveland — direct labeling raises the data-ink ratio and avoids legend ping-pong):

1. Direct labels first. Label series at the end of each line, label pie slices on the chart, label bars above the bar. LabelView / *TickLabelView exist precisely so you can do this without re-templating the whole chart. Eyes don't ping-pong from line to legend; print works; screen readers work.
2. Use a legend only when direct labeling would collide — many series, tightly-packed lines, repeating palette across small multiples. Treat it as a fallback, not a default.
3. Use a tooltip for precise values on dense data, in addition to — never instead of — direct labels or a legend. Tooltips fail print, screen readers, mobile-tap accuracy, and keyboard navigation.
4. Pie slices: large slices get inside-labels; small slices (<~5%) need outside leader lines or get rolled into "Other". Don't label tiny slices inline — they overlap.
5. Backfire cases: dense scatterplots, tightly-packed bars, many overlapping line endpoints. Label collisions there are worse than a legend; switch to legend.

Anchor primitive (used by *View internally)

The *View methods are built on Canvas's anchor extensions (CanvasExtensions.cs). You'll rarely call them directly, but if you need to position arbitrary content on a Reactor Canvas without knowing its size at build time (overlay markers, custom callouts), use these:

.Canvas(left, top, anchorX, anchorY)   // 0..1 fractions of rendered size
.CenterAt(x, y)                        // sugar for anchor (0.5, 0.5)

The reconciler subscribes once to Loaded + SizeChanged per anchored element and recomputes Canvas.Left/Top as target − anchor × ActualWidth/Height. Zero-anchor (0, 0) is the legacy fast path with no subscription overhead.

Accessibility — beyond the framework defaults

Charts implement IChartAccessibilityData, which exposes axis ranges, units, point values, and (for pie) slice descriptors via UIA. Don't disable that. Beyond that, your responsibilities:

• Color is never the sole channel (WCAG 1.4.1). Pair color with shape, pattern, dash style, or — best — a direct text label. Useful for series identification when the user can't distinguish two of your colors.
• Color-blind-safe palettes. Use ChartPalette.Categorical (Reactor's curated set; Okabe-Ito-style). Avoid red/green pairings. Avoid rainbow for ordinal data — use a sequential ramp (Viridis-style) instead.
• Contrast. WCAG 1.4.11 — 3:1 for non-text essential graphics, 4.5:1 for text labels. The default chart palette meets this against the framework's surface tokens; if you override with .Stroke("#…") / .Fill("#…"), check contrast against Theme.SurfaceBackground.
• Custom colors & the scanner. Three tiers, in order of safety: .Palette(ChartPalette.Categorical) (Tier 1, curated) and .SeriesColors(…) (Tier 3, your own colors) are both contrast-checked by the a11y scanner (A11Y_CHART_011). .RawColors(…) (Tier 4) is an escape hatch that bypasses the check and itself trips the A11Y_CHART_012 info. A pie chart's low-level .SetColors(…) colors are the slices it actually draws, so they are scanner-visible too — validated as a Tier-3 custom palette. When a pie sets both .SetColors(…) and .Palette(…), the rendered .SetColors(…) colors are the ones scanned.
• Declare the background you render on. A11Y_CHART_011 is theme-agnostic by default, so it can only flag a custom color against either fixed light/dark background as an info. Call .ChartBackground("#1E1E1E") (also takes a D3Color or Windows.UI.Color) to scope the check to the single background the chart actually renders on — the finding becomes an actionable warning with a real, contrast-hardened fix, and palettes that are fine on their actual background stop being flagged.
• Screen-reader fallback. UIA structured data is good but not enough for screen-reader-only users — a hidden, expandable data table next to the chart is the pattern Tenon and the W3C WAI accessibility guidance recommend. Build it from the same data the chart consumed.
• Keyboard nav. Data points should be focusable in reading order, and focus should announce category + value. The IChartAccessibilityData surface drives this; if you turn the chart Interactive(false) you lose it — keep it on unless there's a reason.
• *View defaults. Custom labels are non-interactive by default: the chart force-applies AccessibilityView=Raw to the entire realized subtree (not just the outer wrapper) and clears IsTabStop on every inner control, so no inner peer surfaces to UIA and nothing inside the label joins the tab order. Prefer keeping the string LabelAccessor (PieChart) or DataLabel (line/bar/area) set — those feed UIA. When the visual lives entirely in the *View, pass name: (a Func<T,string> for pie / Func<double,string> for ticks) so the accessible name matches the visible label instead of falling back to Slice {n}. Set interactive: true only when the label has focusable children that must stay reachable — then you own its accessibility. Signatures: LabelView(render, name: null, interactive: false), XTickLabelView(render, name: null, interactive: false), YTickLabelView(render, name: null, interactive: false).

Common pitfalls — refuse to ship these

The most-cited visualization mistakes (Tufte, Few, Cairo, Wilke). If a user asks for one, push back with the alternative.

• Truncated bar baselines. Bars MUST start at zero. A 3% gap with a truncated baseline visually looks like 300%. Cairo's How Charts Lie spends a chapter on this. Line charts may truncate because shape, not height, conveys meaning — bars never.
• Dual y-axes. Fabricates correlation between unrelated series. Use two small multiples or normalize both series to an index (e.g. (value / baseline) × 100) so they share a single axis.
• 3D / exploded pies, drop shadows, gradients on bars. Tufte's "chartjunk." 3D pies are actively misleading — angle distortion changes the visual proportion of slices.
• Too many series. >5–7 lines, >7 pie slices. Group the tail into "Other" or split into small multiples.
• Rainbow / unordered categorical palettes on ordinal data. When the variable has order (low/medium/high, age buckets, sentiment), use a sequential ramp. A categorical palette implies "different kind", not "different magnitude".
• Pie chart for ranking. Pies hide rank — angle judgments are imprecise. A sorted bar chart shows it directly.

When to reach for *View (and when not to)

Reach for it when:

• You need an icon-plus-text axis tick or slice label.
• You need to render the slice percent in the slice itself instead of a side legend (direct labeling, see above).
• You're embedding a chart in a dashboard whose typography contract demands fonts/colors the built-in ChartAxis style doesn't match.

Skip it when a string works:

• Plain numeric formatting → DataLabel((d, i) => d.Value.ToString("C")).
• Custom number-to-string for ticks → built-in tick formatting (Fmt(t) handles short numbers cleanly).
• Just changing color/font of a built-in label — that's not exposed yet; if you need it, file an issue rather than dropping to *View for a one-property override.

Reading list

• docs/guide/charting.md — full user-facing chart guide.
• src/Reactor.Advanced/Charting/Charts.cs — ChartElement<T> / PieChartElement<T> fluent API. *View methods sit near the bottom of each class.
• src/Reactor.Advanced/Charting/Charts.Tree.cs — TreeChart and ForceGraph factories + their elements.
• src/Reactor.Advanced/Charting/D3Charts.cs — d3 primitives (D3Pie, D3Axes, D3Grid, D3Canvas). D3Axes is where the optional xTickLabel / yTickLabel delegates plug in.
• src/Reactor.Advanced/Charting/D3/Layout/ — composable layout algorithms (Sankey.cs, Treemap.cs, Cluster.cs, Stratify.cs, TreeLayout.cs). No top-level factory wrapping these yet; they're the building blocks for one when the time comes.
• src/Reactor/Elements/CanvasExtensions.cs — CenterAt and the anchor overload of Canvas.

External (read these once if charting is new to you):

• Cleveland & McGill (1984), Graphical Perception — the perceptual ranking.
• Edward Tufte, The Visual Display of Quantitative Information — data-ink ratio, chartjunk.
• Stephen Few, Show Me the Numbers — practitioner playbook for business charts.
• Claus Wilke, Fundamentals of Data Visualization — free online; the modern reference.
• Alberto Cairo, How Charts Lie — the pitfalls chapter is required reading.
• d3js.org docs on d3-scale, d3-axis, d3-shape — even when working through Reactor's wrappers.