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

package/docs/ja/doc/doc-key-findings.md

@@ -0,0 +1,61 @@
+# DocKeyFindings
+
+> 分析で分かったこと 3〜5 件。結論の見出し、根拠、任意の数字。
+
+「分かったこと」のセクションです。結論を書いた見出し、その下に根拠、任意で数字を 1 つ添えた発見を 3〜5 件並べます。各発見は番号付きの `h3` です。数字の増減は渡した `delta` の符号から向きを決め、▲▼ と符号を必ず出します。
+
+```tsx
+import { DocKeyFindings } from "@squadbase/vantage/doc";
+import type { DocKeyFindingsProps, DocFinding, DocFindingMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `evidence` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"主要な発見"` | セクションの見出し。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `findings` | `DocFinding[]` |  | 発見（`{ headline: string; evidence: ReactNode; metric?: DocFindingMetric }`）。3〜5 件、重要な順。**必須**。 |
+| `findings[].metric` | `DocFindingMetric` |  | 発見に添える数字 1 つ。以下のフィールドを持つ。 |
+| `findings[].metric[].label` | `string` |  | 指標の名前。 |
+| `findings[].metric[].value` | `number \| null` |  | 値。`null` は「—」。 |
+| `findings[].metric[].format` | `ValueFormat` |  | `value` の書式（`"currency"`、`{ type: "percent", digits: 1 }` など）。 |
+| `findings[].metric[].display` | `string` |  | 渡すと値の代わりにこの文字列を出す（「約 5,400 万円」）。 |
+| `findings[].metric[].delta` | `{ value: number; format?: ValueFormat }` |  | 比較先からの増減そのもの（現在値 − 比較値）。向きは符号で決まり、▲▼ と符号を必ず出す。省くと比較を出さない。`format` を省くと指標の `format` を使う。 |
+| `findings[].metric[].comparisonLabel` | `string` | `"前期比"` | 比較の名前（「前月比」）。 |
+| `findings[].metric[].betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率やコストは `"down"`。色は良し悪しだけを足す。 |
+
+## 使い方
+
+```tsx
+import { Document, DocKeyFindings } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocKeyFindings
+    findings={[
+      {
+        headline: "新規契約は法人プランが牽引した",
+        evidence: "法人プランの新規が前月比 +20%（20 社 → 24 社）。個人プランは横ばいだった。",
+        metric: { label: "法人プランの新規", value: 24, format: { type: "number", unit: "社" }, delta: { value: 4 }, comparisonLabel: "前月比" },
+      },
+      {
+        headline: "解約は導入 3 か月以内に集中している",
+        evidence: "解約の 62% が導入から 3 か月以内で、オンボーディングが分かれ目になっている。",
+      },
+      {
+        headline: "紹介経由の契約は定着率が高い",
+        evidence: "紹介経由で入った契約の 6 か月継続率は 91% で、広告経由の 74% を上回った。",
+      },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- `headline` は話題ではなく、判断を含む文で書きます（「解約は法人プランに集中している」）。`headingLevel={3}` のときは発見が `h4` になります。
+- `evidence` の文中の数字と `metric` の数字は食い違わないようにします（`delta` は増減そのもので、比率は自動では出ません）。
+- 印刷時は発見 1 件ごとにページをまたぎません。

package/docs/ja/doc/doc-kpi-scorecard.md

@@ -0,0 +1,80 @@
+# DocKpiScorecard
+
+> 主要指標の一覧。実績・前期比・目標との差・推移。
+
+主要指標を 1 か所にまとめるセクションです。実績、前期からの増減、目標に対する達成率、小さな推移を出します。既定の `table` は印刷に向き、`grid` は 3〜6 個の指標を `dl` のタイルで見せます。増減の向きは `delta` の符号、達成率は `value ÷ target` から block が計算します。
+
+```tsx
+import { DocKpiScorecard } from "@squadbase/vantage/doc";
+import type { DocKpiScorecardProps, DocScorecardMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `asOf` と `source` は block の下の 1 行に出ます。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"主要指標"` | 見出しの文言。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `metrics` | `DocScorecardMetric[]` |  | 指標。**必須**。 |
+| `metrics[].label` | `string` |  | 指標の名前。 |
+| `metrics[].value` | `number \| null` |  | 値。`null` は「—」。 |
+| `metrics[].format` | `ValueFormat` |  | `value` の書式（`"currency"`、`{ type: "percent", digits: 1 }` など）。 |
+| `metrics[].display` | `string` |  | 渡すと値の代わりにこの文字列を出す（「約 5,400 万円」）。 |
+| `metrics[].delta` | `{ value: number; format?: ValueFormat }` |  | 比較先からの増減そのもの（現在値 − 比較値）。向きは符号で決まり、▲▼ と符号を必ず出す。省くと比較を出さない。`format` を省くと指標の `format` を使う。 |
+| `metrics[].comparisonLabel` | `string` | `"前期比"` | 比較の名前（「前月比」）。 |
+| `metrics[].betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率やコストは `"down"`。色は良し悪しだけを足す。 |
+| `metrics[].target` | `number` |  | 期間の目標。`value` と同じ `format` で出し、達成率（value ÷ target）はここで計算する。 |
+| `metrics[].trend` | `{ x: string; y: number }[]` |  | 時系列 1 本（古い順、最後が現在値）。`value` と同じ単位で渡す。省くと「—」。2 点以上で `Sparkline` を描く。 |
+| `variant` | `"table" \| "grid"` | `"table"` | 表か、タイルか。 |
+| `asOf` | `string` |  | 数字を取った日。日付だけを書く（「2026-10-03」）。block の下の 1 行に「データ時点 …」と出る。 |
+| `source` | `string` |  | 出典。block の下の 1 行に「出典: …」と出る。 |
+
+## 使い方
+
+```tsx
+import { Document, DocKpiScorecard } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocKpiScorecard
+    asOf="2026-10-03"
+    source="会計システム"
+    metrics={[
+      {
+        label: "売上",
+        value: 53_900_000,
+        format: "currency",
+        delta: { value: 3_700_000 },
+        comparisonLabel: "前月比",
+        target: 52_000_000,
+        trend: [
+          { x: "5 月", y: 48_000_000 },
+          { x: "6 月", y: 49_000_000 },
+          { x: "7 月", y: 50_000_000 },
+          { x: "8 月", y: 50_200_000 },
+          { x: "9 月", y: 53_900_000 },
+        ],
+      },
+      {
+        label: "解約率",
+        value: 0.018,
+        format: { type: "percent", digits: 1 },
+        delta: { value: -0.003, format: { type: "number", digits: 1, unit: "pt", divisor: 0.01 } },
+        comparisonLabel: "前月比",
+        betterWhen: "down",
+        target: 0.02,
+      },
+      { label: "新規獲得", value: 38, format: { type: "number", unit: "社" }, delta: { value: -4 }, comparisonLabel: "前月比", target: 50 },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- 解約率やコストのように下がることが良い指標は `betterWhen: "down"`。値が無いセルは「—」になります。
+- `target` と `trend` の `y` は `value` と同じ単位で渡します（`value` が円なら円）。`target` は指標の `format` で出ます。
+- 表の「比較」列の見出しは、指標のうち最初に `comparisonLabel` を持つものの値で、どれも持たないと「前期比」です。列は 1 つなので、指標ごとに違う比較名にするなら `variant="grid"` を使います。
+- 印刷時、`table` は行ごと、`grid` はタイル 1 つごとにページをまたぎません。

package/docs/ja/doc/doc-notes-and-sources.md

@@ -0,0 +1,43 @@
+# DocNotesAndSources
+
+> ドキュメント末尾の注記・用語の定義・出典。
+
+ドキュメントの最後に置く節です。注記（番号つき）、用語の定義、出典（データ時点つき）をまとめて出します。中身のない部分は描かれず、3 つとも空なら何も出ません。
+
+```tsx
+import { DocNotesAndSources } from "@squadbase/vantage/doc";
+import type { DocNotesAndSourcesProps, DocDefinition, DocSource } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に置く 1 セクション**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。Markdown 文字列は解釈されません。ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"注記・出典"` | 節の見出し。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しの階層。`<Document>` 直下なら `2`、別の節の中なら `3`。小見出しは 1 つ下がる。 |
+| `notes` | `ReactNode[]` |  | 注記。番号つきの一覧で出る（速報値・除外条件など）。 |
+| `definitions` | `DocDefinition[]` |  | 用語の定義。`{ term: string; description: ReactNode }`。 |
+| `sources` | `DocSource[]` |  | 出典。`{ name: string; asOf?: string }`。`asOf` は日付のみ（例: `"2026-10-03"`）で、「（データ時点 2026-10-03）」と出る。 |
+
+## 使い方
+
+```tsx
+import { Document, DocNotesAndSources } from "@squadbase/vantage/doc";
+
+<Document>
+  {/* …本文の節… */}
+  <DocNotesAndSources
+    notes={["9 月の数値は速報値です。確定値は 10 月 10 日に更新します。", "返金分は売上から除いています。"]}
+    definitions={[{ term: "解約率", description: "月初契約数に対する、当月に解約した契約数の割合。" }]}
+    sources={[{ name: "契約管理 DB", asOf: "2026-10-03" }, { name: "会計システム" }]}
+  />
+</Document>
+```
+
+## 注意
+
+- 小見出し「注記」「用語の定義」「出典」と「（データ時点 …）」は固定の日本語です。
+- 各部分は印刷時に途中で改ページされないようにまとまります。

package/docs/ja/doc/doc-report-header.md

@@ -0,0 +1,46 @@
+# DocReportHeader
+
+> ドキュメントの冒頭。タイトル、サブタイトル、期間・時点・作成者・出典。
+
+ドキュメントの冒頭に置くセクションです。`h1` のタイトルと、期間・データ時点・作成者・出典の短い事実表（`dl`）を出します。`h1` を持つのはこの block だけで、以降のセクションは `h2` から始まります。
+
+```tsx
+import { DocReportHeader } from "@squadbase/vantage/doc";
+import type { DocReportHeaderProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `subtitle` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | ドキュメントの題（`h1`）。対象と期間を書き、スローガンにしない。**必須**。 |
+| `subtitle` | `ReactNode` | 題の下の 1 行（誰向けか、など）。`string` か `ReactNode`。 |
+| `period` | `string` | 数字の対象期間（「2026 年 9 月」「2026-07-01 〜 2026-09-30」）。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+| `author` | `string` | 作成者。 |
+| `source` | `string` | 数字の出どころ（「受注管理システム、会計システム」）。1 つの文字列で書く。 |
+
+## 使い方
+
+```tsx
+import { Document, DocReportHeader } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocReportHeader
+    title="2026 年 9 月 月次事業報告"
+    subtitle="経営会議向け"
+    period="2026-09-01 〜 2026-09-30"
+    asOf="2026-10-03"
+    author="事業企画チーム"
+    source="受注管理システム、会計システム"
+  />
+</Document>
+```
+
+## 注意
+
+- 空の項目は「—」ではなく、行ごと省かれます。
+- 印刷時はヘッダー全体が 1 ページに収まるよう、ページをまたぎません。

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,133 @@
+# スライド
+
+> <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` として保存します。
+- **日本語の改行。** ルート `_layout.tsx` に `export const lang = "ja"` を書くと、見出しが文節の途中で折れず、ツールバーも日本語になります（[アプリの表示言語](pages-and-metadata)）。
+- **テーマに追従。** 配色と書体は `--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()` | 今見えているスライドかどうか。入場アニメーションを始める合図に使う |