@squadbase/vantage 0.6.2 → 0.7.0-dev1.19083f7

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

@@ -0,0 +1,66 @@
+# DonutChart
+
+> 構成比を見せる型付きのドーナツ / 円グラフ。中央に合計を出す。
+
+構成比をドーナツ（または円）で描きます。**行の配列（`data`）・名前の列（`index`）・値の列（`categories`）**
+を渡すだけで描けます。ドーナツの穴には `donutOptions.centerLabel` で合計や最大の切片を出せます。中央のラベルはキャンバスではなく
+HTML なので、ページの文字色・書体のまま表示されます。配色はトークンに追従します。
+
+```tsx
+import { DonutChart } from "@squadbase/vantage/components";
+import type { DonutChartProps, DonutChartOptions, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が 1 切片。 |
+| `index` | `keyof T & string` |  | 切片の名前に使う列名。 |
+| `categories` | `(keyof T & string)[]` |  | 切片の大きさに使う列名を 1 つだけ入れた配列（`["売上"]`）。最初の 1 つだけを使う。number か数値文字列。0 以下と欠損は 0 扱い。 |
+| `colors` | `ChartSeriesColor[]` | `トークン順` | 切片の色（大きい順）。`"chart-1"`〜`"chart-5"` か意味色。「その他」は常に灰色。 |
+| `labels` | `Record<string, string>` |  | 切片の名前（`index` の値）→ 表示名。凡例・ツールチップ・データ表に反映。 |
+| `donutOptions` | `DonutChartOptions` |  | ドーナツ固有の設定。`{ variant, centerLabel, totalLabel, unit, showLegend, maxSlices }`（下の表）。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` などか `{ type, digits, unit, … }`。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | 1 文の要約。`"auto"` なら slices から「最大は <名前>（<構成比>）」を組む。順位や構成比を文に書くなら `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。 |
+| `showTooltip` | `boolean` | `true` | ホバーで名前・値・構成比を出す。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 切片のクリックで呼ばれる。行に `eventType: "slice"` と `categoryClicked`（切片名）を足して渡し、同じ切片をもう一度押すと `null`。 |
+| `ariaLabel` | `string` |  | チャートの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。大きさは `height`（既定 288px）で決める。幅は親に合わせて広がる。 |
+
+### donutOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `variant` | `"donut" \| "pie"` | `"donut"` | 穴あきか、円か。 |
+| `centerLabel` | `"none" \| "total" \| "top" \| ReactNode` | `"none"` | 穴の中央に出すもの。`"total"` は合計、`"top"` は最大の切片の名前と構成比。ノードを渡すとそのまま置く。donut のみ。合計は KPI と重複しがちなので既定は出さない。 |
+| `totalLabel` | `string` | `"合計"` | `"total"` の見出し。 |
+| `unit` | `string` |  | `"total"` の合計に添える単位（`"セッション"`）。 |
+| `showLegend` | `boolean` | `true` | 凡例（名前と構成比、大きい順）を出す。広いときは右、狭いときは下。消すと、広いときだけ大きい 2 切片に外ラベルが出る。 |
+| `maxSlices` | `number` | `5` | 個別に描く切片の数。超えた分は「その他」1 切片にまとめる。 |
+
+> [!NOTE]
+> 旧 props は**非推奨**です。`category` → `index`、`value` → `categories={[value]}`、`variant` → `donutOptions.variant`、`label` / `showLabel` → `donutOptions.centerLabel`、`loading` → `isLoading`。
+
+## 凡例と中央のラベル
+
+名前と構成比を並べた凡例が付きます（広いときは右、狭いときは下）。消すには
+`donutOptions={{ showLegend: false }}`。穴の中央には `centerLabel` で合計や最大の切片を出せます。
+
+```tsx
+<DonutChart
+  data={rows}
+  index="channel"
+  categories={["sessions"]}
+  donutOptions={{ centerLabel: "total", unit: "セッション" }}
+/>
+```
+
+> [!NOTE]
+> 切片が 5 つを超えると、小さい切片は「その他」にまとまります（`donutOptions.maxSlices` で変えられます）。

package/docs/ja/parts/echart.md

@@ -7,6 +7,9 @@ Apache ECharts をそのまま使えるようにした薄いラッパーです
 系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから組まれ、
 ライト / ダークの切り替えにも追いかけます。
 
+> [!TIP]
+> まず型付きグラフ（[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)・[`LineChart`](parts/line-chart)・[`DonutChart`](parts/donut-chart)）を使い、二軸・散布図・ヒートマップなど細かい制御が要るときだけ `EChart` に option を書いてください。
+
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
 import type { EChartsOption } from "@squadbase/vantage/components";

package/docs/ja/parts/format.md

@@ -0,0 +1,44 @@
+# format / comparison
+
+> KPI・表・グラフで共有する数値の書式（formatValue）と、増減の計算（computeComparison）。
+
+`KpiCard` / `Delta` が内部で使っている数値の書式と比較の計算を、そのまま関数として使えます。表の
+セルやグラフの `valueFormatter` を KPI と同じ書式に揃えたいときに使ってください。短縮（「4.8億」
+など）は `Intl.NumberFormat` に任せており、単位の文字列を自前で持ちません。
+
+```tsx
+import {
+  formatValue,
+  formatDelta,
+  toValueFormatter,
+  computeComparison,
+} from "@squadbase/vantage/components";
+import type { ValueFormat, Comparison, ComparisonResult } from "@squadbase/vantage/components";
+```
+
+## ValueFormat
+
+`"number" | "compact" | "currency" | "percent" | "multiple"` のどれか、または
+`{ type, digits?, currency? }`。既定は `"compact"`、通貨の既定は `JPY`、ロケールの既定は `"ja-JP"`。
+`percent` は比率（`0.124` → 12.4%）を受け取ります。値が `null` / `undefined` / `NaN` のときは「—」を
+返します。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `formatValue(value, format?, locale?)` | `string` | 値を書式化する。 |
+| `formatDelta(value, format?, locale?)` | `string` | 差分用。0 以外は常に符号が付く（`+12.4%`）。 |
+| `toValueFormatter(format?, locale?)` | `(value) => string` | 書式とロケールを束ねた 1 引数の関数。グラフの `valueFormatter` に渡せる。 |
+
+```tsx
+formatValue(48_200_000, "currency");                // "￥48,200,000"
+formatValue(0.021, { type: "percent", digits: 1 }); // "2.1%"
+<LineChart valueFormatter={toValueFormatter("compact")} … />
+```
+
+## computeComparison
+
+`computeComparison(current, comparison, { polarity?, neutralBand? })` が
+`{ current, previous, difference, ratio, direction, sentiment, label, vs }` を返します。率は前の値が
+0 でない数のときだけ出し、`neutralBand`（既定 0.01）未満の変化は `direction: "flat"` になります。
+`sentiment`（`"positive" | "negative" | "neutral"`）は `polarity` で決まります。表示は
+[`Delta`](parts/delta) に任せ、自前で矢印や色を組まないでください。

package/docs/ja/parts/funnel-steps.md

@@ -7,27 +7,46 @@
 
 ```tsx
 import { FunnelSteps, funnelStepsVariants } from "@squadbase/vantage/components";
