@squadbase/vantage 0.6.2-dev1.5aae04e → 0.6.2-dev1.81c1bbe

package/docs/ja/components.md

@@ -3,13 +3,15 @@
 > Vantage に同梱される shadcn/ui (Base UI) キットと、ダッシュボード用の複合コンポーネントのリファレンス。
 
 Vantage は **shadcn/ui** をそのまま同梱しています。インストールもコピーも不要で、import するだけで
-使えます。入り口は 3 つのサブパスで、**サイドバーもこの 3 つで区切ってあります**。
+使えます。入り口は 5 つのサブパスで、**サイドバーもこの 5 つで区切ってあります**（`/slide` と `/doc` は、スライドとドキュメントのページの中身に使う block 用です）。
 
 | サブパス | 中身 |
 | --- | --- |
 | [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ |
 | [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 |
 | [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） |
+| [`@squadbase/vantage/slide`](slide/slide-cover) | `.slide.tsx` の 1 枚の中身に置く block（表紙・要旨・KPI・グラフ・スコアカード・次の打ち手の 7 つ） |
+| [`@squadbase/vantage/doc`](doc/doc-report-header) | `.doc.tsx` の `<Document>` の中に並べる節・部品の block（8 つ） |
 
 ```tsx
 import { Button, Card, Badge } from "@squadbase/vantage/ui";
@@ -91,6 +93,13 @@ KPI は [`KpiCard`](parts/kpi-card)、増減は [`Delta`](parts/delta)（`compar
 Markdown 描画は Shiki の全言語文法を抱えており、`components` のバレルに混ぜるとビルド出力が
 10 MB 以上増えるため、意図的に分けてあります。
 
+## `@squadbase/vantage/slide` と `@squadbase/vantage/doc`
+
+[スライド](page-types/slide)と[ドキュメント](page-types/doc)のページに置く block です。`/components` とは別のサブパスで、`vantage add` のコピー対象にもなりません（import して使います）。
+
+- **slide**: 1 枚の `<Slide>` の中身（`<Slide>` 自体は持ちません）。[`SlideCover`](slide/slide-cover) / [`SlideExecSummary`](slide/slide-exec-summary) / [`SlideKpiHero`](slide/slide-kpi-hero) / [`SlideKpiGrid`](slide/slide-kpi-grid) / [`SlideChartInsight`](slide/slide-chart-insight) / [`SlideScorecardTable`](slide/slide-scorecard-table) / [`SlideNextActions`](slide/slide-next-actions)
+- **doc**: `<Document>` の中に並べる節や部品（`DocFigure` / `DocDataTable` / `DocCallout` は節の中に置く部品）。[`DocReportHeader`](doc/doc-report-header) / [`DocExecutiveSummary`](doc/doc-executive-summary) / [`DocKpiScorecard`](doc/doc-kpi-scorecard) / [`DocFigure`](doc/doc-figure) / [`DocDataTable`](doc/doc-data-table) / [`DocCallout`](doc/doc-callout) / [`DocKeyFindings`](doc/doc-key-findings) / [`DocActionItems`](doc/doc-action-items)
+
 ## 組み合わせる
 
 ```tsx

package/docs/ja/doc/doc-action-items.md

@@ -0,0 +1,49 @@
+# DocActionItems
+
+> 次にやること。内容・担当・期限・期待する効果・優先度。
+
+推奨する対応を並べるセクションです。内容・担当・期限・期待する効果・優先度を出します。既定の `table` は表、`asks` は読み手へのお願い（紹介・判断・採用など）を短い箇条書きにします。優先度は高・中・低の語だけで、バッジや色は付きません。
+
+```tsx
+import { DocActionItems } from "@squadbase/vantage/doc";
+import type { DocActionItemsProps, DocActionItem, DocActionPriority } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `action` は `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"推奨する対応"` | 見出しの文言。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `items` | `DocActionItem[]` |  | 対応。重要なものから。**必須**。 |
+| `items[].action` | `ReactNode` |  | やること。**必須**。 |
+| `items[].owner` | `string` |  | 担当。 |
+| `items[].due` | `string` |  | 期限。書いたまま出る（「2026-11-15」「11 月末」）。 |
+| `items[].impact` | `string` |  | 期待する効果（「解約率 −0.5pt」）。`table` だけに出る。 |
+| `items[].priority` | `"high" \| "medium" \| "low"` |  | 優先度。高・中・低の語で出る（高は太字）。`table` だけに出る。 |
+| `variant` | `"table" \| "asks"` | `"table"` | 表か、読み手へのお願いの箇条書きか。 |
+
+## 使い方
+
+```tsx
+import { Document, DocActionItems } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocActionItems
+    items={[
+      { action: "法人プランの導入支援を増員する", owner: "CS 部", due: "2026-11-15", impact: "解約率 −0.5pt", priority: "high" },
+      { action: "紹介プログラムの特典を見直す", owner: "マーケティング部", due: "11 月末", impact: "紹介経由の新規 +10 社", priority: "medium" },
+      { action: "料金ページの文言を改善する", owner: "プロダクト部", priority: "low" },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- `due` は書いたまま表示されます（「2026-11-15」「11 月末」）。値の無い担当・期限・効果は「—」になります。
+- `variant="asks"` は担当と「`due` まで」だけを添えます（例: 「（CS 部・11 月末 まで）」）。効果と優先度は出しません。
+- 印刷時、`asks` は項目 1 つごとにページをまたぎません。

package/docs/ja/doc/doc-callout.md

@@ -0,0 +1,38 @@
+# DocCallout
+
+> 本文の中の囲み。補足・示唆・注意・決定事項。
+
+読み手に見落とされたくない 1 点を囲んで示す block です。`role="note"` の `div` に、種類ごとの意味色の左罫線が付きます（決定事項は中立色）。種類は「注意」「示唆」のような語でも表示されるので、色だけに頼りません。飾りには使いません。
+
+```tsx
+import { DocCallout } from "@squadbase/vantage/doc";
+import type { DocCalloutProps, DocCalloutKind } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `children` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `kind` | `"note" \| "insight" \| "warning" \| "decision"` | `"note"` | 種類。補足 / 示唆 / 注意 / 決定事項。 |
+| `title` | `string` |  | 囲みの見出し（1 行）。渡すと「<種類の語>: <title>」と出る。省くと種類の語だけが出る。種類の語と同じ文字列を渡したときも 1 回だけ出る。 |
+| `children` | `ReactNode` |  | 本文。`string` なら段落になる。Markdown 文字列は解釈されない。**必須**。 |
+
+## 使い方
+
+```tsx
+import { Document, DocCallout } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocCallout kind="warning" title="9 月の数値は速報値">
+    10 月 10 日の確定で変わることがあります。
+  </DocCallout>
+</Document>
+```
+
+## 注意
+
+- 種類の語（「補足」「示唆」「注意」「決定事項」）は block が付けます。`title` にも同じ語を書くと重複するので、見出しの内容だけを書きます。
+- 印刷時は 1 ページに収まるよう、ページをまたぎません。

package/docs/ja/doc/doc-data-table.md

@@ -0,0 +1,60 @@
+# DocDataTable
+
+> 印刷物の表に要る注記つきの表。タイトル・単位・合計行・脚注・出典。
+
+印刷物の表に必要な要素を揃えた表です。タイトル、単位、右揃えの数値、合計行、強調行、脚注、出典を出します。素の `table` なので、スタイルと印刷時の行の分割回避は `<Document>` が担います（並べ替えやスクロールが要る画面向けの表は `DataTable`）。
+
+```tsx
+import { DocDataTable } from "@squadbase/vantage/doc";
+import type { DocDataTableProps, DocTableColumn, DocTableRow, DocTableCell } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 セルは文字列か数値で、`ReactNode` は渡せません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 表のタイトル（表の上のキャプション）。 |
+| `unit` | `string` | 単位・スケール（「単位: 百万円」）。タイトルがあれば「（単位: 百万円）」と続く。 |
+| `columns` | `DocTableColumn[]` | 列（`{ key; label; format?: ValueFormat; align?: "left" \| "right" \| "center" }`）。`format` を省くと桁区切りの数値。`align` を省くと数値の列は右揃え、それ以外は左揃え。**必須**。 |
+| `rows` | `DocTableRow[]` | 行。`columns` の `key` を持つオブジェクト。セルは文字列か数値（`null` / `undefined` / 空文字は「—」）。**必須**。 |
+| `total` | `DocTableRow` | 合計行（`tfoot`）。`rows` と同じキーで書く。 |
+| `highlightRows` | `number[]` | 太字にする行の index（0 始まり、`rows` の添字）。 |
+| `footnotes` | `{ mark: string; text: string }[]` | 脚注。セルの文字列に同じ `mark`（「※1」）を書くと対応する。 |
+| `source` | `string` | 出典。キャプションに「出典: …」と出る。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+
+## 使い方
+
+```tsx
+import { Document, DocDataTable } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocDataTable
+    title="部門別の売上"
+    unit="単位: 百万円"
+    columns={[
+      { key: "dept", label: "部門" },
+      { key: "sales", label: "売上", format: "number" },
+      { key: "share", label: "構成比", format: { type: "percent", digits: 1 } },
+    ]}
+    rows={[
+      { dept: "法人営業", sales: 312, share: 0.58 },
+      { dept: "パートナー", sales: 148, share: 0.27 },
+      { dept: "オンライン ※1", sales: 80, share: 0.15 },
+    ]}
+    total={{ dept: "合計", sales: 540, share: 1 }}
+    highlightRows={[0]}
+    footnotes={[{ mark: "※1", text: "9 月から集計対象に追加" }]}
+    source="会計システム"
+    asOf="2026-10-03"
+  />
+</Document>
+```
+
+## 注意
+
+- 数値は `tabular-nums` で桁が揃い、値が無いセルは「—」になります。
+- 印刷時は行ごとにページをまたぎません。長い表は行の間で改ページされ、キャプション（脚注・出典）は 1 ページにまとまります。

package/docs/ja/doc/doc-executive-summary.md

@@ -0,0 +1,64 @@
+# DocExecutiveSummary
+
+> 結論を先に書く要旨。結論 1 文、要点 3〜5 個、任意で主要な数字。
+
+結論を先に書く（BLUF）要旨のセクションです。結論の 1 文、番号付きの要点 3〜5 個、任意で最大 3 つの主要な数字を出します。数字の増減は渡した `delta` の符号から向きを決め、▲▼ と符号を必ず出すので、色が見えなくても向きが分かります。
+
+```tsx
+import { DocExecutiveSummary } from "@squadbase/vantage/doc";
+import type { DocExecutiveSummaryProps, DocSummaryMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `conclusion` と `points` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"要旨"` | 見出しの文言。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `conclusion` | `ReactNode` |  | 結論を 1 文で。太字で出る。**必須**。 |
+| `points` | `ReactNode[]` |  | 裏付ける要点。3〜5 個、重要な順。番号付きで出る。**必須**。 |
+| `metrics` | `DocSummaryMetric[]` |  | 主要な数字（最大 3、超えた分は無視）。 |
+| `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"`。色は良し悪しだけを足す。 |
+
+## 使い方
+
+```tsx
+import { Document, DocExecutiveSummary } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocExecutiveSummary
+    conclusion="9 月の売上は計画を上回ったが、新規獲得は目標に届いていない。"
+    points={[
+      "売上は 5,390 万円で、計画比 +3.7%。",
+      "解約率は 1.8% まで下がり、3 か月連続で改善。",
+      "新規獲得は 38 社で、目標の 50 社に未達。",
+    ]}
+    metrics={[
+      { label: "売上", value: 53_900_000, format: "currency", delta: { value: 3_700_000 }, comparisonLabel: "前月比" },
+      {
+        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",
+      },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- 下がることが良い指標は `betterWhen: "down"` にします（色の良し悪しが反転します。▲▼ と符号は実際の向きのままです）。
+- `delta` は比較値ではなく増減そのものです。比率の指標（解約率など）は、例のように `format` で `pt` 表記にすると相対変化と読み違えません。
+- 印刷時は、要点 1 つごと・主要な数字のタイル 1 つごとがページをまたぎません。セクション全体は途中で改ページされることがあります。

package/docs/ja/doc/doc-figure.md

@@ -0,0 +1,56 @@
+# DocFigure
+
+> 図の約束事を 1 か所に。主張のタイトル、単位、図、出典つきのキャプション。
+
+図の約束事をまとめた block です。主張を書いたタイトル、単位、チャート（`children`）、出典と注記のキャプションを `figure` / `figcaption` で組みます。チャートは自由で、型付きグラフでも `EChart` でも画像でも構いません。出典と時点が無い数字は未完成として、`source` と `asOf` を最初から用意しています。
+
+```tsx
+import { DocFigure } from "@squadbase/vantage/doc";
+import type { DocFigureProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `children` はチャート（`ReactNode`）です。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 図が示す主張を文で（「解約率は 2 か月連続で低下」）。主題（「解約率の推移」）にしない。**必須**。 |
+| `unit` | `string` | 単位・スケール（「単位: %」）。タイトルの直下に出る。定義や但し書きは `notes` に書く。 |
+| `number` | `number` | 図の番号。キャプションに「図 N」と出る。 |
+| `source` | `string` | データの出どころ。キャプションに「出典: …」と出る。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+| `notes` | `string[]` | 注記・定義。1 行 1 件。 |
+| `children` | `ReactNode` | チャート。列の全幅を使う。**必須**。 |
+
+## 使い方
+
+```tsx
+import { Document, DocFigure } from "@squadbase/vantage/doc";
+import { EChart, type EChartsOption } from "@squadbase/vantage/components";
+
+const option: EChartsOption = {
+  xAxis: { type: "category", data: ["7 月", "8 月", "9 月"] },
+  yAxis: { type: "value" },
+  series: [{ type: "line", data: [2.4, 2.1, 1.8] }],
+};
+
+<Document>
+  <DocFigure
+    number={1}
+    title="解約率は 2 か月連続で低下"
+    unit="単位: %"
+    source="課金システム"
+    asOf="2026-10-03"
+    notes={["解約率は、月初の契約数に対するその月の解約数の割合。"]}
+  >
+    <EChart option={option} height={240} ariaLabel="解約率の推移（7〜9 月）" />
+  </DocFigure>
+</Document>
+```
+
+## 注意
+
+- `children` のチャートには `title` を付けません。タイトルは `DocFigure` の `title` に書きます。チャートの読み上げ名が要るときは `ariaLabel` を使います。
+- 図は印刷時に 1 ページに収まるよう、ページをまたぎません。

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-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/parts/area-chart.md

@@ -9,50 +9,74 @@
 
 ```tsx
 import { AreaChart } from "@squadbase/vantage/components";
-import type { AreaChartProps, ChartColor, ChartEventPayload } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
-| `index` | `string` |  | x 軸に使う列名。**必須**。 |
-| `categories` | `string[]` |  | 系列として描く列名。**必須**。この順が凡例と配色の順になる。 |
-| `colors` | `ChartColor[]` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か CSS カラー。足りなければ繰り返す。 |
-| `valueFormatter` | `(value: number) => string` |  | 値軸の目盛りとツールチップの書式。既定は 3 桁区切り。 |
-| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` は積み上げ、`percent` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
-| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
-| `connectNulls` | `boolean` | `false` | 欠損した点をまたいで線をつなぐ。 |
-| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
-| `showLegend` | `boolean` | `true` | 右上に凡例を出す。 |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `keyof T & string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `NumericKeys<T>[]` |  | 系列として描く列名（数値の列だけ渡せる）。**必須**。この順が凡例と配色の順。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `トークン順` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`。配列は系列の順、record は系列名ごと。CSS カラーは渡せない。 |
+| `labels` | `Record<string, string>` |  | `index` の値・系列名 → 表示名（軸・凡例・ツールチップ・データ表に反映）。例 `{ jan: "1 月", sales: "売上" }`。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、または `{ type, digits, currency, notation, unit, divisor, durationUnit }`。軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `areaOptions` | `AreaChartOptions` |  | 面グラフ固有の設定。`{ type, curveType, fill, connectNulls }`（下の表）。 |
+| `forecast` | `{ data: ChartForecastRow[]; category?: string; label?: string }` |  | 予測。最初の系列（または `category`）の続きを点線と薄い帯で描く。`data` の行は実績と同じ `index` のキーに、`value`（と任意の `lower` / `upper`）を持つ。`label` の既定は「予測」。 |
+| `comparison` | `{ category: string; vs: "prior-period" \| "prior-year" \| "target" \| "custom"; label?: string }` |  | 比較系列。`categories` のうち 1 つを「前年」「計画」などの比較の線にする（細い灰色の実線）。ツールチップに主系列の差を添える。`vs: "custom"` では `label` が必須。 |
+| `highlight` | `"auto" \| "none"` |  | 最大値と最新値に値ラベルを付ける（最初の系列だけ・系列が 2 つ以下のときだけ）。既定は Line / Area が `"auto"`、Bar は `index` が日付・年月・年のときだけ `"auto"`。 |
+| `provisionalFrom` | `string \| number` |  | ここから先は確定前（速報）の点。`index` の値で渡す。薄い色・点線で描き、凡例とツールチップに `provisionalLabel` を出す。 |
+| `provisionalLabel` | `string` | `"速報"` | 速報の呼び名（凡例・ツールチップ）。 |
+| `target` | `number` |  | 目標値。点線の水平線で示し、値軸は必ずこの値を含む。 |
+| `targetLabel` | `string` | `「目標 <書式化した値>」` | 目標線のラベル。 |
+| `annotations` | `ChartAnnotation[]` |  | 任意の位置への注記。`{ at, label }` は縦線、`to` を足すと `at`〜`to` の区間の帯。`at` / `to` は `index` の値。横棒では描かない。 |
+| `showLegend` | `boolean` | `true` | 凡例を出す。 |
 | `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
 | `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
 | `showXAxis` | `boolean` | `true` | x 軸を出す。 |
 | `showYAxis` | `boolean` | `true` | y 軸を出す。 |
 | `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
 | `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
-| `minValue` | `number` |  | 値軸の下限。 |
-| `maxValue` | `number` |  | 値軸の上限。 |
-| `autoMinValue` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
-| `allowDecimals` | `boolean` | `true` | `false` で目盛りを整数に限る。 |
+| `minValue` | `number` |  | 値軸の下限。常に 0 起点なので、0 以下の値だけ有効（負の値の下に余白を取る）。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
 | `xAxisLabel` | `string` |  | x 軸の名前。 |
 | `yAxisLabel` | `string` |  | y 軸の名前。 |
-| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
-| `height` | `string \| number` |  | 高さ。数値は px。省略時は `h-80`（320px）。`className` の高さクラスでも決められる。 |
-| `loading` | `boolean` |  | ローディング表示を出す。 |
-| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
-| `className` | `string` |  | 足すクラス。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点（棒）のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。見出しの下に出す。`"auto"` なら data から機械的に組む。向きの言い回しを手書きすると data とずれるので `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。`title` の既定は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列（CSS の長さ）は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。`title` / `summary` は画像の上に含まれる。含めないなら `{ includeTitle: false }`。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。`actions` と使う。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。見出しがあればそちらが使われる。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは `height` で決める。 |
+
+### areaOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `"stacked"` は積み上げ、`"percent"` は各点の合計を 100% にした積み上げ（ツールチップは元の値）。 |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | 面の塗り。 |
+| `connectNulls` | `boolean` | `false` | 値の欠けた点（`null` など）をまたいで線をつなぐ。 |
+
+> [!NOTE]
+> `type` / `curveType` / `fill` / `connectNulls` をグラフの props に直接渡す書き方と、`autoMinValue`・`loading` は**非推奨**です（`areaOptions.*` と `isLoading` を使う。面グラフは常に 0 起点で `autoMinValue` は無視されます）。
 
 > [!NOTE]
-> `colors` は Tailwind のクラスではなく**色の値**です（キャンバスに描くため）。`"chart-2"` のような
-> トークン名ならライト / ダークに追従します。軸・凡例・ツールチップの色はいつもテーマから入ります。
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
 
 ## 構成比の推移を見る
 
-`type="percent"` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
-ツールチップには**元の値**が `valueFormatter` で出ます。
+`areaOptions={{ type: "percent" }}` にすると、各点の合計を 100% として積み上げます。値軸は 0〜100% に固定され、
+ツールチップには**元の値**が `format` / `valueFormatter` の書式で出ます。
 
 ```tsx
-<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} type="percent" />
+<AreaChart data={rows} index="month" categories={["オンライン", "店舗"]} areaOptions={{ type: "percent" }} />
 ```
 
 ## EChart との使い分け