@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.72360fb

package/docs/en/doc/doc-report-header.md

@@ -0,0 +1,46 @@
+# DocReportHeader
+
+> The opening of a document — title, subtitle, period, as-of, author and source.
+
+The section that opens a document: an `h1` title and a short fact sheet (`dl`) of period, data as-of, author and source. It is the only block that owns the `h1`; the rest start at `h2`.
+
+```tsx
+import { DocReportHeader } from "@squadbase/vantage/doc";
+import type { DocReportHeaderProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `subtitle` is a `string` or a `ReactNode`; Markdown strings are not parsed. The fact labels this block prints ("対象期間", "データ時点", "作成者", "出典") are fixed in Japanese and cannot be overridden, so an English page shows them in Japanese. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The document title (`h1`). State the subject and period, not a slogan. **Required.** |
+| `subtitle` | `ReactNode` | One line under the title (who it is for, …). A `string` or a `ReactNode`. |
+| `period` | `string` | The period the numbers cover ("2026 年 9 月", "2026-07-01 〜 2026-09-30"). |
+| `asOf` | `string` | The date the data was taken, as a date only ("2026-10-03"). The block adds the label "データ時点". |
+| `author` | `string` | Author. |
+| `source` | `string` | Where the numbers come from ("受注管理システム、会計システム"), as one string. |
+
+## Usage
+
+```tsx
+import { Document, DocReportHeader } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocReportHeader
+    title="2026 年 9 月 月次事業報告"
+    subtitle="経営会議向け"
+    period="2026-09-01 〜 2026-09-30"
+    asOf="2026-10-03"
+    author="事業企画チーム"
+    source="受注管理システム、会計システム"
+  />
+</Document>
+```
+
+## Notes
+
+- An empty fact is left out, row and all, instead of showing "—".
+- When printed, the whole header stays on one page; it does not break across pages.

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/data-table.md

@@ -56,6 +56,28 @@ it.
 
 `useDataTable()` gives a child component the TanStack `table` instance directly.
 
+## Column formats and CSV export
+
+A column without `cell` can format its number with `meta.format` (right-aligned, tabular-nums; null shows `meta.nullLabel`, default `—`). Pass a function when the currency changes per row. `DataTableExport` writes a BOM-prefixed UTF-8 CSV in the same sorted, filtered order as the screen; with `DataTablePreset`, `exportable` alone adds it to the toolbar.
+
+```tsx
+const columns: ColumnDef<Row>[] = [
+  { accessorKey: "month", header: "Month" },
+  {
+    accessorKey: "revenue",
+    header: "Revenue",
+    meta: { format: (row) => ({ type: "currency", currency: row.currency, notation: "standard" }) },
+  },
+];
+
+<DataTable columns={columns} data={rows}>
+  <DataTableToolbar toolbar={<DataTableExport fileName="sales.csv" />} />
+  <DataTableContent />
+</DataTable>;
+```
+
+`values="raw"` exports raw values; `scope="page"` exports only the visible page. For server-side paging, `rowCount` (total rows), `manualSorting`, `manualFiltering` and `isLoading` are also available.
+
 ## Paginating on the server
 
 Own `pagination` and `onPaginationChange`, and pass the total in `pageCount`.

package/docs/en/parts/delta.md

@@ -0,0 +1,51 @@
+# Delta
+
+> The change against a comparison — arrow, signed rate and label, all derived from the values.
+
+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 `betterWhen="down"` (`polarity` is the older name and still works).
+
+It replaces the deprecated [`TrendIndicator`](parts/trend-indicator).
+
+```tsx
+import { Delta } from "@squadbase/vantage/components";
+import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `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. |
+| `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. |
+| `showLabel` | `boolean` | `true` | Show the comparison label ("前期比") after the percent. |
+| `className` | `string` |  | Classes to add. |
+
+## Comparison
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `previous` | `number \| null \| undefined` | The value compared against. `null` or `0` yields no rate, shown as "—". |
+| `vs` | `"prior-period" \| "prior-year" \| "target"` | The kind of comparison. Default labels: 前期比 / 前年同期比 / 目標比. |
+| `label` | `string` | Override the label (e.g. "vs last week"). |
+
+## Migrating from TrendIndicator
+
+```tsx
+// Before: direction and colour chosen by hand
+<TrendIndicator value={12.4} direction="up" />
+
+// After: pass the current and previous values
+<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" }} betterWhen="down" />
+```
+
+The colours come from the `--positive` / `--negative` / `--neutral` tokens. To show a KPI as a whole
+card, [`KpiCard`](parts/kpi-card) uses `Delta` inside.

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/format.md

@@ -0,0 +1,43 @@
+# format / comparison
+
+> The number formatting (formatValue) and change calculation (computeComparison) shared by KPIs, tables and charts.
+
+The formatting and comparison logic that `KpiCard` / `Delta` use internally, exposed as functions. Use
+them when a table cell or a chart's `valueFormatter` should match the KPIs. Shortening (e.g. "4.8億")
+is left to `Intl.NumberFormat`; no unit strings are hard-coded.
+
+```tsx
+import {
+  formatValue,
+  formatDelta,
+  toValueFormatter,
+  computeComparison,
+} from "@squadbase/vantage/components";
+import type { ValueFormat, Comparison, ComparisonResult } from "@squadbase/vantage/components";
+```
+
+## ValueFormat
+
+One of `"number" | "compact" | "currency" | "percent" | "multiple"`, or `{ type, digits?, currency? }`.
+The default format is `"compact"`, the default currency `JPY`, the default locale `"ja-JP"`. `percent`
+takes a ratio (`0.124` → 12.4%). `null` / `undefined` / `NaN` format as "—".
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `formatValue(value, format?, locale?)` | `string` | Format a value. |
+| `formatDelta(value, format?, locale?)` | `string` | For differences: always signed except zero (`+12.4%`). |
+| `toValueFormatter(format?, locale?)` | `(value) => string` | A one-argument formatter with the format and locale bound — fits a chart's `valueFormatter`. |
+
+```tsx
+formatValue(48_200_000, "currency");                // "￥48,200,000"
+formatValue(0.021, { type: "percent", digits: 1 }); // "2.1%"
+<LineChart valueFormatter={toValueFormatter("compact")} … />
+```
+
+## computeComparison
+
+`computeComparison(current, comparison, { polarity?, neutralBand? })` returns
+`{ current, previous, difference, ratio, direction, sentiment, label, vs }`. A rate is produced only
+when the previous value is a non-zero number; moves inside `neutralBand` (default 0.01) give
+`direction: "flat"`. `sentiment` (`"positive" | "negative" | "neutral"`) follows `polarity`. Leave the
+rendering to [`Delta`](parts/delta) rather than building arrows and colours yourself.

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"` |  |