@squadbase/vantage 0.6.1-dev2.5f947f1 → 0.6.2-dev1.25d59a0

package/docs/ja/page-types/slide.md

@@ -0,0 +1,132 @@
+# スライド
+
+> <name>.slide.tsx を置くとスライドデッキのページになる。1920×1080 のキャンバス、段階表示、トランジション、pptx 書き出し。
+
+`<name>.slide.tsx` を置くと、そのページは**スライドデッキ**になります（`src/june.slide.tsx` →
+`/june`）。分析の結論を誰かに伝えるときの形です。下のプレビューはクリックか `→` で送れます。
+
+## 置き方
+
+中身は `<SlideDeck>` を返す普通の React コンポーネントです。`<Slide>` 1 つが 1 枚になります。
+
+```tsx
+// src/june.slide.tsx  →  /june
+import { definePage } from "@squadbase/vantage";
+import { Slide, SlideDeck, Step, Steps } from "@squadbase/vantage/slide";
+
+export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" });
+
+export default function Deck() {
+  return (
+    <SlideDeck>
+      <Slide>
+        <h1 style={{ fontSize: 96 }}>売上は目標を 5% 上回った</h1>
+      </Slide>
+      <Slide>
+        <Steps>
+          <Step><p style={{ fontSize: 48 }}>1. 関東の既存顧客が +8%</p></Step>
+          <Step><p style={{ fontSize: 48 }}>2. 中部の新規開拓が立ち上がった</p></Step>
+        </Steps>
+      </Slide>
+    </SlideDeck>
+  );
+}
+```
+
+## できること
+
+- **画面サイズに合わせて縮小。** スライドは 1920×1080 の固定キャンバスに px で書き、表示先に
+  合わせて拡大縮小されます。ノート PC でもプロジェクターでも同じ見た目です。
+- **キーボードとクリックで送る。** `→` / `Space` / `PageDown` で次へ、`←` / `PageUp` で前へ、
+  `Home` / `End` で最初と最後へ。スライドの左右をクリックしても送れます。
+- **段階表示。** `<Steps>` の中の `<Step>` は、次へ進むたびに 1 つずつ現れます。
+- **トランジション。** `<Slide transition={…}>` で入り方を決めます。同じ `id` の
+  `<MorphElement>` を前後のスライドに置き `morph: true` にすると、その要素が連続して動きます。
+- **3 つの見え方。** 左にスライド一覧（`L` で開閉）、スライドのみ、全画面（`F`）。一覧の開閉と
+  今のページは URL（`?rail=` / `?p=`）に入るので、そのまま共有できます。`Esc` でデッキを抜けます。
+- **PowerPoint に書き出す。** ツールバーのボタンで、全スライドを `.pptx` として保存します。
+- **テーマに追従。** 配色と書体は `--slide-*` トークンで、既定はアプリのトークンを指すので
+  ダークモードにも追従します。デッキごとに `theme` で上書きできます。
+
+ダッシュボードの中に 16:9 の枠として埋め込むときは `<SlideDeck embedded>` にします
+（既定は画面全体を覆い、アプリのナビはその下に残ります）。
+
+## 制限
+
+- **pptx は画像で書き出されます。** 受け取り側にフォントが要らず日本語も崩れませんが、
+  PowerPoint で文字を検索・編集することはできません。
+- **発表者ノートや発表者用ウィンドウはありません。**
+- **スライドの中で `@squadbase/vantage/ui` を使わないでください。** UI キットはダッシュボード向けの
+  rem 単位なので、1920×1080 を縮小すると `text-sm` のボタンは実効 8px ほどになり読めません。
+- iframe の中など、ブラウザが全画面を許さない場所では全画面ボタンが出ません。
+- `.slide` を付けられるのはルートになる `.tsx` / `.jsx` だけです
+  （[ページにならないファイル](page-types)）。
+
+キャンバスの縦方向の予算・文字サイズの目安・pptx 書き出しが崩れる条件など、書き方の作法は同梱の
+**`vantage-slide` スキル**にあります（[エージェント Skill](agent-skills)）。
+
+## API
+
+```tsx
+import {
+  SlideDeck, Slide, Steps, Step, MorphElement,
+  useSlideNumber, useIsActiveSlide,
+} from "@squadbase/vantage/slide";
+```
+
+### SlideDeck
+
+デッキの器です。子に `<Slide>` を並べます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `theme` | `SlideTheme` |  | このデッキだけ配色・書体を上書きする。省いた項目はアプリのテーマに従う。 |
+| `embedded` | `boolean` | `false` | 画面全体を覆わず、ページの流れの中に 16:9 で置く。 |
+| `rail` | `boolean` | `!embedded` | スライド一覧を開いた状態で始めるか。読み手は `L` でいつでも切り替えられる。 |
+| `exportName` | `string` | `URL の最後のセグメント` | 書き出す pptx のファイル名（拡張子なし）。 |
+
+`SlideTheme` のキー: `bg`・`fg`・`accent`・`muted`・`fontDisplay`・`fontBody`（CSS の値）、
+`sizeHero`・`sizeBody`・`radius`（キャンバス上の px）。
+
+### Slide
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `transition` | `SlideTransition` | このスライドに入るときの動き。省くと切り替えは一瞬。 |
+
+`SlideTransition` は `duration`（ms、必須）・`easing`・`enter` / `exit`（Web Animations の
+`keyframes` を持つ）・`morph`（`true` か `{ duration, easing, delay }`）を持ちます。
+
+```tsx
+<Slide
+  transition={{
+    duration: 500,
+    enter: { keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+    morph: true,
+  }}
+>
+```
+
+### Steps / Step
+
+`<Steps>` の直下に置いた `<Step>` が、次へ進むたびに 1 つずつ現れます。前のスライドから戻ってきた
+ときは、すべて出た状態で表示されます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | `180` | `Step` に渡す。フェードインの長さ（ms）。 |
+
+### MorphElement
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `id` | `string` | 前後のスライドで同じ値を付けた要素どうしが、連続して動く。 |
+| `className` | `string` | 足すクラス。子が 1 つの HTML 要素ならそこへ、それ以外はラッパーの `<div>` へ付く。 |
+| `style` | `CSSProperties` | `className` と同じ要素に足すスタイル。 |
+
+### フック
+
+| 名前 | 返すもの |
+|---|---|
+| `useSlideNumber()` | `{ current, total }`。ページ番号のフッター用 |
+| `useIsActiveSlide()` | 今見えているスライドかどうか。入場アニメーションを始める合図に使う |

