@squadbase/vantage 0.0.1 → 0.1.0

package/docs/ja/parts/metric-value.md

@@ -0,0 +1,25 @@
+# MetricValue
+
+> KPI の数値。単位は MetricUnit で。
+
+KPI の数値を大きく見せるための、字送りを詰めた表示です。単位や補助的な文字は `MetricUnit` で
+添えます。
+
+```tsx
+import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | 文字サイズ。 |
+| `className` | `string` |  | 足すクラス。 |
+
+既定で上下に余白（`my-4`）が付きます。カードの中でぴったり詰めたいときは `className="my-0"` を
+渡してください。
+
+```tsx
+<DashboardCardPreset title="売上">
+  <MetricValue className="my-0">¥1,240,000</MetricValue>
+  <TrendIndicator value={12.4} direction="up" />
+</DashboardCardPreset>
+```

package/docs/ja/parts/multi-select.md

@@ -0,0 +1,27 @@
+# MultiSelect
+
+> 検索できる複数選択。選択はチップで表示。
+
+検索欄付きの複数選択です。選んだものはトリガーにチップとして並び、`maxCount` を超えた分は
+「+N」にまとめられます。
+
+```tsx
+import { MultiSelect } from "@squadbase/vantage/components";
+import type { SelectOption, SelectOptionGroup } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `options` | `SelectOption[] \| SelectOptionGroup[]` | 候補。グループ配列を渡すと見出し付きになる。 |
+| `value` | `string[]` | 選択中の値。 |
+| `onChange` | `(value: string[]) => void` | 変更時。 |
+| `maxCount` | `number` | チップとして並べる上限。超えた分は「+N」になる。 |
+| `onSearch` | `(query: string) => void` | 入力のたびに呼ばれる。サーバー側検索に使う。 |
+| `isLoading` | `boolean` | 候補を取得中。 |
+| `placeholder` | `string` | 未選択時のトリガー表示。 |
+| `searchPlaceholder` | `string` | 検索欄のプレースホルダ。 |
+| `emptyText` | `string` | 0 件のときの表示。 |
+| `disabled` | `boolean` | 操作を無効にする。 |
+
+フィルタ行の中で使うなら、[`FilterBar`](parts/filter-bar) の `FilterBarMultiSelect`
+が値の受け渡しまで面倒を見てくれます。

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

@@ -0,0 +1,45 @@
+# PageShell
+
+> ヘッダー帯・サマリー・本文からなるページ枠。
+
+1 ページぶんの枠です。全幅のヘッダー帯、その中に置けるサマリーカードの行、そして本文の 3 段で
+できています。各パーツは薄い `<div>` なので、必要なものだけ使えます。
+
+```tsx
+import {
+  PageShell,
+  PageShellHeader,
+  PageShellHeading,
+  PageShellTitle,
+  PageShellDescription,
+  PageShellHeaderEnd,
+  PageShellMeta,
+  PageShellActions,
+  PageShellSummary,
+  PageShellSummaryCard,
+  PageShellContent,
+  pageShellSummaryCardVariants,
+} from "@squadbase/vantage/components";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `PageShell` | 全体の縦積み |
+| `PageShellHeader` | 下線付きのヘッダー帯。左に見出し、右に `HeaderEnd` の 2 列 |
+| `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | 見出しブロック |
+| `PageShellHeaderEnd` | 右端の縦積み |
+| `PageShellMeta` | 「最終更新 10 分前」のような補足 |
+| `PageShellActions` | ボタン行 |
+| `PageShellSummary` | サマリーカードのグリッド（ヘッダー内で全幅） |
+| `PageShellSummaryCard` | サマリー 1 枚。`accent` で色が付く |
+| `PageShellContent` | 本文 |
+
+`PageShellSummaryCard` の `accent` は `default` / `accent` / `amber` / `blue` / `emerald` / `red`
+です。`accent` はテーマの `--chart-1` を使うので、テーマトークンを変えると一緒に変わります。
+
+## レイアウトと組み合わせる
+
+ページごとに書くより、`_layout.tsx` に置いて全ページで共有する方が実際的です
+（[ルーティング](routing) を参照）。

