@squadbase/vantage 0.1.0 → 0.2.0

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

@@ -33,10 +33,6 @@ server/       API（存在するとサーバーが有効になる）
 public/       静的アセット
 ```
 
-> [!NOTE]
-> ファイル間の import は **ランタイムの `.js` 指定子**を使います（例: `./components/revenue-chart.js`）。
-> ESM の Node 解決に必要です。
-
 ## 動的パラメータの 3 つの綴り
 
 同じパラメータが、場所によって 3 つの綴りで現れます。**必ず一致させます。**
@@ -85,6 +81,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.2.0",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",

package/skills/vantage-add-feature/SKILL.md

@@ -43,7 +43,9 @@ vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerI
 チェックリスト:
 
 1. **デフォルトエクスポートは必須**(無いと `MISSING_DEFAULT_EXPORT` エラー)。
-2. `definePage({ title })` の値は**リテラル**で書く(ビルド時に静的抽出されるため)。
+2. `definePage({ title })` の値は**リテラル**で書く(ビルド時に静的抽出されるため)。ナビに出す
+   短い名前が要るなら `navLabel` も足す(`useRoutes()` が読む。既定は `title`)。
+   `_layout.tsx` のナビを `useRoutes()` で組んでいれば、ページを足すだけでリンクも増える。
 3. 動的ページなら **3つの綴りを同期**:
    - ファイル `foo/[id].tsx`
    - 表示ルート `/foo/:id`
@@ -88,20 +90,21 @@ export async function GET({ request, params }: ApiContext) {
 6. サーバー専用の共有コードは `server/utils.ts` 等に置く。**クライアントから `server/` を
    import しない**(`CLIENT_IMPORTS_SERVER` エラー。共有は `lib/` に置く)。
 
-クライアント側から叩くときは `apiFetch`:
+クライアント側から叩くときは `useApiQuery`(ベース URL 解決・JSON パース・非 2xx の `ApiError`
+化・クエリキー `["api", url]` が入っている):
 
 ```tsx
-import { apiFetch, useQuery } from "@squadbase/vantage/query"
-const q = useQuery({
-  queryKey: ["customer", id],
-  queryFn: async () => {
-    const res = await apiFetch(`/api/customers/${id}`)
-    if (!res.ok) throw new Error("not found")
-    return res.json()
-  },
-})
+import { useApiQuery } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${id}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+
+// クエリ文字列は search で(undefined の項目は落ちる)
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
 ```
 
+書き込みは `useApiMutation(path, { method: "POST" })` — 変数がそのまま JSON ボディになる。
+
 ## UI コンポーネント / ブロックを追加する
 
 ```bash
@@ -118,7 +121,6 @@ vantage add block sales-overview # → components/blocks/sales-overview.tsx
   import { Button, Loading, ErrorState } from "@squadbase/vantage/ui"
   import { DashboardCardPreset, DataTablePreset, EChart } from "@squadbase/vantage/components"
   ```
-- コピーしたソースの相対 import は**ランタイムの `.js` 指定子**で書く(`./cn.js` など)。
 - **props は `vantage docs <name>` で確認してから書く**(`vantage docs button`・
   `vantage docs parts/data-table`。名前が分からなければ `vantage search <やりたいこと>` で
   探してから `vantage docs` に渡す)。

package/skills/vantage-app/SKILL.md

@@ -22,16 +22,14 @@ Tailwind・UI キット・開発サーバー・API サーバー・ビルドは
   `echarts`・`hono`・`vite`・`tailwindcss` を直接 import しない。`lucide-react` のアイコンだけは
   直接 import してよい。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。
-- **モジュール間 import はランタイムの `.js` 指定子を使う**(例: `./components/revenue-chart.js`)。
-  ソースは `.tsx`/`.ts` でも、相対 import の拡張子は `.js` と書く。ESM の Node 解決に必要。
 
 ## サブパスの地図
 
 | import 元 | 提供するもの |
 | --- | --- |
 | `@squadbase/vantage` | `definePage`(ページ設定) |
-| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound` |
-| `@squadbase/vantage/query` | `useQuery`・`useMutation`・`apiFetch`・`apiUrl` ほか TanStack Query の再エクスポート |
+| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
+| `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
 | `@squadbase/vantage/ui` | shadcn/ui 系プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
 | `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するため専用サブパス) |
