@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.81c1bbe

package/dist/vite/index.js

@@ -1,5 +1,5 @@
-export { vantagePlugin } from '../chunk-IBGOCWJB.js';
-import '../chunk-QEWCYW3I.js';
+export { vantagePlugin } from '../chunk-2ICNHUG6.js';
+import '../chunk-WAMZWZJB.js';
 import '../chunk-CEXAQQ5W.js';
 import '../chunk-RNTDBX6S.js';
 import '../chunk-46QI6GFC.js';

package/docs/en/components.md

@@ -2,14 +2,16 @@
 
 > Reference for the bundled shadcn/ui (Base UI) kit and the composite dashboard components.
 
-Vantage ships **shadcn/ui** as-is. Nothing to install, nothing to copy — just import. There are three
-public entry points, and **the sidebar is sectioned by those three**.
+Vantage ships **shadcn/ui** as-is. Nothing to install, nothing to copy — just import. There are five
+public entry points, and **the sidebar is sectioned by those five** (`/slide` and `/doc` hold the blocks for slide and document pages).
 
 | Subpath | What's in it | Count |
 | --- | --- | --- |
 | [`@squadbase/vantage/ui`](ui/button) | The shadcn/ui primitives (Base UI build) plus utilities like `cn()` | 37 |
 | [`@squadbase/vantage/components`](parts/page-shell) | Dashboard parts composed from them | 15 |
 | [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown rendering alone (kept apart — it's heavy) | 1 |
+| [`@squadbase/vantage/slide`](slide/slide-cover) | Blocks for the content of one slide in a `.slide.tsx` (7: cover, summary, KPI, chart, scorecard, next actions) | 7 |
+| [`@squadbase/vantage/doc`](doc/doc-report-header) | Section and part blocks placed inside `<Document>` in a `.doc.tsx` | 8 |
 
 ```tsx
 import { Button, Card, Badge } from "@squadbase/vantage/ui";
@@ -113,7 +115,12 @@ here they're grouped by what they're for.
 
 ## `@squadbase/vantage/components`
 
-Dashboard parts composed from `ui/`.
+Dashboard parts composed from `ui/`. Their source of truth is SquadKit; Vantage re-exports them.
+
+Show a KPI with [`KpiCard`](parts/kpi-card) and a change with
+[`Delta`](parts/delta) (pass `comparison` and `polarity`).
+[`TrendIndicator`](parts/trend-indicator) is deprecated. Number formatting and the
+change calculation live in [format / comparison](parts/format).
 
 | Component | What it is |
 | --- | --- |
@@ -130,8 +137,10 @@ Dashboard parts composed from `ui/`.
 | [`SegmentedControl`](parts/segmented-control) | Single-choice segments |
 | [`SearchableSelect`](parts/searchable-select) | Single choice with search |
 | [`MultiSelect`](parts/multi-select) | Multiple choice with search |
+| [`KpiCard`](parts/kpi-card) | One KPI as a card: value, change, previous actual, conclusion |
+| [`Delta`](parts/delta) | The change against a comparison, derived from the values |
 | [`MetricValue`](parts/metric-value) | A KPI's number and unit |
-| [`TrendIndicator`](parts/trend-indicator) | An arrow and a percentage |
+| [`TrendIndicator`](parts/trend-indicator) | Deprecated — use `Delta` |
 | [`StatusBadge`](parts/status-badge) | A dot-and-label status badge |
 | [`Placeholder`](parts/placeholder) | An inline marker for sample data |
 
@@ -141,6 +150,13 @@ A subpath holding only [`MarkdownRenderer`](markdown/markdown-renderer). Markdow
 rendering carries Shiki with every language grammar; mixed into the `components` barrel it would add
 over 10 MB to every build, so it is deliberately kept apart.
 
+## `@squadbase/vantage/slide` and `@squadbase/vantage/doc`
+
+Blocks for [slide](page-types/slide) and [document](page-types/doc) pages. They live on their own subpaths, apart from `/components`, and `vantage add` does not copy them — import and use them.
+
+- **slide**: the content of one `<Slide>` (not `<Slide>` itself). [`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**: sections and parts placed inside `<Document>` (`DocFigure` / `DocDataTable` / `DocCallout` go inside a section). [`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)
+
 ## Putting it together
 
 ```tsx
@@ -154,9 +170,8 @@ import {
   PageShellHeaderEnd,
   PageShellActions,
   PageShellContent,
+  KpiCard,
   DashboardCardPreset,
-  MetricValue,
-  TrendIndicator,
   EChart,
   type EChartsOption,
 } from "@squadbase/vantage/components";
@@ -184,17 +199,25 @@ export default function Overview() {
 
       <PageShellContent>
         <div className="grid gap-4 md:grid-cols-3">
-          <DashboardCardPreset title="Revenue">
-            <MetricValue className="my-0">$12,400</MetricValue>
-            <TrendIndicator value={12.4} direction="up" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="New customers">
-            <MetricValue className="my-0">128</MetricValue>
-            <TrendIndicator value={3.1} direction="down" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="Churn">
-            <MetricValue className="my-0">2.1%</MetricValue>
-          </DashboardCardPreset>
+          <KpiCard
+            label="Revenue"
+            value={1_240_000}
+            format="currency"
+            comparison={{ previous: 1_103_000, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="New customers"
+            value={128}
+            format="number"
+            comparison={{ previous: 132, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="Churn"
+            value={0.021}
+            format={{ type: "percent", digits: 1 }}
+            comparison={{ previous: 0.026, vs: "prior-period" }}
+            polarity="lower-is-better"
+          />
         </div>
 
         <DashboardCardPreset title="Monthly revenue" className="mt-4">

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

@@ -0,0 +1,49 @@
+# DocActionItems
+
+> What to do next — action, owner, due date, expected effect and priority.
+
+The recommendations section: action, owner, due date, expected effect and priority. The default `table` is a table; `asks` is a short bulleted list of requests to the reader (introductions, a decision, a hire). Priority is only the word 高 / 中 / 低, with no badge and no colour.
+
+```tsx
+import { DocActionItems } from "@squadbase/vantage/doc";
+import type { DocActionItemsProps, DocActionItem, DocActionPriority } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `action` is a `ReactNode`; Markdown strings are not parsed. The table headings ("対応", "担当", "期限", "期待する効果", "優先度"), the priority words (高 / 中 / 低) and the "まで" after a due date in `asks` are fixed in Japanese and cannot be overridden. Write `action`, `owner`, `due` and `impact` in English yourself; the default heading "推奨する対応" is Japanese, so pass `title`. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"推奨する対応"` | Heading text. |
+| `headingLevel` | `2 \| 3` | `2` | Heading level: 2 directly under `<Document>`, 3 inside another section. |
+| `items` | `DocActionItem[]` |  | Actions, most important first. **Required.** |
+| `items[].action` | `ReactNode` |  | What to do. **Required.** |
+| `items[].owner` | `string` |  | Owner. |
+| `items[].due` | `string` |  | Due date, shown as written ("2026-11-15", "11 月末"). |
+| `items[].impact` | `string` |  | Expected effect ("解約率 −0.5pt"). Shown in the `table` only. |
+| `items[].priority` | `"high" \| "medium" \| "low"` |  | Priority, printed as the word 高 / 中 / 低 (高 in semibold). Shown in the `table` only. |
+| `variant` | `"table" \| "asks"` | `"table"` | A table, or a bulleted list of requests to the reader. |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- `due` is shown as written ("2026-11-15", "11 月末"). A missing owner, due or impact shows "—".
+- `variant="asks"` adds only the owner and "`due` まで" (e.g. "（CS 部・11 月末 まで）"); the effect and priority are not shown.
+- When printed, each item of `asks` stays on one page and does not break across pages.

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

@@ -0,0 +1,38 @@
+# DocCallout
+
+> A boxed remark inside the text — a note, insight, warning or decision.
+
+A box for the one thing a reader must not miss — a `div` with `role="note"` and a left rule in the kind's semantic colour (a decision is neutral). The kind also prints as a word ("注意", "示唆"), so colour is never the only signal. Don't use it for decoration.
+
+```tsx
+import { DocCallout } from "@squadbase/vantage/doc";
+import type { DocCalloutProps, DocCalloutKind } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **a part to place inside body text or a section**, not a section of its own directly under `<Document>`. The document sets heading and body sizes and the width, so no dimensions are set here. `children` is a `string` or a `ReactNode`; Markdown strings are not parsed. The kind words ("補足", "示唆", "注意", "決定事項") are fixed in Japanese and cannot be overridden, so an English callout reads "注意: your title". Write `title` in English. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `kind` | `"note" \| "insight" \| "warning" \| "decision"` | `"note"` | Kind: note (補足) / insight (示唆) / warning (注意) / decision (決定事項). |
+| `title` | `string` |  | Heading of the box, one short line. When given, it prints as "<kind word>: <title>". Omit it and only the kind word shows. A title equal to the kind word is shown once. |
+| `children` | `ReactNode` |  | The body. A `string` becomes a paragraph. Markdown strings are not parsed. **Required.** |
+
+## Usage
+
+```tsx
+import { Document, DocCallout } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocCallout kind="warning" title="9 月の数値は速報値">
+    10 月 10 日の確定で変わることがあります。
+  </DocCallout>
+</Document>
+```
+
+## Notes
+
+- The kind word is added by the block; do not repeat it in `title`, which should hold only the heading itself.
+- When printed, it stays on one page and does not break across pages.

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

@@ -0,0 +1,60 @@
+# DocDataTable
+
+> A table with the notes a printed table needs — title, unit, total row, footnotes and source.
+
+A table with what a printed table needs: title, unit, right-aligned numbers, a total row, highlighted rows, footnotes and a source line. It is a plain `table` styled by `<Document>`, which also keeps rows together when printed. For screens that need sorting or scrolling, use `DataTable`.
+
+```tsx
+import { DocDataTable } from "@squadbase/vantage/doc";
+import type { DocDataTableProps, DocTableColumn, DocTableRow, DocTableCell } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **a part to place inside body text or a section**, not a section of its own directly under `<Document>`. The document sets heading and body sizes and the width, so no dimensions are set here. A cell is a string or a number; a `ReactNode` is not accepted. The caption labels "出典" and "データ時点" are fixed in Japanese and cannot be overridden; column labels, `title`, `unit` and footnotes are yours, so write them in English. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Table title, as a caption above the table. |
+| `unit` | `string` | Unit or scale ("単位: 百万円"). With a title it follows in parentheses. |
+| `columns` | `DocTableColumn[]` | Columns (`{ key; label; format?: ValueFormat; align?: "left" \| "right" \| "center" }`). Without `format`, numbers use a plain thousands format. Without `align`, a column of numbers is right-aligned and others left-aligned. **Required.** |
+| `rows` | `DocTableRow[]` | Rows: objects keyed by the `key` of `columns`. A cell is a string or a number (`null`, `undefined` and an empty string show "—"). **Required.** |
+| `total` | `DocTableRow` | The total row (`tfoot`), keyed like `rows`. |
+| `highlightRows` | `number[]` | Indexes of the rows to set in semibold (zero-based, indexes into `rows`). |
+| `footnotes` | `{ mark: string; text: string }[]` | Footnotes. Write the same `mark` ("※1") in a cell string to point at one. |
+| `source` | `string` | Source. Shown as "出典: …" in the caption. |
+| `asOf` | `string` | The date the data was taken, as a date only ("2026-10-03"). The block adds the label "データ時点". |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- Numbers line up with `tabular-nums`, and a missing cell shows "—".
+- When printed, a row does not break across pages. A long table may break between rows, and the caption (footnotes and source) stays on one page.

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

@@ -0,0 +1,64 @@
+# DocExecutiveSummary
+
+> The answer first — one conclusion, 3–5 points and optional headline numbers.
+
+The answer-first section (BLUF): one conclusion sentence, 3–5 numbered points and up to 3 headline numbers. The direction of each change comes from the sign of the `delta` you pass, and the ▲▼ mark and the sign are always printed, so the direction is clear without colour.
+
+```tsx
+import { DocExecutiveSummary } from "@squadbase/vantage/doc";
+import type { DocExecutiveSummaryProps, DocSummaryMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `conclusion` and `points` are a `string` or a `ReactNode`; Markdown strings are not parsed. The default heading "要旨" and the default comparison name "前期比" are Japanese; on an English page pass `title` and `comparisonLabel` in English. Nothing else is printed by the block here. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"要旨"` | Heading text. |
+| `headingLevel` | `2 \| 3` | `2` | Heading level: 2 directly under `<Document>`, 3 inside another section. |
+| `conclusion` | `ReactNode` |  | The verdict in one sentence, set in semibold. **Required.** |
+| `points` | `ReactNode[]` |  | Supporting points, 3–5, most important first. Shown as a numbered list. **Required.** |
+| `metrics` | `DocSummaryMetric[]` |  | Headline numbers (at most 3; any beyond are ignored). |
+| `metrics[].label` | `string` |  | Name of the metric. |
+| `metrics[].value` | `number \| null` |  | The value. `null` shows "—". |
+| `metrics[].format` | `ValueFormat` |  | Format of `value` (`"currency"`, `{ type: "percent", digits: 1 }`, …). |
+| `metrics[].display` | `string` |  | When given, shown instead of the formatted value ("about ¥54M"). |
+| `metrics[].delta` | `{ value: number; format?: ValueFormat }` |  | The change itself (current − comparison). Direction comes from the sign; the ▲▼ mark and the sign are always printed. Omit for no comparison. Without `format`, the metric's `format` is used. |
+| `metrics[].comparisonLabel` | `string` | `"前期比"` | Name of the comparison (e.g. "前月比"). |
+| `metrics[].betterWhen` | `"up" \| "down"` | `"up"` | Which way is good. Use `"down"` for churn or cost. Colour only adds good / bad. |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- For a metric where a fall is good, set `betterWhen: "down"` (this flips the good / bad colour; the ▲▼ mark and sign still show the real direction).
+- `delta` is the change itself, not the comparison value. For a rate (churn and the like), give it a `pt` format as in the example so it is not read as a relative change.
+- When printed, each point and each metric tile stays on one page; the section as a whole may break across pages.

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

@@ -0,0 +1,56 @@
+# DocFigure
+
+> The figure convention in one place — a finding title, unit, the chart and a caption with source.
+
+The figure convention: a title that states the finding, the unit, the chart (as `children`) and a caption with source and notes, as a real `figure` / `figcaption`. The chart is yours — a typed chart, an `EChart` or an image. A number without a source and a date is unfinished, so `source` and `asOf` are first-class.
+
+```tsx
+import { DocFigure } from "@squadbase/vantage/doc";
+import type { DocFigureProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **a part to place inside body text or a section**, not a section of its own directly under `<Document>`. The document sets heading and body sizes and the width, so no dimensions are set here. `children` is the chart (a `ReactNode`). The caption labels "図 N", "出典" and "データ時点" are fixed in Japanese and cannot be overridden; write `title`, `unit` and `notes` in English yourself. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The finding as a sentence ("Churn fell two months running"), not the subject. **Required.** |
+| `unit` | `string` | Unit or scale ("単位: %"), shown right under the title. Put definitions and caveats in `notes`. |
+| `number` | `number` | Figure number, shown as "図 N" in the caption. |
+| `source` | `string` | Where the data comes from. Shown as "出典: …" in the caption. |
+| `asOf` | `string` | The date the data was taken, as a date only ("2026-10-03"). The block adds the label "データ時点". |
+| `notes` | `string[]` | Footnotes and definitions, one per line. |
+| `children` | `ReactNode` | The chart; it takes the full column. **Required.** |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- Do not give the chart in `children` its own `title`; the title goes in the `title` of `DocFigure`. If the chart needs an accessible name, use `ariaLabel`.
+- A figure does not break across pages when printed.

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

@@ -0,0 +1,61 @@
+# DocKeyFindings
+
+> 3–5 findings — a concluding headline, evidence and an optional number.
+
+The "what we learned" section: 3–5 findings, each a numbered `h3` headline that states the conclusion, the evidence under it and optionally one number. The direction of the change comes from the sign of the `delta` you pass, and the ▲▼ mark and sign are always printed.
+
+```tsx
+import { DocKeyFindings } from "@squadbase/vantage/doc";
+import type { DocKeyFindingsProps, DocFinding, DocFindingMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `evidence` is a `string` or a `ReactNode`; Markdown strings are not parsed. The default heading "主要な発見" and the default comparison name "前期比" are Japanese; on an English page pass `title` and `comparisonLabel` in English. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"主要な発見"` | Section heading. |
+| `headingLevel` | `2 \| 3` | `2` | Heading level: 2 directly under `<Document>`, 3 inside another section. |
+| `findings` | `DocFinding[]` |  | Findings (`{ headline: string; evidence: ReactNode; metric?: DocFindingMetric }`), 3–5, most important first. **Required.** |
+| `findings[].metric` | `DocFindingMetric` |  | One number to go with the finding, with the fields below. |
+| `findings[].metric[].label` | `string` |  | Name of the metric. |
+| `findings[].metric[].value` | `number \| null` |  | The value. `null` shows "—". |
+| `findings[].metric[].format` | `ValueFormat` |  | Format of `value` (`"currency"`, `{ type: "percent", digits: 1 }`, …). |
+| `findings[].metric[].display` | `string` |  | When given, shown instead of the formatted value ("about ¥54M"). |
+| `findings[].metric[].delta` | `{ value: number; format?: ValueFormat }` |  | The change itself (current − comparison). Direction comes from the sign; the ▲▼ mark and the sign are always printed. Omit for no comparison. Without `format`, the metric's `format` is used. |
+| `findings[].metric[].comparisonLabel` | `string` | `"前期比"` | Name of the comparison (e.g. "前月比"). |
+| `findings[].metric[].betterWhen` | `"up" \| "down"` | `"up"` | Which way is good. Use `"down"` for churn or cost. Colour only adds good / bad. |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- Write `headline` as a sentence with a verdict, not a topic ("Churn is concentrated in business plans"). With `headingLevel={3}` the findings become `h4`.
+- Keep the numbers in `evidence` consistent with the `metric` (`delta` is the change itself; no rate is computed for you).
+- When printed, each finding stays on one page and does not break across pages.

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

@@ -0,0 +1,80 @@
+# DocKpiScorecard
+
+> Key metrics in one place — actual, change, gap to target and trend.
+
+The key metrics in one section: actual, change from the previous period, achievement against target and a small trend. The default `table` prints well; `grid` shows 3–6 metrics as `dl` tiles. The block computes the direction from the sign of `delta` and the achievement rate from `value ÷ target`.
+
+```tsx
+import { DocKpiScorecard } from "@squadbase/vantage/doc";
+import type { DocKpiScorecardProps, DocScorecardMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `asOf` and `source` appear in one line under the block. The labels the block prints (the column headings "指標" / "実績" / "目標" / "達成率" / "推移", "達成率" and "目標" in tiles, "データ時点", "出典") are fixed in Japanese and cannot be overridden. Only `title` and `comparisonLabel` can be set, so pass them in English; their defaults ("主要指標", "前期比") are Japanese. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"主要指標"` | Heading text. |
+| `headingLevel` | `2 \| 3` | `2` | Heading level: 2 directly under `<Document>`, 3 inside another section. |
+| `metrics` | `DocScorecardMetric[]` |  | Metrics. **Required.** |
+| `metrics[].label` | `string` |  | Name of the metric. |
+| `metrics[].value` | `number \| null` |  | The value. `null` shows "—". |
+| `metrics[].format` | `ValueFormat` |  | Format of `value` (`"currency"`, `{ type: "percent", digits: 1 }`, …). |
+| `metrics[].display` | `string` |  | When given, shown instead of the formatted value ("about ¥54M"). |
+| `metrics[].delta` | `{ value: number; format?: ValueFormat }` |  | The change itself (current − comparison). Direction comes from the sign; the ▲▼ mark and the sign are always printed. Omit for no comparison. Without `format`, the metric's `format` is used. |
+| `metrics[].comparisonLabel` | `string` | `"前期比"` | Name of the comparison (e.g. "前月比"). |
+| `metrics[].betterWhen` | `"up" \| "down"` | `"up"` | Which way is good. Use `"down"` for churn or cost. Colour only adds good / bad. |
+| `metrics[].target` | `number` |  | The target for the period, shown in the metric's `format`; the achievement rate (value ÷ target) is computed here. |
+| `metrics[].trend` | `{ x: string; y: number }[]` |  | One series over time, oldest first; the last point is the current value. Use the same unit as `value`. Omit and the cell shows "—"; with two or more points a `Sparkline` is drawn. |
+| `variant` | `"table" \| "grid"` | `"table"` | Table or tiles. |
+| `asOf` | `string` |  | The date the numbers were taken, as a date only ("2026-10-03"). Shown as "データ時点 …" in a line under the block. |
+| `source` | `string` |  | Source. Shown as "出典: …" in a line under the block. |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- For churn or cost, where a fall is good, set `betterWhen: "down"`. A missing value shows "—".
+- Give `target` and the `y` of `trend` in the same unit as `value` (yen if `value` is yen). `target` is shown in the metric's `format`.
+- The heading of the comparison column in the table is the `comparisonLabel` of the first metric that has one, or "前期比" if none does. There is only one column, so use `variant="grid"` to give each metric its own comparison name.
+- When printed, the `table` keeps each row on one page and the `grid` keeps each tile on one page.

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

@@ -0,0 +1,46 @@
+# DocReportHeader
+
+> The opening of a document — title, subtitle, period, as-of, author and source.
+
+The section that opens a document: an `h1` title and a short fact sheet (`dl`) of period, data as-of, author and source. It is the only block that owns the `h1`; the rest start at `h2`.
+
+```tsx
+import { DocReportHeader } from "@squadbase/vantage/doc";
+import type { DocReportHeaderProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section to place directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. `subtitle` is a `string` or a `ReactNode`; Markdown strings are not parsed. The fact labels this block prints ("対象期間", "データ時点", "作成者", "出典") are fixed in Japanese and cannot be overridden, so an English page shows them in Japanese. For the whole page, see [Document](page-types/doc).
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The document title (`h1`). State the subject and period, not a slogan. **Required.** |
+| `subtitle` | `ReactNode` | One line under the title (who it is for, …). A `string` or a `ReactNode`. |
+| `period` | `string` | The period the numbers cover ("2026 年 9 月", "2026-07-01 〜 2026-09-30"). |
+| `asOf` | `string` | The date the data was taken, as a date only ("2026-10-03"). The block adds the label "データ時点". |
+| `author` | `string` | Author. |
+| `source` | `string` | Where the numbers come from ("受注管理システム、会計システム"), as one string. |
+
+## Usage
+
+```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>
+```
+
+## Notes
+
+- An empty fact is left out, row and all, instead of showing "—".
+- When printed, the whole header stays on one page; it does not break across pages.