@squadbase/vantage 0.6.1 → 0.6.2-dev1.1c9e8bc

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/metric-value.md

@@ -2,7 +2,8 @@
 
 > KPI の数値。単位は MetricUnit で。
 
-KPI の数値を大きく見せるための、字送りを詰めた表示です。単位や補助的な文字は `MetricUnit` で
+KPI の数値を大きく見せるための、字送りを詰めた表示です。KPI のタイルを 1 枚作るなら、増減や前期実績まで
+出せる [`KpiCard`](parts/kpi-card) を先に検討してください。単位や補助的な文字は `MetricUnit` で
 添えます。
 
 ```tsx
@@ -20,6 +21,6 @@ import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage
 ```tsx
 <DashboardCardPreset title="売上">
   <MetricValue className="my-0">¥1,240,000</MetricValue>
-  <TrendIndicator value={12.4} direction="up" />
+  <Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
 </DashboardCardPreset>
 ```

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,10 +38,10 @@ 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]
 > `aria-hidden="true"` が付いているため、スクリーンリーダーには読まれません。実際の数値は
 > [`MetricValue`](parts/metric-value) や
-> [`TrendIndicator`](parts/trend-indicator) など、テキストとして隣に置いてください。
+> [`Delta`](parts/delta) など、テキストとして隣に置いてください。

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/parts/trend-indicator.md

@@ -1,6 +1,22 @@
 # TrendIndicator
 
-> 増減の矢印と変化率。良し悪しは positiveIsGood で決まる。
+> 非推奨。新規は Delta を使う。増減の矢印と変化率。
+
+> [!WARNING]
+> **非推奨です。新規のコードでは [`Delta`](parts/delta) を使ってください。**
+> `TrendIndicator` は向き（`direction`）と色を手で渡すため、値と矢印が食い違うことがあります。`Delta` は今期と
+> 比較相手の値から向き・率・色・ラベルを計算します。KPI をカードで見せるなら
+> [`KpiCard`](parts/kpi-card) を使います。
+
+```tsx
+// 旧
+<TrendIndicator value={12.4} direction="up" />
+<TrendIndicator value={0.4} direction="down" positiveIsGood={false} />
+
+// 新
+<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" />
+```
 
 前期比などの変化を、矢印と変化率で示します。**「上がった＝良い」とは限らない**ので、色は
 `direction` と `positiveIsGood` の組み合わせで決まります — 解約率のように下がる方が良い指標では

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` で包んでください。

package/docs/ja/ui/avatar.md

@@ -0,0 +1,31 @@
+# Avatar
+
+> ユーザーの顔写真またはイニシャル。
+
+ユーザーやオーナーを小さな丸で示します。画像が読み込めないとき・`src` が無いときは
+`AvatarFallback` の中身(イニシャルなど)を出します。
+
+```tsx
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Avatar` | 外枠。`size` で大きさを選ぶ |
+| `AvatarImage` | 画像。読み込みに失敗すると描画されない |
+| `AvatarFallback` | 画像が無いときの中身 |
+| `AvatarBadge` | 右下の小さな丸(オンライン表示など) |
+| `AvatarGroup` / `AvatarGroupCount` | 重ねて並べる。`AvatarGroupCount` は「+4」などの残数 |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | `Avatar` に渡す。`sm` は 24px、`default` は 32px、`lg` は 40px。 |

package/docs/ja/ui/combobox.md

