@squadbase/vantage-template 0.0.2 → 0.1.0-dev.c40b771

package/README.md

@@ -56,6 +56,8 @@ npx @squadbase/vantage-template add funnel --force      # Overwrite existing fil
 
 Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css` (under `src/` when that layout is in use), leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
 
+A new project starts on the `blue` preset — the base template ships that block already written, so `init` and the gallery previews show the same colors. This command swaps it for another preset.
+
 ```bash
 npx @squadbase/vantage-template chart ocean
 npx @squadbase/vantage-template chart forest --dry-run

package/base-template/.squadbase/skills/project-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-storage
+description: Squadbase の Project Storage(アップロード済みファイル)を @squadbase/react の useStorage() でブラウザから扱う手順。ファイル一覧、画像 / 動画 / PDF の埋め込み、中身の読み取り、アップロードと削除・移動。ページやコンポーネントがアップロード済みファイルを表示・埋め込み・アップロードするときに参照する。
+---
+
+# Project Storage(ブラウザ側)
+
+Squadbase の **Project Storage** を React コンポーネントから読み書きする手順。Squadbase 上で
+動くアプリでは資格情報も設定も要らず、そのまま動く。サーバー(`server/api/**`)からストレージを
+触る API は別物で、ここでは扱わない。
+
+## import は `@squadbase/react` から直接
+
+「import は `@squadbase/vantage` のサブパス経由」はフレームワークが所有するものの話。
+**`@squadbase/react` は Squadbase プラットフォームの SDK なので直接 import する**
+(`SquadbaseProvider` / `useUser` と同じ)。
+
+```tsx
+import { useStorage } from "@squadbase/react"
+
+const storage = useStorage()
+// 呼び出しはすべて storage.uploads.* の下
+```
+
+`useStorage()` が返すクライアントは安定なので、コンポーネント先頭で呼んで `useQuery` /
+`useMutation` の中で使ってよい。データ取得のフックは `@squadbase/vantage/query` から取る
+(`@tanstack/*` は直接 import しない)。
+
+## API
+
+すべて async。`key` はストレージ内の**相対**パス(例: `reports/2025-q1.pdf`)で、先頭に
+スラッシュを付けない。
+
+読み取り:
+
+- `list(prefix?, options?)` → `{ objects, commonPrefixes, nextCursor? }`。`objects` は
+  `{ key, size, lastModified }[]`。`options.delimiter = "/"` でフォルダ表示(サブフォルダが
+  `commonPrefixes` に入る)、省略すると再帰的なフラット一覧。`options.limit` / `options.cursor`
+  でページング(`cursor` は前回の `nextCursor`)
+- `head(key)` → `{ key, size, contentType, createdAt }`。メタ情報だけで本体は取らない
+- `getUrl(key)` → `{ url, expiresAt }`。埋め込み用の一時 URL
+- `get(key)` → 生の `Response`。`.json()` / `.text()` / `.blob()` / `.arrayBuffer()` で読む
+
+書き込み:
+
+- `put(key, data, options?)` → `void`。`data` は `Blob`(`File` を含む) / `ArrayBuffer` /
+  `Uint8Array` / `string`
+- `delete(key)` → `void`
+- `copy(srcKey, destKey, options?)` / `move(srcKey, destKey, options?)` → `void`
+
+## 一覧を出す
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const { data, isPending, isError } = useQuery({
+  queryKey: ["storage", "list", prefix],
+  queryFn: () => storage.uploads.list(prefix, { delimiter: "/" }),
+})
+```
+
+`data.commonPrefixes` をフォルダ、`data.objects` をファイルとして描く。プレフィックス配下を
+まとめて出すなら `delimiter` を省く。
+
+## 画像 / 動画 / PDF を埋め込む
+
+埋め込みには URL が要るので `getUrl` を使う。**URL には期限がある**ので、切れる前に取り直す:
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+function useStorageUrl(key: string) {
+  const storage = useStorage()
+  return useQuery({
+    queryKey: ["storage", "url", key],
+    queryFn: () => storage.uploads.getUrl(key),
+    refetchInterval: (query) => {
+      const expiresAt = query.state.data?.expiresAt
+      if (!expiresAt) return false
+      // 期限の 60 秒前に取り直す
+      return Math.max(0, new Date(expiresAt).getTime() - Date.now() - 60_000)
+    },
+  })
+}
+```
+
+```tsx
+import { ErrorState, Loading } from "@squadbase/vantage/ui"
+
+const { data, isPending, isError } = useStorageUrl("reports/cover.png")
+if (isPending) return <Loading />
+if (isError) return <ErrorState message="ファイルを読み込めませんでした" />
+return <img src={data.url} alt="" className="w-full rounded-lg" />
+```
+
+動画は `<video src={data.url} controls className="w-full rounded-lg" />`、PDF は
+`<iframe src={data.url} className="h-[80vh] w-full rounded-lg border border-border" />`。
+
+## 中身を JS で読む
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["storage", "content", key],
+  queryFn: async () => {
+    const res = await storage.uploads.get(key)
+    return (await res.json()) as Row[] // または res.text()
+  },
+})
+```
+
+## アップロードする
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useMutation, useQueryClient } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const queryClient = useQueryClient()
+const upload = useMutation({
+  mutationFn: (file: File) =>
+    storage.uploads.put(`uploads/${file.name}`, file, { contentType: file.type }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["storage", "list"] }),
+})
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0]
+    if (file) upload.mutate(file)
+  }}
+/>
+```
+
+`File` はそのまま `put` に渡す。書き込み後は該当する `["storage", "list", …]` を invalidate して
+UI を追従させる。
+
+## 落とし穴
+
+- **`getUrl` の URL は短命。** 結果を永続化したり長寿命のキャッシュに入れたりしない。
+  `expiresAt` の前に取り直す(上のフック)。`<img src>` に一度入れて放置すると、開いたままの
+  画面で後から読み込まれた分が失敗する
+- **`put` の `contentType` の既定は `application/octet-stream`。** 後で埋め込むもの(画像・動画・
+  PDF)には `file.type` を必ず渡す。付けないとブラウザが表示せずダウンロードに落ちる
+- **`key` は相対パス。** 先頭にスラッシュを付けない。`getUrl` を通さず `<img src="/foo.png">` の
+  ような静的パスで参照しない ― ストレージはアプリの `public/` ではない
+- **`copy` / `move` は既定で既存の宛先を上書きする。** 残したいときは `{ overwrite: false }`
+- **サーバー(`server/api/**`)からは呼ばない。** `useStorage` はブラウザ側の API
+
+---
+
+## 関連スキル
+
+- `vantage-add-feature` — ページ / API / コンポーネントを 1 つ足す手順
+- `vantage-pitfalls` — UI・配色・ルーティングの落とし穴

