@squadbase/vantage 0.1.0 → 0.1.1

package/docs/en/parts/placeholder.md

@@ -0,0 +1,38 @@
+# Placeholder
+
+> An inline marker for sample, not-yet-real data.
+
+Marks a spot where real data isn't wired up yet. The muted colour plus `animate-pulse` says
+**"this value is meant to be replaced"**, so a template never gets shared with sample numbers
+mistaken for real ones.
+
+```tsx
+import { Placeholder } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactNode` | The sample value — text or elements. |
+| `className` | `string` | Override size and weight (e.g. `text-2xl font-medium`). |
+
+Any remaining props go straight to the `<span>`.
+
+## Placeholder or Skeleton
+
+| | Use for | Element |
+| --- | --- | --- |
+| [`Skeleton`](ui/skeleton) | **Loading** — it disappears when data arrives | block `<div>` |
+| `Placeholder` | **A stand-in value** — it stays until you replace it | inline `<span>` |
+
+Being inline, it is safe **inside a sentence** — in a `<p>` or a heading. `Skeleton` is a block
+element and breaks the line if you mix it into running text.
+
+```tsx
+<p>
+  Revenue this month was <Placeholder>$12,400</Placeholder>.
+</p>
+```
+
+> [!TIP]
+> When you start from a template, searching for `Placeholder` gives you the checklist of everything
+> still unwired.

package/docs/en/parts/sparkline.md

