@squadbase/vantage 0.6.1 → 0.6.2-dev1.0017a4d

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

@@ -0,0 +1,85 @@
+# 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, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `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` より優先する。 |
+| `areaOptions` | `AreaChartOptions` |  | 面グラフ固有の設定。`{ type, curveType, fill, connectNulls }`（下の表）。 |
+| `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` |  | 値軸の下限。常に 0 起点なので、0 以下の値だけ有効（負の値の下に余白を取る）。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `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` で決める。 |
+
+### areaOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `"stacked"` は積み上げ、`"percent"` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
+| `connectNulls` | `boolean` | `false` | 値の欠けた点（`null` など）をまたいで線をつなぐ。 |
+
+> [!NOTE]
+> `type` / `curveType` / `fill` / `connectNulls` をグラフの props に直接渡す書き方と、`autoMinValue`・`loading` は**非推奨**です（`areaOptions.*` と `isLoading` を使う。面グラフは常に 0 起点で `autoMinValue` は無視されます）。
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 構成比の推移を見る
+
+`areaOptions={{ type: "percent" }}` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
+ツールチップには**元の値**が `format` / `valueFormatter` の書式で出ます。
+
+```tsx
+<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} areaOptions={{ type: "percent" }} />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

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

@@ -0,0 +1,95 @@
+# BarChart
+
+> 比較を棒で見せる型付きグラフ。横並び・積み上げ・横棒に切り替えられる。
+
+カテゴリごとの値を棒で比べます。**行の配列（`data`）・カテゴリの列名（`index`）・系列の列名（`categories`）**
+を渡すだけで描け、`barOptions.type` で横並び / 積み上げ / 100% 積み上げ、`barOptions.layout` で縦棒 / 横棒を切り替えます。
+配色はトークンに追従します。中身は [`EChart`](parts/echart) です。
+
+```tsx
+import { BarChart } from "@squadbase/vantage/components";
+import type { BarChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `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` より優先する。 |
+| `barOptions` | `BarChartOptions<T>` |  | 棒グラフ固有の設定。`{ type, layout, barCategoryGap, showZeroValues, targetKey, highlight }`（下の表）。 |
+| `thresholds` | `ChartThreshold[]` |  | 棒を値で色分けする。`{ lt?, lte?, gt?, gte?, tone }` を上から順に見て、最初に当たった規則の意味色（`"positive"` / `"warning"` / `"negative"` / `"neutral"`）で塗る。積み上げでは無視。例 `[{ gt: 2, tone: "negative" }, { gt: 1.5, tone: "warning" }]` |
+| `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` |  | 値軸の下限。常に 0 起点なので、0 以下の値だけ有効（負の値の下に余白を取る）。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `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` で決める。 |
+
+### barOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `"default"` は横並び、`"stacked"` は積み上げ、`"percent"` は各カテゴリの合計を 100% にした積み上げ。 |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | `"vertical"` はカテゴリを縦に並べた**横棒**（先頭の行が一番上）。ラベルの長いランキング向け。1 系列の横棒は淡い色が既定。 |
+| `barCategoryGap` | `string \| number` |  | カテゴリ間の隙間（`"20%"` や px）。省略時は ECharts の既定。 |
+| `showZeroValues` | `boolean` | `true` | 値が 0 の棒に「0」の値ラベルを付ける（積み上げでは付けない）。 |
+| `targetKey` | `NumericKeys<T>` |  | 棒ごとの目標値が入った `data` の列名。各棒に短い目標マーカーを引き、ツールチップに達成率を足す。1 系列と積み上げで使える。渡すとグラフ全体の `target` 線は描かない。 |
+| `highlight` | `string \| number` |  | 横棒（`layout: "vertical"`）の 1 系列で伝えたい 1 本。`index` の値で渡す（例 `"東京店"`）。この 1 本だけ濃い色になる。 |
+
+> [!NOTE]
+> `type` / `layout` / `barCategoryGap` をグラフの props に直接渡す書き方と、`autoMinValue`・`loading` は**非推奨**です（`barOptions.*` と `isLoading` を使う。棒グラフは常に 0 起点で `autoMinValue` は無視されます）。
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 横棒のランキング
+
+ラベルが長いときは `barOptions={{ layout: "vertical" }}` で横棒にします。`yAxisWidth` でラベル幅を固定すると、
+長いラベルは省略されます。行の順に上から並ぶので、並べ替えは `data` 側で済ませてください。
+
+```tsx
+<BarChart
+  data={stores}
+  index="store"
+  categories={["売上"]}
+  barOptions={{ 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,58 @@
+# BarList
+
+> 名前と値を横棒で並べるランキング。軸なしで、カードに収まる軽さ。
+
+名前と値の組を、値に比例した淡い横棒で並べます。アクセスの多いページ・店舗別の売上・
+エラーの種類別件数のような**上位 N 件**に向きます。ECharts を使わない HTML なので、カードの中に
+いくつ置いても軽く、配色はテーマに追従します。
+
+```tsx
+import { BarList } from "@squadbase/vantage/components";
+import type { BarListItem, BarListOptions, ChartSeriesColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | 行の配列。**必須**。`index` / `categories` を省くと `{ name, value, href?, key? }` の形として読む。 |
+| `index` | `keyof T & string` | `"name"` | 行の名前に使う列名。 |
+| `categories` | `(keyof T & string)[]` | `["value"]` | 値に使う列名を 1 つだけ入れた配列（`["売上"]`）。最初の 1 つだけを使う。 |
+| `colors` | `ChartSeriesColor \| ChartSeriesColor[]` | `"chart-1"` | バーの色（`"chart-1"`〜`"chart-5"` か意味色、最初の 1 つだけを使う）。全行を同じ淡い色で塗り、順位はバーの長さで読む。 |
+| `labels` | `Record<string, string>` |  | 行の名前（`index` の値）→ 表示名。行のラベルとデータ表に反映。 |
+| `thresholds` | `ChartThreshold[]` |  | 行の値で意味色に塗り分ける（最初に当たった規則。どれにも当たらない行は通常色）。例 `[{ lt: 40, tone: "negative" }, { lt: 70, tone: "warning" }]` |
+| `highlight` | `string` |  | 伝えたい 1 行。`index` の値で渡す。この 1 行だけ濃い色になる。「その他」は選べない。 |
+| `barListOptions` | `BarListOptions` |  | BarList 固有の設定。`{ sortOrder, maxItems, otherLabel, exclude, showShare }`（下の表）。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` などか `{ type, digits, unit, … }`。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string` |  | 1 文の要約。見出しの下に出す。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。`title` の既定は「表示できるデータがありません」。 |
+| `onValueChange` | `(item: T) => void` |  | 渡すと行がボタンになり、クリックした行を受け取る（絞り込みの起点に）。「その他」の行は押せない。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。リストの高さは行数で決まる（`height` は持たない）。 |
+
+### barListOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `sortOrder` | `"descending" \| "ascending" \| "none"` | `"descending"` | 並べ順。`"none"` は渡した順。「その他」は常に最後。 |
+| `maxItems` | `number` | `5` | 個別に出す行の数。超えた分は合計して「その他」の 1 行にまとめる。 |
+| `otherLabel` | `string` | `"その他"` | まとめた行のラベル。 |
+| `exclude` | `readonly string[]` |  | 順位に入れず、常に「その他」へ足す行の名前。例 `["(not set)"]`。 |
+| `showShare` | `boolean` | `false` | 値の横に構成比（全行の合計に対する割合。整数 %）を添える。例「¥8,240万 · 43%」。 |
+
+> [!NOTE]
+> 次の旧 props は**非推奨**です。`sortOrder` → `barListOptions.sortOrder`、`color` → `colors`、`formatValue` → `valueFormatter` か `format`、`showAnimation` は入場アニメーションを持たないため不要です。`BarListItem.color`（行ごとの色）も非推奨で、行ごとの色は持ちません。
+
+残りの 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/chart-frame.md

@@ -0,0 +1,36 @@
+# ChartFrame
+
+> 型付きグラフが共通で使う枠。見出し・要約・読み込み中・空の状態を、高さを保ったまま出す。
+
+`LineChart` や `BarChart` などの型付きグラフが内部で使っている枠です。任意の見出しと 1 文の要約を、
+**固定の高さのプロット領域**の上に置きます。プロット領域は見出しで名前が付き、要約で説明されるので、スクリーン
+リーダーには「グラフがある」だけでなく「何を言っているか」が届きます。読み込み中は最終形と同じ形のスケルトン、
+データが無いときは空の表示を、**どちらも高さを変えずに**出します。
+
+通常は型付きグラフの `title` / `summary` / `isLoading` / `emptyState` を使えば足ります。`ChartFrame` を直接使うのは、
+自前の HTML のグラフを同じ作法で包みたいときです。
+
+```tsx
+import { ChartFrame } from "@squadbase/vantage/components";
+import type { ChartFrameProps, ChartSkeletonVariant } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | グラフの見出し。プロット領域の `aria-labelledby` になる。 |
+| `summary` | `string` |  | 1 文の要約。見出しの下に出し、プロット領域の `aria-describedby` になる。 |
+| `isLoading` | `boolean` | `false` | 読み込み中。`variant` の形のスケルトンを同じ高さで出す。 |
+| `isEmpty` | `boolean` | `false` | データが無い。高さを保ったまま `emptyState` を出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | 空のときの表示。題の既定は「表示できるデータがありません」。操作は 1 つだけ置ける。 |
+| `height` | `number \| string` | `288` | プロット領域の高さ。数値は px。 |
+| `variant` | `"line" \| "area" \| "bar" \| "donut" \| "list"` | `"line"` | スケルトンの形。包むグラフに合わせる。 |
+| `ariaLabel` | `string` |  | 見出しが無いときのプロット領域のラベル。 |
+| `plotRole` | `"img" \| "group"` | `"img"` | プロット領域の役割。canvas のグラフは `img`。行がボタンやリンクになる HTML のグラフは `group` にして中身を読ませる。 |
+| `dataTable` | `{ caption?: string; columns: string[]; rows: string[][] }` |  | 値の表。画面には出さず（`sr-only`）、スクリーンリーダー向けに図の中に置く。先頭の列が行の見出し。 |
+| `children` | `ReactNode` |  | プロット本体。読み込み中・空のときは描かない。 |
+| `className` | `string` |  | 外枠（`<figure>`）のクラス。 |
+
+`ref` はプロット領域（高さが決まっている要素）を指し、`className` とその他の属性は外側の `<figure>` に渡ります。
+
+> [!NOTE]
+> プロット領域は読み込み中・空・表示のどの状態でも同じ高さです。高さを揃えるための余白を自分で足さないでください。

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,66 @@
+# DonutChart
+
+> 構成比を見せる型付きのドーナツ / 円グラフ。中央に合計を出す。
+
+構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`index`）・値の列（`categories`）**
+を渡すだけで描けます。ドーナツの穴には `donutOptions.centerLabel` で合計や最大の切片を出せます。中央のラベルはキャンバスではなく
+HTML なので、ページの文字色・書体のまま表示されます。配色はトークンに追従します。
+
+```tsx
+import { DonutChart } from "@squadbase/vantage/components";
+import type { DonutChartProps, DonutChartOptions, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が 1 切片。 |
+| `index` | `keyof T & string` |  | 切片の名前に使う列名。 |
+| `categories` | `(keyof T & string)[]` |  | 切片の大きさに使う列名を 1 つだけ入れた配列（`["売上"]`）。最初の 1 つだけを使う。number か数値文字列。0 以下と欠損は 0 扱い。 |
+| `colors` | `ChartSeriesColor[]` | `トークン順` | 切片の色（大きい順）。`"chart-1"`〜`"chart-5"` か意味色。「その他」は常に灰色。 |
+| `labels` | `Record<string, string>` |  | 切片の名前（`index` の値）→ 表示名。凡例・ツールチップ・データ表に反映。 |
+| `donutOptions` | `DonutChartOptions` |  | ドーナツ固有の設定。`{ variant, centerLabel, totalLabel, unit, showLegend, maxSlices }`（下の表）。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` などか `{ type, digits, unit, … }`。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | 1 文の要約。`"auto"` なら slices から「最大は <名前>（<構成比>）」を組む。順位や構成比を文に書くなら `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `showTooltip` | `boolean` | `true` | ホバーで名前・値・構成比を出す。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 切片のクリックで呼ばれる。行に `eventType: "slice"` と `categoryClicked`（切片名）を足して渡し、同じ切片をもう一度押すと `null`。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。大きさは `height`（既定 288px）で決める。幅は親に合わせて広がる。 |
+
+### donutOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `variant` | `"donut" \| "pie"` | `"donut"` | 穴あきか、円か。 |
+| `centerLabel` | `"none" \| "total" \| "top" \| ReactNode` | `"none"` | 穴の中央に出すもの。`"total"` は合計、`"top"` は最大の切片の名前と構成比。ノードを渡すとそのまま置く。donut のみ。合計は KPI と重複しがちなので既定は出さない。 |
+| `totalLabel` | `string` | `"合計"` | `"total"` の見出し。 |
+| `unit` | `string` |  | `"total"` の合計に添える単位（`"セッション"`）。 |
+| `showLegend` | `boolean` | `true` | 凡例（名前と構成比、大きい順）を出す。広いときは右、狭いときは下。消すと、広いときだけ大きい 2 切片に外ラベルが出る。 |
+| `maxSlices` | `number` | `5` | 個別に描く切片の数。超えた分は「その他」1 切片にまとめる。 |
+
+> [!NOTE]
+> 旧 props は**非推奨**です。`category` → `index`、`value` → `categories={[value]}`、`variant` → `donutOptions.variant`、`label` / `showLabel` → `donutOptions.centerLabel`、`loading` → `isLoading`。
+
+## 凡例と中央のラベル
+
+名前と構成比を並べた凡例が付きます（広いときは右、狭いときは下）。消すには
+`donutOptions={{ showLegend: false }}`。穴の中央には `centerLabel` で合計や最大の切片を出せます。
+
+```tsx
+<DonutChart
+  data={rows}
+  index="channel"
+  categories={["sessions"]}
+  donutOptions={{ centerLabel: "total", unit: "セッション" }}
+/>
+```
+
+> [!NOTE]
+> 切片が 5 つを超えると、小さい切片は「その他」にまとまります（`donutOptions.maxSlices` で変えられます）。

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/funnel-steps.md

@@ -7,27 +7,46 @@
 
 ```tsx
 import { FunnelSteps, funnelStepsVariants } from "@squadbase/vantage/components";
-import type { FunnelStep } from "@squadbase/vantage/components";
+import type { FunnelStep, ChartColorToken } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `FunnelStep[]` |  | 各段。**先頭が最大幅**になる。 |
-| `showConversion` | `boolean` |  | 段の間に転換率を出す。 |
-| `formatValue` | `(value: number) => string` |  | 値の書式。既定はそのまま。 |
-| `animate` | `boolean` |  | マウント時に幅を伸ばすアニメーション。 |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
-| `direction` | `"vertical" \| "horizontal"` | `"vertical"` |  |
+| `data` | `T[]` |  | 各段。**必須**。**先頭が最大幅**になる。`index` / `categories` を省くと `{ label, value }` の形として読む。 |
+| `index` | `keyof T & string` | `"label"` | ステップのラベルに使う列名。 |
+| `categories` | `(keyof T & string)[]` | `["value"]` | 値に使う列名を 1 つだけ入れた配列。最初の 1 つだけを使う。 |
+| `colors` | `ChartColorToken[]` |  | 段の色（`"chart-1"`〜`"chart-5"`、段の順に繰り返す）。省略時はすべて `"chart-1"`（段は同じ量の絞り込みなので 1 色）。 |
+| `labels` | `Record<string, string>` |  | ステップの名前（`index` の値）→ 表示名。ラベルとデータ表に反映。 |
+| `highlight` | `string` |  | 伝えたい 1 段。`index` の値で渡す。この 1 段だけ濃い色になる（他は淡い色）。 |
+| `showConversion` | `boolean` |  | 段の間に転換率を出す。最も低い転換率だけが強調される。 |
+| `comparison` | `{ values: readonly (number \| null)[]; label?: string }` |  | 前期の各段の値（`data` と同じ順）。渡すと転換率の横に前期比（pt）を出し、最も下がった率を強調する。`label` の既定は「前期」。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` などか `{ type, digits, unit, … }`。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string` |  | 1 文の要約。見出しの下に出す。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。`title` の既定は「表示できるデータがありません」。 |
+| `animate` | `boolean` | `false` | マウント時に幅を伸ばすアニメーション。 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 段の大きさ。 |
+| `direction` | `"vertical" \| "horizontal"` | `"vertical"` | 並べる向き。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは段数で決まる（`height` は持たない）。 |
 
 ## FunnelStep
 
+`index` / `categories` を省いたときに読まれる行の形です。
+
 ```ts
 interface FunnelStep {
   label: string;
   value: number;
-  color?: string; // 既定はテーマの chart 色
   onClick?: () => void;
+  /** @deprecated Tailwind の bg クラス。`colors` を使う。 */
+  color?: string;
 }
 ```
 
 `onClick` を渡した段は押せるようになるので、その段の内訳へドリルダウンさせられます。
+
+> [!NOTE]
+> `formatValue` は**非推奨**です。`valueFormatter`（関数）か `format`（`"compact"` など）を使ってください。