@@ -62,7 +60,7 @@ Tailwind・UI キット・開発サーバー・API サーバー・ビルドは
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.1.0",
+    "@squadbase/vantage": "^0.2.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -114,27 +112,39 @@ pnpm routes   # ページ/API の URL マップ
 ```tsx
 import { definePage } from "@squadbase/vantage"
 
-export const page = definePage({ title: "Monthly Analysis" })
+// navLabel は useRoutes() で組むナビの表示名(省略時は title)
+export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
 
 export default function MonthlyAnalysis() {
   return <main className="p-6">…</main>
 }
 ```
 
-> `page` エクスポートはランタイムでは読まれない。title/description はビルド時に**静的抽出**される
-> ので、値はリテラルで書く(変数や関数呼び出しにしない)。
+> `page` エクスポートはランタイムでは読まれない。title/description/navLabel はビルド時に
+> **静的抽出**されるので、値はリテラルで書く(変数や関数呼び出しにしない)。
 
 ### ネストレイアウトと特殊ページ
 
-`_layout.tsx` は `Outlet` で子ルートを描く:
+`_layout.tsx` は `Outlet` で子ルートを描く。ナビは `useRoutes()` から組むと、ページファイルを
+足すだけでリンクが増える(手で持つリンク配列を作らない):
 
 ```tsx
-import { Outlet } from "@squadbase/vantage/router"
+import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
 
 export default function RootLayout() {
+  // 動的ルート(/sales/:id)は URL が定まらないので外す。label は navLabel → title → path
+  const routes = useRoutes().filter((r) => !r.dynamic)
+  const current = useCurrentRoute()
+
   return (
     <div className="min-h-screen">
-      <header>…</header>
+      <header>
+        {routes.map((r) => (
+          <Link key={r.path} to={r.to} activeClassName="font-semibold">
+            {r.label}
+          </Link>
+        ))}
+      </header>
       <Outlet />
     </div>
   )
@@ -182,8 +192,25 @@ if (q.isPending) return <Loading />
 if (q.isError) return <ErrorState message={(q.error as Error).message} />
 ```
 
-`QueryClient` は Vantage が1つだけ管理する(staleTime 30s・retry 1・refetchOnWindowFocus false)。
-挙動を変えたいときはクエリ側のオプションで上書きする(クライアントごと差し替える口は無い)。
+`QueryClient` は Vantage が1つだけ管理する(staleTime 30s・retry 1・refetchOnWindowFocus false・
+networkMode "always" = ブラウザのオフライン判定に従わず必ず投げる)。挙動を変えたいときは
+クエリ側のオプションで上書きする(クライアントごと差し替える口は無い)。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→ Step 4)。
+
+### フィルタ状態は URL に置く
+
+ダッシュボードの絞り込みは `useState` ではなく `useSearchParam` にする。リロードで消えず、
+URL をそのまま共有できる:
+
+```tsx
+import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
+
+const [region, setRegion] = useSearchParam("region", "all")              // 値は常に string
+const [segments, setSegments] = useSearchState<string[]>("segments", []) // 配列・オブジェクト
+```
+
+デフォルト値(または `null`)を書き込むとキーは URL から消える。履歴は既定で `replace`
+(`{ replace: false }` で push)。動的ルートの上でもパスパラメータは保たれる。
 
 ## Step 4 — fullstack へ拡張(server/api を足す)
 