-import type { FunnelStep } from "@squadbase/vantage/components";
+import type { FunnelStep, ChartColorToken } from "@squadbase/vantage/components";
 ```
 
 | Prop | Type | Default | 説明 |
 | --- | --- | --- | --- |
-| `data` | `FunnelStep[]` |  | 各段。**先頭が最大幅**になる。 |
-| `showConversion` | `boolean` |  | 段の間に転換率を出す。 |
-| `formatValue` | `(value: number) => string` |  | 値の書式。既定はそのまま。 |
-| `animate` | `boolean` |  | マウント時に幅を伸ばすアニメーション。 |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
-| `direction` | `"vertical" \| "horizontal"` | `"vertical"` |  |
+| `data` | `T[]` |  | 各段。**必須**。**先頭が最大幅**になる。`index` / `categories` を省くと `{ label, value }` の形として読む。 |
+| `index` | `keyof T & string` | `"label"` | ステップのラベルに使う列名。 |
+| `categories` | `(keyof T & string)[]` | `["value"]` | 値に使う列名を 1 つだけ入れた配列。最初の 1 つだけを使う。 |
+| `colors` | `ChartColorToken[]` |  | 段の色（`"chart-1"`〜`"chart-5"`、段の順に繰り返す）。省略時はすべて `"chart-1"`（段は同じ量の絞り込みなので 1 色）。 |
+| `labels` | `Record<string, string>` |  | ステップの名前（`index` の値）→ 表示名。ラベルとデータ表に反映。 |
+| `highlight` | `string` |  | 伝えたい 1 段。`index` の値で渡す。この 1 段だけ濃い色になる（他は淡い色）。 |
+| `showConversion` | `boolean` |  | 段の間に転換率を出す。最も低い転換率だけが強調される。 |
+| `comparison` | `{ values: readonly (number \| null)[]; label?: string }` |  | 前期の各段の値（`data` と同じ順）。渡すと転換率の横に前期比（pt）を出し、最も下がった率を強調する。`label` の既定は「前期」。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` などか `{ type, digits, unit, … }`。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string` |  | 1 文の要約。見出しの下に出す。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。`title` の既定は「表示できるデータがありません」。 |
+| `animate` | `boolean` | `false` | マウント時に幅を伸ばすアニメーション。 |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 段の大きさ。 |
+| `direction` | `"vertical" \| "horizontal"` | `"vertical"` | 並べる向き。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは段数で決まる（`height` は持たない）。 |
 
 ## FunnelStep
 
+`index` / `categories` を省いたときに読まれる行の形です。
+
 ```ts
 interface FunnelStep {
   label: string;
   value: number;
-  color?: string; // 既定はテーマの chart 色
   onClick?: () => void;
+  /** @deprecated Tailwind の bg クラス。`colors` を使う。 */
+  color?: string;
 }
 ```
 
 `onClick` を渡した段は押せるようになるので、その段の内訳へドリルダウンさせられます。
+
+> [!NOTE]
+> `formatValue` は**非推奨**です。`valueFormatter`（関数）か `format`（`"compact"` など）を使ってください。

package/docs/ja/parts/heatmap.md

@@ -0,0 +1,45 @@
+# Heatmap
+
+> 2 つのカテゴリの掛け合わせを濃淡で見せる型付きのヒートマップ。曜日 × 時間帯やコホートの継続率に。
+
+マス目の濃さで値の大小を見せます。**行の配列（`data`）・横軸の列（`x`）・縦軸の列（`y`）・濃さを決める数値の列
+（`value`）**を渡すだけで描けます。配色は 1 色の薄い → 濃いのグラデーション（既定 `--chart-1`）で、
+レインボーにはしません。値が無いマスは塗らず、0 とは区別します（ツールチップとデータ表は「—」）。
+
+```tsx
+import { Heatmap } from "@squadbase/vantage/components";
+import type { HeatmapProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `Record<string, unknown>[]` |  | 行の配列。**必須**。1 行が 1 マス（x と y の組）。同じ組が複数あれば後の行が勝つ。 |
+| `x` | `string` |  | 横軸（列）に使う列名。**必須**。 |
+| `y` | `string` |  | 縦軸（行）に使う列名。**必須**。先頭の行が一番上。 |
+| `value` | `string` |  | マスの濃さを決める数値の列名。**必須**。null・欠損・数値でない値のマスは塗らない。 |
+| `xLabels` | `string[]` |  | 横軸の並び順（と表示するマス）。省略時は `data` の出現順。ここに無い x の行は描かない。 |
+| `yLabels` | `string[]` |  | 縦軸の並び順（と表示するマス）。省略時は `data` の出現順。 |
+| `labels` | `Record<string, string>` |  | 列名・軸の値 → 表示名（軸・ツールチップ・データ表）。 |
+| `format` | `ValueFormat` | `"number"` | 数値の書式（`"percent"` や `{ type: "number", unit: "件" }` など）。マス内・ツールチップ・データ表で同じ。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先。 |
+| `tone` | `ChartSeriesColor` | `"chart-1"` | 濃淡の色。`"chart-1"`〜`"chart-5"` か意味色（`positive` / `warning` / `negative` / `neutral`）。 |
+| `scale` | `{ min?: number; max?: number }` |  | 濃さの固定スケール。省略時はデータの最小〜最大。継続率なら `{ min: 0, max: 100 }`。比べたい範囲が決まっているときだけ渡す。凡例の両端もこの値になる。 |
+| `showValues` | `boolean` | `false` | マスの中に値を書く。 |
+| `showLegend` | `boolean` | `true` | 凡例（薄い → 濃いの帯と両端の値）を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `details` | `string[]` |  | ツールチップとデータ表に添える同じ行の別の数値列。「SLA 未達 2件」のように出る。 |
+| `flag` | `string` |  | この列が真（`true` / 0 でない数）の行のマスに、注意色（`--negative`）の枠を付ける。ツールチップにも「要注意」と出る。 |
+| `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` |  | スクリーンリーダー向けのラベル。省略時は「<y の列>×<x の列>のヒートマップ」。 |
+
+> [!NOTE]
+> 濃さはデータの範囲に合わせて決まります。別々のヒートマップを並べて比べるときは、全部に同じ `scale` を
+> 渡してください。`minValue` / `maxValue` は非推奨で、`scale` を使います。

package/docs/ja/parts/kpi-card.md

@@ -0,0 +1,56 @@
+# KpiCard
+
+> KPI 1 つ分のカード。値・増減・前期実績・結論の 1 文までを数値から組み立てる。
+
+KPI を 1 つ見せるカードです。**数値と列挙値だけを渡せば**、上から「指標名 → 値 → 増減
+（[`Delta`](parts/delta)）→ 前期の実績 → 結論の 1 文」の順に組み立てます。増減の向き・率・
+色・目標までの残り・達成率・記録更新はすべてカードの中で計算するので、props どうしが食い違うことは
+ありません。KPI タイルは `DashboardCardPreset` + `MetricValue` で組むより、まずこれを使ってください。
+
+```tsx
+import { KpiCard } from "@squadbase/vantage/components";
+import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `label` | `string` |  | 指標名。**必須**。 |
+| `value` | `number \| null \| undefined` |  | 現在の値。**必須**。`null` / `undefined` は「—」と表示する。 |
+| `format` | `ValueFormat` | `"compact"` | 値の書式（→ format / comparison のページ）。前期実績・目標・残りにも同じ書式を使う。 |
+| `locale` | `string` | `"ja-JP"` | 書式のロケール。 |
+| `comparison` | `Comparison` |  | 比較の相手（`{ previous, vs, label? }`）。渡すと増減と前期実績の行が出る。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率のように下がる方が良い指標は `"down"`。`polarity` より優先される。 |
+| `polarity` | `"higher-is-better" \| "lower-is-better" \| "neutral"` | `"higher-is-better"` | 非推奨。`betterWhen` の古い名前。`"neutral"`（良し悪しの色をつけない）はこちらからだけ渡せる。 |
+| `neutralBand` | `number` | `0.01` | 変化率の絶対値がこれ未満なら横ばいとして扱う。 |
+| `showPrevious` | `boolean` | `true` | 前期の実績（「前期 400」）を出すか。`comparison` が要る。 |
+| `summary` | `string` |  | 結論の 1 文の**テンプレート**。下のプレースホルダをカードが埋める。 |
+| `target` | `number` |  | 今期の目標。「目標まであと …（… 達成）」の行が出る。 |
+| `period` | `{ start: Date \| string \| number; end: Date \| string \| number }` |  | 今期の期間。`target` と一緒に渡すと、期間中は「見込み」（このペースなら期末いくつ）が出る。 |
+| `history` | `ReadonlyArray<number \| null \| undefined>` |  | 今期で終わる系列（最後の点 = `value`）。記録更新のバッジが出る。 |
+| `historyGrain` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | `"month"` | `history` の粒度。 |
+| `source` | `{ period?: string; count?: number; name?: string }` |  | データの出所の注記（「2023-04 以降・48,210 件から集計・Snowflake」）。 |
+| `updatedAt` | `Date \| string \| number` |  | 最終更新時刻。「3 分前に更新」と出る。 |
+| `now` | `Date \| number` |  | 見込みと相対時刻の基準時刻（表示を固定したいとき）。 |
+| `isLoading` | `boolean` | `false` | 値の代わりに、完成形と同じ形のスケルトンを出す。 |
+| `className` | `string` |  | 足すクラス。 |
+
+## summary のプレースホルダ
+
+`{value}` `{delta}` `{difference}` `{previous}` `{label}` `{target}` `{achievement}` `{remaining}` が
+使えます。知らない名前はそのまま残り、値が無いものは「—」になります。
+
+> [!WARNING]
+> **テンプレートに数値を直接書かないでください。** 数値はすべてプレースホルダで差し込みます —
+> 値が変わっても文が古くならないようにするためです。
+
+```tsx
+<KpiCard
+  label="売上"
+  value={48_200_000}
+  format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }}
+  summary="{label}は前月から {difference}（{delta}）伸びています。"
+/>
+```
+
+増減だけを表やタイルの中に置きたいときは [`Delta`](parts/delta) を単体で使います。

package/docs/ja/parts/legend.md

@@ -0,0 +1,36 @@
+# Legend
+
+> 複数のグラフで共有する、HTML だけの独立した凡例。
+
+複数のグラフで同じ系列を見せるとき、各グラフの凡例を消して、凡例を 1 つにまとめます。**系列名の配列
+（`categories`）**を渡すだけで、`DonutChart` と同じ見た目（角丸の色見本と名前）の凡例が出ます。色はグラフと
+同じ関数で決まるので、グラフに渡した `categories` / `colors` / `labels` と同じ値を渡せば食い違いません。
+キャンバスも SVG も使わない HTML です。
+
+```tsx
+import { Legend } from "@squadbase/vantage/components";
+import type { LegendProps } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `categories` | `string[]` |  | 凡例に並べる系列名。**必須**。並び順が配色の順。空配列なら何も描かない。6 つ以上はグラフ側で「その他」にまとまるので、凡例も 5 つ +「その他」で渡す。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `["chart-1", …, "chart-5"]` | 系列色。`"chart-1"`〜`"chart-5"` か意味色。配列は系列の順、record は系列名ごと。「その他」は常に灰色。意味色は棒の面の色（`--warning-fill` など）で出る。 |
+| `labels` | `Record<string, string>` |  | 系列名 → 表示名。グラフの `labels` と同じものを渡す。 |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | 並べ方。`horizontal` は折り返す横並び、`vertical` は縦並び。 |
+| `ariaLabel` | `string` | `"凡例"` | 凡例の読み上げ名。 |
+| `className` | `string` |  | `<ul>` に足すクラス。 |
+
+## グラフの凡例を消す
+
+共有する側のグラフには `showLegend={false}` を渡します。
+
+```tsx
+<Legend categories={["東京店", "大阪店", "名古屋店"]} />
+<LineChart data={sales} index="month" categories={stores} showLegend={false} />
+<BarChart data={visitors} index="month" categories={stores} showLegend={false} />
+```
+
+> [!NOTE]
+> グラフに `colors` を渡しているときは、`Legend` にも同じ `colors` を渡してください。省略するとトークン順の
+> 色になり、グラフと食い違います。

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

