@squadbase/vantage 0.6.2-dev1.d7c0911 → 0.6.2-dev1.e333781

package/docs/en/parts/area-chart.md

@@ -0,0 +1,99 @@
+# AreaChart
+
+> A typed area chart for trends over time. Pass rows, the x-axis column and the series columns.
+
+Draws a trend as filled areas. Instead of building an ECharts option, pass **the rows (`data`), the
+x-axis column (`index`) and the series columns (`categories`)**; the legend, tooltip and axis
+formats come with it. Colours follow the `--chart-1` … `--chart-5` tokens in fixed order and track
+light / dark. Under the hood it is an [`EChart`](parts/echart) inside a chart frame
+(title, summary, loading skeleton, empty state). The value axis always starts at 0.
+
+```tsx
+import { AreaChart } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | An array of rows. **Required.** One row is one x-axis point. Numeric columns are a number or a numeric string (such as a SQL DECIMAL); anything else counts as a gap. |
+| `index` | `string` |  | The column used for the x axis. **Required.** |
+| `categories` | `string[]` |  | The columns drawn as series. **Required.** Their order is the legend and colour order. Six or more fold into the five largest by total plus an Other series. |
+| `areaOptions` | `AreaChartOptions` |  | Area-specific settings: `{ type, curveType, fill, connectNulls }`. **Prefer this.** Takes precedence over the deprecated flat props of the same name. See below. |
+| `forecast` | `ChartForecast` |  | A forecast continuing one series: `{ data, category?, label? }`. `data` rows share the `index` key and carry the predicted value and an optional range. Always drawn as a dashed, lighter line. |
+| `comparison` | `ChartComparison` |  | Turns one of `categories` into a comparison line (prior year, plan…): `{ category, vs: "prior-period" \| "prior-year" \| "target" \| "custom", label? }`. Drawn as a thin grey line with no fill; the tooltip adds the main series' difference from it. `label` is required for `custom`. |
+| `colors` | `ChartColors` | `["chart-1", …, "chart-5"]` | Series colours: `"chart-1"` … `"chart-5"` or a semantic tone (`"positive"` / `"warning"` / `"negative"` / `"neutral"`). An array follows series order; a record is keyed by series name. |
+| `labels` | `Record<string, string>` |  | Maps `index` values and series names to display names (axes, legend, tooltip, data table). |
+| `format` | `ValueFormat` | `"compact"` | Number format: `"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`, or `{ type, digits, currency, notation, unit, divisor, durationUnit }`. Same values as the KPI components. Axes use a short form; the tooltip uses the same format. |
+| `valueFormatter` | `(value: number) => string` |  | A function escape hatch for the format. Takes precedence over `format`; kept for compatibility. |
+| `title` | `string` |  | The chart heading. It labels the plot area for screen readers. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary shown under the title and used as the plot's `aria-describedby`. `"auto"` builds one from `data`. Omitted means no summary. |
+| `isLoading` | `boolean` |  | Show a skeleton shaped like the final chart, at the same height. |
+| `emptyState` | `ChartEmptyState` |  | What to show when `data` is empty: `{ title?, description?, action? }`. The frame keeps its height. `action` takes one node, such as a button. |
+| `height` | `number \| string` | `288` | Plot-area height in px. A CSS length string is accepted for compatibility only and is deprecated; pass a number. |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | Show PNG save / copy buttons at the top right on hover. The PNG includes the title and summary unless you pass `{ includeTitle: false }`. |
+| `fileName` | `string` | `"chart.png"` | File name for the saved PNG. Use with `actions`. |
+| `chartOptions` | `EChartsOption` |  | An escape hatch deep-merged last into the generated ECharts option. |
+| `highlight` | `"auto" \| "none"` | `"auto"` | Label the max and latest value (first series only, two series or fewer). For `percent` stacking it labels the first and latest share of the bottom band. |
+| `provisionalFrom` | `string \| number` |  | An `index` value; points from here on are provisional and drawn lighter or dashed. Distinct from `forecast`. |
+| `provisionalLabel` | `string` |  | Name of the provisional range in legend and tooltip. |
+| `target` | `number` |  | A target value, drawn as a dotted horizontal line. The value axis always includes it. |
+| `targetLabel` | `string` |  | Label for the target line. |
+| `annotations` | `ChartAnnotation[]` |  | Notes at given positions: `{ at, label, to? }`. `at` / `to` are `index` values; with `to` it becomes a band, otherwise a vertical line. |
+| `showLegend` | `boolean` | `true` | Show the legend. |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `showGridLines` | `boolean` | `true` | Grid lines on the value axis. |
+| `showXAxis` | `boolean` | `true` | Show the x axis. |
+| `showYAxis` | `boolean` | `true` | Show the y axis. |
+| `startEndOnly` | `boolean` | `false` | Label only the first and last x-axis ticks. |
+| `yAxisWidth` | `number` |  | Width of the y-axis labels (px). Fix it to align plot areas across stacked charts. |
+| `minValue` | `number` |  | Lower bound of the value axis. Area charts always start at 0, so only values of 0 or below take effect (room under negative values). |
+| `maxValue` | `number` |  | Upper bound of the value axis. The axis widens if the data exceeds it. Pass the same value to charts you compare side by side. |
+| `allowDecimals` | `boolean` | `true` | `false` limits ticks to integers. |
+| `xAxisLabel` | `string` |  | Name of the x axis. |
+| `yAxisLabel` | `string` |  | Name of the y axis. |
+| `onValueChange` | `(value: ChartEventPayload \| null) => void` |  | Called on a click. Receives the clicked row plus `eventType` and `categoryClicked` (the series name); clicking the same point again passes `null`. When set, everything but the selection dims. |
+| `ariaLabel` | `string` |  | Screen-reader label for the plot area when there is no `title`. |
+| `className` | `string` |  | Classes to add (to the outer `<figure>`). |
+| `type` | `"default" \| "stacked" \| "percent"` |  | **Deprecated.** Use `areaOptions.type`. |
+| `curveType` | `"linear" \| "smooth" \| "step"` |  | **Deprecated.** Use `areaOptions.curveType`. |
+| `fill` | `"gradient" \| "solid" \| "none"` |  | **Deprecated.** Use `areaOptions.fill`. |
+| `connectNulls` | `boolean` |  | **Deprecated.** Use `areaOptions.connectNulls`. |
+| `loading` | `boolean` |  | **Deprecated.** Use `isLoading`. |
+
+## areaOptions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` stacks the series; `percent` stacks them as shares of each point's total (the tooltip still shows the original values). |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | The line shape. |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | How the area is filled. |
+| `connectNulls` | `boolean` | `false` | Join the line across gaps (`null` values). |
+
+> [!WARNING]
+> The flat `type`, `curveType`, `fill` and `connectNulls` props still work but are **deprecated**. Use
+> `areaOptions`; when both are given, `areaOptions` wins.
+
+## Showing a change in composition
+
+`areaOptions.type: "percent"` stacks each point to 100%. The value axis is fixed to 0–100%, and the
+tooltip shows the **original values**.
+
+```tsx
+<AreaChart
+  data={rows}
+  index="month"
+  categories={["Online", "Store"]}
+  areaOptions={{ type: "percent" }}
+/>
+```
+
+> [!NOTE]
+> `colors` are not Tailwind classes but **colour values** (the chart is drawn on a canvas). Token
+> names such as `"chart-2"` follow light / dark. Axis, legend and tooltip colours always come from the
+> theme.
+
+## AreaChart or EChart
+
+Start with this typed chart. Reach for [`EChart`](parts/echart) only for what these
+props cannot express — dual axes, scatter plots, heatmaps. Small tweaks can go through
+`chartOptions`.