package/docs/ja/parts/searchable-select.md

@@ -0,0 +1,47 @@
+# SearchableSelect
+
+> 検索できる単一選択。候補が多いときに。
+
+検索欄の付いた単一選択です。候補が多くて [`Select`](ui/select) では探しづらいときに
+使います。`onSearch` を渡せばサーバー側検索にもできます。
+
+```tsx
+import { SearchableSelect } from "@squadbase/vantage/components";
+import type { SelectOption, SelectOptionGroup } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `options` | `SelectOption[] \| SelectOptionGroup[]` | 候補。グループ配列を渡すと見出し付きになる。 |
+| `value` | `string` | 選択中の値。 |
+| `onChange` | `(value: string \| undefined) => void` | 変更時。 |
+| `onSearch` | `(query: string) => void` | 入力のたびに呼ばれる。サーバー側検索に使う。 |
+| `clearable` | `boolean` | 選択解除できるようにする。 |
+| `isLoading` | `boolean` | 候補を取得中。 |
+| `placeholder` | `string` | 未選択時のトリガー表示。 |
+| `searchPlaceholder` | `string` | 検索欄のプレースホルダ。 |
+| `emptyText` | `string` | 0 件のときの表示。 |
+| `disabled` | `boolean` | 操作を無効にする。 |
+
+## サーバー側で検索する
+
+`onSearch` を渡して `options` を差し替えます。絞り込みはサーバーの仕事になるので、返ってきた
+候補をそのまま渡してください。
+
+```tsx
+const [query, setQuery] = useState("");
+const { data, isFetching } = useQuery({
+  queryKey: ["customers", query],
+  queryFn: () => apiFetch(`/api/customers?q=${query}`).then((r) => r.json()),
+});
+
+<SearchableSelect
+  options={data ?? []}
+  onSearch={setQuery}
+  isLoading={isFetching}
+  value={value}
+  onChange={setValue}
+/>;
+```
+
+複数選べるようにしたいときは [`MultiSelect`](parts/multi-select) を使います。

package/docs/ja/parts/section-header.md

@@ -0,0 +1,20 @@
+# SectionHeader
+
+> セクションの見出しとアクション。
+
+ページの中でセクションを区切る見出しです。見出しレベルは `as` で選べます。
+
+```tsx
+import { SectionHeader } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 見出し。 |
+| `description` | `string` |  | 見出しの下の補足文。 |
+| `actions` | `ReactNode` |  | 右端に置く要素。 |
+| `as` | `"h1" \| "h2" \| "h3" \| "h4"` | `"h2"` | 見出しレベル。文字サイズも一緒に変わる。 |
+| `className` | `string` |  | 足すクラス。 |
+
+ページ全体の見出しには [`PageShell`](parts/page-shell) のヘッダー帯を使ってください。
+`SectionHeader` はその中のセクション向けです。

package/docs/ja/parts/segmented-control.md

