@squadbase/vantage 0.6.2-dev1.a7c4a3e → 0.6.2-dev1.a881d95

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.

package/docs/en/pages-and-metadata.md

@@ -60,6 +60,21 @@ No `navLabel` is set, so the nav shows the same string. To change it, **rename t
 prefix it with `_` to stop it routing and render it from a `.tsx` page with `FilePageView`, where a
 `definePage` of your own applies.
 
+## App display language
+
+Export `lang` as a literal from the root `_layout.tsx` and it becomes `<html lang>`.
+
+```tsx
+// src/_layout.tsx
+export const lang = "ja"
+```
+
+- The value is a BCP 47 language tag (`"ja"`, `"en"`, `"ja-JP"`, …). Variables and template interpolation are not read.
+- Only the root `_layout.tsx` is read. A `lang` in a nested layout or a page is ignored.
+- A missing or malformed value falls back to `"en"` (malformed values raise a diagnostic). Apps that specify nothing produce the same output as before.
+- With `ja`, Japanese text in slides and doc pages no longer breaks mid-phrase (`word-break: auto-phrase`), and the slide toolbar messages switch to Japanese.
+- In dev, editing `lang` reloads the page automatically.
+
 ## Relationship to Fast Refresh
 
 Even with a non-component export like `page`, Vantage handles it internally so React Fast Refresh

package/docs/en/parts/area-chart.md

