@squadbase/vantage 0.6.2-dev1.d7c0911 → 0.6.2-dev1.e85faec

package/docs/ja/parts/legend.md

@@ -0,0 +1,36 @@
+# Legend
+
+> 複数のグラフで共有する、HTML だけの独立した凡例。
+
+複数のグラフで同じ系列を見せるとき、各グラフの凡例を消して、凡例を 1 つにまとめます。**系列名の配列
+（`categories`）**を渡すだけで、`DonutChart` と同じ見た目（角丸の色見本と名前）の凡例が出ます。色はグラフと
+同じ関数で決まるので、グラフに渡した `categories` / `colors` / `labels` と同じ値を渡せば食い違いません。
+キャンバスも SVG も使わない HTML です。
+
+```tsx
+import { Legend } from "@squadbase/vantage/components";
+import type { LegendProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `categories` | `string[]` |  | 凡例に並べる系列名。**必須**。並び順が配色の順。空配列なら何も描かない。6 つ以上はグラフ側で「その他」にまとまるので、凡例も 5 つ +「その他」で渡す。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"` か意味色。配列は系列の順、record は系列名ごと。「その他」は常に灰色。意味色は棒の面の色（`--warning-fill` など）で出る。 |
+| `labels` | `Record<string, string>` |  | 系列名 → 表示名。グラフの `labels` と同じものを渡す。 |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | 並べ方。`horizontal` は折り返す横並び、`vertical` は縦並び。 |
+| `ariaLabel` | `string` | `"凡例"` | 凡例の読み上げ名。 |
+| `className` | `string` |  | `<ul>` に足すクラス。 |
+
+## グラフの凡例を消す
+
+共有する側のグラフには `showLegend={false}` を渡します。
+
+```tsx
+<Legend categories={["東京店", "大阪店", "名古屋店"]} />
+<LineChart data={sales} index="month" categories={stores} showLegend={false} />
+<BarChart data={visitors} index="month" categories={stores} showLegend={false} />
+```
+
+> [!NOTE]
+> グラフに `colors` を渡しているときは、`Legend` にも同じ `colors` を渡してください。省略するとトークン順の
+> 色になり、グラフと食い違います。

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

