@squadbase/vantage 0.6.2-dev1.5aae04e → 0.6.2-dev1.81c1bbe

package/docs/ja/parts/sample-data.md

@@ -0,0 +1,61 @@
+# SampleData
+
+> まだ実データにつながっていない「見本の値」に印を付ける。
+
+下書きの段階で、クエリをつなぐ前に並べた値を囲みます。囲んだ中の `KpiCard` と `DashboardCardPreset` が、見出しに
+**「見本の値」のバッジ**を出します。バッジは色だけでなく言葉で伝え、ツールチップで意味も説明します。実データを
+つなぎ終えたら `SampleData` を外します。
+
+```tsx
+import { SampleData, SampleBadge } from "@squadbase/vantage/components";
+import type { SampleDataProps, SampleBadgeProps } from "@squadbase/vantage/components";
+```
+
+## SampleData
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` | `"見本の値"` | 印の文言。 |
+| `children` | `ReactNode` |  | 印を付けたい部品。 |
+
+`SampleData` 自身は箱を持ちません（`display: contents`）。親の grid・subgrid から見ると中のカードが直接の子の
+ままなので、`KpiCard` の行の区切りは揃ったままです。
+
+カードは 1 枚につき印を 1 回だけ出します。`DashboardCardPreset` が見出しに出したら、その中のグラフや表は
+重ねて出しません。素のグラフに印を付けたいときは `DashboardCardPreset` に入れてください。
+
+## SampleBadge
+
+バッジ単体です。`SampleData` の外で、見本であることを自分で示したいときに使います。`<span>` の属性もそのまま渡せます。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` | `"見本の値"` | 印の文言。 |
+| `className` | `string` |  | 足すクラス。 |
+
+## SampleClaim と useSampleMark
+
+自作のカード部品が `SampleData` に対応するための部品です。`useSampleMark()` は、いま印を出すべきなら
+`{ label }`、なければ `null` を返します。印を出したカードは、中身を `<SampleClaim>` で包んで、内側の部品が
+同じ印を繰り返さないようにします。
+
+```tsx
+import { SampleBadge, SampleClaim, useSampleMark } from "@squadbase/vantage/components";
+
+function MyCard({ title, children }: { title: string; children: React.ReactNode }) {
+  const mark = useSampleMark();
+  return (
+    <section>
+      <h3>
+        {title} {mark && <SampleBadge label={mark.label} />}
+      </h3>
+      <SampleClaim>{children}</SampleClaim>
+    </section>
+  );
+}
+```
+
+> [!NOTE]
+> `SampleData` は「実データにまだつながっていない」ことを示します。速報値のように、実データだが確定前の値は
+> `KpiCard` やグラフの `provisional` で示し、混ぜません。文中や見出しの中の値 1 つだけが仮なら
+> [`Placeholder`](parts/placeholder) を使います。同じ値に両方は付けません。

package/docs/ja/parts/scatter-chart.md

