@x12i/charts 1.0.0 → 1.1.0

package/README.md

@@ -1,37 +1,528 @@
 # @x12i/charts
 
-`ChartSpec` for the Unified UI Kit: one JSON-serializable description of a chart.
+Accessible charts for the Unified UI Kit. You describe a chart as one
+JSON-serializable `ChartSpec`; the package draws it as SVG with the kit's design
+tokens, adds a legend, tooltip, keyboard navigation, loading/empty/error states,
+a generated text description and a data table, and switches to an ECharts canvas
+for very large data.
 
-> **Status: foundation.** This package ships the spec types and the renderer
-> choice logic. The renderers themselves are not built yet.
+- **16 chart types**: bar, lollipop, line, area, step, sparkline, combo (bars and
+  lines, optionally on two axes), scatter, bubble, histogram, waterfall, donut,
+  pie, heatmap, gauge and progress ring.
+- **Accessible by construction**: every chart has a name, a description, keyboard
+  navigation, a screen-reader announcement per point and a "View as table"
+  toggle. Color is never the only way to tell series apart.
+- **Tokens only**: no colors, sizes or fonts of its own. Light, dark and
+  high-contrast themes work through `data-theme`.
+- **Right to left** and **localized**: logical CSS, mirrored axes, `Intl` for
+  numbers, dates and lists, and a message catalog for every word it shows.
+- **Server-safe**: the root entry has no React and no DOM.
+
+## Install
+
+```sh
+pnpm add @x12i/charts @x12i/ui @x12i/themes react react-dom
+# Only if you want the canvas renderer (see "Performance"):
+pnpm add echarts
+```
+
+`@x12i/ui`, `react` and `react-dom` are peer dependencies; `echarts` is an
+**optional** peer dependency. The package depends on `@x12i/tokens` and a few
+small D3 modules (`d3-array`, `d3-scale`, `d3-shape`, `d3-time`, `d3-format`,
+`d3-time-format`; all ISC). It is ESM only.
+
+Import both stylesheets once, and set the theme on a parent element:
+
+```tsx
+import "@x12i/ui/styles.css";
+import "@x12i/charts/styles.css";
+```
+
+The stylesheet is made of zero-specificity rules (`:where(...)`) on
+`data-kit="chart-*"` hooks, so your own CSS always wins without `!important`.
+
+## Two entry points
+
+| Import | Contents | Needs |
+| --- | --- | --- |
+| `@x12i/charts` | The headless core: `ChartSpec` types and `defineChartSpec`, validation, data transforms, statistics, scales and layout math, formatting, message catalog, text descriptions, data tables and CSV, the ECharts option builder. | Nothing. No React, no DOM, no browser globals. Safe in server code, workers and scripts. |
+| `@x12i/charts/react` | `Chart`, `ChartFrame`, `ChartCard`, `ChartGrid`, `ChartDataTable`, `ChartLegend`, `ChartState`, `ChartConfigProvider`, `SvgChart`, `EChartsChart`. | React 19, `@x12i/ui`. |
+
+`dist/react.js` starts with `"use client"`, so the components work in a Next.js
+App Router tree without wrapping. The root entry has no directive and runs in
+server components, route handlers and workers.
+
+### Server rendering
+
+`Chart` renders on the server. Without a `width` it uses a fixed default width
+(640) on the server **and** on the first client render, so hydration matches;
+then it measures its container and re-draws to fit. Pass `width` and `height`
+for charts that must not move. The default locale is the fixed `"en"`, never the
+runtime's, so the server and browser print identical text. Pass `locale` (or set
+it once with `ChartConfigProvider`) to localize.
 
 ```ts
-import { defineChartSpec } from "@x12i/charts";
+// A server component, route handler or script: no React involved.
+import { chartToCsv, describeChart, validateChartSpec } from "@x12i/charts";
+
+const issues = validateChartSpec(spec);
+const { name, text } = describeChart(spec);   // the screen-reader description
+const csv = chartToCsv(spec, { locale: "de" });
+```
+
+## Quick start
+
+```tsx
+import { ChartFrame } from "@x12i/charts/react";
+import type { ChartSpec } from "@x12i/charts";
 
-export const signups = defineChartSpec({
-  title: "Weekly signups passed target in week 4",
-  source: "Product analytics",
-  data: { ref: "signups_by_week" },
+// Define specs outside the component, or memoize them. A new object on every
+// render makes the chart rebuild its model on every render.
+const tickets: ChartSpec = {
+  title: "Platform has the most open tickets",
+  source: "Support desk, 1 Nov 2025",
+  data: {
+    values: [
+      { team: "Platform", tickets: 42 },
+      { team: "Growth", tickets: 31 },
+      { team: "Payments", tickets: 18 },
+      { team: "Search", tickets: 12 },
+    ],
+  },
   mark: "bar",
-  x: { field: "week", type: "category" },
-  y: { field: "signups", type: "number", format: "compact" },
-  highlight: { where: "week == 'W4'" },
-  annotations: [{ type: "reference-line", y: 300, label: "Target" }],
-  a11y: { description: "Bars of weekly signups; week 4 is highest." },
-});
+  x: { field: "team", type: "category", title: "Team" },
+  y: { field: "tickets", type: "number", title: "Open tickets" },
+  highlight: { where: "team == 'Platform'" },
+  labels: { values: true },
+  a11y: { description: "Platform has 42 open tickets, more than any other team." },
+};
+
+export function TicketsChart() {
+  return <ChartFrame spec={tickets} />;
+}
+```
+
+`ChartFrame` is a `<figure>` with a heading (the title states the finding), a
+subtitle, a toolbar (**View as table**, **Download CSV**), the chart, the source
+line and the data table. Use `Chart` alone when you supply your own frame, and
+`ChartCard` for the same frame on a bordered surface.
+
+### Line
+
+```tsx
+const revenue: ChartSpec = {
+  title: "Revenue outgrew cost every month",
+  subtitle: "Monthly, USD thousands",
+  source: "Finance ledger",
+  data: {
+    values: [
+      { month: "2025-01-01", revenue: 120, cost: 90 },
+      { month: "2025-02-01", revenue: 135, cost: 96 },
+      { month: "2025-03-01", revenue: 128, cost: 99 },
+      { month: "2025-04-01", revenue: 160, cost: 104 },
+    ],
+  },
+  mark: "line",
+  x: { field: "month", type: "time", title: "Month" },
+  y: { field: "revenue", type: "number", title: "USD thousands" },
+  series: [
+    { id: "revenue", label: "Revenue", field: "revenue" },
+    { id: "cost", label: "Cost", field: "cost" },
+  ],
+  annotations: [{ type: "reference-line", y: 130, label: "Target" }],
+  a11y: { description: "Revenue rose from 120 to 160 while cost rose from 90 to 104." },
+};
+
+<ChartFrame spec={revenue} />;
 ```
 