@@ -0,0 +1,84 @@
+# LineChart
+
+> 推移を線で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。
+
+時系列の推移を折れ線で描きます。**行の配列（`data`）・x 軸の列名（`index`）・系列の列名（`categories`）**
+を渡すだけで、凡例・ツールチップ・軸の書式まで揃います。配色はトークンに追従します。中身は
+[`EChart`](parts/echart) です。
+
+```tsx
+import { LineChart } from "@squadbase/vantage/components";
+import type { LineChartProps, ChartSeriesColor, ChartEventPayload } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `data` | `T[]` |  | 行の配列。**必須**。1 行が x 軸の 1 点。数値の列は number か数値文字列（SQL の DECIMAL など）で、それ以外は欠損として扱う。 |
+| `index` | `keyof T & string` |  | x 軸に使う列名。**必須**。 |
+| `categories` | `NumericKeys<T>[]` |  | 系列として描く列名（数値の列だけ渡せる）。**必須**。この順が凡例と配色の順。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 |
+| `colors` | `ChartSeriesColor[] \| Record<string, ChartSeriesColor>` | `トークン順` | 系列色。`"chart-1"`〜`"chart-5"`（ライト / ダークに追従）か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`。配列は系列の順、record は系列名ごと。CSS カラーは渡せない。 |
+| `labels` | `Record<string, string>` |  | `index` の値・系列名 → 表示名（軸・凡例・ツールチップ・データ表に反映）。例 `{ jan: "1 月", sales: "売上" }`。 |
+| `format` | `ValueFormat` | `"compact"` | 数値の書式。`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、または `{ type, digits, currency, notation, unit, divisor, durationUnit }`。軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。 |
+| `valueFormatter` | `(value: number) => string` |  | 書式を関数で直接渡す逃げ道。`format` より優先する。 |
+| `lineOptions` | `LineChartOptions` |  | 折れ線固有の設定。`{ curveType, connectNulls, fitToData, targetLabelPosition }`（下の表）。 |
+| `forecast` | `{ data: ChartForecastRow[]; category?: string; label?: string }` |  | 予測。最初の系列（または `category`）の続きを点線と薄い帯で描く。`data` の行は実績と同じ `index` のキーに、`value`（と任意の `lower` / `upper`）を持つ。`label` の既定は「予測」。 |
+| `comparison` | `{ category: string; vs: "prior-period" \| "prior-year" \| "target" \| "custom"; label?: string }` |  | 比較系列。`categories` のうち 1 つを「前年」「計画」などの比較の線にする（細い灰色の実線）。ツールチップに主系列の差を添える。`vs: "custom"` では `label` が必須。 |
+| `highlight` | `"auto" \| "none"` |  | 最大値と最新値に値ラベルを付ける（最初の系列だけ・系列が 2 つ以下のときだけ）。既定は Line / Area が `"auto"`、Bar は `index` が日付・年月・年のときだけ `"auto"`。 |
+| `provisionalFrom` | `string \| number` |  | ここから先は確定前（速報）の点。`index` の値で渡す。薄い色・点線で描き、凡例とツールチップに `provisionalLabel` を出す。 |
+| `provisionalLabel` | `string` | `"速報"` | 速報の呼び名（凡例・ツールチップ）。 |
+| `target` | `number` |  | 目標値。点線の水平線で示し、値軸は必ずこの値を含む。 |
+| `targetLabel` | `string` | `「目標 <書式化した値>」` | 目標線のラベル。 |
+| `annotations` | `ChartAnnotation[]` |  | 任意の位置への注記。`{ at, label }` は縦線、`to` を足すと `at`〜`to` の区間の帯。`at` / `to` は `index` の値。横棒では描かない。 |
+| `showLegend` | `boolean` | `true` | 凡例を出す。 |
+| `showTooltip` | `boolean` | `true` | ホバーでツールチップを出す。 |
+| `showGridLines` | `boolean` | `true` | 値軸の目盛り線。 |
+| `showXAxis` | `boolean` | `true` | x 軸を出す。 |
+| `showYAxis` | `boolean` | `true` | y 軸を出す。 |
+| `startEndOnly` | `boolean` | `false` | x 軸のラベルを最初と最後だけにする。 |
+| `yAxisWidth` | `number` |  | y 軸ラベルの幅（px）。縦に並べた複数のグラフでプロット領域を揃えたいときに固定する。 |
+| `minValue` | `number` |  | 値軸の下限。指定した値から始める。データが下限を下回るときは軸を広げる。 |
+| `maxValue` | `number` |  | 値軸の上限（横棒は横軸）。データが上限を超えるときは軸を広げる。並べて比べる複数のグラフには同じ値を渡して軸をそろえる。 |
+| `allowDecimals` | `boolean` | `true` | `false` で値軸の目盛りを整数に限る。 |
+| `xAxisLabel` | `string` |  | x 軸の名前。 |
+| `yAxisLabel` | `string` |  | y 軸の名前。 |
+| `onValueChange` | `(value: ChartEventPayload) => void` |  | 点（棒）のクリックで呼ばれる。クリックした行に `eventType` と `categoryClicked`（系列名）を足して渡し、同じ点をもう一度押すと `null`。渡すと選択以外が薄くなる。 |
+| `title` | `string` |  | グラフの見出し。 |
+| `summary` | `string \| "auto"` |  | グラフが言っていることの 1 文要約。見出しの下に出す。`"auto"` なら data から機械的に組む。向きの言い回しを手書きすると data とずれるので `"auto"` を使う。 |
+| `isLoading` | `boolean` |  | 読み込み中。最終形と同じ形・高さのスケルトンを出す。 |
+| `emptyState` | `{ title?: string; description?: string; action?: ReactNode }` |  | `data` が空のときの表示。高さは保たれる。`title` の既定は「表示できるデータがありません」。 |
+| `height` | `number` | `288` | プロット領域の高さ（px）。文字列（CSS の長さ）は互換のために受けるだけで非推奨。 |
+| `chartOptions` | `EChartsOption` |  | 生成した ECharts の option に最後に深くマージする逃げ道。 |
+| `actions` | `boolean \| { includeTitle?: boolean }` | `false` | 右上に PNG の保存 / コピーのボタンを出す（ホバー時）。`title` / `summary` は画像の上に含まれる。含めないなら `{ includeTitle: false }`。 |
+| `fileName` | `string` | `"chart.png"` | PNG 保存時のファイル名（拡張子つき）。`actions` と使う。 |
+| `ariaLabel` | `string` |  | グラフの説明（スクリーンリーダー向け）。見出しがあればそちらが使われる。 |
+| `className` | `string` |  | 外側の `<figure>` に足すクラス。高さは `height` で決める。 |
+
+### lineOptions
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `curveType` | `"linear" \| "smooth" \| "step"` | `"linear"` | 線の形。 |
+| `connectNulls` | `boolean` | `false` | 値の欠けた点（`null` など）をまたいで線をつなぐ。 |
+| `fitToData` | `boolean` | `false` | 値軸を 0 からではなくデータの範囲に合わせる。 |
+| `targetLabelPosition` | `"start" \| "end" \| "legend"` | `"start"` | 目標線（`target`）のラベルの置き場所。`"legend"` は凡例だけに出し、線の上には出さない。 |
+
+> [!NOTE]
+> `curveType` / `connectNulls` をグラフの props に直接渡す書き方、`autoMinValue`（`lineOptions.fitToData` を使う）、`loading`（`isLoading` を使う）は**非推奨**です。
+
+> [!NOTE]
+> `colors` は Tailwind のクラスではなく**テーマの色名**（`"chart-1"`〜`"chart-5"`、意味色）です。
+> ライト / ダークに追従します。任意の CSS カラーは渡せません。軸・凡例・ツールチップの色はいつもテーマから入ります。
+
+## 欠損のある系列
+
+値が `null`・空文字・数値でない文字列の点は欠損として扱い、線が途切れます。`lineOptions={{ connectNulls: true }}` を
+付けると欠損をまたいでつなぎます。
+
+```tsx
+<LineChart data={rows} index="date" categories={["CVR"]} lineOptions={{ connectNulls: true }} valueFormatter={(v) => `${v}%`} />
+```
+
+## EChart との使い分け
+
+まずこの型付きグラフで描き、二軸・散布図・ヒートマップ・注釈線など**この props で表せないもの
+だけ** [`EChart`](parts/echart) に option を書いてください。

package/docs/ja/parts/metric-value.md

@@ -2,7 +2,8 @@
 
 > KPI の数値。単位は MetricUnit で。
 
-KPI の数値を大きく見せるための、字送りを詰めた表示です。単位や補助的な文字は `MetricUnit` で
+KPI の数値を大きく見せるための、字送りを詰めた表示です。KPI のタイルを 1 枚作るなら、増減や前期実績まで
+出せる [`KpiCard`](parts/kpi-card) を先に検討してください。単位や補助的な文字は `MetricUnit` で
 添えます。
 
 ```tsx
