@squadbase/vantage 0.6.2-dev1.9d91dda → 0.6.2-dev1.abc3f77

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

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

@@ -0,0 +1,52 @@
+# SlideChartInsight
+
+> One chart and its reading — the most common slide in a report.
+
+One chart (8 of 12 columns) and its reading (the other 4, up to 3 points). The chart is `line`, `bar` or `area`, built with canvas-size text, no tooltip and no animation, so it exports to pptx as it looks.
+
+```tsx
+import { SlideChartInsight } from "@squadbase/vantage/slide";
+import type { SlideChartInsightProps, SlideChartInsightChart } 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: the `asOf` / `source` line (「… 時点」/「出典: …」) cannot be overridden, while `title`, `insights`, `chart.categories` and `chart.series[].name` are your own text.
+
+## Props
+
+| Prop | Type | Default | 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.** Two or more series show a legend. |
+| `insights` | `string[]` |  | Points that read the chart, 2–3. **Required.** |
+| `chartSide` | `"left" \| "right"` | `"left"` | Which side the chart takes. |
+| `asOf` | `string` |  | The date the numbers were taken, date only (e.g. `"2026-10-01"`). The block adds 「時点」 once, so don't write it. The label is fixed in Japanese. |
+| `source` | `string` |  | Where the numbers come from (e.g. `"社内 BI"`). Shown as 「出典: 社内 BI」; the "出典:" label is fixed in Japanese. |
+
+## Usage
+
+```tsx
+import { Slide, SlideChartInsight } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideChartInsight
+    title="解約率は 6 月以降、毎月下がり続けている"
+    chart={{
+      type: "line",
+      categories: ["6 月", "7 月", "8 月", "9 月"],
+      series: [{ name: "解約率(%)", data: [2.7, 2.4, 2.1, 1.8] }],
+    }}
+    insights={[
+      "オンボーディング刷新後の 3 か月で 0.9pt 低下",
+      "低下は中小企業プランが中心",
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- More than 3 insights are still drawn but log a `console.warn` — split the slide.
+- Typed charts such as `LineChart` are not used; the block builds the chart with `EChart` directly.

package/docs/en/slide/slide-columns.md

@@ -0,0 +1,46 @@
+# SlideColumns
+
+> [Part] The 12-column layout of a slide's body — SlideColumns and SlideColumn.
+
+The 12-column layout of one slide's body. `SlideColumns` lays out `SlideColumn`s, each taking `span` of the 12 columns (8 / 4, 6 / 6, 4 / 4 / 4, …). It is a **part** for the body row of the grid, not a whole-slide block.
+
+```tsx
+import { SlideColumns, SlideColumn } from "@squadbase/vantage/slide";
+import type { SlideColumnsProps, SlideColumnProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> This is **a slide part**, not a whole-slide block. Place it as a row in the 12-column grid inside a `<Slide>`; its root does not fill the canvas (100%×100%). All dimensions are fixed inside the part, so do not add your own. For how to build a deck, see [Slide](page-types/slide).
+
+## Props
+
+### SlideColumns
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | The `SlideColumn`s. **Required.** |
+| `align` | `"start" \| "center" \| "stretch"` | `"stretch"` | Vertical alignment of the columns in the row. |
+
+### SlideColumn
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `span` | `number` | How many of the 12 columns it takes (1–12). **Required.** |
+| `children` | `ReactNode` | The column's content. **Required.** |
+
+## Usage
+
+```tsx
+import { SlideColumns, SlideColumn } from "@squadbase/vantage/slide";
+
+<SlideColumns align="center">
+  <SlideColumn span={8}>{/* chart */}</SlideColumn>
+  <SlideColumn span={4}>{/* reading */}</SlideColumn>
+</SlideColumns>
+```
+
+## Notes
+
+- The spans should add up to 12.
+- The gap and the number of columns come from the slide spec.
+- If a column's content must fill the column's height, set `height: "100%"` on that content.

package/docs/en/slide/slide-comparison.md

@@ -0,0 +1,68 @@
+# SlideComparison
+
+> A vs B, or before and after — 2 to 3 columns side by side.
+
+A slide that compares 2 to 3 columns side by side. Each column has a heading, one main number (with its change) and a few points; an optional `verdict` line sits underneath. The columns share the 12 columns equally (6 / 6 or 4 / 4 / 4).
+
+```tsx
+import { SlideComparison } from "@squadbase/vantage/slide";
+import type { SlideComparisonProps, SlideComparisonColumn } 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.** |
+| `columns` | `SlideComparisonColumn[]` | 2 to 3 columns. **Required.** Each column is described below. |
+| `verdict` | `string` | One line saying which side wins or what follows. |
+| `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」. |
+
+### SlideComparisonColumn
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `heading` | `string` |  | What the column is ("Old plan", "Before"). **Required.** |
+| `points` | `string[]` |  | Short points. **Required.** At most 3 per column, about 24 characters each. Write the same kind of point in each column, in the same order. |
+| `value` | `number \| null` |  | The main number. `null` shows 「—」. Formatted by `format`. |
+| `format` | `ValueFormat` |  | How to format the value (`"currency"`, `"percent"`, …). Also the default format of `delta`. |
+| `display` | `string` |  | A string you already formatted ("¥120M"). Wins over `value`. |
+| `delta` | `{ value: number \| null; format?: ValueFormat }` |  | The change of the main number itself (a ratio for `percent`). Its direction comes from the sign. Without `format`, the column's `format` is used. |
+| `comparisonLabel` | `string` |  | What `delta` is measured against (「前月比」, 「旧プラン比」). Printed muted before the change. |
+| `betterWhen` | `"up" \| "down"` | `"up"` | Which direction of `delta` is good. Use `"down"` for churn and cost. |
+
+## Usage
+
+```tsx
+import { Slide, SlideComparison } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideComparison
+    title="The new plan churns less than the old one"
+    columns={[
+      { heading: "Old plan", value: 0.024, format: "percent", points: ["¥9,800 per month", "No onboarding support"] },
+      {
+        heading: "New plan",
+        value: 0.018,
+        format: "percent",
+        delta: { value: -0.006 },
+        comparisonLabel: "旧プラン比",
+        betterWhen: "down",
+        points: ["¥12,800 per month", "With onboarding support"],
+      },
+    ]}
+    verdict="Onboarding support explains most of the gap"
+    asOf="2026-10-01"
+    source="BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- Fewer than 2 or more than 3 columns, or too many or too long points, log a console warning. Split the slide.
+- The change is drawn with `DeltaText` (▲ ▼ and 「増」/「減」). Polarity is set only by `betterWhen`.