@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.19083f7

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

@@ -0,0 +1,58 @@
+# KpiCard
+
+> One KPI as a card — value, change, previous actual and a one-line conclusion, all derived from numbers.
+
+A card that shows one KPI. **Pass numbers and enums only**, and it lays out, top to bottom: the metric
+name → the value → the change ([`Delta`](parts/delta)) → the previous actual → a
+one-sentence conclusion. Direction, rate, colour, remaining-to-target, achievement and record highs are
+all computed inside the card, so no two props can disagree. Reach for this before composing a KPI tile
+from `DashboardCardPreset` + `MetricValue`.
+
+```tsx
+import { KpiCard } from "@squadbase/vantage/components";
+import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | The metric name. **Required.** |
+| `value` | `number \| null \| undefined` |  | The current value. **Required.** `null` / `undefined` renders "—". |
+| `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. |
+| `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. |
+| `target` | `number` |  | Target for the current period; adds a remaining / achievement line. |
+| `period` | `{ start: Date \| string \| number; end: Date \| string \| number }` |  | The current period. With `target`, adds a pace projection (marked 見込み) while the period is in progress. |
+| `history` | `ReadonlyArray<number \| null \| undefined>` |  | Series ending at the current period (last point = `value`); adds a record badge. |
+| `historyGrain` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | `"month"` | The grain of `history`. |
+| `source` | `{ period?: string; count?: number; name?: string }` |  | A data-source footnote (period, row count, source name). |
+| `updatedAt` | `Date \| string \| number` |  | When the data was last refreshed; shown as relative time. |
+| `now` | `Date \| number` |  | Reference time for the projection and relative time (for deterministic rendering). |
+| `isLoading` | `boolean` | `false` | Render a skeleton with the final shape instead of the values. |
+| `className` | `string` |  | Classes to add. |
+
+## Summary placeholders
+
+`{value}` `{delta}` `{difference}` `{previous}` `{label}` `{target}` `{achievement}` `{remaining}`.
+Unknown placeholders are left as written; a known one whose value is missing becomes "—".
+
+> [!WARNING]
+> **Never put numbers in the template itself.** Insert every number through a placeholder, so the
+> sentence can't go stale when the value changes.
+
+```tsx
+<KpiCard
+  label="Revenue"
+  value={48_200_000}
+  format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }}
+  summary="{label} grew {difference} ({delta}) on last month."
+/>
+```
+
+The card's built-in wording (labels such as 前期比 and 目標まであと) is Japanese. To place just the
+change inside a table or tile, use [`Delta`](parts/delta) on its own.

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/metric-value.md

@@ -2,7 +2,8 @@
 
 > The KPI number, with MetricUnit for the unit.
 
-A tight-tracking display for a KPI's number. Units and other trailing text go in `MetricUnit`.
+A tight-tracking display for a KPI's number. Units and other trailing text go in `MetricUnit`. For a whole KPI
+tile, consider [`KpiCard`](parts/kpi-card) first — it also shows the change and the previous actual.
 
 ```tsx
 import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage/components";
@@ -18,6 +19,6 @@ It carries vertical margin (`my-4`) by default. Inside a card, pass `className="
 ```tsx
 <DashboardCardPreset title="Revenue">
   <MetricValue className="my-0">$12,400</MetricValue>
-  <TrendIndicator value={12.4} direction="up" />
+  <Delta value={12_400} comparison={{ previous: 11_030, vs: "prior-period" }} />
 </DashboardCardPreset>
 ```

package/docs/en/parts/page-shell.md

@@ -27,7 +27,7 @@ import {
 | Part | Role |
 | --- | --- |
 | `PageShell` | The outer stack |
-| `PageShellHeader` | The underlined header band: heading on the left, `HeaderEnd` on the right |
+| `PageShellHeader` | The underlined header band: heading on the left, `HeaderEnd` on the right. When the row is too narrow, `HeaderEnd` wraps below the heading |
 | `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | The heading block |
 | `PageShellHeaderEnd` | The right-hand stack |
 | `PageShellMeta` | Asides such as "updated 10 minutes ago" |

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

@@ -44,4 +44,4 @@ series. `Sparkline` conveys the *shape* of a series and nothing else — **no ti
 > [!NOTE]
 > It is `aria-hidden="true"`, so screen readers skip it. Put the actual number next to it as text —
 > [`MetricValue`](parts/metric-value) or