@@ -0,0 +1,69 @@
+# ScatterChart
+
+> 2 つの数値の関係と外れ値を見せる型付きの散布図。大きさを足せばバブルチャートになる。
+
+広告費と売上、客単価と購入頻度のように、2 つの数値の関係を点の位置で見ます。**行の配列（`data`）と、
+横軸・縦軸の列名（`x` / `y`）**を渡すだけで描けます。`size` でバブル、`series` で色分け（`--chart-1..5` を
+固定順）、`labelKey` で点の名前の表示ができます。散布図は位置で読むので、軸は既定でデータの範囲に合わせ、
+0 起点にしません。
+
+```tsx
+import { ScatterChart } from "@squadbase/vantage/components";
+import type { ScatterChartProps, ScatterReferenceLine } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 点。x か y が数値でない行は描かない。 |
+| `x` | `string` |  | 横軸に使う数値の列名。**必須**。 |
+| `y` | `string` |  | 縦軸に使う数値の列名。**必須**。 |
+| `size` | `string` |  | 点の面積に使う数値の列名。渡すとバブルチャートになる。0 を基準に面積が比例し、null・0 以下は最小の大きさ。 |
+| `index` | `string` |  | 点の名前の列名。ツールチップの見出しとデータ表の先頭列になる。 |
+| `labelKey` | `string` |  | 点の脇に書く文字の列名。重なるラベルは自動で間引く（ツールチップには常に出る）。`index` が無ければ名前も兼ねる。 |
+| `series` | `string` |  | 系列分けの列名。値ごとに色を分け、凡例を出す。6 つ以上は点の多い 5 つ +「その他」（灰色）にまとまる。 |
+| `seriesLabel` | `string` |  | 凡例の見出し。系列があって凡例が出るときだけ、凡例の左に小さく書く。 |
+| `highlight` | `string \| string[]` |  | 前面に出す系列（`series` 列の値）。指定した系列は不透明で手前に、指定外は薄く背面に描く。 |
+| `referenceLines` | `ScatterReferenceLine[]` |  | 基準線（目標・平均・しきい値）。`{ axis: "x" \| "y", value, label? }`。中立色の破線で、軸の範囲が線まで広がる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"` か意味色。配列は系列の出現順、record は系列名ごと。「その他」は常に灰色。 |
+| `labels` | `Record<string, string>` |  | 列名・系列の値 → 表示名（軸のタイトル・凡例・ツールチップ・データ表）。 |
+| `format` | `ValueFormat` | `"compact"` | x・y・size の既定の書式。 |
+| `xFormat` | `ValueFormat` |  | 横軸と x の値の書式。`format` より優先。 |
+| `yFormat` | `ValueFormat` |  | 縦軸と y の値の書式。`format` より優先。 |
+| `sizeFormat` | `ValueFormat` |  | `size` の値の書式（ツールチップ・データ表）。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。x・y・size すべてに使われ、`format` 系より優先。 |
+| `minValue` | `number` |  | 縦軸の下限。データが下回れば広がる。 |
+| `maxValue` | `number` |  | 縦軸の上限。データが超えれば広がる。 |
+| `xMinValue` | `number` |  | 横軸の下限。 |
+| `xMaxValue` | `number` |  | 横軸の上限。並べて比べる散布図には同じ範囲を渡す。 |
+| `fitToData` | `boolean` | `true` | 両軸をデータの範囲に合わせる。`false` で両軸を 0 から始める。 |
+| `showLegend` | `boolean` | `true` | 凡例を出す（系列が 2 つ以上のときだけ）。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `summary` | `string \| "auto"` |  | 1 文要約。`"auto"` で点の数と y が最大の点から組む。省略時は要約なし。 |
+| `title` | `string` |  | グラフの見出し。プロット領域の読み上げ名にもなる。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。既定の題は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。 |
+| `chartOptions` | `EChartsOption` |  | 生成した option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG 保存 / コピーのボタンを出す（ホバー時）。見出しと要約は既定で画像に含まれ、`includeTitle: false` で外せる。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `className` | `string` |  | 外枠（`<figure>`）のクラス。幅はここで決める。 |
+| `ariaLabel` | `string` |  | 見出しが無いときのプロット領域の読み上げ名。 |
+
+## 基準線と強調
+
+目標や平均は `referenceLines` で引きます。数が多い点の中に埋もれる少数の系列は `highlight` で手前に出し、
+残りを薄くします。
+
+```tsx
+<ScatterChart
+  data={rows}
+  x="spend"
+  y="roas"
+  series="channel"
+  highlight="SNS"
+  referenceLines={[{ axis: "y", value: 3, label: "目標 ROAS 3" }]}
+/>
+```
+
+> [!NOTE]
+> 幅が 480px 未満になると、ラベルは y が高い 2 点だけになり、凡例はプロットの下に移ります。

package/docs/ja/parts/updated-at.md