@@ -0,0 +1,26 @@
+# SegmentedControl
+
+> 単一選択のセグメント。ToggleGroup の配列を隠す。
+
+2〜4 個の選択肢を横一列で切り替えます。中身は [`ToggleGroup`](ui/toggle-group) ですが、
+**単一選択なので `value` は文字列 1 つ**です — Base UI の配列 API を扱う手間はここで吸収されて
+います。
+
+```tsx
+import { SegmentedControl } from "@squadbase/vantage/components";
+import type { SegmentOption } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `options` | `SegmentOption[]` |  | `{ label, value, icon?, disabled? }` の配列。 |
+| `value` | `string` |  | 選択中の値（**文字列 1 つ**）。 |
+| `onChange` | `(value: string) => void` |  | 変更時。 |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | アイコンの大きさ。 |
+| `fullWidth` | `boolean` |  | 親の幅いっぱいに広げる。 |
+| `ariaLabel` | `string` |  | グループ全体の説明。 |
+
+`icon` には `lucide-react` のコンポーネントをそのまま渡せます。
+
+選択肢が 5 個を超えるなら [`Select`](ui/select)、切り替える対象がページ相当なら
+[`Tabs`](ui/tabs) の方が向いています。

package/docs/ja/parts/status-badge.md

@@ -0,0 +1,44 @@
+# StatusBadge
+
+> ドット付きのステータスバッジ。色は名前で決まる。
+
+行やレコードの状態を、色付きのドットとラベルで示します。状態の文字列から色への対応は
+組み込みの表で決まり、`colorMap` で足したり上書きしたりできます。
+
+```tsx
+import { StatusBadge } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `status` | `string` | 状態の文字列。色はこれで決まる。 |
+| `label` | `string` | 表示するテキスト。省くと `status` がそのまま出る。 |
+| `colorMap` | `Record<string, string>` | 状態 → 色名の対応。既定の表に上書きされる。 |
+| `className` | `string` | 足すクラス。 |
+
+## 既定の対応
+
+| `status` | 色 |
+| --- | --- |
+| `active` | green |
+| `inactive` | gray |
+| `warning` | yellow |
+| `error` | red |
+| `pending` | blue |
+
+未知の状態は gray になります。独自の状態を足すときは `colorMap` に
+`green` / `gray` / `yellow` / `red` / `blue` のいずれかを割り当ててください。
+
+```tsx
+<StatusBadge status="reviewing" label="レビュー中" colorMap={{ reviewing: "blue" }} />
+```
+
+テーブルのセルにそのまま置けます。
+
+```tsx
+{
+  accessorKey: "status",
+  header: "状態",
+  cell: ({ row }) => <StatusBadge status={row.original.status} />,
+}
+```

package/docs/ja/parts/trend-indicator.md

@@ -0,0 +1,26 @@
+# TrendIndicator
+
+> 増減の矢印と変化率。良し悪しは positiveIsGood で決まる。
+
+前期比などの変化を、矢印と変化率で示します。**「上がった＝良い」とは限らない**ので、色は
+`direction` と `positiveIsGood` の組み合わせで決まります — 解約率のように下がる方が良い指標では
+`positiveIsGood={false}` を渡してください。
+
+```tsx
+import { TrendIndicator } from "@squadbase/vantage/components";
+import type { TrendDirection } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number` |  | 変化率（`12.4` で 12.4%）。 |
+| `direction` | `"up" \| "down" \| "neutral"` |  | 矢印の向き。**必須**。 |
+| `positiveIsGood` | `boolean` | `true` | 上がることが良いか。`false` にすると色が反転する。 |
+| `className` | `string` |  | 足すクラス。 |
+
+> [!WARNING]
+> `direction` は必須です。`value` の符号からは推測しません — 「値は減ったが、それは良いこと」と
+> いう場合を表現できるようにするためです。
+
+色は 3 通りです。良い方向なら `--chart-1`、悪い方向なら `--primary`、`neutral` なら
+`--muted-foreground`。テーマトークンを変えればここも一緒に変わります。

package/docs/ja/routing.md

