@squadbase/vantage 0.6.2-dev1.05a930b → 0.6.2-dev1.100dfeb

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" }} />
+```

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

@@ -0,0 +1,94 @@
+# LineChart
+
+> A typed line chart for trends and comparisons. Pass rows, the x-axis column and the series columns.
+
+Draws one or more series as lines. Pass **the rows (`data`), the x-axis column (`index`) and the
+series columns (`categories`)** instead of an ECharts option; the legend, tooltip and axis formats
+come with it. 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 starts at 0 unless `lineOptions.fitToData` is set.
+
+```tsx
+import { LineChart } from "@squadbase/vantage/components";
+import type { LineChartProps, 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. |
+| `lineOptions` | `LineChartOptions` |  | Line-specific settings: `{ curveType, connectNulls, fitToData, targetLabelPosition }`. **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 markers; 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). |
+| `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; the line chart starts from the value you give. The axis widens if the data goes below it. |
+| `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>`). |
+| `curveType` | `"linear" \| "smooth" \| "step"` |  | **Deprecated.** Use `lineOptions.curveType`. |
+| `connectNulls` | `boolean` |  | **Deprecated.** Use `lineOptions.connectNulls`. |
+| `autoMinValue` | `boolean` |  | **Deprecated.** Use `lineOptions.fitToData`. |
+| `loading` | `boolean` |  | **Deprecated.** Use `isLoading`. |
+
+## lineOptions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | The line shape. |
+| `connectNulls` | `boolean` | `false` | Join the line across gaps (`null` values). |
+| `fitToData` | `boolean` | `false` | Fit the value axis to the data range instead of starting at 0. The lowest tick label is omitted so it does not collide with the first x label (the grid line stays). |
+| `targetLabelPosition` | `"start" \| "end" \| "legend"` | `"start"` | Where the `target` label goes: above the line's left end, above its right end, or in the legend only (when the area around the line is crowded). The legend always names the target. |
+
+> [!WARNING]
+> The flat `curveType`, `connectNulls` and `autoMinValue` props still work but are **deprecated**. Use
+> `lineOptions.curveType`, `lineOptions.connectNulls` and `lineOptions.fitToData`; when both are
+> given, `lineOptions` wins.
+
+## Comparing against last year
+
+Mark one of `categories` as a comparison line with `comparison`. It is drawn as a thin grey line
+with no markers, and the tooltip adds the main series' difference from it.
+
+```tsx
+<LineChart
+  data={rows}
+  index="month"
+  categories={["Revenue", "Last year"]}
+  comparison={{ category: "Last year", vs: "prior-year" }}
+/>
+```
+
+## LineChart 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/progress-circle.md

@@ -0,0 +1,33 @@
+# ProgressCircle
+
+> A ring showing progress toward a target, with anything you like in the middle.
+
+Fills the ring to `value / max`. Children sit in the centre, so put the percentage or an icon
+there. It is a single `<svg>`, so a row of them in KPI tiles stays light.
+
+```tsx
+import { ProgressCircle } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` | `0` | Current value, clamped to `0`–`max`. |
+| `max` | `number` | `100` | The value of a full ring. |
+| `radius` | `number` | `32` | Outer radius in px. The whole part is `radius * 2` square. |
+| `strokeWidth` | `number` | `6` | Stroke width in px. |
+| `color` | `ChartColor` | `"chart-1"` | `"chart-1"` … `"chart-5"`, a meaning colour (`"positive"` …) or a CSS colour. The track is the same colour, lightened. |
+| `showAnimation` | `boolean` | `false` | Animate on mount and when the value changes. Always off under `prefers-reduced-motion`. |
+| `children` | `ReactNode` |  | What to put in the centre (e.g. `72%`). |
+| `className` | `string` |  | Classes to add. |
+
+Remaining props go to the outer `<div>`, which carries `role="progressbar"` and `aria-valuenow`.
+
+## Formatting is up to you
+
+The centre is just your children. To show a real number rather than a percentage, write it there.
+
+```tsx
+<ProgressCircle value={3_400_000} max={5_000_000} radius={40} strokeWidth={8}>
+  <span className="text-xs">3.4M</span>
+</ProgressCircle>
+```

package/docs/en/parts/sample-data.md

@@ -0,0 +1,39 @@
+# SampleData
+
+> Marks the values inside it as sample values that are not yet connected to real data.
+
+Wrap a draft laid out before its queries are wired, or a screen built from column definitions only,
+and every card inside is marked as showing sample values. This is not the same as `provisional` on
+`KpiCard` and the charts, which means *preliminary*: real values that are not final yet. For a single
+value in running text or a heading, use [`Placeholder`](parts/placeholder) instead.
+
+```tsx
+import { SampleData, SampleBadge } from "@squadbase/vantage/components";
+import type { SampleDataProps, SampleBadgeProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | `"見本の値"` | Text of the mark. |
+| `children` | `ReactNode` |  | The cards to mark. |
+
+## How it behaves
+
+- **No box of its own.** It renders `display: contents`, so the grid of the parent still sees the
+  cards inside as its direct children, and `KpiCard` rows keep lining up.
+- **The card shows the mark.** The nearest `KpiCard` or `DashboardCardPreset` inside it puts a
+  `SampleBadge` in its header, once (also while loading). A card claims the mark, so parts anywhere
+  inside that card do not repeat it. Put a bare chart in a `DashboardCardPreset` to have it marked.
+- **The mark is a word, not only a colour.** It uses `--warning` on `--warning-subtle`, and its
+  `title` says what it means.
+
+```tsx
+<SampleData>
+  <KpiCard label="Revenue" value={12400000} format={{ type: "currency", currency: "JPY" }} />
+</SampleData>
+```
+
+## SampleBadge
+
+`SampleBadge` is the mark itself, for placing by hand. It takes `label` (default `"見本の値"`) and
+the usual `<span>` attributes.

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

@@ -0,0 +1,56 @@
+# ScatterChart
+
+> A typed scatter chart, or bubble chart with `size`. Shows how two numbers relate across items.
+
+Each row is one point: pass the column for the x axis (`x`) and the y axis (`y`). Add `size` for a
+bubble chart, `series` to colour by group, and `referenceLines` for targets or averages. Both axes
+fit the data rather than starting at 0, because a scatter plot is read by position. It renders
+inside [`ChartFrame`](parts/chart-frame).
+
+```tsx
+import { ScatterChart } from "@squadbase/vantage/components";
+import type { ScatterChartProps, ScatterReferenceLine } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | One row per point. **Required.** Rows whose x or y is not a number are not drawn. |
+| `x` | `NumericKeys<T>` |  | The column for the horizontal axis, e.g. `"adSpend"`. **Required.** |
+| `y` | `NumericKeys<T>` |  | The column for the vertical axis, e.g. `"revenue"`. **Required.** |
+| `size` | `NumericKeys<T>` |  | The column for point area; turns this into a bubble chart. Area is proportional from 0; `null` and values ≤ 0 get the smallest size. The value shows in the tooltip. |
+| `index` | `keyof T` |  | The column naming each point. It becomes the tooltip heading and the data table's first column. |
+| `labelKey` | `keyof T` |  | The column printed beside each point (store name, say). Overlapping labels are thinned; the tooltip always has it. With `highlight`, non-highlighted series get no label. |
+| `series` | `keyof T` |  | The column to split series by (e.g. `"channel"`). Each value gets a colour and a legend entry. Beyond five series, the five largest stay and the rest fold into a grey "Other". |
+| `seriesLabel` | `string` |  | A small heading to the left of the legend, shown only when a legend is shown. |
+| `highlight` | `string \| string[]` |  | Series (values of the `series` column) to bring forward. They are drawn opaque and in front; the rest fade behind. Ignored when nothing matches. |
+| `referenceLines` | `ScatterReferenceLine[]` |  | `{ axis: "x" \| "y"; value: number; label?: string }`. Draws a vertical (`x`) or horizontal (`y`) neutral line, widening the axis to include it. |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` |  | Series colours: an array in order of appearance, or a record by series name. "Other" is always grey. |
+| `labels` | `Record<string, string>` |  | Column name or series value → display name, used in axis titles, legend, tooltip and the data table. |
+| `format` | `ValueFormat` | `"compact"` | Default format for x, y and size. Override per axis with `xFormat` / `yFormat` / `sizeFormat`. |
+| `xFormat` | `ValueFormat` |  | Format of the x axis and x values. Wins over `format`. |
+| `yFormat` | `ValueFormat` |  | Format of the y axis and y values. Wins over `format`. |
+| `sizeFormat` | `ValueFormat` |  | Format of `size` values (tooltip, table). Wins over `format`. |
+| `valueFormatter` | `(value: number) => string` |  | Escape hatch: one function for x, y and size that wins over every `format`. |
+| `minValue` | `number` |  | Lower limit of the **y** axis. The axis widens if data falls below it. |
+| `maxValue` | `number` |  | Upper limit of the **y** axis. The axis widens if data exceeds it. |
+| `xMinValue` | `number` |  | Lower limit of the x axis. |
+| `xMaxValue` | `number` |  | Upper limit of the x axis. |
+| `fitToData` | `boolean` | `true` | Fit both axes to the data range. `false` starts both at 0. |
+| `showLegend` | `boolean` | `true` | Show the legend (only with two or more series). |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `title` | `string` |  | Heading of the chart. |
+| `summary` | `string \| "auto"` |  | `"auto"` builds one from the point count and the point with the largest y. Omitted means no summary. |
+| `isLoading` | `boolean` | `false` | Show a skeleton with the same height. |
+| `emptyState` | `ChartEmptyState` |  | Shown when `data` is empty or no point can be drawn. |
+| `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` | `false` | Show PNG save / copy buttons on hover. `{ includeTitle: false }` leaves the heading out of the image. |
+| `fileName` | `string` | `"chart.png"` | File name for the saved PNG. |
+| `ariaLabel` | `string` |  | Label read aloud when there is no `title`. |
+| `className` | `string` |  | Classes to add (on the outer figure). |
+
+## Comparing several charts
+
+To compare scatter plots side by side, give all of them the same `minValue` / `maxValue` and
+`xMinValue` / `xMaxValue` so the axes line up. To share one legend, set `showLegend={false}` on each
+and place a [`Legend`](parts/legend) next to them.

package/docs/en/parts/tracker.md

@@ -0,0 +1,36 @@
+# Tracker
+
+> A row of small blocks, one per period, coloured by status. For uptime and batch results.
+
+One period is one block, coloured by status. It suits **consecutive states**: daily uptime, batch
+success or failure, a daily target hit or missed. Hover a block to see its `tooltip`. It is plain
+HTML, not ECharts, and the colours follow the theme.
+
+```tsx
+import { Tracker } from "@squadbase/vantage/components";
+import type { TrackerBlock } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `TrackerBlock[]` |  | An array of `{ color?: ChartColor; tooltip?: string; key?: string \| number }`. **Required.** Oldest on the left. |
+| `defaultColor` | `ChartColor` |  | Colour of blocks with no `color`. Defaults to a lightened muted-foreground grey (for no data / not run). |
+| `hoverEffect` | `boolean` | `true` | Fade the block under the pointer. |
+| `className` | `string` |  | Classes to add. The height defaults to `h-6`. |
+
+Remaining props go to the outer `<div>`.
+
+## Assigning colours to states
+
+`color` is `"positive"` / `"negative"` / `"warning"` / `"info"` (the area tokens, `--<tone>-fill`),
+`"chart-1"` … `"chart-5"`, or a CSS colour.
+
+```tsx
+const COLOR = { ok: "positive", warn: "warning", error: "negative" } as const;
+
+<Tracker data={days.map((d) => ({ color: COLOR[d.status], tooltip: `${d.date} ${d.label}` }))} />
+```
+
+> [!NOTE]
+> Colour should not carry the meaning alone. Put the date and the state in `tooltip`; it is also the
+> block's accessible name (`role="img"`), and blocks with a tooltip are keyboard focusable.