@@ -208,21 +235,25 @@ export async function GET(_ctx: ApiContext) {
   ログに記録され汎用の 500 になる。
 - **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
 
-クライアント側からは `apiFetch` で同一オリジンの `/api/*` を叩く:
+クライアント側からは `useApiQuery` で `/api/*` を叩く(ベース URL 解決・JSON パース・非 2xx の
+`ApiError` 化・クエリキー `["api", url]` が入っている):
 
 ```tsx
-import { apiFetch, useQuery } from "@squadbase/vantage/query"
-
-const q = useQuery({
-  queryKey: ["customer", customerId],
-  queryFn: async () => {
-    const res = await apiFetch(`/api/customers/${customerId}`)
-    if (!res.ok) throw new Error(`Customer ${customerId} not found`)
-    return res.json()
-  },
-})
+import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージが入る
+
+// クエリ文字列は search で渡す(undefined の項目は落ちる → URL にもキーにも出ない)
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+
+// 書き込み。変数がそのまま JSON ボディになる
+const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
 ```
 
+`ApiError` は `message`・`status`・`body`・`requestId`(dev ターミナルのログと突き合わせられる)を
+持つ。hook が使えない場所では `apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。
+
 ### server/ とクライアントの境界(絶対に守る)
 
 - **クライアントコードは `server/` を import してはならない。** 共有したいコードは `lib/` に置く。

package/skills/vantage-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-pitfalls
-description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、SelectValue は value を描く、クライアントから server/ を import しない、EChart はテーマ非追従、相対 import は .js 指定子、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、SelectValue は value を描く、クライアントから server/ を import しない、EChart はテーマ非追従、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
 ---
 
 # Vantage アプリの落とし穴リファレンス
@@ -52,16 +52,6 @@ Vantage の UI キットは shadcn/ui の **Base UI バリアント**。Radix
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。
 - `VITE_` 系の公開 API は無い。サーバーのシークレットは `ctx.env` で読む。
 
-## import:相対 import はランタイムの `.js` 指定子で書く
-
-ソースが `.tsx`/`.ts` でも、**モジュール間の相対 import は `.js`** と書く(ESM の Node 解決に必要):
-
-```tsx
-import { RevenueChart } from "./components/revenue-chart.js"  // ← .tsx ではなく .js
-```
-
-`@squadbase/vantage` のサブパス import はこの限りではない(`@squadbase/vantage/ui` 等)。
-
 ## ルーティング:動的パラメータは「3つの綴り」を同期させる
 
 ズレると静かにマッチしなくなる:
@@ -72,10 +62,34 @@ import { RevenueChart } from "./components/revenue-chart.js"  // ← .tsx では
 
 ## ページ:`definePage` の値はリテラルで書く
 
-title/description は**ビルド時に静的抽出**される。変数・関数呼び出し・テンプレート補間を使うと
-抽出できない。`export const page = definePage({ title: "…" })` の右辺はリテラルにする。
+title/description/navLabel は**ビルド時に静的抽出**される。変数・関数呼び出し・テンプレート補間を
+使うと抽出できない。`export const page = definePage({ title: "…" })` の右辺はリテラルにする。
 なお `page` エクスポートはランタイムでは読まれない(抽出専用)。
 
+## ナビ:`useRoutes()` は動的ルートも返す
+
+`/sales/:customerId` のような動的ルートは URL が 1 つに定まらない。ナビに出すなら
+`useRoutes().filter((r) => !r.dynamic)` で外す。リンク先は `r.path`(`:id` 形式)ではなく
+**`r.to`**(`$id` 形式)を `Link` に渡す。表示名は `r.label`(`navLabel` → `title` → `path` の順)。
+
+`useCurrentRoute()` は 404 のとき `undefined` を返す。動的ルートを開いているときに親を
+アクティブにしたいなら `current?.path.startsWith("/sales")` のように前方一致で判定する。
+
+## URL 状態:`useSearchParam` の値は常に string、既定値はURLから消える
+
+- TanStack は `?year=2024` を数値としてパースするが、`useSearchParam` は必ず `string` に戻す
+  (数値が欲しければ自分で `Number(...)`)。配列やオブジェクトは `useSearchState` を使う。
+- **デフォルト値または `null` を書き込むとキーが URL から消える**。「明示的に既定値を選んだ」
+  状態を URL に残すことはできない。
+- 履歴は既定で `replace`。戻るボタンで1手ずつ戻したいときだけ `{ replace: false }`。
+
+## API 呼び出し:`useApiQuery` のエラーは `ApiError`
+
+`(q.error as Error)` のキャストは要らない。`q.error` は `ApiError | null` で、`message` には
+サーバーが `HttpError` で明示したメッセージが入る(それ以外は汎用のステータス文言)。
+`status`・`body`・`requestId` も持つ。クエリキーは `["api", url]` なので、
+`invalidateQueries({ queryKey: ["api"] })` で API 由来のキャッシュを一括で捨てられる。
+
 ## API:見せたいエラーは `HttpError` を throw する
 
 ```ts

package/templates/AGENTS.md

@@ -10,7 +10,7 @@
 > アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています
-> (`vantage add skill --all` で `.claude/skills/` に配置)。このファイルは「地図」、Skill は
+> (`vantage add skill --all --dir .claude/skills` で配置)。このファイルは「地図」、Skill は
 > 「手順書」という役割分担です。詰まったら `vantage-app` / `vantage-add-feature` /
 > `vantage-pitfalls` を参照してください。
 
@@ -29,9 +29,6 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **import は必ず `@squadbase/vantage` のサブパス経由。** `@tanstack/*`・`@base-ui/react`・
   `echarts`・`hono`・`vite`・`tailwindcss` を直接 import しない。`lucide-react` のアイコンだけは
   直接 import してよい。
-- **モジュール間の相対 import はランタイムの `.js` 指定子で書く**(例:
-  `./components/revenue-chart.js`)。ソースが `.tsx`/`.ts` でも拡張子は `.js` と書く。
-  ESM の Node 解決に必要。`@squadbase/vantage` のサブパスはこの限りではない。
 - **クライアントコードは `server/` を import してはならない。** 違反は `CLIENT_IMPORTS_SERVER`
   エラー(静的にもビルド時にも弾かれる)。共有したいコードは `lib/` に置く。
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
@@ -39,16 +36,17 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
   `ApiContext.env`(server/ 内)にだけ届く。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
-- **`definePage` の値はリテラルで書く。** title/description はビルド時に静的抽出されるため、
-  変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは読まれない。
+- **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
+  ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
+  読まれない。
 
 ## import サブパスの地図
 
 | import 元 | 提供するもの |
 | --- | --- |
 | `@squadbase/vantage` | `definePage`(ページ設定) |
-| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound` |
-| `@squadbase/vantage/query` | `useQuery`・`useMutation`・`apiFetch`・`apiUrl` ほか TanStack Query の再エクスポート |
+| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
+| `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
 | `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
 | `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
@@ -73,7 +71,7 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.1.0",
+    "@squadbase/vantage": "^0.2.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -121,13 +119,50 @@ pnpm routes   # ページ/API の URL マップ
 ```tsx
 import { definePage } from "@squadbase/vantage"
 
-export const page = definePage({ title: "Monthly Analysis" })
+// title は document.title、navLabel は useRoutes() で組むナビの表示名(既定は title)
+export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
 
 export default function MonthlyAnalysis() {
   return <main className="p-6">…</main>
 }
 ```
 
+### ナビはルート一覧から組む
+
+`useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
+`useCurrentRoute()` は現在のルート(404 なら `undefined`)。
+
+```tsx
+import { Link, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
+
+// 動的ルートは URL が定まらないので外す。label は navLabel → title → path の順
+const routes = useRoutes().filter((r) => !r.dynamic)
+const current = useCurrentRoute()
+
+routes.map((r) => (
+  <Link key={r.path} to={r.to} activeClassName="font-semibold">
+    {r.label}
+  </Link>
+))
+```
+
+`RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
+`title`・`description`・`navLabel`。
+
+### フィルタ状態は URL に置く
+
+リロードで消えず、URL をそのまま共有できる。`useState` と同じ形。
+
+```tsx
+import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
+
+const [region, setRegion] = useSearchParam("region", "all")   // 常に string
+const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON になる値
+```
+
+デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
+(`{ replace: false }` で push)。
+
 ### 動的パラメータの「3 つの綴り」を同期させる
 
 崩すと静かにマッチしなくなる不変条件:
@@ -159,7 +194,10 @@ if (q.isError) return <ErrorState message={(q.error as Error).message} />
 ```
 
 `QueryClient` は Vantage が 1 つだけ管理する(staleTime 30s・retry 1・
-refetchOnWindowFocus false)。挙動を変えたいときはクエリ側のオプションで上書きする。
+refetchOnWindowFocus false・networkMode "always")。挙動を変えたいときはクエリ側のオプションで
+上書きする。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→「API を足して fullstack に
+する」)。
 
 ## API を足して fullstack にする
 
@@ -186,21 +224,25 @@ export async function GET({ params, env }: ApiContext) {
   ログに記録され汎用の 500 に丸められる。
 - **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
 
-クライアント側からは `apiFetch` で同一オリジンの `/api/*` を叩く:
+クライアント側からは `useApiQuery` で `/api/*` を叩く。ベース URL の解決・JSON パース・
+非 2xx の `ApiError` 化・クエリキー(`["api", url]`)が入っている:
 
 ```tsx
-import { apiFetch, useQuery } from "@squadbase/vantage/query"
-
-const q = useQuery({
-  queryKey: ["customer", customerId],
-  queryFn: async () => {
-    const res = await apiFetch(`/api/customers/${customerId}`)
-    if (!res.ok) throw new Error(`Customer ${customerId} not found`)
-    return res.json()
-  },
-})
+import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+
+// クエリ文字列は search で。undefined の項目は落ちる
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+
+// 書き込み。変数がそのまま JSON ボディになる
+const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
 ```
 
+`ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
+`apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。
+
 ## 環境変数
 
 - **クライアントで読めるのは `import.meta.env.PUBLIC_*` と `MODE`/`DEV`/`PROD`/`SSR`/`BASE_URL`
@@ -260,7 +302,7 @@ pnpm preview   # 本番ビルドをローカル実行
 
 ## さらに詳しく(同梱 Skill)
 
-`vantage add skill --all` で `.claude/skills/` に配置される:
+`vantage add skill --all --dir .claude/skills` で配置される(`--dir` を省くとルート直下):
 
 - **`vantage-app`** — アプリを一から作る / SPA を fullstack に広げる手順
 - **`vantage-add-feature`** — 既存アプリに page / api / ui / block を 1 つ足す定型

package/dist/chunk-ATYZ45XL.js

@@ -1,19 +0,0 @@
-import { QueryClient } from '@tanstack/react-query';
-
-// @squadbase/vantage — generated build. Do not edit.
-
-function createQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        staleTime: 3e4,
-        retry: 1,
-        refetchOnWindowFocus: false
-      }
-    }
-  });
-}
-
-export { createQueryClient };
-//# sourceMappingURL=chunk-ATYZ45XL.js.map
-//# sourceMappingURL=chunk-ATYZ45XL.js.map

package/dist/chunk-ATYZ45XL.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/query/client.ts"],"names":[],"mappings":";;;;AAOO,SAAS,iBAAA,GAAiC;AAC/C,EAAA,OAAO,IAAI,WAAA,CAAY;AAAA,IACrB,cAAA,EAAgB;AAAA,MACd,OAAA,EAAS;AAAA,QACP,SAAA,EAAW,GAAA;AAAA,QACX,KAAA,EAAO,CAAA;AAAA,QACP,oBAAA,EAAsB;AAAA;AACxB;AACF,GACD,CAAA;AACH","file":"chunk-ATYZ45XL.js","sourcesContent":["import { QueryClient } from \"@tanstack/react-query\"\n\n/**\n * Create the QueryClient with Vantage defaults. Individual queries may override\n * these, but replacing the QueryClient wholesale is intentionally not exposed —\n * Squadbase relies on a single managed client for auth, logging and telemetry.\n */\nexport function createQueryClient(): QueryClient {\n  return new QueryClient({\n    defaultOptions: {\n      queries: {\n        staleTime: 30_000,\n        retry: 1,\n        refetchOnWindowFocus: false,\n      },\n    },\n  })\n}\n"]}