@squadbase/vantage 0.6.2-dev1.b332e5a → 0.6.2-dev1.d7c0911

package/dist/components/index.d.ts

@@ -1,17 +1,47 @@
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import * as React from 'react';
-import { HTMLAttributes, ComponentType, ReactNode, ElementType, ComponentProps, SVGAttributes } from 'react';
+import { HTMLAttributes, ReactNode, ComponentType, ElementType, Ref, ReactElement, ComponentProps, SVGAttributes } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { EChartsOption } from 'echarts';
 export { EChartsOption } from 'echarts';
-import { ColumnDef, SortingState, OnChangeFn, ColumnFiltersState, PaginationState, RowSelectionState, VisibilityState, TableMeta, Table } from '@tanstack/react-table';
+import { RowData, ColumnDef, SortingState, OnChangeFn, ColumnFiltersState, PaginationState, RowSelectionState, VisibilityState, TableMeta, Table } from '@tanstack/react-table';
 export { ColumnDef, ColumnFiltersState, PaginationState, RowSelectionState, SortingState, VisibilityState } from '@tanstack/react-table';
 export { DateRange as RdpDateRange } from 'react-day-picker';
 
+interface UpdatedAtProps {
+    /** When the data was last updated. */
+    at: Date | string | number;
+    /** `"relative"` (default): "23 分前に更新". `"absolute-first"`: "16:41 更新（23 分前）" — for pages where "now" matters. */
+    variant?: "relative" | "absolute-first";
+    /** IANA time zone (e.g. `"Asia/Tokyo"`) for the absolute time. Defaults to the runtime's zone. */
+    timeZone?: string;
+    /** Text placed before the label, e.g. `"売上データ: "`. */
+    prefix?: string;
+    /** Fixed "current time" for tests and fixtures. Disables the 60 s refresh. */
+    now?: Date | number;
+    className?: string;
+}
+declare const UpdatedAt: React.ForwardRefExoticComponent<UpdatedAtProps & React.RefAttributes<HTMLTimeElement>>;
+
 interface PageShellProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLDivElement>>;
 interface PageShellHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** When the data was last updated. Drawn by `UpdatedAt` at the right end of the title row. */
