@squadbase/vantage 0.6.2-dev1.5aae04e → 0.6.2-dev1.72360fb

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.

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.