@squadbase/vantage 0.6.2-dev1.9d91dda → 0.6.2-dev1.ac99e02

package/docs/ja/changelog.md

@@ -20,6 +20,32 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
   そのままでは届きませんでした。`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも
   渡せます(フラグが優先)。どちらも指定しなければ挙動は従来どおりです。詳細は
   [CLI リファレンス](cli-reference)を参照してください。
+- **型付きチャート 8 種**を `@squadbase/vantage/components` に追加しました。`LineChart` /
+  `AreaChart` / `BarChart` / `DonutChart`(ECharts で描画)は `data`・`index`・`categories` を
+  渡すだけで描け、`EChartsOption` を書く必要がありません。`BarList` / `CategoryBar` /
+  `ProgressCircle` / `Tracker` は SVG と Tailwind で描く軽い部品です。色は既定でテーマの
+  `--chart-1..5` に追従し、指定するときはトークン名(`"chart-1"`〜`"chart-5"`)か CSS 色を渡します。
+  `EChart` は型付きチャートで表せない図のための逃げ道として残ります。
+- **UI プリミティブ 10 種**を `@squadbase/vantage/ui` に追加しました: `Avatar`・`Pagination`・
+  `RadioGroup`・`AlertDialog`・`Drawer`・`Toast`(`<Toaster>` + `toast.add()`)・`Field`・
+  `Combobox`・`HoverCard`・`Kbd`。
+- **[コンポーネント](components)に一覧ギャラリー**を足しました。カテゴリで絞り込め、各部品の
+  `vantage add ui` コマンドをコピーできます。
+- **[ページの種類](page-types)**のガイドを足しました(`.csv` / `.xlsx` / `.slide.tsx` /
+  `.doc.tsx` の書き方と、ページにならないファイル)。
+
+### 変更
+
+- **`vantage add ui <name>` で `/ui` と `/components` の部品をすべて取り出せるようになりました。**
+  これまでコピーできたのは `data-table` だけでした。registry は `src/` から生成するようになり、
+  コピーの中の import は公開サブパスに書き換わっています(→ [UI とテーマ](ui-and-theming))。
+
+### 修正
+
+- **`.xlsx` のページで日付が 1 日ずれて表示されなくなりました。** Excel の日付はタイムゾーンを
+  持たないのに、ブラウザのタイムゾーンで表示していたため、UTC より西(アメリカなど)では
+  `2026-06-02` が `6/1` と前日に、時刻付きのセルは UTC より東(日本など)でも夜の時刻が翌日に
+  ずれていました。いまはどのタイムゾーンでもファイルに書かれた日付・時刻のまま表示します。
 
 ## v0.6.2
 

package/docs/ja/components.md

@@ -3,13 +3,13 @@
 > Vantage に同梱される shadcn/ui (Base UI) キットと、ダッシュボード用の複合コンポーネントのリファレンス。
 
 Vantage は **shadcn/ui** をそのまま同梱しています。インストールもコピーも不要で、import するだけで
-使えます。公開されている入り口は 3 つで、**サイドバーもこの 3 つで区切ってあります**。
+使えます。入り口は 3 つのサブパスで、**サイドバーもこの 3 つで区切ってあります**。
 
-| サブパス | 中身 | 件数 |
-| --- | --- | --- |
-| [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ | 37 |
-| [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 | 15 |
-| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） | 1 |
+| サブパス | 中身 |
+| --- | --- |
+| [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ |
+| [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 |
+| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） |
 
 ```tsx
 import { Button, Card, Badge } from "@squadbase/vantage/ui";
