@squadbase/vantage-template 0.1.1-dev1.ac4fa22 → 0.1.1-dev1.bb2f95a

package/base-template/agents/doc.md

@@ -12,9 +12,16 @@
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
-import { EChart } from "@squadbase/vantage/components"
+import { BarChart } from "@squadbase/vantage/components"
 import { Document } from "@squadbase/vantage/doc"
 
+const weekly = [
+  { week: "第1週", 売上: 1180 },
+  { week: "第2週", 売上: 1240 },
+  { week: "第3週", 売上: 1210 },
+  { week: "第4週", 売上: 1620 },
+]
+
 export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
 export default function JuneSummary() {
   return (
@@ -23,7 +30,7 @@ export default function JuneSummary() {
       <p>6月の売上は <strong>5,250 万円</strong>で、目標を 5% 上回りました。</p>
       <h2>週次の売上</h2>
       <figure>
-        <EChart option={option} height={280} ariaLabel="6月の週次売上" />
+        <BarChart data={weekly} index="week" categories={["売上"]} height={280} ariaLabel="6月の週次売上" />
         <figcaption>第4週はキャンペーン初週</figcaption>
       </figure>
       <table>…</table>
@@ -42,13 +49,38 @@ export default function JuneSummary() {
   見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
 - **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
   `useApiQuery` などで読み込むと、開くたびに値が変わります。
-- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+- **チャートは型付きチャート(`BarChart`・`LineChart` など。`@squadbase/vantage/components`)を
+  文中に置く**(選び方は `agents/page.md` の「グラフはまず型付きチャートで描く」)。`figure` で囲めば
   `figcaption` がキャプションになります。
 - **PDF の保存ボタンは作らない。** `<Document>` が右下に PDF 保存のボタンを出し、印刷時は
   本文だけをライトの配色で出します。
 - **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
   (本文の幅と余白は `<Document>` が決めます)。
 
+## まず block を探す
+
+1 節分の中身は、手で組む前に `@squadbase/vantage/doc` の block から探します(`<Document>` の直下に
+並べる。多くは 1 block = 1 節。`DocCallout`・`DocFigure`・`DocDataTable` は節ではなく、節の中(本文の間)に置く部品)。props は `vantage docs <name>`(例: `vantage docs doc-kpi-scorecard`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `DocReportHeader` | レポートの冒頭(タイトル・サブタイトル・対象期間・データ時点・作成者・出典) |
+| `DocExecutiveSummary` | 結論を先に述べる要約の節 |
+| `DocKpiScorecard` | 主要指標をまとめたスコアカード |
+| `DocFigure` | 図表 1 つとキャプション(チャートは children で渡す) |
+| `DocDataTable` | 素の `table` による表 |
+| `DocCallout` | 補足・示唆・注意・決定の囲み(`kind`: `note` / `insight` / `warning` / `decision`) |
+| `DocKeyFindings` | 主要な発見の箇条 |
+| `DocActionItems` | 次のアクション(担当・期限つき) |
+| `DocNotesAndSources` | 末尾の注記・用語の定義・データソースをまとめた節 |
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「データ時点」は block が付けるので「時点」を書かない)。時系列は、単一系列なら `{ x, y }[]`(`trend`)。
+
+本文の中で増減を書くときは `DeltaText`(部品。「▲ +3.2%」の形で、文字サイズは持たず置かれた行に従う。`value` `format` `betterWhen` `comparisonLabel`)を使う。節ではなく文の中に置く。
+
+block が合わない**1 節だけ**を素の HTML 要素で手で書く。import 元は `@squadbase/vantage/doc` のままで、
+block のための新しい import 元はありません。本文は文字列か ReactNode で渡し、Markdown 文字列は渡さない。
+
 ## 見た目を変える
 
 配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
@@ -73,3 +105,20 @@ export default function JuneSummary() {
 `.doc` を付けられるのはルートになるページモジュールだけで、`_layout.doc.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.doc.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではドキュメント固有のものだけを挙げます。
+
+**MUST**
+
+- ファイル名は `<name>.doc.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.doc.mdx` は
+  `INVALID_PAGE_VARIANT`、`.DOC.tsx`・二重サフィックスは黙って通常ページになる
+- default export は `<Document>` をルートに返す。フレームワークは包まない
+- ドキュメントの部品は `@squadbase/vantage/doc` から import する
+
+**SHOULD**
+
+- `PageShell` で包まない・PDF の保存ボタンを自作しない(上の「書き方」)
+- 数値はコードに直接書き、いつ時点の値かを本文に書く

package/base-template/agents/page.md

@@ -4,7 +4,7 @@
 (ダッシュボード)を書くときに読んでください。前提となる不変条件・ディレクトリ構造は
 `AGENTS.md` を先に読んでいる想定です。
 
-プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで配色・書体・レイアウトの規則に従う。
+書き始める前に `AGENTS.md` の「見た目の規約」(と、あればプロジェクトルートの `DESIGN.md`)に従う。
 
 ## 最小アプリ(2 ファイル)
 
@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@squadbase/vantage": "^0.5.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }
 ```
@@ -71,6 +71,7 @@ URL になる。各ページは**デフォルトエクスポートの React コ
 | `_404.tsx` | Not Found ページ |
 | `_error.tsx` | ルートが throw したときのエラーページ |
 | `monthly-report.slide.tsx` | `/monthly-report`(スライドデッキ。詳しくは `agents/slide.md`) |
+| `june-summary.doc.tsx` | `/june-summary`(ドキュメント。詳しくは `agents/doc.md`) |
 | `sales-export.csv` | `/sales-export`(詳しくは `agents/csv.md`) |
 | `data/june.xlsx` | `/data/june`(詳しくは `agents/xlsx.md`) |
 
@@ -89,6 +90,26 @@ export default function MonthlyAnalysis() {
 }
 ```
 
+### ページファイルの規約(`.tsx` / `.slide.tsx` / `.doc.tsx` 共通)
+
+**MUST**
+
+- ページルートの配下に置く。`components/` などの走査対象外のディレクトリに置いたファイルはページに
+  ならず、エラーも出ない。`_` 始まりの名前は予約名(`_layout` / `_404` / `_error`)にだけ使う
+  (それ以外の `_` 始まりはページにならない。予約名にサフィックスを付けると `INVALID_PAGE_VARIANT`)
+- URL はサフィックスと拡張子を除いたパスで決まる。同じ URL になる別ファイル(`june.tsx` /
+  `june.slide.tsx` / `june.doc.tsx` / `june.csv`)を並べない(`ROUTE_CONFLICT`)。テンプレートの
+  未編集の `index.tsx` だけは例外で、`index.slide.tsx` / `index.doc.tsx` が `/` を取れる
+- default export は React の関数コンポーネント(無いと `MISSING_DEFAULT_EXPORT`。関数かどうかは
+  検査されない)
+- `definePage({ ... })` にはオブジェクトリテラルを直接渡し、`title` / `description` / `navLabel` は
+  文字列リテラルで書く。ビルド時に静的抽出されるので、変数・関数呼び出し・spread・shorthand・
+  `${}` を含むテンプレート文字列は**エラーにならず黙ってメタなし**になる
+
+**SHOULD**
+
+- `definePage` に `title` と `navLabel` を書く(ナビの表示名とブラウザのタブ名になる)
+
 ### ナビはルート一覧から組む
 
 `useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
@@ -109,7 +130,7 @@ routes.map((r) => (
 ```
 
 `RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
-`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"`)。
+`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"` | `"doc"`)。
 後ろの 2 つで、ナビをダッシュボード / スライド / データに分けたりアイコンを変えたりできます。
 
 ### フィルタ状態は URL に置く
@@ -126,6 +147,42 @@ const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON
 デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
 (`{ replace: false }` で push)。
 
+### 絞り込みの欄は、読み込み中も失敗したときも出し続ける
+
+ページの先頭で `if (q.isError) return <ErrorState …/>` と書くと、取得に失敗したときに
+期間などの絞り込みの欄まで消える。利用者は条件を直せず、初期値に戻すしかなくなる。
+絞り込みの欄はページに置いたままにし、取得と `Loading` / `ErrorState` はデータを描く
+子コンポーネントに入れる:
+
+```tsx
+export default function Traffic() {
+  const [from, setFrom] = useSearchParam("from", DEFAULT_FROM)
+  const [to, setTo] = useSearchParam("to", DEFAULT_TO)
+  return (
+    <>
+      {/* 失敗しても消えない。ここから条件を直せる */}
+      <PeriodFilter from={from} to={to} onChange={…} />
+      <TrafficBody from={from} to={to} />
+    </>
+  )
+}
+
+function TrafficBody({ from, to }: { from: string; to: string }) {
+  const q = useApiQuery<Row[]>("/api/traffic", { search: { from, to } })
+  if (q.isPending) return <Loading />
+  if (q.isError) return <ErrorState message={q.error.message} />
+  return <BarChart data={q.data} index="channel" categories={["sessions"]} />
+}
+```
+
+- **期間は `DateRangePicker`(`@squadbase/vantage/components`)で選ばせる。** カレンダーで
+  範囲を選ぶので開始と終了が逆にならず、選べる日を `minDate` / `maxDate` で絞れる。
+  `<input type="date">` を 2 つ並べて自前で組まない。
+- 値をそのまま打ち込める欄を置くなら、開始が終了より後・選べる範囲の外といった誤りは、
+  API へ送る前に欄のそばで理由を出す。誤りがあるあいだはデータの子コンポーネントを描かない
+  (送れば失敗するだけで、`ErrorState` には直し方が出ない)。
+- サーバー側の検証で弾くときも、`HttpError(400, …)` の文で何がどう誤りかを言う(→ `agents/api.md`)。
+
 ### 動的パラメータの「3 つの綴り」を同期させる
 
 崩すと静かにマッチしなくなる不変条件:
@@ -164,17 +221,41 @@ refetchOnWindowFocus false・networkMode "always")。挙動を変えたいとき
 ## 組み込み UI / コンポーネントの入口
 
 - **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
-  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+  `ErrorState`・`Empty`・`Select`・`Checkbox`・`RadioGroup`・`Field`・`Combobox`・`Pagination`・
+  `Avatar`・`Kbd`・`HoverCard`・`AlertDialog`・`Drawer`・`Toaster` + `toast.add()` ほか)。
 - **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
-  `DataTablePreset`・`EChart` ほか)。
+  `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` の対象ではない(未知名で実行すると候補が一覧表示される)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui <name>` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンド。`/ui` のプリミティブも
+  `/components` の複合パーツも全部取り出せる(名前は kebab-case: `add ui bar-chart`。
+  ブロックは `add block sales-overview`。未知名で実行すると候補が一覧表示される)。
+
+### 長い表はページングする(縦スクロール箱を作らない)
+
+- 行が多い表は `DataTablePreset`(または `DataTable`)に `enablePagination` を付けて**ページング**する
+  (既定は 10 行 / ページ。ページングは既定で無効なので、付け忘れると全行が並ぶ)。素の `<table>` を
+  手書きして全行を流し込まない。
+- カードの中に `max-h-*` + `overflow-y-auto` の**縦スクロール領域を作らない**。ホイールやキー
+  (End / Space)がその箱に吸われ、ページ全体がスクロールしなくなる。高さは内容に任せる。
+- 横に広い表の `overflow-x-auto` は構わない。`SheetGrid`(`.csv` / `.xlsx` のビューア)は
+  グリッドとして意図した入れ子スクロールなので対象外。
+
+### グラフはまず型付きチャートで描く
+
+- 推移は `LineChart` / `AreaChart`、比較は `BarChart`、構成比は `DonutChart`。`data`(行の配列)・
+  `index`(x 軸の列)・`categories`(系列の列)を渡すだけで、option は書かない
+  (`DonutChart` は `category` / `value`)。
+- 上位 N 件は `BarList`、判定帯や予算消化は `CategoryBar`、達成率は `ProgressCircle`、
+  日ごとの状態は `Tracker`。
+- `EChart` + `EChartsOption` は、二軸・散布図・ヒートマップ・注釈線など型付きチャートの props で
+  表せないときだけ使う。
+- 色は省略してテーマトークンに任せる。指定するなら `"chart-1"`〜`"chart-5"` か
+  `"var(--destructive)"` などの CSS 色。hex の直書きや Tailwind クラスは使わない。
+- 数値の書式(`¥`・`%`・桁区切り)は `valueFormatter` に渡す。
 
 ### ダークモードは opt-in
 

package/base-template/agents/slide.md

@@ -4,7 +4,13 @@
 スライドデッキを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
 先に読んでいる想定です。
 
-プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで「スライド」の節と配色・書体の規則に従う。
+書き始める前に `AGENTS.md` の「見た目の規約」(と、あればプロジェクトルートの `DESIGN.md`)に従う。
+スライド固有の規則:
+
+- 1 枚に 1 メッセージ。見出しに結論を書く。
+- 色は `--slide-bg` / `--slide-fg` / `--slide-accent` / `--slide-muted` を使う(既定では
+  `--background` / `--foreground` / `--primary` / `--muted-foreground` に連動)。
+- 強調色は 1 枚につき 1 か所まで。
 
 ## スライドは `.slide.tsx` で書く
 
@@ -19,6 +25,7 @@
 - 新規プロジェクトでまだ `/` が空いている場合のみ、`index.slide.tsx` を使ってよい。
 
 ```tsx
+import { definePage } from "@squadbase/vantage"
 import { Slide, SlideDeck } from "@squadbase/vantage/slide"
 
 export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" })
@@ -34,8 +41,10 @@ export default function Deck() {
 
 **`<Slide>` は `<SlideDeck>` の直接の子に書く。** `SlideDeck` は直下の `<Slide>` 要素だけを数えるので、
 `<Slide>` を自作コンポーネント(`<Slide1 />` など)や Fragment で包むと 1 枚も数えられず「1 / 0」に
-なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列は可)。共通の部品は
-`<Slide>` の**中**に置くコンポーネントとして切り出します(`<Slide><CoverPage /></Slide>`)。
+なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列はファイル形式としては可。
+1 枚の中で視覚要素を `map` で量産しない方針は `vantage-slide` skill の「繰り返す要素は `map` ではなく
+コンポーネント」)。共通の部品は `<Slide>` の**中**に置くコンポーネントとして切り出します
+(`<Slide><CoverPage /></Slide>`)。
 
 1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
@@ -51,3 +60,68 @@ pptx が壊れる条件、説明と図表のデータ時点の揃え方)。
 `.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## まず block を探す
+
+1 枚分の中身は、手で組む前に `@squadbase/vantage/slide` の block から探します(`<Slide>` の**中**に
+置く。ルートは 100% で、`<Slide>` 自体は持たない)。props は `vantage docs <name>`(例:
+`vantage docs slide-kpi-hero`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `SlideCover` | 表紙(タイトル・サブタイトル・期間) |
+| `SlideExecSummary` | 結論を先に述べるエグゼクティブサマリー |
+| `SlideKpiHero` | 主要な KPI 1 つを大きく見せる |
+| `SlideKpiGrid` | 複数の KPI を並べる |
+| `SlideChartInsight` | チャート 1 つと、そこから読み取れること |
+| `SlideScorecardTable` | 指標と目標・達成度を表にしたスコアカード |
+| `SlideNextActions` | 次のアクション(担当・期限つき) |
+| `SlideSection` | 章の扉(`items` を渡すと番号付きのアジェンダ。`current` の章を強調) |
+| `SlideComparison` | A vs B・前後の 2〜3 列比較(各列に見出し・主要数値・箇条) |
+| `SlideChartFull` | チャートを全幅に置き、注記を 1 行添える |
+
+**手書きの 1 枚には部品を使う。** block が合わない 1 枚でも、見出し・出典行・列割りは自前で組まず、
+次の部品を使う(どれも `@squadbase/vantage/slide`。1 枚にはならないので `<Slide>` の中に並べる)。
+
+| 部品 | 用途 |
+| --- | --- |
+| `SlideHeading` | 見出し(`title`、任意で `eyebrow`)。1 枚の先頭に置く |
+| `SlideSourceLine` | 足元の出典・時点(`source` `asOf`)。`page={{ current, total }}` を渡すとページ番号も出す |
+| `SlideColumns` / `SlideColumn` | 12 列の割り付け(`<SlideColumn span={8}>` と `span={4}` など)。`align` は `start` / `center` / `stretch` |
+| `DeltaText` | 増減の文字(「▲ +3.2%」)。`value` `format` `betterWhen` `comparisonLabel` |
+
+`SlideSection` は `Steps` を持たない。順に見せたいときは呼び出し側で `<Steps>` で包む。
+
+```tsx
+import { Slide, SlideDeck, SlideCover, SlideExecSummary } from "@squadbase/vantage/slide"
+// <SlideDeck><Slide><SlideCover … /></Slide><Slide><SlideExecSummary … /></Slide></SlideDeck>
+```
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`(文字列)、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「時点」は block が付けるので書かない)。時系列は、単一系列なら `{ x, y }[]`(kpi-hero の `trend`。scorecard に `trend` は無い)、複数系列なら `{ categories, series }`(chart-insight の `chart`)。
+
+block が合わない**1 枚だけ**を手で書く(デッキ全体を手書きに切り替えない)。import 元は
+`@squadbase/vantage/slide` のままで、block のための新しい import 元はありません。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではスライド固有のものだけを挙げます。**中身の値(キャンバス・
+セーフエリア・グリッド・文字サイズ・余白)は `vantage-slide` skill を参照。**
+
+**MUST**(破ると黙って壊れるものが多い。`vantage check` が拾うのは名前の誤りだけ)
+
+- ファイル名は `<name>.slide.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.slide.ts` は
+  `INVALID_PAGE_VARIANT`、`.SLIDE.tsx`・二重サフィックス・`.slide.test.tsx` は黙って通常ページになる
+- default export は `<SlideDeck>` をルートに返す。フレームワークは包まない
+- `<Slide>` は `<SlideDeck>` の直接の子(配列は可。Fragment・自作コンポーネントで包まない)
+- `<Step>` は `<Steps>` の直接の子(包むと常に表示される)
+- スライドの部品は `@squadbase/vantage/slide` から import する
+
+**SHOULD**
+
+- 1 ファイル = 1 デッキ。ヘルパーコンポーネント・定数も同じ `.slide.tsx` に書く
+- 各 `<Slide>` のルート要素は `width: "100%"; height: "100%"` でキャンバスを埋める
+- canvas に描くチャート(`EChart`)は `data-waitfor="canvas"` で包む(無いと pptx でそのスライドが白紙になりうる)
+- pptx に出る中身をアプリの Context(router / query / テーマ)に依存させない
+- `MorphElement` の `id` はページ内で一意にし、入れ子にしない。遷移先の `<Slide>` で `transition.morph` を有効にする
+- pptx 用などの依存を追加しない(html-to-image / fflate は自動で入る)

package/base-template/agents/xlsx.md

@@ -28,6 +28,7 @@
 - **複数シートに対応**しています。シートのタブは下端に並び、切り替えて閲覧できます。
 - 数式・グラフ・セル書式は再現されません(値として読めれば十分、という設計)。ブラウザでパースするので
   25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは `server/api/` から配って
-  `DataTable` で描いてください
+  `DataTable` で描いてください。20 万行を超えると先頭
+  20 万行だけが表示されます(残りはダウンロードして見る)
 - **ビューアの無い拡張子(`.xls`・`.ods` など)はルートになりません。** `vantage check` の
   `UNSUPPORTED_PAGE_FILE` 警告が知らせます