@squadbase/vantage 0.0.1 → 0.1.1

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

@@ -0,0 +1,64 @@
+# FilterBar
+
+> フィルタ一式を 1 つの値オブジェクトで扱う行。
+
+複数のフィルタをまとめて扱う行です。値は `FilterValues`（`{ [key]: string | string[] }`）という
+1 つのオブジェクトで持ち、選択中の条件をチップで表示したり、一括で消したりできます。
+
+```tsx
+import {
+  FilterBar,
+  FilterBarSelect,
+  FilterBarMultiSelect,
+  FilterBarActiveChips,
+  FilterBarClearButton,
+  FilterBarPreset,
+} from "@squadbase/vantage/components";
+import type { FilterConfig, FilterValues, FilterOption } from "@squadbase/vantage/components";
+```
+
+## FilterBarPreset
+
+`filters` に定義を並べるだけで、セレクト・複数選択・チップ・クリアボタンまで組み上がります。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `filters` | `FilterConfig[]` | フィルタの定義。 |
+| `value` | `FilterValues` | 現在の値。 |
+| `onChange` | `(values: FilterValues) => void` | 変更時。 |
+| `onClear` | `() => void` | クリアボタンを押したとき。 |
+
+```ts
+interface FilterConfig {
+  key: string;
+  label: string;
+  type: "select" | "multiselect" | "date" | "daterange" | "search";
+  options?: FilterOption[]; // { label, value, count?, disabled? }
+  placeholder?: string;
+  defaultValue?: string | string[];
+}
+```
+
+`FilterOption` の `count` を入れると、候補の右に件数が出ます。
+
+## 自分で組む
+
+```tsx
+<FilterBar value={values} onChange={setValues} onClear={() => setValues({})}>
+  <FilterBarSelect filterKey="region" label="地域" options={regions} />
+  <FilterBarMultiSelect filterKey="status" label="状態" options={statuses} />
+  <FilterBarClearButton />
+  <FilterBarActiveChips filters={filters} />
+</FilterBar>
+```
+
+## クエリと繋ぐ
+
+`FilterValues` をそのまま `queryKey` に入れると、条件が変わったときだけ再取得されます。
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["sales", values],
+  queryFn: () => apiFetch(`/api/sales?${new URLSearchParams(values as never)}`).then((r) => r.json()),
+});
+```

package/docs/ja/parts/funnel-steps.md

@@ -0,0 +1,33 @@
+# FunnelSteps
+
+> ファネルの各段を棒で示す。転換率も出せる。
+
+ファネルの各段を、先頭を最大幅とする棒で表します。段の間の転換率も出せます。ECharts を持ち出す
+ほどではない、軽い可視化です。
+
+```tsx
+import { FunnelSteps, funnelStepsVariants } from "@squadbase/vantage/components";
+import type { FunnelStep } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `FunnelStep[]` |  | 各段。**先頭が最大幅**になる。 |
+| `showConversion` | `boolean` |  | 段の間に転換率を出す。 |
+| `formatValue` | `(value: number) => string` |  | 値の書式。既定はそのまま。 |
+| `animate` | `boolean` |  | マウント時に幅を伸ばすアニメーション。 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
+| `direction` | `"vertical" \| "horizontal"` | `"vertical"` |  |
+
+## FunnelStep
+
+```ts
+interface FunnelStep {
+  label: string;
+  value: number;
+  color?: string; // 既定はテーマの chart 色
+  onClick?: () => void;
+}
+```
+
+`onClick` を渡した段は押せるようになるので、その段の内訳へドリルダウンさせられます。

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

