@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.1197de7

package/dist/components/index.d.ts

@@ -1,18 +1,66 @@
 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 { V as ValueFormat, a as DateStyle } from '../format-D34piCei.js';
+export { D as DEFAULT_LOCALE, E as EMPTY_VALUE, F as FormatDateOptions, b as FormatKind, c as FormatValueOptions, M as MINUS_SIGN, f as formatDate, d as formatDateRange, e as formatDatesInText, g as formatDelta, h as formatKind, i as formatPoints, j as formatValue, t as toValueFormatter } from '../format-D34piCei.js';
+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 PageShellProps extends HTMLAttributes<HTMLDivElement> {
+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 Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The page heading. When given, the header (title and `description`) and the content area are drawn for you; `children` go in the content area. */
+    title?: string;
+    /** One line under the title. Used only with `title`. */
+    description?: string;
 }
 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 "Source: ○○" (ja: "出典：○○") 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
+ * 20rem basis next to `PageShellHeaderEnd`, the end block drops below it. A
+ * `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> {
 }
@@ -35,13 +83,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> {
 }
@@ -73,6 +116,8 @@ interface FilterConfig {
     options?: FilterOption[];
     /** Placeholder text */
     placeholder?: string;
+    /** `select` のみ。渡すと先頭に「絞り込まない」項目をこの文言で足す（例: `"すべて"`）。 */
+    allLabel?: string;
     /** Default value */
     defaultValue?: string | string[];
 }
@@ -155,6 +200,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";
@@ -182,8 +408,8 @@ 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 h3: "text-xl font-semibold";
+    readonly h2: "text-base font-semibold tracking-tight";
+    readonly h3: "text-base font-semibold";
     readonly h4: "text-lg font-semibold";
 };
 interface SectionHeaderProps {
@@ -196,6 +422,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> {
@@ -220,7 +450,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;
@@ -229,7 +459,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 {
     /**
@@ -240,7 +470,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"] },
@@ -271,19 +501,899 @@ 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 come from the grain of the period, in the locale's language (`<html lang>` unless a
+ * `locale` is passed): a monthly KPI compares "vs. prior month" / "vs. same month last year"
+ * (ja: "前月比" / "前年同月比"), a quarterly one "前四半期比" / "前年同期比" in ja. Without a
+ * grain the label is the generic "vs. prior period" (ja: "前期比").
+ *
+ * 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, in English (the fallback language). A `custom` comparison always brings
+ * its own `label`. The parts pick the language from `<html lang>` (`comparisonLabel`): ja reads "前期比" / "前年同期比" / "目標比".
+ */
+declare const COMPARISON_LABELS: Record<Exclude<ComparisonKind, "custom">, string>;
+/**
+ * What the previous value is called: "prior month" / "same month last year" / "target" (ja: "前月" / "前年同月" / "目標");
+ * with a `label`, that label minus its comparison word ("昨日比" → "昨日", "vs. yesterday" → "yesterday").
+ * `toDate` (a running total such as YTD) turns a `prior-year` baseline into "same period last year" (ja: "前年同期") whatever the grain.
+ * `locale` picks the language; default the page's (`<html lang>`).
+ */
+declare function comparisonBaseline(vs: ComparisonKind, grain?: PeriodGrain, label?: string, toDate?: boolean, locale?: string): string;
+/**
+ * The comparison label: "vs. prior month" (ja: "前月比") for `("prior-period", "month")`, "vs. prior period" (ja: "前期比")
+ * without a grain; a given `label` as is. A running total (`toDate`) against the prior year is "vs. same period last year"
+ * (ja: "前年同期比"), not "vs. prior year" (ja: "前年比"). `locale` picks the language; default the page's (`<html lang>`).
+ */
+declare function comparisonLabel(vs: ComparisonKind, grain?: PeriodGrain, label?: string, toDate?: boolean, locale?: string): 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;
+    /** Locale of the derived `label`. Default the page's (`<html lang>`). */
+    locale?: string;
+}
+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;
+    /** プロットの下に常に出す小さな注記(近似値である旨など)。読み込み中・空のときも出す。 */
+    footnote?: string;
+    /** プロット(チャート本体)。読み込み中・空のときは描かない。 */
+    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;
@@ -292,17 +1402,704 @@ 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;
+}
+/** 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$2<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$2<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$2<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;
+};
+
+/**
+ * PairedChart — 量(棒)と率・単価(線)を、同じ期間軸の上下 2 段で見せる型付きグラフ（`DashboardCardPreset` の中に置く）。
+ * 二重 Y 軸は持たない: 上段が棒の値軸、下段が線の値軸で、横軸(期間)とツールチップの位置は
+ * 1 つの ECharts の中で揃っている(ホバーすると同じ期間の棒と線の値が 1 枚のツールチップに出る)。
+ * 段ごとに `format`(件数・金額・%)を持ち、率を分子・分母から計算することはしない(呼び元が値を渡す)。
+ * 棒は 0 起点。色は `--chart-1..5` を固定順(棒 → 線の順に続く)で使い、ライト/ダークに追従する。
+ * `ChartFrame` の中に描く(見出し・要約・読み込み中・空表示)。
+ */
+
+/** 1 段ぶんの設定。 */
+interface PairedPanel<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** この段に描く系列の列。 */
+    categories: NumericKeys<T>[];
+    /** 系列の色。省略時は `--chart-1..5` を固定順(上段の続きから下段)。 */
+    colors?: ChartColors<T>;
+    /** 値の書式(件数 `number`・金額 `currency`・率 `percent` など)。`percent` は比率(0.124 → 12.4%)を渡す。 */
+    format?: ValueFormat;
+    /** `format` で足りないときの自前の書式。 */
+    valueFormatter?: ValueFormatter;
+    /** 値軸の見出し(「売上」「客単価」など)。 */
+    yAxisLabel?: string;
+    /** 値軸の上限。データが超えるときは軸を広げる。 */
+    maxValue?: number;
+}
+interface PairedChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends Pick<ChartCommonProps<T>, "data" | "index" | "labels" | "title" | "summary" | "isLoading" | "emptyState" | "chartOptions" | "actions" | "fileName" | "className" | "ariaLabel"> {
+    /** 上段。量を棒で。`type` は BarChart と同じ(`stacked` で積み上げ)。 */
+    bars: PairedPanel<T> & {
+        type?: CartesianStackType;
+    };
+    /** 下段。率・単価を線で。`fitToData` で値軸をデータに合わせる(率が狭い幅で動くとき)。 */
+    line: PairedPanel<T> & {
+        fitToData?: boolean;
+        minValue?: number;
+    };
+    /** 全体の高さ(px)。既定 400。 */
+    height?: number;
+    /** 上段:下段の高さの比。既定 `[3, 2]`。 */
+    heightRatio?: [number, number];
+    /** 値軸ラベルの幅(px)。2 段の左端を揃える。既定 64。 */
+    yAxisWidth?: number;
+    showLegend?: boolean;
+    showTooltip?: boolean;
+}
+/** Generic over the row type, so `index` / `categories` / `colors` keys are checked against `data`. */
+declare const PairedChart: (<T extends Record<string, unknown>>(props: PairedChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+interface HistogramThreshold {
+    /** 線を引く値(例 SLA の 3 日)。 */
+    value: number;
+    /** 線の名前(例「SLA」)。ツールチップ・要約・データ表の注記に出る。 */
+    label?: string;
+}
+interface HistogramChartProps extends Omit<ChartCommonProps, "data" | "index" | "categories" | "colors" | "labels" | "summary"> {
+    /** 生の値の配列。number か数値文字列。null・数にならない値は数えない。 */
+    values: unknown[];
+    /** 階級の幅。省略すると値の範囲から区切りのよい幅(1・2・2.5・5 × 10^n)を選ぶ。 */
+    binWidth?: number;
+    /** 階級の始まり。省略は幅の倍数に切り下げた最小値。 */
+    start?: number;
+    /** 上限。この値以上は 1 つの「<上限>以上」階級にまとめる。省略するとまとめない。 */
+    max?: number;
+    /** しきい値の線(任意)。階級の途中にも引ける。 */
+    threshold?: HistogramThreshold;
+    /** 件数の単位。既定は日本語のページで「件」、それ以外は単位なし。 */
+    countUnit?: string;
+    /** 横軸の値の名前(データ表の先頭列)。既定「値」。例「解決日数」 */
+    valueLabel?: string;
+    /** 1 文要約(自由文)。`"auto"` なら件数・最頻の階級・しきい値超えの割合を組む。省略時は要約なし。 */
+    summary?: string | "auto";
+    /** ホバー時のツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+}
+declare const HistogramChart: React.ForwardRefExoticComponent<HistogramChartProps & React.RefAttributes<HTMLDivElement>>;
+
+interface BoxPlotGroup {
+    /** 箱の名前(横軸)。 */
+    name: string;
+    /** 生の値の配列。number か数値文字列。null・数にならない値は数えない。 */
+    values: unknown[];
+}
+interface BoxPlotChartProps extends Omit<ChartCommonProps, "data" | "index" | "categories" | "colors" | "labels" | "summary"> {
+    /** 群ごとの値。並びがそのまま左から右の順。 */
+    groups: BoxPlotGroup[];
+    /** ひげの長さ(四分位範囲の何倍までを外れ値にしないか)。既定 1.5。 */
+    whisker?: number;
+    /** 値(縦軸)の名前。ツールチップとデータ表に出る。既定「値」。例「残業時間」 */
+    valueLabel?: string;
+    /** 1 文要約(自由文)。`"auto"` なら中央値が最大・最小の群と外れ値の数を組む。省略時は要約なし。 */
+    summary?: string | "auto";
+    /** ホバー時のツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+}
+declare const BoxPlotChart: React.ForwardRefExoticComponent<BoxPlotChartProps & React.RefAttributes<HTMLDivElement>>;
+
+type AttentionKind = "overdue" | "risk" | "dueSoon" | "stale";
+type DateInput = Date | string | null | undefined;
+interface AttentionJudgement {
+    kind: AttentionKind;
+    /**
+     * overdue: 期日を過ぎた日数（1 以上）／ dueSoon: 期日までの日数（0 = 当日）／
+     * stale: 最終の動きからの日数／ risk: 0。
+     */
+    days: number;
+}
+interface AttentionListProps<T> {
+    rows: T[];
+    /** 基準日（`"2026-10-23"` か Date）。 */
+    asOf: Date | string;
+    /** 期日の何日前から「期限間近」にするか。既定 7。 */
+    dueSoonDays?: number;
+    /** この日数動きがなければ「滞留」。未指定なら滞留は判定しない。 */
+    staleDays?: number;
+    /** 区分名の差し替え（例: `{ overdue: "入金遅れ" }`）。 */
+    labels?: Partial<Record<AttentionKind, string>>;
+    /** 行の ID。省略時は `idKey` の列、それも無ければ行の順番。 */
+    getRowId?: (row: T) => string;
+    /** 行の見出し（顧客名・案件名など）。省略時は `titleKey` の列、それも無ければ空。 */
+    getTitle?: (row: T) => ReactNode;
+    getDueDate?: (row: T) => DateInput;
+    getLastActivityAt?: (row: T) => DateInput;
+    /** リスクと判定する行。期日・滞留より先に出す。 */
+    isRisk?: (row: T) => boolean;
+    /** 行の ID の列名（JSON で書ける `getRowId`）。 */
+    idKey?: string;
+    /** 見出しの列名（JSON で書ける `getTitle`）。 */
+    titleKey?: string;
+    /** 期日の列名（JSON で書ける `getDueDate`）。値は `"2026-10-23"` 形式の日付か Date。 */
+    dueDateKey?: string;
+    /** 最後に動きがあった日の列名（JSON で書ける `getLastActivityAt`）。 */
+    lastActivityAtKey?: string;
+    /** リスクの列名（JSON で書ける `isRisk`）。値が真の行をリストにする。 */
+    riskKey?: string;
+    /** 次の一手の列名（JSON で書ける `getNextAction`）。値が空の行には添えない。 */
+    nextActionKey?: string;
+    /** 理由の文。省略すると区分と日数から作る。 */
+    getReason?: (row: T, judgement: AttentionJudgement) => ReactNode;
+    /** 次の一手。判定に当たる行に添える。 */
+    getNextAction?: (row: T, judgement: AttentionJudgement) => ReactNode;
+    /** 見出しの右に出す補足（金額・担当者など）。 */
+    getMeta?: (row: T) => ReactNode;
+    /** 行を押したとき。渡すと行が button になる。 */
+    onRowClick?: (row: T) => void;
+    /** 判定に当たらない行も末尾に出す。既定 false。 */
+    includeUnflagged?: boolean;
+    /** 該当なしのときの見出し・説明。 */
+    emptyTitle?: string;
+    emptyDescription?: string;
+    className?: string;
+}
+declare function AttentionList<T>({ rows, asOf, dueSoonDays, staleDays, labels, getRowId, getTitle, getDueDate, getLastActivityAt, isRisk, idKey, titleKey, dueDateKey, lastActivityAtKey, riskKey, nextActionKey, getReason, getNextAction, getMeta, onRowClick, includeUnflagged, emptyTitle, emptyDescription, className, ...rest }: AttentionListProps<T> & Omit<HTMLAttributes<HTMLUListElement>, keyof AttentionListProps<T>>): React.JSX.Element;
+declare namespace AttentionList {
+    var displayName: string;
+}
+
+/**
+ * ComboChart — bars, lines and areas on one category / time axis, with up to two value axes (left and right); use it only to migrate a Tableau dual-axis sheet, and use `PairedChart` for a new dashboard.
+ *
+ * It exists to reproduce a Tableau dual-axis sheet faithfully (a Pareto: sales as bars, the cumulative share as a
+ * line on the right). For a new dashboard prefer PairedChart, which stacks the two measures in panels over a
+ * shared axis instead of reading two scales off one plot.
+ *
+ * Each value axis starts at 0 (bars always do; a negative value extends the axis below it), carries its own format
+ * (`format` left, `rightFormat` right), and never repeats a tick label: the tick step widens until every label on
+ * the axis reads differently. Only the left axis draws grid lines. `referenceLines` draw dashed lines on either axis.
+ * Clicking a bar or a point calls `onSelect` with its row.
+ */
+
+type ComboSeriesType = "bar" | "line" | "area";
+type ComboAxis = "left" | "right";
+/** One measure of a ComboChart. */
+interface ComboSeries<K extends string = string> {
+    /** 値の列名。 */
+    key: K;
+    /** 描き方。`"bar"`(棒)・`"line"`(線)・`"area"`(面)。 */
+    type: ComboSeriesType;
+    /** どちらの値の軸で読むか。既定 `"left"`。`"right"` の系列が 1 つでもあると右軸を出す。 */
+    axis?: ComboAxis;
+    /** 凡例・ツールチップの表示名。省略時は `labels[key]`、無ければ列名。 */
+    label?: string;
+    /** 色。`"chart-1"`〜`"chart-5"` か意味色。省略時は系列の順にトークン色。 */
+    color?: ChartSeriesColor;
+}
+/** A dashed horizontal (vertical with `layout="vertical"`) line at a value of one axis. */
+interface ComboReferenceLine {
+    /** 線を引く値。 */
+    value: number;
+    /** どちらの軸の値か。既定 `"left"`。 */
+    axis?: ComboAxis;
+    /** 線のラベル。省略時は軸の書式で値を書く。 */
+    label?: string;
+}
+interface ComboChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = カテゴリ軸の 1 つの値(集計済み)。 */
+    data: T[];
+    /** カテゴリ軸(横軸)の列名。例 `"month"`・`"product"`。行の順に並ぶ。 */
+    index: keyof T & string;
+    /** 描く系列。`{ key, type: "bar" | "line" | "area", axis?: "left" | "right", label? }` の配列。描く順(後ろほど手前)。 */
+    series: ComboSeries<keyof T & string>[];
+    /** 左軸(と左軸の系列のツールチップ・データ表)の書式。既定 `"compact"` 相当の短い表記。 */
+    format?: ValueFormat;
+    /** 右軸の書式。例 パレート図の累積比なら `"percent"`。省略時は `format`。 */
+    rightFormat?: ValueFormat;
+    /** 列名・カテゴリの値 → 表示名。 */
+    labels?: Record<string, string>;
+    /** 参照線(目標・平均など)。`{ value, axis?, label? }` の配列。 */
+    referenceLines?: ComboReferenceLine[];
+    /** 同じ軸の棒どうし・面どうしを積み上げる。既定 `false`(棒は横に並べる)。 */
+    stacked?: boolean;
+    /** `"vertical"` でカテゴリを縦軸に並べる(横棒)。左軸は下、右軸は上になる。既定 `"horizontal"`。 */
+    layout?: "horizontal" | "vertical";
+    /** 凡例を出す。既定 `true`(系列が 2 つ以上のとき)。 */
+    showLegend?: boolean;
+    /** ホバーでツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /** 棒・点のクリック。その行を受け取る(フィルターの操作に使う)。 */
+    onSelect?: (row: T) => void;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。 */
+    summary?: string;
+    /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ(px)。既定 288。 */
+    height?: number;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /** グラフ右上に PNG 保存/コピーのボタンを出す。 */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。 */
+    fileName?: string;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。 */
+    ariaLabel?: string;
 }
-declare const FunnelSteps: React.ForwardRefExoticComponent<Omit<FunnelStepsProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** Generic over the row type, so `index` and the series keys are checked against `data`. */
+declare const ComboChart: (<T extends Record<string, unknown>>(props: ComboChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * 等間隔の 1 系列に対する指数平滑法(ETS、誤差は加法)の予測。依存なしの純関数で、同じ入力には同じ出力を返す(乱数を使わない)。
+ *
+ * - モデルは トレンド(なし / 加法)× 季節(なし / 加法 / 乗法)。乗法トレンドは扱わず、加法トレンドとして当てはめる
+ *   (`model.trend` には実際に当てはめた `"additive"` が入る)。乗法トレンドの予測区間は閉じた式が無く、決定的に出せないため。
+ * - 平滑化係数(α・β・γ)と初期の水準・傾きは、1 期先予測の残差平方和の最小化(誤差が加法なので最尤と同じ)を
+ *   Nelder–Mead で解く。範囲は 0 < α < 1、0 < β < α、0 < γ < 1 − α。初期の季節成分は古典的分解(最初の数季節の移動平均)で決める。
+ * - `"auto"` は当てはめられる組み合わせをすべて当て、AICc が最小のものを選ぶ(Tableau も最大 8 モデルから AIC で選ぶ)。
+ * - 予測区間は ETS(A,·,·) の分散の式(Hyndman ほか 2008 / fpp の表)で、点予測 ± z·σ·√(分散の倍率)。σ は残差から。
+ *   乗法の季節は閉じた式が無いので、2 期先以降の項に季節指数の 2 乗を掛ける近似にしている。
+ * - Tableau はパラメータの推定方法を公開していないため、同じモデルを選んでも値は一致しない(近似値として扱う)。
+ */
+/** トレンド・季節の指定。`"auto"` は当てはめられる候補から AICc で選ぶ。 */
+type ForecastComponent = "none" | "additive" | "multiplicative" | "auto";
+interface ForecastOptions {
+    /** トレンド。既定 `"auto"`。`"multiplicative"` は加法トレンドとして当てはめる。 */
+    trend?: ForecastComponent;
+    /** 季節。既定 `"auto"`。`seasonLength` が 1 以下か、点が 2 季節分に満たないときは季節なしに落とす。 */
+    season?: ForecastComponent;
+    /** 1 季節の期数(月次 12・四半期 4・曜日 7)。省略か 1 で季節なし。 */
+    seasonLength?: number;
+    /**
+     * 予測する期数。既定は季節ありなら 1 季節分(`seasonLength`)、なければ当てはめた点の 4 分の 1(1〜12 期)。
+     * 末尾の除外期(`ignoreLast` と末尾の欠損)はこれとは別に予測する。
+     */
+    horizon?: number;
+    /** 予測区間の信頼水準(0〜1)。既定 0.95。 */
+    confidence?: number;
+    /** 末尾から除外する期数(締まっていない期)。当てはめに使わず、予測する側に回す。既定 0。 */
+    ignoreLast?: number;
+}
+
+/**
+ * ForecastChart — a time-series line chart that continues each series with an exponential-smoothing forecast (dashed line and shaded prediction interval) computed from `data` at render time; place it inside `DashboardCardPreset`, and use it to migrate a Tableau forecast sheet.
+ *
+ * Pass the rows, the date column (`x`), the value column (`y`) and optionally a column that splits the rows into
+ * series (`series`, e.g. a segment). Rows that fall in the same period and series are summed. The forecast is
+ * recomputed on every change of the inputs (never stored or fetched) with the model family in `forecast`
+ * (trend / season, `"auto"` picks the lowest AICc), so it is an approximation: a fixed note under the plot always
+ * says so (name the source tool with `forecastSource`; `forecastNote` only adds to it). A series with too few points draws its actuals only.
+ */
+
+/** 予測の 1 期の長さ。未来の日付を進める単位。 */
+type ForecastPeriod = "day" | "week" | "month" | "quarter" | "year";
+interface ForecastChartProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors"> {
+    /** 日付の列名。ISO の日付・年月(`"2026-01"`)・年・`Date` を受ける。 */
+    x: keyof T & string;
+    /** 値の列名。number か数値文字列。 */
+    y: keyof T & string;
+    /** 系列に分ける列名(セグメントなど)。省略時は 1 系列。6 つ以上は合計の大きい 5 つ +「その他」にまとめる。 */
+    series?: keyof T & string;
+    /** 1 期の長さ。省略時は日付の間隔から推定する。同じ期に入る行は合計する。 */
+    period?: ForecastPeriod;
+    /**
+     * 予測の設定(トレンド・季節・季節の長さ・期数・信頼水準・末尾の除外期)。`seasonLength` を省略すると `period` から
+     * 決める(月 12・四半期 4・週 52・日 7・年は季節なし)。例: `forecast={{ trend: "additive", season: "additive", horizon: 12 }}`
+     */
+    forecast?: ForecastOptions;
+    /** 凡例・ツールチップ・境目の縦線に出す予測の呼び名。既定は表示言語の「予測」/ "Forecast"。 */
+    forecastLabel?: string;
+    /**
+     * 予測の元になったツール（`"Tableau"` など）。プロットの下の注記に「〈ツール〉の予測値とは一致しない」と名前で出す。
+     * 注記そのもの（近似であること）は部品が必ず出し、置き換えられない。
+     */
+    forecastSource?: string;
+    /** 注記のあとに足す補足（集計の範囲など）。近似の注記を置き換えるものではない。 */
+    forecastNote?: string;
+    /** 系列色。配列は系列の順、record は系列名ごと。省略時はトークン順。 */
+    colors?: ChartColors;
+    /** 凡例・ツールチップを出す。既定 `true`。 */
+    showLegend?: boolean;
+    showTooltip?: boolean;
+    /** 値軸の目盛り線を出す。既定 `true`。 */
+    showGridLines?: boolean;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    /** y 軸ラベルの幅(px)。 */
+    yAxisWidth?: number;
+    /** 値軸の下限・上限(データ・予測区間がはみ出すときは軸を広げる)。 */
+    minValue?: number;
+    maxValue?: number;
+    /** 値軸を 0 からではなくデータに合わせる。既定 `false`。 */
+    fitToData?: boolean;
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+}
+/** Generic over the row type, so `x` / `y` / `series` are checked against `data`. */
+declare const ForecastChart: (<T extends Record<string, unknown>>(props: ForecastChartProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/** The maps the parts draw. */
+type GeoMapName = "japan" | "us" | "world";
+
+/**
+ * FilledMap — a choropleth: each region (Japanese prefecture, US state or country) shaded by a number. Pass rows,
+ * the column naming the region and the number to shade by instead of an ECharts option.
+ *
+ * Regions are matched by name or code, in Japanese or English: 「東京都」「東京」「Tokyo」「JP-13」「13」,
+ * 「California」「CA」「US-CA」, 「Japan」「JPN」「JP」 (case, width and accents don't matter: "Ōita" = "Oita").
+ * `map="auto"` (default) picks the map whose regions the most rows name. A row that names no region is not drawn;
+ * it is listed in the screen-reader table instead.
+ *
+ * Shading is a single-colour ramp of one theme colour (`tone`, `--chart-1` by default) like Heatmap: the lowest
+ * value is the tone mixed 20% into the surface, the highest the tone itself, never a rainbow. A region with no row
+ * (or a null value) is grey. `selected` dims the other regions; clicking a region calls `onSelect` (a filter action).
+ * The boundaries (Natural Earth, public domain) load on demand, so the part shows its skeleton for a moment the first time.
+ */
+
+/** Columns of `T` that hold numbers (null / undefined allowed for gaps); untyped rows keep every key. */
+type NumericColumn$1<T> = {
+    [K in keyof T]-?: unknown extends T[K] ? K : T[K] extends number | bigint | null | undefined ? K : never;
+}[keyof T] & string;
+type FilledMapName = GeoMapName | "auto";
+interface FilledMapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = 1 地域。同じ地域が複数あれば後の行が勝つ。値は number か数値文字列。 */
+    data: T[];
+    /** 地域を表す列名。都道府県名(「東京都」「東京」「Tokyo」)・州名・国名か、コード(`JP-13`・`13`・`CA`・`US-CA`・`JPN`・`JP`)。 */
+    region: keyof T & string;
+    /** 塗りの濃さを決める数値の列名。null・欠損の地域は灰色(0 とは別)。 */
+    value: NumericColumn$1<T>;
+    /** 描く地図。`"japan"`(都道府県)・`"us"`(州)・`"world"`(国)。既定 `"auto"`(地域の列の値が最も多く当たる地図)。 */
+    map?: FilledMapName;
+    /** 列名・地域の値 → 表示名(ツールチップ・データ表)。例 `{ sales: "売上" }`。 */
+    labels?: Record<string, string>;
+    /** 数値の書式(`"number"` / `"currency"` / `"percent"` / `{ type: "number", unit: "件" }` など)。既定 `"number"`。 */
+    format?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道。`format` より優先する。 */
+    valueFormatter?: ValueFormatter;
+    /** 濃淡の色。`"chart-1"`〜`"chart-5"` か意味色。薄い → 濃いの単色(レインボーにしない)。既定 `"chart-1"`。 */
+    tone?: ChartSeriesColor;
+    /** 濃さの固定スケール。省略時はデータの最小〜最大。範囲外の値は端に丸める。 */
+    scale?: {
+        min?: number;
+        max?: number;
+    };
+    /** 凡例(薄い → 濃いの帯と両端の値)を出す。既定 `true`。 */
+    showLegend?: boolean;
+    /** ホバーでツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /** ツールチップとデータ表に添える列(同じ行の別の値)。数値は `format`、それ以外は文字のまま。 */
+    details?: (keyof T & string)[];
+    /** 選択中の地域(`region` 列の値。名前・コードのどの書き方でもよい)。渡すと、それ以外の地域を薄くする。 */
+    selected?: string[];
+    /** 地域のクリック。`region` 列の値と、その行を受け取る(フィルターの操作に使う)。データの無い地域では呼ばない。 */
+    onSelect?: (region: string, row: T) => void;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。`"auto"` で最大の地域から自動生成。 */
+    summary?: string | "auto";
+    /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ(px)。既定 288。 */
+    height?: number;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /** グラフ右上に PNG 保存/コピーのボタンを出す。 */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。 */
+    fileName?: string;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。省略時は `<valueの列>の地図`。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so `region` / `value` keys are checked against `data`. */
+declare const FilledMap: (<T extends Record<string, unknown>>(props: FilledMapProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * SymbolMap — points at latitude / longitude over a faint boundary basemap (Japan's prefectures, US states or the
+ * countries of the world). Pass rows and the two coordinate columns instead of an ECharts option.
+ *
+ * `size` scales each symbol's area by a number; `color` colours it by a number (a single-hue ramp of `tone`, like
+ * Heatmap) or by a category (`--chart-1..5` in order of appearance, the 6th category on as「その他」/ "Other").
+ * `basemap="auto"` (default) picks the smallest map holding every point. A row without usable coordinates is not
+ * drawn; it is listed in the screen-reader table instead. `selected` dims the other points; clicking a point calls
+ * `onSelect` (a filter action). The boundaries (Natural Earth, public domain) load on demand.
+ */
+
+type SymbolMapBasemap = GeoMapName | "auto";
+interface SymbolMapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = 1 点。 */
+    data: T[];
+    /** 緯度の列名(-90〜90。数値か数値文字列)。 */
+    latitude: keyof T & string;
+    /** 経度の列名(-180〜180。数値か数値文字列)。 */
+    longitude: keyof T & string;
+    /** 点の名前の列名(ツールチップ・データ表・`selected` の照合に使う)。 */
+    name?: keyof T & string;
+    /** 点の大きさ(面積)を決める数値の列名。省略時は同じ大きさ。 */
+    size?: keyof T & string;
+    /** 点の色を決める列名。数値なら `tone` の単色の濃淡、文字ならカテゴリ色(`--chart-1..5` の出現順、6 つ目以降は「その他」)。 */
+    color?: keyof T & string;
+    /** 背景の地図。`"japan"`・`"us"`・`"world"`。既定 `"auto"`(全部の点が入る最も狭い地図)。 */
+    basemap?: SymbolMapBasemap;
+    /** 列名 → 表示名(ツールチップ・凡例・データ表)。 */
+    labels?: Record<string, string>;
+    /** 数値の書式(`color` の数値と、`sizeFormat` が無いときの `size`)。既定 `"number"`。 */
+    format?: ValueFormat;
+    /** `size` の値の書式。省略時は `format`。 */
+    sizeFormat?: ValueFormat;
+    /** 数値の `color` の濃淡の色。`"chart-1"`〜`"chart-5"` か意味色。既定 `"chart-1"`。 */
+    tone?: ChartSeriesColor;
+    /** 凡例(数値の色なら濃淡の帯、カテゴリなら色の一覧)を出す。既定 `true`。 */
+    showLegend?: boolean;
+    /** ホバーでツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /** ツールチップとデータ表に添える列。 */
+    details?: (keyof T & string)[];
+    /** 選択中の点(`name` 列の値)。渡すと、それ以外の点を薄くする。 */
+    selected?: string[];
+    /** 点のクリック。その行を受け取る(フィルターの操作に使う)。 */
+    onSelect?: (row: T) => void;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。 */
+    summary?: string;
+    /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ(px)。既定 288。 */
+    height?: number;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /** グラフ右上に PNG 保存/コピーのボタンを出す。 */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。 */
+    fileName?: string;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so the column keys are checked against `data`. */
+declare const SymbolMap: (<T extends Record<string, unknown>>(props: SymbolMapProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
+
+/**
+ * Treemap — parts of a whole as nested rectangles whose areas are the values.
+ * Pass rows, the leaf column (`index`),
+ * optionally a parent column (`group`, for two levels) and the number (`value`) instead of an ECharts option.
+ *
+ * Colour is categorical by `group` (or by `index` without one): `--chart-1..5` for the largest five, the rest the
+ * 「その他」grey. A numeric `color` column shades each tile on a single-hue ramp of `tone` instead (like Heatmap).
+ * Each tile carries its name and value when it fits. Values that are zero, negative or missing take no area; they
+ * stay in the screen-reader table. Clicking a tile calls `onSelect` with its row.
+ */
+
+/** 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 TreemapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+    /** 行の配列。1 行 = 1 タイル(集計済みの値)。 */
+    data: T[];
+    /** タイル(葉)の名前の列名。例 `"product"`。 */
+    index: keyof T & string;
+    /** 親の列名(2 階層にする)。例 `"category"`。省略時は 1 階層。 */
+    group?: keyof T & string;
+    /** タイルの面積を決める数値の列名。0 以下・欠損の行は面積を持たない(データ表には残る)。 */
+    value: NumericColumn<T>;
+    /** タイルの色を決める数値の列名(`tone` の単色の濃淡)。省略時は `group`(無ければ `index`)ごとのカテゴリ色。 */
+    color?: NumericColumn<T>;
+    /** 列名・値 → 表示名(タイル・ツールチップ・凡例・データ表)。 */
+    labels?: Record<string, string>;
+    /** `value` の書式。既定 `"number"`。 */
+    format?: ValueFormat;
+    /** `color` の値の書式。省略時は `format`。 */
+    colorFormat?: ValueFormat;
+    /** 書式を関数で直接渡す逃げ道(`value`)。`format` より優先する。 */
+    valueFormatter?: ValueFormatter;
+    /** 数値の `color` の濃淡の色。既定 `"chart-1"`。 */
+    tone?: ChartSeriesColor;
+    /** 凡例(カテゴリ色なら色の一覧、数値の色なら濃淡の帯)を出す。既定 `true`(カテゴリ色は `group` があるときだけ)。 */
+    showLegend?: boolean;
+    /** ホバーでツールチップを出す。既定 `true`。 */
+    showTooltip?: boolean;
+    /** タイルのクリック。その行を受け取る(フィルターの操作に使う)。 */
+    onSelect?: (row: T) => void;
+    /** グラフの見出し。 */
+    title?: string;
+    /** グラフが言っていることの 1 文要約。`"auto"` で最大のタイルとその構成比。 */
+    summary?: string | "auto";
+    /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** プロット領域の高さ(px)。既定 288。 */
+    height?: number;
+    /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+    chartOptions?: EChartsOption;
+    /** グラフ右上に PNG 保存/コピーのボタンを出す。 */
+    actions?: boolean | ChartActionsOptions;
+    /** PNG 保存時のファイル名(拡張子つき)。 */
+    fileName?: string;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。 */
+    ariaLabel?: string;
+}
+/** Generic over the row type, so the column keys are checked against `data`. */
+declare const Treemap: (<T extends Record<string, unknown>>(props: TreemapProps<T> & {
+    ref?: Ref<HTMLDivElement>;
+}) => ReactElement) & {
+    displayName?: string;
+};
 
 type SparklineVariant = "line" | "bar";
 interface SparklineDataPoint {
@@ -316,11 +2113,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[];
@@ -331,6 +2220,7 @@ interface DataTableContextValue<TData> {
     enablePagination: boolean;
     enableRowSelection: boolean;
     visibleColumnCount: number;
+    isLoading: boolean;
 }
 /**
  * @template TData 行データ型
@@ -345,7 +2235,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" },
@@ -366,12 +2257,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). */
@@ -384,6 +2317,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 を書き出す"`（英語は `"Export CSV"`）。 */
+    children?: ReactNode;
+    className?: string;
+}
 interface DataTablePaginationProps extends HTMLAttributes<HTMLDivElement> {
     pageSizeOptions?: number[];
 }
