@squadbase/vantage 0.6.1 → 0.6.2-dev1.31accb1

package/docs/ja/page-types.md

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

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

@@ -0,0 +1,61 @@
+# AreaChart
+
+> 推移を面で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。
+
+時系列の推移を面で描きます。ECharts の option を組む代わりに、**行の配列（`data`）・x 軸の列名（`index`）・
+系列の列名（`categories`）**を渡すだけで、凡例・ツールチップ・軸の書式まで揃います。配色は
+`--chart-1`〜`--chart-5` のトークンに追従し、ライト / ダークを切り替えても追いかけます。中身は
+[`EChart`](parts/echart) です。
+
+```tsx
+import { AreaChart } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
+| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` は積み上げ、`percent` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
+| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
+| `showXAxis` | `boolean` | `true` | x 軸を出す。 |
+| `showYAxis` | `boolean` | `true` | y 軸を出す。 |
+| `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
+| `minValue` | `number` |  | 値軸の下限。 |
+| `maxValue` | `number` |  | 値軸の上限。 |
+| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
+| `loading` | `boolean` |  | ローディング表示を出す。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 構成比の推移を見る
+
+`type="percent"` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
+ツールチップには**元の値**が `valueFormatter` で出ます。
+
+```tsx
+<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} type="percent" />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

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