package/docs/en/parts/bar-chart.md

@@ -0,0 +1,91 @@
+# BarChart
+
+> A typed bar chart for comparing categories. Grouped, stacked or 100% stacked; vertical or horizontal bars.
+
+Draws categories as bars. Pass **the rows (`data`), the category column (`index`) and the series
+columns (`categories`)** instead of an ECharts option; the legend, tooltip and axis formats come
+with it. Grouped, stacked or 100%-stacked, with vertical or horizontal bars. Colours follow the
+`--chart-1` … `--chart-5` tokens and track light / dark. Under the hood it is an
+[`EChart`](parts/echart) inside a chart frame (title, summary, loading skeleton,
+empty state). The value axis always starts at 0.
+
+```tsx
+import { BarChart } from "@squadbase/vantage/components";
+import type { BarChartProps, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | An array of rows. **Required.** One row is one category. Numeric columns are a number or a numeric string (such as a SQL DECIMAL); anything else counts as a gap. |
+| `index` | `string` |  | The column used for the category axis. **Required.** |
+| `categories` | `string[]` |  | The columns drawn as series. **Required.** Their order is the legend and colour order. Six or more fold into the five largest by total plus an Other series. |
+| `barOptions` | `BarChartOptions` |  | Bar-specific settings: `{ type, layout, barCategoryGap, showZeroValues, targetKey, highlight }`. **Prefer this.** Takes precedence over the deprecated flat props of the same name. See below. Bar charts have no forecast. |
+| `thresholds` | `ChartThreshold[]` |  | Colour bars by value. Rules are checked top to bottom and the first match wins; each is `{ lt?, lte?, gt?, gte?, tone }` (all given conditions must hold). Unmatched bars keep the normal colour. With several series it applies per bar and keeps the series colour on the edge; **ignored for stacked bars**. Example: `[{ gt: 2, tone: "negative" }, { gt: 1.5, tone: "warning" }]`. |
+| `colors` | `ChartColors` | `["chart-1", …, "chart-5"]` | Series colours: `"chart-1"` … `"chart-5"` or a semantic tone (`"positive"` / `"warning"` / `"negative"` / `"neutral"`). An array follows series order; a record is keyed by series name. |
+| `labels` | `Record<string, string>` |  | Maps `index` values and series names to display names (axes, legend, tooltip, data table). |
+| `format` | `ValueFormat` | `"compact"` | Number format: `"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`, or `{ type, digits, currency, notation, unit, divisor, durationUnit }`. Same values as the KPI components. Axes use a short form; the tooltip uses the same format. |
+| `valueFormatter` | `(value: number) => string` |  | A function escape hatch for the format. Takes precedence over `format`; kept for compatibility. |
+| `title` | `string` |  | The chart heading. It labels the plot area for screen readers. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary shown under the title and used as the plot's `aria-describedby`. `"auto"` builds one from `data`. Omitted means no summary. |
+| `isLoading` | `boolean` |  | Show a skeleton shaped like the final chart, at the same height. |
+| `emptyState` | `ChartEmptyState` |  | What to show when `data` is empty: `{ title?, description?, action? }`. The frame keeps its height. `action` takes one node, such as a button. |
+| `height` | `number \| string` | `288` | Plot-area height in px. A CSS length string is accepted for compatibility only and is deprecated; pass a number. |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | Show PNG save / copy buttons at the top right on hover. The PNG includes the title and summary unless you pass `{ includeTitle: false }`. |
+| `fileName` | `string` | `"chart.png"` | File name for the saved PNG. Use with `actions`. |
+| `chartOptions` | `EChartsOption` |  | An escape hatch deep-merged last into the generated ECharts option. |
+| `highlight` | `"auto" \| "none"` |  | Label the max and latest value (first series only, two series or fewer). Defaults to `"auto"` only when `index` is a date, month or year. Not to be confused with `barOptions.highlight`. |
+| `provisionalFrom` | `string \| number` |  | An `index` value; bars from here on are provisional (light fill, dashed edge). |
+| `provisionalLabel` | `string` |  | Name of the provisional range in legend and tooltip. |
+| `target` | `number` |  | A target value, drawn as a dotted line. The value axis always includes it. Not drawn when `barOptions.targetKey` is set. |
+| `targetLabel` | `string` |  | Label for the target line (or the marker name with `barOptions.targetKey`). |
+| `annotations` | `ChartAnnotation[]` |  | Notes at given positions: `{ at, label, to? }`. `at` / `to` are `index` values. Drawn for vertical bars (the default `layout`), not for horizontal bars. |
+| `showLegend` | `boolean` | `true` | Show the legend. |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `showGridLines` | `boolean` | `true` | Grid lines on the value axis. |
+| `showXAxis` | `boolean` | `true` | Show the x axis. |
+| `showYAxis` | `boolean` | `true` | Show the y axis. |
+| `startEndOnly` | `boolean` | `false` | Label only the first and last x-axis ticks. |
+| `yAxisWidth` | `number` |  | Width of the y-axis labels (px). Fix it to align plot areas across stacked charts. |
+| `minValue` | `number` |  | Lower bound of the value axis. Bar charts always start at 0, so only values of 0 or below take effect (room under negative values). |
+| `maxValue` | `number` |  | Upper bound of the value axis (the horizontal axis for horizontal bars). The axis widens if the data exceeds it. |
+| `allowDecimals` | `boolean` | `true` | `false` limits ticks to integers. |
+| `xAxisLabel` | `string` |  | Name of the x axis. |
+| `yAxisLabel` | `string` |  | Name of the y axis. |
+| `onValueChange` | `(value: ChartEventPayload \| null) => void` |  | Called on a click. Receives the clicked row plus `eventType` and `categoryClicked` (the series name); clicking the same bar again passes `null`. When set, everything but the selection dims. |
+| `ariaLabel` | `string` |  | Screen-reader label for the plot area when there is no `title`. |
+| `className` | `string` |  | Classes to add (to the outer `<figure>`). |
+| `type` | `"default" \| "stacked" \| "percent"` |  | **Deprecated.** Use `barOptions.type`. |
+| `layout` | `"horizontal" \| "vertical"` |  | **Deprecated.** Use `barOptions.layout`. |
+| `barCategoryGap` | `string \| number` |  | **Deprecated.** Use `barOptions.barCategoryGap`. |
+| `loading` | `boolean` |  | **Deprecated.** Use `isLoading`. |
+
+## barOptions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `default` groups series side by side; `stacked` stacks them; `percent` stacks them as shares of each category's total. |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` lines the categories up along the x axis (vertical bars). `vertical` stacks the categories top to bottom (horizontal bars), which suits rankings with long labels; the first row is on top. A one-series `vertical` chart is a light tint by default. |
+| `barCategoryGap` | `string \| number` |  | The gap between categories (`"20%"` or px). Omitted uses the ECharts default. |
+| `showZeroValues` | `boolean` | `true` | Print a "0" label on zero-value bars so an undrawn bar does not read as "no data". Not shown when stacked. |
+| `targetKey` | `string` |  | A `data` column holding a per-bar target. Draws a short target marker on each bar and adds the target and achievement rate to the tooltip. Works for one series and stacked; not drawn for grouped multi-series or percent. When set, the single `target` line is not drawn. |
+| `highlight` | `string \| number` |  | For a one-series `layout: "vertical"` chart: the `index` value of the one bar the page is about, drawn in the full series colour while the rest stay light. No effect otherwise; a matching `thresholds` colour wins. |
+
+> [!WARNING]
+> The flat `type`, `layout` and `barCategoryGap` props still work but are **deprecated**. Use
+> `barOptions`; when both are given, `barOptions` wins.
+
+## A ranking with one bar highlighted
+
+```tsx
+<BarChart
+  data={rows}
+  index="store"
+  categories={["Sales"]}
+  barOptions={{ layout: "vertical", highlight: "Tokyo" }}
+/>
+```
+
+## BarChart or EChart
+
+Start with this typed chart. Reach for [`EChart`](parts/echart) only for what these
+props cannot express. Small tweaks can go through `chartOptions`.

