@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.19083f7

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

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

package/docs/ja/page-types.md

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

package/docs/ja/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

@@ -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,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` を使います。