@@ -17,9 +17,27 @@ import { PageShell, DashboardCardPreset, EChart } from "@squadbase/vantage/compo
 import { MarkdownRenderer } from "@squadbase/vantage/markdown";
 ```
 
+## 一覧
+
+用途で絞り込めます。カードを開くと、動くプレビュー・import 文・props が見られます。
+
+## どちらを使うか
+
+似た役割のものが並んでいる組み合わせです。迷ったら左の列の条件で選んでください。
+
+| 迷いやすい組み合わせ | 選び方 |
+| --- | --- |
+| [`Badge`](ui/badge) / [`StatusBadge`](parts/status-badge) | 件数やタグなど**ただのラベル**は `Badge`。`active` / `failed` のような**レコードの状態**を色付きドットで示すなら `StatusBadge`（色は状態名から自動で決まる）。 |
+| [`ToggleGroup`](ui/toggle-group) / [`SegmentedControl`](parts/segmented-control) | 表示期間やビューの切り替えのような**単一選択**は `SegmentedControl`（値は `string`）。複数を同時に押せる**トグルの束**が要るときだけ `ToggleGroup`（値は常に配列）。 |
+| [`Select`](ui/select) / [`SearchableSelect`](parts/searchable-select) / [`MultiSelect`](parts/multi-select) / [`FilterBar`](parts/filter-bar) | 候補が**数個**なら `Select`。**多くて探したい**なら `SearchableSelect`、**複数選ぶ**なら `MultiSelect`。ページ上部に並ぶ**絞り込み一式**は、個別に置かず `FilterBar`（`FilterBarSelect` / `FilterBarMultiSelect`）でまとめて 1 つの値として扱う。 |
+| [`Sparkline`](parts/sparkline) / [`EChart`](parts/echart) | 表のセルや KPI タイルの隅に置く、**軸も凡例もない小さな推移**は `Sparkline`。軸・ツールチップ・凡例のある**本格的なグラフ**は `EChart`。 |
+| [`Skeleton`](ui/skeleton) / [`DashboardCardSkeleton`](parts/dashboard-card) / [`Placeholder`](parts/placeholder) | **読み込み中**の任意の形は `Skeleton`、ダッシュボードのタイル 1 枚分なら `DashboardCardSkeleton`。`Placeholder` は読み込み中ではなく、**中身が仮データであること**を示す目印。 |
+| [`Loading`](ui/loading) / [`Empty`](ui/empty) / [`ErrorState`](ui/error-state) | データ取得の 3 状態に 1 つずつ対応する。**取得中**は `Loading`、**0 件**は `Empty`、**失敗**は `ErrorState`（`action` に再試行ボタンを置ける）。 |
+
 > [!NOTE]
 > UI キットは**パッケージから import して使う**のが基本です（コピーしません）。中身を書き換えたい
-> ときだけ [`vantage add`](cli-reference) で編集可能なソースを取り出します。
+> ときだけ [`vantage add ui`](cli-reference) で編集可能なソースを取り出します。各コンポーネントの
+> ページ冒頭に、import 文と取り出しコマンドをコピーできる行があります。
 
 ## Base UI ベースであること
 
@@ -53,87 +71,14 @@ Vantage の `theme.css` は両方の綴りを受ける custom variant を定義
 
 shadcn/ui のプリミティブです。名前も props も shadcn/ui のものと同じなので、
 [shadcn/ui のドキュメント](https://ui.shadcn.com/docs/components) もそのまま参考になります。
-サイドバーはアルファベット順ですが、ここでは用途で並べています。
-
-### フォームと入力
-
-[`Button`](ui/button) ·
-[`Input`](ui/input) ·
-[`InputGroup`](ui/input-group) ·
-[`Textarea`](ui/textarea) ·
-[`Label`](ui/label) ·
-[`Select`](ui/select) ·
-[`Checkbox`](ui/checkbox) ·
-[`Switch`](ui/switch) ·
-[`Slider`](ui/slider) ·
-[`Toggle`](ui/toggle) ·
-[`ToggleGroup`](ui/toggle-group) ·
-[`Calendar`](ui/calendar) ·
-[`Command`](ui/command)
-
-### レイアウトとナビゲーション
-
-[`Card`](ui/card) ·
-[`Tabs`](ui/tabs) ·
-[`Separator`](ui/separator) ·
-[`ScrollArea`](ui/scroll-area) ·
-[`Sidebar`](ui/sidebar) ·
-[`Breadcrumb`](ui/breadcrumb) ·
-[`Accordion`](ui/accordion) ·
-[`Collapsible`](ui/collapsible)
-
-### データ表示
-
-[`Table`](ui/table) ·
-[`Badge`](ui/badge) ·
-[`Progress`](ui/progress)
-
-### オーバーレイ
-
-[`Dialog`](ui/dialog) ·
-[`Sheet`](ui/sheet) ·
-[`Popover`](ui/popover) ·
-[`Tooltip`](ui/tooltip) ·
-[`DropdownMenu`](ui/dropdown-menu)
-
-### 状態表示
-
-[`Alert`](ui/alert) ·
-[`Skeleton`](ui/skeleton) ·
-[`Spinner`](ui/spinner) ·
-[`Loading`](ui/loading) ·
-[`Empty`](ui/empty) ·
-[`ErrorState`](ui/error-state)
-
 `Loading` / `Empty` / `ErrorState` の 3 つだけは shadcn/ui にはなく、Vantage が足したものです。
 
-### ユーティリティ
-
-[`cn()`](ui/cn) · [`useIsMobile()`](ui/use-is-mobile)
-
 ## `@squadbase/vantage/components`
 
-`ui/` を組み上げた、ダッシュボード向けの複合部品です。
-
-| コンポーネント | 概要 |
-| --- | --- |
-| [`PageShell`](parts/page-shell) | ヘッダー帯・サマリー・本文からなるページ枠 |
-| [`AppShell`](parts/app-shell) | ナビゲーション定義を渡すだけのアプリ枠 |
-| [`SectionHeader`](parts/section-header) | セクション見出しとアクション |
-| [`DashboardCard`](parts/dashboard-card) | ダッシュボードのタイル（プリセットとスケルトン付き） |
-| [`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) | 単一選択のセグメント |
-| [`SearchableSelect`](parts/searchable-select) | 検索できる単一選択 |
-| [`MultiSelect`](parts/multi-select) | 検索できる複数選択 |
-| [`MetricValue`](parts/metric-value) | KPI の数値と単位 |
-| [`TrendIndicator`](parts/trend-indicator) | 増減の矢印と変化率 |
-| [`StatusBadge`](parts/status-badge) | ドット付きステータスバッジ |
-| [`Placeholder`](parts/placeholder) | 仮データであることを示すインラインの目印 |
+`ui/` を組み上げた、ダッシュボード向けの複合部品です。ページ枠（`PageShell` / `AppShell`）、
+タイル（`DashboardCard`）、表（`DataTable`）、グラフ（`EChart` / `Sparkline` / `FunnelSteps`）、
+フィルタ（`FilterBar` / `DateRangePicker` など）、KPI 表示（`MetricValue` / `TrendIndicator`）が
+入っています。
 
 ## `@squadbase/vantage/markdown`
 