-## Renderers (planned)
+Series that differ in kind are listed in `series`. Without `series`, one series
+is drawn from `y`, or one per value of `color: { field }`.
 
-| Renderer | Engine | Used for |
+### Bar variants
+
+```ts
+// Grouped (default), stacked, normalized to 100%, or horizontal:
+{ mark: "bar", color: { field: "region", type: "category" } }
+{ mark: "bar", color: { field: "region", type: "category" }, stack: "stacked" }
+{ mark: "bar", color: { field: "region", type: "category" }, stack: "normalized" }
+{ mark: "bar", orientation: "horizontal" }
+```
+
+### Donut
+
+```tsx
+const share: ChartSpec = {
+  title: "Platform and Growth hold three quarters of tickets",
+  data: { ref: "tickets" },                    // resolved from `datasets`
+  mark: "donut",
+  x: { field: "team", type: "category", title: "Team" },
+  y: { field: "tickets", type: "number", title: "Open tickets" },
+  donut: { centerCaption: "tickets" },         // the center shows the total
+  a11y: { description: "Platform 41 percent, Growth 30 percent, the rest 29 percent." },
+};
+
+<ChartFrame spec={share} datasets={{ tickets: rows }} />;
+```
+
+Slices beyond `donut.maxSlices` (default 5) merge into "Other". Slices show their
+share; the legend toggles them.
+
+### Sparkline
+
+```tsx
+import { Chart } from "@x12i/charts/react";
+
+const trend: ChartSpec = {
+  title: "Revenue trend",
+  data: { values: monthly },
+  mark: "sparkline",
+  x: { field: "month", type: "time" },
+  y: { field: "revenue", type: "number" },
+  a11y: { description: "Revenue trends up." },
+};
+
+// 48 high by default. A non-interactive sparkline is a labelled image.
+<Chart spec={trend} width={120} height={32} interactive={false} />;
+```
+
+### Other types
+
+| `mark` | Key fields | Notes |
 | --- | --- | --- |