+    updatedAt?: UpdatedAtProps["at"];
+    /** `"relative"` (default) or `"absolute-first"` ("16:41 更新（23 分前）") for pages where "now" matters. */
+    updatedAtVariant?: UpdatedAtProps["variant"];
+    /** IANA time zone for the absolute time of `updatedAt`. Defaults to the runtime's zone. */
+    timeZone?: string;
+    /** Where the data comes from. Shown as a chip "出典：○○" on the second row. */
+    source?: string;
+    /** The period the data covers. Shown as a chip "2026/9/23〜10/20" on the second row. */
+    period?: {
+        start: Date | string | number;
+        end: Date | string | number;
+    };
+    /** The page's overall state (an alert, a status badge). Shown on the third row; no row when absent. */
+    status?: ReactNode;
 }
 /**
  * A wrapping flex row, not a two-column grid: when the heading cannot keep its
@@ -19,6 +49,11 @@ interface PageShellHeaderProps extends HTMLAttributes<HTMLDivElement> {
  * `1fr auto` grid would instead hand the heading whatever the end block leaves,
  * and a CJK title — breakable between any two characters — collapses into a
  * one-character column.
+ *
+ * The meta props (`updatedAt`, `source`, `period`, `status`) fix the order every
+ * page head shares: title and update time (right end) → source / period chips →
+ * overall status → summary cards. Empty rows are not drawn. Rows are placed with
+ * flex `order`, so they land before `PageShellSummary` whatever the child order.
  */
 declare const PageShellHeader: React.ForwardRefExoticComponent<PageShellHeaderProps & React.RefAttributes<HTMLDivElement>>;
 interface PageShellHeadingProps extends HTMLAttributes<HTMLDivElement> {
@@ -42,13 +77,8 @@ declare const PageShellActions: React.ForwardRefExoticComponent<PageShellActions
 interface PageShellSummaryProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare const PageShellSummary: React.ForwardRefExoticComponent<PageShellSummaryProps & React.RefAttributes<HTMLDivElement>>;
-/**
- * Accent colours are spelled out one utility set per colour rather than built
- * from a template string — Tailwind only emits classes it can see literally in
- * the source.
- */
 declare const pageShellSummaryCardVariants: (props?: ({
-    accent?: "accent" | "default" | "amber" | "blue" | "emerald" | "red" | "violet" | "orange" | "cyan" | "slate" | "green" | "teal" | "sky" | "indigo" | "purple" | "pink" | "rose" | "yellow" | "lime" | "gray" | "zinc" | "neutral" | "stone" | "fuchsia" | null | undefined;
+    accent?: "default" | "accent" | "amber" | "blue" | "emerald" | "red" | "violet" | "orange" | "cyan" | "slate" | "green" | "teal" | "sky" | "indigo" | "purple" | "pink" | "rose" | "yellow" | "lime" | "gray" | "zinc" | "neutral" | "stone" | "fuchsia" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface PageShellSummaryCardProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof pageShellSummaryCardVariants> {
 }
@@ -57,6 +87,248 @@ interface PageShellContentProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare const PageShellContent: React.ForwardRefExoticComponent<PageShellContentProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Locale-aware number formatting shared by KPI cards, tables and charts. All
+ * shortening is delegated to `Intl.NumberFormat` (`notation: "compact"`); this
+ * module never hard-codes unit thresholds or unit strings.
+ *
+ * | `format`                                   | input        | ja-JP output   |
+ * |--------------------------------------------|--------------|----------------|
+ * | `"compact"` (default)                      | `48_200_000` | `4,820万`      |
+ * | `"number"`                                 | `1234.567`   | `1,234.57`     |
+ * | `"currency"` (JPY, compact)                | `48_200_000` | `¥4,820万`     |
+ * | `{ type: "currency", notation: "standard" }` | `48_200_000` | `¥48,200,000`  |
+ * | `{ type: "currency", currency: "USD" }`    | `1234.5`     | `$1,234.5`     |
+ * | `"percent"` — pass a **ratio**             | `0.124`      | `12.4%`        |
+ * | `{ type: "percent", digits: 0 }`           | `0.124`      | `12%`          |
+ * | `"multiple"`                               | `1.5`        | `1.5×`         |
+ * | `{ type: "number", unit: "件" }`           | `48_210`     | `48,210件`     |
+ * | `{ type: "compact", unit: "人" }`          | `12_345`     | `1.2万人`      |
+ * | `"duration"` — pass **seconds**            | `12_000`     | `3時間20分`    |
+ * | `{ type: "duration", durationUnit: "minute" }` | `2160`   | `1.5日`        |
+ *
+ * - `percent` takes a ratio (0.124 → 12.4%). Passing 12.4 renders 1,240%. The fraction
+ *   digits are **fixed**, never trimmed (`PERCENT_DIGITS` = 1: 0.14 → "14.0%", never "14%"
+ *   beside "11.9%"). Pass `digits` in the format to share another count across cards.
+ * - A minus sign is always U+2212 (`MINUS_SIGN`, "−1,234" / "−5.0%"), never the hyphen-minus.
+ * - `currency` defaults to JPY and to compact notation (万・億 in ja); pass
+ *   `notation: "standard"` for every digit (tables, invoices). In ja-JP the yen
+ *   sign is the half-width `¥`.
+ * - `unit` is a counter appended right after the number, with no space
+ *   ("48,210件", "1.2万人"), for `number` / `compact` / `currency`. It is
+ *   ignored for `percent` and `duration`, and for `multiple` it replaces the
+ *   default `×` ("2.7倍"). Do not write it into a `valueFormatter` by hand.
+ * - Charts take the same `format` a KpiCard takes (`format="currency"`).
+ *   `toValueFormatter(format)` turns it into a function for places that need
+ *   one (a `valueFormatter`, table cells).
+ * - Missing values (null / undefined / NaN) render as `—` (`EMPTY_VALUE`).
+ * - Dates go through `formatDate` (`Intl.DateTimeFormat`): `"date"` → `2026/10/20`,
+ *   `"datetime"` → `2026/10/20 14:30`, `"year-month"` → `2026年10月`, `"month"` → `10月`,
+ *   `"year"` → `2026年`.
+ * - A period goes through `formatDateRange`: `2026/9/23〜10/20` (same year drops the end year),
+ *   `2025/12/20〜2026/1/18` across years; month and day are not zero-padded.
+ */
+/**
+ * The kind of number a value is. Pick by what the number means, not by how
+ * long it is: `currency` for money, `percent` for a ratio, `multiple` for a
+ * factor ("1.5×"), `duration` for a length of time ("3時間20分"), `number` for
+ * exact counts in tables, `compact` (default) for large headline counts (万・億).
+ */
+type FormatKind = "number" | "compact" | "currency" | "percent" | "multiple" | "duration";
+/** The unit a `duration` value is measured in. */
+type DurationUnit = "second" | "minute" | "hour" | "day";
+/**
+ * How to display a number: a `FormatKind` alone, or an object for digits,
+ * currency, notation and a counter. The same value is accepted by KpiCard,
+ * Delta, the charts (`format`) and `formatValue`.
+ *
+ * @example
+ * "currency"                                   // ¥4,820万
+ * { type: "currency", notation: "standard" }   // ¥48,200,000
+ * { type: "percent", digits: 1 }               // 2.0%
+ * { type: "number", unit: "件" }               // 48,210件
+ */
+type ValueFormat = FormatKind | {
+    type: FormatKind;
+    /** Fixed number of fraction digits. */
+    digits?: number;
+    /** ISO 4217 code for `currency`. Default `"JPY"`. */
+    currency?: string;
+    /** `currency` only: `"compact"` (default, 万・億) or `"standard"` (every digit). */
+    notation?: "compact" | "standard";
+    /** Counter appended after the number, e.g. `"件"`, `"人"`. Ignored for `percent` and `duration`. For `multiple` it replaces the default `×` (`"倍"` → `2.7倍`). */
+    unit?: string;
+    /** 値をこの数で割ってから整形する。例: `divisor: 100`（セント → ドル）。0 と非有限は無視。 */
+    divisor?: number;
+    /** `duration` only: the unit the value is in. Default `"second"`. Reads as "45秒" / "12分" / "3時間20分" / "1.5日" (`digits` sets the fraction digits of days). */
+    durationUnit?: DurationUnit;
+};
+/** Locale used when none is passed. Every function here takes a `locale` to override it. */
+declare const DEFAULT_LOCALE = "ja-JP";
+/** Shown in place of a missing value (null / undefined / NaN). */
+declare const EMPTY_VALUE = "\u2014";
+/** The minus sign every formatter writes (U+2212), so a negative never mixes with a hyphen-minus. */
+declare const MINUS_SIGN = "\u2212";
+/** Extra options for `formatValue`. */
+interface FormatValueOptions {
+    /** `"auto"` (default) signs negatives only; `"exceptZero"` also writes `+` on positives (for differences). */
+    signDisplay?: "auto" | "exceptZero";
+    /** Round to this many significant digits (e.g. 3 for an estimate: 79,653,985 → 7,970万). */
+    significantDigits?: number;
+}
+/**
+ * The kind of a format, whether it was given as a string or an object. Use it
+ * to branch on the meaning of a metric (e.g. a `percent` metric compares in
+ * points) without unpacking `ValueFormat` yourself.
+ *
+ * @param format - The format as a KpiCard / chart takes it. `undefined` means the default.
+ * @returns The `FormatKind`; `"compact"` when `format` is omitted.
+ *
+ * @example
+ * formatKind("percent")                                // "percent"
+ * formatKind({ type: "currency", notation: "standard" }) // "currency"
+ * formatKind(undefined)                                // "compact"
+ */
+declare function formatKind(format: ValueFormat | undefined): FormatKind;
+/**
+ * Format a number for display — KPI values, table cells, chart labels and
+ * sentences built from data (titles, summaries). See the table at the top of
+ * this module.
+ *
+ * @param value - The number. `null` / `undefined` / `NaN` render as `—`.
+ *   For `percent`, a ratio (0.124 means 12.4%).
+ * @param format - How to display it. Default `"compact"`.
+ * @param locale - BCP 47 locale. Default `"ja-JP"`.
+ * @param options - `signDisplay` and `significantDigits` (rounding for estimates).
+ * @returns The display string. In ja-JP the yen sign is the half-width `¥`.
+ *
+ * @example
+ * formatValue(48_200_000, "currency")                              // "¥4,820万"
+ * formatValue(48_200_000, { type: "currency", notation: "standard" }) // "¥48,200,000"
+ * formatValue(0.021, "percent")                                    // "2.1%"
+ * formatValue(0.124, "percent", "ja-JP", { signDisplay: "exceptZero" }) // "+12.4%"
+ * formatValue(79_653_985, "currency", "ja-JP", { significantDigits: 3 }) // "¥7,970万"
+ * formatValue(48_210, { type: "number", unit: "件" })              // "48,210件"
+ * formatValue(1.5, "multiple")                                     // "1.5×"
+ * formatValue(null)                                                // "—"
+ */
+declare function formatValue(value: number | null | undefined, format?: ValueFormat, locale?: string, options?: FormatValueOptions): string;
+/**
+ * Like `formatValue`, but always signed (except zero) — for a difference
+ * between two values ("+¥530万", "−120件"). Use `formatPoints` instead for a
+ * difference between two rates.
+ *
+ * @param value - The difference (current − previous). Missing values render as `—`.
+ * @param format - Format of the metric itself. Default `"compact"`.
+ * @param locale - BCP 47 locale. Default `"ja-JP"`.
+ * @returns The signed display string; zero has no sign.
+ *
+ * @example
+ * formatDelta(5_300_000, "currency")                 // "+¥530万"
+ * formatDelta(-120, { type: "number", unit: "件" })  // "−120件"
+ * formatDelta(0.031, "percent")                      // "+3.1%"
+ * formatDelta(0, "currency")                         // "¥0"
+ */
+declare function formatDelta(value: number | null | undefined, format?: ValueFormat, locale?: string): string;
+/**
+ * A difference between two rates in percentage points, always signed:
+ * `formatPoints(0.021 - 0.026)` → `"−0.5pt"`. Use it instead of a relative
+ * change for rate metrics (churn, conversion), where "−19.2%" reads as a drop
+ * of nineteen points. `signDisplay: "never"` drops the sign ("あと 0.5pt").
+ *
+ * @param difference - The difference of two **ratios** (0.021 − 0.026). Missing values render as `—`.
+ * @param locale - BCP 47 locale. Default `"ja-JP"`.
+ * @param options - `digits`: fixed fraction digits (default `PERCENT_DIGITS` = 1, so "0.0pt" / "+0.5pt"); `signDisplay`:
+ *   `"exceptZero"` (default) or `"never"` when the sentence already says the direction.
+ * @returns The difference in points with the `pt` suffix.
+ *
+ * @example
+ * formatPoints(0.021 - 0.026)                                   // "−0.5pt"
+ * formatPoints(0.031 - 0.026)                                   // "+0.5pt"
+ * formatPoints(0.02 - 0.015, "ja-JP", { signDisplay: "never" }) // "0.5pt"（「目標まであと 0.5pt」）
+ */
+declare function formatPoints(difference: number | null | undefined, locale?: string, options?: {
+    digits?: number;
+    signDisplay?: "exceptZero" | "never";
+}): string;
+/**
+ * Binds a format and locale into a single-argument formatter, for a chart
+ * `valueFormatter` or a table cell: `valueFormatter={toValueFormatter("currency")}`.
+ * Prefer passing `format` to the chart directly; this is for APIs that only
+ * take a function.
+ *
+ * @param format - How to display each value. Default `"compact"`.
+ * @param locale - BCP 47 locale. Default `"ja-JP"`.
+ * @returns `(value) => string`, rendering missing values as `—`.
+ *
+ * @example
+ * const yen = toValueFormatter("currency")
+ * yen(48_200_000) // "¥4,820万"
+ * yen(null)       // "—"
+ * const count = toValueFormatter({ type: "number", unit: "件" })
+ * count(48_210)   // "48,210件"（表のセル）
+ */
+declare function toValueFormatter(format?: ValueFormat, locale?: string): (value: number | null | undefined) => string;
+/**
+ * 日付の書式。何を表す日付かで選ぶ: 日単位は `"date"`、時刻まで要るなら `"datetime"`、
+ * 月次の集計は `"year-month"`（年をまたぐ軸）か `"month"`（同じ年の中の軸）、年次は `"year"`。
+ */
+type DateStyle = "date" | "datetime" | "month" | "year-month" | "year";
+/** `formatDate` の追加オプション。 */
+interface FormatDateOptions {
+    /**
+     * IANA のタイムゾーン名（例: `"Asia/Tokyo"`）。既定は実行環境のタイムゾーン。
+     * サーバーとブラウザで描画が食い違う（SSR）なら固定する。日付だけの文字列（`"2026-10-20"`）には効かず、常にその暦日のまま出す。
+     */
+    timeZone?: string;
+}
+/**
+ * 日付を表示用の文字列にする。表のセル・タイトル・文に埋める日付に使い、`toLocaleString` や手組みの
+ * `getMonth() + 1` は使わない。
+ *
+ * @param value - `Date`、エポックミリ秒、または日付文字列（`"2026-10-20"`、ISO 8601）。`null` / `undefined` / 解釈できない値は `—`。
+ * @param style - 何を表す日付か。既定 `"date"`。
+ * @param locale - BCP 47 ロケール。既定 `"ja-JP"`。
+ * @param options - `timeZone`。
+ * @returns 表示文字列。
+ *
+ * @example
+ * formatDate("2026-10-20")                         // "2026/10/20"
+ * formatDate(new Date("2026-10-20T05:30:00Z"), "datetime", "ja-JP", { timeZone: "Asia/Tokyo" }) // "2026/10/20 14:30"
+ * formatDate("2026-10-01", "year-month")           // "2026年10月"
+ * formatDate("2026-10-01", "month")                // "10月"
+ * formatDate(null)                                 // "—"
+ */
+declare function formatDate(value: Date | string | number | null | undefined, style?: DateStyle, locale?: string, options?: FormatDateOptions): string;
+/** `formatDateRange` のオプション。 */
+interface FormatDateRangeOptions extends FormatDateOptions {
+    /** BCP 47 ロケール。既定 `"ja-JP"`。 */
+    locale?: string;
+}
+/**
+ * 期間を「2026/9/23〜10/20」の形にする。同じ年なら終了側の年を省き、年をまたぐときは両方に付ける。
+ * 月日はゼロ詰めしない。区切りは日本語で「〜」、それ以外のロケールでは「 – 」。始まりと終わりが同じ日なら 1 日だけ出す。
+ *
+ * @param start - 期間の最初の日（`Date`、エポックミリ秒、日付文字列）。`"2026-09-23"` のような日付だけの文字列はその暦日のまま出す。
+ * @param end - 期間の最後の日。
+ * @param options - `locale` と `timeZone`。
+ * @returns 表示文字列。どちらかが解釈できなければ `—`。
+ *
+ * @example
+ * formatDateRange("2026-09-23", "2026-10-20")  // "2026/9/23〜10/20"
+ * formatDateRange("2025-12-20", "2026-01-18")  // "2025/12/20〜2026/1/18"
+ */
+declare function formatDateRange(start: Date | string | number | null | undefined, end: Date | string | number | null | undefined, options?: FormatDateRangeOptions): string;
+/**
+ * 文中の ISO の年月・日付（`2023-04`、`2026-10-20`）を `formatDate` の書式に置き換える。期間や出典の注記のように、
+ * 利用者が文字列で渡す文に日付が混ざるときの表示用（`"2023-04 以降"` → `"2023年4月 以降"`）。日付でない数字は触らない。
+ *
+ * @param text - 日付を含みうる文。
+ * @param locale - BCP 47 ロケール。既定 `"ja-JP"`。
+ * @returns ISO の年月は `"year-month"`、年月日は `"date"` で整形した文。
+ */
+declare function formatDatesInText(text: string, locale?: string): string;
+
 /**
  * Shared data shapes for the composite dashboard components. Kept in one place
  * so filters, metrics and date pickers agree on the same vocabulary.
@@ -80,6 +352,8 @@ interface FilterConfig {
     options?: FilterOption[];
     /** Placeholder text */
     placeholder?: string;
+    /** `select` のみ。渡すと先頭に「絞り込まない」項目をこの文言で足す（例: `"すべて"`）。 */
+    allLabel?: string;
     /** Default value */
     defaultValue?: string | string[];
 }
@@ -162,6 +436,187 @@ interface SelectOptionGroup {
 type SelectOptions = SelectOption[] | SelectOptionGroup[];
 declare function isGroupedOptions(options: SelectOptions): options is SelectOptionGroup[];
 declare function flattenOptions(options: SelectOptions): SelectOption[];
+/**
+ * A chart colour: one of the theme's series tokens (`"chart-1"`〜`"chart-5"`,
+ * which follow light/dark) or any CSS colour (`"#16a34a"`, `"var(--destructive)"`).
+ * Not a Tailwind class — the ECharts-based charts paint on a canvas.
+ */
+type ChartColor = "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | (string & {});
+/** Formats a value for tooltips, axes and labels (e.g. `(v) => \`¥${v.toLocaleString()}\``). */
+type ValueFormatter = (value: number) => string;
+/** What a typed chart reports through `onValueChange`; `null` when the selection is cleared. */
+type ChartEventPayload = {
+    /** What was clicked: a bar, a line/area point, or a donut slice. */
+    eventType: "bar" | "dot" | "slice";
+    /** The series (`categories` entry) or slice name that was clicked. */
+    categoryClicked: string;
+    /** The clicked row of `data`, spread in. */
+    [key: string]: unknown;
+} | null;
+/** The theme's series tokens — the only colours a typed chart's `colors` accepts. Fixed order. */
+type ChartColorToken = "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5";
+/**
+ * 意味色。`"positive"`(良い)・`"warning"`(注意)・`"negative"`(悪い)・`"neutral"`(中立)。
+ * テーマの `--positive` / `--warning` / `--negative` / `--neutral` に解決され、light/dark に追従する。
+ */
+type ChartTone = "positive" | "warning" | "negative" | "neutral";
+/** A typed chart's series colour: a series token or a meaning colour (`ChartTone`). */
+type ChartSeriesColor = ChartColorToken | ChartTone;
+/**
+ * Series colours for a typed chart: tokens / meaning colours by series position
+ * (cycled), or a record from category to colour (unlisted categories keep their
+ * positional token).
+ */
+type ChartColors<T extends Record<string, unknown> = Record<string, unknown>> = ChartSeriesColor[] | Partial<Record<keyof T & string, ChartSeriesColor>>;
+/**
+ * 値の範囲で棒・セルの色(意味色)を決める 1 つの規則。`lt`(未満)・`lte`(以下)・`gt`(より大きい)・`gte`(以上)を
+ * 1 つ以上書く。複数書いたら全部を満たす値だけが当たる(`gte: 40, lt: 70` なら `40 <= 値 < 70`)。
+ * 規則は配列の上から順に見て、**最初に当たった規則**の意味色になる(どれにも当たらない値は通常色)。
+ * そのため厳しい規則(`gt: 10`)を先に、ゆるい規則(`gt: 7`)を後に書く。条件が 1 つも無い規則は当たらない。
+ * 例 `[{ gt: 10, tone: "negative" }, { gt: 7, tone: "warning" }]`(10 超は赤、7 超は黄)
+ */
+interface ChartThreshold {
+    /** この値未満に当たる。 */
+    lt?: number;
+    /** この値以下に当たる。 */
+    lte?: number;
+    /** この値より大きいときに当たる(「10% 超で赤」)。 */
+    gt?: number;
+    /** この値以上に当たる。 */
+    gte?: number;
+    tone: ChartTone;
+}
+/** What an empty chart says instead of a blank plot. The frame keeps its height. */
+interface ChartEmptyState {
+    /** 既定「表示できるデータがありません」。 */
+    title?: string;
+    description?: string;
+    /** 1 つだけ置ける操作(「期間を広げる」ボタンなど)。 */
+    action?: ReactNode;
+}
+/** `"auto"`: label the max and latest point of the first series (≤ 2 series only). */
+type ChartHighlight = "auto" | "none";
+/** A forecast row: the same `index` key as `data`, plus the predicted value and an optional range. */
+type ChartForecastRow = Record<string, unknown> & {
+    value: number | null;
+    lower?: number;
+    upper?: number;
+};
+/**
+ * Forecast continuing one series (Line / Area). Always drawn as a 2px dashed, lighter
+ * line starting at the last actual point, with a boundary line labelled 「予測 →」
+ * (the same word as the legend) — there is no way to draw it solid.
+ */
+interface ChartForecast<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 予測の行。`index` の列は実績と同じキーで持つ。 */
+    data: ChartForecastRow[];
+    /** 予測が続ける系列。既定 `categories[0]`(比較系列は除く)。 */
+    category?: keyof T & string;
+    /** 凡例・ツールチップ・境目の縦線の上端に出す名前。既定「予測」(境目では「予測 →」と矢印が付く)。 */
+    label?: string;
+}
+/**
+ * The series a Line / Area chart compares the others against (last year, the plan…): `category`
+ * is one of `categories`, `vs` says what it is (the same enum as `KpiCard`'s `comparison.vs`).
+ * It is drawn as a thin muted line with no markers and no `--chart-*` colour, and the tooltip adds
+ * the main series' difference from it ("↑ +12.4% 前年同月比"). Colour, width and wording are not props.
+ * With `vs: "custom"` the `label` names the baseline ("昨日比"); for the other `vs` it is optional.
+ */
+type ChartComparison<K extends string = string> = {
+    category: K;
+} & ({
+    vs: "prior-period" | "prior-year" | "target";
+    label?: string;
+} | {
+    vs: "custom";
+    label: string;
+});
+/**
+ * 任意の位置への注記(折れ線・面・縦の棒)。`at` は `index` の値(例 `"2026-04"`)。`to` を足すと
+ * `at`〜`to` の区間(薄い帯)、無ければ `at` の位置の縦線。色は中立(意味色は使わない)で、
+ * `index` に無い値の注記は描かない。例 `{ at: "2026-04", label: "料金改定" }`、
+ * `{ at: "2026-08", to: "2026-09", label: "キャンペーン" }`
+ */
+interface ChartAnnotation {
+    /** 注記の位置(区間なら始点)。`index` 列の値と同じ形で渡す。 */
+    at: string | number;
+    /** 注記の文言(短く。事実の記述だけ)。 */
+    label: string;
+    /** 区間の終点(`index` の値)。省略すると `at` の縦線。 */
+    to?: string | number;
+}
+/**
+ * `actions` に渡せる PNG 操作の設定。`actions={true}` は `{}` と同じ。
+ */
+interface ChartActionsOptions {
+    /**
+     * 保存・コピーする PNG に、グラフの見出し(`title`)と要約(`summary`)を画像の上に含める。
+     * 見出しが無いグラフでは何も変わらない。既定 `true`(画像だけ切り出されても何のグラフか分かるように)。
+     * 図だけが欲しいときは `false`。
+     */
+    includeTitle?: boolean;
+}
+/**
+ * 型付きグラフのルート要素(`<figure>`)へ渡る属性。`data-*` と `aria-*` も渡る(型は不要)。
+ * 最小限だけ型に出す。`className` / `ariaLabel` は別に持つ。
+ */
+type ChartRootAttributes = Pick<HTMLAttributes<HTMLElement>, "id" | "style" | "role" | "tabIndex" | "lang" | "hidden">;
+/**
+ * Columns of `T` whose values are numbers (null / undefined allowed for gaps).
+ * `categories` only accepts these, so a text column like `"month"` is a type error.
+ * Untyped rows (`unknown` / `any` values, e.g. `Record<string, unknown>`) keep every key.
+ */
+type NumericKeys<T> = {
+    [K in keyof T]-?: unknown extends T[K] ? K : T[K] extends number | bigint | null | undefined ? K : never;
+}[keyof T] & string;
+/** Props every typed chart shares. Per-type differences live in `areaOptions` / `lineOptions` / `barOptions`. */
+interface ChartCommonProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = x 軸の 1 点。数値の列は number か数値文字列(SQL の DECIMAL など)。 */
+    data: T[];
+    /** x 軸(カテゴリ軸)に使う列名。 */
+    index: keyof T & string;
+    /** 系列として描く列名。並び順が凡例と配色の順になる。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 */
+    categories: NumericKeys<T>[];
+    /** 系列色(`"chart-1"`〜`"chart-5"` か意味色 `"positive"` / `"warning"` / `"negative"` / `"neutral"`)。配列は系列の順、record は系列名ごと。省略時はトークン順。 */
+    colors?: ChartColors<T>;
+    /**
+     * index の値・系列名 → 表示名(軸・凡例・ツールチップ・データ表に反映)。例 `{ jan: "1月", sales: "売上" }`。無いキーはそのまま。
+     */
+    labels?: Record<string, string>;
+    /**
+     * 数値の書式(`"compact"` / `"number"` / `"currency"` / `"percent"` / `"multiple"` / `"duration"`、
+     * または `{ type, digits, currency, notation, unit, divisor, durationUnit }`)。例 `format={{ type: "number", unit: "件" }}`。
+     * 軸は短縮、ツールチップも同じ書式。KPI 系の `format` と同じ値を渡せる。既定 `"compact"`。
+     */
+    format?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道。`format` より優先する(互換のために残す)。 */
+    valueFormatter?: ValueFormatter;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。見出しの下に出し、グラフの `aria-describedby` になる。 */
+    summary?: string;
+    /** 読み込み中。最終形と同じ形・高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /**
+     * プロット領域の高さ(px)。既定 288。
+     * 文字列(CSS の長さ)は互換のために受けるだけで非推奨 — 数値(px)で渡す。
+     */
+    height?: number | string;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /**
+     * グラフ右上に PNG 保存/コピーのボタンを出す(ホバー時。凡例とは重ならない)。既定 `false`。
+     * 見出し(`title` / `summary`)があれば PNG の上に含める。含めないなら `actions={{ includeTitle: false }}`。
+     * 例: `actions`
+     */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。`actions` と使う。既定 `"chart.png"`。例: `fileName="monthly-sales.png"` */
+    fileName?: string;
+    className?: string;
+    ariaLabel?: string;
+}
 
 interface AppShellSidebarProps {
     variant?: "sidebar";
@@ -189,7 +644,7 @@ declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.Re
 
 declare const headingStyles: {
     readonly h1: "text-3xl font-bold tracking-tight";
-    readonly h2: "text-2xl font-semibold tracking-tight";
+    readonly h2: "text-xl font-semibold tracking-tight";
     readonly h3: "text-xl font-semibold";
     readonly h4: "text-lg font-semibold";
 };
@@ -203,6 +658,10 @@ interface SectionHeaderProps {
 declare const SectionHeader: React.ForwardRefExoticComponent<SectionHeaderProps & React.RefAttributes<HTMLDivElement>>;
 
 interface DashboardCardProps extends HTMLAttributes<HTMLDivElement> {
+    /** 親の grid の何行にまたがって subgrid で揃えるか（ヘッダー・本文・フッターなら 3、ヘッダー・本文なら 2）。未指定なら通常のブロック。 */
+    subgrid?: 2 | 3;
+    /** `"sm"` は一段小さい余白。Sheet の中などで 2 枚を横に並べるとき。既定 `"default"`。 */
+    size?: "default" | "sm";
 }
 declare const DashboardCard: React.ForwardRefExoticComponent<DashboardCardProps & React.RefAttributes<HTMLDivElement>>;
 interface DashboardCardHeaderProps extends HTMLAttributes<HTMLDivElement> {
@@ -227,7 +686,7 @@ interface DashboardCardSkeletonProps {
     className?: string;
 }
 declare function DashboardCardSkeleton({ className }: DashboardCardSkeletonProps): React.JSX.Element;
-interface DashboardCardPresetProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+interface DashboardCardPresetProps extends Omit<HTMLAttributes<HTMLDivElement>, "title">, Pick<DashboardCardProps, "subgrid" | "size"> {
     title?: ReactNode;
     description?: ReactNode;
     actions?: ReactNode;
@@ -236,7 +695,7 @@ interface DashboardCardPresetProps extends Omit<HTMLAttributes<HTMLDivElement>,
     contentClassName?: string;
     footerClassName?: string;
 }
-declare function DashboardCardPreset({ title, description, actions, footer, children, headerClassName, contentClassName, footerClassName, className, ...props }: DashboardCardPresetProps): React.JSX.Element;
+declare function DashboardCardPreset({ title, description, actions, footer, children, headerClassName, contentClassName, footerClassName, className, subgrid, ...props }: DashboardCardPresetProps): React.JSX.Element;
 
 interface EChartProps {
     /**
@@ -247,7 +706,7 @@ interface EChartProps {
      * literal が `string` に拡張され、ビルドが失敗する。
      *
      * @example
-     * import type { EChartsOption } from "@squadbase/vantage/components"
+     * import type { EChartsOption } from "@/components/echart"
      *
      * const option: EChartsOption = {
      *   xAxis: { type: "category", data: ["A", "B"] },
@@ -278,19 +737,888 @@ interface EChartProps {
     onEvents?: Record<string, (params: unknown) => void>;
     ariaLabel?: string;
     className?: string;
-    /** true にするとチャート右上に PNG コピー / ダウンロードボタンを表示する */
-    actions?: boolean;
+    /**
+     * true にするとチャート右上に PNG コピー / ダウンロードボタンを表示する。
+     * `exportHeader` があれば PNG の上にその見出しを含める(`{ includeTitle: false }` で含めない)。
+     */
+    actions?: boolean | ChartActionsOptions;
     /** ダウンロード時のファイル名(拡張子含む)。省略時は "chart.png" */
     fileName?: string;
+    /**
+     * PNG の上に含める見出しと要約。型付きグラフは自分の `title` / `summary` を渡す。
+     * 自分で `ChartFrame` を組むときも同じものを渡すと、保存した画像だけで何のグラフか分かる。
+     */
+    exportHeader?: ChartExportHeader;
+}
+/** The heading a saved PNG carries above the plot. */
+interface ChartExportHeader {
+    title?: string;
+    summary?: string;
 }
+/**
+ * Canvas-safe versions of theme colours, kept current across light/dark.
+ * Takes `"chart-1"`〜`"chart-5"`, `"var(--token)"` or any CSS colour; one that
+ * can't be resolved comes back as `""` (ECharts then uses the palette).
+ * Use it whenever a colour goes into a raw `EChart` option by hand.
+ *
+ * @example
+ * const [line, band] = useResolvedChartColors(["chart-1", "var(--muted-foreground)"])
+ */
+declare function useResolvedChartColors(colors: readonly string[]): string[];
 declare const EChart: React.ForwardRefExoticComponent<EChartProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Period-over-period / target comparison for KPIs. A rate is only produced when
+ * the baseline is a non-zero number; small moves inside the neutral band read
+ * as flat, and polarity decides whether up is good or bad.
+ *
+ * Labels follow Japanese business usage and come from the grain of the period:
+ * a monthly KPI compares "前月比" / "前年同月比", a quarterly one "前四半期比" /
+ * "前年同期比". Without a grain the label is the generic "前期比".
+ *
+ * A running total of a period still in progress (年初来・月初来 = YTD / MTD) sets
+ * `toDate: true`: a `prior-year` baseline is then the same stretch of the prior year,
+ * and the label is always "前年同期比" (never "前年比", which would mean a whole year
+ * against a whole year), whatever the grain.
+ *
+ * Any other baseline is `vs: "custom"` with a `label` ("昨日比"). The baseline of
+ * the previous-actual line is derived from that label ("昨日"), so the badge and
+ * the line never name different things.
+ */
+
+type ComparisonKind = "prior-period" | "prior-year" | "target" | "custom";
+/**
+ * 増減の良し悪しの向き。`"neutral"` は増減どちらでも sentiment を neutral にする（例: 在庫数）。
+ * @example polarity="neutral"
+ */
+type Polarity = "higher-is-better" | "lower-is-better" | "neutral";
+/** Length of the period a value covers. */
+type PeriodGrain = "day" | "week" | "month" | "quarter" | "year";
+interface ComparisonBase {
+    previous: number | null | undefined;
+    /** Grain of the period, which picks the label: `"month"` → "前月比" / "前年同月比". */
+    grain?: PeriodGrain;
+    /**
+     * The value is a running total of the period so far (年初来・月初来), not a closed period.
+     * With `vs: "prior-year"` the label is "前年同期比" (the same stretch of last year) whatever the `grain`.
+     * Leave it off for a closed period: a full year against the prior year is "前年比".
+     */
+    toDate?: boolean;
+}
+type Comparison = (ComparisonBase & {
+    vs: Exclude<ComparisonKind, "custom">;
+    /** The badge's full name ("先週比"). Overrides the derived label; the previous-actual line takes its name from it too. */
+    label?: string;
+}) | (ComparisonBase & {
+    /** Any other baseline ("昨日", "先週の同じ曜日"): the `label` names it. */
+    vs: "custom";
+    /** The badge's full name: `"昨日比"` / `"先週の同じ曜日比"`. The previous-actual line drops one trailing "比" ("昨日 617"). */
+    label: string;
+});
+/** Labels used when the grain is unknown. A `custom` comparison always brings its own `label`. */
+declare const COMPARISON_LABELS: Record<Exclude<ComparisonKind, "custom">, string>;
+/**
+ * What the previous value is called: "前月" / "前年同月" / "目標"; with a `label`, that label minus one trailing "比" ("昨日比" → "昨日").
+ * `toDate` (a running total such as YTD) turns a `prior-year` baseline into "前年同期" whatever the grain.
+ */
+declare function comparisonBaseline(vs: ComparisonKind, grain?: PeriodGrain, label?: string, toDate?: boolean): string;
+/**
+ * The comparison label: "前月比" for `("prior-period", "month")`, "前期比" without a grain; a given `label` as is.
+ * A running total (`toDate`) against the prior year is "前年同期比", not "前年比".
+ */
+declare function comparisonLabel(vs: ComparisonKind, grain?: PeriodGrain, label?: string, toDate?: boolean): string;
+type DeltaDirection = "up" | "down" | "flat" | "none";
+type DeltaSentiment = "positive" | "negative" | "neutral";
+interface ComparisonResult {
+    current: number | null;
+    previous: number | null;
+    /** `current − previous` in the metric's own unit (a ratio difference for a rate). `null` when either is missing. */
+    difference: number | null;
+    /** `difference / |previous|`. `null` when it cannot be computed (missing values or a zero baseline). */
+    ratio: number | null;
+    direction: DeltaDirection;
+    sentiment: DeltaSentiment;
+    label: string;
+    vs: ComparisonKind;
+}
+interface ComparisonOptions {
+    polarity?: Polarity;
+    /** Absolute ratio below which the change reads as flat (0.01 = 1%). Default 0.01. */
+    neutralBand?: number;
+}
+declare function computeComparison(current: number | null | undefined, comparison: Comparison, options?: ComparisonOptions): ComparisonResult;
+/**
+ * How a change is expressed: `"relative"` = change rate ("+12.4%"), `"points"` =
+ * difference of two rates in percentage points ("−0.5pt"), `"difference"` =
+ * absolute difference in the metric's own format ("+¥530万"; pass `format` to `formatChange`).
+ */
+type ChangeDisplay = "relative" | "points" | "difference";
+/** `"points"` for a `percent` metric (a rate), else `"relative"`. */
+declare function defaultChangeDisplay(format: ValueFormat | undefined): ChangeDisplay;
+/**
+ * The change as shown next to a KPI: "+12.4%" (relative) or "−0.5pt" (points).
+ * Returns `null` when the values cannot be compared.
+ *
+ * @param digits - Fixed fraction digits of the change, for `"relative"` and `"points"`
+ *   (not `"difference"`, which follows `format`). Default `PERCENT_DIGITS` (1), so
+ *   "+14.0%" and "+11.9%" line up. Pass the same count to every card in a group.
+ */
+declare function formatChange(result: ComparisonResult, display?: ChangeDisplay, locale?: string, 
+/** `"difference"` 表示で使う値の format。例: `"currency"`。 */
+format?: ValueFormat, 
+/** `"relative"` / `"points"` 表示の小数桁数（固定）。例: `2` → "+0.14pt"。未指定は 1 桁。 */
+digits?: number): string | null;
+/**
+ * The size of the change with **no sign**, for a sentence or a screen-reader text that
+ * already says the direction with a verb ("0.5pt 下がりました", "前月比 12.4% 減少"): a signed
+ * "−0.5pt 下がりました" negates twice. Same arguments as `formatChange`; `null` when the
+ * values cannot be compared.
+ */
+declare function formatChangeAmount(result: ComparisonResult, display?: ChangeDisplay, locale?: string, format?: ValueFormat, digits?: number): string | null;
+/**
+ * The tone of the first threshold rule `value` falls in, or `undefined` (a value
+ * no rule matches keeps the normal colour). A rule matches when every bound it
+ * carries holds: `value < lt`, `value <= lte`, `value > gt`, `value >= gte`
+ * (`gt` / `lte` are the strict-inclusive counterparts, so「10% 超」is `gt: 10`).
+ * Rules are tried in array order and the first match wins — put the strict rule
+ * first (`gt: 10` before `gt: 7`). A rule with no bound never matches. Gaps (`null`) match nothing.
+ */
+declare function toneForValue(value: number | null | undefined, thresholds: readonly ChartThreshold[] | undefined): ChartTone | undefined;
+
+/**
+ * ECharts option builders behind the typed charts (AreaChart, BarChart,
+ * LineChart, DonutChart). They turn the Tremor-style props — `data` rows, an
+ * `index` key and `categories` — into an `EChartsOption` for `EChart`, which
+ * keeps owning the canvas and the token theme.
+ *
+ * Pure functions of their input: colours arrive already resolved to
+ * canvas-safe strings (`resolveChartColors` in `chart-theme.ts`), so everything
+ * here is unit-testable without a DOM. Internal; inlined into each copy.
+ */
+
+type CartesianStackType = "default" | "stacked" | "percent";
+type CartesianCurveType = "linear" | "smooth" | "step";
+type AreaFill = "gradient" | "solid" | "none";
+type BarLayout = "horizontal" | "vertical";
+/** AreaChart-only settings. */
+interface AreaChartOptions {
+    /** `"stacked"` は積み上げ、`"percent"` は各点の合計を 100% にした積み上げ。既定 `"default"`。 */
+    type?: CartesianStackType;
+    /** 線の形。既定 `"linear"`。 */
+    curveType?: CartesianCurveType;
+    /** 面の塗り。既定 `"gradient"`。 */
+    fill?: AreaFill;
+    /** 値の欠けた点(`null` など)をまたいで線をつなぐ。既定 `false`。 */
+    connectNulls?: boolean;
+}
+/** LineChart-only settings. */
+interface LineChartOptions {
+    /** 線の形。既定 `"linear"`。 */
+    curveType?: CartesianCurveType;
+    /** 値の欠けた点(`null` など)をまたいで線をつなぐ。既定 `false`。 */
+    connectNulls?: boolean;
+    /** 値軸を 0 からではなくデータの範囲に合わせる。既定 `false`(0 起点)。最小の目盛ラベルは先頭の x ラベルと重なるので出さない(グリッド線は残る)。 */
+    fitToData?: boolean;
+    /**
+     * 目標線(`target`)のラベルの置き場所。`"start"`(既定)は線の左端の上(最大・最新の強調と近いときは下)。
+     * `"end"` は線の右端の上。`"legend"` は凡例だけに出し、線の上には出さない(線の周りが混み合うとき)。
+     * 目標の呼び名は、どれを選んでも凡例に出る。
+     */
+    targetLabelPosition?: LineTargetLabelPosition;
+}
+/** Where a line chart prints its target label: at the line's left end, its right end, or in the legend only. */
+type LineTargetLabelPosition = "start" | "end" | "legend";
+/** BarChart-only settings. */
+interface BarChartOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** `"stacked"` は積み上げ、`"percent"` は各カテゴリの合計を 100% にした積み上げ。既定 `"default"`(横並び)。 */
+    type?: CartesianStackType;
+    /**
+     * 棒の向き。既定 `"horizontal"`(カテゴリが横に並ぶ縦棒)。`"vertical"` はカテゴリを
+     * 縦に並べた横棒で、ラベルの長いランキングに向く(先頭の行が一番上)。
+     */
+    layout?: BarLayout;
+    /** カテゴリ間の隙間(`"20%"` や px)。省略時は ECharts の既定。 */
+    barCategoryGap?: string | number;
+    /**
+     * 値が 0 の棒に「0」の値ラベルを付ける。棒が描かれない 0 が「データなし」に見えるのを防ぐ
+     * (在庫 0・件数 0 など)。積み上げでは付けない。0 以外の棒の見た目は変わらない。既定 `true`。
+     */
+    showZeroValues?: boolean;
+    /**
+     * 棒ごとの目標値が入った `data` の列名(行ごとの目標。店舗別の月次目標など)。各棒に短い目標マーカーを
+     * 引き、ツールチップに「目標 … (達成率 …%)」を足す。凡例に目標の呼び名(`targetLabel`、既定「目標」)が出る。
+     * 1 系列の棒と積み上げ(達成率は合計に対して)で使える。横並びの複数系列と 100% 積み上げでは描かない。
+     * 値が欠けた(null・0 以下の)行はマーカーを引かない。
+     *
+     * 優先順位: `targetKey` を渡すと 1 本の目標線 `target` は描かない(`targetLabel` はマーカーの呼び名として使う)。
+     * 値による色分け `thresholds` とは併用できる(色は棒、マーカーは目標)。値軸は最大の目標を含む。
+     * 例: `barOptions={{ targetKey: "月次目標" }}`
+     */
+    targetKey?: NumericKeys<T>;
+    /**
+     * 横棒(`layout: "vertical"`)の 1 系列で伝えたい 1 本。`index` の値で渡す(例 `"東京店"`)。
+     * 横棒は淡い色(`--chart-1` の薄い塗り)が既定で、この 1 本だけ濃い色(系列色そのまま)になる。省略すると全部が淡い色。
+     * 縦棒・複数系列・積み上げでは効かない(色は変わらない)。意味色の `thresholds` に当たった棒はそちらの色が優先。
+     * 例: `barOptions={{ layout: "vertical", highlight: "東京店" }}`
+     */
+    highlight?: string | number;
+}
+/** Props every cartesian typed chart (Area / Bar / Line) shares. */
+interface CartesianChartBaseProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartCommonProps<T> {
+    /**
+     * 最大値と最新値に値ラベルを付ける(最初の系列だけ・系列が 2 つ以下のときだけ・最大 2 つ)。
+     * 100% 積み上げの面グラフでは、最初の系列(一番下の帯)の最初と最新の比率(「24%」「31%」)を帯の中に付ける。
+     * 既定は Line / Area が `"auto"`、Bar は `index` が日付・年月・年のときだけ `"auto"`。
+     */
+    highlight?: ChartHighlight;
+    /**
+     * ここから先は確定前(速報)の点。index の値で渡す(例 `"2026-09"`)。薄い色・点線(棒は薄い塗りと破線の縁)で
+     * 描き、凡例・ツールチップに `provisionalLabel` を出す。線・面は確定の最終点とつなぐ。`forecast`(予測)とは別物。
+     * 例: `provisionalFrom="2026-09"`
+     */
+    provisionalFrom?: string | number;
+    /** 速報の呼び名(凡例・ツールチップ)。既定「速報」。例: `provisionalLabel="暫定"` */
+    provisionalLabel?: string;
+    /**
+     * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら data から機械的に組む
+     * (「<見出し>: 最新 <index値> は <値>、前の点より増加/減少」。向きは最新 2 点の値で決まる)。
+     * 増減の向きを文に書くなら `"auto"` を使うか data から作る — 手書きの向きは data とずれて誤る。
+     * 省略時は要約なし(既存どおり)。例: `summary="auto"`
+     */
+    summary?: string | "auto";
+    /** 目標値。点線の水平線で示し、値軸は必ずこの値を含む。棒ごとの目標(`barOptions.targetKey`)を渡したときは描かない。 */
+    target?: number;
+    /** 目標線のラベル。既定「目標 <書式化した値>」。`barOptions.targetKey` のときはマーカーの呼び名(既定「目標」)。 */
+    targetLabel?: string;
+    /**
+     * 任意の位置への注記(縦の線、または `to` で区間の帯)。折れ線・面・縦の棒(`barOptions.layout` が既定のとき)で使え、
+     * 横棒では描かない。`at` / `to` は `index` の値。色は中立で、ツールチップにも文言が出る。例:
+     * `annotations={[{ at: "2026-04", label: "料金改定" }, { at: "2026-08", to: "2026-09", label: "キャンペーン" }]}`
+     */
+    annotations?: ChartAnnotation[];
+    /** 凡例を出す。既定 `true`。 */
+    showLegend?: boolean;
+    /** ホバー時のツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /** 値軸の目盛り線を出す。既定 `true`。 */
+    showGridLines?: boolean;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    /** x 軸のラベルを最初と最後だけにする。 */
+    startEndOnly?: boolean;
+    /** y 軸ラベルの幅(px)。並べた複数グラフのプロット領域を揃えたいときに固定する。 */
+    yAxisWidth?: number;
+    /**
+     * 値軸の下限。Bar / Area は常に 0 起点なので、0 以下の値だけ有効(負の値の下に余白を取る。正の値は無視)。
+     * Line は指定した値から始める。データが下限を下回るときは軸を広げる(切り詰めない)。
+     * 並べて比べる複数のグラフには同じ値を渡して軸をそろえる。
+     */
+    minValue?: number;
+    /**
+     * 値軸の上限(横棒は横軸)。データが上限を超えるときは軸を広げる(切り詰めない)。
+     * 並べて比べる複数のグラフには同じ値を渡して軸をそろえる。
+     */
+    maxValue?: number;
+    /** @deprecated `lineOptions.fitToData` を使う。Bar / Area では無視される(常に 0 起点)。 */
+    autoMinValue?: boolean;
+    /** `false` で値軸の目盛りを整数に限る。 */
+    allowDecimals?: boolean;
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+    /**
+     * 点(棒)のクリックで呼ばれる。クリックした行に `eventType` / `categoryClicked` を
+     * 足して渡し、同じ点をもう一度クリックすると `null`。渡すと選択以外が薄くなる。
+     */
+    onValueChange?: (value: ChartEventPayload) => void;
+    /** @deprecated `isLoading` を使う。 */
+    loading?: boolean;
+}
+type DonutVariant = "donut" | "pie";
+/** What the donut prints in its hole (`donutOptions.centerLabel`). */
+type DonutCenterLabel = "none" | "total" | "top";
+/** DonutChart-only settings. */
+interface DonutChartOptions {
+    /** `"donut"`(中央に穴とラベル)か `"pie"`。既定 `"donut"`。 */
+    variant?: DonutVariant;
+    /** @deprecated `centerLabel` を使う。`false` は `centerLabel: "none"` と同じ。`true` を明示すると `"total"` 扱い(以前の既定)。 */
+    showLabel?: boolean;
+    /**
+     * 穴の中央に出すもの。`"none"`(既定。何も出さない。合計は KPI と重複しがち)/ `"total"`(「合計」と
+     * 合計を書式化した値。`totalLabel` / `unit` を添える)/ `"top"`(最大の切片の名前と構成比)。
+     * それ以外のノードを渡すとそのまま中央に置く。donut のみ。
+     */
+    centerLabel?: DonutCenterLabel | ReactNode;
+    /** 中央ラベルの見出し(何の合計か)。既定「合計」。 */
+    totalLabel?: string;
+    /** 中央ラベルの合計に添える単位(`"セッション"` → 「9.2万 セッション」)。 */
+    unit?: string;
+    /** 凡例(名前と構成比、大きい順)を出す。広いときは右、狭いときは下。既定 `true`。構成比は凡例だけが持つ(凡例を消すと、広いときだけ大きい 2 切片に外ラベルで名前と構成比が出る)。 */
+    showLegend?: boolean;
+    /** 個別に描く切片の数。超えた分は大きさ順の残りを「その他」1 切片にまとめる。既定 5。 */
+    maxSlices?: number;
+}
+
+/**
+ * AreaChart — a typed area chart over `EChart`: pass rows, the x-axis key
+ * (`index`) and the series keys (`categories`) instead of an ECharts option.
+ * Colours are the `--chart-1..5` tokens in fixed order (more than 5 series fold
+ * into「その他」) and follow light/dark. The value axis always starts at 0.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state).
+ * Reach for `chartOptions` — or `EChart` itself — only when this API lacks something.
+ */
+
+interface AreaChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends CartesianChartBaseProps<T> {
+    /** 面グラフ固有の設定(積み上げ・線の形・塗り・欠損の扱い)。同名のフラットな props より優先。 */
+    areaOptions?: AreaChartOptions;
+    /** 予測。最初の系列(または `forecast.category`)の続きを点線と薄い帯で描く。 */
+    forecast?: ChartForecast<T>;
+    /**
+     * 比較系列。`categories` のうち 1 つを「前年」「計画」などの比較の線にする(`vs` は KpiCard と同じ語彙)。
+     * 比較系列は `--chart-*` を使わず、細い(1.5px)灰色の実線でマーカーなし・塗りなし。主系列の色は比較の有無で変わらない。
+     * ツールチップは最初の主系列の行に「↑ +12.4% 前年同月比」を添え、比較系列の行は値のみ。
+     * 例: `comparison={{ category: "前年", vs: "prior-year" }}`
+     */
+    comparison?: ChartComparison<NumericKeys<T>>;
+    /** @deprecated `areaOptions.type` を使う。 */
+    type?: CartesianStackType;
+    /** @deprecated `areaOptions.curveType` を使う。 */
+    curveType?: CartesianCurveType;
+    /** @deprecated `areaOptions.fill` を使う。 */
+    fill?: AreaFill;
+    /** @deprecated `areaOptions.connectNulls` を使う。 */
+    connectNulls?: boolean;
+}
+/** Generic over the row type, so `index` / `categories` / `colors` keys are checked against `data`. */
+declare const AreaChart: (<T extends Record<string, unknown>>(props: AreaChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * BarChart — a typed bar chart over `EChart`: pass rows, the category key
+ * (`index`) and the series keys (`categories`) instead of an ECharts option.
+ * Grouped, stacked or 100%-stacked; vertical or horizontal bars. Colours are the
+ * `--chart-1..5` tokens in fixed order (more than 5 series fold into「その他」)
+ * and follow light/dark. The value axis always starts at 0. A horizontal bar chart of one
+ * series (`barOptions.layout: "vertical"`) is a light tint by default, like BarList; `barOptions.highlight`
+ * names the one bar the page is about, drawn in the full colour.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state).
+ * Reach for `chartOptions` — or `EChart` itself — only when this API lacks something.
+ */
+
+interface BarChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends CartesianChartBaseProps<T> {
+    /** 棒グラフ固有の設定(積み上げ・向き・カテゴリ間の隙間)。同名のフラットな props より優先。予測は持たない。 */
+    barOptions?: BarChartOptions<T>;
+    /**
+     * 棒を値で色分けする(上から順に最初に当たった規則の意味色。棒の面なので文字用の `--<tone>` ではなく面用の `--<tone>-fill` で塗る。どれにも当たらない棒は通常色)。
+     * 規則は `lt`(未満)・`lte`(以下)・`gt`(より大きい)・`gte`(以上)。複数系列(横並び)では系列ごとの棒に効き、当たった棒は意味色で塗って縁に系列色を残す(凡例と結べる)。
+     * 積み上げでは無視(一部分の値は良し悪しを判定する量ではないため。系列色のまま)。
+     * 例 `[{ gt: 2, tone: "negative" }, { gt: 1.5, tone: "warning" }]`(2 超は赤、1.5 超は黄)
+     */
+    thresholds?: ChartThreshold[];
+    /** @deprecated `barOptions.type` を使う。 */
+    type?: CartesianStackType;
+    /** @deprecated `barOptions.layout` を使う。 */
+    layout?: BarLayout;
+    /** @deprecated `barOptions.barCategoryGap` を使う。 */
+    barCategoryGap?: string | number;
+}
+/** Generic over the row type, so `index` / `categories` / `colors` keys are checked against `data`. */
+declare const BarChart: (<T extends Record<string, unknown>>(props: BarChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * LineChart — a typed line chart over `EChart`: pass rows, the x-axis key
+ * (`index`) and the series keys (`categories`) instead of an ECharts option.
+ * Colours are the `--chart-1..5` tokens in fixed order (more than 5 series fold
+ * into「その他」) and follow light/dark. The value axis starts at 0 unless
+ * `lineOptions.fitToData`.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state).
+ * Reach for `chartOptions` — or `EChart` itself — only when this API lacks something.
+ */
+
+interface LineChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends CartesianChartBaseProps<T> {
+    /** 折れ線固有の設定(線の形・欠損の扱い・値軸をデータに合わせるか・目標ラベルの位置 `targetLabelPosition`)。同名のフラットな props より優先。 */
+    lineOptions?: LineChartOptions;
+    /** 予測。最初の系列(または `forecast.category`)の続きを点線と薄い帯で描く。 */
+    forecast?: ChartForecast<T>;
+    /**
+     * 比較系列。`categories` のうち 1 つを「前年」「計画」などの比較の線にする(`vs` は KpiCard と同じ語彙)。
+     * 比較系列は `--chart-*` を使わず、細い(1.5px)灰色の実線でマーカーなし。主系列の色は比較の有無で変わらない。
+     * ツールチップは最初の主系列の行に「↑ +12.4% 前年同月比」を添え、比較系列の行は値のみ。
+     * 例: `comparison={{ category: "前年", vs: "prior-year" }}`
+     */
+    comparison?: ChartComparison<NumericKeys<T>>;
+    /** @deprecated `lineOptions.curveType` を使う。 */
+    curveType?: CartesianCurveType;
+    /** @deprecated `lineOptions.connectNulls` を使う。 */
+    connectNulls?: boolean;
+}
+/** Generic over the row type, so `index` / `categories` / `colors` keys are checked against `data`. */
+declare const LineChart: (<T extends Record<string, unknown>>(props: LineChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * DonutChart — a typed donut / pie chart over `EChart`: pass rows, the label
+ * key (`index`) and the value key (`categories: [valueKey]`). Slices are sorted
+ * largest first and coloured with the `--chart-1..5` tokens in fixed order;
+ * more than 5 fold into one「その他」slice. The hole is empty by default (the
+ * total usually repeats a KPI); `donutOptions.centerLabel` picks `"total"`
+ * (「合計」+ the formatted total, plus `unit`), `"top"` (the largest slice and its
+ * share) or a custom node — plain HTML over the canvas, so it takes the page's
+ * type and colours. A share is printed once: the HTML legend lists every slice
+ * with its share, right of the ring when there is room, below it otherwise, and
+ * with the legend there are no outside labels (without it, a plot at least
+ * `DONUT_OUTSIDE_LABEL_MIN_WIDTH` wide labels its 2 largest slices).
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state,
+ * and a visually-hidden table of the slices).
+ */
+
+interface DonutChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors"> {
+    /** 切片の名前に使う列名。 */
+    index?: keyof T & string;
+    /** 切片の大きさに使う列名を 1 つだけ入れた配列(`["売上"]`)。2 つ以上渡しても最初の 1 つだけを使う。 */
+    categories?: (keyof T & string)[];
+    /** 切片の色(大きい順)。`"chart-1"`〜`"chart-5"` か意味色(`"positive"` など。面用の `--<tone>-fill` で塗る)。省略時はトークン順。「その他」は常に灰色。 */
+    colors?: ChartSeriesColor[];
+    /** 切片の名前(`index` の値)→ 表示名。凡例・ツールチップ・外ラベル・データ表に反映。例 `{ organic: "自然検索" }`。無いキーはそのまま。データ表の列名を直すには、`index` と値のキーも渡す(`{ source: "流入元", sessions: "セッション" }`。既定は「項目」「値」)。 */
+    labels?: Record<string, string>;
+    /** ドーナツ固有の設定(形・中央に出すもの `centerLabel`・凡例・切片の上限)。同名のフラットな props より優先。 */
+    donutOptions?: DonutChartOptions;
+    /**
+     * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら slices から「<見出し>: 最大は <名前>(<構成比>)」を組む。
+     * 順位や構成比を文に書くなら `"auto"` を使うか data から作る。省略時は要約なし。例: `summary="auto"`
+     */
+    summary?: string | "auto";
+    showTooltip?: boolean;
+    /** 切片のクリックで呼ばれる。同じ切片をもう一度クリックすると `null`。渡すと選択以外が薄くなる。 */
+    onValueChange?: (value: ChartEventPayload) => void;
+    /** @deprecated `index` を使う。 */
+    category?: keyof T & string;
+    /** @deprecated `categories={[value]}` を使う。 */
+    value?: keyof T & string;
+    /** @deprecated `donutOptions.variant` を使う。 */
+    variant?: DonutVariant;
+    /** @deprecated `donutOptions.centerLabel` を使う。 */
+    label?: ReactNode;
+    /** @deprecated `donutOptions.centerLabel`(`"none"` で消す)を使う。 */
+    showLabel?: boolean;
+    /** @deprecated `isLoading` を使う。 */
+    loading?: boolean;
+}
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+declare const DonutChart: (<T extends Record<string, unknown>>(props: DonutChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * Chart helpers shared by the typed charts — colour tokens, number handling and
+ * the layout maths of the Tailwind/SVG charts (BarList, CategoryBar,
+ * ProgressCircle, Tracker). Pure and DOM-free, so it can be unit-tested; kept
+ * internal and inlined into each `vantage add ui` copy.
+ */
+
+type BarListSortOrder = "ascending" | "descending" | "none";
+/** BarList-only settings. */
+interface BarListOptions {
+    /** 並べ順。既定 `"descending"`(大きい順)。`"none"` は渡した順。「その他」は常に最後。 */
+    sortOrder?: BarListSortOrder;
+    /** 個別に出す行の数。超えた分は合計して「その他」の 1 行にまとめる。既定 5。 */
+    maxItems?: number;
+    /** まとめた行のラベル。既定「その他」。 */
+    otherLabel?: string;
+    /** 順位に入れず、常に「その他」へ足す行の名前。例 `["(not set)", "Unassigned"]`。 */
+    exclude?: readonly string[];
+    /** 値の横に構成比(「その他」も含めた全行の合計に対する割合。整数 %)を添える。例「¥8,240万 · 43%」。既定 `false`。 */
+    showShare?: boolean;
+}
+/** The visually-hidden table `ChartFrame` renders next to the plot (`dataTable`). */
+interface ChartDataTable {
+    /** 表の見出し(`<caption>`)。 */
+    caption?: string;
+    /** 列見出し。先頭がラベル列。 */
+    columns: string[];
+    /** 行。セルは書式済みの文字列。 */
+    rows: string[][];
+}
+
+/**
+ * BarList — a ranked list of horizontal bars with the value at the end of each
+ * row: top pages, sales by store, error counts by type. Plain HTML/CSS (no
+ * ECharts), so it stays cheap inside cards and follows the theme natively.
+ *
+ * Pass rows plus the name key (`index`) and the value key (`categories: [valueKey]`),
+ * or the legacy `{ name, value, href?, color? }` items. More than
+ * `barListOptions.maxItems` (5) rows fold into one「その他」row; rows named in
+ * `barListOptions.exclude` always do (outside the ranking). Every row is
+ * painted the same light tint of the colour (rank is the bar's length; `highlight` names the one
+ * row drawn in the full colour),「その他」
+ * in the subdued other colour; `barListOptions.showShare` adds each row's share
+ * of the total after its value (「¥8,240万 · 43%」). Always renders in `ChartFrame` (title, summary,
+ * loading / empty states, a visually-hidden table); the list is as tall as its rows.
+ */
+
+interface BarListItem {
+    /** React の key。省略時は `name`。 */
+    key?: string;
+    /** 行のラベル(バーの上に出る)。 */
+    name: string;
+    value: number;
+    /** 渡すとラベルがリンクになる。 */
+    href?: string;
+    /** @deprecated この行だけ色を変える。`colors` を使う(行ごとの色は持たない)。 */
+    color?: ChartColor;
+}
+interface BarListProps<T extends object = BarListItem> extends Omit<ComponentProps<"div">, "children" | "title" | "color">, Pick<ChartCommonProps, "format" | "valueFormatter" | "title" | "summary" | "isLoading" | "emptyState"> {
+    /** 行の配列。`index` / `categories` を省くと `{ name, value, href? }` の形として読む。 */
+    data: T[];
+    /** 行の名前に使う列名。既定 `"name"`。 */
+    index?: keyof T & string;
+    /** 値に使う列名を 1 つだけ入れた配列(`["売上"]`)。最初の 1 つだけを使う。既定 `["value"]`。 */
+    categories?: (keyof T & string)[];
+    /** バーの色(`"chart-1"`〜`"chart-5"` か意味色、最初の 1 つだけを使う)。既定 `"chart-1"`。全行を同じ淡い色で塗る(順位はバーの長さで読む)。 */
+    colors?: ChartSeriesColor | ChartSeriesColor[];
+    /** 行の名前(`index` の値)→ 表示名。行のラベル・データ表に反映。例 `{ tokyo: "東京店" }`。無いキーはそのまま。データ表の列名を直すには、列のキーも渡す(`{ store: "店舗", sales: "売上" }`。既定は「項目」「値」)。 */
+    labels?: Record<string, string>;
+    /** 行の値で意味色に塗り分ける(最初に当たった規則。どれにも当たらない行は通常色)。例 `[{ lt: 40, tone: "negative" }, { lt: 70, tone: "warning" }]` */
+    thresholds?: ChartThreshold[];
+    /** 伝えたい 1 行。`index` の値(行の名前。例 `"東京店"`)で渡す。行は淡い色が既定で、この 1 行だけ濃い色(`colors` の色そのまま)になる。省略すると全部が淡い色。「その他」は選べない。 */
+    highlight?: string;
+    /** BarList 固有の設定(並べ順・行数の上限・「その他」のラベル・順位から外す行 `exclude`・値の横の構成比 `showShare`)。同名のフラットな props より優先。 */
+    barListOptions?: BarListOptions;
+    /** 渡すと行がボタンになり、クリックした行を受け取る(「その他」の行は押せない)。 */
+    onValueChange?: (item: T) => void;
+    /**
+     * 行の並べ順(`"descending"` / `"ascending"` / `"none"`)。既定 `"descending"`。
+     * @deprecated `barListOptions.sortOrder` を使う(両方あれば `barListOptions` が優先)。
+     */
+    sortOrder?: BarListSortOrder;
+    /** @deprecated `colors` を使う。 */
+    color?: ChartColor;
+    /** @deprecated マウント時にバーを伸ばす。入場アニメーションは既定で持たない。 */
+    showAnimation?: boolean;
+    /** @deprecated `valueFormatter` か `format` を使う。 */
+    formatValue?: (value: number) => string;
+    ariaLabel?: string;
+}
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+declare const BarList: (<T extends object = BarListItem>(props: BarListProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+interface CategoryBarMarker {
+    /** マーカーの位置(`values` の合計と同じ尺度)。 */
+    value: number;
+    /** ホバーで出す説明。 */
+    tooltip?: string;
+    /** 位置の変化をアニメーションする。既定 `false`(`prefers-reduced-motion` では常に無効)。 */
+    showAnimation?: boolean;
+}
+interface CategoryBarProps extends Omit<ComponentProps<"div">, "children"> {
+    /** 各区間の幅(相対値)。合計が 100 である必要はない。負の値は 0 扱い。 */
+    values: number[];
+    /** 区間の色(順に対応)。`"chart-1"`〜`"chart-5"`・意味色(`"positive"` など。面用の `--<tone>-fill` で塗る)・CSS カラー。省略時はトークン順。 */
+    colors?: ChartColor[];
+    marker?: CategoryBarMarker;
+    /** バーの上に区切りの累計値を出す。既定 `true`。 */
+    showLabels?: boolean;
+    /**
+     * 区切りの数値の書式(`"compact"` / `"currency"` / `{ type, currency }`)。他のグラフの
+     * 軸と同じ短縮形で出す(`"currency"` → `¥780万`)。既定 `"compact"`。
+     */
+    format?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道。`format` より優先する。 */
+    valueFormatter?: ValueFormatter;
+}
+declare const CategoryBar: React.ForwardRefExoticComponent<Omit<CategoryBarProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+interface ProgressCircleProps extends ComponentProps<"div"> {
+    /** 現在値。`0`〜`max` に丸める。 */
+    value?: number;
+    /** 満タンの値。既定 `100`。 */
+    max?: number;
+    /** 外側の半径(px)。既定 `32`(64px 四方)。 */
+    radius?: number;
+    /** 線の太さ(px)。既定 `6`。 */
+    strokeWidth?: number;
+    /** 色。`"chart-1"`〜`"chart-5"`・意味色(`"positive"` など。面用の `--<tone>-fill` で塗る)・CSS カラー。既定 `"chart-1"`。地のリングは同じ色を淡くしたもの。 */
+    color?: ChartColor;
+    /** マウント時と値の変化をアニメーションする。既定 `false`(`prefers-reduced-motion` では常に無効)。 */
+    showAnimation?: boolean;
+}
+declare const ProgressCircle: React.ForwardRefExoticComponent<Omit<ProgressCircleProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+interface TrackerBlock {
+    /** React の key。省略時は位置。 */
+    key?: string | number;
+    /** ブロックの色。`"positive"` / `"negative"` / `"warning"` / `"info"`(面用の `--<tone>-fill`)、`"chart-1"`〜`"chart-5"`、CSS カラー。省略時は `defaultColor`。 */
+    color?: ChartColor;
+    /** ホバーで出す説明。日付と状態・件数を入れる(例: `"10/12 失敗 3 件"`)。ブロックの accessible name にもなる。 */
+    tooltip?: string;
+}
+interface TrackerProps extends Omit<ComponentProps<"div">, "children"> {
+    data: TrackerBlock[];
+    /** `color` の無いブロックの色。既定は muted-foreground を淡くした灰色。 */
+    defaultColor?: ChartColor;
+    /** ホバー中のブロックを薄くする。既定 `true`。 */
+    hoverEffect?: boolean;
+}
+declare const Tracker: React.ForwardRefExoticComponent<Omit<TrackerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * WaterfallChart — a typed waterfall chart over `EChart`: pass the steps as rows,
+ * the name key (`index`) and the amount key (`categories: [valueKey]`) instead of
+ * an ECharts option. 売上 → 原価 → 粗利 の内訳、前期からの増減要因。
+ *
+ * Each row is a step that moves the running total by its value; rows named in
+ * `totals` are totals — a bar from 0 to the running total (or to their own value
+ * when they carry one). The bars are a stacked bar chart over a transparent base,
+ * so the value axis always starts at 0. Increase / decrease bars use the
+ * area tokens (`--positive-fill` / `--negative-fill`, swapped by `polarity`), totals are
+ * `--chart-1`; every step also prints its signed amount (+ / -), so the colour is
+ * never the only carrier of the direction. Missing values (null) draw no bar and read「—」.
+ * `mode="delta"` draws only the moves: the axis is the cumulative change from 0 (the start),
+ * totals are not bars (their numbers go in a note above the plot), so a small change against
+ * a large total is not a hairline on a tall axis; the axis still starts at 0 and can go negative.
+ * A closing「純増」bar (the net change, `--chart-1`, signed) is appended in `delta`. Value-axis ticks carry no "+" in
+ * both modes; the sign is on the bar labels only.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state, and
+ * a visually-hidden table of the steps).
+ */
+
+/**
+ * `"total"`: 合計の段を 0 からの棒として描く(既定)。`"delta"`: 増減の段だけを描く(開始を 0 とした累計増減の軸)。
+ */
+type WaterfallMode = "total" | "delta";
+interface WaterfallChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors" | "summary"> {
+    /** 段の名前に使う列名。行の並びがそのままグラフの左から右の順。 */
+    index: keyof T & string;
+    /** 増減額(合計の行は合計値)の列名を 1 つだけ入れた配列(`["金額"]`)。2 つ以上渡しても最初の 1 つだけを使う。値は number か数値文字列。 */
+    categories: NumericKeys<T>[];
+    /**
+     * 合計の段にする行の `index` の値(例 `["売上", "粗利"]`)。合計の段は 0 から累計まで届く棒で、色は `--chart-1`。
+     * 合計の行の値が null なら直前までの累計になる(計算に任せるのが確実)。値があればその値が合計になり、以降の累計はそこから続く。
+     * 最初の段が増減の行なら 0 から始まる。`mode="delta"` では棒にならず、先頭の行が「開始」、末尾の行が「終了」の注記になる。
+     */
+    totals?: string[];
+    /**
+     * 増えるのが良いか。`"higher-is-better"`(既定)は増加が `--positive-fill`・減少が `--negative-fill`(棒用の面のトークン)。
+     * 解約数のように増えて悪い指標は `"lower-is-better"` で色が入れ替わる。`"neutral"` は増減とも `--neutral-fill`(符号は付く)。
+     */
+    polarity?: Polarity;
+    /**
+     * 描き方。`"total"`(既定)は合計の段を 0 からの棒で描く。
+     * `"delta"` は開始を 0 とした累計増減の軸で増減の段だけを描き、`totals` の行は棒にせず、
+     * 開始・終了の値は図の上の注記(と要約・データ表)に出し、末尾に「純増」棒(増減の合計。`--chart-1`、符号つき)を足す。値軸の目盛に `+` は付かない。合計に対して増減が小さい(目安: 総額の 5% 未満)ときに使う。
+     * 軸は 0 起点のまま(累計が負になる段も 0 の下に描く)。例 `mode="delta"`
+     */
+    mode?: WaterfallMode;
+    /** 段の名前(`index` の値)→ 表示名。軸・ツールチップ・データ表に反映。例 `{ cogs: "売上原価" }`。無いキーはそのまま。データ表の先頭列名を直すには `index` のキーも渡す(既定は「項目」)。 */
+    labels?: Record<string, string>;
+    /**
+     * 縦軸の下限。軸は常に 0 を含むので、0 以下の値だけ有効(累計が負になる段の下に余白を取る。正の値は無視)。
+     * データが下限を下回るときは軸を広げる(切り詰めない)。`mode="total"` / `"delta"` の両方で効く。
+     * 部署別などを並べて比べるときは、全部のグラフに同じ `minValue` / `maxValue` を渡して縦軸をそろえる。
+     */
+    minValue?: number;
+    /**
+     * 縦軸の上限。データが上限を超えるときは軸を広げる(切り詰めない)。`mode="total"` / `"delta"` の両方で効く。
+     * 並べて比べるときは、全部のグラフに同じ `minValue` / `maxValue` を渡して縦軸をそろえる。
+     */
+    maxValue?: number;
+    /** y 軸ラベルの幅(px)。並べた複数グラフのプロット領域を揃えたいときに固定する。 */
+    yAxisWidth?: number;
+    /** 各棒に符号つきの増減額(合計は累計)を書く。既定 `true`。 */
+    showValues?: boolean;
+    /** ホバー時のツールチップ(増減と累計)を出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /**
+     * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら steps から「<見出し>: <最初> <値> → <最後> <値>。最大の増加は …、最大の減少は …」を組む(`mode="delta"` は「<開始> <値> → <終了> <値>（<増減>）」)。
+     * 省略時は要約なし。例: `summary="auto"`
+     */
+    summary?: string | "auto";
+    /** 見出しが無いときのプロット領域の読み上げ名。省略時は「<金額の列>のウォーターフォールチャート」。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+declare const WaterfallChart: (<T extends Record<string, unknown>>(props: WaterfallChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * ScatterChart — a typed scatter / bubble chart over `EChart`: pass rows and the
+ * two numeric column keys for the axes (`x` / `y`) instead of an ECharts option.
+ * 広告費 × 売上、客単価 × 購入頻度 のように 2 つの数値の関係と外れ値を見る。
+ *
+ * `size` turns the dots into bubbles (area proportional to the value, from 0),
+ * `series` splits the dots into series coloured with the `--chart-1..5` tokens in
+ * fixed order (more than 5 fold into one grey「その他」series), `index` names each
+ * dot in the tooltip. Both axes fit the data by default — a scatter is read by
+ * position, not by length, so it does not start at 0 (`fitToData={false}` does).
+ * Rows whose x or y is missing are left out. `labelKey` prints each dot's name beside it (dots whose
+ * labels would collide are thinned, never overprinted; on a narrow plot (under 480px) only the 2 highest dots are
+ * named, each label turned inward so it stays inside the plot, the legend moves under the plot and the y axis carries
+ * 3 intervals), `referenceLines` draws neutral guide lines at
+ * fixed x / y values, `highlight` brings some series forward and fades the rest. Renders inside `ChartFrame` (title,
+ * summary, loading skeleton, empty state, and a visually-hidden table of the dots).
+ */
+
+/** 散布図に引く基準線 1 本(`x` なら縦線、`y` なら横線)。中立色の破線で、点の色とは混ざらない。 */
+interface ScatterReferenceLine {
+    /** `"x"` は横軸の値に縦線、`"y"` は縦軸の値に横線を引く。 */
+    axis: "x" | "y";
+    /** 線を引く位置(軸の値そのまま。`format` が percent の列でも、列と同じ単位の数値を渡す)。軸の範囲に収まらないときは軸が線まで広がる。 */
+    value: number;
+    /** 線の脇に書く短い名前(「目標 25%」)。省略すると線だけ。 */
+    label?: string;
+}
+interface ScatterChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors" | "summary" | "labels" | "format" | "valueFormatter"> {
+    /** 行の配列。1 行 = 1 つの点。数値の列は number か数値文字列。x か y が数値でない行は描かない。 */
+    data: T[];
+    /** 横軸に使う数値の列名。例 `"adSpend"`。 */
+    x: NumericKeys<T>;
+    /** 縦軸に使う数値の列名。例 `"revenue"`。 */
+    y: NumericKeys<T>;
+    /** 点の大きさ(面積)に使う数値の列名。渡すとバブルチャートになる。0 を基準に面積が比例し、null・0 以下は最小の大きさ。ツールチップに値が出る。 */
+    size?: NumericKeys<T>;
+    /** 点の名前に使う列名(店舗名・キャンペーン名など)。ツールチップの見出しとデータ表の先頭列になる。 */
+    index?: keyof T & string;
+    /**
+     * 点の脇に書く文字の列名(店舗名など)。重なる点のラベルは自動で間引く(ホバーのツールチップには常に出る)。
+     * `index` が無いときはツールチップの見出しとデータ表の名前にもなる。`highlight` を使うと、強調しない系列のラベルは出さない。
+     */
+    labelKey?: keyof T & string;
+    /** 系列分けに使う列名(`"channel"` など)。値ごとに色を分け、凡例を出す。6 つ以上は点の多い 5 つ +「その他」(灰色)にまとまる。 */
+    series?: keyof T & string;
+    /** 凡例の見出し(「店の規模」)。`series` があって凡例が出るときだけ、凡例の左に小さく書く。 */
+    seriesLabel?: string;
+    /**
+     * 前面に出す系列(`series` 列の値。`"退職"` か `["退職", "休職"]`)。指定した系列は不透明で手前に、指定外は薄く背面に描く。
+     * 数が多い点の中に埋もれる少数の系列を見せたいときに使う。値が系列に一つも当たらないときは強調しない。
+     */
+    highlight?: string | string[];
+    /**
+     * 基準線(目標・平均・しきい値)。`axis: "x" | "y"` と軸の値で縦線・横線を引く。例 `[{ axis: "y", value: 25, label: "粗利率 25%" }]`
+     * 色は中立色(点の系列色とは別)。線は点の下に敷かず、軸の範囲を線まで広げる。
+     */
+    referenceLines?: ScatterReferenceLine[];
+    /** 系列色(`"chart-1"`〜`"chart-5"` か意味色)。配列は系列の出現順、record は系列名ごと。省略時はトークン順。「その他」は常に灰色。 */
+    colors?: ChartSeriesColor[] | Partial<Record<string, ChartSeriesColor>>;
+    /** 列名・系列の値 → 表示名(軸のタイトル・凡例・ツールチップ・データ表に反映)。例 `{ adSpend: "広告費", revenue: "売上" }`。無いキーはそのまま。データ表の列名の既定は「名前」「系列」「横軸」「縦軸」「大きさ」で、直すには各キーを渡す。 */
+    labels?: Record<string, string>;
+    /** 数値の書式。x・y・size の既定の書式(`"compact"` など。`{ type: "number", unit: "件" }` も可)。軸ごとに変えるなら `xFormat` / `yFormat` / `sizeFormat`。既定 `"compact"`。 */
+    format?: ValueFormat;
+    /** 横軸と x の値の書式。`format` より優先。 */
+    xFormat?: ValueFormat;
+    /** 縦軸と y の値の書式。`format` より優先。 */
+    yFormat?: ValueFormat;
+    /** `size` の値の書式(ツールチップ・データ表)。`format` より優先。 */
+    sizeFormat?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道。x・y・size すべてに使われ、`format` 系より優先する。 */
+    valueFormatter?: ValueFormatter;
+    /**
+     * 縦軸(y)の下限。散布図は 0 起点にしないので、指定した値から始める。データが下限を下回るときは軸を広げる(切り詰めない)。
+     * 並べて比べる複数の散布図には同じ `minValue` / `maxValue` と `xMinValue` / `xMaxValue` を渡して軸をそろえる。
+     */
+    minValue?: number;
+    /** 縦軸(y)の上限。データが上限を超えるときは軸を広げる(切り詰めない)。並べて比べるときは同じ値を渡す。 */
+    maxValue?: number;
+    /** 横軸(x)の下限。データが下限を下回るときは軸を広げる。並べて比べるときは同じ値を渡す。 */
+    xMinValue?: number;
+    /** 横軸(x)の上限。データが上限を超えるときは軸を広げる。並べて比べるときは同じ値を渡す。 */
+    xMaxValue?: number;
+    /** 両軸をデータの範囲に合わせる。既定 `true`(散布図は位置で読むので 0 起点にしない)。`false` で両軸を 0 から始める。 */
+    fitToData?: boolean;
+    /** 凡例(系列が 2 つ以上のときだけ)を出す。既定 `true`。 */
+    showLegend?: boolean;
+    /** ホバー時のツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /**
+     * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら「<見出し>: <点の数>点。<y の列> が最大なのは <名前>（<値>）」を組む(`index` が無いときは最大値だけ)。
+     * 省略時は要約なし。例: `summary="auto"`
+     */
+    summary?: string | "auto";
+    /** `data` が空(または描ける点が無い)ときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** 見出しが無いときのプロット領域の読み上げ名。省略時は「<y の列>×<x の列>の散布図」。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so `x` / `y` / `size` / `index` / `series` keys are checked against `data`. */
+declare const ScatterChart: (<T extends Record<string, unknown>>(props: ScatterChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+interface LegendProps {
+    /** 凡例に並べる系列名。並び順が配色の順(グラフの `categories` と同じものを渡す)。6 つ以上はグラフ側で「その他」にまとまるので、凡例も 5 つ +「その他」で渡す。 */
+    categories: string[];
+    /** 系列色(`"chart-1"`〜`"chart-5"` か意味色)。配列は系列の順、record は系列名ごと。グラフに渡した `colors` と同じものを渡す。省略時はトークン順。「その他」は常に灰色。 */
+    colors?: ChartSeriesColor[] | Partial<Record<string, ChartSeriesColor>>;
+    /** 系列名 → 表示名。グラフの `labels` と同じものを渡す。例 `{ sales: "売上" }`。無いキーはそのまま。 */
+    labels?: Record<string, string>;
+    /** 並べ方。`"horizontal"`(既定。折り返す横並び)か `"vertical"`(縦並び)。 */
+    layout?: "horizontal" | "vertical";
+    /** 凡例の読み上げ名。省略時は「凡例」。 */
+    ariaLabel?: string;
+    className?: string;
+}
+/** Plain-HTML legend. Renders nothing for an empty `categories`. */
+declare const Legend: React.ForwardRefExoticComponent<LegendProps & React.RefAttributes<HTMLUListElement>>;
+
+/** The shape the loading skeleton takes, matching the chart it stands in for. */
+type ChartSkeletonVariant = "line" | "area" | "bar" | "donut" | "list";
+interface ChartFrameProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+    /** グラフの見出し。プロット領域の `aria-labelledby` になる。 */
+    title?: string;
+    /** 1 文の要約。見出しの下に出し、プロット領域の `aria-describedby` になる。 */
+    summary?: string;
+    /** 読み込み中。`variant` の形のスケルトンを同じ高さで出す。 */
+    isLoading?: boolean;
+    /** データが無い。高さを保ったまま `emptyState` を出す。 */
+    isEmpty?: boolean;
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ。数値は px。既定 288。 */
+    height?: number | string;
+    /** スケルトンの形。既定 `"line"`。 */
+    variant?: ChartSkeletonVariant;
+    /** 見出しが無いときのプロット領域のラベル。 */
+    ariaLabel?: string;
+    /**
+     * プロット領域の役割。既定 `"img"`(canvas のグラフ)。行がボタンやリンクになる
+     * HTML のグラフ(BarList・FunnelSteps)は `"group"` にして、中身を読ませる。
+     */
+    plotRole?: "img" | "group";
+    /** 値の表。画面には出さず(`sr-only`)、スクリーンリーダー向けに図の中に置く。`chartDataTable` で作る。 */
+    dataTable?: ChartDataTable;
+    /** プロット(チャート本体)。読み込み中・空のときは描かない。 */
+    children?: ReactNode;
+}
+/**
+ * The frame. `ref` points at the plot area (the element with the fixed height),
+ * `className` / other attributes go to the outer `<figure>`.
+ */
+declare const ChartFrame: React.ForwardRefExoticComponent<ChartFrameProps & React.RefAttributes<HTMLDivElement>>;
+
 interface FunnelStep {
     /** ステップのラベル(例: "ページビュー") */
     label: string;
     /** このステップの数値 */
     value: number;
-    /** Tailwind bg カラークラス(例: "bg-chart-1")。未指定時は自動割り当て */
+    /** @deprecated Tailwind bg カラークラス(例: "bg-chart-1")。`colors` を使う。未指定時は `bg-chart-1` */
     color?: string;
     /** クリック時のハンドラ */
     onClick?: () => void;
@@ -299,17 +1627,141 @@ declare const funnelStepsVariants: (props?: ({
     size?: "sm" | "lg" | "md" | null | undefined;
     direction?: "horizontal" | "vertical" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-interface FunnelStepsProps extends ComponentProps<"div">, VariantProps<typeof funnelStepsVariants> {
-    /** ファネルステップの配列(先頭が最大幅) */
-    data: FunnelStep[];
+interface FunnelStepsProps<T extends object = FunnelStep> extends Omit<ComponentProps<"div">, "title" | "color">, Pick<ChartCommonProps, "format" | "valueFormatter" | "title" | "summary" | "isLoading" | "emptyState">, VariantProps<typeof funnelStepsVariants> {
+    /** ファネルステップの配列(先頭が最大幅)。`index` / `categories` を省くと `{ label, value }` の形として読む。 */
+    data: T[];
+    /** ステップのラベルに使う列名。既定 `"label"`。 */
+    index?: keyof T & string;
+    /** 値に使う列名を 1 つだけ入れた配列(`["件数"]`)。最初の 1 つだけを使う。既定 `["value"]`。 */
+    categories?: (keyof T & string)[];
+    /** 段の色(`"chart-1"`〜`"chart-5"`、段の順に繰り返す)。省略時はすべて `"chart-1"`(段は同じ量の絞り込みなので 1 色)。 */
+    colors?: ChartColorToken[];
+    /** ステップの名前(`index` の値)→ 表示名。ラベル・データ表に反映。例 `{ visit: "訪問" }`。無いキーはそのまま。データ表の列名を直すには、列のキーも渡す(`{ label: "工程", value: "人数" }`。既定は「ステップ」「値」)。 */
+    labels?: Record<string, string>;
+    /** 伝えたい 1 段。`index` の値(ステップ名。例 `"購入"`)で渡す。段は淡い色が既定で、この 1 段だけ濃い色(`colors` の色そのまま)になる。省略すると全部が淡い色。 */
+    highlight?: string;
     /** ステップ間のコンバージョン率を表示する */
     showConversion?: boolean;
-    /** 値の表示フォーマット関数 */
+    /** 前期の各段の値(`data` と同じ順)。渡すと転換率の横に前期比(pt)を出し、最も下がった率を強調する。`label` は列見出し・注記の名前(既定「前期」)。KpiCard の `comparison` と同じ形。例 `comparison={{ values: [231_400, 1_210, 402] }}` */
+    comparison?: {
+        values: readonly (number | null)[];
+        label?: string;
+    };
+    /** @deprecated `valueFormatter` か `format` を使う。 */
     formatValue?: (value: number) => string;
-    /** マウント時のエントリアニメーションを有効にする */
+    /** マウント時のエントリアニメーションを有効にする。既定 `false`。 */
     animate?: boolean;
+    ariaLabel?: string;
 }
-declare const FunnelSteps: React.ForwardRefExoticComponent<Omit<FunnelStepsProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+declare const FunnelSteps: (<T extends object = FunnelStep>(props: FunnelStepsProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * Heatmap — a typed heatmap over `EChart`: pass rows, the column keys for the
+ * x axis / y axis (`x` / `y`) and the number to shade by (`value`) instead of an
+ * ECharts option. Cohort retention (週 × コホート), weekday × hour counts, …
+ *
+ * Shading is a single-colour ramp (light → dark) of one theme colour
+ * (`--chart-1` by default; `tone` moves it to another series token or a meaning
+ * colour) and follows light/dark. A cell with no value (null / missing row) is left
+ * unpainted (transparent, no text), never shaded like 0; the tooltip and the table say「—」.
+ * The shading range is the data's min–max unless `scale` fixes it. The ramp's lowest end is the tone mixed 20% into
+ * the surface (`color-mix(in oklch, var(--chart-1) 20%, var(--card))`), so the lowest cell never melts into the
+ * background in dark mode; the legend's gradient starts at the same colour.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state)
+ * with the numbers as a screen-reader table.
+ */
+
+/** Columns of `T` that hold numbers (null / undefined allowed for gaps); untyped rows keep every key. */
+type NumericColumn<T> = {
+    [K in keyof T]-?: unknown extends T[K] ? K : T[K] extends number | bigint | null | undefined ? K : never;
+}[keyof T] & string;
+interface HeatmapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = 1 マス(x と y の組)。同じ組が複数あれば後の行が勝つ。値は number か数値文字列。 */
+    data: T[];
+    /** 横軸(列)に使う列名。例 `"hour"`・`"week"`。 */
+    x: keyof T & string;
+    /** 縦軸(行)に使う列名。例 `"weekday"`・`"cohort"`。先頭の行が一番上。 */
+    y: keyof T & string;
+    /** マスの濃さを決める数値の列名。null・欠損・数値でない値のマスは塗らない(0 とは別。ツールチップとデータ表は「—」)。 */
+    value: NumericColumn<T>;
+    /** 横軸の並び順(と表示するマス)。省略時は `data` の出現順。ここに無い x の行は描かない。 */
+    xLabels?: string[];
+    /** 縦軸の並び順(と表示するマス)。省略時は `data` の出現順。ここに無い y の行は描かない。 */
+    yLabels?: string[];
+    /**
+     * 列名・軸の値 → 表示名(軸・ツールチップ・データ表に反映)。
+     * 例 `{ mon: "月曜", value: "件数", breached: "SLA 未達" }`。無いキーはそのまま。データ表の先頭列名は `y` のキーを渡すと直る(既定は「項目」)。
+     */
+    labels?: Record<string, string>;
+    /** 数値の書式(`"number"` / `"percent"` / `{ type: "number", unit: "件" }` など)。マス内・ツールチップ・データ表で同じ書式。既定 `"number"`。 */
+    format?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道。`format` より優先する。 */
+    valueFormatter?: ValueFormatter;
+    /**
+     * 濃淡の色。`"chart-1"`〜`"chart-5"` か意味色(`"positive"` / `"warning"` / `"negative"` / `"neutral"`)。
+     * 薄い → 濃いの単色グラデーション(レインボーにしない)。既定 `"chart-1"`。
+     */
+    tone?: ChartSeriesColor;
+    /**
+     * 濃さの固定スケール。省略時はデータの最小〜最大(自動)。比べたい上限・下限が決まっているときだけ渡す。`min` 以下が最も薄く、`max` 以上が最も濃い(範囲外の値は端に丸める)。凡例の両端もこの値になる。
+     * 継続率(0〜100)なら `{ min: 0, max: 100 }`。片方だけでもよく、省略した側はデータの最小・最大。
+     * `minValue` / `maxValue` より優先する。
+     */
+    scale?: {
+        min?: number;
+        max?: number;
+    };
+    /** @deprecated `scale={{ min }}` を使う。濃さの下限(この値以下が最も薄い)。 */
+    minValue?: number;
+    /** @deprecated `scale={{ max }}` を使う。濃さの上限(この値以上が最も濃い)。 */
+    maxValue?: number;
+    /** マスの中に値を書く(`format` どおり)。既定 `false`。 */
+    showValues?: boolean;
+    /** 凡例(薄い → 濃いの帯と両端の値)を出す。既定 `true`。 */
+    showLegend?: boolean;
+    /** ホバーでツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /**
+     * ツールチップとデータ表に添える列(同じ行の別の数値)。例 `["breached"]` →「月曜 9時台 電話 12件・SLA 未達 2件」の「SLA 未達 2件」。
+     * 列名の表示は `labels`、値は `format`(単位つきの書式なら同じ単位)で出る。
+     */
+    details?: NumericColumn<T>[];
+    /**
+     * この列が真(`true` / 0 でない数)の行のマスに、注意色(`--negative`)の枠を付ける。
+     * 例 SLA 未達が集中したマス。色だけでなく枠の太さでも区別でき、ツールチップに「要注意」と出る。
+     */
+    flag?: keyof T & string;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。`"auto"` で最大のマスから自動生成。 */
+    summary?: string | "auto";
+    /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ(px)。既定 288。 */
+    height?: number;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /** グラフ右上に PNG 保存/コピーのボタンを出す。見出しがあれば PNG の上に含める(`{ includeTitle: false }` で含めない)。 */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。 */
+    fileName?: string;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。省略時は `<yの列>×<xの列>のヒートマップ`。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so `x` / `y` / `value` keys are checked against `data`. */
+declare const Heatmap: (<T extends Record<string, unknown>>(props: HeatmapProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
 
 type SparklineVariant = "line" | "bar";
 interface SparklineDataPoint {
@@ -323,11 +1775,103 @@ interface SparklineProps extends SVGAttributes<SVGSVGElement> {
     /** Tailwind text-colour class; drives both stroke and fill via `currentColor`. */
     color?: string;
     area?: boolean;
+    /** マウント時に線を引く / 棒を伸ばす。既定 `false`(`prefers-reduced-motion` では常に無効)。 */
     animate?: boolean;
+    /**
+     * 点の強調(Tufte 流)。`"auto"` は最新・最大・最小の 3 点だけに小さな点を打つ
+     * (最新は系列の色、最大・最小は muted)。`"latest"` は最新の 1 点だけ、`"none"` は線だけ。`variant="line"` のときだけ効く。既定 `"auto"`。
+     */
+    highlight?: ChartHighlight | "latest";
+    /** 指定すると `role="img"` で読み上げ対象にする。省略時は装飾として `aria-hidden`。 */
+    "aria-label"?: string;
     className?: string;
 }
 declare const Sparkline: React.ForwardRefExoticComponent<SparklineProps & React.RefAttributes<SVGSVGElement>>;
 
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> {
+        /**
+         * Classes put on the column's header and body cells — e.g.
+         * `"hidden md:table-cell"` to drop a column on narrow screens.
+         */
+        className?: string;
+        /**
+         * 列の数値書式。`cell` を持たない列だけに効き、右寄せ・tabular-nums で描く。
+         * 行ごとに通貨が変わるときは関数で行を受ける。CSV の「表示」値にも使われる。
+         *
+         * @example
+         * meta: { format: "currency" }
+         * meta: { format: (row) => ({ type: "currency", currency: row.currency, notation: "standard" }) }
+         */
+        format?: ValueFormat | ((row: TData) => ValueFormat);
+        /**
+         * 日付の列の書式（`formatDate` の `style`）。`cell` を持たない列だけに効く。左寄せ・tabular-nums で描き、
+         * 値は `Date`・エポックミリ秒・日付文字列（`"2026-10-20"`、ISO 8601）。CSV の「表示」値にも使われる。
+         * `format`（数値）とは併用しない。
+         *
+         * @example
+         * meta: { dateFormat: "date" }
+         * meta: { dateFormat: "datetime", nullLabel: "未更新" }
+         */
+        dateFormat?: DateStyle;
+        /**
+         * `dateFormat` の列の日時を出すタイムゾーン（IANA 名。例 `"Asia/Tokyo"`）。既定は実行環境（ブラウザ）のタイムゾーン。
+         * サーバーとブラウザで表示が食い違う（SSR）なら固定する。`dateFormat` の列だけに効き、CSV の「表示」値にも同じ値を使う。
+         * `"2026-10-20"` のような日付だけの文字列は、どのタイムゾーンでもその暦日のまま。
+         *
+         * @example
+         * meta: { dateFormat: "datetime", timeZone: "Asia/Tokyo" }
+         */
+        timeZone?: string;
+        /**
+         * 値が無いときの表示。既定 `"—"`。null / undefined（数値は NaN も）に効き、文字列の列では空文字 `""` も値なしとして扱う。
+         * `format` / `dateFormat` を持つ列と、書式なしの文字列の列に効く。`cell` を自前で書いた列には効かない（`cell` の中で扱う）。
+         * CSV の「表示」値は、書式付き・日付の列だけ `nullLabel` で書き、書式なしの文字列の列は空欄のまま。
+         *
+         * @example
+         * meta: { format: "number", nullLabel: "未集計" }
+         * meta: { nullLabel: "未設定" }  // 書式なしの文字列の列
+         */
+        nullLabel?: string;
+        /**
+         * 値の範囲でセルを意味色に塗り分ける規則（最初に当たった規則。どれにも当たらない値は通常色）。
+         * `cell` を持たない列だけに効き、BarChart / BarList の `thresholds` と同じ型・同じ判定。
+         * 色だけに頼らず、色に応じた記号（○ / △ / × / −）を値の前に添える。CSV は生の値のまま。
+         *
+         * @example
+         * meta: { format: { type: "percent", divisor: 100 }, thresholds: [{ lt: 40, tone: "negative" }, { lt: 70, tone: "warning" }] }
+         */
+        thresholds?: ChartThreshold[];
+        /**
+         * 狭い幅で列を隠す順。数が小さい列から隠れる(表の置き場の幅が 1 は 640px 未満、2 は 520px 未満、3 は 400px 未満)。
+         * 書かない列と 4 以上の列は、どの幅でも出す(部署名・離職率のような肝心の列に使う)。
+         * 画面の幅ではなく、表を置いた場所の幅(コンテナ幅)で決まる。隠した列は DOM にも読み上げにも出ず、CSV の出力には含まれる。
+         *
+         * @example
+         * meta: { format: "number", priority: 1 }  // 幅が足りないときに最初に隠す
+         */
+        priority?: number;
+        /**
+         * true にすると、増減(`Delta`)など「直前の列の値との比較」を表示する列になる。表の置き場が 320px 未満に狭まると、
+         * この列は隠れる代わりに、直前の列(値の列)のセルの下に同じ内容を小さく(text-xs)積んで出す。比較は消えない。
+         * `priority` で隠す順は最後(どの列よりも後)になり、この列の `priority` は無視される。直前の列も `priority` に関わらず残る。
+         * 列の `cell` に `<Delta variant="inline" … />` を書く。直前に列が無いときは積まず、通常の列として出す。CSV には通常の列として含まれる。
+         *
+         * @example
+         * { accessorKey: "revenue", header: "売上", meta: { format: "currency" } },
+         * { id: "revenueDelta", header: "前月比", meta: { comparison: true }, cell: ({ row }) => <Delta variant="inline" value={row.original.revenue} comparison={{ previous: row.original.prev, vs: "prior-period", grain: "month" }} /> }
+         */
+        comparison?: boolean;
+        /**
+         * 列の寄せ。見出し(ソートボタンを含む)とセルの両方に効く。既定は、`format` / `thresholds` の列と
+         * `comparison` の列(増減 `Delta`)が `"right"`、それ以外は `"left"`。右寄せの列は tabular-nums で描く。
+         *
+         * @example
+         * meta: { align: "right" }
+         */
+        align?: "left" | "right";
+    }
+}
 interface DataTableContextValue<TData> {
     table: Table<TData>;
     selectedRows: TData[];
@@ -338,6 +1882,7 @@ interface DataTableContextValue<TData> {
     enablePagination: boolean;
     enableRowSelection: boolean;
     visibleColumnCount: number;
+    isLoading: boolean;
 }
 /**
  * @template TData 行データ型
@@ -352,7 +1897,8 @@ interface DataTableProps<TData, TValue> {
      * literal が `string` に拡張され型エラーになる。
      *
      * @example
-     * import type { ColumnDef } from "@squadbase/vantage/components"
+     * import { DataTable, type ColumnDef } from "@/components/data-table"
+     * // Vantage: import { DataTable, type ColumnDef } from "@squadbase/vantage/components"
      *
      * const columns: ColumnDef<User>[] = [
      *   { accessorKey: "id", header: "ID" },
@@ -373,12 +1919,54 @@ interface DataTableProps<TData, TValue> {
     enablePagination?: boolean;
     pagination?: PaginationState;
     onPaginationChange?: OnChangeFn<PaginationState>;
+    /**
+     * サーバー側ページング時の総ページ数。指定すると manualPagination になる。
+     *
+     * @example
+     * <DataTable pageCount={data.pageCount} … />
+     */
     pageCount?: number;
+    /**
+     * サーバー側ページング時の総件数。指定すると manualPagination になり、ページ数は
+     * `rowCount / pageSize` から導かれ、「N件中」もこの値を使う（`pageCount` を同時に渡せばそちらが優先）。
+     *
+     * @example
+     * <DataTable rowCount={1240} pagination={pagination} onPaginationChange={setPagination} … />
+     */
+    rowCount?: number;
+    /**
+     * true にすると絞り込みを表では行わず、`data` をそのまま使う（サーバー側で絞り込む）。
+     *
+     * @example
+     * <DataTable manualFiltering globalFilter={q} onGlobalFilterChange={setQ} … />
+     */
+    manualFiltering?: boolean;
+    /**
+     * true にすると並べ替えを表では行わず、`data` の順をそのまま使う（サーバー側で並べ替える）。
+     *
+     * @example
+     * <DataTable manualSorting sorting={sorting} onSortingChange={setSorting} … />
+     */
+    manualSorting?: boolean;
+    /**
+     * 読み込み中。Content はスケルトン行、Pagination のボタンは無効、表は aria-busy になる。
+     *
+     * @example
+     * <DataTable isLoading={query.isFetching} … />
+     */
+    isLoading?: boolean;
     enableRowSelection?: boolean;
     rowSelection?: RowSelectionState;
     onRowSelectionChange?: OnChangeFn<RowSelectionState>;
     columnVisibility?: VisibilityState;
     onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
+    /**
+     * TanStack Table の `meta`。表全体で共有する値(行を更新する関数など)を渡し、列定義の `cell` から
+     * `table.options.meta` で読む。列ごとの書式は列定義の `meta.format` に書く(こちらではない)。
+     *
+     * @example
+     * <DataTable meta={{ updateRow: (id, patch) => mutate({ id, patch }) }} … />
+     */
     meta?: TableMeta<TData>;
     className?: string;
     /** Required — the parts to render (toolbar, content, pagination). */
@@ -391,6 +1979,32 @@ interface DataTableToolbarProps extends HTMLAttributes<HTMLDivElement> {
 }
 interface DataTableContentProps extends HTMLAttributes<HTMLDivElement> {
 }
+interface DataTableExportProps {
+    /**
+     * 保存するファイル名。既定 `"export.csv"`。
+     *
+     * @example
+     * <DataTableExport fileName="sales-2025.csv" />
+     */
+    fileName?: string;
+    /**
+     * `"display"`（既定）は `meta.format` どおりの表示文字列、`"raw"` は生の値を書き出す。
+     *
+     * @example
+     * <DataTableExport values="raw" />
+     */
+    values?: CsvValues;
+    /**
+     * `"filtered"`（既定）は並べ替え・絞り込み後の全ページ、`"page"` は表示中のページだけ。
+     *
+     * @example
+     * <DataTableExport scope="page" />
+     */
+    scope?: CsvScope;
+    /** ボタンの文言。既定 `"CSV を書き出す"`。 */
+    children?: ReactNode;
+    className?: string;
+}
 interface DataTablePaginationProps extends HTMLAttributes<HTMLDivElement> {
     pageSizeOptions?: number[];
 }
@@ -403,12 +2017,26 @@ interface DataTableColumnVisibilityProps {
 type DataTablePresetProps<TData, TValue> = Omit<DataTableProps<TData, TValue>, "children"> & {
     enableColumnVisibility?: boolean;
     columnLabels?: Record<string, string>;
+    /**
+     * true にすると toolbar に CSV 書き出しボタン（`DataTableExport`）を置く。既定 false。
+     *
+     * @example
+     * <DataTablePreset exportable … />
+     */
+    exportable?: boolean;
+    /**
+     * `exportable` のときの保存ファイル名。既定 `"export.csv"`。
+     *
+     * @example
+     * <DataTablePreset exportable exportFileName="sales.csv" … />
+     */
+    exportFileName?: string;
     /** Extension slots */
     toolbar?: ReactNode;
     bulkActions?: (selectedRows: TData[]) => ReactNode;
 };
 declare function useDataTable<TData>(): DataTableContextValue<TData>;
-declare function DataTable<TData, TValue>({ columns, data, enableSorting, sorting: sortingProp, onSortingChange, enableFiltering, columnFilters: columnFiltersProp, onColumnFiltersChange, globalFilter: globalFilterProp, onGlobalFilterChange, enablePagination, pagination: paginationProp, onPaginationChange, pageCount, enableRowSelection, rowSelection: rowSelectionProp, onRowSelectionChange, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, meta, className, children, }: DataTableProps<TData, TValue>): React.JSX.Element;
+declare function DataTable<TData, TValue>({ columns, data, enableSorting, sorting: sortingProp, onSortingChange, enableFiltering, columnFilters: columnFiltersProp, onColumnFiltersChange, globalFilter: globalFilterProp, onGlobalFilterChange, enablePagination, pagination: paginationProp, onPaginationChange, pageCount, rowCount, manualFiltering, manualSorting, isLoading, enableRowSelection, rowSelection: rowSelectionProp, onRowSelectionChange, columnVisibility: columnVisibilityProp, onColumnVisibilityChange, meta, className, children, }: DataTableProps<TData, TValue>): React.JSX.Element;
 declare namespace DataTable {
     var displayName: string;
 }
@@ -416,8 +2044,39 @@ declare const DataTableToolbar: React.ForwardRefExoticComponent<DataTableToolbar
 declare const DataTableContent: React.ForwardRefExoticComponent<DataTableContentProps & React.RefAttributes<HTMLDivElement>>;
 declare const DataTablePagination: React.ForwardRefExoticComponent<DataTablePaginationProps & React.RefAttributes<HTMLDivElement>>;
 declare const DataTableColumnVisibility: React.ForwardRefExoticComponent<DataTableColumnVisibilityProps & React.RefAttributes<HTMLButtonElement>>;
+type CsvCell = string | number | null | undefined;
+type CsvValues = "display" | "raw";
+type CsvScope = "filtered" | "page";
+/**
+ * CSV 文字列を作る純関数（RFC 4180: CRLF、`,` `"` 改行を含む欄は `"` で囲み `"` は二重化）。
+ * 既定で BOM 付き UTF-8（Excel で文字化けしない）。`guardFormulas` が true の間、先頭が
+ * `= + - @` の文字列欄には `'` を付けて数式として実行されないようにする（数値と符号付きの数値表記は除く）。
+ *
+ * @example
+ * toCsv(["月", "売上"], [["2025-01", 1200], ["2025-02", null]])
+ * // "\uFEFF月,売上\r\n2025-01,1200\r\n2025-02,"
+ */
+declare function toCsv(header: string[], rows: CsvCell[][], options?: {
+    bom?: boolean;
+    guardFormulas?: boolean;
+}): string;
+/**
+ * 表の現在の状態から CSV を作る。行は画面と同じ並べ替え・絞り込み後の順、列は表示中の列のみ。
+ *
+ * @example
+ * const csv = tableToCsv(table, { values: "raw", scope: "page" })
+ */
+declare function tableToCsv<TData>(table: Table<TData>, { values, scope }?: {
+    values?: CsvValues;
+    scope?: CsvScope;
+}): string;
+/** toolbar に置く CSV 書き出しボタン。`useDataTable()` の table から画面と同じ順・同じ集合を書き出す。 */
+declare function DataTableExport({ fileName, values, scope, children, className, }: DataTableExportProps): React.JSX.Element;
+declare namespace DataTableExport {
+    var displayName: string;
+}
 /** The usual arrangement — toolbar, body and pagination — in one component. */
-declare function DataTablePreset<TData, TValue>({ enableColumnVisibility, columnLabels, toolbar, bulkActions, ...tableProps }: DataTablePresetProps<TData, TValue>): React.JSX.Element;
+declare function DataTablePreset<TData, TValue>({ enableColumnVisibility, columnLabels, exportable, exportFileName, toolbar, bulkActions, ...tableProps }: DataTablePresetProps<TData, TValue>): React.JSX.Element;
 declare namespace DataTablePreset {
     var displayName: string;
 }
@@ -435,9 +2094,15 @@ interface FilterBarSelectProps {
     label: string;
     options: FilterOption[];
     placeholder?: string;
+    /**
+     * 渡すと、選択肢の先頭に「絞り込まない」項目をこの文言で足す（例: `"すべて"`）。選ぶとこのキーを値から外す（`undefined`）ので、
+     * アクティブチップにも出ない。絞り込んでいないときのトリガーは `placeholder`（既定は `label`）のまま。既定は足さない。
+     * @example allLabel="すべて"
+     */
+    allLabel?: string;
     className?: string;
 }
-declare function FilterBarSelect({ filterKey, label, options, placeholder, className, }: FilterBarSelectProps): React.JSX.Element;
+declare function FilterBarSelect({ filterKey, label, options, placeholder, allLabel, className, }: FilterBarSelectProps): React.JSX.Element;
 declare namespace FilterBarSelect {
     var displayName: string;
 }
@@ -483,23 +2148,47 @@ declare namespace FilterBarPreset {
     var displayName: string;
 }
 
+/** 既定のプリセット（英語・4 月始まり）。`locale` / `fiscalYearStartMonth` を変えるなら `createDatePresets` か DateRangePicker の同名 props。 */
 declare const defaultPresets: PresetItem[];
 interface DateRangePickerProps {
     /**
-     * 選択中の日付範囲。型は Vantage 独自の `DateRange`。
+     * 選択中の日付範囲。型はこの部品独自の `DateRange`。
      * react-day-picker の `DateRange` とは別物なので注意 — そちらが必要なら
      * このファイルの末尾で re-export している `RdpDateRange` を使う。
      *
      * @example
-     * import type { DateRange } from "@squadbase/vantage/components"
+     * import { DateRangePicker, type DateRange } from "@/components/date-range-picker"
+     * // Vantage: import { DateRangePicker, type DateRange } from "@squadbase/vantage/components"
      *
      * const [range, setRange] = useState<DateRange | undefined>()
      * <DateRangePicker value={range} onChange={setRange} />
      */
     value?: DateRange;
     onChange?: (range: DateRange) => void;
+    /**
+     * ショートカットの一覧。指定すると `locale` / `fiscalYearStartMonth` による既定の一覧の代わりに使う。
+     *
+     * @example
+     * presets={[{ label: "直近 10 日", getValue: () => ({ from: subDays(new Date(), 9), to: new Date() }) }]}
+     */
     presets?: PresetItem[];
     showPresets?: boolean;
+    /**
+     * プリセットのラベルとカレンダーの月名・曜日の言語。`ja*` なら日本語、それ以外は英語。既定 `"en-US"`（英語）。
+     * 他部品の既定は ja-JP だが、この部品は従来のプリセットが英語だったので既存の見た目を保つため英語を既定にしている。
+     *
+     * @example
+     * <DateRangePicker locale="ja-JP" />
+     */
+    locale?: string;
+    /**
+     * 年度の開始月（1-12）。「今年度」「前年度」と、年度基準の「今四半期」「前四半期」の区切りになる。既定 `4`（4 月始まり）。
+     * 範囲外・整数でない値は 4 として扱う。
+     *
+     * @example
+     * <DateRangePicker fiscalYearStartMonth={1} />
+     */
+    fiscalYearStartMonth?: number;
     maxDate?: Date;
     minDate?: Date;
     placeholder?: string;
@@ -560,29 +2249,287 @@ declare const metricValueVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface MetricValueProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof metricValueVariants> {
 }
+/** @deprecated KPI の数字は KpiCard を使う。 */
 declare const MetricValue: React.ForwardRefExoticComponent<MetricValueProps & React.RefAttributes<HTMLDivElement>>;
 interface MetricUnitProps extends HTMLAttributes<HTMLSpanElement> {
 }
+/** @deprecated KPI の単位は KpiCard の `format`（`{ type: "number", unit: "社" }`）で付ける。 */
 declare const MetricUnit: React.ForwardRefExoticComponent<MetricUnitProps & React.RefAttributes<HTMLSpanElement>>;
 
+/**
+ * Lightweight KPI insights: progress toward a target (with a simple linear pace
+ * projection) and "highest / lowest in N periods" record detection. No statistics.
+ *
+ * Both follow `polarity`: for a lower-is-better metric (churn, cost) the target
+ * is met at or below it, and the record is the lowest value, never the highest.
+ */
+
+interface KpiPeriod {
+    start: Date | string | number;
+    end: Date | string | number;
+}
+interface TargetProgress {
+    target: number;
+    /**
+     * Distance left to the target, never negative: `target − current` when higher
+     * is better, `current − target` when lower is better. 0 once achieved.
+     */
+    remaining: number;
+    /** Whether the current value meets the target (≥ for higher-is-better, ≤ for lower-is-better). */
+    achieved: boolean;
+    /**
+     * How far the target is met, as a ratio: `current / target` when higher is
+     * better, `target / current` when lower is better (1 = exactly on target).
+     */
+    achievement: number;
+    /** achievement / elapsed when the period is in progress, else null. Higher-is-better only. */
+    projected: number | null;
+    /** Fraction of the period elapsed at `now`, or null without a valid period. */
+    elapsed: number | null;
+}
+declare function computeTargetProgress(current: number | null | undefined, target: number | null | undefined, options?: {
+    period?: KpiPeriod;
+    now?: Date | number;
+    polarity?: Polarity;
+}): TargetProgress | null;
+/** @deprecated Use `PeriodGrain` (same values). */
+type HistoryGrain = PeriodGrain;
+/**
+ * The grain of a period from its length: ~1 day, 7 days, 28–31 days, 89–92 days
+ * or 365–366 days. Anything else (a custom range) returns undefined.
+ */
+declare function inferPeriodGrain(period: KpiPeriod | null | undefined): PeriodGrain | undefined;
+interface RecordInsight {
+    span: number;
+    grain: PeriodGrain;
+    /** "highest" for higher-is-better, "lowest" for lower-is-better. */
+    kind: "highest" | "lowest";
+    label: string;
+}
+/** Fewer finite points than this never yields a record. */
+declare const RECORD_MIN_POINTS = 6;
+/**
+ * The latest point is a record when it beats every earlier finite point:
+ * strictly highest for higher-is-better, strictly lowest for lower-is-better.
+ */
+declare function detectRecord(history: ReadonlyArray<number | null | undefined> | null | undefined, grain?: PeriodGrain, polarity?: Polarity): RecordInsight | null;
+
+interface KpiCardSource {
+    /** Period the data covers (e.g. "2023-04 以降"). ISO year-months / dates in it are written by the card ("2023年4月 以降"). */
+    period?: string;
+    /** Number of rows aggregated; formatted by the card ("48,210件から集計"). */
+    count?: number;
+    /**
+     * 集計から除いた行数。出典の脚注に「12件を除外」と添える（ja 以外は「12 excluded」）。0 や負の値は出さない。
+     * 除外の理由（テスト用アカウント、欠損など）は `note` に書く。
+     * @example source={{ count: 48_210, excluded: 12, note: "テスト用アカウントを除外" }}
+     */
+    excluded?: number;
+    /** Data source name (e.g. "Snowflake"). */
+    name?: string;
+    /** 換算・税抜などの脚注。フッターに出す。例: `note: "税抜、1 ドル=150 円で換算"`。数字を使う説明は summary ではなくここへ。 */
+    note?: string;
+}
+interface KpiCardProps extends Omit<ComponentProps<"div">, "children"> {
+    /** Metric name (tier 1). */
+    label: string;
+    /** Current value (tier 2). null / undefined renders "—". */
+    value: number | null | undefined;
+    /**
+     * Value format, also used for previous / target / remaining. Default `"compact"`.
+     * `"currency"` is JPY in 万・億; `"percent"` takes a ratio (0.021 → 2.1%) and
+     * switches the delta to points. See `formatValue` for the full table.
+     */
+    format?: ValueFormat;
+    /** Default `"ja-JP"`. */
+    locale?: string;
+    /**
+     * What the value is compared against; drives the delta (tier 3) and previous line (tier 4).
+     * 前期・前年・目標以外は `vs: "custom"` + `label`（バッジの呼び名。末尾の「比」を外した語が前期実績行の呼び名になる）。
+     * @example comparison={{ previous: 617, vs: "custom", label: "昨日比" }}
+     */
+    comparison?: Comparison;
+    /**
+     * 前年比と前月比など、複数の比較を併記する。先頭だけが前期実績行と summary に使われ、2 つ目以降は Delta 行のみ。`comparison` も渡したらそれが先頭。バッジは値の下に並ぶ。
+     * @example comparisons={[{ previous: 4_290, vs: "prior-period", grain: "month" }, { previous: 3_900, vs: "prior-year", grain: "month" }]}  /  comparisons={[{ previous: 617, vs: "custom", label: "昨日比" }, { previous: 590, vs: "custom", label: "先週の同じ曜日比" }]}
+     */
+    comparisons?: Comparison[];
+    /**
+     * 確定前の値。値の隣に「速報」バッジを出し、目標の「達成」を言い切らず、最高記録の判定も出さない。
+     * @example provisional  /  provisional={{ label: "暫定" }}
+     */
+    provisional?: boolean | {
+        label?: string;
+    };
+    /** Whether a rise is good. Default `"higher-is-better"`. `"neutral"` never colours the change and skips the target and record logic. */
+    polarity?: Polarity;
+    /** `"relative"` ("+12.4%"), `"points"` ("-0.5pt") or `"difference"` ("+¥530万", in `format`). Default: points for a `percent` format, else relative. */
+    change?: ChangeDisplay;
+    /** Absolute ratio below which the change reads as flat. Default 0.01. */
+    neutralBand?: number;
+    /** Show the previous actual ("前月 400"). Default true; needs `comparison`. */
+    showPrevious?: boolean;
+    /** Conclusion sentence template (tier 5); see the placeholders above. */
+    summary?: string;
+    /**
+     * Target for the current period. Under the value it adds a 6px bar (actual, the pace
+     * projection, a tick at the target) and one line "目標の 49%・このペースなら 98%"
+     * (the projection only while `period` is in progress). With `polarity="lower-is-better"`
+     * or a rate target (points) there is no bar: "目標 … まであと …" in the footer.
+     */
+    target?: number;
+    /**
+     * 目標行・見込み行での目標の呼び名。既定「目標」。予算・計画・ノルマなど業務の言葉に合わせる。
+     * @example targetLabel="予算"  // 予算まであと ¥2,934万（98.1% 達成）
+     */
+    targetLabel?: string;
+    /**
+     * 目標に対する進み具合の出し方。`"achievement"` は達成率（現在値 ÷ 目標。「98.1% 達成」）、`"points"` は目標との差（「あと 2.8pt」）。
+     * 既定は `format` から決まる: `percent`（率）は `"points"`（率を率で割った達成度は読めない）、それ以外は `"achievement"`。
+     * `"points"` のとき `{achievement}` は目標との符号付きの差（"-2.8pt"）になり、見込み行は出ない。
+     */
+    targetDisplay?: "achievement" | "points";
+    /** Current period; with `target`, adds a pace projection while the period is in progress. */
+    period?: KpiPeriod;
+    /** Series ending at the current period (last point = `value`); adds a record badge. */
+    history?: ReadonlyArray<number | null | undefined>;
+    /** Grain of `history` (and of the comparison labels). Default: inferred from `period`, else `"month"` for the record. */
+    historyGrain?: PeriodGrain;
+    /**
+     * `history` が 6 点以上あるとき、フッター末尾に軸なしのスパークライン（高さ 32px・`--chart-1`・最新点だけドット）を出す。既定 true。
+     * 推移を出したくないカードは `showHistory={false}`（記録バッジは `history` があれば出る）。
+     * @example showHistory={false}
+     */
+    showHistory?: boolean;
+    /** Data source footnote. */
+    source?: KpiCardSource;
+    /** When the data was last refreshed: "3 分前に更新". 出し方は `updatedAtDisplay`。 */
+    updatedAt?: Date | string | number;
+    /**
+     * `updatedAt` の出し方。`"relative"`（既定）は「3 分前に更新」、`"absolute"` は「2026/10/20 14:30 に更新」、
+     * `"both"` は「2026/10/20 14:30 に更新（3 分前）」。絶対時刻は実行環境のタイムゾーンで出す（`timeZone` で固定できる）。
+     * 画面を印刷・スクリーンショットで残すなら、時間が経っても読める `"absolute"` か `"both"`。
+     * @example updatedAtDisplay="absolute"
+     */
+    updatedAtDisplay?: "relative" | "absolute" | "both";
+    /**
+     * `updatedAt` の絶対時刻（`updatedAtDisplay` が `"absolute"` / `"both"`）を出すタイムゾーン（IANA 名。例 `"Asia/Tokyo"`）。
+     * 既定は実行環境（ブラウザ）のタイムゾーン。サーバーとブラウザで表示が食い違う（SSR）なら固定する。「3 分前」には影響しない。
+     * @example updatedAtDisplay="absolute" timeZone="Asia/Tokyo"
+     */
+    timeZone?: string;
+    /** Reference time for the projection and relative time (for deterministic rendering). */
+    now?: Date | number;
+    /** Render a skeleton with the final shape instead of the values. */
+    isLoading?: boolean;
+    /**
+     * `"sm"` は Sheet の中など狭い場所で 2 枚を横に並べるときの小さいサイズ。値の文字と余白が一段小さくなり、スパークラインは出さない。既定 `"default"`。
+     * @example size="sm"
+     */
+    size?: "default" | "sm";
+}
+/**
+ * Fill `{name}` placeholders from `values`. Unknown names stay as written.
+ *
+ * Without `fallback`, a known name whose value is null / undefined / empty
+ * becomes "—". With `fallback`, any such missing value replaces the whole
+ * sentence with `fallback` (which may be null to drop it).
+ */
+declare function fillKpiTemplate(template: string, values: Readonly<Record<string, string | null | undefined>>): string;
+declare function fillKpiTemplate(template: string, values: Readonly<Record<string, string | null | undefined>>, fallback: string | null): string | null;
+declare function KpiCard({ label, value, format, locale, comparison: comparisonProp, comparisons, provisional, polarity, change, neutralBand, showPrevious, summary, target, targetLabel, targetDisplay, period, history, historyGrain, showHistory, source, updatedAt, updatedAtDisplay, timeZone, now, isLoading, size, className, ...props }: KpiCardProps): React.JSX.Element;
+
+declare const deltaVariants: (props?: ({
+    variant?: "inline" | "badge" | null | undefined;
+    sentiment?: "negative" | "neutral" | "positive" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface DeltaProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children">, Pick<VariantProps<typeof deltaVariants>, "variant"> {
+    /** The current value. The previous one comes from `comparison`. */
+    value: number | null | undefined;
+    /** What the value is compared against. Required so the delta always carries its label. */
+    comparison: Comparison;
+    /** Whether a rise is good. Default `"higher-is-better"`. */
+    polarity?: Polarity;
+    /** Absolute ratio below which the change reads as flat (0.01 = 1%). Default 0.01. */
+    neutralBand?: number;
+    /** Format of the metric itself; a `percent` metric shows its change in points. */
+    format?: ValueFormat;
+    /**
+     * `"relative"` ("+12.4%"), `"points"` ("-0.5pt") or `"difference"` (the absolute difference in the
+     * metric's own `format`, "+¥530万"). Default: points for a `percent` format, else relative.
+     */
+    change?: ChangeDisplay;
+    /**
+     * 変化（`"relative"` の率・`"points"` の pt）の小数桁数。固定で、末尾の 0 も出す。例: `digits={2}` → "+0.14pt"。
+     * 同じカード群で桁がばらつかないよう、全部に同じ値を渡す。未指定は 1 桁（"+14.0%"）。`"points"` は未指定のとき `format.digits` に従う。
+     */
+    digits?: number;
+    /** Locale for the change. Default `"ja-JP"`. */
+    locale?: string;
+    /** Show the comparison label ("前月比") after the change. Default true. */
+    showLabel?: boolean;
+}
+/** Text shown when the values cannot be compared (no previous value, or a zero baseline): the same "—" as every missing value. */
+declare const DELTA_NOT_COMPARABLE = "\u2014";
+declare const Delta: React.ForwardRefExoticComponent<DeltaProps & React.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * @deprecated 新規は Delta を使う。value/direction を別々に受けるため食い違える（C4）。
+ */
 interface TrendIndicatorProps {
     value: number;
     direction: TrendDirection;
     positiveIsGood?: boolean;
     className?: string;
 }
+/**
+ * Arrow plus percentage change.
+ *
+ * @deprecated 新規は Delta を使う。value/direction を別々に受けるため食い違える（C4）。
+ */
 declare const TrendIndicator: React.ForwardRefExoticComponent<TrendIndicatorProps & React.RefAttributes<HTMLSpanElement>>;
 
 interface StatusBadgeProps {
     status: string;
     label?: string;
+    /** status → tone (`positive` | `negative` | `warning` | `info` | `neutral`) or legacy colour name. */
     colorMap?: Partial<Record<string, string>>;
     className?: string;
 }
 declare const StatusBadge: React.ForwardRefExoticComponent<StatusBadgeProps & React.RefAttributes<HTMLSpanElement>>;
 
+declare function formatRelativeTime(date: Date | string | number, options?: {
+    now?: Date | number;
+    locale?: string;
+}): string;
+
 interface PlaceholderProps extends HTMLAttributes<HTMLSpanElement> {
 }
 declare const Placeholder: React.ForwardRefExoticComponent<PlaceholderProps & React.RefAttributes<HTMLSpanElement>>;
 
-export { AppShell, type AppShellHeaderProps, type AppShellProps, type AppShellSidebarProps, DashboardCard, DashboardCardAction, type DashboardCardActionProps, DashboardCardContent, type DashboardCardContentProps, DashboardCardDescription, type DashboardCardDescriptionProps, DashboardCardFooter, type DashboardCardFooterProps, DashboardCardHeader, type DashboardCardHeaderProps, DashboardCardPreset, type DashboardCardPresetProps, type DashboardCardProps, DashboardCardSkeleton, type DashboardCardSkeletonProps, DashboardCardTitle, type DashboardCardTitleProps, DataTable, DataTableColumnVisibility, type DataTableColumnVisibilityProps, DataTableContent, type DataTableContentProps, DataTablePagination, type DataTablePaginationProps, DataTablePreset, type DataTablePresetProps, type DataTableProps, DataTableToolbar, type DataTableToolbarProps, type DateRange, DateRangePicker, type DateRangePickerProps, EChart, type EChartProps, FilterBar, FilterBarActiveChips, type FilterBarActiveChipsProps, FilterBarClearButton, type FilterBarClearButtonProps, FilterBarMultiSelect, type FilterBarMultiSelectProps, FilterBarPreset, type FilterBarPresetProps, type FilterBarProps, FilterBarSelect, type FilterBarSelectProps, type FilterConfig, type FilterOption, type FilterType, type FilterValues, type FunnelStep, FunnelSteps, type FunnelStepsProps, type MetricItem, MetricUnit, type MetricUnitProps, MetricValue, type MetricValueProps, type MetricVariant, MultiSelect, type MultiSelectProps, type NavGroup, type NavItem, PageShell, PageShellActions, type PageShellActionsProps, PageShellContent, type PageShellContentProps, PageShellDescription, type PageShellDescriptionProps, PageShellHeader, PageShellHeaderEnd, type PageShellHeaderEndProps, type PageShellHeaderProps, PageShellHeading, type PageShellHeadingProps, PageShellMeta, type PageShellMetaProps, type PageShellProps, PageShellSummary, PageShellSummaryCard, type PageShellSummaryCardProps, type PageShellSummaryProps, PageShellTitle, type PageShellTitleProps, Placeholder, type PlaceholderProps, type PresetItem, SearchableSelect, type SearchableSelectProps, SectionHeader, type SectionHeaderProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SelectOption, type SelectOptionGroup, type SelectOptions, Sparkline, type SparklineDataPoint, type SparklineProps, type SparklineVariant, StatusBadge, type StatusBadgeProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, defaultPresets, flattenOptions, funnelStepsVariants, isGroupedOptions, metricValueVariants, pageShellSummaryCardVariants, useDataTable };
+declare const DEFAULT_SAMPLE_LABEL = "\u898B\u672C\u306E\u5024";
+interface SampleState {
+    label: string;
+}
+/**
+ * The mark a card inside `SampleData` should show, or null. A card that shows it wraps its
+ * content in `<SampleClaim>` so the parts inside do not show it again.
+ */
+declare function useSampleMark(): SampleState | null;
+/** Ends the `SampleData` scope for the parts inside a card that already shows the mark. */
+declare function SampleClaim({ children }: {
+    children?: ReactNode;
+}): React.JSX.Element;
+interface SampleBadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    /** 印の文言。既定「見本の値」。 */
+    label?: string;
+}
+declare function SampleBadge({ label, className, ...props }: SampleBadgeProps): React.JSX.Element;
+interface SampleDataProps {
+    /** 印の文言。既定「見本の値」。 */
+    label?: string;
+    children?: ReactNode;
+}
+declare function SampleData({ label, children }: SampleDataProps): React.JSX.Element;
+
+export { AppShell, type AppShellHeaderProps, type AppShellProps, type AppShellSidebarProps, AreaChart, type AreaChartProps, BarChart, type BarChartProps, BarList, type BarListItem, type BarListOptions, type BarListProps, type BarListSortOrder, COMPARISON_LABELS, CategoryBar, type CategoryBarMarker, type CategoryBarProps, type ChangeDisplay, type ChartActionsOptions, type ChartAnnotation, type ChartColor, type ChartColorToken, type ChartColors, type ChartCommonProps, type ChartComparison, type ChartEmptyState, type ChartEventPayload, type ChartForecast, type ChartForecastRow, ChartFrame, type ChartFrameProps, type ChartHighlight, type ChartRootAttributes, type ChartSeriesColor, type ChartSkeletonVariant, type ChartThreshold, type ChartTone, type Comparison, type ComparisonKind, type ComparisonOptions, type ComparisonResult, DEFAULT_LOCALE, DEFAULT_SAMPLE_LABEL, DELTA_NOT_COMPARABLE, DashboardCard, DashboardCardAction, type DashboardCardActionProps, DashboardCardContent, type DashboardCardContentProps, DashboardCardDescription, type DashboardCardDescriptionProps, DashboardCardFooter, type DashboardCardFooterProps, DashboardCardHeader, type DashboardCardHeaderProps, DashboardCardPreset, type DashboardCardPresetProps, type DashboardCardProps, DashboardCardSkeleton, type DashboardCardSkeletonProps, DashboardCardTitle, type DashboardCardTitleProps, DataTable, DataTableColumnVisibility, type DataTableColumnVisibilityProps, DataTableContent, type DataTableContentProps, DataTableExport, type DataTableExportProps, DataTablePagination, type DataTablePaginationProps, DataTablePreset, type DataTablePresetProps, type DataTableProps, DataTableToolbar, type DataTableToolbarProps, type DateRange, DateRangePicker, type DateRangePickerProps, type DateStyle, Delta, type DeltaDirection, type DeltaProps, type DeltaSentiment, DonutChart, type DonutChartOptions, type DonutChartProps, type DonutVariant, EChart, type EChartProps, EMPTY_VALUE, FilterBar, FilterBarActiveChips, type FilterBarActiveChipsProps, FilterBarClearButton, type FilterBarClearButtonProps, FilterBarMultiSelect, type FilterBarMultiSelectProps, FilterBarPreset, type FilterBarPresetProps, type FilterBarProps, FilterBarSelect, type FilterBarSelectProps, type FilterConfig, type FilterOption, type FilterType, type FilterValues, type FormatDateOptions, type FormatKind, type FormatValueOptions, type FunnelStep, FunnelSteps, type FunnelStepsProps, Heatmap, type HeatmapProps, type HistoryGrain, KpiCard, type KpiCardProps, type KpiCardSource, type KpiPeriod, Legend, type LegendProps, LineChart, type LineChartProps, MINUS_SIGN, type MetricItem, MetricUnit, type MetricUnitProps, MetricValue, type MetricValueProps, type MetricVariant, MultiSelect, type MultiSelectProps, type NavGroup, type NavItem, type NumericKeys, PageShell, PageShellActions, type PageShellActionsProps, PageShellContent, type PageShellContentProps, PageShellDescription, type PageShellDescriptionProps, PageShellHeader, PageShellHeaderEnd, type PageShellHeaderEndProps, type PageShellHeaderProps, PageShellHeading, type PageShellHeadingProps, PageShellMeta, type PageShellMetaProps, type PageShellProps, PageShellSummary, PageShellSummaryCard, type PageShellSummaryCardProps, type PageShellSummaryProps, PageShellTitle, type PageShellTitleProps, type PeriodGrain, Placeholder, type PlaceholderProps, type Polarity, type PresetItem, ProgressCircle, type ProgressCircleProps, RECORD_MIN_POINTS, type RecordInsight, SampleBadge, type SampleBadgeProps, SampleClaim, SampleData, type SampleDataProps, ScatterChart, type ScatterChartProps, type ScatterReferenceLine, SearchableSelect, type SearchableSelectProps, SectionHeader, type SectionHeaderProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SelectOption, type SelectOptionGroup, type SelectOptions, Sparkline, type SparklineDataPoint, type SparklineProps, type SparklineVariant, StatusBadge, type StatusBadgeProps, type TargetProgress, Tracker, type TrackerBlock, type TrackerProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, UpdatedAt, type UpdatedAtProps, type ValueFormat, type ValueFormatter, WaterfallChart, type WaterfallChartProps, type WaterfallMode, comparisonBaseline, comparisonLabel, computeComparison, computeTargetProgress, defaultChangeDisplay, defaultPresets, deltaVariants, detectRecord, fillKpiTemplate, flattenOptions, formatChange, formatChangeAmount, formatDate, formatDateRange, formatDatesInText, formatDelta, formatKind, formatPoints, formatRelativeTime, formatValue, funnelStepsVariants, inferPeriodGrain, isGroupedOptions, metricValueVariants, pageShellSummaryCardVariants, tableToCsv, toCsv, toValueFormatter, toneForValue, useDataTable, useResolvedChartColors, useSampleMark };