@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.51e401a

package/docs/ja/doc/doc-report-header.md

@@ -0,0 +1,46 @@
+# DocReportHeader
+
+> ドキュメントの冒頭。タイトル、サブタイトル、期間・時点・作成者・出典。
+
+ドキュメントの冒頭に置くセクションです。`h1` のタイトルと、期間・データ時点・作成者・出典の短い事実表（`dl`）を出します。`h1` を持つのはこの block だけで、以降のセクションは `h2` から始まります。
+
+```tsx
+import { DocReportHeader } from "@squadbase/vantage/doc";
+import type { DocReportHeaderProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `subtitle` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | ドキュメントの題（`h1`）。対象と期間を書き、スローガンにしない。**必須**。 |
+| `subtitle` | `ReactNode` | 題の下の 1 行（誰向けか、など）。`string` か `ReactNode`。 |
+| `period` | `string` | 数字の対象期間（「2026 年 9 月」「2026-07-01 〜 2026-09-30」）。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+| `author` | `string` | 作成者。 |
+| `source` | `string` | 数字の出どころ（「受注管理システム、会計システム」）。1 つの文字列で書く。 |
+
+## 使い方
+
+```tsx
+import { Document, DocReportHeader } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocReportHeader
+    title="2026 年 9 月 月次事業報告"
+    subtitle="経営会議向け"
+    period="2026-09-01 〜 2026-09-30"
+    asOf="2026-10-03"
+    author="事業企画チーム"
+    source="受注管理システム、会計システム"
+  />
+</Document>
+```
+
+## 注意
+
+- 空の項目は「—」ではなく、行ごと省かれます。
+- 印刷時はヘッダー全体が 1 ページに収まるよう、ページをまたぎません。

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

@@ -45,6 +45,7 @@ export default function Deck() {
 - **3 つの見え方。** 左にスライド一覧（`L` で開閉）、スライドのみ、全画面（`F`）。一覧の開閉と
   今のページは URL（`?rail=` / `?p=`）に入るので、そのまま共有できます。`Esc` でデッキを抜けます。
 - **PowerPoint に書き出す。** ツールバーのボタンで、全スライドを `.pptx` として保存します。
+- **日本語の改行。** ルート `_layout.tsx` に `export const lang = "ja"` を書くと、見出しが文節の途中で折れず、ツールバーも日本語になります（[アプリの表示言語](pages-and-metadata)）。
 - **テーマに追従。** 配色と書体は `--slide-*` トークンで、既定はアプリのトークンを指すので
   ダークモードにも追従します。デッキごとに `theme` で上書きできます。
 

package/docs/ja/pages-and-metadata.md

@@ -60,6 +60,21 @@ export default function MonthlyAnalysis() {
 **ファイルをリネーム**するか、`_` を前置してルート化を止め、tsx から `FilePageView` で描いて
 そこに `definePage` を書きます。
 
+## アプリの表示言語
+
+ルートの `_layout.tsx` で `lang` をリテラルでエクスポートすると、`<html lang>` に入ります。
+
+```tsx
+// src/_layout.tsx
+export const lang = "ja"
+```
+
+- 値は BCP 47 の言語タグ（`"ja"` / `"en"` / `"ja-JP"` など）。変数やテンプレート補間は読まれません。
+- 読まれるのはルートの `_layout.tsx` だけです。入れ子のレイアウトやページに書いても無視されます。
+- 未指定、または形式が不正な値は `"en"` になります（診断で警告します）。何も書かないアプリの出力は従来どおりです。
+- `ja` を指定すると、スライドと doc ページの日本語が文節の途中で折れなくなり（`word-break: auto-phrase`）、スライドのツールバーの文言も日本語になります。
+- dev では `lang` を書き換えると自動で再読み込みされます。
+
 ## Fast Refresh との関係
 
 `page` のような非コンポーネントのエクスポートがあっても、Vantage はそれを内部で扱うため

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/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,51 @@
+# Delta
+
+> 比較相手に対する増減。矢印・符号付きの率・比較ラベルを値から導く。
+
+値の変化を「↑ +12.4% 前期比」の 1 行で示します。**向き・率・色・文言はすべて `value` と `comparison`
+から計算**され、外から渡すことはできません — そのため矢印と色が食い違うことがありません。色だけに
+頼らず、矢印と符号が必ず付きます。解約率のように上がると悪い指標は `betterWhen="down"` を
+渡してください（古い名前の `polarity` も使えます）。
+
+非推奨の [`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` |  | 比較の相手。**必須**（増減に必ずラベルが付くように）。下の表を参照。 |
+| `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"` | 率の書式のロケール。 |
+| `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" }} betterWhen="down" />
+```
+
+色は `--positive` / `--negative` / `--neutral` のトークンで決まります。KPI を 1 枚のカードで見せる
+なら [`KpiCard`](parts/kpi-card) が中で `Delta` を使います。

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` で変えられます）。