package/docs/ja/page-types.md

@@ -0,0 +1,47 @@
+# ページの種類
+
+> 通常ページ・スライド・ドキュメント・CSV・Excel の 5 種類。それぞれの置き方とできること、ページにならないファイル。
+
+Vantage のページは **5 種類**あります。どれもファイルを置くだけでページになり、URL の作り方は同じ
+です（[ファイルベースルーティング](routing)）。違うのは「何が描かれるか」だけです。
+
+| 種類 | 置き方 | できること |
+|---|---|---|
+| 通常ページ | `sales.tsx` | ダッシュボード。表・チャート・フィルタを自由に組む |
+| [スライド](page-types/slide) | `june.slide.tsx` | 発表用のスライドデッキ。段階表示・トランジション・pptx 書き出し |
+| [ドキュメント](page-types/doc) | `june-summary.doc.tsx` | 上から読む報告書。クラス無しで組版され、PDF として保存できる |
+| [CSV](page-types/csv) | `sales-export.csv` | ファイルを置くだけで表として読める |
+| [Excel](page-types/excel) | `june.xlsx` | CSV と同じ表ビューアに、シートの切り替えが付く |
+
+- **`.slide` / `.doc` と拡張子は URL に出ません。** `june.slide.tsx`・`june.csv`・`june.tsx` は
+  どれも `/june` です。同じ URL に 2 つ置くと `vantage check` が `ROUTE_CONFLICT` エラーを出します。
+- **ナビにも同格で並びます。** `vantage routes` と `useRoutes()` には 5 種類が区別なく出て、
+  `kind`（`"module"` / `"file"`）と `variant`（`"slide"` / `"doc"`）で見分けられます。
+- 通常ページ・スライド・ドキュメントは React コンポーネントなので
+  [`definePage`](pages-and-metadata) が効きます。CSV と Excel はファイル名がタイトルになります。
+
+どれにするか迷ったら、**繰り返し見に来る数字はダッシュボード、誰かに伝える結論はスライド、
+残しておく説明はドキュメント、受け取ったデータをそのまま見せたいなら CSV / Excel** です。
+
+## ページにならないファイル
+
+ページ走査のルート（`src/` があればその中）に置いても、次のファイルはページになりません。
+
+| ファイル | どうなるか |
+|---|---|
+| `.xls`・`.xlsm`・`.xlsb`・`.ods`・`.tsv`・`.numbers`・`.parquet` | ルートにならない。`vantage check` が `UNSUPPORTED_PAGE_FILE` 警告を出す |
+| `.md`・`.json`・`.txt` など | 何も言わずに無視される（コードから読む用途があるため） |
+| `_` で始まるファイル（`_draft.tsx`・`_june.xlsx`） | プライベート。`_layout` などの予約名を除き、ルートにならない |
+| `~$june.xlsx` | Excel が開いている間に作るロックファイル。無視される |
+| `components/`・`hooks/`・`lib/` の中のファイル | 走査されない（`server/`・`public/` も同じ） |
+
+ビューアの無い表計算ファイルは、404 にすらならず**黙って消えます**。ナビにも `vantage routes` にも
+出ないので、`vantage check` の警告が唯一の手がかりです。`.xlsx` か `.csv` に変換して置き直すか、
+`.tsx` のページから [`TableViewer`](page-types/excel) で描いてください。
+
+Markdown（`.md`）はページになりません。Markdown を見せたいときは `.tsx` のページで
+[`MarkdownRenderer`](markdown/markdown-renderer) に文字列を渡します。
+
+> [!WARNING]
+> `.slide` / `.doc` を付けられるのは**ルートになるページモジュール（`.tsx` / `.jsx`）だけ**です。
+> `_layout.slide.tsx` や `deck.slide.ts`、`notes.doc.css` は `INVALID_PAGE_VARIANT` エラーになります。

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

