@squadbase/vantage 0.6.2-dev1.25d59a0 → 0.6.2-dev1.26a3cce

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

@@ -9,50 +9,74 @@
 
 ```tsx
 import { AreaChart } from "@squadbase/vantage/components";
-import type { AreaChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
-| `index` | `string` |  | x 軸に使う列名。**必須**。 |
-| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
-| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
-| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
-| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` は積み上げ、`percent` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
-| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
-| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
-| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
-| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `keyof T & string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `NumericKeys<T>[]` |  | 系列として描く列名（数値の列だけ渡せる）。**必須**。この順が凡例と配色の順。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `トークン順` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`。配列は系列の順、record は系列名ごと。CSS カラーは渡せない。 |
+| `labels` | `Record<string, string>` |  | `index` の値・系列名 → 表示名（軸・凡例・ツールチップ・データ表に反映）。例 `{ jan: "1 月", sales: "売上" }`。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、または `{ type, digits, currency, notation, unit, divisor, durationUnit }`。軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `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` |  | 値軸の下限。 |
-| `maxValue` | `number` |  | 値軸の上限。 |
-| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
-| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `minValue` | `number` |  | 値軸の下限。常に 0 起点なので、0 以下の値だけ有効（負の値の下に余白を取る）。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
 | `xAxisLabel` | `string` |  | x 軸の名前。 |
 | `yAxisLabel` | `string` |  | y 軸の名前。 |
-| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
-| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
-| `loading` | `boolean` |  | ローディング表示を出す。 |
-| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
-| `className` | `string` |  | 足すクラス。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点（棒）のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。見出しの下に出す。`"auto"` なら data から機械的に組む。向きの言い回しを手書きすると data とずれるので `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。`title` の既定は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列（CSS の長さ）は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。`title` / `summary` は画像の上に含まれる。含めないなら `{ includeTitle: false }`。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。`actions` と使う。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。見出しがあればそちらが使われる。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは `height` で決める。 |
+
+### 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-2"` のような
-> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
 
 ## 構成比の推移を見る
 
-`type="percent"` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
-ツールチップには**元の値**が `valueFormatter` で出ます。
+`areaOptions={{ type: "percent" }}` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
+ツールチップには**元の値**が `format` / `valueFormatter` の書式で出ます。
 
 ```tsx
-<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} type="percent" />
+<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} areaOptions={{ type: "percent" }} />
 ```
 
 ## EChart との使い分け

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

@@ -3,50 +3,76 @@
 > 比較を棒で見せる型付きグラフ。横並び・積み上げ・横棒に切り替えられる。
 
 カテゴリごとの値を棒で比べます。**行の配列（`data`）・カテゴリの列名（`index`）・系列の列名（`categories`）**
-を渡すだけで描け、`type` で横並び / 積み上げ / 100% 積み上げ、`layout` で縦棒 / 横棒を切り替えます。
+を渡すだけで描け、`barOptions.type` で横並び / 積み上げ / 100% 積み上げ、`barOptions.layout` で縦棒 / 横棒を切り替えます。
 配色はトークンに追従します。中身は [`EChart`](parts/echart) です。
 
 ```tsx
 import { BarChart } from "@squadbase/vantage/components";
-import type { BarChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+import type { BarChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
-| `index` | `string` |  | x 軸に使う列名。**必須**。 |
-| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
-| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
-| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
-| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `default` は横並び、`stacked` は積み上げ、`percent` は各カテゴリの合計を 100% にした積み上げ。 |
-| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` はカテゴリを縦に並べた**横棒**（先頭の行が一番上）。ラベルの長いランキング向け。 |
-| `barCategoryGap` | `string \| number` |  | カテゴリ間の隙間（`"30%"` や px）。 |
-| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `keyof T & string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `NumericKeys<T>[]` |  | 系列として描く列名（数値の列だけ渡せる）。**必須**。この順が凡例と配色の順。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `トークン順` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`。配列は系列の順、record は系列名ごと。CSS カラーは渡せない。 |
+| `labels` | `Record<string, string>` |  | `index` の値・系列名 → 表示名（軸・凡例・ツールチップ・データ表に反映）。例 `{ jan: "1 月", sales: "売上" }`。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、または `{ type, digits, currency, notation, unit, divisor, durationUnit }`。軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `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` |  | 値軸の下限。 |
-| `maxValue` | `number` |  | 値軸の上限。 |
-| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
-| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `minValue` | `number` |  | 値軸の下限。常に 0 起点なので、0 以下の値だけ有効（負の値の下に余白を取る）。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
 | `xAxisLabel` | `string` |  | x 軸の名前。 |
 | `yAxisLabel` | `string` |  | y 軸の名前。 |