@@ -0,0 +1,95 @@
+# ファイルベースルーティング
+
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
+
+Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
+
+## ページの規約
+
+| ファイル | ルート |
+|---|---|
+| `index.tsx` | `/` |
+| `monthly-analysis.tsx` | `/monthly-analysis` |
+| `sales/index.tsx` | `/sales` |
+| `sales/[customerId].tsx` | `/sales/:customerId` |
+| `sales/[...path].tsx` | `/sales/*`（catchall） |
+| `_layout.tsx` | そのディレクトリ配下のレイアウト（入れ子可） |
+| `_404.tsx` | not-found の UI（**ルートのみ**） |
+| `_error.tsx` | error の UI（**ルートのみ**） |
+
+- `[name]` → 動的パラメータ、`[...name]` → catchall。
+- `index` は自身のディレクトリにマップ（名前は URL から落ちる）。
+- `_` で始まるファイルは予約（`_layout`/`_404`/`_error`）またはプライベート（ルーティングされない）。
+
+## ルーティングされないディレクトリ
+
+次のディレクトリは決して走査されません。ここには自由にコードを置けます。
+
+```text
+components/   再利用する React コンポーネント
+hooks/        カスタムフック
+lib/          ユーティリティ
+server/       API（存在するとサーバーが有効になる）
+public/       静的アセット
+```
+
+> [!NOTE]
+> ファイル間の import は **ランタイムの `.js` 指定子**を使います（例: `./components/revenue-chart.js`）。
+> ESM の Node 解決に必要です。
+
+## 動的パラメータの 3 つの綴り
+
+同じパラメータが、場所によって 3 つの綴りで現れます。**必ず一致させます。**
+
+| 場所 | 綴り | 例 |
+|---|---|---|
+| ファイル名 | `[id]` | `sales/[customerId].tsx` |
+| 表示ルート | `:id` | `/sales/:customerId` |
+| リンク | `$id` + `params` | `to="/sales/$customerId"` `params={{ customerId }}` |
+
+```tsx
+import { Link, useParams } from "@squadbase/vantage/router";
+
+function Row({ customerId }: { customerId: string }) {
+  return (
+    <Link to="/sales/$customerId" params={{ customerId }}>
+      顧客を開く
+    </Link>
+  );
+}
+
+// sales/[customerId].tsx
+export default function Customer() {
+  const { customerId } = useParams({ strict: false });
+  return <div>顧客 {customerId}</div>;
+}
+```
+
+## レイアウトと入れ子
+
+`_layout.tsx` は `<Outlet />` を描画して子ルートを囲みます。ディレクトリごとに置けば入れ子になります。
+
+```tsx
+// _layout.tsx
+import { Outlet } from "@squadbase/vantage/router";
+
+export default function RootLayout() {
+  return (
+    <div className="min-h-screen">
+      <nav className="border-b p-4">My Dashboard</nav>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+`_404.tsx` と `_error.tsx` は **ルート（プロジェクト直下）でのみ**認識されます。
+
+## HMR とルート再生成
+
+`.tsx` ページや `server/api` ファイルを追加・削除すると、開発サーバーがルートを再生成して
+フルリロードします。ページ本体を編集した場合は React Fast Refresh がその場で反映します。
+
+## 次に読む
+
+- [ページと definePage](pages-and-metadata) — ページの契約とメタデータ

package/docs/ja/ui/accordion.md

@@ -0,0 +1,37 @@
+# Accordion
+
+> 開閉する見出しの縦積み。既定では 1 つだけ開く。
+
+見出しをクリックして中身を開閉するリストです。既定では一度に 1 つだけ開きます。複数を同時に開き
+たいときは `openMultiple` を付けます。
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Accordion` | 全体。`value` / `defaultValue` は**開いている項目の配列** |
+| `AccordionItem` | 1 項目。`value` で識別する |
+| `AccordionTrigger` | 見出しボタン。シェブロンは自動で付く |
+| `AccordionContent` | 開閉する中身 |
+
+## 複数同時に開く
+
+```tsx
+<Accordion openMultiple defaultValue={["a", "b"]}>
+```
+
+> [!NOTE]
+> `value` は Radix 版のような文字列ではなく**配列**です（Base UI の仕様）。1 つだけ開く場合も
+> `defaultValue={["freshness"]}` のように配列で渡します。
+
+常に開いている単独の折りたたみが欲しいだけなら
+[`Collapsible`](ui/collapsible) の方が軽量です。

package/docs/ja/ui/alert.md

@@ -0,0 +1,31 @@
+# Alert
+
+> ページ内に置く通知。中身は表示したまま注意を促す。
+
+ページの中に置く通知です。「この画面は失敗した」を表す
+[`ErrorState`](ui/error-state) と違い、中身が表示できている上での注意喚起に使います。
+
+```tsx
+import { Alert, AlertTitle, AlertDescription, AlertAction } from "@squadbase/vantage/ui";
+```
+
+## パーツと variant
+
+| パーツ | 役割 |
+| --- | --- |
+| `Alert` | 枠。`variant`: `default` \| `destructive` |
+| `AlertTitle` | 見出し |
+| `AlertDescription` | 本文 |
+| `AlertAction` | 右端に寄せるアクション |
+
+アイコンは `Alert` の直下に置くだけで、グリッドが自動で 2 列になります。`lucide-react` から直接
+import して構いません。
+
+```tsx
+import { Info } from "lucide-react";
+
+<Alert>
+  <Info />
+  <AlertTitle>読み取り専用です</AlertTitle>
+</Alert>;
+```

