@squadbase/vantage 0.6.2-dev1.01caa72 → 0.6.2-dev1.02aab78

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

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

@@ -0,0 +1,39 @@
+# SlideCover
+
+> The cover of a deck — title, subtitle, period, author and as-of line on one slide.
+
+The cover of a deck. The title sits in the left 8 columns; period, author and as-of go on one line at the foot.
+
+```tsx
+import { SlideCover } from "@squadbase/vantage/slide";
+import type { SlideCoverProps } 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 and cannot be overridden; `title`, `subtitle`, `period` and `author` are your own text.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The name of the deck. **Required.** |
+| `subtitle` | `string` | One line under the title. |
+| `period` | `string` | The period covered, e.g. "Jul–Sep 2026". |
+| `author` | `string` | Author or team. |
+| `asOf` | `string` | The date the numbers were taken, date only (e.g. `"2026-10-20"`). 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, SlideCover } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideCover title="2026 年度 第 2 四半期 事業レビュー" subtitle="売上・解約・新規獲得の振り返りと次の打ち手" period="2026 年 7 月〜9 月" author="事業企画チーム" asOf="2026-10-20" source="社内 BI" />
+</Slide>
+```
+
+## Notes
+
+- Use one cover per deck. Later slides carry their headline in the action title of the other blocks.
+- Keep the subtitle to one line of purpose or audience; move longer explanations to later slides.

package/docs/en/slide/slide-exec-summary.md

@@ -0,0 +1,47 @@
+# SlideExecSummary
+
+> The conclusion-first slide — an action title and 3–5 points.
+
+The conclusion-first slide. Under the action title it lists 3–5 points, each a one-line headline with an optional supporting line.
+
+```tsx
+import { SlideExecSummary } from "@squadbase/vantage/slide";
+import type { SlideExecSummaryProps, SlideExecSummaryPoint } 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 and cannot be overridden; `title`, `points[].headline` and `points[].detail` are your own text.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | The conclusion as one sentence (an action title). **Required.** |
+| `points` | `SlideExecSummaryPoint[]` |  | Points (`{ headline: string; detail?: string }`), 3–5 of them. **Required.** |
+| `layout` | `"rows" \| "columns"` | `"rows"` | `rows` stacks them numbered; `columns` puts them side by side (best with 3–4). |
+| `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, SlideExecSummary } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideExecSummary
+    title="Q2 は売上が計画を 4% 上回り、解約の改善が次の課題"
+    points={[
+      { headline: "売上は 5.4 億円で計画比 +4%", detail: "新規 38 社が牽引" },
+      { headline: "解約率は 1.8% まで低下", detail: "オンボーディング刷新の効果" },
+      { headline: "新規獲得は目標に 12 社届かず", detail: "紹介経由が想定の半分" },
+    ]}
+    asOf="2026-10-20"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- More than 5 points are still drawn but log a `console.warn` — split the slide.
+- Write `title` as a conclusion sentence, not a topic ("Sales status").

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