@@ -396,12 +2355,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;
 }
@@ -409,12 +2382,80 @@ 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 を作る。行は画面と同じ並べ替え・絞り込み後の順、列は表示中の列のみ。
+ * `"display"` の書式のロケールは `locale`（既定はページのロケール、`<html lang>`）。
+ *
+ * @example
+ * const csv = tableToCsv(table, { values: "raw", scope: "page" })
+ */
+declare function tableToCsv<TData>(table: Table<TData>, { values, scope, locale: localeArg }?: {
+    values?: CsvValues;
+    scope?: CsvScope;
+    locale?: string;
+}): 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;
 }
 
+interface PivotTableProps<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 集計済みの行の配列。1 行 = 1 マス(行の次元 × 列の次元の組)。同じ組が複数あれば後の行が勝つ(合計はしない)。 */
+    data: T[];
+    /** 行の次元の列名(左から入れ子)。例 `["region", "category"]`。空なら 1 行。 */
+    rows: (keyof T & string)[];
+    /** 列の次元の列名(上から入れ子)。例 `["year"]`。空なら列の見出しは値の名前だけ。 */
+    columns: (keyof T & string)[];
+    /** マスに出す数値の列名。2 つ以上なら列の次元ごとに小列に分かれる。 */
+    values: (keyof T & string)[];
+    /** 値ごとの書式。例 `{ sales: "currency", margin: "percent" }`。無い値は `"number"`。 */
+    formats?: Partial<Record<string, ValueFormat>>;
+    /** 列名・次元の値 → 表示名(見出しに反映)。 */
+    labels?: Record<string, string>;
+    /** 値でマスを塗る(ハイライト表)。`true` で全部の値(値ごとに最小〜最大)、値の列名でその値だけ。既定 `false`。 */
+    highlight?: boolean | string;
+    /** 塗りの色。`"chart-1"`〜`"chart-5"` か意味色。薄い → 濃いの単色。既定 `"chart-1"`。 */
+    tone?: ChartSeriesColor;
+    /** マスのクリック。そのマスの行を受け取る(フィルターの操作に使う)。値の無いマスでは呼ばない。 */
+    onSelect?: (row: T) => void;
+    /** 表の見出し。 */
+    title?: string;
+    /** 表が言っていることの 1 文要約。 */
+    summary?: string;
+    /** 読み込み中。スケルトンを出す。 */
+    isLoading?: boolean;
+    /** `data` が空のときの表示。 */
+    emptyState?: ChartEmptyState;
+    /** 表の箱の最大の高さ(px)。超えると箱の中で縦にスクロールし、見出しは上に残る。既定 480。 */
+    maxHeight?: number;
+    className?: string;
+    /** スクリーンリーダー向けのラベル。省略時は見出し。 */
+    ariaLabel?: string;
+}
+declare function PivotTable<T extends Record<string, unknown>>({ data, rows: rowDims, columns: colDims, values: valueKeys, formats, labels, highlight, tone, onSelect, title, summary, isLoading, emptyState, maxHeight, className, ariaLabel, }: PivotTableProps<T>): React.JSX.Element;
+
 interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
     value: FilterValues;
     onChange: (values: FilterValues) => void;