@@ -0,0 +1,27 @@
+# UpdatedAt
+
+> データの鮮度を示す更新時刻。相対時刻に、タイムゾーンつきの絶対時刻を添える。
+
+「23 分前に更新」のような鮮度の表示です。`<time>` 要素で、`dateTime` に ISO 形式の時刻を持ち、ツールチップと
+`title` に**タイムゾーンつきの絶対時刻**（「2026/10/20 16:41 JST」）が出ます。表示は 60 秒ごとに更新されます。
+「今」が大事なページでは `variant="absolute-first"` で「16:41 更新（23 分前）」と併記します。
+
+```tsx
+import { UpdatedAt } from "@squadbase/vantage/components";
+import type { UpdatedAtProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `at` | `Date \| string \| number` |  | データを最後に更新した時刻。**必須**。 |
+| `variant` | `"relative" \| "absolute-first"` | `"relative"` | `relative` は「23 分前に更新」。`absolute-first` は「16:41 更新（23 分前）」で、今日でなければ日付も付く。 |
+| `timeZone` | `string` |  | 絶対時刻に使う IANA タイムゾーン（`"Asia/Tokyo"` など）。省略時は実行環境のもの。 |
+| `prefix` | `string` |  | ラベルの前に置く文字（`"売上データ: "`）。 |
+| `now` | `Date \| number` |  | 「現在時刻」を固定する（テスト・見本用）。渡すと 60 秒ごとの更新を止める。 |
+| `className` | `string` |  | 足すクラス。 |
+
+1 分未満の差は「たった今」と出ます。
+
+> [!NOTE]
+> 最初の描画（サーバーとクライアント）は ISO の `dateTime` だけの空の `<time>` で、マウント後にラベルが入ります。
+> 表示が閲覧者の時計とタイムゾーンに依存するためで、ハイドレーションの不一致は起きません。

package/docs/ja/parts/waterfall-chart.md

@@ -0,0 +1,61 @@
+# WaterfallChart
+
+> 増減の積み上がりを見せる型付きのウォーターフォール。売上から粗利までの内訳や、前期からの増減要因に。
+
+段ごとの増減が累計をどう動かすかを、階段状の棒で描きます。**行の配列（`data`）・段の名前の列（`index`）・
+金額の列（`categories`）**を渡し、合計の段は `totals` に名前で挙げます。合計の行の値は省けば直前までの累計を
+計算します。増加は `--positive-fill`、減少は `--negative-fill`、合計は `--chart-1`。各棒には符号つきの金額も
+書くので、色だけで向きを伝えません。縦軸は常に 0 を含みます。
+
+```tsx
+import { WaterfallChart } from "@squadbase/vantage/components";
+import type { WaterfallChartProps, WaterfallMode } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 段で、並びがそのまま左から右の順。値は number か数値文字列。null は棒を描かず「—」。 |
+| `index` | `string` |  | 段の名前に使う列名。**必須**。 |
+| `categories` | `string[]` |  | 金額の列名を 1 つだけ入れた配列（`["amount"]`）。**必須**。2 つ以上渡しても最初の 1 つだけを使う。 |
+| `totals` | `string[]` |  | 合計の段にする行の `index` の値。0 から累計まで届く棒になる。値が null なら直前までの累計。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | 増えるのが良いか。解約数のように増えて悪い指標は `lower-is-better` で増減の色が入れ替わる。`neutral` は増減とも中立色（符号は付く）。 |
+| `mode` | `"total" \| "delta"` | `"total"` | `delta` は増減の段だけを、開始を 0 とした累計増減の軸で描き、末尾に「純増」の棒を足す。開始・終了の値は図の上の注記に出る。合計に対して増減が小さい（目安 5% 未満）ときに使う。 |
+| `labels` | `Record<string, string>` |  | 段の名前 → 表示名（軸・ツールチップ・データ表）。無いキーはそのまま。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式（`"currency"` や `{ type: "number", unit: "件" }` など）。軸・棒のラベル・ツールチップで同じ。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先。 |
+| `minValue` | `number` |  | 縦軸の下限。軸は常に 0 を含むので 0 以下の値だけ有効。データが下回れば広がる。 |
+| `maxValue` | `number` |  | 縦軸の上限。データが超えれば広がる。並べて比べるグラフには同じ値を渡して軸をそろえる。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。並べたグラフのプロット領域を揃えたいときに固定する。 |
+| `showValues` | `boolean` | `true` | 各棒に符号つきの増減額（合計は累計）を書く。 |
+| `showTooltip` | `boolean` | `true` | ホバーで増減と累計を出す。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。`"auto"` で最初と最後の値、最大の増加・減少から組む。省略時は要約なし。 |
+| `title` | `string` |  | グラフの見出し。プロット領域の読み上げ名にもなる。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。既定の題は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。 |
+| `chartOptions` | `EChartsOption` |  | 生成した option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG 保存 / コピーのボタンを出す（ホバー時）。見出しと要約は既定で画像に含まれ、`includeTitle: false` で外せる。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `className` | `string` |  | 外枠（`<figure>`）のクラス。幅はここで決める。 |
+| `ariaLabel` | `string` |  | 見出しが無いときのプロット領域の読み上げ名。 |
+
+## 増減が小さいときは delta
+
+総額に対して増減が小さいと、棒が総額の高い軸に埋もれて線のようになります。`mode="delta"` にすると
+増減だけを 0 起点の累計で描き、最後に「純増」の棒を足します。`totals` に挙げた行（前期・当期）は棒にならず、
+図の上の注記になります。
+
+```tsx
+<WaterfallChart
+  data={rows}
+  index="item"
+  categories={["amount"]}
+  totals={["前期", "当期"]}
+  mode="delta"
+  format="currency"
+/>
+```
+
+> [!NOTE]
+> 解約数や原価のように増えて悪い値の段を並べるときは `polarity="lower-is-better"` にします。色の意味が
+> 入れ替わるだけで、棒の向きと符号は変わりません。