package/docs/en/parts/bar-list.md

@@ -0,0 +1,50 @@
+# BarList
+
+> A ranked list of horizontal bars, name and value per row. No axes, light enough for a card.
+
+Lays out name and value pairs as rows with a bar whose length follows the value. It suits **top-N
+lists**: most visited pages, sales by store, error counts by type. It is plain HTML, not ECharts,
+so any number of them in cards stay cheap, and the colours follow the theme. It renders inside
+[`ChartFrame`](parts/chart-frame), so title, summary, loading and empty states and a
+screen-reader table come with it.
+
+```tsx
+import { BarList } from "@squadbase/vantage/components";
+import type { BarListItem, BarListOptions } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | The rows. **Required.** Without `index` / `categories` each row is read as `{ name, value, href?, key? }` (`BarListItem`). |
+| `index` | `keyof T` | `"name"` | The column holding each row's name. |
+| `categories` | `(keyof T)[]` | `["value"]` | The column holding the value, as a one-element array. Only the first is used. |
+| `colors` | `ChartSeriesColor \| ChartSeriesColor[]` | `"chart-1"` | `"chart-1"` … `"chart-5"` or a meaning colour. Only the first is used. Every row gets the same light tint; rank reads from the bar length. |
+| `highlight` | `string` |  | The name (the `index` value) of the one row to draw in the full colour. The rest stay light. The folded "Other" row cannot be chosen. |
+| `thresholds` | `ChartThreshold[]` |  | Colour rows by value with meaning colours; the first matching rule wins, e.g. `[{ lt: 40, tone: "negative" }, { lt: 70, tone: "warning" }]`. |
+| `labels` | `Record<string, string>` |  | Row name → display name, used in the row labels and the data table. Pass the column keys too to rename the table's columns. |
+| `format` | `ValueFormat` |  | Number format, e.g. `"compact"` or `{ type: "number", unit: "…" }`. |
+| `valueFormatter` | `(value: number) => string` |  | Escape hatch: a function that wins over `format`. |
+| `barListOptions` | `BarListOptions` |  | BarList-only settings: `sortOrder` (`"descending"` default, `"ascending"`, `"none"`), `maxItems` (default 5; the rest fold into one "Other" row), `otherLabel`, `exclude` (names always folded into "Other"), `showShare` (append each row's share of the total). |
+| `onValueChange` | `(item: T) => void` |  | When given, rows become buttons and the clicked row is passed in (a starting point for filtering). The "Other" row is not clickable. |
+| `title` | `string` |  | Heading of the chart. |
+| `summary` | `string` |  | A one-sentence summary shown under the title. |
+| `isLoading` | `boolean` | `false` | Show a skeleton with the height of the rows to come. |
+| `emptyState` | `ChartEmptyState` |  | Shown when `data` is empty: `{ title?, description?, action? }`. |
+| `ariaLabel` | `string` |  | Label read aloud when there is no `title`. |
+| `className` | `string` |  | Classes to add (on the outer figure). |
+
+The list is as tall as its rows, so `height` is not taken. Remaining props go to the list's `<div>`.
+`color`, `sortOrder`, `showAnimation`, `formatValue` and a per-row `color` still work but are
+deprecated; use `colors`, `barListOptions.sortOrder` and `valueFormatter` / `format`.
+
+## Making rows links
+
+A row with `href` turns its name into a link. Anything starting with `http(s)://` opens in a new tab.
+
+```tsx
+<BarList data={pages.map((p) => ({ name: p.path, value: p.views, href: p.url }))} />
+```
+
+The bar length is **relative to the largest value**. To show a share of the whole, use
+[`CategoryBar`](parts/category-bar) or `DonutChart`, or turn on
+`barListOptions={{ showShare: true }}`.