package/docs/ja/ui/badge.md

@@ -0,0 +1,23 @@
+# Badge
+
+> 小さなラベル。件数・状態・タグに。
+
+テキストの横に添える小さなラベルです。行の状態を色付きのドットで示したいときは
+[`StatusBadge`](parts/status-badge) を使ってください。
+
+```tsx
+import { Badge, badgeVariants } from "@squadbase/vantage/ui";
+```
+
+## Variant
+
+`default` / `secondary` / `destructive` / `outline` / `ghost` / `link`。
+
+`badgeVariants` はクラス文字列を返す関数で、`<a>` など別の要素にバッジの見た目を移したいときに
+使います。
+
+```tsx
+<a href="/docs" className={badgeVariants({ variant: "outline" })}>
+  ドキュメント
+</a>
+```

package/docs/ja/ui/breadcrumb.md

@@ -0,0 +1,38 @@
+# Breadcrumb
+
+> 階層を示すパンくずリスト。
+
+いま見ているページが階層のどこにあるかを示します。ドリルダウンする詳細ページ
+（`/sales/$customerId` など）で特に効きます。
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `BreadcrumbLink` | 途中の階層（リンク） |
+| `BreadcrumbPage` | 現在地。リンクにしない |
+| `BreadcrumbSeparator` | 区切り。中身を渡せば記号を差し替えられる |
+| `BreadcrumbEllipsis` | 省略した中間階層 |
+
+## ルーターのリンクと組み合わせる
+
+`BreadcrumbLink` は `render` プロップで別のコンポーネントに置き換えられます。Vantage の
+[`Link`](routing) を渡せばクライアントサイド遷移になります。
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<BreadcrumbLink render={<Link to="/sales" />}>売上</BreadcrumbLink>;
+```

package/docs/ja/ui/button.md

@@ -0,0 +1,39 @@
+# Button
+
+> 6 つの variant と 8 つの size を持つボタン。
+
+いちばんよく使うコンポーネントです。`variant` で意味づけを、`size` で大きさを決めます。
+
+```tsx
+import { Button, buttonVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link"` | `"default"` | 見た目と意味づけ。 |
+| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` | 高さと余白。`icon` 系は正方形になる。 |
+| `render` | `ReactElement` |  | 別の要素として描画する（Radix の `asChild` に相当）。 |
+
+アイコンは子要素として置くだけでサイズと余白が揃います。アイコンだけのボタンには
+`size="icon"` と `aria-label` を必ず付けてください。
+
+## リンクをボタンに見せる
+
+`render` に要素を渡します。`asChild` は Base UI にはありません。
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<Button render={<Link to="/sales" />}>売上を見る</Button>;
+```
+
+クラス文字列だけが欲しいときは `buttonVariants({ variant, size })` を使います。
+
+## 処理中の表示
+
+```tsx
+<Button disabled={isPending}>
+  {isPending && <Spinner />}
+  保存
+</Button>
+```

package/docs/ja/ui/calendar.md

@@ -0,0 +1,28 @@
+# Calendar
+
+> react-day-picker ベースの日付カレンダー。
+
+単日・複数日・期間を選べるカレンダーです。ダッシュボードで期間を選ばせたい場合は、これを直接
+使うより [`DateRangePicker`](parts/date-range-picker) の方が手早く済みます。
+
+```tsx
+import { Calendar, CalendarDayButton } from "@squadbase/vantage/ui";
+```
+
+props は [react-day-picker](https://daypicker.dev) の `DayPicker` そのままで、Vantage 側で足して
+いるのは次の 3 つだけです。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `captionLayout` | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"` | 月・年の見出しをテキストにするかセレクトにするか。 |
+| `buttonVariant` | `Button の variant` | `"ghost"` | 前後の月へ送るボタンの見た目。 |
+| `showOutsideDays` | `boolean` | `true` | 前後の月の日を薄く表示するか。 |
+
+`mode` は `"single"` / `"multiple"` / `"range"` で、`selected` と `onSelect` の型がそれに追従
+します。`CalendarDayButton` は 1 日分のセルで、日付の下にドットやラベルを描きたいときに差し
+替えます。
+
+> [!NOTE]
+> ロケールは `locale` プロップに `date-fns` のロケールを渡して切り替えます。`date-fns` は
+> Vantage の依存に含まれていますが、アプリからの直接 import は避け、必要なら
+> [`DateRangePicker`](parts/date-range-picker) 側で完結させるのが安全です。

package/docs/ja/ui/card.md

@@ -0,0 +1,35 @@
+# Card
+
+> 汎用のカード。ダッシュボードのタイルには DashboardCard を。
+
+汎用のカードです。ダッシュボードのタイルには、余白とスケルトンまで組んである
+[`DashboardCard`](parts/dashboard-card) の方が向いています。
+
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardAction,
+  CardContent,
+  CardFooter,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Card` | 枠。`size`: `default` \| `sm`（内側の余白が変わる） |
+| `CardHeader` | 見出し行 |
+| `CardTitle` / `CardDescription` | 見出しと補足 |
+| `CardAction` | 見出し行の右端。置くとヘッダーが自動で 2 列になる |
+| `CardContent` | 本文 |
+| `CardFooter` | 下端。置くとカード下部の余白が自動で詰まる |
+
+余白は `--card-spacing` という CSS 変数 1 つで決まっているので、個別に上書きできます。
+
+```tsx
+<Card className="[--card-spacing:--spacing(6)]">…</Card>
+```

package/docs/ja/ui/checkbox.md

@@ -0,0 +1,34 @@
+# Checkbox
+
+> チェックボックス。中間状態は indeterminate プロップで。
+
+オン/オフの入力です。Base UI 版では `checked` が `boolean` のみを取り、中間状態は別プロップに
+分かれています — Radix 版から移ってきた場合の最大の違いです。
+
+```tsx
+import { Checkbox } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `checked` | `boolean` | チェック状態。`"indeterminate"` は受け付けない。 |
+| `indeterminate` | `boolean` | 中間状態（一部だけ選択）。`checked` とは独立。 |
+| `onCheckedChange` | `(checked: boolean) => void` | 変更時。値は必ず boolean。 |
+| `disabled` | `boolean` | 操作を無効にする。 |
+
+> [!WARNING]
+> Radix 版の `checked={"indeterminate"}` は型エラーになります。Base UI では `indeterminate` を
+> 独立したプロップとして渡してください。
+
+## テーブルの全選択
+
+[`DataTable`](parts/data-table) の選択列がこの形です。
+
+```tsx
+<Checkbox
+  checked={table.getIsAllPageRowsSelected()}
+  indeterminate={table.getIsSomePageRowsSelected()}
+  onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
+  aria-label="全て選択"
+/>
+```

package/docs/ja/ui/cn.md

@@ -0,0 +1,34 @@
+# cn()
+
+> 条件付きでクラスを組み立て、競合を解決するヘルパー。
+
+`className` を条件付きで組み立てるヘルパーです。`clsx` で条件を解決し、`tailwind-merge` で競合
+するユーティリティを解決します。
+
+```tsx
+import { cn } from "@squadbase/vantage/ui";
+import type { ClassValue } from "@squadbase/vantage/ui";
+
+<div className={cn("p-4", isActive && "bg-accent", className)} />;
+```
+
+## 後から渡したクラスが勝つ
+
+`tailwind-merge` を通しているので、競合するユーティリティは**後ろが勝ちます**。
+
+```tsx
+cn("p-2", "p-4"); // → "p-4"
+```
+
+これが効くおかげで、コンポーネントに渡した `className` が既定のスタイルを確実に上書きできます。
+組み込みコンポーネントはすべて内部で `cn()` を使っているので、`className` は常に上書きとして
+機能します。
+
+```tsx
+// 既定の bg-primary を確実に打ち消せる
+<Button className="bg-emerald-600 hover:bg-emerald-700">実行</Button>
+```
+
+> [!NOTE]
+> `clsx` や `tailwind-merge` を直接 import する必要はありません（アプリからの直接 import は
+> 避けてください）。両方まとめてこの `cn()` が公開の入り口です。