@squadbase/vantage-template 0.0.2 → 0.1.0-dev.3f759a0

package/base-template/agents/page.md

@@ -0,0 +1,187 @@
+# ダッシュボード / 通常ページ(.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.tsx` の通常ページ
+(ダッシュボード)を書くときに読んでください。前提となる不変条件・ディレクトリ構造は
+`AGENTS.md` を先に読んでいる想定です。
+
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで配色・書体・レイアウトの規則に従う。
+
+## 最小アプリ(2 ファイル)
+
+`package.json` と `index.tsx` の 2 ファイルだけで動く。
+
+`package.json`:
+
+```json
+{
+  "name": "my-dashboard",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vantage dev",
+    "build": "vantage build",
+    "preview": "vantage preview",
+    "check": "vantage check",
+    "routes": "vantage routes"
+  },
+  "dependencies": {
+    "@squadbase/vantage": "^0.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}
+```
+
+`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
+
+```tsx
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  )
+}
+```
+
+```bash
+pnpm install
+pnpm dev      # → http://localhost:5173(HMR)
+pnpm check    # 静的診断(エラーがあれば exit 1)
+pnpm routes   # ページ/API の URL マップ
+```
+
+`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
+`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
+どちらか一方に寄せること(→ `AGENTS.md` の「ディレクトリ構造」)。
+
+## ルーティング規約(ファイル名 → ルート)
+
+ページルート(`src/` があればその中、無ければプロジェクトルート)からの相対パスが、そのまま
+URL になる。各ページは**デフォルトエクスポートの React コンポーネントが必須**(無いと
+`MISSING_DEFAULT_EXPORT`)。以下の「ファイル」列はページルートからの相対パス。
+
+| ファイル | ルート |
+| --- | --- |
+| `index.tsx` | `/` |
+| `monthly-analysis.tsx` | `/monthly-analysis` |
+| `sales/index.tsx` | `/sales` |
+| `sales/[customerId].tsx` | `/sales/:customerId`(動的パラメータ) |
+| `_layout.tsx` | そのディレクトリ配下を包むネストレイアウト(`Outlet` で子を描く) |
+| `_404.tsx` | Not Found ページ |
+| `_error.tsx` | ルートが throw したときのエラーページ |
+| `monthly-report.slide.tsx` | `/monthly-report`(スライドデッキ。詳しくは `agents/slide.md`) |
+| `sales-export.csv` | `/sales-export`(詳しくは `agents/csv.md`) |
+| `data/june.xlsx` | `/data/june`(詳しくは `agents/xlsx.md`) |
+
+`components/`・`hooks/`・`lib/`・`server/`・`public/` はどの階層でもルート走査の対象外
+(ページにならない)。それ以外のディレクトリ名は URL のセグメントになる(→ `AGENTS.md` の
+「ディレクトリ構造」)。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+
+// 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`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"`)。
+後ろの 2 つで、ナビをダッシュボード / スライド / データに分けたりアイコンを変えたりできます。
+
+### フィルタ状態は 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 つの綴り」を同期させる
+
+崩すと静かにマッチしなくなる不変条件:
+
+- ファイル名 `sales/[customerId].tsx`
+- 表示ルート `/sales/:customerId`
+- リンクトークン `to="/sales/$customerId"` + `params={{ customerId }}`
+
+```tsx
+import { Link, useParams } from "@squadbase/vantage/router"
+
+<Link to="/sales/$customerId" params={{ customerId: row.id }}>{row.name}</Link>
+
+// 詳細ページ側で取り出す
+const { customerId } = useParams()
+```
+
+## データ取得(server を持たない fetch)
+
+外部 API を叩くだけなら `server/` は不要。`@squadbase/vantage/query` の `useQuery` を使う:
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query"
+import { Loading, ErrorState } from "@squadbase/vantage/ui"
+
+const q = useQuery({ queryKey: ["stats"], queryFn: () => fetch("/…").then((r) => r.json()) })
+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・networkMode "always")。挙動を変えたいときはクエリ側のオプションで
+上書きする。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→ `agents/api.md`)。
+
+## 組み込み UI / コンポーネントの入口
+
+- **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
+  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+- **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
+  `DataTablePreset`・`EChart` ほか)。
+- **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
+  リファレンスはパッケージに同梱されていて、オフラインでも読める(→ `AGENTS.md` の
+  「ドキュメントを引く」)。**名前が分からないとき**はやりたいことで `vantage search` する
+  (→ 同節)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
+  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
+  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
+
+### ダークモードは opt-in
+
+ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけ。
+**OS / ブラウザの設定(`prefers-color-scheme`)は見ない。** `dark:` ユーティリティも同じ
+スイッチに繋いであるので(`theme.css` の `@custom-variant dark`)、自分でクラスを付けない限り
+アプリは常にライトで描かれる ― `dark:` を書いてもそこだけダークになることはない。
+
+明暗を切り替えたいときは、レイアウトのルート要素などに `.dark` / `data-theme="dark"` を
+自分で付ける。