@@ -428,9 +2469,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;
 }
@@ -455,7 +2502,7 @@ declare namespace FilterBarActiveChips {
     var displayName: string;
 }
 interface FilterBarClearButtonProps {
-    /** Override the button label. Defaults to "クリア". */
+    /** Override the button label. Defaults to "Clear" (ja: "クリア"). */
     label?: string;
     className?: string;
 }
@@ -476,23 +2523,51 @@ declare namespace FilterBarPreset {
     var displayName: string;
 }
 
+/**
+ * フォールバック（`en-US`：英語・1 月始まり・日曜始まり）のプリセット。DateRangePicker は `presets` を渡さなければ
+ * ページのロケールからプリセットを作るので、これを渡す必要はない。`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*` なら日本語、それ以外は英語。
+     * 既定はページのロケール（`<html lang>`、無ければ `"en-US"`）。
+     *
+     * @example
+     * <DateRangePicker locale="ja-JP" />
+     */
+    locale?: string;
+    /**
+     * 年度の開始月（1-12）。「今年度」「前年度」と、年度基準の「今四半期」「前四半期」の区切りになる。
+     * 既定はロケールで決まる（ja は `4`、それ以外は `1`）。範囲外・整数でない値はその既定として扱う。
+     *
+     * @example
+     * <DateRangePicker fiscalYearStartMonth={1} />
+     */
+    fiscalYearStartMonth?: number;
     maxDate?: Date;
     minDate?: Date;
     placeholder?: string;
