@squadbase/vantage 0.6.2 → 0.7.0-dev1.1197de7

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,15 @@ 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) / [`SlideSection`](slide/slide-section) / [`SlideComparison`](slide/slide-comparison) / [`SlideChartFull`](slide/slide-chart-full)
+- **slide parts**: parts used inside a slide (not whole slides). [`SlideHeading`](slide/slide-heading) / [`SlideSourceLine`](slide/slide-source-line) / [`SlideColumns`, `SlideColumn`](slide/slide-columns)
+- **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) / [`DocNotesAndSources`](doc/doc-notes-and-sources)
+- **doc parts**: a part placed inside a sentence (also usable in slides). [`DeltaText`](doc/delta-text)
+
 ## Putting it together
 
 ```tsx
@@ -154,9 +172,8 @@ import {
   PageShellHeaderEnd,
   PageShellActions,
   PageShellContent,
+  KpiCard,
   DashboardCardPreset,
-  MetricValue,
-  TrendIndicator,
   EChart,
   type EChartsOption,
 } from "@squadbase/vantage/components";
@@ -184,17 +201,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/delta-text.md

@@ -0,0 +1,40 @@
+# DeltaText
+
+> [Part] An inline change — ▲ ▼ and a signed value — for documents and slides.
+
+A change as a bare inline `span`: a mark plus a signed value ("▲ +3.2%"), so print and colour-blind readers get the direction; colour only adds good or bad. It sets no text size and takes the size of the line it sits in. It is a **part** usable in both documents and slides, not a section or a slide block.
+
+```tsx
+import { DeltaText } from "@squadbase/vantage/doc";
+import type { DeltaTextProps } from "@squadbase/vantage/doc";
+// The same part is available from the slide subpath
+// import { DeltaText } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> This is **a part to place inside a sentence**. It has no dimensions or text size of its own and follows the line it sits in. It is separate from the dashboard `Delta`.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number \| null` |  | The change itself; its direction comes from the sign. `null` shows 「—」. **Required.** |
+| `format` | `ValueFormat` |  | How to format the value (`"percent"`, `"currency"`, …). Printed with an explicit sign. |
+| `betterWhen` | `"up" \| "down"` | `"up"` | Which direction is good; decides the colour. Use `"down"` for churn and cost. |
+| `comparisonLabel` | `string` |  | Name of the comparison ("vs last month"). Printed before the change, muted. |
+
+## Usage
+
+```tsx
+import { DeltaText } from "@squadbase/vantage/doc";
+
+<p>
+  Revenue in September was ¥540M (<DeltaText value={0.074} format="percent" comparisonLabel="vs last month" />).
+  Churn is 1.8% (<DeltaText value={-0.006} format="percent" betterWhen="down" comparisonLabel="vs last month" />).
+</p>
+```
+
+## Notes
+
+- Zero is shown as 「→」 in the muted colour.
+- The spoken words (「増」, 「減」, 「横ばい」, 「改善」, 「悪化」) in the accessible label are fixed in Japanese.

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-notes-and-sources.md

@@ -0,0 +1,43 @@
+# DocNotesAndSources
+
+> The end matter of a document — notes, definitions of terms and data sources.
+
+The section to put last in a document. It prints numbered notes, definitions of terms and the data sources (with their as-of dates). A part with nothing in it is not drawn; with all three empty nothing renders.
+
+```tsx
+import { DocNotesAndSources } from "@squadbase/vantage/doc";
+import type { DocNotesAndSourcesProps, DocDefinition, DocSource } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> This is **one section placed directly under `<Document>`**. The document sets heading and body sizes and the width, so no dimensions are set here. Markdown strings are not parsed. For the whole page, see [Document](page-types/doc). The sub-headings ("注記", "用語の定義", "出典") and 「（データ時点 …）」 are fixed in Japanese.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"注記・出典"` | The section heading. |
+| `headingLevel` | `2 \| 3` | `2` | Heading level: `2` directly under `<Document>`, `3` inside another section. The sub-headings go one level lower. |
+| `notes` | `ReactNode[]` |  | Notes, printed as a numbered list (provisional figures, exclusions). |
+| `definitions` | `DocDefinition[]` |  | Definitions of terms: `{ term: string; description: ReactNode }`. |
+| `sources` | `DocSource[]` |  | Data sources: `{ name: string; asOf?: string }`. `asOf` is a date only (e.g. `"2026-10-03"`), printed as 「（データ時点 2026-10-03）」. |
+
+## Usage
+
+```tsx
+import { Document, DocNotesAndSources } from "@squadbase/vantage/doc";
+
+<Document>
+  {/* …body sections… */}
+  <DocNotesAndSources
+    notes={["September figures are provisional; final values are posted on October 10.", "Refunds are excluded from revenue."]}
+    definitions={[{ term: "Churn rate", description: "Contracts cancelled in the month divided by contracts at the start of the month." }]}
+    sources={[{ name: "Contract DB", asOf: "2026-10-03" }, { name: "Accounting system" }]}
+  />
+</Document>
+```
+
+## Notes
+
+- Each part is kept together so it does not break across pages when printed.
+- `asOf` is date only; the 「データ時点」 wording is added for you.