@@ -0,0 +1,61 @@
+# AreaChart
+
+> 推移を面で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。
+
+時系列の推移を面で描きます。ECharts の option を組む代わりに、**行の配列（`data`）・x 軸の列名（`index`）・
+系列の列名（`categories`）**を渡すだけで、凡例・ツールチップ・軸の書式まで揃います。配色は
+`--chart-1`〜`--chart-5` のトークンに追従し、ライト / ダークを切り替えても追いかけます。中身は
+[`EChart`](parts/echart) です。
+
+```tsx
+import { AreaChart } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartColor, 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 桁区切り。 |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` は積み上げ、`percent` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
+| `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` で目盛りを整数に限る。 |
+| `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` |  | 足すクラス。 |
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 構成比の推移を見る
+
+`type="percent"` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
+ツールチップには**元の値**が `valueFormatter` で出ます。
+
+```tsx
+<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} type="percent" />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

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

@@ -0,0 +1,69 @@
+# BarChart
+
+> 比較を棒で見せる型付きグラフ。横並び・積み上げ・横棒に切り替えられる。
+
+カテゴリごとの値を棒で比べます。**行の配列（`data`）・カテゴリの列名（`index`）・系列の列名（`categories`）**
+を渡すだけで描け、`type` で横並び / 積み上げ / 100% 積み上げ、`layout` で縦棒 / 横棒を切り替えます。
+配色はトークンに追従します。中身は [`EChart`](parts/echart) です。
+
+```tsx
+import { BarChart } from "@squadbase/vantage/components";
+import type { BarChartProps, ChartColor, 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 桁区切り。 |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `default` は横並び、`stacked` は積み上げ、`percent` は各カテゴリの合計を 100% にした積み上げ。 |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` はカテゴリを縦に並べた**横棒**（先頭の行が一番上）。ラベルの長いランキング向け。 |
+| `barCategoryGap` | `string \| number` |  | カテゴリ間の隙間（`"30%"` や px）。 |
+| `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` で目盛りを整数に限る。 |
+| `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` |  | 足すクラス。 |
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 横棒のランキング
+
+ラベルが長いときは `layout="vertical"` で横棒にします。`yAxisWidth` でラベル幅を固定すると、
+長いラベルは省略されます。行の順に上から並ぶので、並べ替えは `data` 側で済ませてください。
+
+```tsx
+<BarChart
+  data={stores}
+  index="store"
+  categories={["売上"]}
+  layout="vertical"
+  yAxisWidth={96}
+  showLegend={false}
+/>
+```
+
+数件のランキングを軸なしで並べるだけなら、[`BarList`](parts/bar-list) のほうが軽く、
+カードにも収まります。
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

package/docs/ja/parts/bar-list.md

@@ -0,0 +1,35 @@
+# BarList
+
+> 名前と値を横棒で並べるランキング。軸なしで、カードに収まる軽さ。
+
+名前と値の組を、値に比例した淡い横棒で並べます。アクセスの多いページ・店舗別の売上・
+エラーの種類別件数のような**上位 N 件**に向きます。ECharts を使わない HTML なので、カードの中に
+いくつ置いても軽く、配色はテーマに追従します。
+
+```tsx
+import { BarList } from "@squadbase/vantage/components";
+import type { BarListItem, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `BarListItem[]` |  | `{ name: string; value: number; href?: string; key?: string; color?: ChartColor }` の配列。**必須**。 |
+| `valueFormatter` | `(value: number) => string` |  | 右端の数値の書式。既定は 3 桁区切り。 |
+| `sortOrder` | `"descending" \| "ascending" \| "none"` | `"descending"` | 並べ順。`none` は渡した順。 |
+| `color` | `ChartColor` | `"chart-1"` | バーの色（淡く塗る）。行ごとに変えるなら `data[].color`。 |
+| `showAnimation` | `boolean` | `false` | マウント時にバーを伸ばす。 |
+| `onValueChange` | `(item: BarListItem) => void` |  | 渡すと行がボタンになり、クリックした行を受け取る（絞り込みの起点に）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## リンクにする
+
+`href` を持つ行は名前がリンクになります。`http(s)://` で始まるものは新しいタブで開きます。
+
+```tsx
+<BarList data={pages.map((p) => ({ name: p.path, value: p.views, href: p.url }))} />
+```
+
+棒の長さは**最大値に対する比**です。全体に対する割合を見せたいなら
+[`CategoryBar`](parts/category-bar) か [`DonutChart`](parts/donut-chart) を使います。

package/docs/ja/parts/category-bar.md

@@ -0,0 +1,36 @@
+# CategoryBar
+
+> 1 本の棒を区間に色分けし、現在値をマーカーで示す。
+
+1 本の棒を `values` の比で色分けし、区切りに累計値を出します。`marker` を渡すと、その値の位置に
+目印が立ちます。スコアの判定帯（要改善 / 標準 / 良好）・予算の消化・構成比の 1 本表示に向きます。
+ECharts を使わない HTML で、配色はテーマに追従します。
+
+```tsx
+import { CategoryBar } from "@squadbase/vantage/components";
+import type { CategoryBarMarker, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `values` | `number[]` |  | 各区間の幅（相対値）。**必須**。合計が 100 である必要はない。負の値は 0 扱い。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 区間の色（順に対応）。`"chart-1"`〜`"chart-5"` か CSS カラー。 |
+| `marker` | `CategoryBarMarker` |  | `{ value: number; tooltip?: string; showAnimation?: boolean }`。`value` は `values` の合計と同じ尺度。 |
+| `showLabels` | `boolean` | `true` | 棒の上に区切りの累計値を出す。狭い区間のラベルは省く。 |
+| `valueFormatter` | `(value: number) => string` |  | 区切りの数値の書式。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## 判定帯に色を合わせる
+
+`colors` は区間の順に対応します。「悪い → 良い」の帯なら、暖色から寒色へ並べると読みやすく
+なります。マーカーの色は、乗っている区間の色になります。
+
+```tsx
+<CategoryBar
+  values={[60, 20, 20]}
+  colors={["chart-5", "chart-3", "chart-2"]}
+  marker={{ value: 72, tooltip: "今月のスコア: 72" }}
+/>
+```

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

@@ -55,6 +55,28 @@ import type { ColumnDef, SortingState, PaginationState } from "@squadbase/vantag
 
 `useDataTable()` を使うと、子コンポーネントから TanStack の `table` インスタンスを直接触れます。
 
+## 列の書式と CSV 書き出し
+
+`cell` を書かない列は `meta.format` で数値を整形できます（右寄せ・tabular-nums、null は `meta.nullLabel`、既定 `—`）。行ごとに通貨が変わるときは関数で渡します。`DataTableExport` は画面と同じ並べ替え・絞り込み後の順で、BOM 付き UTF-8 の CSV を書き出します。`DataTablePreset` なら `exportable` だけで toolbar に置けます。
+
+```tsx
+const columns: ColumnDef<Row>[] = [
+  { accessorKey: "month", header: "月" },
+  {
+    accessorKey: "revenue",
+    header: "売上",
+    meta: { format: (row) => ({ type: "currency", currency: row.currency, notation: "standard" }) },
+  },
+];
+
+<DataTable columns={columns} data={rows}>
+  <DataTableToolbar toolbar={<DataTableExport fileName="sales.csv" />} />
+  <DataTableContent />
+</DataTable>;
+```
+
+`values="raw"` で生の値、`scope="page"` で表示中のページだけを書き出せます。サーバー側でページングするときは `rowCount`（総件数）・`manualSorting`・`manualFiltering`・`isLoading` も使えます。
+
 ## サーバー側でページングする
 
 `pagination` と `onPaginationChange` を自分で持ち、`pageCount` に総ページ数を渡します。

package/docs/ja/parts/delta.md

@@ -0,0 +1,50 @@
+# Delta
+
+> 比較相手に対する増減。矢印・符号付きの率・比較ラベルを値から導く。
+
+値の変化を「↑ +12.4% 前期比」の 1 行で示します。**向き・率・色・文言はすべて `value` と `comparison`
+から計算**され、外から渡すことはできません — そのため矢印と色が食い違うことがありません。色だけに
+頼らず、矢印と符号が必ず付きます。解約率のように上がると悪い指標は `polarity="lower-is-better"` を
+渡してください。
+
+非推奨の [`TrendIndicator`](parts/trend-indicator) の置き換えです。
+
+```tsx
+import { Delta } from "@squadbase/vantage/components";
+import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number \| null \| undefined` |  | 現在の値。**必須**。前の値は `comparison` から取る。 |
+| `comparison` | `Comparison` |  | 比較の相手。**必須**（増減に必ずラベルが付くように）。下の表を参照。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | 上がることが良いか。 |
+| `neutralBand` | `number` | `0.01` | 変化率の絶対値がこれ未満なら横ばい（–）として扱う。既定は 1%。 |
+| `variant` | `"badge" \| "inline"` | `"badge"` | 枠付きのバッジか、文中に置く素の文字か。 |
+| `locale` | `string` | `"ja-JP"` | 率の書式のロケール。 |
+| `showLabel` | `boolean` | `true` | 率のあとに比較ラベル（「前期比」）を出すか。 |
+| `className` | `string` |  | 足すクラス。 |
+
+## Comparison
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `previous` | `number \| null \| undefined` | 比較相手の値。`null` や `0` のときは率が出せないので「—」になる。 |
+| `vs` | `"prior-period" \| "prior-year" \| "target"` | 比較の種類。ラベルは順に「前期比」「前年同期比」「目標比」。 |
+| `label` | `string` | ラベルを差し替える（「先週比」など）。 |
+
+## TrendIndicator からの置き換え
+
+```tsx
+// 旧: 向きと色を手で決めていた
+<TrendIndicator value={12.4} direction="up" />
+
+// 新: 今期と前期の値を渡すだけ
+<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" />
+```
+
+色は `--positive` / `--negative` / `--neutral` のトークンで決まります。KPI を 1 枚のカードで見せる
+なら [`KpiCard`](parts/kpi-card) が中で `Delta` を使います。

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

@@ -0,0 +1,47 @@
+# DonutChart
+
+> 構成比を見せる型付きのドーナツ / 円グラフ。中央に合計を出す。
+
+構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`category`）・値の列（`value`）**
+を渡すだけで描け、ドーナツの穴には合計（または `label`）が出ます。中央のラベルはキャンバスではなく
+HTML なので、ページの文字色・書体のまま表示されます。配色はトークンに追従します。
+
+```tsx
+import { DonutChart } from "@squadbase/vantage/components";
+import type { DonutChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 切片。 |
+| `category` | `string` |  | 切片の名前に使う列名。**必須**。 |
+| `value` | `string` |  | 切片の大きさに使う列名。**必須**。number か数値文字列。0 以下と欠損は 0 扱い。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 切片の色（行の順）。`"chart-1"`〜`"chart-5"` か CSS カラー。足りなければ繰り返す。 |
+| `variant` | `"donut" \| "pie"` | `"donut"` | 穴あき（中央ラベルあり）か、円か。 |
+| `valueFormatter` | `(value: number) => string` |  | ツールチップと中央ラベルの書式。 |
+| `label` | `ReactNode` |  | 中央ラベル。省略時は合計を `valueFormatter` で書いたもの。 |
+| `showLabel` | `boolean` | `true` | 中央ラベルを出す（donut のみ）。 |
+| `showTooltip` | `boolean` | `true` | ホバーで名前・値・構成比を出す。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 切片のクリックで呼ばれる。行に `eventType: "slice"` と `categoryClicked`（切片名）を足して渡し、同じ切片をもう一度押すと `null`。 |
+| `loading` | `boolean` |  | ローディング表示を出す。 |
+| `ariaLabel` | `string` |  | チャートの説明。 |
+| `className` | `string` | `"size-40"` | 外枠のクラス。大きさはここで決める。 |
+
+## 凡例を添える
+
+凡例は持ちません（切片が 5 つ程度ならツールチップで足りるため）。並べて見せたいときは、
+行ごとに同じ色を当てた [`BarList`](parts/bar-list) や表を隣に置いてください。
+
+```tsx
+<div className="flex items-center gap-6">
+  <DonutChart data={rows} category="channel" value="sessions" label="9.7万" className="size-48" />
+  <BarList
+    data={rows.map((r, i) => ({ name: r.channel, value: r.sessions, color: `chart-${(i % 5) + 1}` }))}
+    sortOrder="none"
+    className="flex-1"
+  />
+</div>
+```
+
+> [!NOTE]
+> 切片が 6 つを超えると色が繰り返されます。小さい切片は「その他」にまとめてから渡してください。

package/docs/ja/parts/echart.md

@@ -7,6 +7,9 @@ Apache ECharts をそのまま使えるようにした薄いラッパーです
 系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから組まれ、
 ライト / ダークの切り替えにも追いかけます。
 
+> [!TIP]
+> まず型付きグラフ（[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)・[`LineChart`](parts/line-chart)・[`DonutChart`](parts/donut-chart)）を使い、二軸・散布図・ヒートマップなど細かい制御が要るときだけ `EChart` に option を書いてください。
+
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
 import type { EChartsOption } from "@squadbase/vantage/components";

package/docs/ja/parts/format.md

@@ -0,0 +1,44 @@
+# format / comparison
+
+> KPI・表・グラフで共有する数値の書式（formatValue）と、増減の計算（computeComparison）。
+
+`KpiCard` / `Delta` が内部で使っている数値の書式と比較の計算を、そのまま関数として使えます。表の
+セルやグラフの `valueFormatter` を KPI と同じ書式に揃えたいときに使ってください。短縮（「4.8億」
+など）は `Intl.NumberFormat` に任せており、単位の文字列を自前で持ちません。
+
+```tsx
+import {
+  formatValue,
+  formatDelta,
+  toValueFormatter,
+  computeComparison,
+} from "@squadbase/vantage/components";
+import type { ValueFormat, Comparison, ComparisonResult } from "@squadbase/vantage/components";
+```
+
+## ValueFormat
+
+`"number" | "compact" | "currency" | "percent" | "multiple"` のどれか、または
+`{ type, digits?, currency? }`。既定は `"compact"`、通貨の既定は `JPY`、ロケールの既定は `"ja-JP"`。
+`percent` は比率（`0.124` → 12.4%）を受け取ります。値が `null` / `undefined` / `NaN` のときは「—」を
+返します。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `formatValue(value, format?, locale?)` | `string` | 値を書式化する。 |
+| `formatDelta(value, format?, locale?)` | `string` | 差分用。0 以外は常に符号が付く（`+12.4%`）。 |
+| `toValueFormatter(format?, locale?)` | `(value) => string` | 書式とロケールを束ねた 1 引数の関数。グラフの `valueFormatter` に渡せる。 |
+
+```tsx
+formatValue(48_200_000, "currency");                // "￥48,200,000"
+formatValue(0.021, { type: "percent", digits: 1 }); // "2.1%"
+<LineChart valueFormatter={toValueFormatter("compact")} … />
+```
+
+## computeComparison
+
+`computeComparison(current, comparison, { polarity?, neutralBand? })` が
+`{ current, previous, difference, ratio, direction, sentiment, label, vs }` を返します。率は前の値が
+0 でない数のときだけ出し、`neutralBand`（既定 0.01）未満の変化は `direction: "flat"` になります。
+`sentiment`（`"positive" | "negative" | "neutral"`）は `polarity` で決まります。表示は
+[`Delta`](parts/delta) に任せ、自前で矢印や色を組まないでください。

package/docs/ja/parts/kpi-card.md

@@ -0,0 +1,55 @@
+# KpiCard
+
+> KPI 1 つ分のカード。値・増減・前期実績・結論の 1 文までを数値から組み立てる。
+
+KPI を 1 つ見せるカードです。**数値と列挙値だけを渡せば**、上から「指標名 → 値 → 増減
+（[`Delta`](parts/delta)）→ 前期の実績 → 結論の 1 文」の順に組み立てます。増減の向き・率・
+色・目標までの残り・達成率・記録更新はすべてカードの中で計算するので、props どうしが食い違うことは
+ありません。KPI タイルは `DashboardCardPreset` + `MetricValue` で組むより、まずこれを使ってください。
+
+```tsx
+import { KpiCard } from "@squadbase/vantage/components";
+import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` |  | 指標名。**必須**。 |
+| `value` | `number \| null \| undefined` |  | 現在の値。**必須**。`null` / `undefined` は「—」と表示する。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式（→ format / comparison のページ）。前期実績・目標・残りにも同じ書式を使う。 |
+| `locale` | `string` | `"ja-JP"` | 書式のロケール。 |
+| `comparison` | `Comparison` |  | 比較の相手（`{ previous, vs, label? }`）。渡すと増減と前期実績の行が出る。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | 上がることが良いか。解約率のように下がる方が良い指標は `"lower-is-better"`。 |
+| `neutralBand` | `number` | `0.01` | 変化率の絶対値がこれ未満なら横ばいとして扱う。 |
+| `showPrevious` | `boolean` | `true` | 前期の実績（「前期 400」）を出すか。`comparison` が要る。 |
+| `summary` | `string` |  | 結論の 1 文の**テンプレート**。下のプレースホルダをカードが埋める。 |
+| `target` | `number` |  | 今期の目標。「目標まであと …（… 達成）」の行が出る。 |
+| `period` | `{ start: Date \| string \| number; end: Date \| string \| number }` |  | 今期の期間。`target` と一緒に渡すと、期間中は「見込み」（このペースなら期末いくつ）が出る。 |
+| `history` | `ReadonlyArray<number \| null \| undefined>` |  | 今期で終わる系列（最後の点 = `value`）。記録更新のバッジが出る。 |
+| `historyGrain` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | `"month"` | `history` の粒度。 |
+| `source` | `{ period?: string; count?: number; name?: string }` |  | データの出所の注記（「2023-04 以降・48,210 件から集計・Snowflake」）。 |
+| `updatedAt` | `Date \| string \| number` |  | 最終更新時刻。「3 分前に更新」と出る。 |
+| `now` | `Date \| number` |  | 見込みと相対時刻の基準時刻（表示を固定したいとき）。 |
+| `isLoading` | `boolean` | `false` | 値の代わりに、完成形と同じ形のスケルトンを出す。 |
+| `className` | `string` |  | 足すクラス。 |
+
+## summary のプレースホルダ
+
+`{value}` `{delta}` `{difference}` `{previous}` `{label}` `{target}` `{achievement}` `{remaining}` が
+使えます。知らない名前はそのまま残り、値が無いものは「—」になります。
+
+> [!WARNING]
+> **テンプレートに数値を直接書かないでください。** 数値はすべてプレースホルダで差し込みます —
+> 値が変わっても文が古くならないようにするためです。
+
+```tsx
+<KpiCard
+  label="売上"
+  value={48_200_000}
+  format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }}
+  summary="{label}は前月から {difference}（{delta}）伸びています。"
+/>
+```
+
+増減だけを表やタイルの中に置きたいときは [`Delta`](parts/delta) を単体で使います。