-| SVG (default) | D3 scale, shape and array modules (ISC) and visx primitives (MIT) | Up to about 5,000 points; always in reports and print |
-| Canvas | Apache ECharts (Apache-2.0), through a token bridge | Above 5,000 points, and types such as Sankey and sunburst |
+| `area` | `x`, `y`, optional `color` + `stack` | Stacked or normalized with `stack`. |
+| `step` | `x`, `y` | Steps instead of slopes. |
+| `lollipop` | `x` (category), `y` | A stem and a dot per category. |
+| `combo` | `series` with `mark: "bar" \| "line" \| "area" \| "step" \| "scatter"` | Second axis needs `dualAxis: true` and `axis: "y2"`; a visible warning is added. |
+| `scatter` | `x` (number), `y` | Optional `color` for groups. |
+| `bubble` | `x`, `y`, `size` | Bubble area encodes `size`. |
+| `histogram` | `x` (the measure) and `bins: { count }` or `bins: { thresholds }` | Bins the raw values. |
+| `waterfall` | `x` (steps), `y` (change), `waterfall: { totals }` | Increase, decrease and total bars with connectors. |
+| `heatmap` | `x`, `y` (categories), `value` | Sequential ramp, or diverging when values cross zero. |
+| `gauge` | `gauge: { value, min, max, target, bands, format }` | `data: { values: [] }` is fine for a literal value. |
+| `progress-ring` | `gauge: { value, min, max, format: "percent" }` | |
+
+Everything else in `chartTypes` (for example `treemap`, `sankey`, `stat`)
+is reserved in the spec but not drawn yet; see "Limitations".
+
+## ChartSpec in brief
+
+```ts
+interface ChartSpec {
+  title: string;                 // a sentence that states the finding (required)
+  subtitle?: string;             // scope and units
+  source?: string;               // where the data came from
+  data: { ref: string } | { values: Row[] };
+  mark: ChartType;
+  x?: Encoding; y?: Encoding; color?: Encoding; size?: Encoding; value?: Encoding;
+  series?: SeriesSpec[];         // explicit series: id, label, field | points, mark, axis, tone, marker, dash, stack, hidden, format
+  stack?: "none" | "stacked" | "normalized" | "diverging";
+  orientation?: "vertical" | "horizontal";
+  scales?: { x?, y?, y2? };      // linear | log | sqrt | time | band | ordinal, domain, nice, zero, reverse, padding
+  axes?: { x?, y?, y2? };        // show, title, grid, ticks, tickValues, format, labelAngle, maxLabelLength
+  thresholds?: Threshold[];      // labelled limits; points that breach get an extra mark and a note
+  annotations?: Annotation[];    // reference-line, reference-band, text, forecast, point (all labelled)
+  transforms?: Transform[];      // aggregate, bin, stack, percent-of-total, sort, top-n, rolling-average, cumulative-sum, period-change, downsample
+  highlight?: { where: string }; // one accent: `team == 'Platform'`
+  legend?: { show?: boolean | "auto"; position?: "top" | "bottom" };
+  labels?: { direct?: boolean | "auto"; values?: boolean };
+  interactions?: { tooltip?; legendIsolate? };
+  dualAxis?: boolean;
+  renderer?: "svg" | "canvas" | "auto";
+  direction?: "ltr" | "rtl" | "auto";
+  timeZone?: string;             // IANA zone for formatting time values (default "UTC")
+  a11y: { description: string; table?: boolean };   // description is required
+}
+```
+
+Formats are named (`compact`, `percent`, `integer`, `decimal`, `currency:USD`,
+`date`, `datetime`, `time`, `month`, `year`), d3-format specifiers (`,.2f`) or
+d3-time-format patterns (`%b %Y`).
+
+`validateChartSpec(spec, { datasets })` returns `{ severity, code, path, message }`
+issues for anything you can get wrong (missing title, unknown field, a bar chart
+with a truncated baseline, a second axis without `dualAxis`, too many series,
+too many rows for SVG, ...). `isValidChartSpec` is the boolean version.
+
+Design rules the validator and defaults enforce: bars start at zero, one accent
+on grey, at most 8 categorical hues, dual axes only behind an explicit flag,
+targets and limits always labelled.
+
+## Component API
 