@@ -0,0 +1,99 @@
+# AreaChart
+
+> A typed area chart for trends over time. Pass rows, the x-axis column and the series columns.
+
+Draws a trend as filled areas. Instead of building an ECharts option, pass **the rows (`data`), the
+x-axis column (`index`) and the series columns (`categories`)**; the legend, tooltip and axis
+formats come with it. Colours follow the `--chart-1` … `--chart-5` tokens in fixed order and track
+light / dark. Under the hood it is an [`EChart`](parts/echart) inside a chart frame
+(title, summary, loading skeleton, empty state). The value axis always starts at 0.
+
+```tsx
+import { AreaChart } from "@squadbase/vantage/components";
+import type { AreaChartProps, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | An array of rows. **Required.** One row is one x-axis point. Numeric columns are a number or a numeric string (such as a SQL DECIMAL); anything else counts as a gap. |
+| `index` | `string` |  | The column used for the x axis. **Required.** |
+| `categories` | `string[]` |  | The columns drawn as series. **Required.** Their order is the legend and colour order. Six or more fold into the five largest by total plus an Other series. |
+| `areaOptions` | `AreaChartOptions` |  | Area-specific settings: `{ type, curveType, fill, connectNulls }`. **Prefer this.** Takes precedence over the deprecated flat props of the same name. See below. |
+| `forecast` | `ChartForecast` |  | A forecast continuing one series: `{ data, category?, label? }`. `data` rows share the `index` key and carry the predicted value and an optional range. Always drawn as a dashed, lighter line. |
+| `comparison` | `ChartComparison` |  | Turns one of `categories` into a comparison line (prior year, plan…): `{ category, vs: "prior-period" \| "prior-year" \| "target" \| "custom", label? }`. Drawn as a thin grey line with no fill; the tooltip adds the main series' difference from it. `label` is required for `custom`. |
+| `colors` | `ChartColors` | `["chart-1", …, "chart-5"]` | Series colours: `"chart-1"` … `"chart-5"` or a semantic tone (`"positive"` / `"warning"` / `"negative"` / `"neutral"`). An array follows series order; a record is keyed by series name. |
+| `labels` | `Record<string, string>` |  | Maps `index` values and series names to display names (axes, legend, tooltip, data table). |
+| `format` | `ValueFormat` | `"compact"` | Number format: `"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`, or `{ type, digits, currency, notation, unit, divisor, durationUnit }`. Same values as the KPI components. Axes use a short form; the tooltip uses the same format. |
+| `valueFormatter` | `(value: number) => string` |  | A function escape hatch for the format. Takes precedence over `format`; kept for compatibility. |
+| `title` | `string` |  | The chart heading. It labels the plot area for screen readers. |
+| `summary` | `string \| "auto"` |  | A one-sentence summary shown under the title and used as the plot's `aria-describedby`. `"auto"` builds one from `data`. Omitted means no summary. |
+| `isLoading` | `boolean` |  | Show a skeleton shaped like the final chart, at the same height. |
+| `emptyState` | `ChartEmptyState` |  | What to show when `data` is empty: `{ title?, description?, action? }`. The frame keeps its height. `action` takes one node, such as a button. |
+| `height` | `number \| string` | `288` | Plot-area height in px. A CSS length string is accepted for compatibility only and is deprecated; pass a number. |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | Show PNG save / copy buttons at the top right on hover. The PNG includes the title and summary unless you pass `{ includeTitle: false }`. |
+| `fileName` | `string` | `"chart.png"` | File name for the saved PNG. Use with `actions`. |
+| `chartOptions` | `EChartsOption` |  | An escape hatch deep-merged last into the generated ECharts option. |
+| `highlight` | `"auto" \| "none"` | `"auto"` | Label the max and latest value (first series only, two series or fewer). For `percent` stacking it labels the first and latest share of the bottom band. |
+| `provisionalFrom` | `string \| number` |  | An `index` value; points from here on are provisional and drawn lighter or dashed. Distinct from `forecast`. |
+| `provisionalLabel` | `string` |  | Name of the provisional range in legend and tooltip. |
+| `target` | `number` |  | A target value, drawn as a dotted horizontal line. The value axis always includes it. |
+| `targetLabel` | `string` |  | Label for the target line. |
+| `annotations` | `ChartAnnotation[]` |  | Notes at given positions: `{ at, label, to? }`. `at` / `to` are `index` values; with `to` it becomes a band, otherwise a vertical line. |
+| `showLegend` | `boolean` | `true` | Show the legend. |
+| `showTooltip` | `boolean` | `true` | Show the tooltip on hover. |
+| `showGridLines` | `boolean` | `true` | Grid lines on the value axis. |
+| `showXAxis` | `boolean` | `true` | Show the x axis. |
+| `showYAxis` | `boolean` | `true` | Show the y axis. |
+| `startEndOnly` | `boolean` | `false` | Label only the first and last x-axis ticks. |
+| `yAxisWidth` | `number` |  | Width of the y-axis labels (px). Fix it to align plot areas across stacked charts. |
+| `minValue` | `number` |  | Lower bound of the value axis. Area charts always start at 0, so only values of 0 or below take effect (room under negative values). |
+| `maxValue` | `number` |  | Upper bound of the value axis. The axis widens if the data exceeds it. Pass the same value to charts you compare side by side. |
+| `allowDecimals` | `boolean` | `true` | `false` limits ticks to integers. |
+| `xAxisLabel` | `string` |  | Name of the x axis. |
+| `yAxisLabel` | `string` |  | Name of the y axis. |
+| `onValueChange` | `(value: ChartEventPayload \| null) => void` |  | Called on a click. Receives the clicked row plus `eventType` and `categoryClicked` (the series name); clicking the same point again passes `null`. When set, everything but the selection dims. |
+| `ariaLabel` | `string` |  | Screen-reader label for the plot area when there is no `title`. |
+| `className` | `string` |  | Classes to add (to the outer `<figure>`). |
+| `type` | `"default" \| "stacked" \| "percent"` |  | **Deprecated.** Use `areaOptions.type`. |
+| `curveType` | `"linear" \| "smooth" \| "step"` |  | **Deprecated.** Use `areaOptions.curveType`. |
+| `fill` | `"gradient" \| "solid" \| "none"` |  | **Deprecated.** Use `areaOptions.fill`. |
+| `connectNulls` | `boolean` |  | **Deprecated.** Use `areaOptions.connectNulls`. |
+| `loading` | `boolean` |  | **Deprecated.** Use `isLoading`. |
+
+## areaOptions
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"default" \| "stacked" \| "percent"` | `"default"` | `stacked` stacks the series; `percent` stacks them as shares of each point's total (the tooltip still shows the original values). |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | The line shape. |
+| `fill` | `"gradient" \| "solid" \| "none"` | `"gradient"` | How the area is filled. |
+| `connectNulls` | `boolean` | `false` | Join the line across gaps (`null` values). |
+
+> [!WARNING]
+> The flat `type`, `curveType`, `fill` and `connectNulls` props still work but are **deprecated**. Use
+> `areaOptions`; when both are given, `areaOptions` wins.
+
+## Showing a change in composition
+
+`areaOptions.type: "percent"` stacks each point to 100%. The value axis is fixed to 0–100%, and the
+tooltip shows the **original values**.
+
+```tsx
+<AreaChart
+  data={rows}
+  index="month"
+  categories={["Online", "Store"]}
+  areaOptions={{ type: "percent" }}
+/>
+```
+
+> [!NOTE]
+> `colors` are not Tailwind classes but **colour values** (the chart is drawn on a canvas). Token
+> names such as `"chart-2"` follow light / dark. Axis, legend and tooltip colours always come from the
+> theme.
+
+## AreaChart or EChart
+
+Start with this typed chart. Reach for [`EChart`](parts/echart) only for what these
+props cannot express — dual axes, scatter plots, heatmaps. Small tweaks can go through
+`chartOptions`.