-| `onValueChange` | `(value: ChartEventPayload) => void` |  | 棒のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
-| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
-| `loading` | `boolean` |  | ローディング表示を出す。 |
-| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
-| `className` | `string` |  | 足すクラス。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点（棒）のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。見出しの下に出す。`"auto"` なら data から機械的に組む。向きの言い回しを手書きすると data とずれるので `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。`title` の既定は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列（CSS の長さ）は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。`title` / `summary` は画像の上に含まれる。含めないなら `{ includeTitle: false }`。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。`actions` と使う。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。見出しがあればそちらが使われる。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは `height` で決める。 |
+
+### 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-2"` のような
-> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
 
 ## 横棒のランキング
 
-ラベルが長いときは `layout="vertical"` で横棒にします。`yAxisWidth` でラベル幅を固定すると、
+ラベルが長いときは `barOptions={{ layout: "vertical" }}` で横棒にします。`yAxisWidth` でラベル幅を固定すると、
 長いラベルは省略されます。行の順に上から並ぶので、並べ替えは `data` 側で済ませてください。
 
 ```tsx
@@ -54,7 +80,7 @@ import type { BarChartProps, ChartColor, ChartEventPayload } from "@squadbase/va
   data={stores}
   index="store"
   categories={["売上"]}
-  layout="vertical"
+  barOptions={{ layout: "vertical" }}
   yAxisWidth={96}
   showLegend={false}
 />

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

@@ -8,18 +8,41 @@
 
 ```tsx
 import { BarList } from "@squadbase/vantage/components";
-import type { BarListItem, ChartColor } from "@squadbase/vantage/components";
+import type { BarListItem, BarListOptions, ChartSeriesColor } 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` |  | 足すクラス。 |
+| `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>` にそのまま渡ります。
 

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

@@ -4,8 +4,8 @@
 
 値の変化を「↑ +12.4% 前期比」の 1 行で示します。**向き・率・色・文言はすべて `value` と `comparison`
 から計算**され、外から渡すことはできません — そのため矢印と色が食い違うことがありません。色だけに
-頼らず、矢印と符号が必ず付きます。解約率のように上がると悪い指標は `polarity="lower-is-better"` を
-渡してください。
+頼らず、矢印と符号が必ず付きます。解約率のように上がると悪い指標は `betterWhen="down"` を
+渡してください（古い名前の `polarity` も使えます）。
 
 非推奨の [`TrendIndicator`](parts/trend-indicator) の置き換えです。
 
@@ -18,7 +18,8 @@ import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/compon
 | --- | --- | --- | --- |
 | `value` | `number \| null \| undefined` |  | 現在の値。**必須**。前の値は `comparison` から取る。 |
 | `comparison` | `Comparison` |  | 比較の相手。**必須**（増減に必ずラベルが付くように）。下の表を参照。 |
-| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | 上がることが良いか。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率のように下がる方が良い指標は `"down"`。`polarity` より優先される。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | 非推奨。`betterWhen` の古い名前。`"neutral"`（良し悪しの色をつけない）はこちらからだけ渡せる。 |
 | `neutralBand` | `number` | `0.01` | 変化率の絶対値がこれ未満なら横ばい（–）として扱う。既定は 1%。 |
 | `variant` | `"badge" \| "inline"` | `"badge"` | 枠付きのバッジか、文中に置く素の文字か。 |
 | `locale` | `string` | `"ja-JP"` | 率の書式のロケール。 |
@@ -43,7 +44,7 @@ import type { DeltaProps, Comparison, Polarity } from "@squadbase/vantage/compon
 <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" />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} betterWhen="down" />
 ```
 
 色は `--positive` / `--negative` / `--neutral` のトークンで決まります。KPI を 1 枚のカードで見せる

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

@@ -2,46 +2,65 @@
 
 > 構成比を見せる型付きのドーナツ / 円グラフ。中央に合計を出す。
 
-構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`category`）・値の列（`value`）**
-を渡すだけで描け、ドーナツの穴には合計（または `label`）が出ます。中央のラベルはキャンバスではなく
+構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`index`）・値の列（`categories`）**
+を渡すだけで描けます。ドーナツの穴には `donutOptions.centerLabel` で合計や最大の切片を出せます。中央のラベルはキャンバスではなく
 HTML なので、ページの文字色・書体のまま表示されます。配色はトークンに追従します。
 
 ```tsx
 import { DonutChart } from "@squadbase/vantage/components";
-import type { DonutChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+import type { DonutChartProps, DonutChartOptions, ChartSeriesColor, 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 のみ）。 |
+| `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`。 |
-| `loading` | `boolean` |  | ローディング表示を出す。 |
-| `ariaLabel` | `string` |  | チャートの説明。 |
-| `className` | `string` | `"size-40"` | 外枠のクラス。大きさはここで決める。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。大きさは `height`（既定 288px）で決める。幅は親に合わせて広がる。 |
 
-## 凡例を添える
+### donutOptions
 
-凡例は持ちません（切片が 5 つ程度ならツールチップで足りるため）。並べて見せたいときは、
-行ごとに同じ色を当てた [`BarList`](parts/bar-list) や表を隣に置いてください。
+| 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
-<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>
+<DonutChart
+  data={rows}
+  index="channel"
+  categories={["sessions"]}
+  donutOptions={{ centerLabel: "total", unit: "セッション" }}
+/>
 ```
 
 > [!NOTE]