@@ -0,0 +1,38 @@
+# SlideHeading
+
+> [Part] The title of one slide — an action title with an optional eyebrow.
+
+The title of one slide: an `h2` at the page size, clamped to 2 lines, with an optional small label above it (`eyebrow`, e.g. the chapter). It is a **part** for the top row of a slide's 12-column grid, not a whole-slide block.
+
+```tsx
+import { SlideHeading } from "@squadbase/vantage/slide";
+import type { SlideHeadingProps } 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
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The conclusion as one sentence (an action title). Clamped to 2 lines. **Required.** |
+| `eyebrow` | `string` | A short label above the title ("Chapter 2: Churn"). |
+
+## Usage
+
+```tsx
+import { Slide, SlideHeading } from "@squadbase/vantage/slide";
+
+<Slide>
+  <div style={{ display: "grid", gridTemplateColumns: "repeat(12, 1fr)" }}>
+    <SlideHeading title="Churn has fallen every month since June" eyebrow="Chapter 2: Churn" />
+    {/* …SlideColumns and so on… */}
+  </div>
+</Slide>
+```
+
+## Notes
+
+- Write the title as the conclusion, not as a topic.
+- It spans all 12 columns of the grid it sits in.

package/docs/en/slide/slide-kpi-grid.md

@@ -0,0 +1,55 @@
+# SlideKpiGrid
+
+> A scoreboard of 2–4 KPIs — value, change and target.
+
+A scoreboard of 2–4 KPI cards side by side, each with label, value, change and target. They share the width equally.
+
+```tsx
+import { SlideKpiGrid } from "@squadbase/vantage/slide";
+import type { SlideKpiGridProps, SlideKpiGridItem, SlideKpiGridDelta } 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 and cannot be overridden; `title`, `items[].label`, `items[].display` and `items[].comparisonLabel` are your own text.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | The conclusion as one sentence (an action title). **Required.** |
+| `items` | `SlideKpiGridItem[]` |  | The KPIs, 2–4 of them. **Required.** Each item is described in the `items[].…` rows below. |
+| `items[].label` | `string` |  | The metric name. **Required.** |
+| `items[].value` | `number \| null` |  | The number. `null` shows 「—」. **Required.** Formatted with `format`. |
+| `items[].format` | `ValueFormat` |  | How to format the value (`"currency"`, `"percent"`, `{ type: "number", unit: "社" }`, …). Also the default format of `delta` and `target`. |
+| `items[].display` | `string` |  | Replaces the shown text only (the number behind it stays `value`, kept as `data-raw`). |
+| `items[].delta` | `SlideKpiGridDelta` |  | `{ value: number; format?: ValueFormat }`. The size of the change, signed (e.g. `0.074` with `format: "percent"` shows 「+7.4%」). The direction comes from the sign, and ▲ ▼ with 「増」「減」 always show. `format` defaults to the item's `format`. |
+| `items[].betterWhen` | `"up" \| "down"` | `"up"` | Which direction of `delta` is good. Drives the colour. |
+| `items[].comparisonLabel` | `string` |  | What `delta` is against (e.g. 「前月比」). |
+| `items[].target` | `number` |  | The target, in the same `format` as `value`. Shown as 「目標 …(達成率 …)」. The rate is value ÷ target (target ÷ value when `betterWhen` is `"down"`). |
+| `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, SlideKpiGrid } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiGrid
+    title="売上と継続率は計画どおり、新規獲得だけが未達"
+    items={[
+      { label: "月次売上", value: 540_000_000, format: "currency", delta: { value: 0.074, format: "percent" }, comparisonLabel: "前月比", target: 520_000_000 },
+      { label: "継続率", value: 0.982, format: { type: "percent", digits: 1 }, delta: { value: 0.004 }, comparisonLabel: "前月比", target: 0.98 },
+      { label: "新規獲得", value: 38, format: { type: "number", unit: "社" }, delta: { value: -4 }, comparisonLabel: "前月比", target: 50 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- More than 4 are still drawn but log a `console.warn` — split the slide.
+- Pass value, change and target as numbers. `format` formats them; use `display` only to change the shown text.
+- Wording such as 「目標 …(達成率 …)」 and 「増」/「減」 comes from the block and is fixed in Japanese.

package/docs/en/slide/slide-kpi-hero.md

@@ -0,0 +1,58 @@
+# SlideKpiHero
+
+> One number as the hero — value, change and a trend line.
+
+One number, large. The label, value and change take the left 6 columns and the trend line the right 6. Without `trend` the number takes the full width.
+
+```tsx
+import { SlideKpiHero } from "@squadbase/vantage/slide";
+import type { SlideKpiHeroProps, SlideKpiHeroDelta } 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 and cannot be overridden; `title`, `label`, `comparisonLabel` and `display` are your own text.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | The conclusion as one sentence (an action title). **Required.** |
+| `label` | `string` |  | What the number is ("Monthly revenue"). **Required.** |
+| `value` | `number \| null` |  | The number. `null` shows 「—」. **Required.** Formatted with `format` (the number is kept as `data-raw` for export and tests). |
+| `format` | `ValueFormat` |  | How to format the value (`"currency"`, `"percent"`, …). Also the default format of `delta`. |
+| `display` | `string` |  | Replaces the shown text only (the number behind it stays `value`). |
+| `delta` | `SlideKpiHeroDelta` |  | `{ value: number; format?: ValueFormat }`. The size of the change, signed (e.g. `0.074` with `format: "percent"` shows 「+7.4%」). The direction comes from the sign, and ▲ ▼ with 「増」「減」 always show. `format` defaults to the metric's `format`. Omit for no change. |
+| `betterWhen` | `"up" \| "down"` | `"up"` | Which direction of `delta` is good. Drives the colour. |
+| `comparisonLabel` | `string` |  | What `delta` is against (e.g. 「前月比」). |
+| `trend` | `{ x: string; y: number }[]` |  | Points of the line on the right; leave out for a number alone. |
+| `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, SlideKpiHero } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiHero
+    title="9 月の売上は過去最高の 5.4 億円"
+    label="月次売上"
+    value={540_000_000}
+    format="currency"
+    delta={{ value: 0.074, format: "percent" }}
+    comparisonLabel="前月比"
+    trend={[
+      { x: "4 月", y: 460_000_000 }, { x: "5 月", y: 480_000_000 }, { x: "6 月", y: 490_000_000 },
+      { x: "7 月", y: 500_000_000 }, { x: "8 月", y: 503_000_000 }, { x: "9 月", y: 540_000_000 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- For a metric where a fall is good (cost), write `betterWhen="down"`. The colour follows `betterWhen`; the direction (▲ ▼ and 「増」/「減」) comes from the sign of `delta.value`.
+- 「増」, 「減」, 「… 時点」 and 「出典: …」 are wording the block adds, fixed in Japanese.
+- The chart is an `EChart` with animation off; the pptx export waits for it.

package/docs/en/slide/slide-next-actions.md

@@ -0,0 +1,49 @@
+# SlideNextActions
+
+> What happens next — 3–5 actions with owner, due date and the metric to check.
+
+The closing slide of most reports: what happens next. Each action can carry an owner, a due date and the metric that shows it worked.
+
+```tsx
+import { SlideNextActions } from "@squadbase/vantage/slide";
+import type { SlideNextActionsProps, SlideNextActionsItem } 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 (the column headers 担当 / 期限 / 確認する指標, 「… 時点」, 「出典: …」) are fixed in Japanese and cannot be overridden; `title` and the `items[]` fields are your own text.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The decision or plan as one sentence. **Required.** |
+| `items` | `SlideNextActionsItem[]` | Actions, 3–5. **Required.** Each item is described in the `items[].…` rows below. |
+| `items[].action` | `string` | What to do, as one sentence starting from the object (about 40 characters at most). **Required.** |
+| `items[].owner` | `string` | The owner. |
+| `items[].due` | `string` | The due date, shown as written on one line ("10/31"; about 10 characters at most). |
+| `items[].metric` | `string` | What to look at to know it worked. |
+| `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, SlideNextActions } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideNextActions
+    title="解約と新規獲得の施策を 3 つ、11 月末までに始める"
+    items={[
+      { action: "解約予兆スコアの上位 50 社に CS が連絡する", owner: "CS 部 山田", due: "10/31", metric: "解約率 1.5% 以下" },
+      { action: "紹介プログラムの特典を見直す", owner: "マーケ 佐藤", due: "11/15", metric: "紹介経由の新規 20 社" },
+      { action: "料金ページの導線を改善する", owner: "プロダクト 鈴木", due: "11/30", metric: "申込率 +1pt" },
+    ]}
+  />
+</Slide>
+```
+
+## Notes
+
+- The owner, due and metric columns appear only when at least one item has a value.
+- The column headers (担当 / 期限 / 確認する指標) are fixed in Japanese and cannot be overridden.
+- `due` is shown as written ("10/31", "by next week"). More than 5 items log a `console.warn`.