@@ -214,16 +159,15 @@ export default function Overview() {
 
 ## ソースを編集したいとき
 
-コンポーネントの中身そのものを変えたい場合は、編集可能なコピーを取り出します。
+コンポーネントの中身そのものを変えたい場合は、編集可能なコピーを取り出します。名前は各ページ冒頭の
+「ソースを取り出す」の行に出ているものです。
 
 ```bash
-vantage add ui data-table        # 編集可能な DataTable を components/ へ
+vantage add ui data-table        # 編集可能な DataTable を components/ui/ へ
 vantage add block sales-overview
 ```
 
-> [!NOTE]
-> 現行プロトタイプで `vantage add` がコピーできるのは `data-table`（ui）と `sales-overview`（block）
-> のみです。その他のコンポーネントは import 専用です。
+`cn()` と `useIsMobile()`、`@squadbase/vantage/markdown` は取り出しの対象外で、import 専用です。
 
 ## このページの読み方
 

package/docs/ja/page-types/csv.md

@@ -0,0 +1,83 @@
+# CSV
+
+> .csv を置くだけで表として読めるページになる。列の型の推定、ファイル名からのタイトル、25MB / 20 万行の上限。
+
+`.csv` を置くだけで、そのファイルは**表として読めるページ**になります（`src/sales-export.csv` →
+`/sales-export`）。tsx は書きません。ダウンロードしなくても、ブラウザでそのまま中身を確かめられます。
+
+## 置き方
+
+ページ走査のルート（`src/` があればその中）にファイルを置くだけです。
+
+| ファイル | ルート | タイトル |
+|---|---|---|
+| `sales-export.csv` | `/sales-export` | Sales Export |
+| `data/june.csv` | `/data/june` | June |
+| `regions/index.csv` | `/regions` | Regions |
+
+- **タイトルはファイル名から作られます。** 区切り（`-`・`_`）で単語に分け、先頭を大文字にします。
+  `index.csv` はディレクトリ名を使います。データファイルに `definePage` は書けないので、
+  名前を変えたいときはファイルをリネームします。
+- 見出しの下には元のファイル名が、右上にはダウンロードボタンが出ます。
+
+## できること
+
+- **表計算ソフトの見た目で読める。** 列は A / B / C、左に行番号、1 行目はヘッダとして固定され、
+  下端に行数と列数が出ます。セルを選んで `Cmd/Ctrl+C` でコピーできます。
+- **列の型を推定。** 先頭 500 行を見て、9 割以上が数値なら数値列（桁区切り・右寄せ）、
+  `2026-06-30` の形の日付なら日付列として扱います。
+- **文字コードを自動判定。** UTF-8（BOM あり / なし）で読み、文字化けが多ければ Shift_JIS で
+  読み直します。Excel から書き出した日本語の CSV もそのまま置けます。
+- **ダークモードに追従。** 配色はアプリのテーマトークンで塗られます。
+
+## 制限
+
+- **読み取り専用です。** 編集・並べ替え・絞り込みはできません。それが要るデータは
+  `server/api/` から配って [`DataTable`](parts/data-table) で描きます。
+- **25MB を超えるファイルは表示されません。** パースはブラウザで行うためです。そのページには
+  エラーとダウンロードボタンが出て、`vantage check` も `FILE_PAGE_TOO_LARGE` で先に警告します。
+- **20 万行を超えると、先頭の 20 万行だけを表示します。** 下端に「First 200,000 of … rows」と
+  出るので、残りはダウンロードして見ます。
+- 1 行目は必ずヘッダとして扱われます。空行は読み飛ばされます。
+- **`.tsv` はページになりません**（`UNSUPPORTED_PAGE_FILE` 警告）。`.csv` に変換して置きます
+  （ほかの形式は [ページにならないファイル](page-types)）。
+- ページにしたくない `.csv` は `_` を前置します（`_sales-export.csv`）。
+
+## 自分で描く
+
+タイトルや説明を自分で付けたいときは、`_` を前置してページになるのを止め、tsx から
+`FilePageView` で描きます。ファイルの URL は `?url&no-inline` を付けて import します
+（小さいファイルが JS に埋め込まれて、ダウンロードできなくなるのを防ぐためです）。
+
+```tsx
+// src/sales.tsx  →  /sales(src/_sales-export.csv を描く)
+import { definePage } from "@squadbase/vantage";
+import { FilePageView } from "@squadbase/vantage/table";
+import src from "./_sales-export.csv?url&no-inline";
+
+export const page = definePage({ title: "売上エクスポート" });
+
+export default function Sales() {
+  return <FilePageView src={src} kind="csv" fileName="sales-export.csv" title="売上エクスポート" />;
+}
+```
+
+ダッシュボードの一部として表だけを埋めたいときは `loadWorkbook` と `TableViewer` を組み合わせます
+（[Excel](page-types/excel) の API を参照）。
+
+## API
+
+```tsx
+import { FilePageView } from "@squadbase/vantage/table";
+```
+
+### FilePageView
+
+ファイルページそのものです。URL を渡すと、取得・パース・表示まで行います。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `src` | `string` |  | ファイルの URL。`import src from "./_x.csv?url&no-inline"` で得る。 |
+| `kind` | `"csv" \| "xlsx"` |  | ファイルの種類（拡張子からドットを除いたもの）。 |
+| `fileName` | `string` |  | 元のファイル名。見出しの下とダウンロード時の名前に使う。 |
+| `title` | `string` | `fileName` | 見出し。 |

package/docs/ja/page-types/doc.md

@@ -0,0 +1,83 @@
+# ドキュメント
+
+> <name>.doc.tsx を置くと上から読む文章のページになる。クラス無しで組版され、「PDF として保存」で印刷できる。
+
+`<name>.doc.tsx` を置くと、そのページは**ドキュメント**になります（`src/june-summary.doc.tsx` →
+`/june-summary`）。報告書や調査のまとめのように、文章と図表を上から読む形で残したいときに使います。
+
+## 置き方
+
+中身は `<Document>` を返す普通の React コンポーネントです。中には素の HTML 要素をそのまま書きます。
+
+```tsx
+// src/june-summary.doc.tsx  →  /june-summary
+import { definePage } from "@squadbase/vantage";
+import { Document } from "@squadbase/vantage/doc";
+
+export const page = definePage({ title: "6月度サマリー" });
+
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>6月度サマリー</h1>
+      <p>6月の売上は目標を 5% 上回りました。</p>
+      <table>…</table>
+    </Document>
+  );
+}
+```
+
+## できること
+
+- **クラスを書かなくても組版される。** `h1`〜`h4`・`p`・`ul` / `ol`・`table`・`blockquote`・
+  `pre` / `code`・`hr`・`a`・`figure` / `figcaption`・`img` に、見出しの大きさ・余白・罫線が当たります。
+  要素に Tailwind のクラスを付ければ、そちらが優先されます。
+- **チャートを文中に置ける。** [`EChart`](parts/echart) をそのまま段落の間に置けます。
+- **PDF として保存。** 右下の「PDF として保存」ボタン（ブラウザの言語が日本語以外なら
+  「Save as PDF」）でブラウザの印刷ダイアログが開きます。紙に載るのはドキュメントの本文だけで、
+  アプリのヘッダーやサイドバーは載りません。
+- **ダークモードでもライトで印刷。** 印刷の間だけライトの配色に切り替え、チャートも描き直してから
+  印刷します。終われば元に戻ります。
+- **テーマに追従。** 配色・書体・本文の幅は `--doc-*` トークンで、既定はアプリのトークンを指します
+  （一覧は [UI とテーマ](ui-and-theming)）。
+
+## 制限
+
+- **PDF はブラウザの印刷機能で作ります。** Vantage が PDF ファイルを生成するわけではないので、
+  改ページの位置や余白はブラウザの印刷設定に従います。
+- 印刷ボタンは消せません。ドキュメントからの出口として、常に右下に出ます。
+- `.doc` を付けられるのはルートになる `.tsx` / `.jsx` だけです
+  （[ページにならないファイル](page-types)）。
+
+## API
+
+```tsx
+import { Document } from "@squadbase/vantage/doc";
+import type { DocumentTheme } from "@squadbase/vantage/doc";
+```
+
+### Document
+
+`<article>` の props（`className`・`style`・`id` など）もそのまま渡せます。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `theme` | `DocumentTheme` | このドキュメントだけ配色・書体を上書きする。省いた項目はアプリのテーマに従う。 |
+
+### DocumentTheme
+
+どれも CSS の値をそのまま書きます（`"#2563eb"`・`"16px"` など）。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `fg` | `string` | 本文の色。 |
+| `muted` | `string` | 引用・キャプションの色。 |
+| `accent` | `string` | リンクの色。 |
+| `border` | `string` | 罫線の色。 |
+| `subtle` | `string` | インラインコード・コードブロック・表の見出し行の背景。 |
+| `fontBody` | `string` | 本文の書体。 |
+| `fontHeading` | `string` | 見出しの書体。 |
+| `fontMono` | `string` | コードの書体。 |
+| `sizeBody` | `string` | 本文の文字サイズ。 |
+| `lineHeight` | `string` | 本文の行間。 |
+| `maxWidth` | `string` | 本文の幅。 |

package/docs/ja/page-types/excel.md

@@ -0,0 +1,82 @@
+# Excel
+
+> .xlsx を置くだけで表として読めるページになる。シートの切り替えと元ファイルのダウンロード付き。
+
+`.xlsx` を置くだけで、そのブックは**表として読めるページ**になります（`src/data/june.xlsx` →
+`/data/june`）。ビューアは [CSV](page-types/csv) と同じもので、下端のタブでシートを切り替えられます。
+
+## 置き方
+
+ページ走査のルート（`src/` があればその中）にファイルを置くだけです。タイトルはファイル名から
+作られます（`june.xlsx` → 「June」、`index.xlsx` はディレクトリ名）。名前を変えたいときは
+ファイルをリネームします。
+
+## できること
+
+- **シートを切り替える。** ブックに 2 枚以上シートがあれば、下端にシート名のタブが並びます。
+- **元ファイルをダウンロードする。** 右上のボタンで、置いた `.xlsx` そのものが落とせます。
+- **値として読める。** 日付のセルは日付として、数値は桁区切りで右寄せに表示されます。
+  そのほかの見た目・コピー・型の推定は [CSV](page-types/csv) と同じです。
+
+## 制限
+
+- **数式・グラフ・セル書式・結合セルは再現されません。** 表示されるのはセルの値だけです
+  （数式は計算結果の値）。見た目まで共有したいときはダウンロードしてもらいます。
+- **25MB を超えるブックは表示されず、20 万行を超えるシートは先頭 20 万行だけ**を表示します
+  （[CSV](page-types/csv) と同じ）。
+- パスワード付きや壊れたブックは、そのページにエラーが出ます。
+- **`.xls`・`.xlsm`・`.xlsb`・`.ods`・`.numbers` はページになりません**（`UNSUPPORTED_PAGE_FILE`
+  警告）。Excel で `.xlsx` として保存し直して置きます。
+- ページにしたくない `.xlsx` は `_` を前置します（`_june.xlsx`）。Excel が開いている間にできる
+  `~$june.xlsx` は無視されます。
+
+## 自分で描く
+
+タイトルを付けたいときは、`_` を前置してページになるのを止め、[CSV](page-types/csv) と同じく
+`FilePageView` に `kind="xlsx"` を渡します。
+
+ダッシュボードのカードの中に表だけを埋めたいときは、`loadWorkbook` でパースして `TableViewer` で
+描きます。`height` を渡すと、ビューポートの残りを埋めずにその高さに収まります。
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query";
+import { TableViewer, loadWorkbook } from "@squadbase/vantage/table";
+import src from "./_june.xlsx?url&no-inline";
+
+export function JuneTable() {
+  const { data } = useQuery({ queryKey: ["june.xlsx"], queryFn: () => loadWorkbook(src, "xlsx") });
+  const sheet = data?.sheets[0];
+  return sheet ? <TableViewer sheet={sheet} height={360} /> : null;
+}
+```
+
+## API
+
+```tsx
+import {
+  FilePageView, TableViewer, SheetGrid, loadWorkbook, toSheet,
+} from "@squadbase/vantage/table";
+```
+
+`FilePageView` の props は [CSV](page-types/csv) を参照してください。
+
+### TableViewer
+
+1 シートを枠付きで描きます。下端にシートのタブと行数・列数が出ます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `sheet` | `TableSheet` |  | 描くシート。`loadWorkbook` か `toSheet` で作る。 |
+| `sheetNames` | `string[]` |  | 全シートの名前。2 つ以上あるとタブが出る。 |
+| `activeSheet` | `number` | `0` | 選ばれているタブの位置。 |
+| `onSheetChange` | `(index: number) => void` |  | タブが押されたとき。 |
+| `height` | `number \| string` |  | 枠の高さ。省くとビューポートの残りを埋める。 |
+| `className` | `string` |  | 枠に足すクラス。 |
+
+### 関数
+
+| 名前 | 役割 |
+|---|---|
+| `loadWorkbook(src, kind)` | URL のファイルを取得してパースし、`{ sheets: TableSheet[] }` を返す。失敗は `FilePageError` で reject |
+| `toSheet(name, rows)` | 行の配列（1 行目がヘッダ）から `TableSheet` を作る。手元のデータを `TableViewer` で見せたいとき |
+| `SheetGrid` | グリッド本体だけ。高さの決まった親の中に置く |

package/docs/ja/page-types/slide.md

@@ -0,0 +1,132 @@
+# スライド
+
+> <name>.slide.tsx を置くとスライドデッキのページになる。1920×1080 のキャンバス、段階表示、トランジション、pptx 書き出し。
+
+`<name>.slide.tsx` を置くと、そのページは**スライドデッキ**になります（`src/june.slide.tsx` →
+`/june`）。分析の結論を誰かに伝えるときの形です。下のプレビューはクリックか `→` で送れます。
+
+## 置き方
+
+中身は `<SlideDeck>` を返す普通の React コンポーネントです。`<Slide>` 1 つが 1 枚になります。
+
+```tsx
+// src/june.slide.tsx  →  /june
+import { definePage } from "@squadbase/vantage";
+import { Slide, SlideDeck, Step, Steps } from "@squadbase/vantage/slide";
+
+export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" });
+
+export default function Deck() {
+  return (
+    <SlideDeck>
+      <Slide>
+        <h1 style={{ fontSize: 96 }}>売上は目標を 5% 上回った</h1>
+      </Slide>
+      <Slide>
+        <Steps>
+          <Step><p style={{ fontSize: 48 }}>1. 関東の既存顧客が +8%</p></Step>
+          <Step><p style={{ fontSize: 48 }}>2. 中部の新規開拓が立ち上がった</p></Step>
+        </Steps>
+      </Slide>
+    </SlideDeck>
+  );
+}
+```
+
+## できること
+
+- **画面サイズに合わせて縮小。** スライドは 1920×1080 の固定キャンバスに px で書き、表示先に
+  合わせて拡大縮小されます。ノート PC でもプロジェクターでも同じ見た目です。
+- **キーボードとクリックで送る。** `→` / `Space` / `PageDown` で次へ、`←` / `PageUp` で前へ、
+  `Home` / `End` で最初と最後へ。スライドの左右をクリックしても送れます。
+- **段階表示。** `<Steps>` の中の `<Step>` は、次へ進むたびに 1 つずつ現れます。
+- **トランジション。** `<Slide transition={…}>` で入り方を決めます。同じ `id` の
+  `<MorphElement>` を前後のスライドに置き `morph: true` にすると、その要素が連続して動きます。
+- **3 つの見え方。** 左にスライド一覧（`L` で開閉）、スライドのみ、全画面（`F`）。一覧の開閉と
+  今のページは URL（`?rail=` / `?p=`）に入るので、そのまま共有できます。`Esc` でデッキを抜けます。
+- **PowerPoint に書き出す。** ツールバーのボタンで、全スライドを `.pptx` として保存します。
+- **テーマに追従。** 配色と書体は `--slide-*` トークンで、既定はアプリのトークンを指すので
+  ダークモードにも追従します。デッキごとに `theme` で上書きできます。
+
+ダッシュボードの中に 16:9 の枠として埋め込むときは `<SlideDeck embedded>` にします
+（既定は画面全体を覆い、アプリのナビはその下に残ります）。
+
+## 制限
+
+- **pptx は画像で書き出されます。** 受け取り側にフォントが要らず日本語も崩れませんが、
+  PowerPoint で文字を検索・編集することはできません。
+- **発表者ノートや発表者用ウィンドウはありません。**
+- **スライドの中で `@squadbase/vantage/ui` を使わないでください。** UI キットはダッシュボード向けの
+  rem 単位なので、1920×1080 を縮小すると `text-sm` のボタンは実効 8px ほどになり読めません。
+- iframe の中など、ブラウザが全画面を許さない場所では全画面ボタンが出ません。
+- `.slide` を付けられるのはルートになる `.tsx` / `.jsx` だけです
+  （[ページにならないファイル](page-types)）。
+
+キャンバスの縦方向の予算・文字サイズの目安・pptx 書き出しが崩れる条件など、書き方の作法は同梱の
+**`vantage-slide` スキル**にあります（[エージェント Skill](agent-skills)）。
+
+## API
+
+```tsx
+import {
+  SlideDeck, Slide, Steps, Step, MorphElement,
+  useSlideNumber, useIsActiveSlide,
+} from "@squadbase/vantage/slide";
+```
+
+### SlideDeck
+
+デッキの器です。子に `<Slide>` を並べます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `theme` | `SlideTheme` |  | このデッキだけ配色・書体を上書きする。省いた項目はアプリのテーマに従う。 |
+| `embedded` | `boolean` | `false` | 画面全体を覆わず、ページの流れの中に 16:9 で置く。 |
+| `rail` | `boolean` | `!embedded` | スライド一覧を開いた状態で始めるか。読み手は `L` でいつでも切り替えられる。 |
+| `exportName` | `string` | `URL の最後のセグメント` | 書き出す pptx のファイル名（拡張子なし）。 |
+
+`SlideTheme` のキー: `bg`・`fg`・`accent`・`muted`・`fontDisplay`・`fontBody`（CSS の値）、
+`sizeHero`・`sizeBody`・`radius`（キャンバス上の px）。
+
+### Slide
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `transition` | `SlideTransition` | このスライドに入るときの動き。省くと切り替えは一瞬。 |
+
+`SlideTransition` は `duration`（ms、必須）・`easing`・`enter` / `exit`（Web Animations の
+`keyframes` を持つ）・`morph`（`true` か `{ duration, easing, delay }`）を持ちます。
+
+```tsx
+<Slide
+  transition={{
+    duration: 500,
+    enter: { keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+    morph: true,
+  }}
+>
+```
+
+### Steps / Step
+
+`<Steps>` の直下に置いた `<Step>` が、次へ進むたびに 1 つずつ現れます。前のスライドから戻ってきた
+ときは、すべて出た状態で表示されます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | `180` | `Step` に渡す。フェードインの長さ（ms）。 |
+
+### MorphElement
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `id` | `string` | 前後のスライドで同じ値を付けた要素どうしが、連続して動く。 |
+| `className` | `string` | 足すクラス。子が 1 つの HTML 要素ならそこへ、それ以外はラッパーの `<div>` へ付く。 |
+| `style` | `CSSProperties` | `className` と同じ要素に足すスタイル。 |
+
+### フック
+
+| 名前 | 返すもの |
+|---|---|
+| `useSlideNumber()` | `{ current, total }`。ページ番号のフッター用 |
+| `useIsActiveSlide()` | 今見えているスライドかどうか。入場アニメーションを始める合図に使う |

package/docs/ja/page-types.md

@@ -0,0 +1,47 @@
+# ページの種類
+
+> 通常ページ・スライド・ドキュメント・CSV・Excel の 5 種類。それぞれの置き方とできること、ページにならないファイル。
+
+Vantage のページは **5 種類**あります。どれもファイルを置くだけでページになり、URL の作り方は同じ
+です（[ファイルベースルーティング](routing)）。違うのは「何が描かれるか」だけです。
+
+| 種類 | 置き方 | できること |
+|---|---|---|
+| 通常ページ | `sales.tsx` | ダッシュボード。表・チャート・フィルタを自由に組む |
+| [スライド](page-types/slide) | `june.slide.tsx` | 発表用のスライドデッキ。段階表示・トランジション・pptx 書き出し |
+| [ドキュメント](page-types/doc) | `june-summary.doc.tsx` | 上から読む報告書。クラス無しで組版され、PDF として保存できる |
+| [CSV](page-types/csv) | `sales-export.csv` | ファイルを置くだけで表として読める |
+| [Excel](page-types/excel) | `june.xlsx` | CSV と同じ表ビューアに、シートの切り替えが付く |
+
+- **`.slide` / `.doc` と拡張子は URL に出ません。** `june.slide.tsx`・`june.csv`・`june.tsx` は
+  どれも `/june` です。同じ URL に 2 つ置くと `vantage check` が `ROUTE_CONFLICT` エラーを出します。
+- **ナビにも同格で並びます。** `vantage routes` と `useRoutes()` には 5 種類が区別なく出て、
+  `kind`（`"module"` / `"file"`）と `variant`（`"slide"` / `"doc"`）で見分けられます。
+- 通常ページ・スライド・ドキュメントは React コンポーネントなので
+  [`definePage`](pages-and-metadata) が効きます。CSV と Excel はファイル名がタイトルになります。
+
+どれにするか迷ったら、**繰り返し見に来る数字はダッシュボード、誰かに伝える結論はスライド、
+残しておく説明はドキュメント、受け取ったデータをそのまま見せたいなら CSV / Excel** です。
+
+## ページにならないファイル
+
+ページ走査のルート（`src/` があればその中）に置いても、次のファイルはページになりません。
+
+| ファイル | どうなるか |
+|---|---|
+| `.xls`・`.xlsm`・`.xlsb`・`.ods`・`.tsv`・`.numbers`・`.parquet` | ルートにならない。`vantage check` が `UNSUPPORTED_PAGE_FILE` 警告を出す |
+| `.md`・`.json`・`.txt` など | 何も言わずに無視される（コードから読む用途があるため） |
+| `_` で始まるファイル（`_draft.tsx`・`_june.xlsx`） | プライベート。`_layout` などの予約名を除き、ルートにならない |
+| `~$june.xlsx` | Excel が開いている間に作るロックファイル。無視される |
+| `components/`・`hooks/`・`lib/` の中のファイル | 走査されない（`server/`・`public/` も同じ） |
+
+ビューアの無い表計算ファイルは、404 にすらならず**黙って消えます**。ナビにも `vantage routes` にも
+出ないので、`vantage check` の警告が唯一の手がかりです。`.xlsx` か `.csv` に変換して置き直すか、
+`.tsx` のページから [`TableViewer`](page-types/excel) で描いてください。
+
+Markdown（`.md`）はページになりません。Markdown を見せたいときは `.tsx` のページで
+[`MarkdownRenderer`](markdown/markdown-renderer) に文字列を渡します。
+
+> [!WARNING]
+> `.slide` / `.doc` を付けられるのは**ルートになるページモジュール（`.tsx` / `.jsx`）だけ**です。
+> `_layout.slide.tsx` や `deck.slide.ts`、`notes.doc.css` は `INVALID_PAGE_VARIANT` エラーになります。