Chart

Preview

A chart ships with its data as a grid — see Text alternative below. The pairing is not decorative; it is what makes the chart conformant.

<esa-chart label="Rainfall by month"></esa-chart>
<!-- data and series are set as PROPERTIES, not attributes -->
<script>
  chart.data = [{ month: 'Jan', rain: 20 }, /* … */];
  chart.series = [{ type: 'bar', xKey: 'month', yKey: 'rain', yName: 'Rainfall (mm)' }];
</script>

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-chart';

@Component({
  selector: 'app-chart-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-chart label="Rainfall by month" [data]="data" [series]="series"></esa-chart>
    <!-- data and series are set as PROPERTIES, not attributes -->
  `,
})
export class ChartDemo {
  data = [{ month: 'Jan', rain: 20 }, /* … */];
  series = [{ type: 'bar', xKey: 'month', yKey: 'rain', yName: 'Rainfall (mm)' }];
}

Multiple series

With more than one series a legend appears, and each series takes the next colour from the data-viz categorical family in fixed order — never cycled, never re-assigned when a filter changes the series count. Line and scatter series also take a rotating marker shape, so identity is never carried by hue alone.

chart.series = [
  { type: 'bar',  xKey: 'month', yKey: 'rain', yName: 'Rainfall (mm)' },
  { type: 'line', xKey: 'month', yKey: 'temp', yName: 'Temperature (C)' },
];

API

Installing

ag-charts-community is an optional peer dependency, loaded by dynamic import on first render. A spoke that never charts never pays the ~2.8 MB, and @esa/ecology’s own dependency list stays at lit alone.

npm install ag-charts-community

AG Charts Community is MIT and free in production. Integrated charts — where a user selects cells in a grid and charts them — require the AG Grid + AG Charts Enterprise Bundle, which is a separate licence from AG Grid Enterprise alone.

Accessibility

AG Charts was scored in a real browser against the five questions worth asking of any charting library. It passes the two that are hardest to retrofit. The rest is what this wrapper exists to fix.

Three more, found by measuring rather than reading the docs

• Legend hit targets render 16px tall — under the 24px raw floor, and reported rather than patched. That is not a violation: SC 2.5.8’s spacing exception passes an undersized target whose 24px circle clears its neighbours’, and the default legend spacing earns it — axe reports zero target-size violations here. Forcing it would mean 24px legend markers, since marker.size is the only option that moves the box (item.paddingY is not an option at all; AG Charts accepts and ignores it). The exception is layout-dependent: a legend packed tight enough loses it, so if npm run a11y ever reports target-size on a chart, the lever is options.legend.item.marker.size.
• Forced colors cannot reach a canvas. It is a bitmap — no token, no @media block and no assurance profile touches it. The only route in is to re-theme from JS with the system keywords, which this component does. It deliberately discards the data-viz palette in that mode: the user chose those colours, and overriding them would itself be SC 1.4.8. Marks stay apart by shape.
• Series told apart by colour alone is SC 1.4.1, Level A. Line, area and scatter series get a rotating marker shape. Bars cannot carry a pattern in Community — for those the answer is direct labels or the paired grid.

What is still yours to do

• Give every chart a real label. The component warns, but it cannot invent one.
• Ship the paired grid. See below.
• Nothing automated proves a screen reader announces any of this correctly. Structure is provable; announcement is not. That needs NVDA/Firefox and VoiceOver/Safari.

Text alternative — pair it with a grid

AG Charts ships no data-table view, and the chart alone does not satisfy the text-alternative requirement. The answer is a composition rather than a prop: esa-grid already solves tabular semantics, and a visible “view as data” gives sighted keyboard users a real affordance instead of an offscreen table only a screen reader can find.

<esa-chart label="Rainfall by month" .data={rows} .series={series} />

<esa-collapsible summary="View as data">
  <esa-grid columnDefs={cols} rowData={rows} />
</esa-collapsible>

There is a second reason, and it is not about screen readers. Three slots of the categorical palette sit under 3:1 against a light surface. The data-viz validator calls that acceptable only with relief — visible labels or a table view. The paired grid is that relief. Drop it and the palette stops being legal, not merely unfriendly.

Theming — why a canvas needs a bridge

A grid re-themes for free because it is DOM. A chart does not: measured, overriding the library’s own --ag-charts-* custom properties changes getComputedStyle and leaves the canvas painting its original colours. Those ~60 properties style the DOM chrome — tooltip, legend, menus, focus ring — and about a third of the theming surface is therefore ordinary CSS. Every mark, though, is resolved in JS and handed over as a literal.

Which means a canvas does not repaint when the cascade changes. The component watches data-theme, data-scheme and data-a11y-assurance on <html> and re-resolves. Without that, switching theme leaves the chart painted in the old brand with no error anywhere.

Series colours come from the tier-2 --color-background-dataviz-* family. Until it lands, the component falls back to a built-in ramp and warns in the console — a fallback that works silently is how a token never gets wired.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.