package/docs/en/slide/slide-scorecard-table.md

@@ -0,0 +1,54 @@
+# SlideScorecardTable
+
+> A scorecard table — target vs actual per metric, with a status.
+
+A table of target, actual and attainment per metric with a status (on track / at risk / off track). The status is a coloured dot and a word, so colour is never the only cue.
+
+```tsx
+import { SlideScorecardTable } from "@squadbase/vantage/slide";
+import type { SlideScorecardTableProps, SlideScorecardRow, SlideScorecardStatus } 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 status words (順調 / 要注意 / 遅延) and the `asOf` / `source` line (「… 時点」, 「出典: …」) cannot be overridden. The header words can be replaced with `columns` (default 指標 / 目標 / 実績 / 達成率 / 状態); `title`, `rows[].metric` and `rows[].display` are your own text.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | The conclusion as one sentence (an action title). **Required.** |
+| `rows` | `SlideScorecardRow[]` |  | Rows, up to 8. **Required.** Each row is described in the `rows[].…` rows below. |
+| `rows[].metric` | `string` |  | The metric name (about 20 characters at most). **Required.** |
+| `rows[].value` | `number \| null` |  | The actual. `null` shows 「—」. **Required.** |
+| `rows[].format` | `ValueFormat` |  | How to format `value` and `target` (`"currency"`, `"percent"`, …). |
+| `rows[].display` | `string` |  | Replaces the shown actual only (the number behind it stays `value`). |
+| `rows[].target` | `number` |  | The target, in the same `format` as `value`. When any row has a target, the attainment column appears (value ÷ target). |
+| `rows[].betterWhen` | `"up" \| "down"` | `"up"` | Which direction is good. With `"down"` the rate is target ÷ value, so beating a cost target reads above 100%. |
+| `rows[].status` | `SlideScorecardStatus` |  | `"on"` (順調) / `"risk"` (要注意) / `"off"` (遅延). Given, not derived from the values. **Required.** |
+| `columns` | `Partial<Record<"metric" \| "target" \| "actual" \| "attainment" \| "status", string>>` |  | Override header words; omitted columns keep the default (指標 / 目標 / 実績 / 達成率 / 状態). The status words (順調 / 要注意 / 遅延) cannot be overridden. |
+| `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, SlideScorecardTable } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideScorecardTable
+    title="4 指標のうち 2 つが目標どおり、解約と新規が遅れている"
+    rows={[
+      { metric: "月次売上", value: 540_000_000, target: 520_000_000, format: "currency", status: "on" },
+      { metric: "継続率", value: 0.982, target: 0.98, format: { type: "percent", digits: 1 }, status: "on" },
+      { metric: "解約率", value: 0.018, target: 0.015, format: { type: "percent", digits: 1 }, betterWhen: "down", status: "risk" },
+      { metric: "新規獲得", value: 38, target: 50, format: { type: "number", unit: "社" }, status: "off" },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## Notes
+
+- From 7 rows the text drops from body to caption size. More than 8 are drawn with a `console.warn`.