package/docs/en/parts/category-bar.md

@@ -0,0 +1,37 @@
+# CategoryBar
+
+> A single bar split into coloured segments, with an optional marker for the current value.
+
+Splits one bar in proportion to `values` and prints the running totals at the boundaries. Pass
+`marker` and a pin stands at that value. It suits score bands (needs work / standard / good), budget
+consumption and a one-bar share breakdown. It is plain HTML, not ECharts, and the colours follow the
+theme.
+
+```tsx
+import { CategoryBar } from "@squadbase/vantage/components";
+import type { CategoryBarMarker } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `values` | `number[]` |  | The width of each segment (relative). **Required.** They need not sum to 100. Negative values count as 0. |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | Segment colours, in order: `"chart-1"` … `"chart-5"`, a meaning colour (`"positive"` …) or a CSS colour. |
+| `marker` | `CategoryBarMarker` |  | `{ value: number; tooltip?: string; showAnimation?: boolean }`. `value` is on the same scale as the sum of `values`. The pin takes the colour of the segment it sits in. |
+| `showLabels` | `boolean` | `true` | Print the running totals above the bar. Labels that would overlap are thinned out. |
+| `format` | `ValueFormat` | `"compact"` | Format of the boundary numbers: `"compact"`, `"currency"`, `{ type, currency }`. |
+| `valueFormatter` | `(value: number) => string` |  | Escape hatch: a function that wins over `format`. |
+| `className` | `string` |  | Classes to add. |
+
+Remaining props go to the outer `<div>`.
+
+## Matching colours to the bands
+
+`colors` lines up with the segments. For a "bad to good" band, going from warm to cool reads well.
+
+```tsx
+<CategoryBar
+  values={[60, 20, 20]}
+  colors={["chart-5", "chart-3", "chart-2"]}
+  marker={{ value: 72, tooltip: "This month's score: 72" }}
+/>
+```

package/docs/en/parts/chart-frame.md

@@ -0,0 +1,39 @@
+# ChartFrame
+
+> The frame every typed chart renders in. A title, a summary and a plot area of fixed height.
+
+`ChartFrame` is what the typed charts (`LineChart`, `BarChart`, `Heatmap` …) render inside: an
+optional title and one-sentence summary above a plot area of fixed height. The plot is labelled by
+the title and described by the summary, so a screen reader hears what the chart says, not just that
+there is one. Use it directly when you build a chart of your own and want the same behaviour.
+
+The plot area keeps its height in every state: while loading it shows a skeleton shaped like the
+final chart, and with no data it says so (and offers one action) instead of drawing empty axes.
+
+```tsx
+import { ChartFrame } from "@squadbase/vantage/components";
+import type { ChartFrameProps, ChartSkeletonVariant } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | Heading of the chart. It labels the plot area (`aria-labelledby`). |
+| `summary` | `string` |  | A one-sentence summary under the title. It describes the plot area (`aria-describedby`). |
+| `isLoading` | `boolean` | `false` | Loading. Shows a skeleton in the shape of `variant`, at the same height. |
+| `isEmpty` | `boolean` | `false` | No data. Shows `emptyState` at the same height. |
+| `emptyState` | `ChartEmptyState` |  | `{ title?, description?, action? }`. `action` is a single node, such as a button. The default title is a generic "no data to show" message. |
+| `height` | `number \| string` | `288` | Height of the plot area. A number is px; a string is a CSS length (e.g. `"auto"`). |
+| `variant` | `ChartSkeletonVariant` | `"line"` | Shape of the loading skeleton: `"line" \| "area" \| "bar" \| "donut" \| "list"`. |
+| `ariaLabel` | `string` |  | Label for the plot area when there is no `title`. |
+| `plotRole` | `"img" \| "group"` | `"img"` | Role of the plot area. `"img"` suits a canvas chart. Use `"group"` for HTML charts whose rows are buttons or links, so their content is read. |
+| `dataTable` | `ChartDataTable` |  | The numbers as a visually-hidden (`sr-only`) table inside the figure, so a screen reader can read what a canvas only draws. Build it with `chartDataTable`. |
+| `children` | `ReactNode` |  | The plot itself. It is not drawn while loading or empty. |
+| `className` | `string` |  | Classes to add (on the outer `<figure>`). |
+
+`ref` points at the plot area (the element with the fixed height). `className` and the other
+attributes go to the outer `<figure>`.
+
+## What the typed charts take from it
+
+The typed charts forward `title`, `summary`, `isLoading`, `emptyState` and `height` to their frame
+under the same names, so you set them on the chart, not on `ChartFrame`.