@@ -0,0 +1,47 @@
+# Sparkline
+
+> An inline trend chart for table cells and KPI tiles.
+
+Draws a sequence of numbers as a small line or bar chart — no axes, no legend. It is **a single
+`<svg>`, not an `EChart`**, so dozens of them inside table cells or tiles stay cheap.
+
+```tsx
+import { Sparkline } from "@squadbase/vantage/components";
+import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `SparklineDataPoint[]` |  | An array of `{ value: number; label?: string }`. **Required.** An empty array draws nothing. |
+| `variant` | `"line" \| "bar"` | `"line"` | Line or bars. |
+| `height` | `number` | `40` | Height in px; the width fills the parent. |
+| `color` | `string` | `"text-chart-1"` | A Tailwind **text-* class**; it drives stroke and fill through `currentColor`. |
+| `area` | `boolean` | `false` | Fill under the line (`line` only). |
+| `animate` | `boolean` | `false` | Draw in on mount. |
+| `className` | `string` |  | Classes to add. |
+
+Any remaining props go straight to the `<svg>`.
+
+> [!WARNING]
+> `color` is a **class name**. Something like `color="#3b82f6"` does nothing — both the stroke and the
+> fill read `currentColor`, so pass a utility such as `text-chart-2`. Change the theme tokens
+> (`--chart-1` … `--chart-5`) and the colours follow.
+
+## Sizing
+
+`preserveAspectRatio="none"` stretches the chart horizontally, so **the parent decides the width**.
+Inside a table cell, constrain both.
+
+```tsx
+<Sparkline data={points} height={16} className="w-20 shrink-0" />
+```
+
+## Sparkline or EChart
+
+Reach for [`EChart`](parts/echart) when you need axes, a legend, tooltips or multiple
+series. `Sparkline` conveys the *shape* of a series and nothing else — **no ticks, no numbers**.
+
+> [!NOTE]
+> It is `aria-hidden="true"`, so screen readers skip it. Put the actual number next to it as text —
+> [`MetricValue`](parts/metric-value) or
+> [`TrendIndicator`](parts/trend-indicator).

package/docs/en/routing.md

@@ -85,6 +85,88 @@ export default function RootLayout() {
 
 `_404.tsx` and `_error.tsx` are recognized at the **root only**.
 
+## Build a nav from the route list
+
+`useRoutes()` returns every page route in the app. The file system is the source of truth, so adding
+one page file adds one nav entry — there is no link array to maintain.
+
+```tsx
+// _layout.tsx
+import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router";
+
+export default function RootLayout() {
+  // Dynamic routes (/sales/:customerId) have no single URL, so leave them out.
+  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>
+  );
+}
+```
+
+The order is Vantage's scan order — shallow before deep, static before dynamic, alphabetical — which
+is the order a nav wants.
+
+Each entry is a `RouteInfo`:
+
+| Field | Type | Contents |
+|---|---|---|
+| `path` | `string` | Display path, `/sales/:customerId` |
+| `to` | `string` | The form `Link`'s `to` expects, `/sales/$customerId` |
+| `params` | `string[]` | Dynamic parameter names; a catch-all is `_splat` |
+| `dynamic` | `boolean` | Whether the route has dynamic parameters |
+| `index` | `boolean` | Whether it is a directory's index route |
+| `label` | `string` | Display name: `navLabel`, else `title`, else `path` |
+| `title` / `description` / `navLabel` | `string \| undefined` | Values from [`definePage`](pages-and-metadata) |
+
+`useCurrentRoute()` returns the route being rendered, or `undefined` on the 404 route. Beyond the
+"you are here" check above, it fits breadcrumbs and page headings.
+
+> [!NOTE]
+> `label` prefers `navLabel` because `title` drives `document.title` and therefore tends to carry the
+> site name, which is usually too long for a nav.
+
+## Keep filter state in the URL
+
+A dashboard's filters belong in the URL: the view survives a reload and can be pasted to a colleague.
+`useSearchParam` reads and writes one search-param key with a `useState` shape.
+
+```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} />;
+}
+```
+
+- The value is **always a string** (`?year=2024` parses as a number; this hook normalizes it back).
+- Writing the **default value** (`"all"` above) or `null` removes the key from the URL.
+- History defaults to `replace`, so filtering doesn't fill the back button. Pass `{ replace: false }`
+  to push instead.
+
+For anything JSON-serializable — an array, an object — use `useSearchState`, which also accepts a
+functional update.
+
+```tsx
+import { useSearchState } from "@squadbase/vantage/router";
+
+const [segments, setSegments] = useSearchState<string[]>("segments", []);
+setSegments((prev) => [...prev, "enterprise"]);
+```
+
 ## HMR and route regeneration
 
 Adding or removing a `.tsx` page or a `server/api` file regenerates routes and triggers a full

package/docs/index.json

@@ -592,6 +592,16 @@
       "file": "ja/parts/page-shell.md",
       "order": 9
     },
+    {
+      "slug": "parts/placeholder",
+      "lang": "ja",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "Placeholder",
+      "description": "仮データであることを示す、インラインの目印。",
+      "file": "ja/parts/placeholder.md",
+      "order": 10
+    },
     {
       "slug": "parts/searchable-select",
       "lang": "ja",
@@ -600,7 +610,7 @@
       "title": "SearchableSelect",
       "description": "検索できる単一選択。候補が多いときに。",
       "file": "ja/parts/searchable-select.md",
-      "order": 10
+      "order": 11
     },
     {
       "slug": "parts/section-header",
@@ -610,7 +620,7 @@
       "title": "SectionHeader",
       "description": "セクションの見出しとアクション。",
       "file": "ja/parts/section-header.md",
-      "order": 11
+      "order": 12
     },
     {
       "slug": "parts/segmented-control",
@@ -620,7 +630,17 @@
       "title": "SegmentedControl",
       "description": "単一選択のセグメント。ToggleGroup の配列を隠す。",
       "file": "ja/parts/segmented-control.md",
-      "order": 12
+      "order": 13
+    },
+    {
+      "slug": "parts/sparkline",
+      "lang": "ja",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "Sparkline",
+      "description": "表のセルや KPI タイルに置く、インラインの推移グラフ。",
+      "file": "ja/parts/sparkline.md",
+      "order": 14
     },
     {
       "slug": "parts/status-badge",
@@ -630,7 +650,7 @@
       "title": "StatusBadge",
       "description": "ドット付きのステータスバッジ。色は名前で決まる。",
       "file": "ja/parts/status-badge.md",
-      "order": 13
+      "order": 15
     },
     {
       "slug": "parts/trend-indicator",
@@ -640,7 +660,7 @@
       "title": "TrendIndicator",
       "description": "増減の矢印と変化率。良し悪しは positiveIsGood で決まる。",
       "file": "ja/parts/trend-indicator.md",
-      "order": 14
+      "order": 16
     },
     {
       "slug": "markdown/markdown-renderer",
@@ -1242,6 +1262,16 @@
       "file": "en/parts/page-shell.md",
       "order": 9
     },
+    {
+      "slug": "parts/placeholder",
+      "lang": "en",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "Placeholder",
+      "description": "An inline marker for sample, not-yet-real data.",
+      "file": "en/parts/placeholder.md",
+      "order": 10
+    },
     {
       "slug": "parts/searchable-select",
       "lang": "en",
@@ -1250,7 +1280,7 @@
       "title": "SearchableSelect",
       "description": "Single choice with search, for long option lists.",
       "file": "en/parts/searchable-select.md",
-      "order": 10
+      "order": 11
     },
     {
       "slug": "parts/section-header",
@@ -1260,7 +1290,7 @@
       "title": "SectionHeader",
       "description": "A section heading with its actions.",
       "file": "en/parts/section-header.md",
-      "order": 11
+      "order": 12
     },
     {
       "slug": "parts/segmented-control",
@@ -1270,7 +1300,17 @@
       "title": "SegmentedControl",
       "description": "Single-choice segments — it hides ToggleGroup's array.",
       "file": "en/parts/segmented-control.md",
-      "order": 12
+      "order": 13
+    },
+    {
+      "slug": "parts/sparkline",
+      "lang": "en",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "Sparkline",
+      "description": "An inline trend chart for table cells and KPI tiles.",
+      "file": "en/parts/sparkline.md",
+      "order": 14
     },
     {
       "slug": "parts/status-badge",
@@ -1280,7 +1320,7 @@
       "title": "StatusBadge",
       "description": "A dot-and-label status badge, coloured by name.",
       "file": "en/parts/status-badge.md",
-      "order": 13
+      "order": 15
     },
     {
       "slug": "parts/trend-indicator",
@@ -1290,7 +1330,7 @@
       "title": "TrendIndicator",
       "description": "An arrow and a percentage; positiveIsGood decides the colour.",
       "file": "en/parts/trend-indicator.md",
-      "order": 14
+      "order": 16
     },
     {
       "slug": "markdown/markdown-renderer",

package/docs/ja/components.md

@@ -124,6 +124,7 @@ shadcn/ui のプリミティブです。名前も props も shadcn/ui のもの
 | [`DataTable`](parts/data-table) | 並べ替え・検索・ページング・選択を備えた表 |
 | [`EChart`](parts/echart) | Apache ECharts のラッパー |
 | [`FunnelSteps`](parts/funnel-steps) | ファネルの棒表示 |
+| [`Sparkline`](parts/sparkline) | セルやタイルに置くインラインの推移グラフ |
 | [`FilterBar`](parts/filter-bar) | フィルタ一式を 1 つの値で扱う行 |
 | [`DateRangePicker`](parts/date-range-picker) | プリセット付きの期間選択 |
 | [`SegmentedControl`](parts/segmented-control) | 単一選択のセグメント |
@@ -132,6 +133,7 @@ shadcn/ui のプリミティブです。名前も props も shadcn/ui のもの
 | [`MetricValue`](parts/metric-value) | KPI の数値と単位 |
 | [`TrendIndicator`](parts/trend-indicator) | 増減の矢印と変化率 |
 | [`StatusBadge`](parts/status-badge) | ドット付きステータスバッジ |
+| [`Placeholder`](parts/placeholder) | 仮データであることを示すインラインの目印 |
 
 ## `@squadbase/vantage/markdown`
 

package/docs/ja/data-fetching.md

@@ -4,6 +4,7 @@
 
 Vantage はサーバー状態のために **管理された TanStack Query** を同梱しています。`QueryClient` の
 セットアップは不要で、`@squadbase/vantage/query` から `useQuery` などを import するだけです。
+自分の `server/api` を呼ぶなら、後述の [`useApiQuery`](#自分の-api-を呼ぶ--useapiquery) が近道です。
 
 ```tsx
 import { useQuery } from "@squadbase/vantage/query";