@@ -0,0 +1,74 @@
+# Combobox
+
+> 入力して候補を絞り込むセレクト。
+
+テキストを打って候補を絞り込み、1 つ(または複数)を選ぶ入力です。候補が数件なら
+[`Select`](ui/select) のほうが手数が少なくて済みます。Base UI の `Combobox` の上に
+作っています。
+
+```tsx
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxCollection,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  useComboboxAnchor,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Combobox` | 状態。`items` / `value` / `defaultValue` / `onValueChange` / `multiple` |
+| `ComboboxInput` | 入力欄。`showTrigger`(既定 `true`)/ `showClear` で右端のボタンを出す |
+| `ComboboxContent` | 候補のポップアップ。`side` / `align` / `anchor` |
+| `ComboboxList` | 候補の並び。子に関数を渡すと、絞り込み後の `items` が 1 件ずつ渡る |
+| `ComboboxItem` | 1 候補。`value` は必須 |
+| `ComboboxEmpty` | 一致する候補が無いときの表示 |
+| `ComboboxGroup` / `ComboboxLabel` / `ComboboxCollection` / `ComboboxSeparator` | グループ分け |
+| `ComboboxChips` / `ComboboxChip` / `ComboboxChipsInput` | 複数選択をチップで見せる |
+| `ComboboxTrigger` / `ComboboxValue` | 入力欄を使わずボタンで開く形 |
+| `useComboboxAnchor` | チップ枠をポップアップの基準にするための ref |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `items` | `readonly unknown[]` |  | `Combobox` に渡す候補。入力に応じて絞り込まれ、`ComboboxList` の関数に渡る。 |
+| `multiple` | `boolean` | `false` | 複数選択にする。 |
+| `onValueChange` | `(value) => void` |  | 選択が変わったとき。単一選択では未選択の `null` も渡りうる。 |
+
+## 複数選択
+
+`multiple` を付け、`ComboboxChips` の中にチップと `ComboboxChipsInput` を置きます。ポップアップを
+チップ枠の幅に合わせるには `useComboboxAnchor()` の ref を両方に渡します。
+
+```tsx
+const anchor = useComboboxAnchor();
+
+<Combobox items={metrics} multiple>
+  <ComboboxChips ref={anchor}>
+    <ComboboxValue>
+      {(values: string[]) =>
+        values.map((v) => <ComboboxChip key={v}>{v}</ComboboxChip>)
+      }
+    </ComboboxValue>
+    <ComboboxChipsInput placeholder="指標を追加" />
+  </ComboboxChips>
+  <ComboboxContent anchor={anchor}>
+    <ComboboxList>
+      {(item: string) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>;
+```

package/docs/ja/ui/drawer.md

@@ -0,0 +1,41 @@
+# Drawer
+
+> 画面の端からスワイプで出し入れするパネル。
+
+画面の下(または上下左右)から出てくるパネルです。スワイプで閉じられるので、モバイルでの
+詳細表示やアクション一覧に向いています。デスクトップで広い面積のフォームを出すなら
+[`Sheet`](ui/sheet) が素直です。Base UI の `Drawer` の上に作っています。
+
+```tsx
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerClose,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Drawer` | 状態。`open` / `defaultOpen` / `onOpenChange`、向き、スナップポイント |
+| `DrawerTrigger` | 開くきっかけ。`render` でボタンにする |
+| `DrawerContent` | 本体。オーバーレイとポータルを内包する |
+| `DrawerHeader` / `DrawerTitle` / `DrawerDescription` | 見出し |
+| `DrawerFooter` | ボタン行 |
+| `DrawerClose` | 閉じるトリガー |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `swipeDirection` | `"down" \| "up" \| "left" \| "right"` | `"down"` | `Drawer` に渡す。閉じるときにスワイプする向き(= 出てくる端)。 |
+| `showSwipeHandle` | `boolean` | `false` | `Drawer` に渡す。つまみ(ハンドル)を表示する。 |
+| `snapPoints` | `(number \| string)[]` |  | `Drawer` に渡す。途中で止まる高さ(`0.5` や `"20rem"`)。 |
+| `modal` | `boolean` | `true` | `Drawer` に渡す。`false` で背景を操作可能にし、オーバーレイを出さない。 |
+
+`DrawerTitle` は支援技術のために必須です。見せたくない場合も置いた上で `className="sr-only"` に
+してください。

package/docs/ja/ui/field.md