-`resolveRenderer()` implements the `renderer="auto"` rule today.
+### `Chart` / `SvgChart` / `EChartsChart`
 
-## Design rules the defaults will enforce
+| Prop | Type | Description |
+| --- | --- | --- |
+| `spec` | `ChartSpec` | The chart. Memoize it. |
+| `datasets` | `Record<string, Row[]>` | Rows for `data: { ref }`. Falls back to `ChartConfigProvider`. |
+| `width`, `height` | `number` | Layout units. Default: fill the container; height by type (320, sparkline 48, gauge 220). |
+| `locale` | `string` | BCP 47 tag for numbers, dates, lists and plurals. Default `"en"`. |
+| `messages` | `ChartMessagesInput` | Overrides for every word the chart shows or announces. |
+| `dir` | `"ltr" \| "rtl"` | Text direction. Default: the page's `dir`, then the locale. |
+| `renderer` | `"svg" \| "canvas" \| "auto"` | Overrides `spec.renderer`. |
+| `target` | `"screen" \| "print" \| "report"` | `print` and `report` always use SVG. |
+| `loadEcharts` | `() => Promise<{ init }>` | Loads echarts for canvas. Default `import("echarts")`. |
+| `loading`, `error`, `onRetry` | `boolean`, `unknown`, `() => void` | Loading and error states at the chart's height. |
+| `hiddenSeries`, `defaultHiddenSeries`, `onHiddenSeriesChange` | `string[]` | Controlled or uncontrolled legend toggles. |
+| `interactive` | `boolean` | `false` draws a static, non-focusable labelled image. Default `true`. |
+| `tooltip` | `boolean` | Default `spec.interactions.tooltip !== false`. |
+| `onPointActivate` | `(info: ChartPointInfo, event) => void` | Click, Enter or Space on a point. |
+| `onActivePointChange` | `(info \| null) => void` | The hovered or focused point changed. |
+| `className`, `style`, `id` | | On the root element. |
+
+`SvgChart` always draws SVG. `EChartsChart` always uses canvas (with an SVG
+fallback, see below). `ChartPointInfo` has `seriesId`, `seriesLabel`,
+`seriesIndex`, `pointIndex`, `x`, `xLabel`, `y`, `size` and `row` (the source row).
+
+### `ChartFrame` / `ChartCard`
+
+Everything `Chart` takes, plus `headingLevel` (2-6, default 3), `toolbar`
+(default `true`), `actions` (extra buttons), `view` / `defaultView` /
+`onViewChange` (`"chart" | "table"`), `tableMaxRows` (default 200; the CSV always
+has every row), `csvFileName`, `onDownload(csv, fileName)` (replaces the browser
+download) and `variant` (`"plain" | "card"`).
+
+### `ChartGrid`, `ChartDataTable`, `ChartLegend`, `ChartState`
+
+`ChartGrid` lays charts out in a responsive grid (`columns` fixes the count,
+`label` makes it a named group). `ChartDataTable` is the data table on its own.
+`ChartLegend` and `ColorScaleLegend` and `ChartState` are the building blocks,
+exported for custom layouts.
+
+### `ChartConfigProvider`
+
+Sets `locale`, `messages`, `direction`, `datasets`, `loadEcharts` and `target`
+for every chart inside. Providers nest and merge (the inner one wins; `markNames`
+merge key by key); props on a chart win over the provider.
+
+```tsx
+<ChartConfigProvider locale="de" messages={deMessages} datasets={datasets}>
+  <ChartFrame spec={spec} />
+</ChartConfigProvider>
+```
+
+## Theming
+
+Series colors are `--kit-color-chart-*` tokens (`accent`, `muted`, `reference`,
+`good`, `warning`, `critical`, `categorical-1` to `categorical-8`); heatmaps use
+the `--kit-color-sequential-*` and `--kit-color-diverging-*` ramps; axes and
+gridlines use `--kit-color-chart-axis` and `--kit-color-chart-grid`. Everything
+follows the theme set by `ThemeProvider` / `data-theme` (light, dark,
+high-contrast) and the density tokens. To change a color, override the token
+where you need it:
+
+```css
+.my-dashboard {
+  --kit-color-chart-categorical-1: var(--kit-color-accent-default);
+}
+```
+
+Specs choose a tone by name (`series: [{ id: "a", tone: "good" }]`), never a
+color. The canvas renderer reads the same variables at runtime and redraws when
+`data-theme` changes on the page or an ancestor.
+
+Every part of a chart has a hook: `data-kit="chart"`, `chart-svg`, `chart-line`,
+`chart-bar`, `chart-point`, `chart-arc`, `chart-cell`, `chart-axis`,
+`chart-tick-label`, `chart-legend`, `chart-tooltip`, `chart-state`,
+`chart-frame`, `chart-table` and so on, with states as `data-*` attributes
+(`data-hidden`, `data-active`, `data-highlighted`, `data-muted`, `data-breach`,
+`data-state`, `data-renderer`). The stylesheet is tested to contain no hex or
+`rgb()` colors, no px/rem lengths, only logical properties and only existing
+`--kit-*` variables.
+
+## Accessibility
+
+- **Name and description.** The plot is `role="application"` with an
+  `aria-label` of "{title} ({chart type})", `aria-roledescription="chart"` and an
+  `aria-describedby` pointing to a generated description: chart type, series and
+  point counts, ranges, trends, the highest and lowest points, thresholds and
+  breaches, plus your own `a11y.description`.
+- **Keyboard.** Tab to the chart, then the arrow keys move between points: left
+  and right along the categories, up and down between series at the same
+  category; on a heatmap along both axes; on a scatter plot to the nearest point
+  in that direction; through the slices of a pie. Home / End jump to the first
+  and last category, PageUp / PageDown move ten categories, Enter or Space
+  activates (`onPointActivate`), Escape dismisses the tooltip. In a right-to-left chart, left and right swap. A visible focus
+  ring is drawn on the focused mark.
+- **Screen readers.** Each focused point is announced politely through a live
+  region ("Mar 1, 2025, Cost: 99. 6 of 12."). The tooltip is for sighted users
+  and is `aria-hidden`, so nothing is announced twice. The decorative SVG groups
+  are `aria-hidden`.
+- **Data table.** `ChartFrame` always renders the data as a real `<table>` with
+  caption, column headers and row headers: visible in table view, visually hidden
+  (but in the accessibility tree) in chart view. Disable with
+  `a11y: { table: false }`.
+- **Color is never the only channel.** Series differ by hue **and** marker shape
+  and dash style (lines), or hatch pattern (bars, areas, slices; eight patterns
+  cycle so hue + pattern pairs stay unique for 64 series). Threshold breaches get
+  an extra mark and a note in the tooltip. Waterfall decreases are hatched, and
+  the tooltip names every change with a sign. Status annotations carry text.
+- **Legend.** Entries are `<button aria-pressed>`; hidden series are removed from
+  the plot, the description and the announcements.
+- **Reduced motion.** Animation is skipped when `prefers-reduced-motion: reduce`.
+- **Forced colors.** In Windows high-contrast mode, marks use system colors and
+  keep their outlines and patterns.
+- **Touch.** A tap selects a point and keeps its tooltip after the finger lifts
+  (a hovering mouse hides it when the pointer leaves).
+- **States.** Loading (`role="status"`, `aria-busy`), empty, missing dataset and
+  unsupported type use `role="status"`; errors use `role="alert"` with an optional
+  retry. All reserve the chart's height so the page does not jump.
+
+Tested with axe (`vitest-axe`) on every chart type, in chart and table view, in
+every state, in right-to-left, and on the canvas renderer, with zero violations.
+Axe cannot check color contrast in jsdom; contrast is guaranteed by the token
+pairs in `@x12i/themes`.
+
+## Internationalization
+
+- Every word the charts print or announce is in `defaultMessages` (86 keys:
+  states, toolbar, table columns, tooltips, point announcements, the generated
+  description, trends). Pass `messages` with any subset. Templates use an ICU
+  MessageFormat subset: `{name}`, `{n, number}`,
+  `{n, plural, =0 {none} one {# row} other {# rows}}` (`#` is the number) and
+  `{kind, select, up {rose} other {fell}}`. Values you pass as text are shown
+  as-is; numbers go through `Intl` for `{n, number}` and for plural rules.
+  `markNames` renames chart types ("line chart").
+- Numbers, dates, times, percentages, compact numbers and lists go through
+  `Intl` with your `locale`; the default is the fixed `"en"`.
+- Right-to-left (Arabic, Hebrew, Persian, Urdu, ...): the chart sets `dir`,
+  time and category axes mirror, the value axis moves to the other side, label
+  anchors flip for right-to-left text and keyboard left/right swap. Numeric
+  labels stay left-to-right. Direction comes from the `dir` prop, then the
+  page's `dir` attribute (observed for changes), then the locale.
+
+```tsx
+<ChartConfigProvider
+  locale="ar"
+  messages={{ viewAsTable: "عرض كجدول", downloadCsv: "تنزيل CSV", legend: "المفتاح" }}
+>
+  <ChartFrame spec={spec} />
+</ChartConfigProvider>
+```
+
+## Performance
+
+| Data size | Renderer | Notes |
+| --- | --- | --- |
+| Up to ~5,000 points | SVG | Fully accessible, keyboard navigable, vector. Always used for `target="print"` and `"report"`. |
+| Above 5,000 points | Canvas (`renderer: "auto"`) | `SVG_POINT_LIMIT = 5000`. Needs `echarts`. |
+
+Before reaching for canvas, thin the data: `transforms: [{ type: "downsample",
+method: "lttb", field: "value", threshold: 1000 }]` keeps the visual shape of a
+line with a fraction of the points, and `aggregate` / `bin` reduce rows before
+drawing. The 5,000-point threshold is a comfort limit, not a measured
+guarantee: DOM-based SVG gets heavier with every mark, so test on your slowest
+target device. Layout is memoized on the spec, size, locale, direction and
+hidden series, so memoize your spec.
+
+### The canvas renderer
+
+`EChartsChart`, `renderer="canvas"` and `renderer="auto"` above the limit draw
+with Apache ECharts, loaded lazily by `import("echarts")` the first time a chart
+needs it (apps that only draw SVG never download it). Colors are read from your
+`--kit-*` variables, and the chart redraws on theme changes. The legend, title,
+frame, data table and text description are the same as for SVG.
+
+If `echarts` cannot be loaded, or cannot draw the particular chart (for example
+a waterfall that crosses zero), the chart falls back to SVG and shows a note.
+
+`echarts` is an optional peer, and bundlers resolve `import("echarts")` at build
+time, so if you do not install it your bundler may warn or fail on that import.
+Either install `echarts`, or pass your own loader, which also lets you register
+only the echarts modules you use:
+
+```tsx
+import * as echarts from "echarts/core";
+import { LineChart } from "echarts/charts";
+import { GridComponent, TooltipComponent } from "echarts/components";
+import { CanvasRenderer } from "echarts/renderers";
+
+echarts.use([LineChart, GridComponent, TooltipComponent, CanvasRenderer]);
+
+<ChartConfigProvider loadEcharts={async () => echarts}>{children}</ChartConfigProvider>;
+```
+
+## CSV and tables
+
+`chartToTable(spec)` and `chartToCsv(spec, { locale, delimiter, bom })` produce
+the same table the component shows; the CSV is RFC 4180 (CRLF line ends, quoted
+fields). The download button adds a UTF-8 byte-order mark so spreadsheets open it
+correctly, and `onDownload` lets you send the CSV to your own handler.
+
+## Headless API
+
+Everything in `@x12i/charts`, by area:
+
+- **Spec**: `defineChartSpec`, `chartTypes`, the `ChartSpec` types.
+- **Validation**: `validateChartSpec`, `isValidChartSpec`.
+- **Model and data**: `buildChartModel`, `supportedMarks`, `isSupportedMark`,
+  `applyTransforms`, `resolveRows`, `countPoints`, `effectiveStack`, `readField`,
+  `histogramBins`, `stackValues`, `lttb`, `minMax`, `compileWhere` /
+  `evaluateWhere` (the `highlight.where` expression language).
+- **Statistics**: `mean`, `median`, `quantile`, `sum`, `variance`,
+  `standardDeviation`, `extent`, `correlation`, `linearRegression`,
+  `regressionBand`, `forecastLinear`, `movingAverage`, `cumulativeSum`,
+  `percentChange`, `periodChange`, `trendDirection`.
+- **Scales and layout**: `createContinuousScale`, `createBandScale`,
+  `createPointScale`, `niceTicks`, `fitTickLabels`, `layoutChart` (spec model to
+  plain geometry; the SVG component only draws it), `patternIndex`.
+- **Interaction as pure functions**: `hitTest`, `navigate`, `tooltipFor`,
+  `describeTarget`, `pointInfo`, `isNavKey`.
+- **Formatting and messages**: `createFormatters`, `createNumberFormatter`,
+  `createDateFormatter`, `formatList`, `formatShare`, `isRtlLocale`,
+  `DEFAULT_LOCALE`, `defaultMessages`, `resolveMessages`, `formatMessage`.
+- **Text alternatives and exports**: `describeChart`, `describeModel`,
+  `chartToTable`, `modelToTable`, `chartToCsv`, `tableToCsv`.
+- **Renderer**: `resolveRenderer`, `SVG_POINT_LIMIT`.
+- **Canvas mapping**: `toEChartsOption`, `themeColorsFromTokens` (no echarts
+  import).
+
+Because layout is a pure function, you can render a chart to your own target
+(a PDF, a canvas, an email) from `layoutChart(buildChartModel(spec), { width,
+height, rtl })`.
+
+## Limitations
+
+Honest list of what is not there yet:
+
+- **Chart types not drawn.** `chartTypes` reserves 50 types so saved specs stay
+  valid, but the renderer draws the 16 in `supportedMarks`. Others (`treemap`,
+  `sankey`, `box-plot`, `stat`, `funnel`, `calendar-heatmap`, maps, ...) show an
+  "unavailable" state, and `validateChartSpec` warns.
+- **Interactions.** `interactions.brush`, `zoom` and `drilldown` are in the spec
+  for forward compatibility and are ignored (the validator warns). There is no
+  shared filter store. Legend toggling, isolate (`legendIsolate`), tooltips,
+  keyboard navigation and `onPointActivate` work.
+- **Canvas.** The canvas renderer has no keyboard navigation and no right-to-left
+  mirroring (it is an image with a description, the table and the legend); use
+  SVG when you need them. A chart that falls back to SVG (echarts missing, or a
+  type canvas cannot draw) stays on SVG until it is re-mounted.
+- **Forced colors.** In Windows high-contrast mode, heatmap cells lose their color
+  ramp (system colors have no ramp); the values are in the tooltip, the labels and
+  the table.
+- **Time axes** are laid out in UTC; `timeZone` changes how values are formatted,
+  not where they sit on the axis.
+- **Waterfalls** that cross zero draw on SVG only.
+- **Gauges** are single-value. `format: "percent"` is the share of the min to max
+  range: 64 of 100 and 0.64 of 1 both read "64%". A literal gauge still needs
+  `data: { values: [] }`.
+- **Hatch patterns** are applied automatically (the second series onward in a
+  multi-series bar, area or slice chart); they are an option of `layoutChart`
+  (`patterns: true`), not a spec field.
+- **Message catalog** is English only. Other languages come from your `messages`.
+- **Contrast** depends on your theme; axe cannot measure it in jsdom.
+
+## Development
+
+```sh
+pnpm --filter @x12i/charts run build      # tsup (two entries) + copy styles.css
+pnpm --filter @x12i/charts run typecheck
+pnpm --filter @x12i/charts run lint       # also bans hard-coded colors and px/rem in src
+pnpm --filter @x12i/charts run test       # vitest: headless units, components, axe, styles, SSR
+```
 
-Grey first with one accent, bars start at zero, no 3D, dual axes only behind an
-explicit flag, and every chart has a title that states the finding, a source
-line, an accessible description and a "View as table" toggle.
+The tests cover every headless function, every chart type (marks, axes, legend,
+tooltip, keyboard, states, messages, right-to-left), axe on every chart type,
+the stylesheet's token rules, server rendering, and the canvas renderer with a
+mocked `echarts`.