@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.275b4ed

package/docs/ja/slide/slide-kpi-grid.md

@@ -0,0 +1,55 @@
+# SlideKpiGrid
+
+> 2〜4 個の KPI を並べるスコアボード。値・増減・目標。
+
+2〜4 個の KPI カードを横に並べるスコアボードです。各カードにラベル・値・増減・目標が入り、幅は等分されます。
+
+```tsx
+import { SlideKpiGrid } from "@squadbase/vantage/slide";
+import type { SlideKpiGridProps, SlideKpiGridItem, SlideKpiGridDelta } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `items` | `SlideKpiGridItem[]` |  | KPI。2〜4 個。**必須**。各要素は下の `items[].…` の行。 |
+| `items[].label` | `string` |  | 指標名。**必須**。 |
+| `items[].value` | `number \| null` |  | 数値。`null` は「—」と表示される。**必須**。`format` で整形される。 |
+| `items[].format` | `ValueFormat` |  | 値の整形（`"currency"` / `"percent"` / `{ type: "number", unit: "社" }` など）。`delta` と `target` の既定の整形にもなる。 |
+| `items[].display` | `string` |  | 表示する文字だけを置き換える（元の数値は `value` のまま `data-raw` に残る）。 |
+| `items[].delta` | `SlideKpiGridDelta` |  | `{ value: number; format?: ValueFormat }`。増減の大きさを符号付きで（例: `0.074` と `format: "percent"` で「+7.4%」）。向きは符号で決まり、▲ ▼ と「増」「減」も出る。`format` の既定は item の `format`。 |
+| `items[].betterWhen` | `"up" \| "down"` | `"up"` | `delta` のどちらの向きが良いか。色が決まる。 |
+| `items[].comparisonLabel` | `string` |  | `delta` の比較相手（「前月比」）。 |
+| `items[].target` | `number` |  | 目標。`format` は `value` と同じ。「目標 …（達成率 …）」と表示される。達成率は value ÷ target（`betterWhen` が `"down"` なら target ÷ value）。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideKpiGrid } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiGrid
+    title="売上と継続率は計画どおり、新規獲得だけが未達"
+    items={[
+      { label: "月次売上", value: 540_000_000, format: "currency", delta: { value: 0.074, format: "percent" }, comparisonLabel: "前月比", target: 520_000_000 },
+      { label: "継続率", value: 0.982, format: { type: "percent", digits: 1 }, delta: { value: 0.004 }, comparisonLabel: "前月比", target: 0.98 },
+      { label: "新規獲得", value: 38, format: { type: "number", unit: "社" }, delta: { value: -4 }, comparisonLabel: "前月比", target: 50 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 5 個以上は描画されますが `console.warn` が出ます。スライドを分けてください。
+- 値・増減・目標は数値で渡します。整形は `format` が行い、文字を変えたいときだけ `display` を使います。
+- 「目標 …（達成率 …）」「増」「減」などの文言は block が出す日本語固定です。

package/docs/ja/slide/slide-kpi-hero.md

@@ -0,0 +1,58 @@
+# SlideKpiHero
+
+> 1 つの数字を主役にする 1 枚。値・増減・推移の線。
+
+1 つの数字を大きく見せる 1 枚です。左 6 カラムにラベルと値（と増減）、右 6 カラムに推移の線を置きます。`trend` を渡さなければ数字が全幅を使います。
+
+```tsx
+import { SlideKpiHero } from "@squadbase/vantage/slide";
+import type { SlideKpiHeroProps, SlideKpiHeroDelta } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `label` | `string` |  | 数字が何か（「月次売上」）。**必須**。 |
+| `value` | `number \| null` |  | 数値。`null` は「—」と表示される。**必須**。`format` で整形される（元の数値は `data-raw` に残り、書き出しやテストで使う）。 |
+| `format` | `ValueFormat` |  | 値の整形（`"currency"` / `"percent"` など）。`delta` の既定の整形にもなる。 |
+| `display` | `string` |  | 表示する文字だけを置き換える（元の数値は `value` のまま）。 |
+| `delta` | `SlideKpiHeroDelta` |  | `{ value: number; format?: ValueFormat }`。増減の大きさを符号付きで（例: `0.074` と `format: "percent"` で「+7.4%」）。向きは符号で決まり、▲ ▼ と「増」「減」も出る。`format` の既定は `format`。省くと増減は出ない。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | `delta` のどちらの向きが良いか。色が決まる。 |
+| `comparisonLabel` | `string` |  | `delta` の比較相手（「前月比」）。 |
+| `trend` | `{ x: string; y: number }[]` |  | 右側の線の点。省くと数字だけの 1 枚になる。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideKpiHero } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiHero
+    title="9 月の売上は過去最高の 5.4 億円"
+    label="月次売上"
+    value={540_000_000}
+    format="currency"
+    delta={{ value: 0.074, format: "percent" }}
+    comparisonLabel="前月比"
+    trend={[
+      { x: "4 月", y: 460_000_000 }, { x: "5 月", y: 480_000_000 }, { x: "6 月", y: 490_000_000 },
+      { x: "7 月", y: 500_000_000 }, { x: "8 月", y: 503_000_000 }, { x: "9 月", y: 540_000_000 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- コストのように下がることが良い指標は `betterWhen="down"` と書きます。色は `betterWhen` に従い、向き（▲ ▼ と「増」「減」）は `delta.value` の符号で決まります。
+- 「増」「減」「… 時点」「出典: …」は block が出す日本語固定の文言です。
+- グラフは `EChart` でアニメーションなし。pptx への書き出しはその描画を待ちます。

package/docs/ja/slide/slide-next-actions.md

@@ -0,0 +1,49 @@
+# SlideNextActions
+
+> 次の打ち手。担当・期限・確認する指標つきで 3〜5 件。
+
+次に何をするかを示す 1 枚で、多くのレポートの最後に置きます。アクションごとに担当・期限・確認する指標を添えられます。
+
+```tsx
+import { SlideNextActions } from "@squadbase/vantage/slide";
+import type { SlideNextActionsProps, SlideNextActionsItem } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 決定や計画を 1 文で書いた見出し。**必須**。 |
+| `items` | `SlideNextActionsItem[]` | 打ち手。3〜5 件。**必須**。各要素は下の `items[].…` の行。 |
+| `items[].action` | `string` | 何をするか（目的語から始めて 1 文。40 文字程度まで）。**必須**。 |
+| `items[].owner` | `string` | 担当。 |
+| `items[].due` | `string` | 期限。書いたまま 1 行で表示される（「10/31」。10 文字程度まで）。 |
+| `items[].metric` | `string` | 確認する指標。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideNextActions } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideNextActions
+    title="解約と新規獲得の施策を 3 つ、11 月末までに始める"
+    items={[
+      { action: "解約予兆スコアの上位 50 社に CS が連絡する", owner: "CS 部 山田", due: "10/31", metric: "解約率 1.5% 以下" },
+      { action: "紹介プログラムの特典を見直す", owner: "マーケ 佐藤", due: "11/15", metric: "紹介経由の新規 20 社" },
+      { action: "料金ページの導線を改善する", owner: "プロダクト 鈴木", due: "11/30", metric: "申込率 +1pt" },
+    ]}
+  />
+</Slide>
+```
+
+## 注意
+
+- 担当・期限・確認する指標の列は、1 件でも値があるときだけ出ます。
+- 列見出し（担当 / 期限 / 確認する指標）は block が出す日本語固定で、上書きできません。
+- `due` は書いたまま表示されます（「10/31」「来週まで」）。6 件以上は `console.warn` が出ます。

package/docs/ja/slide/slide-scorecard-table.md

@@ -0,0 +1,54 @@
+# SlideScorecardTable
+
+> 指標ごとの目標と実績、状態を並べるスコアカード表。
+
+指標ごとに目標・実績・達成率と、状態（順調 / 要注意 / 遅延）を並べる表の 1 枚です。状態は色付きの点と言葉の両方で示すので、色だけに頼りません。
+
+```tsx
+import { SlideScorecardTable } from "@squadbase/vantage/slide";
+import type { SlideScorecardTableProps, SlideScorecardRow, SlideScorecardStatus } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `rows` | `SlideScorecardRow[]` |  | 行。8 行まで。**必須**。各要素は下の `rows[].…` の行。 |
+| `rows[].metric` | `string` |  | 指標名（20 文字程度まで）。**必須**。 |
+| `rows[].value` | `number \| null` |  | 実績。`null` は「—」と表示される。**必須**。 |
+| `rows[].format` | `ValueFormat` |  | `value` と `target` の整形（`"currency"` / `"percent"` など）。 |
+| `rows[].display` | `string` |  | 表示する実績の文字だけを置き換える（元の数値は `value` のまま）。 |
+| `rows[].target` | `number` |  | 目標。`format` は `value` と同じ。どれかの行に目標があると達成率の列が出る（value ÷ target）。 |
+| `rows[].betterWhen` | `"up" \| "down"` | `"up"` | どちらの向きが良いか。`"down"` なら達成率は target ÷ value になり、コストの目標を下回ると 100% を超える。 |
+| `rows[].status` | `SlideScorecardStatus` |  | `"on"`（順調）/ `"risk"`（要注意）/ `"off"`（遅延）。値から導かず、渡したものをそのまま出す。**必須**。 |
+| `columns` | `Partial<Record<"metric" \| "target" \| "actual" \| "attainment" \| "status", string>>` |  | 見出しの語を差し替える。省いた列は既定（指標 / 目標 / 実績 / 達成率 / 状態）。状態の言葉（順調 / 要注意 / 遅延）は上書きできない。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideScorecardTable } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideScorecardTable
+    title="4 指標のうち 2 つが目標どおり、解約と新規が遅れている"
+    rows={[
+      { metric: "月次売上", value: 540_000_000, target: 520_000_000, format: "currency", status: "on" },
+      { metric: "継続率", value: 0.982, target: 0.98, format: { type: "percent", digits: 1 }, status: "on" },
+      { metric: "解約率", value: 0.018, target: 0.015, format: { type: "percent", digits: 1 }, betterWhen: "down", status: "risk" },
+      { metric: "新規獲得", value: 38, target: 50, format: { type: "number", unit: "社" }, status: "off" },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 7 行からは文字が本文から注記のサイズに下がります。9 行以上は描画されますが `console.warn` が出ます。

package/docs/ja/slide/slide-section.md

@@ -0,0 +1,44 @@
+# SlideSection
+
+> 章の区切りの 1 枚。章タイトルと、任意で目次。
+
+章の区切りに置く 1 枚です。左に章タイトル、`items` を渡すと右に目次（番号つきの一覧）を出し、`current` の章を強調します。
+
+```tsx
+import { SlideSection } from "@squadbase/vantage/slide";
+import type { SlideSectionProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 章のタイトル。**必須**。 |
+| `index` | `number` | 章番号。タイトルの上に「02」のように 2 桁で出る。 |
+| `lead` | `string` | その章が何に答えるかを 1 行で。 |
+| `items` | `string[]` | デッキの章の一覧。右側に番号つきの目次として出る。1 行ずつなので 6 件ほどまで。省くとタイトルが全幅を使う。 |
+| `current` | `number` | `items` のうち強調する章（1 始まり）。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideSection } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideSection
+    index={2}
+    title="解約の動向"
+    lead="どの層が、いつ離れているか"
+    items={["全体像", "解約の動向", "要因の分析", "次の打ち手"]}
+    current={2}
+  />
+</Slide>
+```
+
+## 注意
+
+- 段階表示（reveal）は持ちません。必要なら呼び出し側で `Steps` などで包んでください。
+- 目次に出る番号は `items` の順で自動採番されます。`index` は章番号の表示だけに使われます。

package/docs/ja/slide/slide-source-line.md

@@ -0,0 +1,34 @@
+# SlideSourceLine
+
+> [部品] スライド 1 枚の足元の 1 行。時点・出典・ページ番号。
+
+スライド 1 枚の足元に置く 1 行です。データの時点と出典、任意で右端にページ番号を出します。12 カラムのグリッドの最下段に置く**部品**で、1 枚まるごとの block ではありません。出すものがなければ何も描きません。
+
+```tsx
+import { SlideSourceLine } from "@squadbase/vantage/slide";
+import type { SlideSourceLineProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **スライドの部品**で、1 枚まるごとの block ではありません。`<Slide>` 内の 12 カラムのグリッドの行として置きます（ルートはキャンバスいっぱい（100%×100%）には広がりません）。寸法はすべて部品の中で決まっているので、足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-20"`）。「2026-10-20 時点」と表示される。「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+| `page` | `{ current: number; total: number }` | 右端に「3 / 12」と出すページ番号。呼び出し側から渡す。 |
+
+## 使い方
+
+```tsx
+import { SlideSourceLine } from "@squadbase/vantage/slide";
+
+<SlideSourceLine asOf="2026-10-20" source="社内 BI" page={{ current: 3, total: 12 }} />
+```
+
+## 注意
+
+- ページ番号は SquadKit がスライドの位置を読めないため、`page` で渡します。
+- 「… 時点」「出典: …」は固定の日本語です。

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

@@ -10,7 +10,7 @@ import { Empty } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `title` | `string` | `"Nothing here yet"` | 見出し。 |
+| `title` | `string` | `"表示できるデータがありません"` | 見出し。 |
 | `description` | `string` |  | 見出しの下の補足文。 |
 | `icon` | `ReactNode` |  | 見出しの上に置く絵柄。 |
 | `action` | `ReactNode` |  | 下部に置く次の一手（ボタンやリンク）。 |

package/docs/ja/ui/error-state.md

@@ -10,8 +10,9 @@ import { ErrorState } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `title` | `string` | `"Something went wrong"` | 見出し。 |
-| `message` | `ReactNode` |  | 詳細。エラーメッセージをそのまま出せます。 |
+| `title` | `string` | `"データを読み込めませんでした"` | 見出し。 |
+| `message` | `ReactNode` | `"時間をおいて再試行してください。解決しない場合は管理者にお問い合わせください。"` | 何が起きたか、次に何をすればよいかを平易な言葉で。 |
+| `details` | `ReactNode` |  | 技術的な詳細（エラーメッセージやステータスコード）。「詳細を表示」の中に折りたたまれます。 |
 | `action` | `ReactNode` |  | 再試行ボタンなど。 |
 | `className` | `string` |  | 足すクラス。 |
 
@@ -34,7 +35,7 @@ export default function Customers() {
   if (error)
     return (
       <ErrorState
-        message={error.message}
+        details={error.message}
         action={<Button variant="outline" onClick={() => refetch()}>再試行</Button>}
       />
     );

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

@@ -12,7 +12,7 @@ import { Loading } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `label` | `string` | `"Loading…"` | スピナーの右に出すテキスト。 |
+| `label` | `string` | `"読み込んでいます…"` | スピナーの右に出すテキスト。 |
 | `className` | `string` |  | 足すクラス。既定では最小高 30vh で縦横中央に置かれます。 |
 
 レイアウトを保ったまま待たせたいときは [`Skeleton`](ui/skeleton)、ボタンの中など

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()` してください。