@@ -20,6 +21,6 @@ import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage
 ```tsx
 <DashboardCardPreset title="売上">
   <MetricValue className="my-0">¥1,240,000</MetricValue>
-  <TrendIndicator value={12.4} direction="up" />
+  <Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
 </DashboardCardPreset>
 ```

package/docs/ja/parts/page-shell.md

@@ -27,7 +27,7 @@ import {
 | パーツ | 役割 |
 | --- | --- |
 | `PageShell` | 全体の縦積み |
-| `PageShellHeader` | 下線付きのヘッダー帯。左に見出し、右に `HeaderEnd` の 2 列 |
+| `PageShellHeader` | 下線付きのヘッダー帯。左に見出し、右に `HeaderEnd`。幅が足りないと `HeaderEnd` は見出しの下へ回り込む |
 | `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | 見出しブロック |
 | `PageShellHeaderEnd` | 右端の縦積み |
 | `PageShellMeta` | 「最終更新 10 分前」のような補足 |

package/docs/ja/parts/progress-circle.md

@@ -0,0 +1,34 @@
+# ProgressCircle
+
+> 目標に対する達成率をリングで示す。中央に任意の内容を置ける。
+
+`value / max` の割合だけリングを塗ります。children は中央に置かれるので、達成率の数値や
+アイコンを入れます。単一の `<svg>` で、KPI タイルに並べても軽いままです。
+
+```tsx
+import { ProgressCircle } from "@squadbase/vantage/components";
+import type { ChartColor } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number` | `0` | 現在値。`0`〜`max` に丸める。 |
+| `max` | `number` | `100` | 満タンの値。 |
+| `radius` | `number` | `32` | 外側の半径（px）。全体は `radius * 2` 四方。 |
+| `strokeWidth` | `number` | `6` | 線の太さ（px）。 |
+| `color` | `ChartColor` | `"chart-1"` | `"chart-1"`〜`"chart-5"` か CSS カラー。地のリングは同じ色を淡くしたもの。 |
+| `showAnimation` | `boolean` | `true` | マウント時と値の変化をアニメーションする。 |
+| `children` | `ReactNode` |  | 中央に置く内容（例: `72%`）。 |
+| `className` | `string` |  | 足すクラス。 |
+
+残りの props は外側の `<div>` にそのまま渡ります。`role="progressbar"` と `aria-valuenow` が付きます。
+
+## 値の書式は呼び出し側で
+
+中央の表示は children そのものです。割合ではなく実数を見せたいときも、そのまま書いてください。
+
+```tsx
+<ProgressCircle value={3_400_000} max={5_000_000} radius={40} strokeWidth={8}>
+  <span className="text-xs">340万</span>
+</ProgressCircle>
+```

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/sparkline.md

@@ -38,10 +38,10 @@ import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/co
 
 ## EChart との使い分け
 
-軸・凡例・ツールチップ・複数系列が要るなら [`EChart`](parts/echart) を使います。
+軸・凡例・ツールチップ・複数系列が要るなら、まず型付きグラフ（[`LineChart`](parts/line-chart)・[`AreaChart`](parts/area-chart)・[`BarChart`](parts/bar-chart)）を使い、細かい制御が要るときだけ [`EChart`](parts/echart) を使います。
 `Sparkline` が持つのは「値の並びの形」だけで、**目盛りも数値も出しません**。
 
 > [!NOTE]
 > `aria-hidden="true"` が付いているため、スクリーンリーダーには読まれません。実際の数値は
 > [`MetricValue`](parts/metric-value) や
-> [`TrendIndicator`](parts/trend-indicator) など、テキストとして隣に置いてください。
+> [`Delta`](parts/delta) など、テキストとして隣に置いてください。