@squadbase/vantage 0.1.0 → 0.2.0

package/docs/en/routing.md

@@ -33,10 +33,6 @@ server/       API (its presence enables the server)
 public/       Static assets
 ```
 
-> [!NOTE]
-> Imports between files use **runtime `.js` specifiers** (e.g. `./components/revenue-chart.js`) —
-> required for ESM Node resolution.
-
 ## The three spellings of a dynamic param
 
 The same param appears in three spellings depending on where it is. **They must match.**
@@ -85,6 +81,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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "generatedFrom": "docs/content",
   "docs": [
     {
@@ -108,10 +108,21 @@
       "section": "guide",
       "sectionTitle": "ガイド",
       "title": "エージェントと Skills",
-      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリの .claude/skills/ に配置し、エージェントに手順を伴うワークフローを教える。",
+      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。",
       "file": "ja/agent-skills.md",
       "order": 9
     },
+    {
+      "slug": "changelog",
+      "lang": "ja",
+      "section": "guide",
+      "sectionTitle": "ガイド",
+      "title": "変更履歴",
+      "description": "Vantage のリリースごとの変更点。新しいものが上。まだプロトタイプ(0.x)のため、リリース間で API が変わることがあります。",
+      "file": "ja/changelog.md",
+      "order": 10,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "ja",
@@ -592,6 +603,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 +621,7 @@
       "title": "SearchableSelect",
       "description": "検索できる単一選択。候補が多いときに。",
       "file": "ja/parts/searchable-select.md",
-      "order": 10
+      "order": 11
     },
     {
       "slug": "parts/section-header",
@@ -610,7 +631,7 @@
       "title": "SectionHeader",
       "description": "セクションの見出しとアクション。",
       "file": "ja/parts/section-header.md",
-      "order": 11
+      "order": 12
     },
     {
       "slug": "parts/segmented-control",
@@ -620,7 +641,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 +661,7 @@
       "title": "StatusBadge",
       "description": "ドット付きのステータスバッジ。色は名前で決まる。",
       "file": "ja/parts/status-badge.md",
-      "order": 13
+      "order": 15
     },
     {
       "slug": "parts/trend-indicator",
@@ -640,7 +671,7 @@
       "title": "TrendIndicator",
       "description": "増減の矢印と変化率。良し悪しは positiveIsGood で決まる。",
       "file": "ja/parts/trend-indicator.md",
-      "order": 14
+      "order": 16
     },
     {
       "slug": "markdown/markdown-renderer",
@@ -758,10 +789,21 @@
       "section": "guide",
       "sectionTitle": "Guide",
       "title": "Agents and Skills",
-      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app's .claude/skills/ with vantage add skill to teach agents step-by-step workflows.",
+      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (the project root by default, or anywhere via --dir, e.g. .claude/skills) to teach agents step-by-step workflows.",
       "file": "en/agent-skills.md",
       "order": 9
     },
+    {
+      "slug": "changelog",
+      "lang": "en",
+      "section": "guide",
+      "sectionTitle": "Guide",
+      "title": "Changelog",
+      "description": "What changed in each Vantage release, newest first. Still a prototype (0.x), so APIs may change between releases.",
+      "file": "en/changelog.md",
+      "order": 10,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "en",
@@ -1242,6 +1284,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 +1302,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 +1312,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 +1322,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 +1342,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 +1352,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/agent-skills.md

@@ -1,6 +1,6 @@
 # エージェントと Skills
 
-> Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリの .claude/skills/ に配置し、エージェントに手順を伴うワークフローを教える。
+> Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。
 
 Vantage は **Claude Code の Agent Skills** を同梱しています。Skill は「手順を伴うワークフロー」を、
 エージェントが必要なときだけ呼び出せる形にしたものです。UI キットや CLI の使い方といった
@@ -18,16 +18,18 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 
 ## 配置する
 
-Skill のソースは `@squadbase/vantage` パッケージに同梱されています。`vantage add skill` で、
-対象アプリの `.claude/skills/` にコピーします。
+Skill のソースは `@squadbase/vantage` パッケージに同梱されています。`vantage add skill` で
+対象アプリにコピーします。配置先は既定で**プロジェクトルート直下**で、`--dir` で変えられます。
 
 ```bash