@@ -39,6 +40,12 @@ Vantage が用意する `QueryClient` は 1 つだけで、次のデフォルト
 | `staleTime` | 30 秒 |
 | `retry` | 1 |
 | `refetchOnWindowFocus` | `false` |
+| `networkMode` | `"always"`（queries / mutations とも） |
+
+`networkMode: "always"` は、ブラウザのオフライン判定を無視して常にリクエストとリトライを行う
+設定です。既定の `"online"` だと、オフラインと判定された瞬間に失敗したクエリが *paused* に
+なり、エラーにならないまま読み込み表示が残り続けます。ダッシュボードは自分のオリジン（または
+設定した API ベース）と話すので、その判定は当てになりません。
 
 カスタマイズは**クエリごとのオプションで上書き**します。`QueryClient` 丸ごとの差し替えは、
 管理されたスタックを保つため意図的に公開していません。
@@ -57,21 +64,78 @@ useQuery({
 > `@tanstack/react-query` を直接 import しないでください。`@squadbase/vantage/query` の
 > キュレートされた再エクスポートを使うことで、Vantage が下層ライブラリを安全に進化させられます。
 
-## API との組み合わせ
+## 自分の API を呼ぶ — useApiQuery
+
+`server/api` のルートを呼ぶときは `useApiQuery` を使います。`useQuery` に、毎回書いていた
+定型（ベース URL の解決・JSON パース・非 2xx のエラー化・クエリキー）を足したものです。
+
+```tsx
+import { useApiQuery } from "@squadbase/vantage/query";
+
+interface Monthly {
+  monthly: { month: string; revenue: number }[];
+}
+
+export default function MonthlyAnalysis() {
+  const { data, isPending, error } = useApiQuery<Monthly>("/api/monthly-analysis");
+
+  if (isPending) return <p>読み込み中…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <Chart data={data.monthly} />;
+}
+```
+
+クエリ文字列は `search` で渡します。`undefined` の項目は落ちるので、未設定のフィルタは
+URL にもクエリキーにも現れません。
+
+```tsx
+const query = useApiQuery<Row[]>("/api/customers", {
+  search: { segment, from: range.from, to: range.to },
+  enabled: Boolean(segment), // useQuery のオプションはそのまま使える
+});
+```
+
+クエリキーは既定で `["api", <クエリ文字列込みの URL>]` です。したがって `search` が変われば
+再取得され、`invalidateQueries({ queryKey: ["api"] })` で API 由来のキャッシュを一括で捨てられます。
+
+### エラーは ApiError
+
+非 2xx のレスポンスは `ApiError` として throw されます。`message` は API が
+[`HttpError`](api-and-server) で投げたメッセージ、それ以外は汎用のステータス文言です。
+
+| プロパティ | 内容 |
+|---|---|
+| `message` | サーバーが `HttpError` で明示したメッセージ |
+| `status` | HTTP ステータス |
+| `body` | パース済みのレスポンスボディ |
+| `requestId` | `x-vantage-request-id`。開発ターミナルのログと突き合わせられる |
+
+### 書き込みは useApiMutation
+
+変数はそのまま JSON ボディとして送られます。パスは関数でも渡せます。
+
+```tsx
+import { useApiMutation, useQueryClient } from "@squadbase/vantage/query";
+
+const queryClient = useQueryClient();
+const save = useApiMutation<Customer, { id: string; name: string }>(
+  (vars) => `/api/customers/${vars.id}`,
+  {
+    method: "PUT",
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["api"] }),
+  },
+);
+
+save.mutate({ id: "1", name: "Northwind" });
+```
 
-`queryFn` の中で `/api/*` を呼べば、[オプションのサーバー](api-and-server)と自然につながります。
-`server/` を持たないクライアントのみのアプリでも、外部 API を `fetch` して同じように扱えます。
+hook が使えない場所（イベントハンドラなど）では `apiJson(path, init)` を直接呼べます。
+生の `Response` が欲しい場合は `apiFetch` です。
 
 > [!TIP]
-> 組み込みの `/api` を呼ぶときは、`@squadbase/vantage/query` の `apiFetch` を使うと、ベースURLを
-> env で切り替えられます(フロントとサーバーを別オリジンにデプロイする場合)。詳しくは
-> [ビルドとデプロイ](build-and-deploy)を参照してください。
->
-> ```tsx
-> import { apiFetch } from "@squadbase/vantage/query";
->
-> queryFn: () => apiFetch("/api/customers").then((r) => r.json());
-> ```
+> 外部 API を呼ぶときは `useQuery` + `fetch` をそのまま使います。`useApiQuery` は
+> `apiFetch` 経由なので、[`PUBLIC_API_BASE_URL`](build-and-deploy) を設定すれば
+> フロントとサーバーを別オリジンにデプロイしても、ページのコードは変わりません。
 
 ## 次に読む
 

package/docs/ja/pages-and-metadata.md

@@ -22,7 +22,8 @@ default export が無いページは `vantage check` が `MISSING_DEFAULT_EXPORT
 import { definePage } from "@squadbase/vantage";
 
 export const page = definePage({
-  title: "月次分析",
+  title: "月次分析 · Acme Analytics",
+  navLabel: "月次分析",
   description: "売上と主要指標の月次サマリー",
 });
 
@@ -33,8 +34,10 @@ export default function MonthlyAnalysis() {
 
 - `title` は `document.title` を駆動します（末端のルートマッチのタイトルが使われ、無ければ
   ドキュメント初期の `<title>` にフォールバック）。
-- `title`/`description` は **生成時に静的に読まれます**。Vantage はページを実行して読むのではなく、
-  ソースを静的に解析します。したがって値は**リテラル**にしてください。
+- `navLabel` は [`useRoutes()`](routing#ルート一覧からナビを作る) で組むナビの表示名です。
+  省略すると `title` が使われます。`title` にサイト名を含めるときに分けます。
+- `title`/`description`/`navLabel` は **生成時に静的に読まれます**。Vantage はページを実行して
+  読むのではなく、ソースを静的に解析します。したがって値は**リテラル**にしてください。
 
 > [!WARNING]
 > `export const page = definePage({...})` の**エクスポート名は `page` 固定**です。別名にすると

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

@@ -85,6 +85,86 @@ export default function RootLayout() {
 
 `_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` ファイルを追加・削除すると、開発サーバーがルートを再生成して

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",