@@ -8,48 +8,74 @@
 
 ```tsx
 import { LineChart } from "@squadbase/vantage/components";
-import type { LineChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+import type { LineChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
-| `index` | `string` |  | x 軸に使う列名。**必須**。 |
-| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
-| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
-| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
-| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
-| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
-| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `keyof T & string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `NumericKeys<T>[]` |  | 系列として描く列名（数値の列だけ渡せる）。**必須**。この順が凡例と配色の順。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `トークン順` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`。配列は系列の順、record は系列名ごと。CSS カラーは渡せない。 |
+| `labels` | `Record<string, string>` |  | `index` の値・系列名 → 表示名（軸・凡例・ツールチップ・データ表に反映）。例 `{ jan: "1 月", sales: "売上" }`。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、または `{ type, digits, currency, notation, unit, divisor, durationUnit }`。軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `lineOptions` | `LineChartOptions` |  | 折れ線固有の設定。`{ curveType, connectNulls, fitToData, targetLabelPosition }`（下の表）。 |
+| `forecast` | `{ data: ChartForecastRow[]; category?: string; label?: string }` |  | 予測。最初の系列（または `category`）の続きを点線と薄い帯で描く。`data` の行は実績と同じ `index` のキーに、`value`（と任意の `lower` / `upper`）を持つ。`label` の既定は「予測」。 |
+| `comparison` | `{ category: string; vs: "prior-period" \| "prior-year" \| "target" \| "custom"; label?: string }` |  | 比較系列。`categories` のうち 1 つを「前年」「計画」などの比較の線にする（細い灰色の実線）。ツールチップに主系列の差を添える。`vs: "custom"` では `label` が必須。 |
+| `highlight` | `"auto" \| "none"` |  | 最大値と最新値に値ラベルを付ける（最初の系列だけ・系列が 2 つ以下のときだけ）。既定は Line / Area が `"auto"`、Bar は `index` が日付・年月・年のときだけ `"auto"`。 |
+| `provisionalFrom` | `string \| number` |  | ここから先は確定前（速報）の点。`index` の値で渡す。薄い色・点線で描き、凡例とツールチップに `provisionalLabel` を出す。 |
+| `provisionalLabel` | `string` | `"速報"` | 速報の呼び名（凡例・ツールチップ）。 |
+| `target` | `number` |  | 目標値。点線の水平線で示し、値軸は必ずこの値を含む。 |
+| `targetLabel` | `string` | `「目標 <書式化した値>」` | 目標線のラベル。 |
+| `annotations` | `ChartAnnotation[]` |  | 任意の位置への注記。`{ at, label }` は縦線、`to` を足すと `at`〜`to` の区間の帯。`at` / `to` は `index` の値。横棒では描かない。 |
+| `showLegend` | `boolean` | `true` | 凡例を出す。 |
 | `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
 | `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
 | `showXAxis` | `boolean` | `true` | x 軸を出す。 |
 | `showYAxis` | `boolean` | `true` | y 軸を出す。 |
 | `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
 | `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
-| `minValue` | `number` |  | 値軸の下限。 |
-| `maxValue` | `number` |  | 値軸の上限。 |
-| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
-| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `minValue` | `number` |  | 値軸の下限。指定した値から始める。データが下限を下回るときは軸を広げる。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
 | `xAxisLabel` | `string` |  | x 軸の名前。 |
 | `yAxisLabel` | `string` |  | y 軸の名前。 |
-| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
-| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
-| `loading` | `boolean` |  | ローディング表示を出す。 |
-| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
-| `className` | `string` |  | 足すクラス。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点（棒）のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。見出しの下に出す。`"auto"` なら data から機械的に組む。向きの言い回しを手書きすると data とずれるので `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。`title` の既定は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列（CSS の長さ）は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。`title` / `summary` は画像の上に含まれる。含めないなら `{ includeTitle: false }`。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。`actions` と使う。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。見出しがあればそちらが使われる。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは `height` で決める。 |
+
+### lineOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 値の欠けた点（`null` など）をまたいで線をつなぐ。 |
+| `fitToData` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
+| `targetLabelPosition` | `"start" \| "end" \| "legend"` | `"start"` | 目標線（`target`）のラベルの置き場所。`"legend"` は凡例だけに出し、線の上には出さない。 |
+
+> [!NOTE]
+> `curveType` / `connectNulls` をグラフの props に直接渡す書き方、`autoMinValue`（`lineOptions.fitToData` を使う）、`loading`（`isLoading` を使う）は**非推奨**です。
 
 > [!NOTE]
-> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
-> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
 
 ## 欠損のある系列
 
-値が `null`・空文字・数値でない文字列の点は欠損として扱い、線が途切れます。`connectNulls` を
+値が `null`・空文字・数値でない文字列の点は欠損として扱い、線が途切れます。`lineOptions={{ connectNulls: true }}` を
 付けると欠損をまたいでつなぎます。
 
 ```tsx
-<LineChart data={rows} index="date" categories={["CVR"]} connectNulls valueFormatter={(v) => `${v}%`} />
+<LineChart data={rows} index="date" categories={["CVR"]} lineOptions={{ connectNulls: true }} valueFormatter={(v) => `${v}%`} />
 ```
 
 ## EChart との使い分け

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