package/docs/en/parts/delta.md

@@ -5,7 +5,7 @@
 Shows a change as one line: "↑ +12.4% 前期比". **Direction, rate, colour and wording are all computed
 from `value` and `comparison`** and cannot be passed in, so the arrow and the colour can never disagree.
 Colour is never the only signal — the arrow and the sign always accompany it. For metrics where a rise
-is bad (churn, error rate), pass `polarity="lower-is-better"`.
+is bad (churn, error rate), pass `betterWhen="down"` (`polarity` is the older name and still works).
 
 It replaces the deprecated [`TrendIndicator`](parts/trend-indicator).
 
@@ -18,7 +18,8 @@ import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/compon
 | --- | --- | --- | --- |
 | `value` | `number \| null \| undefined` |  | The current value. **Required.** The previous one comes from `comparison`. |
 | `comparison` | `Comparison` |  | What the value is compared against. **Required**, so the change always carries its label. See below. |
-| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | Whether a rise is good. |
+| `betterWhen` | `"up" \| "down"` | `"up"` | Which direction is good. Use `"down"` for metrics like churn. Wins over `polarity`. |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | Deprecated: the older name of `betterWhen`. `"neutral"` (no good or bad colouring) is only available here. |
 | `neutralBand` | `number` | `0.01` | Absolute ratio below which the change reads as flat. Default 1%. |
 | `variant` | `"badge" \| "inline"` | `"badge"` | A bordered badge, or plain text for use inline. |
 | `locale` | `string` | `"ja-JP"` | Locale for the percent. |
