@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.1197de7

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

@@ -38,10 +38,10 @@ import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/co
 
 ## EChart との使い分け
 
-軸・凡例・ツールチップ・複数系列が要るなら [`EChart`](parts/echart) を使います。
+軸・凡例・ツールチップ・複数系列が要るなら、まず型付きグラフ（[`LineChart`](parts/line-chart)・[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)）を使い、細かい制御が要るときだけ [`EChart`](parts/echart) を使います。
 `Sparkline` が持つのは「値の並びの形」だけで、**目盛りも数値も出しません**。
 
 > [!NOTE]
 > `aria-hidden="true"` が付いているため、スクリーンリーダーには読まれません。実際の数値は
 > [`MetricValue`](parts/metric-value) や
-> [`TrendIndicator`](parts/trend-indicator) など、テキストとして隣に置いてください。
+> [`Delta`](parts/delta) など、テキストとして隣に置いてください。

package/docs/ja/parts/tracker.md

@@ -0,0 +1,32 @@
+# Tracker
+
+> 期間ごとの状態を小さなブロックの列で示す。稼働状況やバッチの結果に。
+
+1 期間 = 1 ブロックで状態を色分けして並べます。日ごとの稼働状況・バッチの成否・日次目標の
+達成 / 未達のような**連続した状態**に向きます。ブロックにホバーすると `tooltip` が出ます。
+ECharts を使わない HTML で、配色はテーマに追従します。
+
+```tsx
+import { Tracker } from "@squadbase/vantage/components";
+import type { TrackerBlock, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `TrackerBlock[]` |  | `{ color?: ChartColor; tooltip?: string; key?: string \| number }` の配列。**必須**。左から古い順。 |
+| `defaultColor` | `ChartColor` |  | `color` の無いブロックの色。既定は muted-foreground を淡くした灰色（データ無し・未実行に）。 |
+| `hoverEffect` | `boolean` | `true` | ホバー中のブロックを薄くする。 |
+| `className` | `string` |  | 足すクラス。高さは既定 `h-8`。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## 状態に色を割り当てる
+
+`color` はトークン名か CSS カラーです。失敗に `var(--destructive)` を使うと、テーマの
+破壊的操作の色と揃います。
+
+```tsx
+const COLOR = { ok: "chart-2", warn: "chart-3", error: "var(--destructive)" } as const;
+
+<Tracker data={days.map((d) => ({ color: COLOR[d.status], tooltip: `${d.date} ${d.label}` }))} />
+```

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

@@ -1,6 +1,22 @@
 # TrendIndicator
 
-> 増減の矢印と変化率。良し悪しは positiveIsGood で決まる。
+> 非推奨。新規は Delta を使う。増減の矢印と変化率。
+
+> [!WARNING]
+> **非推奨です。新規のコードでは [`Delta`](parts/delta) を使ってください。**
+> `TrendIndicator` は向き（`direction`）と色を手で渡すため、値と矢印が食い違うことがあります。`Delta` は今期と
+> 比較相手の値から向き・率・色・ラベルを計算します。KPI をカードで見せるなら
+> [`KpiCard`](parts/kpi-card) を使います。
+
+```tsx
+// 旧
+<TrendIndicator value={12.4} direction="up" />
+<TrendIndicator value={0.4} direction="down" positiveIsGood={false} />
+
+// 新
+<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" />
+```
 
 前期比などの変化を、矢印と変化率で示します。**「上がった＝良い」とは限らない**ので、色は
 `direction` と `positiveIsGood` の組み合わせで決まります — 解約率のように下がる方が良い指標では

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

@@ -1,6 +1,6 @@
 # ファイルベースルーティング
 
-> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド / ドキュメント）。
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
@@ -46,92 +46,13 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 
 ## tsx 以外もページになる
 
-ルートになるのは `.tsx` / `.jsx` だけではありません。**`.csv` と `.xlsx`** はそのまま表として
-読めるページになり、**`<name>.slide.tsx`** はスライドデッキに、**`<name>.doc.tsx`** はドキュメントになります。どれも URL の作り方は
-tsx と同じで、`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
+ルートになるのは `.tsx` / `.jsx` だけではありません。**`<name>.slide.tsx`** はスライドデッキに、
+**`<name>.doc.tsx`** はドキュメントに、**`.csv` と `.xlsx`** はそのまま表として読めるページに
+なります。どれも URL の作り方は tsx と同じで、`.slide` / `.doc` と拡張子は URL に出ません
+（`june.slide.tsx`・`june.csv` → `/june`）。`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
 
-### データファイル（`.csv` / `.xlsx`）
-
-`src/data/june.xlsx` を置いて `/data/june` を開くと、ダウンロードせずブラウザ上で表として
-読めます。xlsx は複数シートを切り替えられ、元ファイルをダウンロードする導線も付きます。
-
-描かれるのは**表計算ソフトそのものの見た目**です —— 列は A / B / C、左に行番号、ファイルの
-1 行目はヘッダとして固定され、罫線はデータの外まで続きます。シートのタブは下端に並びます。
-読み取り専用なので編集もソートもできません(セルを選んで `Cmd/Ctrl+C` でコピーはできます)。
-並べ替えや絞り込みが要るデータは、`server/api/` から配って `DataTable` で描いてください。
-
-- **タイトルはファイル名から導かれます**（`june.xlsx` → 「June」、`index.csv` はディレクトリ名）。
-  データファイルに `definePage` は書けないので、名前を変えたいときはファイルをリネームします。
-- **パースはブラウザで行われます。** dev・ビルド後・デプロイ後で同じコードが同じバイトを読むので、
-  同じ URL が同じものを返します。25MB を超えるファイルはそのページにエラーが出ます
-  （`vantage check` が `FILE_PAGE_TOO_LARGE` で先に警告します）。
-- 数式・グラフ・セル書式は再現されません。**値として読めれば十分**という設計です。
-- ページにしたくないファイルは `_` を前置します（`_june.xlsx`）。tsx から自分で描きたいときは
-  こうしてルート化を止め、`@squadbase/vantage/table` の `FilePageView` を使います。
-
-> [!WARNING]
-> **ビューアの無い拡張子はルートになりません。** `.xls` / `.ods` / `.tsv` などを置いても
-> 404 にすらならず、ナビにも `vantage routes` にも出ません。`vantage check` の
-> `UNSUPPORTED_PAGE_FILE` 警告が唯一の告知点です。
-
-### スライド（`.slide.tsx`）
-
-`.slide` は**ページ種別サフィックス**で、URL には出ません（`src/june.slide.tsx` → `/june`）。
-中身は `<SlideDeck>` を返す普通の React コンポーネントなので、`definePage` もナビも
-通常のページと同じように効きます。
-
-```tsx
-import { definePage } from "@squadbase/vantage";
-import { Slide, SlideDeck } from "@squadbase/vantage/slide";
-
-export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" });
-
-export default function Deck() {
-  return (
-    <SlideDeck>
-      <Slide>…</Slide>
-      <Slide>…</Slide>
-    </SlideDeck>
-  );
-}
-```
-
-1920×1080 の固定キャンバスに書き、画面サイズに合わせて縮小されます。キーボードとクリックで
-送れ、左のスライド一覧は `L` で開閉、`F` で全画面、ツールバーから pptx を書き出せます。詳しくは
-[UI とテーマ](ui-and-theming)。
-
-> [!WARNING]
-> `.slide` を付けられるのは**ルートになるページモジュールだけ**です。`_layout.slide.tsx` や
-> `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。また `june.slide.tsx` と
-> `june.tsx`、`sales.csv` と `sales.tsx` はいずれも同じ URL に解決するので `ROUTE_CONFLICT` です。
-
-### ドキュメント（`.doc.tsx`）
-
-`.doc` も**ページ種別サフィックス**です（`src/june-summary.doc.tsx` → `/june-summary`）。上から下へ
-読む文章のページで、中身は `<Document>` を返す普通の React コンポーネントです。
-
-```tsx
-import { definePage } from "@squadbase/vantage";
-import { Document } from "@squadbase/vantage/doc";
-
-export const page = definePage({ title: "6月度サマリー" });
-
-export default function JuneSummary() {
-  return (
-    <Document>
-      <h1>6月度サマリー</h1>
-      <p>6月の売上は目標を 5% 上回りました。</p>
-      <table>…</table>
-    </Document>
-  );
-}
-```
-
-`<Document>` の中の見出し・段落・リスト・表・引用・コードには、クラスを書かなくてもスタイルが
-当たります。詳しくは [UI とテーマ](ui-and-theming)。右下の「PDF として保存」ボタン(ブラウザの
-言語が日本語以外なら「Save as PDF」)から印刷ダイアログを開けます。印刷されるのはドキュメントの本文
-だけで、アプリのヘッダーやサイドバーは載らず、ダークモードでもライトの配色で出ます。`.slide` と
-同じく、`.doc` を付けられるのはルートになるページモジュールだけです。
+それぞれの書き方・できること・制限、そして**置いてもページにならないファイル**（`.xls`・`.tsv`・
+`.md` など）は [ページの種類](page-types) にまとめてあります。
 
 ## ルーティングされないディレクトリ
 
@@ -291,3 +212,4 @@ setSegments((prev) => [...prev, "enterprise"]);
 ## 次に読む
 
 - [ページと definePage](pages-and-metadata) — ページの契約とメタデータ
+- [ページの種類](page-types) — スライド・ドキュメント・CSV・Excel

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 枚目以降へ。