@@ -0,0 +1,61 @@
+# SampleData
+
+> まだ実データにつながっていない「見本の値」に印を付ける。
+
+下書きの段階で、クエリをつなぐ前に並べた値を囲みます。囲んだ中の `KpiCard` と `DashboardCardPreset` が、見出しに
+**「見本の値」のバッジ**を出します。バッジは色だけでなく言葉で伝え、ツールチップで意味も説明します。実データを
+つなぎ終えたら `SampleData` を外します。
+
+```tsx
+import { SampleData, SampleBadge } from "@squadbase/vantage/components";
+import type { SampleDataProps, SampleBadgeProps } from "@squadbase/vantage/components";
+```
+
+## SampleData
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` | `"見本の値"` | 印の文言。 |
+| `children` | `ReactNode` |  | 印を付けたい部品。 |
+
+`SampleData` 自身は箱を持ちません（`display: contents`）。親の grid・subgrid から見ると中のカードが直接の子の
+ままなので、`KpiCard` の行の区切りは揃ったままです。
+
+カードは 1 枚につき印を 1 回だけ出します。`DashboardCardPreset` が見出しに出したら、その中のグラフや表は
+重ねて出しません。素のグラフに印を付けたいときは `DashboardCardPreset` に入れてください。
+
+## SampleBadge
+
+バッジ単体です。`SampleData` の外で、見本であることを自分で示したいときに使います。`<span>` の属性もそのまま渡せます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` | `"見本の値"` | 印の文言。 |
+| `className` | `string` |  | 足すクラス。 |
+
+## SampleClaim と useSampleMark
+
+自作のカード部品が `SampleData` に対応するための部品です。`useSampleMark()` は、いま印を出すべきなら
+`{ label }`、なければ `null` を返します。印を出したカードは、中身を `<SampleClaim>` で包んで、内側の部品が
+同じ印を繰り返さないようにします。
+
+```tsx
+import { SampleBadge, SampleClaim, useSampleMark } from "@squadbase/vantage/components";
+
+function MyCard({ title, children }: { title: string; children: React.ReactNode }) {
+  const mark = useSampleMark();
+  return (
+    <section>
+      <h3>
+        {title} {mark && <SampleBadge label={mark.label} />}
+      </h3>
+      <SampleClaim>{children}</SampleClaim>
+    </section>
+  );
+}
+```
+
+> [!NOTE]
+> `SampleData` は「実データにまだつながっていない」ことを示します。速報値のように、実データだが確定前の値は
+> `KpiCard` やグラフの `provisional` で示し、混ぜません。文中や見出しの中の値 1 つだけが仮なら
+> [`Placeholder`](parts/placeholder) を使います。同じ値に両方は付けません。

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

@@ -0,0 +1,69 @@
+# ScatterChart
+
+> 2 つの数値の関係と外れ値を見せる型付きの散布図。大きさを足せばバブルチャートになる。
+
+広告費と売上、客単価と購入頻度のように、2 つの数値の関係を点の位置で見ます。**行の配列（`data`）と、
+横軸・縦軸の列名（`x` / `y`）**を渡すだけで描けます。`size` でバブル、`series` で色分け（`--chart-1..5` を
+固定順）、`labelKey` で点の名前の表示ができます。散布図は位置で読むので、軸は既定でデータの範囲に合わせ、
+0 起点にしません。
+
+```tsx
+import { ScatterChart } from "@squadbase/vantage/components";
+import type { ScatterChartProps, ScatterReferenceLine } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 点。x か y が数値でない行は描かない。 |
+| `x` | `string` |  | 横軸に使う数値の列名。**必須**。 |
+| `y` | `string` |  | 縦軸に使う数値の列名。**必須**。 |
+| `size` | `string` |  | 点の面積に使う数値の列名。渡すとバブルチャートになる。0 を基準に面積が比例し、null・0 以下は最小の大きさ。 |
+| `index` | `string` |  | 点の名前の列名。ツールチップの見出しとデータ表の先頭列になる。 |
+| `labelKey` | `string` |  | 点の脇に書く文字の列名。重なるラベルは自動で間引く（ツールチップには常に出る）。`index` が無ければ名前も兼ねる。 |
+| `series` | `string` |  | 系列分けの列名。値ごとに色を分け、凡例を出す。6 つ以上は点の多い 5 つ +「その他」（灰色）にまとまる。 |
+| `seriesLabel` | `string` |  | 凡例の見出し。系列があって凡例が出るときだけ、凡例の左に小さく書く。 |
+| `highlight` | `string \| string[]` |  | 前面に出す系列（`series` 列の値）。指定した系列は不透明で手前に、指定外は薄く背面に描く。 |
+| `referenceLines` | `ScatterReferenceLine[]` |  | 基準線（目標・平均・しきい値）。`{ axis: "x" \| "y", value, label? }`。中立色の破線で、軸の範囲が線まで広がる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"` か意味色。配列は系列の出現順、record は系列名ごと。「その他」は常に灰色。 |
+| `labels` | `Record<string, string>` |  | 列名・系列の値 → 表示名（軸のタイトル・凡例・ツールチップ・データ表）。 |
+| `format` | `ValueFormat` | `"compact"` | x・y・size の既定の書式。 |
+| `xFormat` | `ValueFormat` |  | 横軸と x の値の書式。`format` より優先。 |
+| `yFormat` | `ValueFormat` |  | 縦軸と y の値の書式。`format` より優先。 |
+| `sizeFormat` | `ValueFormat` |  | `size` の値の書式（ツールチップ・データ表）。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。x・y・size すべてに使われ、`format` 系より優先。 |
+| `minValue` | `number` |  | 縦軸の下限。データが下回れば広がる。 |
+| `maxValue` | `number` |  | 縦軸の上限。データが超えれば広がる。 |
+| `xMinValue` | `number` |  | 横軸の下限。 |
+| `xMaxValue` | `number` |  | 横軸の上限。並べて比べる散布図には同じ範囲を渡す。 |
+| `fitToData` | `boolean` | `true` | 両軸をデータの範囲に合わせる。`false` で両軸を 0 から始める。 |
+| `showLegend` | `boolean` | `true` | 凡例を出す（系列が 2 つ以上のときだけ）。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `summary` | `string \| "auto"` |  | 1 文要約。`"auto"` で点の数と y が最大の点から組む。省略時は要約なし。 |
+| `title` | `string` |  | グラフの見出し。プロット領域の読み上げ名にもなる。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。既定の題は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。 |
+| `chartOptions` | `EChartsOption` |  | 生成した option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG 保存 / コピーのボタンを出す（ホバー時）。見出しと要約は既定で画像に含まれ、`includeTitle: false` で外せる。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `className` | `string` |  | 外枠（`<figure>`）のクラス。幅はここで決める。 |
+| `ariaLabel` | `string` |  | 見出しが無いときのプロット領域の読み上げ名。 |
+
+## 基準線と強調
+
+目標や平均は `referenceLines` で引きます。数が多い点の中に埋もれる少数の系列は `highlight` で手前に出し、
+残りを薄くします。
+
+```tsx
+<ScatterChart
+  data={rows}
+  x="spend"
+  y="roas"
+  series="channel"
+  highlight="SNS"
+  referenceLines={[{ axis: "y", value: 3, label: "目標 ROAS 3" }]}
+/>
+```
+
+> [!NOTE]
+> 幅が 480px 未満になると、ラベルは y が高い 2 点だけになり、凡例はプロットの下に移ります。

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