package/docs/ja/slide/slide-chart-insight.md

@@ -0,0 +1,52 @@
+# SlideChartInsight
+
+> グラフ 1 つと、その読み解き。レポートでいちばん多い 1 枚。
+
+グラフ 1 つ（12 カラムのうち 8）と、その読み解き（残りの 4、最大 3 点）を並べる 1 枚です。グラフは `line` / `bar` / `area`。キャンバス用の文字サイズで、ツールチップとアニメーションなしで組まれるので、pptx に見た目のまま書き出せます。
+
+```tsx
+import { SlideChartInsight } from "@squadbase/vantage/slide";
+import type { SlideChartInsightProps, SlideChartInsightChart } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `chart` | `SlideChartInsightChart` |  | `{ type: "line" \| "bar" \| "area"; categories: string[]; series: { name: string; data: number[] }[] }`。**必須**。系列が 2 つ以上なら凡例が出る。 |
+| `insights` | `string[]` |  | グラフの読み解き。2〜3 点。**必須**。 |
+| `chartSide` | `"left" \| "right"` | `"left"` | グラフを置く側。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideChartInsight } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideChartInsight
+    title="解約率は 6 月以降、毎月下がり続けている"
+    chart={{
+      type: "line",
+      categories: ["6 月", "7 月", "8 月", "9 月"],
+      series: [{ name: "解約率(%)", data: [2.7, 2.4, 2.1, 1.8] }],
+    }}
+    insights={[
+      "オンボーディング刷新後の 3 か月で 0.9pt 低下",
+      "低下は中小企業プランが中心",
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 4 点以上の `insights` は描画されますが `console.warn` が出ます。スライドを分けてください。
+- 型付きグラフ（`LineChart` など）は使いません。この block が `EChart` で直接組みます。

package/docs/ja/slide/slide-cover.md

@@ -0,0 +1,39 @@
+# SlideCover
+
+> デッキの表紙。タイトル・サブタイトル・期間・作成者・時点を 1 枚に収める。
+
+デッキの表紙です。タイトルは左 8 カラムに置かれ、期間・作成者・時点は下端の 1 行にまとまります。
+
+```tsx
+import { SlideCover } from "@squadbase/vantage/slide";
+import type { SlideCoverProps } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | デッキの名前。**必須**。 |
+| `subtitle` | `string` | タイトルの下の 1 行。 |
+| `period` | `string` | 対象期間（「2026 年 7 月〜9 月」）。 |
+| `author` | `string` | 作成者・チーム名。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-20"`）。block が「2026-10-20 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideCover } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideCover title="2026 年度 第 2 四半期 事業レビュー" subtitle="売上・解約・新規獲得の振り返りと次の打ち手" period="2026 年 7 月〜9 月" author="事業企画チーム" asOf="2026-10-20" source="社内 BI" />
+</Slide>
+```
+
+## 注意
+
+- 表紙は 1 デッキに 1 枚です。2 枚目以降の見出しは他の block のアクションタイトルで書きます。
+- サブタイトルは目的や読み手を 1 行で。長い説明は 2 枚目以降へ。

package/docs/ja/slide/slide-exec-summary.md

@@ -0,0 +1,47 @@
+# SlideExecSummary
+
+> 結論を先に伝える 1 枚。アクションタイトルと 3〜5 個の要点。
+
+結論が先の 1 枚です。アクションタイトルの下に、1 行の見出し（と任意の補足 1 行）を持つ要点を 3〜5 個並べます。
+
+```tsx
+import { SlideExecSummary } from "@squadbase/vantage/slide";
+import type { SlideExecSummaryProps, SlideExecSummaryPoint } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `points` | `SlideExecSummaryPoint[]` |  | 要点（`{ headline: string; detail?: string }`）。3〜5 個。**必須**。 |
+| `layout` | `"rows" \| "columns"` | `"rows"` | `rows` は番号付きで縦に積む。`columns` は横に並べる（3〜4 個向き）。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideExecSummary } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideExecSummary
+    title="Q2 は売上が計画を 4% 上回り、解約の改善が次の課題"
+    points={[
+      { headline: "売上は 5.4 億円で計画比 +4%", detail: "新規 38 社が牽引" },
+      { headline: "解約率は 1.8% まで低下", detail: "オンボーディング刷新の効果" },
+      { headline: "新規獲得は目標に 12 社届かず", detail: "紹介経由が想定の半分" },
+    ]}
+    asOf="2026-10-20"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 6 個以上は描画されますが、`console.warn` が出ます。スライドを分けてください。
+- `title` は話題（「売上の状況」）ではなく、結論の文で書きます。