@@ -0,0 +1,69 @@
+# BarChart
+
+> 比較を棒で見せる型付きグラフ。横並び・積み上げ・横棒に切り替えられる。
+
+カテゴリごとの値を棒で比べます。**行の配列（`data`）・カテゴリの列名（`index`）・系列の列名（`categories`）**
+を渡すだけで描け、`type` で横並び / 積み上げ / 100% 積み上げ、`layout` で縦棒 / 横棒を切り替えます。
+配色はトークンに追従します。中身は [`EChart`](parts/echart) です。
+
+```tsx
+import { BarChart } from "@squadbase/vantage/components";
+import type { BarChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
+| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `default` は横並び、`stacked` は積み上げ、`percent` は各カテゴリの合計を 100% にした積み上げ。 |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` はカテゴリを縦に並べた**横棒**（先頭の行が一番上）。ラベルの長いランキング向け。 |
+| `barCategoryGap` | `string \| number` |  | カテゴリ間の隙間（`"30%"` や px）。 |
+| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
+| `showXAxis` | `boolean` | `true` | x 軸を出す。 |
+| `showYAxis` | `boolean` | `true` | y 軸を出す。 |
+| `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
+| `minValue` | `number` |  | 値軸の下限。 |
+| `maxValue` | `number` |  | 値軸の上限。 |
+| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 棒のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
+| `loading` | `boolean` |  | ローディング表示を出す。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 横棒のランキング
+
+ラベルが長いときは `layout="vertical"` で横棒にします。`yAxisWidth` でラベル幅を固定すると、
+長いラベルは省略されます。行の順に上から並ぶので、並べ替えは `data` 側で済ませてください。
+
+```tsx
+<BarChart
+  data={stores}
+  index="store"
+  categories={["売上"]}
+  layout="vertical"
+  yAxisWidth={96}
+  showLegend={false}
+/>
+```
+
+数件のランキングを軸なしで並べるだけなら、[`BarList`](parts/bar-list) のほうが軽く、
+カードにも収まります。
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

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

@@ -0,0 +1,35 @@
+# BarList
+
+> 名前と値を横棒で並べるランキング。軸なしで、カードに収まる軽さ。
+
+名前と値の組を、値に比例した淡い横棒で並べます。アクセスの多いページ・店舗別の売上・
+エラーの種類別件数のような**上位 N 件**に向きます。ECharts を使わない HTML なので、カードの中に
+いくつ置いても軽く、配色はテーマに追従します。
+
+```tsx
+import { BarList } from "@squadbase/vantage/components";
+import type { BarListItem, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `BarListItem[]` |  | `{ name: string; value: number; href?: string; key?: string; color?: ChartColor }` の配列。**必須**。 |
+| `valueFormatter` | `(value: number) => string` |  | 右端の数値の書式。既定は 3 桁区切り。 |
+| `sortOrder` | `"descending" \| "ascending" \| "none"` | `"descending"` | 並べ順。`none` は渡した順。 |
+| `color` | `ChartColor` | `"chart-1"` | バーの色（淡く塗る）。行ごとに変えるなら `data[].color`。 |
+| `showAnimation` | `boolean` | `false` | マウント時にバーを伸ばす。 |
+| `onValueChange` | `(item: BarListItem) => void` |  | 渡すと行がボタンになり、クリックした行を受け取る（絞り込みの起点に）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## リンクにする
+
+`href` を持つ行は名前がリンクになります。`http(s)://` で始まるものは新しいタブで開きます。
+
+```tsx
+<BarList data={pages.map((p) => ({ name: p.path, value: p.views, href: p.url }))} />
+```
+
+棒の長さは**最大値に対する比**です。全体に対する割合を見せたいなら
+[`CategoryBar`](parts/category-bar) か [`DonutChart`](parts/donut-chart) を使います。

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

@@ -0,0 +1,36 @@
+# CategoryBar
+
+> 1 本の棒を区間に色分けし、現在値をマーカーで示す。
+
+1 本の棒を `values` の比で色分けし、区切りに累計値を出します。`marker` を渡すと、その値の位置に
+目印が立ちます。スコアの判定帯（要改善 / 標準 / 良好）・予算の消化・構成比の 1 本表示に向きます。
+ECharts を使わない HTML で、配色はテーマに追従します。
+
+```tsx
+import { CategoryBar } from "@squadbase/vantage/components";
+import type { CategoryBarMarker, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `values` | `number[]` |  | 各区間の幅（相対値）。**必須**。合計が 100 である必要はない。負の値は 0 扱い。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 区間の色（順に対応）。`"chart-1"`〜`"chart-5"` か CSS カラー。 |
+| `marker` | `CategoryBarMarker` |  | `{ value: number; tooltip?: string; showAnimation?: boolean }`。`value` は `values` の合計と同じ尺度。 |
+| `showLabels` | `boolean` | `true` | 棒の上に区切りの累計値を出す。狭い区間のラベルは省く。 |
+| `valueFormatter` | `(value: number) => string` |  | 区切りの数値の書式。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## 判定帯に色を合わせる
+
+`colors` は区間の順に対応します。「悪い → 良い」の帯なら、暖色から寒色へ並べると読みやすく
+なります。マーカーの色は、乗っている区間の色になります。
+
+```tsx
+<CategoryBar
+  values={[60, 20, 20]}
+  colors={["chart-5", "chart-3", "chart-2"]}
+  marker={{ value: 72, tooltip: "今月のスコア: 72" }}
+/>
+```

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

@@ -0,0 +1,47 @@
+# DonutChart
+
+> 構成比を見せる型付きのドーナツ / 円グラフ。中央に合計を出す。
+
+構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`category`）・値の列（`value`）**
+を渡すだけで描け、ドーナツの穴には合計（または `label`）が出ます。中央のラベルはキャンバスではなく
+HTML なので、ページの文字色・書体のまま表示されます。配色はトークンに追従します。
+
+```tsx
+import { DonutChart } from "@squadbase/vantage/components";
+import type { DonutChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 切片。 |
+| `category` | `string` |  | 切片の名前に使う列名。**必須**。 |
+| `value` | `string` |  | 切片の大きさに使う列名。**必須**。number か数値文字列。0 以下と欠損は 0 扱い。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 切片の色（行の順）。`"chart-1"`〜`"chart-5"` か CSS カラー。足りなければ繰り返す。 |
+| `variant` | `"donut" \| "pie"` | `"donut"` | 穴あき（中央ラベルあり）か、円か。 |
+| `valueFormatter` | `(value: number) => string` |  | ツールチップと中央ラベルの書式。 |
+| `label` | `ReactNode` |  | 中央ラベル。省略時は合計を `valueFormatter` で書いたもの。 |
+| `showLabel` | `boolean` | `true` | 中央ラベルを出す（donut のみ）。 |
+| `showTooltip` | `boolean` | `true` | ホバーで名前・値・構成比を出す。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 切片のクリックで呼ばれる。行に `eventType: "slice"` と `categoryClicked`（切片名）を足して渡し、同じ切片をもう一度押すと `null`。 |
+| `loading` | `boolean` |  | ローディング表示を出す。 |
+| `ariaLabel` | `string` |  | チャートの説明。 |
+| `className` | `string` | `"size-40"` | 外枠のクラス。大きさはここで決める。 |
+
+## 凡例を添える
+
+凡例は持ちません（切片が 5 つ程度ならツールチップで足りるため）。並べて見せたいときは、
+行ごとに同じ色を当てた [`BarList`](parts/bar-list) や表を隣に置いてください。
+
+```tsx
+<div className="flex items-center gap-6">
+  <DonutChart data={rows} category="channel" value="sessions" label="9.7万" className="size-48" />
+  <BarList
+    data={rows.map((r, i) => ({ name: r.channel, value: r.sessions, color: `chart-${(i % 5) + 1}` }))}
+    sortOrder="none"
+    className="flex-1"
+  />
+</div>
+```
+
+> [!NOTE]
+> 切片が 6 つを超えると色が繰り返されます。小さい切片は「その他」にまとめてから渡してください。

package/docs/ja/parts/echart.md

@@ -7,6 +7,9 @@ Apache ECharts をそのまま使えるようにした薄いラッパーです
 系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから組まれ、
 ライト / ダークの切り替えにも追いかけます。
 
+> [!TIP]
+> まず型付きグラフ（[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)・[`LineChart`](parts/line-chart)・[`DonutChart`](parts/donut-chart)）を使い、二軸・散布図・ヒートマップなど細かい制御が要るときだけ `EChart` に option を書いてください。
+
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
 import type { EChartsOption } from "@squadbase/vantage/components";

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

@@ -0,0 +1,58 @@
+# LineChart
+
+> 推移を線で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。
+
+時系列の推移を折れ線で描きます。**行の配列（`data`）・x 軸の列名（`index`）・系列の列名（`categories`）**
+を渡すだけで、凡例・ツールチップ・軸の書式まで揃います。配色はトークンに追従します。中身は
+[`EChart`](parts/echart) です。
+
+```tsx
+import { LineChart } from "@squadbase/vantage/components";
+import type { LineChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
+| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
+| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
+| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
+| `showXAxis` | `boolean` | `true` | x 軸を出す。 |
+| `showYAxis` | `boolean` | `true` | y 軸を出す。 |
+| `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
+| `minValue` | `number` |  | 値軸の下限。 |
+| `maxValue` | `number` |  | 値軸の上限。 |
+| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
+| `loading` | `boolean` |  | ローディング表示を出す。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
+> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 欠損のある系列
+
+値が `null`・空文字・数値でない文字列の点は欠損として扱い、線が途切れます。`connectNulls` を
+付けると欠損をまたいでつなぎます。
+
+```tsx
+<LineChart data={rows} index="date" categories={["CVR"]} connectNulls valueFormatter={(v) => `${v}%`} />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

package/docs/ja/parts/page-shell.md

@@ -27,7 +27,7 @@ import {
 | パーツ | 役割 |
 | --- | --- |
 | `PageShell` | 全体の縦積み |
-| `PageShellHeader` | 下線付きのヘッダー帯。左に見出し、右に `HeaderEnd` の 2 列 |
+| `PageShellHeader` | 下線付きのヘッダー帯。左に見出し、右に `HeaderEnd`。幅が足りないと `HeaderEnd` は見出しの下へ回り込む |
 | `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | 見出しブロック |
 | `PageShellHeaderEnd` | 右端の縦積み |
 | `PageShellMeta` | 「最終更新 10 分前」のような補足 |

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

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

package/docs/ja/parts/sparkline.md

@@ -38,7 +38,7 @@ import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/co
 
 ## EChart との使い分け
 
-軸・凡例・ツールチップ・複数系列が要るなら [`EChart`](parts/echart) を使います。
+軸・凡例・ツールチップ・複数系列が要るなら、まず型付きグラフ（[`LineChart`](parts/line-chart)・[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)）を使い、細かい制御が要るときだけ [`EChart`](parts/echart) を使います。
 `Sparkline` が持つのは「値の並びの形」だけで、**目盛りも数値も出しません**。
 
 > [!NOTE]

package/docs/ja/parts/tracker.md

@@ -0,0 +1,32 @@
+# Tracker
+
+> 期間ごとの状態を小さなブロックの列で示す。稼働状況やバッチの結果に。
+
+1 期間 = 1 ブロックで状態を色分けして並べます。日ごとの稼働状況・バッチの成否・日次目標の
+達成 / 未達のような**連続した状態**に向きます。ブロックにホバーすると `tooltip` が出ます。
+ECharts を使わない HTML で、配色はテーマに追従します。
+
+```tsx
+import { Tracker } from "@squadbase/vantage/components";
+import type { TrackerBlock, ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `TrackerBlock[]` |  | `{ color?: ChartColor; tooltip?: string; key?: string \| number }` の配列。**必須**。左から古い順。 |
+| `defaultColor` | `ChartColor` |  | `color` の無いブロックの色。既定は muted-foreground を淡くした灰色（データ無し・未実行に）。 |
+| `hoverEffect` | `boolean` | `true` | ホバー中のブロックを薄くする。 |
+| `className` | `string` |  | 足すクラス。高さは既定 `h-8`。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。
+
+## 状態に色を割り当てる
+
+`color` はトークン名か CSS カラーです。失敗に `var(--destructive)` を使うと、テーマの
+破壊的操作の色と揃います。
+
+```tsx
+const COLOR = { ok: "chart-2", warn: "chart-3", error: "var(--destructive)" } as const;
+
+<Tracker data={days.map((d) => ({ color: COLOR[d.status], tooltip: `${d.date} ${d.label}` }))} />
+```

package/docs/ja/routing.md

@@ -1,6 +1,6 @@
 # ファイルベースルーティング
 
-> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド / ドキュメント）。
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
@@ -46,90 +46,13 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 
 ## tsx 以外もページになる
 
-ルートになるのは `.tsx` / `.jsx` だけではありません。**`.csv` と `.xlsx`** はそのまま表として
-読めるページになり、**`<name>.slide.tsx`** はスライドデッキに、**`<name>.doc.tsx`** はドキュメントになります。どれも URL の作り方は
-tsx と同じで、`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
+ルートになるのは `.tsx` / `.jsx` だけではありません。**`<name>.slide.tsx`** はスライドデッキに、
+**`<name>.doc.tsx`** はドキュメントに、**`.csv` と `.xlsx`** はそのまま表として読めるページに
+なります。どれも URL の作り方は tsx と同じで、`.slide` / `.doc` と拡張子は URL に出ません
+（`june.slide.tsx`・`june.csv` → `/june`）。`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
 
-### データファイル（`.csv` / `.xlsx`）
-
-`src/data/june.xlsx` を置いて `/data/june` を開くと、ダウンロードせずブラウザ上で表として
-読めます。xlsx は複数シートを切り替えられ、元ファイルをダウンロードする導線も付きます。
-
-描かれるのは**表計算ソフトそのものの見た目**です —— 列は A / B / C、左に行番号、ファイルの
-1 行目はヘッダとして固定され、罫線はデータの外まで続きます。シートのタブは下端に並びます。
-読み取り専用なので編集もソートもできません(セルを選んで `Cmd/Ctrl+C` でコピーはできます)。
-並べ替えや絞り込みが要るデータは、`server/api/` から配って `DataTable` で描いてください。
-
-- **タイトルはファイル名から導かれます**（`june.xlsx` → 「June」、`index.csv` はディレクトリ名）。
-  データファイルに `definePage` は書けないので、名前を変えたいときはファイルをリネームします。
-- **パースはブラウザで行われます。** dev・ビルド後・デプロイ後で同じコードが同じバイトを読むので、
-  同じ URL が同じものを返します。25MB を超えるファイルはそのページにエラーが出ます
-  （`vantage check` が `FILE_PAGE_TOO_LARGE` で先に警告します）。
-- 数式・グラフ・セル書式は再現されません。**値として読めれば十分**という設計です。
-- ページにしたくないファイルは `_` を前置します（`_june.xlsx`）。tsx から自分で描きたいときは
-  こうしてルート化を止め、`@squadbase/vantage/table` の `FilePageView` を使います。
-
-> [!WARNING]
-> **ビューアの無い拡張子はルートになりません。** `.xls` / `.ods` / `.tsv` などを置いても
-> 404 にすらならず、ナビにも `vantage routes` にも出ません。`vantage check` の
-> `UNSUPPORTED_PAGE_FILE` 警告が唯一の告知点です。
-
-### スライド（`.slide.tsx`）
-
-`.slide` は**ページ種別サフィックス**で、URL には出ません（`src/june.slide.tsx` → `/june`）。
-中身は `<SlideDeck>` を返す普通の React コンポーネントなので、`definePage` もナビも
-通常のページと同じように効きます。
-
-```tsx
-import { definePage } from "@squadbase/vantage";
-import { Slide, SlideDeck } from "@squadbase/vantage/slide";
-
-export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" });
-
-export default function Deck() {
-  return (
-    <SlideDeck>
-      <Slide>…</Slide>
-      <Slide>…</Slide>
-    </SlideDeck>
-  );
-}
-```
-
-1920×1080 の固定キャンバスに書き、画面サイズに合わせて縮小されます。キーボードとクリックで
-送れ、左のスライド一覧は `L` で開閉、`F` で全画面、ツールバーから pptx を書き出せます。詳しくは
-[UI とテーマ](ui-and-theming)。
-
-> [!WARNING]
-> `.slide` を付けられるのは**ルートになるページモジュールだけ**です。`_layout.slide.tsx` や
-> `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。また `june.slide.tsx` と
-> `june.tsx`、`sales.csv` と `sales.tsx` はいずれも同じ URL に解決するので `ROUTE_CONFLICT` です。
-
-### ドキュメント（`.doc.tsx`）
-
-`.doc` も**ページ種別サフィックス**です（`src/june-summary.doc.tsx` → `/june-summary`）。上から下へ
-読む文章のページで、中身は `<Document>` を返す普通の React コンポーネントです。
-
-```tsx
-import { definePage } from "@squadbase/vantage";
-import { Document } from "@squadbase/vantage/doc";
-
-export const page = definePage({ title: "6月度サマリー" });
-
-export default function JuneSummary() {
-  return (
-    <Document>
-      <h1>6月度サマリー</h1>
-      <p>6月の売上は目標を 5% 上回りました。</p>
-      <table>…</table>
-    </Document>
-  );
-}
-```
-
-`<Document>` の中の見出し・段落・リスト・表・引用・コードには、クラスを書かなくてもスタイルが
-当たります。詳しくは [UI とテーマ](ui-and-theming)。`.slide` と同じく、`.doc` を付けられるのは
-ルートになるページモジュールだけです。
+それぞれの書き方・できること・制限、そして**置いてもページにならないファイル**（`.xls`・`.tsv`・
+`.md` など）は [ページの種類](page-types) にまとめてあります。
 
 ## ルーティングされないディレクトリ
 
@@ -289,3 +212,4 @@ setSegments((prev) => [...prev, "enterprise"]);
 ## 次に読む
 
 - [ページと definePage](pages-and-metadata) — ページの契約とメタデータ
+- [ページの種類](page-types) — スライド・ドキュメント・CSV・Excel

package/docs/ja/ui/alert-dialog.md

@@ -0,0 +1,41 @@
+# Alert Dialog
+
+> 取り消せない操作の前に確認するモーダル。
+
+削除など取り消せない操作の前に、ユーザーの明示的な返答を求めるモーダルです。
+[`Dialog`](ui/dialog) と違い、背景のクリックでは閉じません。
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogCancel,
+  AlertDialogAction,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `AlertDialog` | 状態。`open` / `defaultOpen` / `onOpenChange` |
+| `AlertDialogTrigger` | 開くきっかけ。`render` でボタンにする |
+| `AlertDialogContent` | 本体。`size` で幅を選ぶ |
+| `AlertDialogMedia` | 見出し横のアイコン枠 |
+| `AlertDialogHeader` / `AlertDialogTitle` / `AlertDialogDescription` | 見出し |
+| `AlertDialogFooter` | ボタン行 |
+| `AlertDialogCancel` | 閉じるボタン(既定 `variant="outline"`) |
+| `AlertDialogAction` | 実行ボタン。`Button` の props をそのまま取る |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `size` | `"default" \| "sm"` | `"default"` | `AlertDialogContent` に渡す。`sm` はボタンを 2 列に並べる。 |
+
+`AlertDialogAction` は**押しても自動では閉じません**。処理が終わったら `open` を `false` に
+するか、閉じてよいなら `AlertDialogCancel` と同じく `render` で包んでください。