@@ -0,0 +1,27 @@
+# UpdatedAt
+
+> データの鮮度を示す更新時刻。相対時刻に、タイムゾーンつきの絶対時刻を添える。
+
+「23 分前に更新」のような鮮度の表示です。`<time>` 要素で、`dateTime` に ISO 形式の時刻を持ち、ツールチップと
+`title` に**タイムゾーンつきの絶対時刻**（「2026/10/20 16:41 JST」）が出ます。表示は 60 秒ごとに更新されます。
+「今」が大事なページでは `variant="absolute-first"` で「16:41 更新（23 分前）」と併記します。
+
+```tsx
+import { UpdatedAt } from "@squadbase/vantage/components";
+import type { UpdatedAtProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `at` | `Date \| string \| number` |  | データを最後に更新した時刻。**必須**。 |
+| `variant` | `"relative" \| "absolute-first"` | `"relative"` | `relative` は「23 分前に更新」。`absolute-first` は「16:41 更新（23 分前）」で、今日でなければ日付も付く。 |
+| `timeZone` | `string` |  | 絶対時刻に使う IANA タイムゾーン（`"Asia/Tokyo"` など）。省略時は実行環境のもの。 |
+| `prefix` | `string` |  | ラベルの前に置く文字（`"売上データ: "`）。 |
+| `now` | `Date \| number` |  | 「現在時刻」を固定する（テスト・見本用）。渡すと 60 秒ごとの更新を止める。 |
+| `className` | `string` |  | 足すクラス。 |
+
+1 分未満の差は「たった今」と出ます。
+
+> [!NOTE]
+> 最初の描画（サーバーとクライアント）は ISO の `dateTime` だけの空の `<time>` で、マウント後にラベルが入ります。
+> 表示が閲覧者の時計とタイムゾーンに依存するためで、ハイドレーションの不一致は起きません。

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

@@ -0,0 +1,61 @@
+# WaterfallChart
+
+> 増減の積み上がりを見せる型付きのウォーターフォール。売上から粗利までの内訳や、前期からの増減要因に。
+
+段ごとの増減が累計をどう動かすかを、階段状の棒で描きます。**行の配列（`data`）・段の名前の列（`index`）・
+金額の列（`categories`）**を渡し、合計の段は `totals` に名前で挙げます。合計の行の値は省けば直前までの累計を
+計算します。増加は `--positive-fill`、減少は `--negative-fill`、合計は `--chart-1`。各棒には符号つきの金額も
+書くので、色だけで向きを伝えません。縦軸は常に 0 を含みます。
+
+```tsx
+import { WaterfallChart } from "@squadbase/vantage/components";
+import type { WaterfallChartProps, WaterfallMode } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 段で、並びがそのまま左から右の順。値は number か数値文字列。null は棒を描かず「—」。 |
+| `index` | `string` |  | 段の名前に使う列名。**必須**。 |
+| `categories` | `string[]` |  | 金額の列名を 1 つだけ入れた配列（`["amount"]`）。**必須**。2 つ以上渡しても最初の 1 つだけを使う。 |
+| `totals` | `string[]` |  | 合計の段にする行の `index` の値。0 から累計まで届く棒になる。値が null なら直前までの累計。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | 増えるのが良いか。解約数のように増えて悪い指標は `lower-is-better` で増減の色が入れ替わる。`neutral` は増減とも中立色（符号は付く）。 |
+| `mode` | `"total" \| "delta"` | `"total"` | `delta` は増減の段だけを、開始を 0 とした累計増減の軸で描き、末尾に「純増」の棒を足す。開始・終了の値は図の上の注記に出る。合計に対して増減が小さい（目安 5% 未満）ときに使う。 |
+| `labels` | `Record<string, string>` |  | 段の名前 → 表示名（軸・ツールチップ・データ表）。無いキーはそのまま。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式（`"currency"` や `{ type: "number", unit: "件" }` など）。軸・棒のラベル・ツールチップで同じ。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先。 |
+| `minValue` | `number` |  | 縦軸の下限。軸は常に 0 を含むので 0 以下の値だけ有効。データが下回れば広がる。 |
+| `maxValue` | `number` |  | 縦軸の上限。データが超えれば広がる。並べて比べるグラフには同じ値を渡して軸をそろえる。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。並べたグラフのプロット領域を揃えたいときに固定する。 |
+| `showValues` | `boolean` | `true` | 各棒に符号つきの増減額（合計は累計）を書く。 |
+| `showTooltip` | `boolean` | `true` | ホバーで増減と累計を出す。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。`"auto"` で最初と最後の値、最大の増加・減少から組む。省略時は要約なし。 |
+| `title` | `string` |  | グラフの見出し。プロット領域の読み上げ名にもなる。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。既定の題は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。 |
+| `chartOptions` | `EChartsOption` |  | 生成した option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG 保存 / コピーのボタンを出す（ホバー時）。見出しと要約は既定で画像に含まれ、`includeTitle: false` で外せる。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `className` | `string` |  | 外枠（`<figure>`）のクラス。幅はここで決める。 |
+| `ariaLabel` | `string` |  | 見出しが無いときのプロット領域の読み上げ名。 |
+
+## 増減が小さいときは delta
+
+総額に対して増減が小さいと、棒が総額の高い軸に埋もれて線のようになります。`mode="delta"` にすると
+増減だけを 0 起点の累計で描き、最後に「純増」の棒を足します。`totals` に挙げた行（前期・当期）は棒にならず、
+図の上の注記になります。
+
+```tsx
+<WaterfallChart
+  data={rows}
+  index="item"
+  categories={["amount"]}
+  totals={["前期", "当期"]}
+  mode="delta"
+  format="currency"
+/>
+```
+
+> [!NOTE]
+> 解約数や原価のように増えて悪い値の段を並べるときは `polarity="lower-is-better"` にします。色の意味が
+> 入れ替わるだけで、棒の向きと符号は変わりません。

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