package/base-template/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる

package/base-template/AGENTS.md

@@ -36,6 +36,11 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
   `ApiContext.env`(server/ 内)にだけ届く。
+- **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
+  `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
+  素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
+  手動で 2 モードを管理することになる(→「ダークモードは opt-in」)。`--muted`・`--accent`・
+  `--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
@@ -318,6 +323,16 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
   `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"` を
+自分で付ける。
+
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash
@@ -364,6 +379,7 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+- **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
 手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
 `.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
@@ -391,8 +407,9 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 > フレームワーク規約と矛盾する場合は**こちらが優先**します。
 >
 > `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
-> このセクションは消えます。消えたら squadbase-templates リポジトリの `agents/vantage/`
-> から貼り直してください(リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+> このセクションは消えます。消えたら squadbase-monorepo の
+> `packages/vantage-template/agents/vantage/` から貼り直してください
+> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
 
 ## Squadbase の Connection / Query からデータを読む
 
@@ -469,3 +486,33 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
   body: JSON.stringify({ customerId: "c_123" }),
 })
 ```
+
+## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
+
+ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
+(まだ存在しないモジュールの import、書きかけのコンポーネント)。これを受け止めるのは
+**Vantage の既定エラー画面**(`Something went wrong`)で、**テンプレートからは差し替えられない** —
+`_error.tsx` はルートルート専用で、ページごとの `errorComponent` は現行プロトタイプでは
+まだ結線されていない。しかも掴んでいるのは TanStack の CatchBoundary なので、HMR で
+ソースが差し替わってもリセットされず、**リロードするまでエラー画面が貼り付く**。
+
+`components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
+`Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
+(上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
+自力で直らないときに本文をそのまま貼り戻してもらうため。
+`_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
+見た目と復帰の仕方は揃っている。
+
+### 追加の不変条件
+
+- **`_layout.tsx` の `<BuildRecovery>` を外さない。** `<Outlet />` を包む形で 1 回だけ使う。
+  外すと、書き込み途中の一瞬のエラーが `Something went wrong` のまま残る。
+- **`components/build-recovery.tsx` と `_error.tsx` を消さない・作り直さない。** ページ側に
+  独自のエラー UI を足す必要はない(足しても既定エラー画面より内側には入れない)。
+- **`role="alert"` の中に `h2` を置かない。** これが既定エラー画面の目印なので、ページが
+  同じ形を描くと `BuildRecovery` が誤検知して中身を覆ってしまう。UI キットの `Alert` /
+  `ErrorState` は見出しを `div` / `p` で描くのでそのまま使ってよい。
+- **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
+  「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
+  (→ フレームワーク規約の「データ取得」)。