-> 切片が 6 つを超えると色が繰り返されます。小さい切片は「その他」にまとめてから渡してください。
+> 切片が 5 つを超えると、小さい切片は「その他」にまとまります（`donutOptions.maxSlices` で変えられます）。

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"` など）を使ってください。

package/docs/ja/parts/heatmap.md

@@ -0,0 +1,45 @@
+# Heatmap
+
+> 2 つのカテゴリの掛け合わせを濃淡で見せる型付きのヒートマップ。曜日 × 時間帯やコホートの継続率に。
+
+マス目の濃さで値の大小を見せます。**行の配列（`data`）・横軸の列（`x`）・縦軸の列（`y`）・濃さを決める数値の列
+（`value`）**を渡すだけで描けます。配色は 1 色の薄い → 濃いのグラデーション（既定 `--chart-1`）で、
+レインボーにはしません。値が無いマスは塗らず、0 とは区別します（ツールチップとデータ表は「—」）。
+
+```tsx
+import { Heatmap } from "@squadbase/vantage/components";
+import type { HeatmapProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 マス（x と y の組）。同じ組が複数あれば後の行が勝つ。 |
+| `x` | `string` |  | 横軸（列）に使う列名。**必須**。 |
+| `y` | `string` |  | 縦軸（行）に使う列名。**必須**。先頭の行が一番上。 |
+| `value` | `string` |  | マスの濃さを決める数値の列名。**必須**。null・欠損・数値でない値のマスは塗らない。 |
+| `xLabels` | `string[]` |  | 横軸の並び順（と表示するマス）。省略時は `data` の出現順。ここに無い x の行は描かない。 |
+| `yLabels` | `string[]` |  | 縦軸の並び順（と表示するマス）。省略時は `data` の出現順。 |
+| `labels` | `Record<string, string>` |  | 列名・軸の値 → 表示名（軸・ツールチップ・データ表）。 |
+| `format` | `ValueFormat` | `"number"` | 数値の書式（`"percent"` や `{ type: "number", unit: "件" }` など）。マス内・ツールチップ・データ表で同じ。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先。 |
+| `tone` | `ChartSeriesColor` | `"chart-1"` | 濃淡の色。`"chart-1"`〜`"chart-5"` か意味色（`positive` / `warning` / `negative` / `neutral`）。 |
+| `scale` | `{ min?: number; max?: number }` |  | 濃さの固定スケール。省略時はデータの最小〜最大。継続率なら `{ min: 0, max: 100 }`。比べたい範囲が決まっているときだけ渡す。凡例の両端もこの値になる。 |
+| `showValues` | `boolean` | `false` | マスの中に値を書く。 |
+| `showLegend` | `boolean` | `true` | 凡例（薄い → 濃いの帯と両端の値）を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `details` | `string[]` |  | ツールチップとデータ表に添える同じ行の別の数値列。「SLA 未達 2件」のように出る。 |
+| `flag` | `string` |  | この列が真（`true` / 0 でない数）の行のマスに、注意色（`--negative`）の枠を付ける。ツールチップにも「要注意」と出る。 |
+| `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` |  | スクリーンリーダー向けのラベル。省略時は「<y の列>×<x の列>のヒートマップ」。 |
+
+> [!NOTE]
+> 濃さはデータの範囲に合わせて決まります。別々のヒートマップを並べて比べるときは、全部に同じ `scale` を
+> 渡してください。`minValue` / `maxValue` は非推奨で、`scale` を使います。

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

@@ -19,7 +19,8 @@ import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } f
 | `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"`。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率のように下がる方が良い指標は `"down"`。`polarity` より優先される。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | 非推奨。`betterWhen` の古い名前。`"neutral"`（良し悪しの色をつけない）はこちらからだけ渡せる。 |
 | `neutralBand` | `number` | `0.01` | 変化率の絶対値がこれ未満なら横ばいとして扱う。 |
 | `showPrevious` | `boolean` | `true` | 前期の実績（「前期 400」）を出すか。`comparison` が要る。 |
 | `summary` | `string` |  | 結論の 1 文の**テンプレート**。下のプレースホルダをカードが埋める。 |