@@ -43,7 +44,7 @@ import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/compon
 <Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
 
 // A metric where down is good
-<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} polarity="lower-is-better" />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} betterWhen="down" />
 ```
 
 The colours come from the `--positive` / `--negative` / `--neutral` tokens. To show a KPI as a whole

package/docs/en/parts/donut-chart.md

@@ -0,0 +1,72 @@
+# DonutChart
+
+> A typed donut / pie chart for showing composition, with a legend that carries each share.
+
+Draws composition as a donut (or a pie). Pass **the rows (`data`), the label column (`index`) and
+the value column (`categories: [valueKey]`)**. Slices are sorted largest first and coloured with the
+`--chart-1` … `--chart-5` tokens in fixed order; more than five fold into one grey Other slice. The
+hole is empty by default; `donutOptions.centerLabel` can put the total, or the largest slice, in it.
+The centre label is HTML, not canvas, so it takes the page's type and colours. Under the hood it is
+an [`EChart`](parts/echart) inside a chart frame (title, summary, loading skeleton,
+empty state).
+
+```tsx
+import { DonutChart } from "@squadbase/vantage/components";
+import type { DonutChartProps, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | An array of rows. **Required.** One row is one slice. |
+| `index` | `string` |  | The column used for slice names. |
+| `categories` | `string[]` |  | A one-element array naming the column used for slice sizes (`["Sales"]`). Only the first entry is used. Values are numbers or numeric strings; zero, negative and missing values count as 0. |
+| `donutOptions` | `DonutChartOptions` |  | Donut-specific settings: `{ variant, centerLabel, totalLabel, unit, showLegend, maxSlices }`. **Prefer this.** Takes precedence over the deprecated flat props of the same name. See below. |
+| `colors` | `ChartSeriesColor[]` | `["chart-1", …, "chart-5"]` | Slice colours, largest first: `"chart-1"` … `"chart-5"` or a semantic tone (`"positive"` and so on). The Other slice is always grey. |
+| `labels` | `Record<string, string>` |  | Maps slice names (`index` values) to display names in the legend, tooltip, labels and data table. Example: `{ organic: "Organic search" }`. |
+| `format` | `ValueFormat` | `"compact"` | Number format: `"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`, or `{ type, digits, currency, notation, unit, divisor, durationUnit }`. |
+| `valueFormatter` | `(value: number) => string` |  | A function escape hatch for the format. Takes precedence over `format`; kept for compatibility. |
+| `title` | `string` |  | The chart heading. It labels the plot area for screen readers. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary shown under the title and used as the plot's `aria-describedby`. `"auto"` builds one from the slices (the largest slice and its share). Omitted means no summary. |
+| `isLoading` | `boolean` |  | Show a ring-shaped skeleton at the same height. |
+| `emptyState` | `ChartEmptyState` |  | What to show when `data` is empty: `{ title?, description?, action? }`. The frame keeps its height. `action` takes one node, such as a button. |
+| `height` | `number \| string` | `288` | Plot-area height in px. A CSS length string is accepted for compatibility only and is deprecated; pass a number. |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | Show PNG save / copy buttons at the top right on hover. The PNG includes the title and summary unless you pass `{ includeTitle: false }`. |
+| `fileName` | `string` | `"chart.png"` | File name for the saved PNG. Use with `actions`. |
+| `chartOptions` | `EChartsOption` |  | An escape hatch deep-merged last into the generated ECharts option. |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `onValueChange` | `(value: ChartEventPayload \| null) => void` |  | Called when a slice is clicked; clicking the same slice again passes `null`. When set, everything but the selection dims. |
+| `ariaLabel` | `string` |  | Screen-reader label for the plot area when there is no `title`. |
+| `className` | `string` |  | Classes to add (to the outer `<figure>`). |
+| `category` | `string` |  | **Deprecated.** Use `index`. |
+| `value` | `string` |  | **Deprecated.** Use `categories={[value]}`. |
+| `variant` | `"donut" \| "pie"` |  | **Deprecated.** Use `donutOptions.variant`. |
+| `label` | `ReactNode` |  | **Deprecated.** Use `donutOptions.centerLabel`. |
+| `showLabel` | `boolean` |  | **Deprecated.** Use `donutOptions.centerLabel` (`"none"` hides it). |
+| `loading` | `boolean` |  | **Deprecated.** Use `isLoading`. |
+
+## donutOptions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"donut" \| "pie"` | `"donut"` | A ring with a hole, or a full pie. |
+| `centerLabel` | `"none" \| "total" \| "top" \| ReactNode` | `"none"` | What to put in the hole (donut only). `"none"` leaves it empty (a total usually repeats a KPI); `"total"` shows the total with `totalLabel` and `unit`; `"top"` shows the largest slice and its share; any other node is placed as is. |
+| `totalLabel` | `string` |  | Heading of the centre total. Defaults to a built-in label. |
+| `unit` | `string` |  | A unit added to the centre total. |
+| `showLegend` | `boolean` | `true` | Show the legend: every slice with its share, largest first, to the right of the ring when there is room and below it otherwise. The share is printed only in the legend; without it, a wide enough plot labels its two largest slices outside the ring. |
+| `maxSlices` | `number` | `5` | How many slices are drawn individually. The rest, by size, fold into one Other slice. |
+
+> [!WARNING]
+> The flat `category`, `value`, `variant`, `label` and `showLabel` props still work but are
+> **deprecated**. Use `index`, `categories`, and `donutOptions`; when both are given, `donutOptions`
+> wins.
+
+## Showing the total in the hole
+
+```tsx
+<DonutChart
+  data={rows}
+  index="source"
+  categories={["sessions"]}
+  donutOptions={{ centerLabel: "total", unit: "sessions" }}
+/>
+```

package/docs/en/parts/funnel-steps.md

@@ -14,7 +14,8 @@ import type { FunnelStep } from "@squadbase/vantage/components";
 | --- | --- | --- | --- |
 | `data` | `FunnelStep[]` |  | The stages. **The first one is the full-width bar.** |
 | `showConversion` | `boolean` |  | Show the conversion between stages. |
-| `formatValue` | `(value: number) => string` |  | Format the numbers; raw by default. |
+| `valueFormatter` | `(value: number) => string` |  | Format the numbers. Takes precedence over `format`. (`formatValue` is deprecated.) |
+| `format` | `ValueFormat` | `"compact"` | Preset number format, as on the other charts. |
 | `animate` | `boolean` |  | Grow the bars on mount. |
 | `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
 | `direction` | `"vertical" \| "horizontal"` | `"vertical"` |  |

package/docs/en/parts/heatmap.md

@@ -0,0 +1,53 @@
+# Heatmap
+
+> A typed heatmap shading a grid of cells by value. For cohorts, weekday by hour counts and the like.
+
+Each row is one cell: pass the column for the x axis (`x`), the y axis (`y`) and the number to shade
+by (`value`). Shading is a single-colour ramp from light to dark in one theme colour, never a
+rainbow. A cell with no value is left unpainted and reads "—", never shaded like 0. It renders
+inside [`ChartFrame`](parts/chart-frame), with the numbers as a screen-reader table.
+
+```tsx
+import { Heatmap } from "@squadbase/vantage/components";
+import type { HeatmapProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | One row per cell (an x and y pair). **Required.** If a pair repeats, the later row wins. |
+| `x` | `keyof T` |  | The column for the horizontal axis (columns), e.g. `"hour"`. **Required.** |
+| `y` | `keyof T` |  | The column for the vertical axis (rows), e.g. `"weekday"`. The first row is at the top. **Required.** |
+| `value` | `NumericColumn<T>` |  | The numeric column that sets each cell's shade. **Required.** `null`, missing and non-numeric cells are left unpainted. |
+| `xLabels` | `string[]` |  | Order (and set) of x values. Defaults to order of appearance; x values not listed are not drawn. |
+| `yLabels` | `string[]` |  | Order (and set) of y values. Defaults to order of appearance; y values not listed are not drawn. |
+| `labels` | `Record<string, string>` |  | Column name or axis value → display name, used in axes, tooltip and data table, e.g. `{ mon: "Monday", value: "Count" }`. Pass the `y` key to rename the table's first column. |
+| `format` | `ValueFormat` | `"number"` | Number format for cells, tooltip and table: `"number"`, `"percent"`, `{ type: "number", unit: "…" }`. |
+| `valueFormatter` | `(value: number) => string` |  | Escape hatch: a function that wins over `format`. |
+| `tone` | `ChartSeriesColor` | `"chart-1"` | `"chart-1"` … `"chart-5"` or a meaning colour (`"positive"`, `"warning"`, `"negative"`, `"neutral"`). The ramp runs light to dark in this colour. |
+| `scale` | `{ min?: number; max?: number }` |  | Fixed shading range. By default the data's min to max. At or below `min` is lightest, at or above `max` darkest; the legend ends show these values. For a retention rate use `{ min: 0, max: 100 }`. Either side may be omitted. |
+| `showValues` | `boolean` | `false` | Write the value inside each cell. |
+| `showLegend` | `boolean` | `true` | Show the legend (light-to-dark band with end values). |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `details` | `NumericColumn<T>[]` |  | Extra numeric columns from the same row to add to the tooltip and data table, e.g. an SLA-breach count. Names come from `labels`, values from `format`. |
+| `flag` | `keyof T` |  | A column; rows where it is truthy (`true` or a non-zero number) get a border in the caution colour (`--negative`) and the tooltip says it needs attention. Distinguishable by border thickness, not colour alone. |
+| `title` | `string` |  | Heading of the chart. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary. `"auto"` builds one from the largest cell. |
+| `isLoading` | `boolean` | `false` | Show a skeleton with the same height. |
+| `emptyState` | `ChartEmptyState` |  | Shown when `data` is empty: `{ title?, description?, action? }`. |
+| `height` | `number` | `288` | Height of the plot area in px. |
+| `chartOptions` | `EChartsOption` |  | Escape hatch: deep-merged last into the generated ECharts option. |
+| `actions` | `boolean \| ChartActionsOptions` |  | Show PNG save / copy buttons. `{ includeTitle: false }` leaves the heading out of the image. |
+| `fileName` | `string` |  | File name for the saved PNG (with extension). |
+| `ariaLabel` | `string` |  | Label read aloud when there is no `title`. |
+| `className` | `string` |  | Classes to add (on the outer figure). |
+
+`minValue` and `maxValue` still work but are deprecated; use `scale`.
+
+## Fixing the scale
+
+By default the darkest cell is the data's maximum, so two heatmaps built from different data are not
+comparable by shade. When both ends have a meaning, as with a rate, fix them.
+
+```tsx
+<Heatmap data={rows} x="week" y="cohort" value="retention" format="percent" scale={{ min: 0, max: 100 }} />
+```

package/docs/en/parts/kpi-card.md

@@ -20,7 +20,8 @@ import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } f
 | `format` | `ValueFormat` | `"compact"` | How the value is formatted (see the format / comparison page); also used for previous, target and remaining. |
 | `locale` | `string` | `"ja-JP"` | The formatting locale. |
 | `comparison` | `Comparison` |  | What the value is compared against (`{ previous, vs, label? }`). Adds the change and the previous-actual line. |
-| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | Whether a rise is good. Use `"lower-is-better"` for metrics like churn. |
+| `betterWhen` | `"up" \| "down"` | `"up"` | Which direction is good. Use `"down"` for metrics like churn. Wins over `polarity`. |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | Deprecated: the older name of `betterWhen`. `"neutral"` (no good or bad colouring) is only available here. |
 | `neutralBand` | `number` | `0.01` | Absolute ratio below which the change reads as flat. |
 | `showPrevious` | `boolean` | `true` | Show the previous actual ("前期 400"). Needs `comparison`. |
 | `summary` | `string` |  | The conclusion sentence, as a **template** whose placeholders (below) the card fills. |

package/docs/en/parts/legend.md

@@ -0,0 +1,35 @@
+# Legend
+
+> A standalone chart legend in plain HTML, for sharing one legend between several charts.
+
+Turn each chart's own legend off (`showLegend={false}`) and put one `Legend` beside or under them.
+It looks like the legend of `DonutChart` (a rounded swatch and a muted name) and takes the same
+`categories`, `colors` and `labels` as the typed charts. Colours are assigned by the same function
+the charts use, so a `Legend` set next to a chart always shows that chart's colours. No chart, canvas
+or SVG is involved.
+
+```tsx
+import { Legend } from "@squadbase/vantage/components";
+import type { LegendProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `categories` | `string[]` |  | The series names, in colour order. **Required.** Pass the same `categories` as the chart. Charts fold six or more series into five plus "Other", so pass five plus "Other" here too. An empty array renders nothing. |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` |  | Series colours: `"chart-1"` … `"chart-5"` or a meaning colour. An array follows series order, a record is by series name. Pass the same `colors` as the chart. Defaults to token order; "Other" is always grey. |
+| `labels` | `Record<string, string>` |  | Series name → display name; pass the chart's `labels`. e.g. `{ sales: "Sales" }`. |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | Wrapping row, or a column. |
+| `ariaLabel` | `string` | `"凡例"` | Accessible name of the list. |
+| `className` | `string` |  | Classes to add. |
+
+> [!NOTE]
+> A meaning colour such as `"warning"` is painted as the **area colour** the bars use
+> (`--warning-fill`), not the text colour `--warning`, so it matches the chart.
+
+## Sharing one legend
+
+```tsx
+const categories = ["online", "retail"];
+
+<Legend categories={categories} labels={{ online: "Online", retail: "Retail" }} />
+```