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

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) を単体で使います。

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

@@ -0,0 +1,58 @@
+# LineChart
+
+> 推移を線で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。
+
+時系列の推移を折れ線で描きます。**行の配列（`data`）・x 軸の列名（`index`）・系列の列名（`categories`）**
+を渡すだけで、凡例・ツールチップ・軸の書式まで揃います。配色はトークンに追従します。中身は
+[`EChart`](parts/echart) です。
+
+```tsx
+import { LineChart } from "@squadbase/vantage/components";
+import type { LineChartProps, 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 桁区切り。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
+| `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"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 欠損のある系列
+
+値が `null`・空文字・数値でない文字列の点は欠損として扱い、線が途切れます。`connectNulls` を
+付けると欠損をまたいでつなぎます。
+
+```tsx
+<LineChart data={rows} index="date" categories={["CVR"]} connectNulls valueFormatter={(v) => `${v}%`} />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

package/docs/ja/parts/metric-value.md

@@ -2,7 +2,8 @@
 
 > KPI の数値。単位は MetricUnit で。
 
-KPI の数値を大きく見せるための、字送りを詰めた表示です。単位や補助的な文字は `MetricUnit` で
+KPI の数値を大きく見せるための、字送りを詰めた表示です。KPI のタイルを 1 枚作るなら、増減や前期実績まで
+出せる [`KpiCard`](parts/kpi-card) を先に検討してください。単位や補助的な文字は `MetricUnit` で
 添えます。
 
 ```tsx
@@ -20,6 +21,6 @@ import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage
 ```tsx
 <DashboardCardPreset title="売上">
   <MetricValue className="my-0">¥1,240,000</MetricValue>
-  <TrendIndicator value={12.4} direction="up" />
+  <Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
 </DashboardCardPreset>
 ```

package/docs/ja/parts/progress-circle.md

@@ -0,0 +1,34 @@
+# ProgressCircle
+
+> 目標に対する達成率をリングで示す。中央に任意の内容を置ける。
+
+`value / max` の割合だけリングを塗ります。children は中央に置かれるので、達成率の数値や
+アイコンを入れます。単一の `<svg>` で、KPI タイルに並べても軽いままです。
+
+```tsx
+import { ProgressCircle } from "@squadbase/vantage/components";
+import type { ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number` | `0` | 現在値。`0`〜`max` に丸める。 |
+| `max` | `number` | `100` | 満タンの値。 |
+| `radius` | `number` | `32` | 外側の半径（px）。全体は `radius * 2` 四方。 |
+| `strokeWidth` | `number` | `6` | 線の太さ（px）。 |
+| `color` | `ChartColor` | `"chart-1"` | `"chart-1"`〜`"chart-5"` か CSS カラー。地のリングは同じ色を淡くしたもの。 |
+| `showAnimation` | `boolean` | `true` | マウント時と値の変化をアニメーションする。 |
+| `children` | `ReactNode` |  | 中央に置く内容（例: `72%`）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。`role="progressbar"` と `aria-valuenow` が付きます。
+
+## 値の書式は呼び出し側で
+
+中央の表示は children そのものです。割合ではなく実数を見せたいときも、そのまま書いてください。
+
+```tsx
+<ProgressCircle value={3_400_000} max={5_000_000} radius={40} strokeWidth={8}>
+  <span className="text-xs">340万</span>
+</ProgressCircle>
+```

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) など、テキストとして隣に置いてください。