@@ -553,29 +2628,312 @@ 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.
+ * `locale` picks the language of `label` ("Highest in 12 months" / "過去 12 か月で最高"); default the page's (`<html lang>`).
+ */
+declare function detectRecord(history: ReadonlyArray<number | null | undefined> | null | undefined, grain?: PeriodGrain, polarity?: Polarity, locale?: string): 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 万・億 on a ja page (USD in K・M・B otherwise); `"percent"` takes a ratio (0.021 → 2.1%) and
+     * switches the delta to points. See `formatValue` for the full table.
+     */
+    format?: ValueFormat;
+    /** Locale of the numbers and the built-in wording. Default: the page's (`<html lang>`, else `"en-US"`). */
+    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;
+    };
+    /** Which direction is good: `"up"` (default) or `"down"` (churn, error rate). Wins over `polarity`. */
+    betterWhen?: "up" | "down";
+    /** @deprecated Older name of `betterWhen` (`"higher-is-better"` / `"lower-is-better"`). `"neutral"` (never colours the change, skips the target and record logic) is only reachable here. `betterWhen` wins if both are given. */
+    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 `betterWhen="down"`
+     * 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: localeProp, comparison: comparisonProp, comparisons, provisional, betterWhen, polarity: polarityProp, 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;
+    /** Which direction is good: `"up"` (default) or `"down"` (churn, error rate). Wins over `polarity`. */
+    betterWhen?: "up" | "down";
+    /** @deprecated Older name of `betterWhen` (`"higher-is-better"` / `"lower-is-better"`); `"neutral"` is only reachable here. `betterWhen` wins if both are given. */
+    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 and its label. Default: the page's (`<html lang>`, else `"en-US"`). */
+    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 };
+/**
+ * The mark's wording in English (the fallback language). Without a `label`, the mark follows the page's
+ * language (`<html lang>`): ja reads「見本の値」.
+ */
+declare const DEFAULT_SAMPLE_LABEL: string;
+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> {
+    /** 印の文言。既定はページの言語で「見本の値」（英語は "Sample data"）。 */
+    label?: string;
+}
+declare function SampleBadge({ label, className, ...props }: SampleBadgeProps): React.JSX.Element;
+interface SampleDataProps {
+    /** 印の文言。既定はページの言語で「見本の値」（英語は "Sample data"）。 */
+    label?: string;
+    children?: ReactNode;
+}
+declare function SampleData({ label, children }: SampleDataProps): React.JSX.Element;
+
+interface DraftChartProps {
+    /** The proposed chart: one card (e.g. `DashboardCardPreset`), as it would sit in the page. */
+    children: ReactElement;
+}
+/**
+ * A chart proposed to the page that nobody has accepted yet. Accepting it removes the
+ * `<DraftChart>` tags and keeps the child; removing it deletes the whole element. Both are
+ * source edits made outside the framework — this component only decides what each build shows.
+ *
+ * - `vantage build` (published dashboards): renders nothing, so viewers never see a proposal.
+ * - `vantage dev` (the editor preview): renders the child faded under the page background, and
+ *   marks the child's root element with `data-sq-draft` so the editor can find it and draw its
+ *   own controls over it. The component itself draws no buttons or text.
+ */
+declare function DraftChart({ children }: DraftChartProps): React.JSX.Element | null;
+
+export { AppShell, type AppShellHeaderProps, type AppShellProps, type AppShellSidebarProps, AreaChart, type AreaChartProps, type AttentionKind, AttentionList, type AttentionListProps, BarChart, type BarChartProps, BarList, type BarListItem, type BarListOptions, type BarListProps, type BarListSortOrder, BoxPlotChart, type BoxPlotChartProps, type BoxPlotGroup, 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 ComboAxis, ComboChart, type ComboChartProps, type ComboReferenceLine, type ComboSeries, type ComboSeriesType, type Comparison, type ComparisonKind, type ComparisonOptions, type ComparisonResult, 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, DateStyle, Delta, type DeltaDirection, type DeltaProps, type DeltaSentiment, DonutChart, type DonutChartOptions, type DonutChartProps, type DonutVariant, DraftChart, type DraftChartProps, EChart, type EChartProps, FilledMap, type FilledMapName, type FilledMapProps, 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, ForecastChart, type ForecastChartProps, type ForecastComponent, type ForecastOptions, type ForecastPeriod, type FunnelStep, FunnelSteps, type FunnelStepsProps, Heatmap, type HeatmapProps, HistogramChart, type HistogramChartProps, type HistogramThreshold, type HistoryGrain, KpiCard, type KpiCardProps, type KpiCardSource, type KpiPeriod, Legend, type LegendProps, LineChart, type LineChartProps, 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, PairedChart, type PairedChartProps, type PairedPanel, type PeriodGrain, PivotTable, type PivotTableProps, 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, SymbolMap, type SymbolMapBasemap, type SymbolMapProps, type TargetProgress, Tracker, type TrackerBlock, type TrackerProps, Treemap, type TreemapProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, UpdatedAt, type UpdatedAtProps, ValueFormat, type ValueFormatter, WaterfallChart, type WaterfallChartProps, type WaterfallMode, comparisonBaseline, comparisonLabel, computeComparison, computeTargetProgress, defaultChangeDisplay, defaultPresets, deltaVariants, detectRecord, fillKpiTemplate, flattenOptions, formatChange, formatChangeAmount, formatRelativeTime, funnelStepsVariants, inferPeriodGrain, isGroupedOptions, metricValueVariants, pageShellSummaryCardVariants, tableToCsv, toCsv, toneForValue, useDataTable, useResolvedChartColors, useSampleMark };