@@ -0,0 +1,48 @@
+# SlideChartFull
+
+> グラフ 1 つを 12 カラム全幅で見せる 1 枚。下に 1 行の注記。
+
+横幅が要るグラフ（カテゴリが多い・系列が長い）を全幅で見せる 1 枚です。グラフの下に、読み方や注目点を 1 行（`note`）で添えられます。
+
+```tsx
+import { SlideChartFull } from "@squadbase/vantage/slide";
+import type { SlideChartFullProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `chart` | `SlideChartInsightChart` | `{ type: "line" \| "bar" \| "area"; categories: string[]; series: { name: string; data: number[] }[] }`。**必須**。`SlideChartInsight` と同じ形・同じ描画。系列が 2 つ以上なら凡例が出る。 |
+| `note` | `string` | グラフの下の 1 行。読み方や注目点。60 文字ほどまで。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-01"`）。「2026-10-01 時点」と表示される。「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideChartFull } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideChartFull
+    title="売上は 9 月に過去最高を更新した"
+    chart={{
+      type: "line",
+      categories: ["4 月", "5 月", "6 月", "7 月", "8 月", "9 月"],
+      series: [{ name: "売上(百万円)", data: [460, 480, 490, 500, 503, 540] }],
+    }}
+    note="9 月は大型案件 2 件の計上を含む"
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- グラフは `EChart` でアニメーションなし・ツールチップなし。pptx への書き出しはその描画（`data-waitfor="canvas"`）を待ちます。
+- 読み解きの文を並べたいときは `SlideChartInsight` を使います。

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

