Add total labels for stacked bar and area charts

[kuzmadom]

Problem

Stacked bar and area charts can show labels for individual series and totals in the tooltip, but they cannot show an always-visible total for the whole stack.

This is useful when the segments represent an analytical breakdown: users need to see both each segment's contribution and the absolute total without hovering.

The current workaround is to calculate totals outside the chart and attach them to the expected top series. It breaks when visibility, missing values, sorting or stack composition changes.

Proposal

Add plugin-specific stackLabels settings to series.options['bar-x'], series.options['bar-y'] and series.options.area:

interface StackLabelsOptions {
  enabled?: boolean;
  format?: ValueFormat;
  style?: Partial<BaseTextStyle>;
  padding?: number;
  allowOverlap?: boolean;
}

series: {
  data: stackedAreaSeries,
  options: {
    area: {
      stackLabels: {
        enabled: true,
        format: {type: 'number', precision: 0},
      },
    },
  },
}

stackLabels.enabled should default to false.

Aggregation is intentionally fixed to sum, because it is the value represented by the stack geometry. format changes only its presentation.

Expected behavior

• Render one label per X value and visible stack, grouped by stackId, plot and value axis. Recalculate it after legend or data changes.
• Sum raw numeric values. For stacking: 'percent', show the raw total rather than 100, so percentage contributions and the absolute total can be read together.
• Place bar totals beyond the stack end and area totals on the outer cumulative boundary.
• If a stack has both signs, show separate positive and negative totals at their respective ends instead of an ambiguous net value.
• Keep total labels independent from series dataLabels and do not create synthetic series, legend items or tooltip rows.

Architecture

Keep the behavior inside the bar-x, bar-y and area plugins. Do not add it to BaseDataLabels or introduce shared series-type checks.

A total belongs to multiple series, so its settings should live in the plugin options rather than on one series. Each plugin already groups data by stackId and calculates stack geometry; derive totals from that same data so labels match rendered gaps, normalization and visibility.

Reuse ValueFormat, getFormattedValue and the existing label layout utilities. Prepare stack labels separately from the top series, which can change at runtime. Do not reuse tooltip custom aggregation: tooltip totals are not anchored to chart geometry.

Edge cases and tests

Add unit and visual coverage for:

• normal and percent stacking in bar-x, bar-y and area;
• legend changes, multiple stackId values, plots and value axes;
• missing, null and zero values, including a single visible series;
• positive, negative and mixed-sign stacks;
• dense or irregular area points, gaps and zoom;
• overlap, plot bounds, coexistence with series labels and ValueFormat variants.

Add a Storybook example and document the option in the Data Labels and Value Formatting guides.

Creating a separate aggregate line or bar series, custom aggregation methods, and per-stackId styling are outside the scope of this issue.

Related APIs and requests

• Highcharts yAxis.stackLabels and ApexCharts bar totals support this for stacked bars.
• Power BI total labels are available for stacked and area charts; users also ask for density control on stacked-area totals.
• Requests for an average or custom measure exist, but Power BI handles them through a separate line/measure rather than another stack-total aggregation mode.
• ECharts users request stack totals and legend-aware recalculation, currently emulating them with an invisible series.