-vantage add skill --all          # 同梱スキルをすべて配置
-vantage add skill vantage-app    # 名前を指定して1つだけ配置
-vantage add skill vantage-app --force   # 既存を上書き
+vantage add skill --all                       # 同梱スキルをすべて、ルート直下に配置
+vantage add skill vantage-app                 # 名前を指定して1つだけ配置
+vantage add skill --all --dir .claude/skills  # Claude Code が読む場所に配置
+vantage add skill vantage-app --force         # 既存を上書き
 ```
 
-配置後のレイアウト:
+`--dir` のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に
+自動認識させるなら `.claude/skills/` に置きます:
 
 ```text
 your-app/
@@ -41,7 +43,8 @@ your-app/
 ```
 
 `.claude/skills/` は Claude Code が自動で認識します。エージェントはタスクに応じて、対応する
-Skill の手順を読み込んで実行します。
+Skill の手順を読み込んで実行します。他のエージェントに読ませる場合は、そのツールが期待する
+ディレクトリを `--dir` に渡してください。
 
 > [!NOTE]
 > `.claude/` はツール用の設定であり、アプリのコードではありません。`vantage check` の静的診断は
@@ -51,7 +54,8 @@ Skill の手順を読み込んで実行します。
 
 - **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
   配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
-  コピーを更新したいときは `vantage add skill --all --force` を実行します。
+  コピーを更新したいときは、配置したときと同じ `--dir` を付けて
+  `vantage add skill --all --force` を実行します。
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 

package/docs/ja/changelog.md

@@ -0,0 +1,89 @@
+# 変更履歴
+
+> Vantage のリリースごとの変更点。新しいものが上。まだプロトタイプ(0.x)のため、リリース間で API が変わることがあります。
+
+Vantage のリリースごとの変更点です。新しいものが上に来ます。
+
+> [!NOTE]
+> まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
+> ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
+
+## v0.2.0
+
+`vantage add skill` の配置先を選べるようにし、相対 import の `.js` 指定子の規約を廃止しました。
+後方互換でない変更(既定の配置先)を含むため、0.x の方針に従って minor を上げています。
+
+依存を `"@squadbase/vantage": "^0.1.0"` と書いているアプリには 0.2.0 は入りません。
+`^0.2.0` に上げてください。
+
+> [!WARNING]
+> **`vantage add skill` の既定の配置先が変わりました。** これまで常に `.claude/skills/` へ
+> 出していましたが、既定は**プロジェクトルート直下**になります。これまでと同じ場所に置くには
+> `--dir .claude/skills` を明示してください。配置済みのコピーはそのまま残るので、更新する
+> ときだけ `--dir` を付け直す形になります。
+
+### 変更
+
+- **`vantage add skill --dir <path>`** ― 配置先をコマンドで指定できるようになりました。
+  パスはプロジェクトルート(`--root` を尊重)からの相対で解決され、絶対パスも渡せます。
+  Claude Code に自動認識させたい場合は `--dir .claude/skills`、他のエージェント向けには
+  そのツールが期待するディレクトリを指定します(→ [エージェントと Skills](agent-skills))。
+- **相対 import の `.js` 指定子の規約を廃止** ― `./components/revenue-chart.js` のように
+  拡張子を書く必要はなくなりました(`./components/revenue-chart` で構いません)。Vantage の
+  コードは常に Vite / tsup を通り、TypeScript も `moduleResolution: "Bundler"` で解決する
+  ため、Node が生の指定子を読む経路がそもそもありませんでした。**既存の `.js` 付きの
+  import はそのまま動きます** ― 書き換えは不要です。
+
+## v0.1.1
+
+一覧・URL 状態・API 呼び出しの hook を追加し、開発時の 2 つの不具合を修正しました。
+すべて後方互換です。
+
+### 追加
+
+- **ルーティングの hook** ― `useRoutes()` / `useCurrentRoute()` を
+  [`@squadbase/vantage/router`](routing) に追加。ファイルベースルーティングの一覧を
+  そのまま受け取り、ナビゲーションを手で二重管理せずに組めます。
+- **URL 同期の状態** ― `useSearchParam`(常に文字列。既定値/`null` を書くとキーを消す)と、
+  JSON 値と関数更新に対応した `useSearchState<T>` を追加。フィルタやタブの状態を URL に置けます。
+- **API 呼び出しの hook** ― `useApiQuery` / `useApiMutation` を
+  [`@squadbase/vantage/query`](data-fetching) に追加。`server/api` を JSON で呼び、
+  エラーは `HttpError` → `ApiError`(`status` / `body` / `requestId`)に正規化されます。
+- **`definePage` の `navLabel`** ― ナビゲーションに出す表示名を、ページのタイトルと
+  独立して指定できるフィールドを追加(→ [ページとメタデータ](pages-and-metadata))。
+
+### 修正
+
+- **dev の SPA フォールバック** ― `/sales` のような URL に直接アクセスすると、Vite が
+  `No matching HTML proxy module found` のエラーオーバーレイを出していた問題を修正
+  (ページ自体は描画されていました)。注入スクリプトの id をシェル文書の URL から
+  導くようにしました。
+- **クエリが `paused` のまま止まる** ― ブラウザのオフライン判定が誤って offline を返すと、
+  失敗したクエリがエラーにならず停止し、ページが読み込み表示から戻らないことがありました。
+  管理された `QueryClient` の `networkMode` を `"always"` にして解消(自オリジンの API を
+  叩くダッシュボードでは、この判定に意味がありません)。
+
+## v0.1.0
+
+最初のプロトタイプリリース。設定ファイル不要(config-free)な React ダッシュボード
+フレームワークの土台一式です。
+
+### 追加
+
+- **config-free な土台** ― Vite 8 の上に構築。アプリ作者が書くのは `index.tsx` だけで、
+  ルーティング・React・TanStack Query・Tailwind v4・UI キット・開発サーバー・
+  オプションの API サーバー・ビルドはすべて Vantage が所有します。
+- **ファイルベースルーティング** ― `*.tsx`(デフォルトエクスポート)がルートに、
+  `_layout.tsx` がレイアウトに、`_404.tsx` / `_error.tsx` が not-found / error に、
+  `[param].tsx` が動的ルートになります(→ [ルーティング](routing))。
+- **オプションの API サーバー** ― `server/api/**` を足すとバックエンドが有効になり、
+  `dev` と本番ビルドで同一に動きます(→ [API とサーバー](api-and-server))。
+- **UI キットとコンポーネント** ― Tailwind v4、shadcn/ui(Base UI 版)、その上に組んだ
+  ダッシュボード向けの複合コンポーネント(→ [UI とテーマ](ui-and-theming))。
+- **CLI** ― `dev` / `build` / `preview` / `check` / `routes` / `add` / `upgrade`
+  (→ [CLI リファレンス](cli-reference))。
+- **同梱ドキュメントと検索** ― `vantage docs` がパッケージ同梱のガイドとコンポーネント
+  リファレンスをオフラインで表示し、`vantage search` が同じ内容を BM25 で検索します。
+- **エージェント向けの配布物** ― `vantage add agents` が `AGENTS.md` を、
+  `vantage add skill` が Claude Code の Agent Skills をアプリへ配置します
+  (→ [エージェントと Skills](agent-skills))。

package/docs/ja/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
 | `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
 | `vantage routes` | ページ + API の URL マップを表示 |
-| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き） |
+| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は `--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
 | `vantage doctor` | 環境・インストールの健全性を診断 |

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` を検索して潰していけば「まだ繋いでいない箇所」の
+> チェックリストになります。