GrChartArea

• the whole and the contribution of its parts over time — revenue by channel, traffic by source, time by stage: stacked lays every series on the sum of the previous ones;
• a single series whose volume matters — a fill down to zero reads as “how much in total” rather than “at what level”;
• shares changing over time — stacked: '100%' normalises every position to one, and the redistribution is visible rather than the growth;
• series that have to show through — when overlaid without stacking, fill: 'auto' gives a gradient, and the lower series stays visible.

With more than seven or eight categories a stack stops being readable: the bands become thinner than their labels, and they can no longer be compared by eye. That is a sign that GrChartBar with grouping is needed, or fewer series.

The body of the chart can be drawn in two ways. Below the threshold it is SVG, above it a <canvas>; the component chooses itself, and there is no “which renderer” prop.

The threshold is counted in drawn vertices rather than in points — canvasThreshold, 24,000 by default. The difference is substantial: decimation cuts every series down to the limit of the screen (about two vertices per pixel), so one series of a hundred thousand points is drawn as 2,400 vertices and costs milliseconds, while twenty series of 2,400 — the same 48,000 points — cost sixteen, that is, a whole frame.

The measured numbers at a width of 1200px, 2,400 vertices per series:

canvasThreshold: 0 switches the canvas off entirely — for the case where the drawing has to stay vector: printing, an SVG export, CSS of your own over the marks.

Accessibility does not change at all with the change of renderer. The cursor, the keyboard, the tooltip and the hidden table work with the overlay and with the full series rather than with the marks: the canvas does not exist for them, it is aria-hidden and does not catch the pointer. That was the condition on which a second renderer was allowed at all.

What the canvas draws differently. The grid moves into it as well: the canvas lies under the <svg> so that the axes and the active point stay on top — and the grid has to stay under the series. In an area chart the gradient fill becomes solid: the canvas does not understand url(#…), and across twenty areas a gradient reads as a mess anyway.

fill: 'auto' means a gradient for an overlay and a dense fill for a stack. The reason is different in each case: overlaid series need to show through one another, while the bands of a stack stand flush, and a gradient would blur the boundary between two neighbours — that is, the very place where one part ends and another begins.

In a stack the bounds of the band arrive on a point as separate fields, but its own y is not touched. The tooltip, the hidden table and the live region say “partners — one hundred and ninety” rather than “six hundred and fifty, because retail lies underneath”.

A hidden series drops out of the stack, and the ones above it come down. The value axis is computed from the tops of the bands and always includes zero: a stack from a non-zero base lies about the proportions.

A stack is built from the full series. A gap is the only place where it is not entirely honest: the sum at that position is understated. Carrying the last known value forward would be worse — that would be drawing data that did not exist.

stacked: true shows the quantities and their sum, and stacked: '100%' only the distribution: the sum at every position equals one, and the band says how the shares changed rather than how much there was in total. One question has to be chosen: the reader does not know whether to compare the heights of the bands or their shares.

What is normalised is the drawing, not the data. The axis moves to percentages, while the tooltip, the hidden table and the live region still name the absolute quantities. A position with a zero sum has nothing to normalise against — there there is a zero rather than a NaN.

decimate: 'auto' (the default) thins out the vertices of the path when there are more points than the screen can show. In a stack the set of abscissas is shared across all of the series — otherwise the bottom of the upper band would be interpolated over one set of X values and the top of the lower one over another, and the fill would come apart at the seams. The cursor, the keyboard, the tooltip and the hidden table know the full series; the details — ../model.md, the section “Decimation is a projection, not the data”.

zoom switches the window on: 'brush' is a drag across the canvas, 'wheel' is the wheel, and 'both' is both. It is off by default.

<GrChartArea v-model:x-window="window" :series="series" zoom="both" />

<GrButton :disabled="window === null" @click="window = null">
The whole series
</GrButton>

The window selects the data rather than cropping the drawing: the positions, the cursor, the keyboard, the hidden table and the span of the value axis are computed from it. The practical consequence is that zooming reveals the fine structure that on the full series lies as a solid hatching: the decimation budget is computed from the width of the area, and there are fewer points in the window, so more vertices fall to each of them.

The keyboard works whenever zoom is on: +/- zoom towards the active point, Shift+arrows shift the window, and 0 returns the whole series. The union of the prop enumerates only pointer gestures — zooming has no switchable keyboard by design (../a11y.md, the section on zooming).

v-model:x-window is not mandatory — without a binding the chart zooms by itself. It is bound for something else: a synchronised pair of charts, a reset button next to the canvas, keeping the zoom in the address bar.

The bounds are accepted in the same form as the abscissas of the points (Date, an ISO string, a number) and go out as numbers. With a window set, activeIndex addresses it rather than the whole series.

The full data of the chart as rows — what a screen reader reads instead of the picture. By default dataTable: 'hidden': in the accessibility tree, invisible to the eye.

A row per point is readable while there are not many rows. The table therefore has a ceiling — dataTableMaxRows, 'auto' by default, that is, the budget of the drawing:

<GrChartArea :series="series" />                              <!-- auto: as drawn -->

<GrChartArea :series="series" :data-table-max-rows="200" />   <!-- a ceiling of your own -->

<GrChartArea :series="series" :data-table-max-rows="Infinity" /> <!-- always full -->

<GrChartArea :series="series" data-table="off" />             <!-- there is no table at all -->

Above the ceiling the table prints the same points that are drawn and says so with a note in the footer. The point-by-point completeness is not lost in the process: the arrows walk the whole series and pronounce every point. The table is responsible for the overview and the keyboard for the exact value; the details — ../model.md.

'auto' means “as many rows as can be read”. The budget of the drawing is taken when there is one; with decimate: 'never' there is none, and a fixed ceiling with a uniform sample remains.

Which of those is needed is decided by the application: keeping ten thousand rows in the accessibility tree is its right, but so is the cost of rebuilding such a table.

A plan, a norm and the limit of the acceptable are the references prop rather than a series made of a constant: a constant series would enter the legend, would stretch the axis and would travel into the table as data. The details — ../model.md, the section “A reference is not a series”.

Series of different orders (money and units) are readable on one chart only with two axes, and two axes let any pair be fitted to a visible correlation. That is why the axis: 'right' of a series does not work until dualAxis is switched on. The invariants — ../model.md, the section “The second value axis”.