@@ -0,0 +1,37 @@
+# Placeholder
+
+> 仮データであることを示す、インラインの目印。
+
+まだ本物のデータを繋いでいない箇所を「仮置き」として見せます。薄い色と `animate-pulse` が
+**「ここは差し替える値だ」**という合図になり、実データを入れ忘れたまま共有してしまう事故を防ぎます。
+
+```tsx
+import { Placeholder } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `children` | `ReactNode` | 仮の値。文字列でも要素でもよい。 |
+| `className` | `string` | 大きさ・太さなどの上書き（例: `text-2xl font-medium`）。 |
+
+残りの props は `<span>` にそのまま渡ります。
+
+## `Skeleton` との違い
+
+| | 用途 | 要素 |
+| --- | --- | --- |
+| [`Skeleton`](ui/skeleton) | **読み込み中**。実データが来れば消える | ブロック `<div>` |
+| `Placeholder` | **仮の値**。実装者が差し替えるまで残る | インライン `<span>` |
+
+インライン要素なので、`<p>` や見出しの**文中に置けます**。`Skeleton` はブロック要素なので、
+文中に混ぜると行が崩れます。
+
+```tsx
+<p>
+  今月の売上は <Placeholder>¥1,240,000</Placeholder> でした。
+</p>
+```
+
+> [!TIP]
+> テンプレートから作り始めたときは、`Placeholder` を検索して潰していけば「まだ繋いでいない箇所」の
+> チェックリストになります。

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

@@ -0,0 +1,47 @@
+# Sparkline
+
+> 表のセルや KPI タイルに置く、インラインの推移グラフ。
+
+数値の並びを、軸も凡例もない小さな折れ線・棒で描きます。**`EChart` ではなく単一の `<svg>`**
+なので、表のセルやタイルに何十個並べても軽いままです。
+
+```tsx
+import { Sparkline } from "@squadbase/vantage/components";
+import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `SparklineDataPoint[]` |  | `{ value: number; label?: string }` の配列。**必須**。空配列なら何も描かない。 |
+| `variant` | `"line" \| "bar"` | `"line"` | 折れ線か棒か。 |
+| `height` | `number` | `40` | 高さ（px）。幅は親要素いっぱい。 |
+| `color` | `string` | `"text-chart-1"` | Tailwind の **text-* クラス**。`currentColor` 経由で線と塗りの両方に効く。 |
+| `area` | `boolean` | `false` | 折れ線の下を薄く塗る（line のみ）。 |
+| `animate` | `boolean` | `false` | マウント時に描画アニメーションする。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は `<svg>` にそのまま渡ります。
+
+> [!WARNING]
+> `color` は**クラス名**です。`color="#3b82f6"` のような値は効きません — 線も塗りも
+> `currentColor` を見ているため、`text-chart-2` のようなユーティリティを渡してください。
+> テーマトークン（`--chart-1`〜`--chart-5`）を変えれば配色も一緒に変わります。
+
+## 大きさを決める
+
+`preserveAspectRatio="none"` で横方向に引き伸ばすので、**幅は親要素が決めます**。表のセルに
+入れるときは幅と高さを絞ってください。
+
+```tsx
+<Sparkline data={points} height={16} className="w-20 shrink-0" />
+```
+
+## EChart との使い分け
+
+軸・凡例・ツールチップ・複数系列が要るなら [`EChart`](parts/echart) を使います。
+`Sparkline` が持つのは「値の並びの形」だけで、**目盛りも数値も出しません**。
+
+> [!NOTE]
+> `aria-hidden="true"` が付いているため、スクリーンリーダーには読まれません。実際の数値は
+> [`MetricValue`](parts/metric-value) や
+> [`TrendIndicator`](parts/trend-indicator) など、テキストとして隣に置いてください。

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,175 @@
+# ファイルベースルーティング
+
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・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` は **ルート（プロジェクト直下）でのみ**認識されます。
+
+## ルート一覧からナビを作る
+
+`useRoutes()` はアプリの全ページルートを返します。ファイルシステムが正本なので、
+ページファイルを 1 つ足せばナビに 1 行増えます。手で管理するリンク配列は不要です。
+
+```tsx
+// _layout.tsx
+import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router";
+
+export default function RootLayout() {
+  // 動的ルート（/sales/:customerId）は URL が 1 つに定まらないので外す
+  const routes = useRoutes().filter((route) => !route.dynamic);
+  const current = useCurrentRoute();
+
+  return (
+    <div>
+      <nav>
+        {routes.map((route) => (
+          <Link key={route.path} to={route.to} aria-current={route.path === current?.path}>
+            {route.label}
+          </Link>
+        ))}
+      </nav>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+並び順は Vantage のスキャン順（浅い順 → 静的が動的より先 → アルファベット順）で、
+そのままナビに使える順序です。
+
+各要素は `RouteInfo` です。
+
+| フィールド | 型 | 内容 |
+|---|---|---|
+| `path` | `string` | 表示パス。`/sales/:customerId` |
+| `to` | `string` | `Link` の `to` に渡す形。`/sales/$customerId` |
+| `params` | `string[]` | 動的パラメータ名。catch-all は `_splat` |
+| `dynamic` | `boolean` | 動的パラメータを持つか |
+| `index` | `boolean` | ディレクトリの index ルートか |
+| `label` | `string` | `navLabel` → `title` → `path` の順で決まる表示名 |
+| `title` / `description` / `navLabel` | `string \| undefined` | [`definePage`](pages-and-metadata) の値 |
+
+`useCurrentRoute()` は今表示中のルートを返します（404 のときは `undefined`）。
+上の例のような「現在地」判定のほか、パンくずやページ見出しに使えます。
+
+> [!NOTE]
+> `label` は `navLabel` を優先します。`title` は `document.title` に使われるためサイト名を
+> 含めがちで、ナビには長すぎることが多いためです。
+
+## URL にフィルタ状態を置く
+
+ダッシュボードの絞り込みは URL に置くと、リロードで消えず、そのまま同僚に共有できます。
+`useSearchParam` は `useState` と同じ形で search params を読み書きします。
+
+```tsx
+import { useSearchParam } from "@squadbase/vantage/router";
+import { SegmentedControl } from "@squadbase/vantage/components";
+
+export default function Sales() {
+  const [region, setRegion] = useSearchParam("region", "all");
+
+  return <SegmentedControl options={REGIONS} value={region} onChange={setRegion} />;
+}
+```
+
+- 値は**常に文字列**です（`?year=2024` は数値としてパースされますが、この hook が文字列に戻します）。
+- **デフォルト値**（上の例では `"all"`）や `null` を書き込むと、キーは URL から取り除かれます。
+- 履歴は既定で `replace`（戻るボタンが埋まらない）。`{ replace: false }` で push に変えられます。
+
+配列やオブジェクトなど JSON になる値は `useSearchState` を使います。関数更新も渡せます。
+
+```tsx
+import { useSearchState } from "@squadbase/vantage/router";
+
+const [segments, setSegments] = useSearchState<string[]>("segments", []);
+setSegments((prev) => [...prev, "enterprise"]);
+```
+
+## 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) の方が軽量です。