package/base-template/agents/slide.md

@@ -0,0 +1,41 @@
+# スライド(.slide.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.slide.tsx` で
+スライドデッキを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで「スライド」の節と配色・書体の規則に従う。
+
+## スライドは `.slide.tsx` で書く
+
+`src/monthly-report.slide.tsx` → `/monthly-report`。中身は `<SlideDeck>` を返す普通の React
+コンポーネントで、`definePage` もナビも通常のページと同じように効きます。
+
+```tsx
+import { Slide, SlideDeck } from "@squadbase/vantage/slide"
+
+export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" })
+export default function Deck() {
+  return (
+    <SlideDeck>
+      <Slide>…</Slide>
+      <Slide>…</Slide>
+    </SlideDeck>
+  )
+}
+```
+
+**`<Slide>` は `<SlideDeck>` の直接の子に書く。** `SlideDeck` は直下の `<Slide>` 要素だけを数えるので、
+`<Slide>` を自作コンポーネント(`<Slide1 />` など)や Fragment で包むと 1 枚も数えられず「1 / 0」に
+なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列は可)。共通の部品は
+`<Slide>` の**中**に置くコンポーネントとして切り出します(`<Slide><CoverPage /></Slide>`)。
+
+1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
+送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
+書き出せます。**書き方の作法は同梱 Skill の
+`vantage-slide`** にあります(キャンバスの縦方向の予算、段階表示、トランジション、モーフ、
+pptx が壊れる条件)。
+
+`.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
+`INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので
+`ROUTE_CONFLICT` です。

package/base-template/agents/xlsx.md

@@ -0,0 +1,33 @@
+# xlsx ページ
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.xlsx` を
+ページとして置くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## `.xlsx` を置くだけでページになる
+
+**`.xlsx` を `src/` に置くだけで、他のページと同格のルートになります。** URL の作り方は
+`.tsx` と同じ(`src/data/june.xlsx` → `/data/june`、`index.xlsx` はそのディレクトリ)で、
+ナビにも `vantage routes` にも並びます。開くとフレームワーク同梱の表ビューアが描き、複数シートを
+切り替えられ、元ファイルをダウンロードできます。ビューアは**表計算ソフトの見た目**です ——
+列は A / B / C、左に行番号、ファイルの 1 行目はヘッダとして固定、シートのタブは下端。
+読み取り専用で、編集もソートもできません(セルを選んで `Cmd/Ctrl+C` でコピーは可)。
+
+- **タイトルはファイル名から導かれる**(`june.xlsx` → 「June」)。データファイルに `definePage` は
+  書けません。名前を変えたいときはファイルをリネームします
+- **ページにしたくないファイルは `_` を前置する**(`_june.xlsx`)。`components/`・`hooks/`・`lib/` に
+  置いたものも同じくページになりません
+- **既定はファイルをそのまま置く(tsx を書かない)。** 自分でタイトルや説明を付けたいときだけ、`_` を
+  前置してルート化を止め、tsx から描きます:
+  ```tsx
+  import { FilePageView } from "@squadbase/vantage/table"
+  import src from "./_june.xlsx?url&no-inline"
+  export const page = definePage({ title: "6月度 売上レポート" })
+  export default () => <FilePageView src={src} kind="xlsx" fileName="june.xlsx" />
+  ```
+- **複数シートに対応**しています。シートのタブは下端に並び、切り替えて閲覧できます。
+- 数式・グラフ・セル書式は再現されません(値として読めれば十分、という設計)。ブラウザでパースするので
+  25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは `server/api/` から配って
+  `DataTable` で描いてください
+- **ビューアの無い拡張子(`.xls`・`.ods` など)はルートになりません。** `vantage check` の
+  `UNSUPPORTED_PAGE_FILE` 警告が知らせます