@squadbase/vantage 0.6.2-dev1.42c4e48 → 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";
@@ -30,6 +32,7 @@ import { MarkdownRenderer } from "@squadbase/vantage/markdown";
 | [`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 つの値として扱う。 |
+| [`KpiCard`](parts/kpi-card) / [`Delta`](parts/delta) / [`MetricValue`](parts/metric-value) | KPI のタイル 1 枚なら `KpiCard`（値・増減・前期実績・結論の 1 文まで出る）。表のセルや見出しの横に**増減だけ**を置くなら `Delta`。`MetricValue` は書式を自分で決めた数値を大きく見せたいときだけ。`TrendIndicator` は非推奨。 |
 | [`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` に再試行ボタンを置ける）。 |
@@ -77,8 +80,12 @@ shadcn/ui のプリミティブです。名前も props も shadcn/ui のもの
 
 `ui/` を組み上げた、ダッシュボード向けの複合部品です。ページ枠（`PageShell` / `AppShell`）、
 タイル（`DashboardCard`）、表（`DataTable`）、グラフ（`EChart` / `Sparkline` / `FunnelSteps`）、
-フィルタ（`FilterBar` / `DateRangePicker` など）、KPI 表示（`MetricValue` / `TrendIndicator`）が
-入っています。
+フィルタ（`FilterBar` / `DateRangePicker` など）、KPI 表示が入っています。部品の正本は SquadKit で、
+Vantage はそれを再エクスポートしています。
+
+KPI は [`KpiCard`](parts/kpi-card)、増減は [`Delta`](parts/delta)（`comparison` と
+`polarity` を渡す）で示します。[`TrendIndicator`](parts/trend-indicator) は非推奨です。数値の
+書式と増減の計算は [format / comparison](parts/format) にまとまっています。
 
 ## `@squadbase/vantage/markdown`
 
@@ -86,6 +93,13 @@ shadcn/ui のプリミティブです。名前も props も shadcn/ui のもの
 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
@@ -99,9 +113,8 @@ import {
   PageShellHeaderEnd,
   PageShellActions,
   PageShellContent,
+  KpiCard,
   DashboardCardPreset,
-  MetricValue,
-  TrendIndicator,
   EChart,
   type EChartsOption,
 } from "@squadbase/vantage/components";
@@ -129,17 +142,25 @@ export default function Overview() {
 
       <PageShellContent>
         <div className="grid gap-4 md:grid-cols-3">
-          <DashboardCardPreset title="売上">
-            <MetricValue className="my-0">¥1,240,000</MetricValue>
-            <TrendIndicator value={12.4} direction="up" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="新規顧客">
-            <MetricValue className="my-0">128</MetricValue>
-            <TrendIndicator value={3.1} direction="down" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="解約率">
-            <MetricValue className="my-0">2.1%</MetricValue>
-          </DashboardCardPreset>
+          <KpiCard
+            label="売上"
+            value={1_240_000}
+            format="currency"
+            comparison={{ previous: 1_103_000, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="新規顧客"
+            value={128}
+            format="number"
+            comparison={{ previous: 132, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="解約率"
+            value={0.021}
+            format={{ type: "percent", digits: 1 }}
+            comparison={{ previous: 0.026, vs: "prior-period" }}
+            polarity="lower-is-better"
+          />
         </div>
 
         <DashboardCardPreset title="月次売上" className="mt-4">

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 ページに収まるよう、ページをまたぎません。