-> [`TrendIndicator`](parts/trend-indicator).
+> [`Delta`](parts/delta).

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.

package/docs/en/parts/trend-indicator.md

@@ -1,6 +1,22 @@
 # TrendIndicator
 
-> An arrow and a percentage; positiveIsGood decides the colour.
+> Deprecated — use Delta for new code. An arrow and a percentage.
+
+> [!WARNING]
+> **Deprecated. Use [`Delta`](parts/delta) in new code.** `TrendIndicator` takes the
+> direction and colour by hand, so the value and the arrow can disagree. `Delta` computes direction,
+> rate, colour and label from the current and compared values. To show a KPI as a card, use
+> [`KpiCard`](parts/kpi-card).
+
+```tsx
+// Before
+<TrendIndicator value={12.4} direction="up" />
+<TrendIndicator value={0.4} direction="down" positiveIsGood={false} />
+
+// After
+<Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} polarity="lower-is-better" />
+```
 
 Shows a change as an arrow plus a percentage. **Up doesn't always mean good**, so the colour comes
 from `direction` combined with `positiveIsGood` — pass `positiveIsGood={false}` for metrics like

package/docs/en/parts/updated-at.md

@@ -0,0 +1,30 @@
+# UpdatedAt
+
+> A freshness label such as "23 minutes ago". Shows the absolute time and zone on hover.
+
+Renders a `<time>` whose `dateTime` is the ISO instant. The absolute time and zone
+(`2026/10/20 16:41 JST`) appear in both a tooltip and the `title` attribute. The label text is
+Japanese, in the form "23 分前に更新".
+
+```tsx
+import { UpdatedAt } from "@squadbase/vantage/components";
+import type { UpdatedAtProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `at` | `Date \| string \| number` |  | When the data was last updated. **Required.** |
+| `variant` | `"relative" \| "absolute-first"` | `"relative"` | `"relative"` reads "23 分前に更新". `"absolute-first"` reads "16:41 更新（23 分前）", with the date added when it is not today. Use it on pages where "now" matters. |
+| `timeZone` | `string` |  | IANA time zone for the absolute time (e.g. `"Asia/Tokyo"`). Defaults to the runtime's zone. |
+| `prefix` | `string` |  | Text placed before the label, e.g. `"売上データ: "`. |
+| `now` | `Date \| number` |  | A fixed "current time" for tests and fixtures. It also disables the 60-second refresh. |
+| `className` | `string` |  | Classes to add. |
+
+## Hydration
+
+The text depends on the clock and time zone of whoever renders, so the first render (server and
+client) is an empty `<time>` carrying only the ISO `dateTime`. After mount it fills in the label and
+refreshes every 60 seconds; the interval is cleared on unmount. The `<time>` sets
+`suppressHydrationWarning`, so sample data built from `Date.now()` at module load does not warn.
+
+Within a minute of `now`, the label reads "たった今" ("just now").

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

@@ -0,0 +1,56 @@
+# WaterfallChart
+
+> A typed waterfall chart. Shows how steps move a running total, such as revenue to gross profit.
+
+Pass the steps as rows, the name column (`index`) and the amount column (`categories`), and it draws
+a waterfall instead of you writing an ECharts option. Each row moves the running total by its value;
+rows named in `totals` are bars from 0 to the total. Every step also prints its signed amount, so
+colour is never the only carrier of direction. It renders inside
+[`ChartFrame`](parts/chart-frame).
+
+```tsx
+import { WaterfallChart } from "@squadbase/vantage/components";
+import type { WaterfallChartProps, WaterfallMode } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | The steps, left to right in row order. **Required.** |
+| `index` | `keyof T` |  | The column holding each step's name. **Required.** |
+| `categories` | `NumericKeys<T>[]` |  | The amount column as a one-element array. **Required.** Only the first is used. Values are numbers or numeric strings. |
+| `totals` | `string[]` |  | The `index` values of rows that are totals (e.g. `["Revenue", "Gross profit"]`). A total with a `null` value takes the running total so far; with a value, that value becomes the total and later steps continue from it. |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | Whether an increase is good. Increases and decreases use `--positive-fill` / `--negative-fill`; `lower-is-better` swaps them (for churn, say), `neutral` uses one neutral colour. |
+| `mode` | `"total" \| "delta"` | `"total"` | `"total"` draws totals as bars from 0. `"delta"` draws only the moves on a cumulative-change axis from 0, prints the opening and closing values in a note above the plot, and appends a net-change bar. Use it when the moves are small against the total (roughly under 5%). |
+| `labels` | `Record<string, string>` |  | Step name → display name, used on the axis, in the tooltip and the data table. Pass the `index` key to rename the table's first column. |
+| `minValue` | `number` |  | Lower limit of the value axis. The axis always includes 0, so only values ≤ 0 matter. It widens rather than clips. Pass the same `minValue` / `maxValue` to charts you compare side by side. |
+| `maxValue` | `number` |  | Upper limit of the value axis. It widens rather than clips. |
+| `yAxisWidth` | `number` |  | Width of the y-axis labels in px. Fix it to align the plot areas of stacked charts. |
+| `showValues` | `boolean` | `true` | Print the signed amount on each bar (totals show the running total). |
+| `showTooltip` | `boolean` | `true` | Show the tooltip (change and running total) on hover. |
+| `format` | `ValueFormat` | `"compact"` | Number format: `"compact"`, `"number"`, `"currency"`, `"percent"`, `{ type, unit, … }`. |
+| `valueFormatter` | `(value: number) => string` |  | Escape hatch: a function that wins over `format`. |
+| `title` | `string` |  | Heading of the chart. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary. `"auto"` builds one from the steps (first and last value, biggest increase and decrease). Omitted means no summary. |
+| `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` | `false` | Show PNG save / copy buttons on hover. Title and summary are included in the image; turn that off with `{ includeTitle: false }`. |
+| `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). |
+
+## Total or delta
+
+When the moves are tiny next to the total, a `total` waterfall flattens them into hairlines on a tall
+axis. Switch to `mode="delta"` so the axis is the change itself.
+
+```tsx
+<WaterfallChart
+  data={rows}
+  index="step"
+  categories={["amount"]}
+  totals={["Revenue", "Gross profit"]}
+  summary="auto"
+/>
+```

package/docs/en/slide/slide-chart-full.md

@@ -0,0 +1,48 @@
+# SlideChartFull
+
+> One chart across all 12 columns, with a one-line note under it.
+
+A slide that gives one chart the full width — for many categories or a long series. A one-line `note` under the chart can say how to read it or what to watch.
+
+```tsx
+import { SlideChartFull } from "@squadbase/vantage/slide";
+import type { SlideChartFullProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> This is **the content of one `<Slide>`**. It does not include `<Slide>` itself, so put it directly inside one. The root fills the canvas (1920×1080) at 100% and takes no `className`. Margins, text sizes and the grid are fixed inside the block (a 12-column grid on 1920×1080), so don't add your own dimensions. For how to build a deck, see [Slide](page-types/slide). The labels the block adds (「… 時点」, 「出典: …」) are fixed in Japanese; `title`, `lead`, `points` and the like are your own text.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The conclusion as one sentence (an action title). **Required.** |
+| `chart` | `SlideChartInsightChart` | `{ type: "line" \| "bar" \| "area"; categories: string[]; series: { name: string; data: number[] }[] }`. **Required.** Same shape and rendering as `SlideChartInsight`. Two or more series show a legend. |
+| `note` | `string` | One line under the chart: how to read it or what to watch. About 60 characters at most. |
+| `asOf` | `string` | The date the numbers were taken, date only (e.g. `"2026-10-01"`). Shown as 「2026-10-01 時点」; don't write 「時点」 yourself. |
+| `source` | `string` | Where the numbers come from (e.g. `"BI"`). Shown as 「出典: BI」. |
+
+## Usage
+
+```tsx
+import { Slide, SlideChartFull } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideChartFull
+    title="Revenue hit a record high in September"
+    chart={{
+      type: "line",
+      categories: ["Apr", "May", "Jun", "Jul", "Aug", "Sep"],
+      series: [{ name: "Revenue (¥M)", data: [460, 480, 490, 500, 503, 540] }],
+    }}
+    note="September includes two large deals"
+    asOf="2026-10-01"
+    source="BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- The chart is an `EChart` with no animation and no tooltip. The pptx export waits for it (`data-waitfor="canvas"`).
+- To put reading points next to the chart, use `SlideChartInsight` instead.