@@ -0,0 +1,52 @@
+# SlideChartInsight
+
+> グラフ 1 つと、その読み解き。レポートでいちばん多い 1 枚。
+
+グラフ 1 つ（12 カラムのうち 8）と、その読み解き（残りの 4、最大 3 点）を並べる 1 枚です。グラフは `line` / `bar` / `area`。キャンバス用の文字サイズで、ツールチップとアニメーションなしで組まれるので、pptx に見た目のまま書き出せます。
+
+```tsx
+import { SlideChartInsight } from "@squadbase/vantage/slide";
+import type { SlideChartInsightProps, SlideChartInsightChart } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `chart` | `SlideChartInsightChart` |  | `{ type: "line" \| "bar" \| "area"; categories: string[]; series: { name: string; data: number[] }[] }`。**必須**。系列が 2 つ以上なら凡例が出る。 |
+| `insights` | `string[]` |  | グラフの読み解き。2〜3 点。**必須**。 |
+| `chartSide` | `"left" \| "right"` | `"left"` | グラフを置く側。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```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>
+```
+
+## 注意
+
+- 4 点以上の `insights` は描画されますが `console.warn` が出ます。スライドを分けてください。
+- 型付きグラフ（`LineChart` など）は使いません。この block が `EChart` で直接組みます。

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

@@ -0,0 +1,46 @@
+# SlideColumns
+
+> [部品] スライド本文の 12 カラム配置。SlideColumns と SlideColumn。
+
+スライド本文の 12 カラム配置です。`SlideColumns` の中に `SlideColumn` を並べ、それぞれが `span` カラム分を取ります（8 / 4、6 / 6、4 / 4 / 4 など）。グリッドの本文の行に置く**部品**で、1 枚まるごとの block ではありません。
+
+```tsx
+import { SlideColumns, SlideColumn } from "@squadbase/vantage/slide";
+import type { SlideColumnsProps, SlideColumnProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **スライドの部品**で、1 枚まるごとの block ではありません。`<Slide>` 内の 12 カラムのグリッドの行として置きます（ルートはキャンバスいっぱい（100%×100%）には広がりません）。寸法はすべて部品の中で決まっているので、足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+### SlideColumns
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | `SlideColumn` を並べる。**必須**。 |
+| `align` | `"start" \| "center" \| "stretch"` | `"stretch"` | 行の中での縦方向の揃え。 |
+
+### SlideColumn
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `span` | `number` | 12 カラムのうち何カラム分を取るか（1〜12）。**必須**。 |
+| `children` | `ReactNode` | 列の中身。**必須**。 |
+
+## 使い方
+
+```tsx
+import { SlideColumns, SlideColumn } from "@squadbase/vantage/slide";
+
+<SlideColumns align="center">
+  <SlideColumn span={8}>{/* グラフ */}</SlideColumn>
+  <SlideColumn span={4}>{/* 読み解き */}</SlideColumn>
+</SlideColumns>
+```
+
+## 注意
+
+- 並べた `span` の合計は 12 にします。
+- 間隔とカラム数はスライドの仕様値で決まっています。
+- 列の中身が列の高さいっぱいに広がるべきときは、その中身側で `height: "100%"` を指定します。

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

@@ -0,0 +1,68 @@
+# SlideComparison
+
+> A と B、施策の前と後を 2〜3 列で並べる 1 枚。
+
+2〜3 列を横に並べて比べる 1 枚です。各列に見出し・主役の数字（と増減）・要点を置き、下に 1 行の結論（`verdict`）を出せます。列は 12 カラムを等分します（6 / 6 または 4 / 4 / 4）。
+
+```tsx
+import { SlideComparison } from "@squadbase/vantage/slide";
+import type { SlideComparisonProps, SlideComparisonColumn } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `columns` | `SlideComparisonColumn[]` | 2〜3 列。**必須**。各列は下の表のとおり。 |
+| `verdict` | `string` | どちらが優れるか、何が続くかを 1 行で。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-01"`）。「2026-10-01 時点」と表示される。「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+### SlideComparisonColumn
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `heading` | `string` |  | その列が何か（「旧プラン」「施策前」）。**必須**。 |
+| `points` | `string[]` |  | 短い要点。**必須**。1 列 3 件まで、1 件 24 文字ほどまで。列ごとに同じ種類の要点を同じ順で書く。 |
+| `value` | `number \| null` |  | 主役の数字。`null` は「—」。`format` で整形される。 |
+| `format` | `ValueFormat` |  | 値の整形（`"currency"` / `"percent"` など）。`delta` の既定の整形にもなる。 |
+| `display` | `string` |  | 整形済みの文字列（「1.2 億円」）。`value` より優先される。 |
+| `delta` | `{ value: number \| null; format?: ValueFormat }` |  | 主役の数字の増減そのもの（`percent` なら比率）。向きは符号で決まる。`format` を省くと列の `format` を使う。 |
+| `comparisonLabel` | `string` |  | `delta` が何との比較かを示す名前（「前月比」「旧プラン比」）。増減の前に薄く出る。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | `delta` のどちらの向きが良いか。解約率・コストは `"down"`。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideComparison } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideComparison
+    title="新プランは旧プランより解約が少ない"
+    columns={[
+      { heading: "旧プラン", value: 0.024, format: "percent", points: ["月額 9,800 円", "導入支援なし"] },
+      {
+        heading: "新プラン",
+        value: 0.018,
+        format: "percent",
+        delta: { value: -0.006 },
+        comparisonLabel: "旧プラン比",
+        betterWhen: "down",
+        points: ["月額 12,800 円", "導入支援つき"],
+      },
+    ]}
+    verdict="導入支援の有無が解約率の差の主因"
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 列が 2〜3 でない、または要点が多い・長いと、コンソールに警告が出ます。スライドを分けてください。
+- 増減は `DeltaText`（▲ ▼ と「増」「減」つき）で描かれます。極性は `betterWhen` のみで指定します。

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

@@ -0,0 +1,39 @@
+# SlideCover
+
+> デッキの表紙。タイトル・サブタイトル・期間・作成者・時点を 1 枚に収める。
+
+デッキの表紙です。タイトルは左 8 カラムに置かれ、期間・作成者・時点は下端の 1 行にまとまります。
+
+```tsx
+import { SlideCover } from "@squadbase/vantage/slide";
+import type { SlideCoverProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | デッキの名前。**必須**。 |
+| `subtitle` | `string` | タイトルの下の 1 行。 |
+| `period` | `string` | 対象期間（「2026 年 7 月〜9 月」）。 |
+| `author` | `string` | 作成者・チーム名。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-20"`）。block が「2026-10-20 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```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>
+```
+
+## 注意
+
+- 表紙は 1 デッキに 1 枚です。2 枚目以降の見出しは他の block のアクションタイトルで書きます。
+- サブタイトルは目的や読み手を 1 行で。長い説明は 2 枚目以降へ。