package/docs/ja/slide/slide-kpi-grid.md

@@ -0,0 +1,55 @@
+# SlideKpiGrid
+
+> 2〜4 個の KPI を並べるスコアボード。値・増減・目標。
+
+2〜4 個の KPI カードを横に並べるスコアボードです。各カードにラベル・値・増減・目標が入り、幅は等分されます。
+
+```tsx
+import { SlideKpiGrid } from "@squadbase/vantage/slide";
+import type { SlideKpiGridProps, SlideKpiGridItem, SlideKpiGridDelta } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `items` | `SlideKpiGridItem[]` |  | KPI。2〜4 個。**必須**。各要素は下の `items[].…` の行。 |
+| `items[].label` | `string` |  | 指標名。**必須**。 |
+| `items[].value` | `number \| null` |  | 数値。`null` は「—」と表示される。**必須**。`format` で整形される。 |
+| `items[].format` | `ValueFormat` |  | 値の整形（`"currency"` / `"percent"` / `{ type: "number", unit: "社" }` など）。`delta` と `target` の既定の整形にもなる。 |
+| `items[].display` | `string` |  | 表示する文字だけを置き換える（元の数値は `value` のまま `data-raw` に残る）。 |
+| `items[].delta` | `SlideKpiGridDelta` |  | `{ value: number; format?: ValueFormat }`。増減の大きさを符号付きで（例: `0.074` と `format: "percent"` で「+7.4%」）。向きは符号で決まり、▲ ▼ と「増」「減」も出る。`format` の既定は item の `format`。 |
+| `items[].betterWhen` | `"up" \| "down"` | `"up"` | `delta` のどちらの向きが良いか。色が決まる。 |
+| `items[].comparisonLabel` | `string` |  | `delta` の比較相手（「前月比」）。 |
+| `items[].target` | `number` |  | 目標。`format` は `value` と同じ。「目標 …（達成率 …）」と表示される。達成率は value ÷ target（`betterWhen` が `"down"` なら target ÷ value）。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideKpiGrid } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiGrid
+    title="売上と継続率は計画どおり、新規獲得だけが未達"
+    items={[
+      { label: "月次売上", value: 540_000_000, format: "currency", delta: { value: 0.074, format: "percent" }, comparisonLabel: "前月比", target: 520_000_000 },
+      { label: "継続率", value: 0.982, format: { type: "percent", digits: 1 }, delta: { value: 0.004 }, comparisonLabel: "前月比", target: 0.98 },
+      { label: "新規獲得", value: 38, format: { type: "number", unit: "社" }, delta: { value: -4 }, comparisonLabel: "前月比", target: 50 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 5 個以上は描画されますが `console.warn` が出ます。スライドを分けてください。
+- 値・増減・目標は数値で渡します。整形は `format` が行い、文字を変えたいときだけ `display` を使います。
+- 「目標 …（達成率 …）」「増」「減」などの文言は block が出す日本語固定です。

package/docs/ja/slide/slide-kpi-hero.md

@@ -0,0 +1,58 @@
+# SlideKpiHero
+
+> 1 つの数字を主役にする 1 枚。値・増減・推移の線。
+
+1 つの数字を大きく見せる 1 枚です。左 6 カラムにラベルと値（と増減）、右 6 カラムに推移の線を置きます。`trend` を渡さなければ数字が全幅を使います。
+
+```tsx
+import { SlideKpiHero } from "@squadbase/vantage/slide";
+import type { SlideKpiHeroProps, SlideKpiHeroDelta } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `label` | `string` |  | 数字が何か（「月次売上」）。**必須**。 |
+| `value` | `number \| null` |  | 数値。`null` は「—」と表示される。**必須**。`format` で整形される（元の数値は `data-raw` に残り、書き出しやテストで使う）。 |
+| `format` | `ValueFormat` |  | 値の整形（`"currency"` / `"percent"` など）。`delta` の既定の整形にもなる。 |
+| `display` | `string` |  | 表示する文字だけを置き換える（元の数値は `value` のまま）。 |
+| `delta` | `SlideKpiHeroDelta` |  | `{ value: number; format?: ValueFormat }`。増減の大きさを符号付きで（例: `0.074` と `format: "percent"` で「+7.4%」）。向きは符号で決まり、▲ ▼ と「増」「減」も出る。`format` の既定は `format`。省くと増減は出ない。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | `delta` のどちらの向きが良いか。色が決まる。 |
+| `comparisonLabel` | `string` |  | `delta` の比較相手（「前月比」）。 |
+| `trend` | `{ x: string; y: number }[]` |  | 右側の線の点。省くと数字だけの 1 枚になる。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideKpiHero } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideKpiHero
+    title="9 月の売上は過去最高の 5.4 億円"
+    label="月次売上"
+    value={540_000_000}
+    format="currency"
+    delta={{ value: 0.074, format: "percent" }}
+    comparisonLabel="前月比"
+    trend={[
+      { x: "4 月", y: 460_000_000 }, { x: "5 月", y: 480_000_000 }, { x: "6 月", y: 490_000_000 },
+      { x: "7 月", y: 500_000_000 }, { x: "8 月", y: 503_000_000 }, { x: "9 月", y: 540_000_000 },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- コストのように下がることが良い指標は `betterWhen="down"` と書きます。色は `betterWhen` に従い、向き（▲ ▼ と「増」「減」）は `delta.value` の符号で決まります。
+- 「増」「減」「… 時点」「出典: …」は block が出す日本語固定の文言です。
+- グラフは `EChart` でアニメーションなし。pptx への書き出しはその描画を待ちます。

package/docs/ja/slide/slide-next-actions.md

@@ -0,0 +1,49 @@
+# SlideNextActions
+
+> 次の打ち手。担当・期限・確認する指標つきで 3〜5 件。
+
+次に何をするかを示す 1 枚で、多くのレポートの最後に置きます。アクションごとに担当・期限・確認する指標を添えられます。
+
+```tsx
+import { SlideNextActions } from "@squadbase/vantage/slide";
+import type { SlideNextActionsProps, SlideNextActionsItem } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 決定や計画を 1 文で書いた見出し。**必須**。 |
+| `items` | `SlideNextActionsItem[]` | 打ち手。3〜5 件。**必須**。各要素は下の `items[].…` の行。 |
+| `items[].action` | `string` | 何をするか（目的語から始めて 1 文。40 文字程度まで）。**必須**。 |
+| `items[].owner` | `string` | 担当。 |
+| `items[].due` | `string` | 期限。書いたまま 1 行で表示される（「10/31」。10 文字程度まで）。 |
+| `items[].metric` | `string` | 確認する指標。 |
+| `asOf` | `string` | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideNextActions } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideNextActions
+    title="解約と新規獲得の施策を 3 つ、11 月末までに始める"
+    items={[
+      { action: "解約予兆スコアの上位 50 社に CS が連絡する", owner: "CS 部 山田", due: "10/31", metric: "解約率 1.5% 以下" },
+      { action: "紹介プログラムの特典を見直す", owner: "マーケ 佐藤", due: "11/15", metric: "紹介経由の新規 20 社" },
+      { action: "料金ページの導線を改善する", owner: "プロダクト 鈴木", due: "11/30", metric: "申込率 +1pt" },
+    ]}
+  />
+</Slide>
+```
+
+## 注意
+
+- 担当・期限・確認する指標の列は、1 件でも値があるときだけ出ます。
+- 列見出し（担当 / 期限 / 確認する指標）は block が出す日本語固定で、上書きできません。
+- `due` は書いたまま表示されます（「10/31」「来週まで」）。6 件以上は `console.warn` が出ます。

package/docs/ja/slide/slide-scorecard-table.md

@@ -0,0 +1,54 @@
+# SlideScorecardTable
+
+> 指標ごとの目標と実績、状態を並べるスコアカード表。
+
+指標ごとに目標・実績・達成率と、状態（順調 / 要注意 / 遅延）を並べる表の 1 枚です。状態は色付きの点と言葉の両方で示すので、色だけに頼りません。
+
+```tsx
+import { SlideScorecardTable } from "@squadbase/vantage/slide";
+import type { SlideScorecardTableProps, SlideScorecardRow, SlideScorecardStatus } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **`<Slide>` 1 枚の中身**です。`<Slide>` 自体は持たないので、`<Slide>` の直下に置いてください。ルートはキャンバス（1920×1080）いっぱい（100%）に広がり、`className` は受けません。余白・文字サイズ・グリッドは block の中で決まっている（1920×1080 の 12 カラム）ので、寸法を足さないでください。デッキの組み方は [スライド](page-types/slide) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` |  | 結論を 1 文で書いた見出し（アクションタイトル）。**必須**。 |
+| `rows` | `SlideScorecardRow[]` |  | 行。8 行まで。**必須**。各要素は下の `rows[].…` の行。 |
+| `rows[].metric` | `string` |  | 指標名（20 文字程度まで）。**必須**。 |
+| `rows[].value` | `number \| null` |  | 実績。`null` は「—」と表示される。**必須**。 |
+| `rows[].format` | `ValueFormat` |  | `value` と `target` の整形（`"currency"` / `"percent"` など）。 |
+| `rows[].display` | `string` |  | 表示する実績の文字だけを置き換える（元の数値は `value` のまま）。 |
+| `rows[].target` | `number` |  | 目標。`format` は `value` と同じ。どれかの行に目標があると達成率の列が出る（value ÷ target）。 |
+| `rows[].betterWhen` | `"up" \| "down"` | `"up"` | どちらの向きが良いか。`"down"` なら達成率は target ÷ value になり、コストの目標を下回ると 100% を超える。 |
+| `rows[].status` | `SlideScorecardStatus` |  | `"on"`（順調）/ `"risk"`（要注意）/ `"off"`（遅延）。値から導かず、渡したものをそのまま出す。**必須**。 |
+| `columns` | `Partial<Record<"metric" \| "target" \| "actual" \| "attainment" \| "status", string>>` |  | 見出しの語を差し替える。省いた列は既定（指標 / 目標 / 実績 / 達成率 / 状態）。状態の言葉（順調 / 要注意 / 遅延）は上書きできない。 |
+| `asOf` | `string` |  | 数字を取った日。日付のみ（例: `"2026-10-01"`）。block が「2026-10-01 時点」と 1 回だけ「時点」を付けるので、「時点」は書かない。 |
+| `source` | `string` |  | 出典（例: `"社内 BI"`）。「出典: 社内 BI」と表示される。 |
+
+## 使い方
+
+```tsx
+import { Slide, SlideScorecardTable } from "@squadbase/vantage/slide";
+
+<Slide>
+  <SlideScorecardTable
+    title="4 指標のうち 2 つが目標どおり、解約と新規が遅れている"
+    rows={[
+      { metric: "月次売上", value: 540_000_000, target: 520_000_000, format: "currency", status: "on" },
+      { metric: "継続率", value: 0.982, target: 0.98, format: { type: "percent", digits: 1 }, status: "on" },
+      { metric: "解約率", value: 0.018, target: 0.015, format: { type: "percent", digits: 1 }, betterWhen: "down", status: "risk" },
+      { metric: "新規獲得", value: 38, target: 50, format: { type: "number", unit: "社" }, status: "off" },
+    ]}
+    asOf="2026-10-01"
+    source="社内 BI"
+  />
+</Slide>
+```
+
+## 注意
+
+- 7 行からは文字が本文から注記のサイズに下がります。9 行以上は描画されますが `console.warn` が出ます。

package/docs/ja/ui/empty.md

@@ -10,7 +10,7 @@ import { Empty } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `title` | `string` | `"Nothing here yet"` | 見出し。 |
+| `title` | `string` | `"表示できるデータがありません"` | 見出し。 |
 | `description` | `string` |  | 見出しの下の補足文。 |
 | `icon` | `ReactNode` |  | 見出しの上に置く絵柄。 |
 | `action` | `ReactNode` |  | 下部に置く次の一手（ボタンやリンク）。 |

package/docs/ja/ui/error-state.md

@@ -10,8 +10,9 @@ import { ErrorState } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `title` | `string` | `"Something went wrong"` | 見出し。 |
-| `message` | `ReactNode` |  | 詳細。エラーメッセージをそのまま出せます。 |
+| `title` | `string` | `"データを読み込めませんでした"` | 見出し。 |
+| `message` | `ReactNode` | `"時間をおいて再試行してください。解決しない場合は管理者にお問い合わせください。"` | 何が起きたか、次に何をすればよいかを平易な言葉で。 |
+| `details` | `ReactNode` |  | 技術的な詳細（エラーメッセージやステータスコード）。「詳細を表示」の中に折りたたまれます。 |
 | `action` | `ReactNode` |  | 再試行ボタンなど。 |
 | `className` | `string` |  | 足すクラス。 |
 
@@ -34,7 +35,7 @@ export default function Customers() {
   if (error)
     return (
       <ErrorState
-        message={error.message}
+        details={error.message}
         action={<Button variant="outline" onClick={() => refetch()}>再試行</Button>}
       />
     );

package/docs/ja/ui/loading.md

@@ -12,7 +12,7 @@ import { Loading } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `label` | `string` | `"Loading…"` | スピナーの右に出すテキスト。 |
+| `label` | `string` | `"読み込んでいます…"` | スピナーの右に出すテキスト。 |
 | `className` | `string` |  | 足すクラス。既定では最小高 30vh で縦横中央に置かれます。 |
 
 レイアウトを保ったまま待たせたいときは [`Skeleton`](ui/skeleton)、ボタンの中など