@@ -0,0 +1,42 @@
+# Field
+
+> ラベル・説明・エラーを入力と束ねるフォームのレイアウト部品。
+
+入力 1 つぶんのラベル・補足説明・エラーメッセージを、決まった間隔と向きで並べる部品です。
+入力そのものは [`Input`](ui/input) や [`Switch`](ui/switch) などを
+中に置きます。
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldContent,
+  FieldTitle,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  FieldSeparator,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Field` | 入力 1 つぶんの外枠。`orientation` で並び方を選ぶ |
+| `FieldLabel` | ラベル(`Label` を使う)。`htmlFor` で入力と結ぶ |
+| `FieldDescription` | 補足説明 |
+| `FieldError` | エラー。`children` か `errors`(`{ message }[]`)を渡す。空なら描画しない |
+| `FieldContent` | 横並びのときにラベルと説明をまとめる列 |
+| `FieldTitle` | `<label>` ではない見出し |
+| `FieldGroup` | 複数の `Field` を縦に並べる |
+| `FieldSet` / `FieldLegend` | `<fieldset>` / `<legend>` |
+| `FieldSeparator` | 区切り線。中に文字も置ける |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | `Field` に渡す。`responsive` はコンテナ幅が広いときだけ横並びにする。 |
+| `data-invalid` | `boolean` |  | `Field` に付けるとラベルと説明がエラー色になる。入力には `aria-invalid` を付ける。 |
+| `errors` | `Array<{ message?: string } \| undefined>` |  | `FieldError` に渡す。複数あれば箇条書きにし、重複は 1 つにまとめる。 |

package/docs/ja/ui/hover-card.md

@@ -0,0 +1,21 @@
+# Hover Card
+
+> リンクにホバーすると出るプレビューカード。
+
+リンクや用語にポインタを載せたとき(キーボードではフォーカスしたとき)に、補足の内容を
+カードで見せます。指標の定義やユーザーのプロフィールなど、**読むだけ**の情報向けです。
+操作を伴うなら [`Popover`](ui/popover)、短い一言なら
+[`Tooltip`](ui/tooltip) を使ってください。Base UI の `PreviewCard` の上に作っています。
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "@squadbase/vantage/ui";
+```
+
+`HoverCardTrigger` は既定で `<a>` を描画します。別の要素にしたい場合は `render` を渡します。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | `HoverCardContent` に渡す。トリガーのどちら側に出すか。 |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | `HoverCardContent` に渡す。 |
+| `sideOffset` | `number` | `4` | `HoverCardContent` とトリガーの距離(px)。 |
+| `delay` | `number` | `600` | `HoverCardTrigger` に渡す。開くまでのミリ秒。 |

package/docs/ja/ui/kbd.md

@@ -0,0 +1,16 @@
+# Kbd
+
+> キーボードのキー表示。
+
+ショートカットキーを表示するための小さな部品です。複数のキーは `KbdGroup` で並べます。
+
+```tsx
+import { Kbd, KbdGroup } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `Kbd` | `ComponentProps<"kbd">` | 1 つのキー。 |
+| `KbdGroup` | `ComponentProps<"div">` | キーを横に並べる。 |
+
+ボタンや [`Tooltip`](ui/tooltip) の中に置くと、周りの文字色に合わせて馴染みます。

package/docs/ja/ui/pagination.md

@@ -0,0 +1,36 @@
+# Pagination
+
+> ページ送りのリンク列。
+
+一覧をページに分けたときのページ送りです。見た目だけの部品で、現在ページや総ページ数は
+持ちません — 状態は呼び出し側(URL の検索パラメータや `useState`)で管理します。
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Pagination` | `<nav>`。`aria-label="pagination"` 付き |
+| `PaginationContent` / `PaginationItem` | `<ul>` / `<li>` |
+| `PaginationLink` | 1 ページ分の `<a>`。`isActive` で現在ページを示す |
+| `PaginationPrevious` / `PaginationNext` | 前後への `<a>`。`text` で文言を変える |
+| `PaginationEllipsis` | 省略記号 |
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `isActive` | `boolean` |  | `PaginationLink` に渡す。`aria-current="page"` と枠線付きの見た目になる。 |
+| `text` | `string` | `"Previous" / "Next"` | `PaginationPrevious` / `PaginationNext` のラベル(640px 未満では隠れる)。 |
+
+リンクは素の `<a>` なので、`href` を渡すとそのまま遷移します。画面内の状態だけを変えたい場合は
+`onClick` で `preventDefault()` してください。

package/docs/ja/ui/radio-group.md

@@ -0,0 +1,21 @@
+# Radio Group
+
+> 少数の選択肢から 1 つを選ぶラジオボタン。
+
+選択肢をすべて見せたまま 1 つ選ばせる入力です。選択肢が多いときは
+[`Select`](ui/select)、横並びのボタンで切り替えたいときは
+[`SegmentedControl`](parts/segmented-control) を検討してください。
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@squadbase/vantage/ui";
+```
+
+`RadioGroupItem` 自体はラベルを持ちません。`id` を振って [`Label`](ui/label) の
+`htmlFor` と結んでください。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `value` | `unknown` | `RadioGroup` の選択値(制御)。 |
+| `defaultValue` | `unknown` | `RadioGroup` の初期値(非制御)。 |
+| `onValueChange` | `(value: unknown) => void` | `RadioGroup` に渡す。選ばれた `RadioGroupItem` の `value` を受け取る。 |
+| `disabled` | `boolean` | グループ全体、または項目単位で無効にする。 |