@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.51e401a

package/registry/ui/funnel-steps.tsx

@@ -1,33 +1,3397 @@
 // Copied by `vantage add ui funnel-steps`. This file is yours to edit.
-// Generated from @squadbase/vantage src/components/funnel-steps.tsx by `npm run registry` (in Vantage, edit src/, not registry/).
+// Generated from @squadbase/squadkit registry/charts/funnel-steps.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * FunnelSteps — proportional bars for a conversion funnel. Bars are sized
+ * against the first step, so pass the steps in descending order. Set
+ * `showConversion` to print the step-to-step rate between them; the lowest
+ * rate is then the only one emphasised (in the `--negative` colour). Pass
+ * `comparison` (`{ values, label? }`: the prior period's value per step) to print each rate's change in
+ * pt and emphasise the rate that fell the most instead. Every bar
+ * is the one primary colour (`--chart-1`) — the steps are one quantity, not
+ * categories — painted as the same light tint BarList uses; `highlight` names the one step the
+ * page is about, drawn in the full colour. A non-zero step always keeps a visible sliver.
+ * Always renders in `ChartFrame` (title, summary, loading / empty states, a
+ * visually-hidden table).
+ */
+import {
+  forwardRef,
+  Fragment,
+  useEffect,
+  useState,
+  type ComponentProps,
+  type ForwardedRef,
+  type KeyboardEvent,
+  type ReactElement,
+  type Ref,
+} from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@squadbase/vantage/ui"
+import { ChartFrame } from "@squadbase/vantage/components"
+import { formatPoints, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartColorToken, ChartCommonProps } from "@squadbase/vantage/components"
+import { useSyncExternalStore } from "react"
+import { EMPTY_VALUE, formatValue, toValueFormatter } from "@squadbase/vantage/components"
+import type { ChartColor, ChartColors, ChartSeriesColor, ChartTone, ValueFormatter } from "@squadbase/vantage/components"
+import { useMemo, useRef, type ReactNode } from "react"
+import type { EChartsOption } from "@squadbase/vantage/components"
+import { computeComparison, defaultChangeDisplay, formatChange, toneForValue, type ComparisonKind, type PeriodGrain } from "@squadbase/vantage/components"
+import { DEFAULT_LOCALE } from "@squadbase/vantage/components"
+import type { ChartThreshold, ChartAnnotation, ChartEventPayload, ChartForecast, ChartForecastRow, ChartHighlight, NumericKeys } from "@squadbase/vantage/components"
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The display language of the parts and the defaults that follow it.
+ *
+ * The language comes from `<html lang>`: a tag starting with `ja` reads Japanese, anything else English.
+ * Without a usable `lang` (missing, invalid, or no `document` — SSR, Node) the locale is `FALLBACK_LOCALE`
+ * (`en-US`). A `locale` passed explicitly (a prop, an argument) always wins.
+ *
+ * Parts read the locale through `useLocale` (`hooks/use-locale`) and pass it down; the pure helpers here
+ * and in `format` / `comparison` / `chart-*` take it as an argument and fall back to `documentLocale()`.
+ */
+
+/** The language of the built-in wording: Japanese or English. */
+type UiLanguage = "ja" | "en"
+
+/** The locale used when `<html lang>` gives none (and on the server). */
+const FALLBACK_LOCALE = "en-US"
+
+/** `"ja"` when `locale` starts with `ja` (`ja`, `ja-JP`), else `"en"`. A missing locale is `"en"`. */
+function uiLanguage(locale: string | null | undefined): UiLanguage {
+  return typeof locale === "string" && locale.trim().toLowerCase().startsWith("ja") ? "ja" : "en"
+}
+
+/** A BCP 47 tag in its canonical form (`en-gb` → `en-GB`), or `FALLBACK_LOCALE` when it is empty or invalid. */
+function normalizeLocale(tag: string | null | undefined): string {
+  const value = tag?.trim()
+  if (!value) return FALLBACK_LOCALE
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? FALLBACK_LOCALE
+  } catch {
+    return FALLBACK_LOCALE
+  }
+}
+
+/**
+ * The locale of the page: `document.documentElement.lang`, canonicalized. `FALLBACK_LOCALE` when it is empty or
+ * invalid, or there is no `document`. Parts read it through `useLocale`, never while rendering.
+ */
+function documentLocale(): string {
+  if (typeof document === "undefined") return FALLBACK_LOCALE
+  return normalizeLocale(document.documentElement?.getAttribute("lang"))
+}
+
+/** `locale` when given, else the page's locale (`documentLocale()`). */
+function resolveLocale(locale?: string | null): string {
+  return locale || documentLocale()
+}
+
+/** Picks the wording table of the locale's language. */
+function pickLocale<T>(table: { ja: T; en: T }, locale?: string | null): T {
+  return table[uiLanguage(resolveLocale(locale))]
+}
+
+/** The currency `format="currency"` uses without a `currency`: JPY for Japanese, USD otherwise. */
+function defaultCurrency(locale?: string | null): string {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? "JPY" : "USD"
+}
+
+/** The month a fiscal year starts in (1–12) when none is given: April for Japanese, January otherwise. */
+function defaultFiscalYearStartMonth(locale?: string | null): number {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? 4 : 1
+}
+
+/** A day of the week, 0 = Sunday … 6 = Saturday (the `Date#getDay` / date-fns numbering). */
+type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+/** Locales whose week starts on Sunday when the runtime has no week data. */
+const SUNDAY_FIRST = new Set(["en", "en-US", "en-CA"])
+
+/**
+ * The first day of the week: Monday for Japanese; otherwise the locale's convention from `Intl.Locale`
+ * (`en-US` Sunday, `en-GB` Monday). Without week data in the runtime: Sunday for `en` / `en-US` / `en-CA`,
+ * Monday for the rest.
+ */
+function weekStartsOn(locale?: string | null): WeekDay {
+  const tag = normalizeLocale(resolveLocale(locale))
+  if (uiLanguage(tag) === "ja") return 1
+  try {
+    const info = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number }
+      weekInfo?: { firstDay: number }
+    }
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay
+    if (typeof firstDay === "number" && firstDay >= 1 && firstDay <= 7) return (firstDay % 7) as WeekDay
+  } catch {
+    // Fall through to the table below.
+  }
+  return SUNDAY_FIRST.has(tag) ? 0 : 1
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/hooks/use-locale.ts (internal to @squadbase/vantage) ---------- */
+
+const listeners = new Set<() => void>()
+let observer: MutationObserver | null = null
+
+/** One observer on `<html lang>` for every subscribed part. */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {}
+  listeners.add(onChange)
+  if (!observer) {
+    observer = new MutationObserver(() => {
+      for (const listener of [...listeners]) listener()
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] })
+  }
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0 && observer) {
+      observer.disconnect()
+      observer = null
+    }
+  }
+}
+
+const serverLocale = () => FALLBACK_LOCALE
+
+/**
+ * The page's locale (`<html lang>`), following changes made while the page runs. On the server and during
+ * hydration it is `FALLBACK_LOCALE` (`en-US`), so the markup matches; it switches right after.
+ */
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
+
+/** The locale a part renders in: its `locale` prop when given, else the page's (`useDocumentLocale`). */
+function useLocale(locale?: string | null): string {
+  const page = useDocumentLocale()
+  return locale || page
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/chart-utils.ts (internal to @squadbase/vantage) ---------- */
+
+const ROOT_PROP_KEYS = new Set(["id", "style", "role", "tabIndex", "lang", "hidden"])
+const ROOT_PROP_PREFIX_RE = /^(data|aria)-/
+
+/**
+ * The attributes of a typed chart's leftover props that belong on its root
+ * element: `id` / `style` / `role` / `tabIndex` / `lang` / `hidden`, `data-*` and `aria-*`.
+ * An allowlist, so a chart's own (or deprecated, ignored) props never reach the DOM.
+ */
+function chartRootProps(rest: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(rest)) {
+    if (value !== undefined && (ROOT_PROP_KEYS.has(key) || ROOT_PROP_PREFIX_RE.test(key))) out[key] = value
+  }
+  return out
+}
+
+/** The series tokens, in palette order — the default `colors` of every typed chart. */
+const DEFAULT_CHART_COLORS: readonly ChartColor[] = [
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+]
+
+const TOKEN_NAME_RE = /^chart-[1-5]$/
+
+/** The meaning colours; each is a theme token of the same name (`--positive`, …). */
+const CHART_TONES: readonly ChartTone[] = ["positive", "warning", "negative", "neutral"]
+
+/** Whether `color` is a meaning colour (`"positive"` / `"warning"` / `"negative"` / `"neutral"`). */
+function isChartTone(color: string): color is ChartTone {
+  return (CHART_TONES as readonly string[]).includes(color.trim())
+}
+
+/**
+ * A chart colour as a CSS value: `"chart-2"` → `var(--chart-2)` (so it follows
+ * light/dark on its own), anything else passes through unchanged.
+ */
+function chartColorToCss(color: ChartColor): string {
+  const value = color.trim()
+  return TOKEN_NAME_RE.test(value) || isChartTone(value) ? `var(--${value})` : value
+}
+
+/**
+ * A chart colour for an AREA (bar, slice, segment, ring): like `chartColorToCss`, but a meaning
+ * colour resolves to its area token (`"positive"` → `var(--positive-fill)`), which keeps the same
+ * lightness step from the page in light and dark. `--positive` etc. are for text and icons.
+ */
+function chartFillToCss(color: ChartColor): string {
+  const value = color.trim()
+  return isChartTone(value) ? `var(--${value}-fill)` : chartColorToCss(color)
+}
+
+/** The colour name to resolve for an area: a meaning colour becomes its `-fill` token (`"positive"` → `"positive-fill"`), the rest is unchanged. */
+function chartFillName(color: ChartColor): ChartColor {
+  const value = color.trim()
+  return isChartTone(value) ? `${value}-fill` : color
+}
+
+/** The `i`-th colour, cycling through `colors` (the token palette when empty). */
+function chartColorAt(colors: readonly ChartColor[] | undefined, i: number): ChartColor {
+  const palette = colors && colors.length > 0 ? colors : DEFAULT_CHART_COLORS
+  return palette[i % palette.length]!
+}
+
+/** `colors` extended (by cycling) to exactly `count` entries. */
+function chartColorsFor(colors: readonly ChartColor[] | undefined, count: number): ChartColor[] {
+  return Array.from({ length: count }, (_, i) => chartColorAt(colors, i))
+}
+
+/** A translucent version of a CSS colour (works for `var(--…)` too). */
+function tintCss(cssColor: string, percent: number): string {
+  return `color-mix(in oklab, ${cssColor} ${percent}%, transparent)`
+}
+
+const numberFormat = new Intl.NumberFormat("ja-JP", { maximumFractionDigits: 2 })
+
+/** Default `valueFormatter`: grouped digits, up to two decimals (`1,234.5`). */
+const defaultValueFormatter: ValueFormatter = (value) => numberFormat.format(value)
+
+/**
+ * The formatter a chart actually uses: an explicit `valueFormatter` wins, else
+ * `format` (default `"compact"`, so ¥1億 / 9.2万 on axes) via `toValueFormatter`.
+ */
+function resolveValueFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  locale?: string,
+): ValueFormatter {
+  return valueFormatter ?? toValueFormatter(format, locale)
+}
+
+/**
+ * The formatter of value-axis ticks and on-plot labels: an explicit
+ * `valueFormatter` wins; else `"compact"` / `"number"` / `"currency"` read in
+ * the short form (`1億`, `¥1億`, `¥4,520万` — a tick of `¥100,000,000` is
+ * too wide to read), and `"percent"` / `"multiple"` as `format` says. The short
+ * form goes through `formatValue` (compact notation, `digits` / `unit` dropped),
+ * so an axis tick and a KPI / tooltip of the same `format` always print the same
+ * currency sign and grouping.
+ */
+function resolveAxisFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  localeArg?: string,
+): ValueFormatter {
+  if (valueFormatter) return valueFormatter
+  const locale = resolveLocale(localeArg)
+  const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
+  if (spec.type !== "compact" && spec.type !== "number" && spec.type !== "currency") return toValueFormatter(format, locale)
+  const currency = "currency" in spec ? spec.currency : undefined
+  const short: ValueFormat =
+    spec.type === "currency" ? { type: "currency", currency, notation: "compact" } : { type: "compact" }
+  return (value) => formatValue(value, short, locale)
+}
+
+interface CompactUnit {
+  token: string
+  size: number
+}
+
+const compactUnitCache = new Map<string, CompactUnit[] | null>()
+
+/**
+ * The compact-notation unit words of a locale and their sizes, largest first: `兆` / `億` / `万` in ja,
+ * `T` / `B` / `M` / `K` in en. `null` when the locale's compact form puts anything between the number and its
+ * word (`1,5 Mio.`), where a token cannot be swapped in place.
+ */
+function compactUnits(locale: string): CompactUnit[] | null {
+  const cached = compactUnitCache.get(locale)
+  if (cached !== undefined) return cached
+  let units: CompactUnit[] | null = []
+  try {
+    const compact = new Intl.NumberFormat(locale, { notation: "compact" })
+    const seen = new Set<string>()
+    for (let exp = 3; exp <= 15; exp++) {
+      const parts = compact.formatToParts(10 ** exp)
+      const at = parts.findIndex((p) => p.type === "compact")
+      if (at === -1) continue
+      if (parts[at - 1]?.type !== "integer" || at !== parts.length - 1) {
+        units = null
+        break
+      }
+      const token = parts[at]!.value
+      if (seen.has(token)) continue
+      seen.add(token)
+      units.push({ token, size: 10 ** exp })
+    }
+  } catch {
+    units = null
+  }
+  const sorted = units && units.length > 0 ? units.sort((a, b) => b.size - a.size) : null
+  compactUnitCache.set(locale, sorted)
+  return sorted
+}
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/**
+ * The value-axis tick formatter for an axis whose largest tick is `top`: every tick reads in the unit of
+ * that largest tick, so units never mix on one axis (`¥0.5億` / `¥1億` / `¥1.5億`, not `¥5,000万` / `¥1億`;
+ * `$0.5M` / `$1M` / `$1.5M`, not `$500K` / `$1M`). Only the short forms (`compact` / `number` / `currency`,
+ * no `valueFormatter`) have units to align; any other format — an axis whose largest tick is under the smallest
+ * unit (1万 / 1K), or a locale whose compact form cannot be aligned in place — keeps `resolveAxisFormatter`'s output as it is.
+ */
+function resolveAxisTickFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  localeArg?: string,
+): (top: number) => ValueFormatter {
+  const locale = resolveLocale(localeArg)
+  const base = resolveAxisFormatter(valueFormatter, format, locale)
+  const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
+  const units = !valueFormatter && (spec.type === "compact" || spec.type === "number" || spec.type === "currency") ? compactUnits(locale) : null
+  if (!units) return () => base
+  const number = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 })
+  const numberToken = new RegExp(`\\d[\\d,]*(?:\\.\\d+)?(?:${units.map((u) => escapeRegExp(u.token)).join("|")})?`)
+  return (top) => {
+    const unit = units.find((u) => Math.abs(top) >= u.size)
+    if (!unit) return base
+    return (value) => {
+      const text = base(value)
+      if (value === 0 || !Number.isFinite(value)) return text
+      const scaled = `${number.format(Math.abs(value) / unit.size)}${unit.token}`
+      return text.replace(numberToken, () => scaled)
+    }
+  }
+}
+
+/**
+ * A data cell as a number, or `null` for a gap. Numeric strings count — SQL
+ * `DECIMAL` / `BIGINT` columns usually arrive as strings.
+ */
+function toChartNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null
+  if (typeof value === "bigint") return Number(value)
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/** Clamp `value` into `[min, max]`. */
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+/* ------------------------------------------------------------ aggregation */
+
+/** How many categories a chart colours individually; the rest fold into「その他」. */
+const MAX_CHART_SERIES = 5
+
+/** The series name the folded categories get, by language. */
+const OTHER_SERIES_LABELS: Record<UiLanguage, string> = { ja: "その他", en: "Other" }
+
+/** The series name the folded categories get in `locale` ("Other" / "その他"). Default the page's locale (`<html lang>`). */
+function otherSeriesLabel(locale?: string): string {
+  return OTHER_SERIES_LABELS[uiLanguage(resolveLocale(locale))]
+}
+
+const OTHER_NAMES = new Set(Object.values(OTHER_SERIES_LABELS))
+
+/** Whether a category / row is the "other" bucket by name (「その他」 or "Other", whatever the page language). */
+function isOtherName(name: string | null | undefined): boolean {
+  return typeof name === "string" && OTHER_NAMES.has(name)
+}
+
+interface AggregatedItems<Item extends { name: string; value: number }> {
+  /** The `n` largest items, in their given order. All items when there are `n` or fewer. */
+  top: Item[]
+  /** The items folded into `other`, in their given order. */
+  rest: Item[]
+  /** The folded remainder, or `null` when nothing was folded. */
+  other: { name: string; value: number } | null
+}
+
+/**
+ * Keep the `n` largest items (by value; ties keep the earlier one) in their
+ * given order and fold the rest into one `otherLabel` item. Shared by every
+ * chart that caps its categories (Area / Line / Bar series, Donut slices,
+ * BarList rows).
+ */
+function aggregateTopN<Item extends { name: string; value: number }>(
+  items: readonly Item[],
+  n: number = MAX_CHART_SERIES,
+  otherLabel: string = otherSeriesLabel(),
+): AggregatedItems<Item> {
+  if (items.length <= n) return { top: [...items], rest: [], other: null }
+  const ranked = items
+    .map((item, i) => ({ item, i }))
+    .sort((a, b) => b.item.value - a.item.value || a.i - b.i)
+  const keep = new Set(ranked.slice(0, n).map((r) => r.i))
+  const top = items.filter((_, i) => keep.has(i))
+  const rest = items.filter((_, i) => !keep.has(i))
+  return { top, rest, other: { name: otherLabel, value: rest.reduce((sum, item) => sum + item.value, 0) } }
+}
+
+interface AggregatedSeries {
+  /** Rows to draw: the input rows, plus an `otherCategory` column when categories were folded. */
+  data: Record<string, unknown>[]
+  /** Series to draw: the kept categories in their given order, then `otherCategory`. */
+  categories: string[]
+  /** The folded series' name, or `null`. */
+  otherCategory: string | null
+}
+
+/**
+ * Cap a cartesian chart at `n` series: rank the categories by the sum of their
+ * values, keep the top `n` and add a per-row sum of the rest as `otherLabel`.
+ */
+function aggregateSeries(
+  data: readonly Record<string, unknown>[],
+  categories: readonly string[],
+  n: number = MAX_CHART_SERIES,
+  otherLabel: string = otherSeriesLabel(),
+): AggregatedSeries {
+  const totals = categories.map((name) => ({
+    name,
+    value: data.reduce((sum, row) => sum + (toChartNumber(row[name]) ?? 0), 0),
+  }))
+  const { top, rest, other } = aggregateTopN(totals, n, otherLabel)
+  if (!other) return { data: [...data], categories: [...categories], otherCategory: null }
+  const folded = rest.map((item) => item.name)
+  return {
+    data: data.map((row) => {
+      let sum: number | null = null
+      for (const name of folded) {
+        const v = toChartNumber(row[name])
+        if (v !== null) sum = (sum ?? 0) + v
+      }
+      return { ...row, [other.name]: sum }
+    }),
+    categories: [...top.map((item) => item.name), other.name],
+    otherCategory: other.name,
+  }
+}
+
+/**
+ * `aggregateSeries` that never folds `keep` (a comparison series) into「その他」: the others are capped
+ * at `n` as usual and `keep` is appended last, so it is drawn on top of the cap and never takes the first slot.
+ */
+function aggregateSeriesKeeping(
+  data: readonly Record<string, unknown>[],
+  categories: readonly string[],
+  keep: string | undefined,
+  n: number = MAX_CHART_SERIES,
+  otherLabel: string = otherSeriesLabel(),
+): AggregatedSeries {
+  if (keep === undefined || !categories.includes(keep)) return aggregateSeries(data, categories, n, otherLabel)
+  const aggregated = aggregateSeries(
+    data,
+    categories.filter((c) => c !== keep),
+    n,
+    otherLabel,
+  )
+  return { ...aggregated, categories: [...aggregated.categories, keep] }
+}
+
+/**
+ * `seriesColorsFor` for a chart with a comparison series: the comparison takes no `--chart-*` token (the
+ * builder paints it in muted grey; its slot here is `""`), and the others are assigned as if it were absent,
+ * so a main series keeps its colour whether or not a comparison is drawn.
+ */
+function seriesColorsWithComparison(
+  categories: readonly string[],
+  colors: ChartColors | undefined,
+  otherColor: string,
+  otherCategory: string | null,
+  allCategories: readonly string[],
+  comparison: string | undefined,
+): string[] {
+  if (comparison === undefined || !categories.includes(comparison)) {
+    return seriesColorsFor(categories, colors, otherColor, otherCategory, allCategories)
+  }
+  const main = categories.filter((c) => c !== comparison)
+  const mainColors = seriesColorsFor(
+    main,
+    colors,
+    otherColor,
+    otherCategory,
+    allCategories.filter((c) => c !== comparison),
+  )
+  return categories.map((c) => (c === comparison ? "" : (mainColors[main.indexOf(c)] ?? "")))
+}
+
+/**
+ * Colour per drawn series: the record's token for that category, else the
+ * array's token at the category's position in `allCategories` (cycled), else
+ * the token palette by drawn position. `otherCategory` — and a category the
+ * data itself names「その他」/ "Other" (`OTHER_SERIES_LABELS`) — always gets `otherColor`.
+ */
+function seriesColorsFor(
+  categories: readonly string[],
+  colors: ChartColors | undefined,
+  otherColor: string,
+  otherCategory: string | null = null,
+  allCategories: readonly string[] = categories,
+): string[] {
+  const list = Array.isArray(colors) ? (colors as ChartSeriesColor[]) : undefined
+  const record = !Array.isArray(colors) && colors ? (colors as Partial<Record<string, ChartSeriesColor>>) : undefined
+  return categories.map((category, i) => {
+    if ((otherCategory !== null && category === otherCategory) || isOtherName(category)) return otherColor
+    const fromRecord = record?.[category]
+    if (fromRecord) return fromRecord
+    if (list && list.length > 0) {
+      const at = allCategories.indexOf(category)
+      return list[(at === -1 ? i : at) % list.length]!
+    }
+    return DEFAULT_CHART_COLORS[i % DEFAULT_CHART_COLORS.length]!
+  })
+}
+
+/* ------------------------------------------------------------------ Donut */
+
+/** One drawn donut slice, largest first. */
+interface DonutSlice {
+  name: string
+  /** Negative and missing values count as 0. */
+  value: number
+  /** A chart token (`"chart-1"`…), or `otherColor` for the folded slice. */
+  color: string
+  /** The folded「その他」slice. */
+  isOther: boolean
+  /** The input row, or a synthesized `{ [index]: "その他", [value]: sum }` for the folded slice. */
+  row: Record<string, unknown>
+}
+
+interface DonutSlicesConfig {
+  /** Label column. */
+  index: string
+  /** Value column. */
+  value: string
+  /** Slice colours by rank (cycled). Default: the token palette in order. */
+  colors?: readonly ChartSeriesColor[]
+  /** How many slices are drawn individually; the rest fold into「その他」. Default 5. */
+  maxSlices?: number
+  /** Colour of the folded slice (pass `CHART_OTHER_COLOR`). */
+  otherColor: string
+  otherLabel?: string
+}
+
+/**
+ * Donut slices: sorted by value (largest first, ties keep input order), the
+ * `maxSlices` largest kept and coloured by rank in fixed token order, the rest
+ * summed into one「その他」slice in `otherColor`.
+ */
+function donutSlices(
+  data: readonly Record<string, unknown>[],
+  { index, value, colors, maxSlices = MAX_CHART_SERIES, otherColor, otherLabel = otherSeriesLabel() }: DonutSlicesConfig,
+): DonutSlice[] {
+  const items = data
+    .map((row, i) => {
+      const n = toChartNumber(row[value])
+      return { name: String(row[index] ?? ""), value: n !== null && n > 0 ? n : 0, row, i }
+    })
+    .sort((a, b) => b.value - a.value || a.i - b.i)
+  const { top, other } = aggregateTopN(items, Math.max(1, maxSlices), otherLabel)
+  const palette = colors && colors.length > 0 ? colors : DEFAULT_CHART_COLORS
+  const slices: DonutSlice[] = top.map((item, rank) => ({
+    name: item.name,
+    value: item.value,
+    // A row the data itself names「その他」/ "Other" is the same remainder: grey, like the folded slice.
+    color: isOtherName(item.name) ? otherColor : palette[rank % palette.length]!,
+    isOther: false,
+    row: item.row,
+  }))
+  if (other) {
+    slices.push({
+      name: other.name,
+      value: other.value,
+      color: otherColor,
+      isOther: true,
+      row: { [index]: other.name, [value]: other.value },
+    })
+  }
+  return slices
+}
+
+/* ---------------------------------------------------------------- BarList */
+
+type BarListSortOrder = "ascending" | "descending" | "none"
+
+/** Sort a copy of the rows by value; `"none"` keeps the given order. */
+function sortBarListData<T extends { value: number }>(data: readonly T[], sortOrder: BarListSortOrder): T[] {
+  const rows = [...data]
+  if (sortOrder === "ascending") rows.sort((a, b) => a.value - b.value)
+  else if (sortOrder === "descending") rows.sort((a, b) => b.value - a.value)
+  return rows
+}
+
+/** 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
+}
+
+/** One drawn BarList row. */
+interface BarListRow<Row = Record<string, unknown>> {
+  /** React key: the row's `key`, else its name (`"__other"` for the folded row). */
+  key: string
+  name: string
+  value: number
+  /** Only for real rows; the folded row never links. */
+  href?: string
+  /** Legacy per-row colour (`BarListItem.color`). */
+  color?: ChartColor
+  /** The folded「その他」row. */
+  isOther: boolean
+  /** The input row (`null` for the folded row). */
+  row: Row | null
+}
+
+interface BarListRowsConfig extends BarListOptions {
+  /** Name column. Default `"name"`. */
+  index?: string
+  /** Value column. Default `"value"`. */
+  category?: string
+}
+
+/**
+ * The rows a BarList draws: read name / value (numeric strings count, gaps are
+ * 0), keep the `maxItems` largest (via `aggregateTopN`), sort them, and append
+ * the folded remainder as one「その他」row. Rows named in `exclude` skip the
+ * ranking and are always added to「その他」.
+ */
+function barListRows<Row extends object>(
+  data: readonly Row[],
+  { index = "name", category = "value", sortOrder = "descending", maxItems = MAX_CHART_SERIES, otherLabel = otherSeriesLabel(), exclude }: BarListRowsConfig = {},
+): BarListRow<Row>[] {
+  const items = data.map((row): BarListRow<Row> => {
+    const cells = row as Record<string, unknown>
+    const name = String(cells[index] ?? "")
+    return {
+      key: typeof cells.key === "string" ? cells.key : name,
+      name,
+      value: toChartNumber(cells[category]) ?? 0,
+      href: typeof cells.href === "string" ? cells.href : undefined,
+      color: typeof cells.color === "string" ? cells.color : undefined,
+      isOther: false,
+      row,
+    }
+  })
+  const excluded = new Set(exclude ?? [])
+  const ranked = excluded.size > 0 ? items.filter((item) => !excluded.has(item.name)) : items
+  const outside = excluded.size > 0 ? items.filter((item) => excluded.has(item.name)) : []
+  const { top, other } = aggregateTopN(ranked, Math.max(0, maxItems), otherLabel)
+  const rows = sortBarListData(top, sortOrder)
+  if (other || outside.length > 0) {
+    const value = (other?.value ?? 0) + outside.reduce((sum, item) => sum + item.value, 0)
+    rows.push({ key: "__other", name: otherLabel, value, isOther: true, row: null })
+  }
+  return rows
+}
+
+/** Bar widths in percent of the largest value (at least a sliver for non-zero values). */
+function barListWidths(values: readonly number[]): number[] {
+  const max = Math.max(0, ...values)
+  if (max === 0) return values.map(() => 0)
+  return values.map((v) => (v <= 0 ? 0 : Math.max(1, (v / max) * 100)))
+}
+
+/**
+ * How strongly the BarList bars are painted: every row the same tint of the bar
+ * colour (rank is the bar's length, not its weight). A tint over transparent, so
+ * it sits on the card in light and dark; it must stay visible against the card
+ * while the label printed over the bar keeps its contrast (see `tests/contrast.test.ts`).
+ */
+const BAR_LIST_TINT = 45
+/** 「その他」: a tint of the other colour, so it is the palest fill in the list (light and dark). */
+const BAR_LIST_OTHER_TINT = 30
+
+/**
+ * The fill of each BarList row: all real rows in the same tint of `color`
+ * (`BAR_LIST_TINT`), the folded「その他」row (and a row the data names「その他」/ "Other") in a tint of `otherColor`
+ * (`BAR_LIST_OTHER_TINT`) — the palest fill, a remainder never outweighs a
+ * ranked row. A legacy per-row `color` (or a threshold tone) replaces `color`
+ * for that row. A tint, not the solid token, so the label printed over the bar
+ * keeps its contrast.
+ */
+function barListFills(
+  rows: readonly (Pick<BarListRow, "isOther" | "color"> & { name?: string })[],
+  color: ChartColor,
+  otherColor: string,
+): string[] {
+  return rows.map((row) =>
+    row.isOther || isOtherName(row.name)
+      ? tintCss(otherColor, BAR_LIST_OTHER_TINT)
+      : tintCss(chartColorToCss(row.color ?? color), BAR_LIST_TINT),
+  )
+}
+
+/** A row's share of `total` as text: whole percent (fixed, no decimals), `<1%` for a sliver, `0%` for nothing. */
+function barListShareText(value: number, total: number): string {
+  const v = Number.isFinite(value) && value > 0 ? value : 0
+  if (total <= 0 || v === 0) return "0%"
+  const pct = (v / total) * 100
+  return pct < 1 ? "<1%" : `${Math.round(pct)}%`
+}
+
+/**
+ * The text at the end of each BarList row: the formatted value and, with
+ * `showShare`, its share of the total of all drawn rows (including「その他」,
+ * so the shares are of the whole list): `value` and `share` apart (the share is
+ * drawn muted), `text` as one string (「¥8,240万 · 43%」).
+ */
+function barListValueTexts(
+  values: readonly number[],
+  formatter: ValueFormatter,
+  showShare = false,
+): { value: string; share?: string; text: string }[] {
+  const total = values.reduce((sum, v) => sum + (Number.isFinite(v) && v > 0 ? v : 0), 0)
+  return values.map((v) => {
+    const value = formatter(v)
+    if (!showShare) return { value, text: value }
+    const share = barListShareText(v, total)
+    return { value, share, text: `${value} · ${share}` }
+  })
+}
+
+/* -------------------------------------------------------------- DataTable */
+
+/** The visually-hidden table `ChartFrame` renders next to the plot (`dataTable`). */
+interface ChartDataTable {
+  /** 表の見出し(`<caption>`)。 */
+  caption?: string
+  /** 列見出し。先頭がラベル列。 */
+  columns: string[]
+  /** 行。セルは書式済みの文字列。 */
+  rows: string[][]
+}
+
+/**
+ * The chart's numbers as a table, for screen readers: one row per data row, the
+ * `index` cell then each category through `formatter` (gaps → `—`). `labels`
+ * renames column keys for the header (`{ sessions: "セッション" }`); `indexName` is the first column's header when `labels` has none for `index` (e.g. 「項目」, instead of the raw key).
+ */
+function chartDataTable(
+  data: readonly Record<string, unknown>[],
+  index: string,
+  categories: readonly string[],
+  formatter: ValueFormatter,
+  labels?: Readonly<Record<string, string>>,
+  indexName?: string,
+): ChartDataTable {
+  const label = (key: string) => labels?.[key] ?? key
+  return {
+    columns: [labels?.[index] ?? indexName ?? index, ...categories.map(label)],
+    rows: data.map((row) => [
+      String(row[index] ?? ""),
+      ...categories.map((key) => {
+        const n = toChartNumber(row[key])
+        return n === null ? EMPTY_VALUE : formatter(n)
+      }),
+    ]),
+  }
+}
+
+/* ------------------------------------------------------------ CategoryBar */
+
+interface CategoryBarSegment {
+  /** Width in percent of the whole bar. */
+  width: number
+  /** Where the segment starts, in percent. */
+  start: number
+  /** The running total at the segment's end — what its right-hand label shows. */
+  end: number
+}
+
+/** Lay the values side by side; negative values count as zero. */
+function categoryBarSegments(values: readonly number[]): CategoryBarSegment[] {
+  const clean = values.map((v) => (Number.isFinite(v) && v > 0 ? v : 0))
+  const total = clean.reduce((sum, v) => sum + v, 0)
+  let running = 0
+  return clean.map((v) => {
+    const start = total === 0 ? 0 : (running / total) * 100
+    running += v
+    return { width: total === 0 ? 0 : (v / total) * 100, start, end: running }
+  })
+}
+
+interface CategoryBarLabel {
+  /** Position in percent of the bar. */
+  position: number
+  /** The running total printed there. */
+  value: number
+}
+
+/**
+ * Tick labels under the bar: `0` at the start, then the running total at each
+ * segment's end. A label closer than `minGap` percent to the one before is
+ * dropped so narrow segments don't print on top of each other — except the
+ * last one (the total), which replaces its neighbour instead. With a
+ * `markerPosition`, an inner label closer than `minGap` to the marker is dropped
+ * too — the marker sits right under it and the two read as one crowded spot.
+ */
+function categoryBarLabels(values: readonly number[], minGap = 8, markerPosition?: number): CategoryBarLabel[] {
+  const segments = categoryBarSegments(values).filter((s) => s.width > 0)
+  if (segments.length === 0) return []
+  const labels: CategoryBarLabel[] = [{ position: 0, value: 0 }]
+  segments.forEach((s, i) => {
+    const label = { position: s.start + s.width, value: s.end }
+    const prev = labels[labels.length - 1]!
+    if (label.position - prev.position >= minGap) labels.push(label)
+    else if (i === segments.length - 1 && labels.length > 1) labels[labels.length - 1] = label
+  })
+  if (markerPosition === undefined || !Number.isFinite(markerPosition)) return labels
+  return labels.filter(
+    (label, i) => i === 0 || i === labels.length - 1 || Math.abs(label.position - markerPosition) >= minGap,
+  )
+}
+
+/**
+ * `labels` thinned to what fits side by side on a bar `width` px wide, given each label's printed text
+ * (`texts`, same order): a label that would touch the one before is dropped — except the last (the
+ * total), which replaces its neighbour instead. The first sits at the left edge, the last at the right
+ * edge, the rest centred on their position. The width is a rough estimate (full-width characters 12 px,
+ * the rest 7 px at 12 px type).
+ */
+function categoryBarFitLabels(
+  labels: readonly CategoryBarLabel[],
+  texts: readonly string[],
+  width: number,
+  gap = 8,
+): CategoryBarLabel[] {
+  const textWidth = (text: string) => {
+    let w = 0
+    for (const ch of text) w += /[\u3000-\u9fff\uff00-\uffef]/.test(ch) ? 12 : 7
+    return w
+  }
+  const extent = (label: CategoryBarLabel, text: string): [number, number] => {
+    const w = textWidth(text)
+    if (label.position <= 0) return [0, w]
+    if (label.position >= 100) return [width - w, width]
+    const center = (label.position / 100) * width
+    return [center - w / 2, center + w / 2]
+  }
+  const kept: { label: CategoryBarLabel; extent: [number, number] }[] = []
+  labels.forEach((label, i) => {
+    const here = extent(label, texts[i] ?? "")
+    const touches = () => kept.length > 0 && kept[kept.length - 1]!.extent[1] + gap > here[0]
+    if (i === labels.length - 1) while (kept.length > 1 && touches()) kept.pop()
+    else if (touches()) return
+    kept.push({ label, extent: here })
+  })
+  return kept.map((k) => k.label)
+}
+
+/** Marker position in percent of the bar, clamped to its ends. */
+function categoryBarMarkerPosition(value: number, values: readonly number[]): number {
+  const total = values.reduce((sum, v) => sum + (Number.isFinite(v) && v > 0 ? v : 0), 0)
+  if (total === 0) return 0
+  return clamp((value / total) * 100, 0, 100)
+}
+
+/** Index of the segment the marker sits on (the last one for a value past the end). */
+function categoryBarMarkerSegment(value: number, values: readonly number[]): number {
+  const segments = categoryBarSegments(values)
+  const index = segments.findIndex((s) => s.width > 0 && value <= s.end)
+  if (index !== -1) return index
+  for (let i = segments.length - 1; i >= 0; i--) if (segments[i]!.width > 0) return i
+  return 0
+}
+
+/* --------------------------------------------------------- ProgressCircle */
+
+interface ProgressCircleGeometry {
+  /** SVG width/height. */
+  size: number
+  /** Radius of the stroke's centre line. */
+  normalizedRadius: number
+  circumference: number
+  /** `stroke-dashoffset` for the value arc. */
+  offset: number
+  /** The value as a fraction of `max`, clamped to `[0, 1]`. */
+  ratio: number
+}
+
+function progressCircleGeometry(
+  value: number,
+  max: number,
+  radius: number,
+  strokeWidth: number,
+): ProgressCircleGeometry {
+  const ratio = max > 0 && Number.isFinite(value) ? clamp(value / max, 0, 1) : 0
+  const normalizedRadius = Math.max(0, radius - strokeWidth / 2)
+  const circumference = 2 * Math.PI * normalizedRadius
+  return { size: radius * 2, normalizedRadius, circumference, offset: circumference * (1 - ratio), ratio }
+}
+
+/* ---------------------------------------------------------------- summary */
+
+interface ChartSummaryInput {
+  data: readonly Record<string, unknown>[]
+  /** The x-axis key. */
+  index: string
+  /** Series keys; the first one is described. */
+  categories: readonly string[]
+  /** Title of the chart, put in front when given. */
+  title?: string
+  /** Same as the chart's `format` (default `"compact"`). */
+  format?: ValueFormat
+  /** Wins over `format`. */
+  valueFormatter?: ValueFormatter
+  /** Language of the sentence. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+const SUMMARY_TEXT = {
+  ja: {
+    up: "、前の点より増加",
+    down: "、前の点より減少",
+    flat: "、前の点と横ばい",
+    latest: (label: string, value: string) => `最新 ${label} は ${value}`,
+    top: (name: string, share: string) => `最大は ${name}(${share})`,
+  },
+  en: {
+    up: ", up from the previous point",
+    down: ", down from the previous point",
+    flat: ", flat from the previous point",
+    latest: (label: string, value: string) => `Latest ${label}: ${value}`,
+    top: (name: string, share: string) => `Largest: ${name} (${share})`,
+  },
+}
+
+/**
+ * One-sentence summary built from the rows, for `summary="auto"`:
+ * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」("<title>: Latest <index>: <value>, up from the previous point"). The direction is
+ * computed from the last two non-empty points of the first series — never
+ * written by hand, so it cannot contradict the data. `undefined` when there is
+ * no usable point.
+ */
+function buildChartSummary(input: ChartSummaryInput): string | undefined {
+  const key = input.categories[0]
+  if (key === undefined) return undefined
+  const points: { label: string; value: number }[] = []
+  for (const row of input.data) {
+    const raw = row[key]
+    const value = raw === null || raw === undefined || raw === "" ? NaN : Number(raw)
+    if (Number.isFinite(value)) points.push({ label: String(row[input.index] ?? ""), value })
+  }
+  const latest = points[points.length - 1]
+  if (!latest) return undefined
+  const locale = resolveLocale(input.locale)
+  const t = SUMMARY_TEXT[uiLanguage(locale)]
+  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact", locale)
+  const prev = points[points.length - 2]
+  const direction = !prev ? "" : latest.value > prev.value ? t.up : latest.value < prev.value ? t.down : t.flat
+  const head = input.title ? `${input.title}: ` : ""
+  return `${head}${t.latest(latest.label, text(latest.value))}${direction}`
+}
+
+/**
+ * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」("<title>: Largest: <name> (<share>)") from the slices
+ * (largest first). `undefined` when there is nothing to describe. `locale` picks the language; default the page's.
+ */
+function buildShareSummary(
+  slices: readonly { name: string; value: number }[],
+  title?: string,
+  locale?: string,
+): string | undefined {
+  const total = slices.reduce((sum, s) => sum + s.value, 0)
+  const top = slices[0]
+  if (!top || total <= 0) return undefined
+  const share = `${Math.round((top.value / total) * 1000) / 10}%`
+  return `${title ? `${title}: ` : ""}${SUMMARY_TEXT[uiLanguage(resolveLocale(locale))].top(top.name, share)}`
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/chart-options.ts (internal to @squadbase/vantage) ---------- */
+
+/** The built-in words of the option builders, by language. */
+const CHART_TEXT = {
+  ja: {
+    target: "目標",
+    forecast: "予測",
+    total: "合計",
+    provisional: "速報",
+    noComparison: "比較なし",
+    share: (share: string) => `（${share}）`,
+    targetRate: (rate: string) => `（達成率 ${rate}）`,
+    provisionalTitle: (title: string, label: string) => `${title}(${label})`,
+  },
+  en: {
+    target: "Target",
+    forecast: "Forecast",
+    total: "Total",
+    provisional: "Preliminary",
+    noComparison: "No comparison",
+    share: (share: string) => ` (${share})`,
+    targetRate: (rate: string) => ` (${rate} achieved)`,
+    provisionalTitle: (title: string, label: string) => `${title} (${label})`,
+  },
+} satisfies Record<UiLanguage, unknown>
+
+const chartText = (locale?: string) => CHART_TEXT[uiLanguage(resolveLocale(locale))]
+
+type CartesianChartKind = "area" | "bar" | "line"
+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
+}
+
+/** The point a user clicked, used to dim everything else. */
+interface ChartActivePoint {
+  category: string
+  index: number
+}
+
+/** The forecast as the builder takes it: untyped keys, already validated by the component's props. */
+type CartesianForecastConfig = Omit<ChartForecast, "category"> & { category?: string }
+
+/** The comparison series as the builder takes it (see `ChartComparison`); `label` names the baseline for `vs: "custom"`. */
+interface CartesianComparisonConfig {
+  /** One of `categories`; drawn as a thin muted line, outside the `--chart-*` order. */
+  category: string
+  vs: ComparisonKind
+  label?: string
+}
+
+interface CartesianChartConfig {
+  kind: CartesianChartKind
+  data: readonly Record<string, unknown>[]
+  index: string
+  categories: readonly string[]
+  /** Resolved series colours, by category position. `""`/missing → theme palette. */
+  palette: readonly string[]
+  /** Display names for `index` values and category names (axis, legend, tooltip). Missing keys show as they are. */
+  labels?: Readonly<Record<string, string>>
+  /** Bar only, not stacked: colour each bar by its value (first matching rule wins). With several series (side by side) a bar that matches takes the tone as its fill and keeps its series colour as the edge. */
+  thresholds?: readonly ChartThreshold[]
+  /** Resolved colour of each tone (`resolveChartColors`); a tone missing here keeps the series colour. */
+  toneColors?: Partial<Record<ChartTone, string>>
+  /** Tooltip values. */
+  valueFormatter: (value: number) => string
+  /** Value-axis ticks, highlight and target labels (short form, e.g. ¥1億). Default `valueFormatter`. */
+  axisFormatter?: (value: number) => string
+  /**
+   * The value-axis tick formatter for an axis whose largest tick is the given number (`resolveAxisTickFormatter`):
+   * all ticks read in one unit (¥0.5億 / ¥1億). Default: `axisFormatter` for every tick.
+   */
+  axisTicks?: (top: number) => (value: number) => string
+  /** Locale of the time-axis labels and the built-in words (total, target, forecast). Default the page's (`<html lang>`). */
+  locale?: string
+  type?: CartesianStackType
+  /** Bar only. `"vertical"` lays the categories down the y axis (horizontal bars). */
+  layout?: BarLayout
+  curveType?: CartesianCurveType
+  fill?: AreaFill
+  connectNulls?: boolean
+  showLegend?: boolean
+  showTooltip?: boolean
+  showGridLines?: boolean
+  showXAxis?: boolean
+  showYAxis?: boolean
+  startEndOnly?: boolean
+  yAxisWidth?: number
+  /** Bar / Area: only a value ≤ 0 takes effect (they start at 0). Line: the axis' start. The axis widens to the data. */
+  minValue?: number
+  /** The axis' top; the axis widens to the data. */
+  maxValue?: number
+  /** Line only: legacy alias of `fitToData`. */
+  autoMinValue?: boolean
+  /** Line only: let the value axis follow the data instead of starting at 0. */
+  fitToData?: boolean
+  allowDecimals?: boolean
+  xAxisLabel?: string
+  yAxisLabel?: string
+  barCategoryGap?: string | number
+  /** Always draw the line/area points (needed to click them). */
+  showDots?: boolean
+  active?: ChartActivePoint | null
+  /** Default: `"auto"` for line/area, for bar only when `index` holds dates. */
+  highlight?: ChartHighlight
+  /** Bar only: the index value of the one horizontal bar drawn in the full colour (`BarChartOptions.highlight`). */
+  barHighlight?: string | number
+  target?: number
+  targetLabel?: string
+  /** Line only: where the target label sits (see `LineChartOptions.targetLabelPosition`). Default `"start"`. */
+  targetLabelPosition?: LineTargetLabelPosition
+  /** Bar only: a data column holding each bar's target (see `BarChartOptions.targetKey`). */
+  targetKey?: string
+  /** Notes at an index value or over a range (vertical bars, line, area). */
+  annotations?: readonly ChartAnnotation[]
+  /** Bar only, not stacked: label bars whose value is 0 with「0」(default true). */
+  showZeroValues?: boolean
+  /** Line / Area only; ignored for bar and for percent stacking. */
+  forecast?: CartesianForecastConfig
+  /**
+   * Line / Area only; ignored for bar and for percent stacking. The series `category` is drawn as a muted 1.5px solid line
+   * (no markers, no fill, outside a stack) and the first other series' tooltip row gets its difference from it.
+   */
+  comparison?: CartesianComparisonConfig
+  /** The `format` of the values, for the comparison's difference in the tooltip (percent → points). Default: relative change. */
+  comparisonFormat?: ValueFormat
+  /** Index value of the first provisional point (see `CartesianChartBaseProps.provisionalFrom`). */
+  provisionalFrom?: string | number
+  provisionalLabel?: string
+  /** The PNG action buttons are shown (top right): the legend keeps clear of them. */
+  reserveActions?: boolean
+  /** Colour of the target / forecast guide lines (resolved muted text). */
+  guideColor?: string
+  /**
+   * The surface the chart sits on (resolved). Highlight labels get it as a
+   * backdrop, so a guide line passing behind them never runs through the text.
+   */
+  labelBackground?: string
+  /** Colour of the highlight labels (resolved foreground). */
+  labelColor?: string
+  /**
+   * The plot's width in px, when known. Sets how many time labels fit, how many value ticks a
+   * horizontal bar chart carries, and drops the max highlight when it would print over the latest one.
+   */
+  plotWidth?: number
+  /** The plot's height in px (the `height` prop), when known: under 200 the value axis carries 3 intervals, else 4–5. */
+  plotHeight?: number
+  reducedMotion?: boolean
+  /** Deep-merged onto the generated option last. */
+  chartOptions?: EChartsOption
+}
+
+/* ----------------------------------------------------------------- motion */
+
+/**
+ * The typed charts' motion: no entrance animation, a short ease on updates so a
+ * filter change reads as a change. Reduced motion turns animation off.
+ */
+function chartMotion(reducedMotion: boolean): EChartsOption {
+  if (reducedMotion) return { animation: false }
+  return { animation: true, animationDuration: 0, animationDurationUpdate: 300, animationEasingUpdate: "cubicOut" }
+}
+
+/* ----------------------------------------------------------------- merge */
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Deep-merge `override` onto `base` without mutating either: plain objects merge
+ * key by key, arrays merge by position (so `series: [{ … }]` tweaks the first
+ * series), anything else in `override` replaces. `undefined` keeps the base.
+ */
+function mergeChartOptions<T>(base: T, override: unknown): T {
+  if (override === undefined) return base
+  if (Array.isArray(override)) {
+    if (!Array.isArray(base)) return override as T
+    const length = Math.max(base.length, override.length)
+    return Array.from({ length }, (_, i) => (i < override.length ? mergeChartOptions(base[i], override[i]) : base[i])) as T
+  }
+  if (isPlainRecord(override) && isPlainRecord(base)) {
+    const out: Record<string, unknown> = { ...base }
+    for (const key of Object.keys(override)) out[key] = mergeChartOptions(base[key], override[key])
+    return out as T
+  }
+  return override as T
+}
+
+/* -------------------------------------------------------------- highlight */
+
+const TIME_INDEX_RE =
+  /^\d{4}(?:[-/]\d{1,2}(?:[-/]\d{1,2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?)?)?$/
+
+/**
+ * Whether the x values look like time: ISO dates / date-times, `YYYY-MM`,
+ * `YYYY`, or `Date` objects. Blank cells are ignored; nothing at all → `false`.
+ */
+function isTimeIndex(values: readonly unknown[]): boolean {
+  const present = values.filter((v) => v !== null && v !== undefined && v !== "")
+  if (present.length === 0) return false
+  return present.every((v) =>
+    v instanceof Date ? !Number.isNaN(v.getTime()) : typeof v === "string" && TIME_INDEX_RE.test(v.trim()),
+  )
+}
+
+/* -------------------------------------------------------------- time axis */
+
+type TimeGranularity = "year" | "month" | "day"
+
+interface ParsedTime {
+  year: number
+  /** 1–12. */
+  month: number
+  day: number
+}
+
+const TIME_PARTS_RE = /^(\d{4})(?:[-/](\d{1,2})(?:[-/](\d{1,2}))?)?$/
+
+/**
+ * The x values as calendar dates, with the finest granularity they carry — or
+ * `null` when any value is not a plain year / month / date (date-times with a
+ * clock part stay as they are: one label per hour would need its own format).
+ */
+function parseTimeIndex(values: readonly unknown[]): { granularity: TimeGranularity; times: (ParsedTime | null)[] } | null {
+  if (!isTimeIndex(values)) return null
+  const ranks: readonly TimeGranularity[] = ["year", "month", "day"]
+  let rank = 0
+  const finer = (g: TimeGranularity) => {
+    rank = Math.max(rank, ranks.indexOf(g))
+  }
+  const times: (ParsedTime | null)[] = []
+  for (const v of values) {
+    if (v === null || v === undefined || v === "") {
+      times.push(null)
+      continue
+    }
+    if (v instanceof Date) {
+      if (v.getHours() !== 0 || v.getMinutes() !== 0 || v.getSeconds() !== 0) return null
+      finer(v.getDate() === 1 ? "month" : "day")
+      times.push({ year: v.getFullYear(), month: v.getMonth() + 1, day: v.getDate() })
+      continue
+    }
+    const text = String(v).trim()
+    // A trailing midnight (`2025-09-01T00:00:00Z`) is still a date; any other time of day is not.
+    const date = text.replace(/[T ]00:00(?::00(?:\.0+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/, "")
+    const m = TIME_PARTS_RE.exec(date)
+    if (!m) return null
+    finer(m[3] !== undefined ? "day" : m[2] !== undefined ? "month" : "year")
+    times.push({ year: Number(m[1]), month: Number(m[2] ?? 1), day: Number(m[3] ?? 1) })
+  }
+  // Date objects on the 1st read as months only when every value falls on a 1st.
+  if (rank === 1 && values.some((v) => v instanceof Date) && times.some((t) => t !== null && t.day !== 1)) rank = 2
+  return { granularity: ranks[rank]!, times }
+}
+
+const timeFormatCache = new Map<string, Intl.DateTimeFormat>()
+
+function timeFormat(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = `${locale}|${JSON.stringify(options)}`
+  let format = timeFormatCache.get(key)
+  if (!format) {
+    format = new Intl.DateTimeFormat(locale, options)
+    timeFormatCache.set(key, format)
+  }
+  return format
+}
+
+const toDate = (t: ParsedTime) => new Date(t.year, t.month - 1, t.day)
+
+/** How many x labels a time axis shows at most (the step is picked so the labels never crowd). */
+const TIME_AXIS_MAX_LABELS = 6
+/** Under this plot width (px) the axis, legend and labels switch to their compact form. */
+const NARROW_PLOT_WIDTH = 400
+/** The most x labels a narrow plot shows (a 262px plot reads 4 at most). */
+const NARROW_TIME_AXIS_MAX_LABELS = 4
+
+/** Calendar-friendly label steps per granularity (every 3 months, every week …). */
+const TIME_AXIS_STEPS: Record<TimeGranularity, readonly number[]> = {
+  year: [1, 2, 5, 10, 20, 50, 100],
+  month: [1, 2, 3, 4, 6, 12, 24, 36, 60, 120],
+  day: [1, 2, 7, 14, 28, 56, 91, 182, 364],
+}
+
+/**
+ * Every how many points a time axis prints a label: the smallest calendar step
+ * (1, 2, 3, 4, 6, 12 months; 1, 2, 7, 14 days; …) that keeps the labels at or
+ * under `maxLabels`. Deterministic, so the year-change label is never skipped by
+ * ECharts' own overlap thinning. `null` when the values are not dates.
+ */
+function timeAxisLabelStep(values: readonly unknown[], maxLabels: number = TIME_AXIS_MAX_LABELS): number | null {
+  const parsed = parseTimeIndex(values)
+  if (!parsed) return null
+  const count = values.length
+  const max = Math.max(1, maxLabels)
+  const steps = TIME_AXIS_STEPS[parsed.granularity]
+  return steps.find((step) => Math.ceil(count / step) <= max) ?? Math.ceil(count / max)
+}
+
+/**
+ * Category-axis labels for time-like x values, in `locale`: monthly data reads
+ * `4月`, with the year (`2025年1月`) on the first shown label and on any shown
+ * label whose year differs from the previous *shown* one; daily data reads
+ * `4/1` (`2025/4/1` likewise); yearly data `2025年`. `shown(i)` says which
+ * labels the axis prints (default: all) — hidden ones never carry the year.
+ * `null` when the values are not dates — the axis then shows them as they are.
+ */
+function timeAxisLabels(
+  values: readonly unknown[],
+  localeArg?: string,
+  shown: (i: number) => boolean = () => true,
+): string[] | null {
+  const parsed = parseTimeIndex(values)
+  if (!parsed) return null
+  const locale = resolveLocale(localeArg)
+  const { granularity, times } = parsed
+  let prevYear: number | null = null
+  return times.map((t, i) => {
+    if (t === null) return String(values[i] ?? "")
+    const visible = shown(i)
+    const withYear = visible && (prevYear === null || t.year !== prevYear)
+    if (visible) prevYear = t.year
+    const options: Intl.DateTimeFormatOptions =
+      granularity === "year"
+        ? { year: "numeric" }
+        : granularity === "month"
+          ? withYear
+            ? { year: "numeric", month: "short" }
+            : { month: "short" }
+          : withYear
+            ? { year: "numeric", month: "numeric", day: "numeric" }
+            : { month: "numeric", day: "numeric" }
+    return timeFormat(locale, options).format(toDate(t))
+  })
+}
+
+/** The tooltip titles for time-like x values (`2025年9月`, `2025年9月1日`), or `null` when they are not dates. */
+function timeTooltipLabels(values: readonly unknown[], localeArg?: string): string[] | null {
+  const parsed = parseTimeIndex(values)
+  if (!parsed) return null
+  const locale = resolveLocale(localeArg)
+  const options: Intl.DateTimeFormatOptions =
+    parsed.granularity === "year"
+      ? { year: "numeric" }
+      : parsed.granularity === "month"
+        ? { year: "numeric", month: "long" }
+        : { year: "numeric", month: "long", day: "numeric" }
+  return parsed.times.map((t, i) => (t === null ? String(values[i] ?? "") : timeFormat(locale, options).format(toDate(t))))
+}
+
+interface HighlightPoint {
+  kind: "max" | "latest" | "start"
+  index: number
+  value: number
+}
+
+/**
+ * The points `highlight="auto"` labels on one series: the latest (last
+ * non-null) point, and the maximum unless it *is* the latest or sits next to it
+ * (`|i - latest| ≤ 1`, the labels would collide) — at most 2, max first.
+ */
+function pickHighlightPoints(values: readonly (number | null)[]): HighlightPoint[] {
+  let latest = -1
+  for (let i = values.length - 1; i >= 0; i--) {
+    if (values[i] !== null && values[i] !== undefined) {
+      latest = i
+      break
+    }
+  }
+  if (latest === -1) return []
+  const latestValue = values[latest]!
+  let max = -1
+  values.forEach((v, i) => {
+    if (v !== null && v !== undefined && (max === -1 || v > values[max]!)) max = i
+  })
+  const latestPoint: HighlightPoint = { kind: "latest", index: latest, value: latestValue }
+  if (max === -1 || max === latest || latestValue >= values[max]! || Math.abs(max - latest) <= 1) return [latestPoint]
+  return [{ kind: "max", index: max, value: values[max]! }, latestPoint]
+}
+
+/**
+ * The points a 100% stacked area labels: the first and the latest (last
+ * non-null) share of one band — "24% → 31%" is the claim such a chart makes.
+ */
+function pickShareHighlightPoints(values: readonly (number | null)[]): HighlightPoint[] {
+  const first = values.findIndex((v) => v !== null && v !== undefined)
+  if (first === -1) return []
+  let latest = first
+  for (let i = values.length - 1; i > first; i--) {
+    if (values[i] !== null && values[i] !== undefined) {
+      latest = i
+      break
+    }
+  }
+  const latestPoint: HighlightPoint = { kind: "latest", index: latest, value: values[latest]! }
+  return latest === first ? [latestPoint] : [{ kind: "start", index: first, value: values[first]! }, latestPoint]
+}
+
+/** Whether a chart of `kind` labels its highlights by default. */
+function defaultChartHighlight(
+  kind: CartesianChartKind,
+  data: readonly Record<string, unknown>[],
+  index: string,
+): ChartHighlight {
+  if (kind !== "bar") return "auto"
+  return isTimeIndex(data.map((row) => row[index])) ? "auto" : "none"
+}
+
+/* ---------------------------------------------------------------- helpers */
+
+/** Same coercion as `toChartNumber` in chart-utils (kept local: inlined modules can't import each other). */
+function cellNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null
+  if (typeof value === "bigint") return Number(value)
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/**
+ * Series values per category. `"percent"` turns each row into shares of that
+ * row's total (0–100); a row whose total is 0 stays at 0.
+ */
+function cartesianSeriesValues(
+  data: readonly Record<string, unknown>[],
+  categories: readonly string[],
+  type: CartesianStackType = "default",
+): (number | null)[][] {
+  const raw = categories.map((category) => data.map((row) => cellNumber(row[category])))
+  if (type !== "percent") return raw
+  return raw.map((values) =>
+    values.map((value, i) => {
+      if (value === null) return null
+      const total = categories.reduce((sum, _, k) => sum + Math.abs(raw[k]![i] ?? 0), 0)
+      return total === 0 ? 0 : (Math.abs(value) / total) * 100
+    }),
+  )
+}
+
+/** A colour with alpha, for gradient stops. Understands `#rgb`, `#rrggbb`, `rgb()`/`rgba()`. */
+function withAlpha(color: string, alpha: number): string {
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())
+  if (hex) {
+    const h = hex[1]!
+    const full = h.length === 3 ? h.replace(/./g, (c) => c + c) : h
+    const n = Number.parseInt(full, 16)
+    return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color.trim())
+  if (rgb) return `rgba(${rgb[1]}, ${rgb[2]}, ${rgb[3]}, ${alpha})`
+  return color
+}
+
+const HTML_ESCAPES: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]!)
+}
+
+interface TooltipRow {
+  name: string
+  color: string
+  value: number | null
+  /** Percent stacking: the row's share of its point's total (0–100). */
+  share?: number
+  /** A muted line right under the row (a comparison's difference). */
+  note?: string
+}
+
+const shareFormat = new Intl.NumberFormat(DEFAULT_LOCALE, { maximumFractionDigits: 1 })
+const formatShare = (share: number) => `${shareFormat.format(share)}%`
+
+/** The tooltip body: a title, then one `● name  value` row per series, then muted one-line `notes` (target, annotation). */
+function tooltipHtml(
+  title: string,
+  rows: readonly TooltipRow[],
+  valueFormatter: (value: number) => string,
+  notes: readonly string[] = [],
+  locale?: string,
+): string {
+  const t = chartText(locale)
+  const lines = rows.map(
+    (row) =>
+      `<div style="display:flex;align-items:center;gap:8px;line-height:20px">` +
+      `<span style="display:inline-block;width:8px;height:8px;border-radius:9999px;background:${escapeHtml(row.color)}"></span>` +
+      `<span style="flex:1;opacity:.8">${escapeHtml(row.name)}</span>` +
+      `<span style="font-weight:600;font-variant-numeric:tabular-nums;margin-left:12px">${
+        row.value === null ? EMPTY_VALUE : escapeHtml(valueFormatter(row.value))
+      }${
+        row.share === undefined ? "" : `<span style="opacity:.6;margin-left:4px">${escapeHtml(t.share(formatShare(row.share)))}</span>`
+      }</span></div>` +
+      (row.note === undefined
+        ? ""
+        : `<div style="padding-left:16px;line-height:18px;font-size:12px;opacity:.7;font-variant-numeric:tabular-nums">${escapeHtml(row.note)}</div>`),
+  )
+  const noteLines = notes.map(
+    (note) => `<div style="margin-top:4px;line-height:18px;font-size:12px;opacity:.7">${escapeHtml(note)}</div>`,
+  )
+  return `<div style="font-weight:500;margin-bottom:4px">${escapeHtml(title)}</div>${lines.join("")}${noteLines.join("")}`
+}
+
+/* ------------------------------------------------- per-bar targets / notes */
+
+/** Default name of the per-bar target marker (legend, tooltip) in `locale`: "Target" / 「目標」. Default the page's locale. */
+function barTargetLabel(locale?: string): string {
+  return chartText(locale).target
+}
+
+/** How far (px) the target marker reaches past each side of its bar. */
+const TARGET_MARKER_OVERHANG = 4
+
 /**
- * FunnelSteps — proportional bars for a conversion funnel. Bars are sized
- * against the first step, so pass the steps in descending order. Set
- * `showConversion` to print the step-to-step rate between them.
+ * The `renderItem` of the per-bar target marker: a 2px tick across the bar. Its length
+ * is the bar's own width as ECharts lays it out (`api.barLayout`, one column — a single
+ * series or a stack) plus a little overhang; without that it falls back to the
+ * category band times `barHalfWidth`.
  */
-import { forwardRef, Fragment, useEffect, useState, type ComponentProps, type KeyboardEvent } from "react"
-import { cva, type VariantProps } from "class-variance-authority"
+function targetMarkerRenderer(horizontalBars: boolean, barCategoryGap: string | number | undefined, color: string | undefined) {
+  type Api = {
+    value(dim: number): number
+    coord(value: number[]): number[]
+    size(value: number[]): number[]
+    barLayout?(opt: { count: number; barCategoryGap?: string | number }): { width: number }[]
+  }
+  return (_params: unknown, api: Api) => {
+    const [x = 0, y = 0] = api.coord([api.value(0), api.value(1)])
+    const band = Math.abs(horizontalBars ? (api.size([0, 1])[1] ?? 0) : (api.size([1, 0])[0] ?? 0))
+    const barWidth = api.barLayout?.({ count: 1, barCategoryGap })?.[0]?.width
+    const length = (barWidth && barWidth > 0 ? barWidth : band * 2 * barHalfWidth(barCategoryGap)) + TARGET_MARKER_OVERHANG * 2
+    return {
+      type: "line",
+      silent: true,
+      shape: horizontalBars
+        ? { x1: x, y1: y - length / 2, x2: x, y2: y + length / 2 }
+        : { x1: x - length / 2, y1: y, x2: x + length / 2, y2: y },
+      style: { stroke: color, lineWidth: 2, lineCap: "butt" },
+    }
+  }
+}
 
-import { cn } from "@squadbase/vantage/ui"
+/**
+ * Each row's target from the `targetKey` column. A missing, non-numeric or
+ * non-positive cell is `null` (no marker for that bar).
+ */
+function barTargetValues(data: readonly Record<string, unknown>[], targetKey: string): (number | null)[] {
+  return data.map((row) => {
+    const value = cellNumber(row[targetKey])
+    return value !== null && value > 0 ? value : null
+  })
+}
+
+/** `value` as a share of `target` in percent; `null` without a value or a positive target. */
+function achievementRate(value: number | null | undefined, target: number | null | undefined): number | null {
+  if (value === null || value === undefined || target === null || target === undefined || !(target > 0)) return null
+  return (value / target) * 100
+}
+
+/** The tooltip line of a bar with a target: 「目標 ¥1,200万（達成率 85.3%）」 / "Target $12M (85.3% achieved)". `null` without a target. */
+function barTargetNote(
+  label: string,
+  value: number | null,
+  target: number | null,
+  valueFormatter: (value: number) => string,
+  locale?: string,
+): string | null {
+  if (target === null) return null
+  const rate = achievementRate(value, target)
+  return `${label} ${valueFormatter(target)}${rate === null ? "" : chartText(locale).targetRate(formatShare(rate))}`
+}
+
+/** Half the width of a bar in category-axis units, from `barCategoryGap` (`"20%"`; a px gap or none → ECharts' 20%). */
+function barHalfWidth(barCategoryGap?: string | number): number {
+  const gap = typeof barCategoryGap === "string" && /^\d+(\.\d+)?%$/.test(barCategoryGap.trim()) ? parseFloat(barCategoryGap) / 100 : 0.2
+  return 0.5 / (1 + gap)
+}
+
+/** An annotation placed on the category axis: positions are indexes into the x labels. */
+interface ResolvedAnnotation {
+  from: number
+  /** Set for a range (`to` after `from`); a single position leaves it out. */
+  to?: number
+  label: string
+}
+
+/**
+ * Place annotations on the x labels by `String(value)` equality. An annotation
+ * whose `at` is not an `index` value is dropped; `to` before `at` swaps them; a
+ * `to` that is unknown or equal to `at` makes it a single position.
+ */
+function resolveAnnotations(
+  annotations: readonly ChartAnnotation[] | undefined,
+  indexValues: readonly unknown[],
+): ResolvedAnnotation[] {
+  if (!annotations?.length) return []
+  const position = new Map<string, number>()
+  indexValues.forEach((value, i) => {
+    const key = String(value ?? "")
+    if (!position.has(key)) position.set(key, i)
+  })
+  const out: ResolvedAnnotation[] = []
+  for (const note of annotations) {
+    const from = position.get(String(note.at))
+    if (from === undefined || !note.label) continue
+    const end = note.to === undefined ? undefined : position.get(String(note.to))
+    if (end === undefined || end === from) out.push({ from, label: note.label })
+    else out.push({ from: Math.min(from, end), to: Math.max(from, end), label: note.label })
+  }
+  return out
+}
+
+/** Gap (px) under which two neighbouring vertical labels (12px text) would print over each other. */
+const ANNOTATION_LABEL_GAP = 16
+/** Assumed spacing (px) between two index positions when the plot's width is unknown. */
+const ANNOTATION_ASSUMED_GAP = 40
+
+/**
+ * Which end of its line each single-position annotation's label sits on. Labels
+ * run along the line; neighbours closer than a label's height alternate between
+ * the top and the bottom end, so they never print over one another. `lines` are
+ * the annotation positions (index units) in any order; the result follows that order.
+ */
+function annotationLabelEnds(lines: readonly number[], pointGap: number | null): ("top" | "bottom")[] {
+  const gap = pointGap ?? ANNOTATION_ASSUMED_GAP
+  const order = lines.map((at, i) => ({ at, i })).sort((a, b) => a.at - b.at || a.i - b.i)
+  const ends: ("top" | "bottom")[] = Array(lines.length).fill("top")
+  for (let k = 1; k < order.length; k++) {
+    const prev = order[k - 1]!
+    const cur = order[k]!
+    if ((cur.at - prev.at) * gap < ANNOTATION_LABEL_GAP) ends[cur.i] = ends[prev.i] === "top" ? "bottom" : "top"
+  }
+  return ends
+}
+
+interface AxisTooltipParam {
+  seriesId?: string
+  seriesName?: string
+  dataIndex?: number
+  color?: unknown
+}
+
+const DIMMED = 0.3
+
+
+/** Series ids. Ours are stable across updates so ECharts can transition them; `__` marks the helpers. */
+const SERIES_ID_PREFIX = "series:"
+const FORECAST_SERIES_ID = "__forecast"
+const PROVISIONAL_SERIES_PREFIX = "__provisional:"
+/** Provisional points are drawn at this opacity (lines, areas, bars). */
+const PROVISIONAL_OPACITY = 0.55
+/** Horizontal bars (one series, not stacked) are painted at this share of the series colour; the highlighted bar is solid. Same tint as BarList. */
+const LIGHT_BAR_ALPHA = 0.7
+const FORECAST_BAND_BASE_ID = "__forecast-band-base"
+const FORECAST_BAND_RANGE_ID = "__forecast-band-range"
+const OVERLAY_SERIES_ID = "__overlay"
+const TARGET_MARKER_SERIES_ID = "__target-marker"
+const TARGET_LEGEND_SERIES_ID = "__target-legend"
+/** A flat tick (8×8 legend box, aspect kept): the per-bar target's legend icon. */
+const TARGET_LEGEND_ICON = "path://M0,0 L100,0 L100,24 L0,24 Z"
+
+/**
+ * The label at the top of a forecast's boundary line: the forecast's name (as in the legend) and an arrow toward the forecast side.
+ * Without a `label`, "Forecast" / 「予測」 in `locale` (default the page's).
+ */
+function forecastBoundaryText(label?: string, locale?: string): string {
+  return `${label ?? chartText(locale).forecast} →`
+}
+
+/** A comparison series: a thin, muted, solid line with no markers (60% of `--muted-foreground`). */
+const COMPARISON_LINE_WIDTH = 1.5
+const COMPARISON_OPACITY = 0.6
+/** Target line: 1px dotted. Forecast: 2px dashed. Different widths *and* patterns, so the two never read as one. */
+const TARGET_LINE_DASH = [2, 3]
+const FORECAST_LINE_DASH = [6, 4]
+/** Legend icons for the two (8×8 box, aspect kept): a row of dots / of dashes in the line's own proportions. */
+const TARGET_DOTTED_ICON = "path://M0,0 L12,0 L12,10 L0,10 Z M30,0 L42,0 L42,10 L30,10 Z M60,0 L72,0 L72,10 L60,10 Z M88,0 L100,0 L100,10 L88,10 Z"
+const FORECAST_DASHED_ICON = "path://M0,0 L42,0 L42,24 L0,24 Z M58,0 L100,0 L100,24 L58,24 Z"
+
+/** The forecast band's fill opacity: on a dark surface it needs more to show against the background. */
+const FORECAST_BAND_ALPHA_LIGHT = 0.15
+const FORECAST_BAND_ALPHA_DARK = 0.22
+
+/** Whether a resolved surface colour (`#rrggbb` / `rgb()`) is dark (relative luminance under 0.4). `false` when it can't be read. */
+function isDarkSurface(color: string | undefined): boolean {
+  if (!color) return false
+  const hex = /^#([0-9a-f]{6})$/i.exec(color.trim())
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color.trim())
+  let channels: number[]
+  if (hex) {
+    const n = Number.parseInt(hex[1]!, 16)
+    channels = [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+  } else if (rgb) channels = [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+  else return false
+  const [r, g, b] = channels.map((c) => {
+    const v = c / 255
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
+  }) as [number, number, number]
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.4
+}
+
+interface AxisExtent {
+  min: number
+  max: number
+}
+
+/** The label of a stack's total (highlight and tooltip) in `locale`: "Total" / 「合計」. Default the page's locale. */
+function stackTotalLabel(locale?: string): string {
+  return chartText(locale).total
+}
+
+/** Per point, the sum of the stacked series; `null` where every series is missing. */
+function stackTotalsOf(values: readonly (readonly (number | null)[])[]): (number | null)[] {
+  const length = Math.max(0, ...values.map((v) => v.length))
+  return Array.from({ length }, (_, i) => {
+    let total: number | null = null
+    for (const series of values) {
+      const v = series[i]
+      if (v !== null && v !== undefined) total = (total ?? 0) + v
+    }
+    return total
+  })
+}
+
+const LEGEND_LINE_HEIGHT = 24
+/** A rough width budget per legend line (px): a narrow card fits about this much. */
+const LEGEND_LINE_BUDGET = 320
+
+/** How many lines the plain legend takes, estimated from its labels (12px text + 8px dot + gaps). */
+function legendLines(items: readonly string[], plotWidth?: number, reserve = 0): number {
+  const width = items.reduce((sum, name) => sum + [...name].length * 12 + 8 + 5 + 16, 0)
+  // A narrow plot has no room for the PNG buttons beside the legend: they move off its line, so no reserve.
+  const narrow = plotWidth !== undefined && plotWidth < NARROW_PLOT_WIDTH
+  const budget = Math.max(80, (plotWidth ? (narrow ? plotWidth : Math.min(LEGEND_LINE_BUDGET, plotWidth)) : LEGEND_LINE_BUDGET) - (narrow ? 0 : reserve))
+  return Math.min(3, Math.max(1, Math.ceil(width / budget)))
+}
+
+/** Width (px) kept free at the legend's right for the PNG action buttons (two 32px buttons + gaps). */
+const ACTIONS_RESERVE = 80
+
+/** Room (px) one time label (`2026年1月`) needs, gap included. */
+const TIME_LABEL_WIDTH = 80
+/** Room (px) one highlight label (`¥6,240万`) needs, gap included. */
+const HIGHLIGHT_LABEL_WIDTH = 96
+
+/** A highlight this close under the target (share of the larger of the two) can reach its label. */
+const TARGET_NEAR_SHARE = 0.12
+/** Under this plot width (px) a target label that would run into the latest value's label is dropped from the line. */
+const TARGET_LABEL_NARROW_WIDTH = 480
+/** A typical value-axis label column (`¥8,000万`), px. */
+const Y_AXIS_ESTIMATE = 72
+/** Breathing room between two labels, px — the estimate is rough. */
+const LABEL_SLACK = 24
+
+/** Rough width (px) of 12px text: full-width characters 12, the rest 7. */
+function estimateTextWidth(text: string): number {
+  let w = 0
+  for (const ch of text) w += /[\u3000-\u9fff\uff00-\uffef]/.test(ch) ? 12 : 7
+  return w
+}
+
+/**
+ * How many intervals a horizontal value axis (a horizontal bar chart's x) can carry in `plot` px
+ * without its tick labels touching: each tick takes the widest of `samples` (the axis' end labels
+ * printed) plus a gap. At least 1, at most 5 (ECharts' default, which it rounds to a tidy step).
+ */
+function valueAxisSplitNumber(plot: number, samples: readonly string[]): number {
+  const widest = samples.reduce((m, t) => Math.max(m, estimateTextWidth(t)), 0)
+  return Math.max(1, Math.min(5, Math.floor(plot / (widest + LABEL_SLACK))))
+}
+
+/** Room (px) above a vertical bar chart's plot for the label of an annotation band. */
+const BAND_LABEL_ROOM = 18
+
+/** The grid's right margin on a line / area chart (px): the last x label hangs past the plot. */
+const LINE_RIGHT_MARGIN = 32
+
+/** Room (px) above the plot for a forecast's boundary label (「予測 →」). */
+const FORECAST_LABEL_ROOM = 18
+
+/**
+ * Which side of the forecast boundary line the flat boundary label reads from: `"left"` starts at the line and runs
+ * over the forecast side; `"right"` ends at the line and runs over the actuals, when the forecast side (the room right
+ * of the line, grid margin included) is narrower than the text, so it never runs off the chart.
+ * `forecastSpan` is `null` when the width is unknown.
+ */
+function forecastLabelAlign(forecastSpan: number | null, text: string = forecastBoundaryText()): "left" | "right" {
+  return forecastSpan !== null && forecastSpan >= estimateTextWidth(text) + 8 ? "left" : "right"
+}
+
+/** ECharts' "nice" tick step for a raw step (1 / 2 / 3 / 5 × 10ⁿ, rounded): the same rule its value axis uses. */
+function niceStep(raw: number): number {
+  if (!(raw > 0) || !Number.isFinite(raw)) return 1
+  const exp10 = 10 ** Math.floor(Math.log10(raw))
+  const f = raw / exp10
+  return (f < 1.5 ? 1 : f < 2.5 ? 2 : f < 4 ? 3 : f < 7 ? 5 : 10) * exp10
+}
+
+/**
+ * The largest tick (by size) a value axis over `[lo, hi]` will carry once ECharts has niced its ends — the number
+ * that decides the unit the ticks read in (`resolveAxisTickFormatter`). `max`, when fixed, is the axis' top as is.
+ */
+function estimateAxisTop(lo: number, hi: number, splitNumber: number, max?: number): number {
+  const top = Math.max(Math.abs(lo), Math.abs(hi))
+  if (!(top > 0)) return 0
+  const step = niceStep((hi - lo) / splitNumber)
+  const niceHi = max !== undefined && max >= hi ? max : Math.ceil(hi / step) * step
+  const niceLo = Math.floor(lo / step) * step
+  return Math.max(Math.abs(niceHi), Math.abs(niceLo))
+}
+
+/** Plot heights (px) under this carry 3 value intervals, not 4–5. */
+const SHORT_PLOT_HEIGHT = 200
+/** Plot heights under this carry 4 value intervals; taller ones 5. */
+const TALL_PLOT_HEIGHT = 300
+/** The plot height assumed when it isn't known (the charts' default `height`). */
+const ASSUMED_PLOT_HEIGHT = 288
+
+/** How many intervals a vertical value axis carries: 3 under 200px of plot height, 4 under 300px, else 5. */
+function valueAxisSplitCount(plotHeight: number = ASSUMED_PLOT_HEIGHT): number {
+  return plotHeight < SHORT_PLOT_HEIGHT ? 3 : plotHeight < TALL_PLOT_HEIGHT ? 4 : 5
+}
+
+/** The grain of time-like x values (`"month"` for `2026-04`), or `null` when they aren't plain years / months / days. */
+function indexGrain(values: readonly unknown[]): PeriodGrain | null {
+  const parsed = parseTimeIndex(values)
+  return parsed ? parsed.granularity : null
+}
+
+/**
+ * The tooltip line under the main series' row when a comparison series is drawn: the arrow, the signed change and the
+ * comparison's name, as `Delta` writes it ("↑ +12.4% vs. same month last year" / "↑ +12.4% 前年同月比"; a minus is U+2212).
+ * "No comparison vs. same month last year" / "比較なし 前年同月比" when either value is missing or the baseline is 0.
+ */
+function comparisonNote(
+  current: number | null,
+  previous: number | null,
+  comparison: Pick<CartesianComparisonConfig, "vs" | "label">,
+  grain?: PeriodGrain,
+  format?: ValueFormat,
+  localeArg?: string,
+): string {
+  const locale = resolveLocale(localeArg)
+  const result = computeComparison(
+    current,
+    comparison.vs === "custom"
+      ? { previous, vs: "custom", label: comparison.label ?? "", grain }
+      : { previous, vs: comparison.vs, label: comparison.label, grain },
+    { locale },
+  )
+  const text = formatChange(result, defaultChangeDisplay(format), locale, format)
+  if (text === null) return `${chartText(locale).noComparison} ${result.label}`
+  const arrow = result.direction === "up" ? "↑" : result.direction === "down" ? "↓" : "→"
+  return `${arrow} ${text.replace(/^-/, "−")} ${result.label}`
+}
+
+/** Bars and areas start at 0: the length / area *is* the value. */
+const zeroBasedMin = (extent: AxisExtent) => Math.min(0, extent.min)
+
+/**
+ * A value axis' `min` / `max` from the limits a caller asked for, so that charts shown side by side can share one scale.
+ * A limit never cuts the data: when the data runs past it, the axis widens to the data (`max(maxValue, data max)`).
+ * `zeroBased` (bars, areas, waterfall): the axis always reaches 0, so a `minValue` above 0 is ignored and only a
+ * negative one (room below 0) takes effect. Without a limit asked for, that edge is `undefined` (ECharts' own choice)
+ * — except a zero-based `min`, which is always given.
+ */
+function valueAxisLimits(
+  limits: { minValue?: number; maxValue?: number },
+  zeroBased: boolean,
+): { min: ((extent: AxisExtent) => number) | undefined; max: ((extent: AxisExtent) => number) | undefined } {
+  const lo = Number.isFinite(limits.minValue) ? limits.minValue : undefined
+  const hi = Number.isFinite(limits.maxValue) ? limits.maxValue : undefined
+  return {
+    min: zeroBased
+      ? (extent) => Math.min(0, lo ?? 0, extent.min)
+      : lo === undefined
+        ? undefined
+        : (extent) => Math.min(lo, extent.min),
+    max: hi === undefined ? undefined : (extent) => Math.max(hi, extent.max),
+  }
+}
+
+function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
+  const {
+    kind,
+    data,
+    index,
+    categories,
+    palette,
+    labels: nameLabels,
+    thresholds,
+    toneColors,
+    valueFormatter,
+    axisFormatter = valueFormatter,
+    type = "default",
+    layout = "horizontal",
+    curveType = "linear",
+    fill = "gradient",
+    connectNulls = false,
+    showLegend = true,
+    showTooltip = true,
+    showGridLines = true,
+    showXAxis = true,
+    showYAxis = true,
+    startEndOnly = false,
+    yAxisWidth,
+    minValue,
+    maxValue,
+    autoMinValue = false,
+    fitToData,
+    allowDecimals = true,
+    xAxisLabel,
+    yAxisLabel,
+    barCategoryGap,
+    showDots = false,
+    active = null,
+    target,
+    targetLabel,
+    targetLabelPosition = "start",
+    targetKey,
+    showZeroValues = true,
+    guideColor,
+    labelBackground,
+    labelColor,
+    plotWidth,
+    plotHeight,
+    reducedMotion = false,
+    chartOptions,
+    reserveActions = false,
+  } = cfg
+  const locale = resolveLocale(cfg.locale)
+  const text = chartText(locale)
+  const provisionalLabel = cfg.provisionalLabel ?? text.provisional
+
+  const stacked = kind !== "line" && type !== "default"
+  const percent = kind !== "line" && type === "percent"
+  const horizontalBars = kind === "bar" && layout === "vertical"
+  /*
+   * -- comparison: a plain line, outside the stack and the palette. Never with bars or a 100% stack
+   * (shares of a total have no "last year" line).
+   */
+  const comparison = kind !== "bar" && !percent ? cfg.comparison : undefined
+  const compIdx = comparison ? categories.indexOf(comparison.category) : -1
+  /** Positions of the series that are not the comparison: the stack, the highlight and the forecast read these. */
+  const mainIdx = categories.map((_, i) => i).filter((i) => i !== compIdx)
+  const seriesType = kind === "line" ? "default" : type
+  const values = (() => {
+    if (compIdx === -1) return cartesianSeriesValues(data, categories, seriesType)
+    const main = cartesianSeriesValues(data, mainIdx.map((i) => categories[i]!), seriesType)
+    const compared = cartesianSeriesValues(data, [categories[compIdx]!], "default")[0]!
+    return categories.map((_, i) => (i === compIdx ? compared : main[mainIdx.indexOf(i)]!))
+  })()
+  const comparisonColor = guideColor ? withAlpha(guideColor, COMPARISON_OPACITY) : undefined
+
+  /* -- x labels: the actual rows, then the forecast rows that extend them */
+  const labels = data.map((row) => String(row[index] ?? ""))
+  const rawIndex: unknown[] = data.map((row) => row[index])
+  const lastActual = labels.length - 1
+  // First provisional point (-1: none). Looked up among the actual rows only; unrelated to `forecast`.
+  const provStart = categories.length > 0 ? provisionalStart(rawIndex, cfg.provisionalFrom) : -1
+  const forecast =
+    kind !== "bar" && !percent && cfg.forecast && cfg.forecast.data.length > 0 && data.length > 0 && categories.length > 0
+      ? cfg.forecast
+      : undefined
+  const forecastAt: number[] = []
+  if (forecast) {
+    const position = new Map(labels.map((label, i) => [label, i]))
+    for (const row of forecast.data) {
+      const label = String(row[index] ?? "")
+      let at = position.get(label)
+      if (at === undefined || at <= lastActual) {
+        // A forecast row never overwrites an actual point; repeated labels append.
+        at = labels.length
+        labels.push(label)
+        rawIndex.push(row[index])
+        position.set(label, at)
+      }
+      forecastAt.push(at)
+    }
+  }
+  const pad = (series: (number | null)[]) =>
+    series.length < labels.length ? [...series, ...Array<null>(labels.length - series.length).fill(null)] : series
+  const last = labels.length - 1
+  /*
+   * -- time-like x values read as dates in the locale (`4月`, `2026年1月`), at a
+   * fixed calendar step so the year-change label is never thinned away.
+   */
+  const timeStep = startEndOnly
+    ? null
+    : timeAxisLabelStep(
+        rawIndex,
+        plotWidth
+          ? Math.max(
+              2,
+              Math.min(
+                plotWidth < NARROW_PLOT_WIDTH ? NARROW_TIME_AXIS_MAX_LABELS : TIME_AXIS_MAX_LABELS,
+                Math.floor(plotWidth / TIME_LABEL_WIDTH),
+              ),
+            )
+          : undefined,
+      )
+  // Plain (non-date) x labels of a line chart: thinned to every n-th so they never touch, never rotated.
+  const plainStep = (() => {
+    if (kind !== "line" || startEndOnly || timeStep !== null || !plotWidth || labels.length < 3) return 1
+    const widest = Math.max(...labels.map((l) => estimateTextWidth(nameLabels && hasLabel(nameLabels, l) ? labelOf(l, nameLabels) : l)))
+    const plot = Math.max(1, plotWidth - (showYAxis ? (yAxisWidth ?? Y_AXIS_ESTIMATE) : 0) - LINE_RIGHT_MARGIN)
+    return Math.max(1, Math.ceil(((widest + 12) * (labels.length - 1)) / plot))
+  })()
+  const shownLabel = startEndOnly
+    ? (i: number) => i === 0 || i === last
+    : timeStep !== null
+      ? (i: number) => i % timeStep === 0
+      : plainStep > 1
+        ? (i: number) => i % plainStep === 0
+        : null
+  const timeLabels = timeAxisLabels(rawIndex, locale, shownLabel ?? undefined)
+  const compGrain = comparison ? (indexGrain(rawIndex.slice(0, lastActual + 1)) ?? undefined) : undefined
+  const tooltipTitles = (timeTooltipLabels(rawIndex, locale) ?? labels).map((title, i) =>
+    nameLabels ? (hasLabel(nameLabels, labels[i] ?? "") ? labelOf(labels[i] ?? "", nameLabels) : title) : title,
+  )
+
+  /*
+   * -- highlight: max + latest. Normal stacking labels the stack's total (on the
+   * top layer); otherwise the first series, ≤ 2 series. A 100% stacked area
+   * labels the first series' (the bottom band's) first and latest share inside
+   * the band; a 100% stacked bar labels nothing.
+   */
+  const highlight = cfg.highlight ?? defaultChartHighlight(kind, data, index)
+  const stackTotals = stacked && !percent ? stackTotalsOf(mainIdx.map((i) => values[i]!)) : null
+  const highlightSeries = (stackTotals ? mainIdx[mainIdx.length - 1] : mainIdx[0]) ?? 0
+  const shareHighlight = percent && kind === "area"
+  const picked =
+    highlight !== "auto" || mainIdx.length === 0 || (percent && !shareHighlight)
+      ? []
+      : shareHighlight
+        ? categories.length <= 2
+          ? pickShareHighlightPoints(values[0] ?? [])
+          : []
+        : stackTotals
+        ? pickHighlightPoints(stackTotals)
+        : mainIdx.length <= 2
+          ? pickHighlightPoints(values[highlightSeries] ?? [])
+          : []
+  // On a narrow plot the max and the latest label would print over each other: keep the latest.
+  const pointGap = plotWidth && labels.length > 1 ? plotWidth / (kind === "bar" ? labels.length : labels.length - 1) : null
+  // By default only the latest value is labelled; an explicit `highlight` keeps its max + latest.
+  const latestOnly = cfg.highlight === undefined && !shareHighlight && picked.length === 2
+  const highlightPoints =
+    latestOnly
+      ? [picked[1]!]
+      : picked.length === 2 && pointGap !== null && Math.abs(picked[1]!.index - picked[0]!.index) * pointGap < HIGHLIGHT_LABEL_WIDTH
+      ? [picked[1]!]
+      : picked
+
+  /*
+   * Points (and the outer bars) sit at the plot's edges: pull the first / last
+   * label inward so it isn't clipped. A label on the forecast boundary sits left
+   * of the boundary line instead of across it.
+   */
+  const boundaryIndex = kind !== "bar" && !percent && cfg.forecast && cfg.forecast.data.length > 0 ? lastActual : -1
+  const edgeAlign = (i: number) =>
+    horizontalBars || labels.length < 2
+      ? undefined
+      : i === boundaryIndex && i !== last
+        ? { align: "right" as const, offset: [-6, 0] }
+        : i === last
+          ? { align: "right" as const, ...(kind === "bar" ? { offset: [8, 0] } : {}) }
+          : i === 0
+            ? { align: "left" as const, ...(kind === "bar" ? { offset: [-8, 0] } : {}) }
+            : undefined
+
+  /*
+   * The target label sits at the plot's start (left), above its line, so it stays clear of the latest value's label at
+   * the right end. Near the label (horizontally, estimated from `plotWidth`) a line / area highlight just under the
+   * target prints below its point, and one just over it moves the target label under the line instead. On a plot
+   * narrower than 480px, when the *latest* point's label would still run into the target label, the target label leaves
+   * the line altogether — the legend names the target.
+   */
+  // `barOptions.targetKey` (a target per bar) takes over from the single `target` line.
+  const perBarTarget = kind === "bar" && Boolean(targetKey)
+  const hasTarget = !perBarTarget && target !== undefined && Number.isFinite(target)
+  const targetText = hasTarget ? (targetLabel ?? `${text.target} ${axisFormatter(target)}`) : ""
+  const highlightText = (value: number) =>
+    shareHighlight ? `${Math.round(value)}%` : `${stackTotals ? `${text.total} ` : ""}${axisFormatter(value)}`
+  /** Whether `p`'s label sits within the target's value band and under the target label (at the right end). */
+  const nearTargetLabel = (p: HighlightPoint, side: "under" | "over") => {
+    if (!hasTarget || !plotWidth || kind === "bar" || labels.length < 2) return false
+    if (side === "under" ? p.value > target : p.value <= target) return false
+    const scale = Math.max(Math.abs(target), ...highlightPoints.map((h) => Math.abs(h.value)))
+    if (scale === 0 || Math.abs(target - p.value) / scale > TARGET_NEAR_SHARE) return false
+    const plot = Math.max(1, plotWidth - (showYAxis ? (yAxisWidth ?? Y_AXIS_ESTIMATE) : 0) - 32)
+    const x = (p.index / (labels.length - 1)) * plot
+    const w = estimateTextWidth(highlightText(p.value)) + 8
+    const align = edgeAlign(p.index)?.align
+    const left = align === "right" ? x - w - 6 : align === "left" ? x : x - w / 2
+    return left < estimateTextWidth(targetText) + 8 + LABEL_SLACK
+  }
+  const hideTargetLabel =
+    (kind === "line" && targetLabelPosition === "legend") ||
+    !shareHighlight &&
+    plotWidth !== undefined &&
+    plotWidth < TARGET_LABEL_NARROW_WIDTH &&
+    highlightPoints.some((p) => p.index === labels.length - 1 && (nearTargetLabel(p, "under") || nearTargetLabel(p, "over")))
+  const below = (p: HighlightPoint) => !shareHighlight && !hideTargetLabel && nearTargetLabel(p, "under")
+  const targetLabelBelow = !shareHighlight && !hideTargetLabel && highlightPoints.some((p) => nearTargetLabel(p, "over"))
+
+  // One series (or a stack, against its total) can be compared to a target; grouped series and 100% stacks cannot.
+  const barTargets: (number | null)[] | null =
+    perBarTarget && targetKey && !percent && (stacked || categories.length === 1) ? barTargetValues(data, targetKey) : null
+  const barTargetName = targetLabel ?? text.target
+  const barTargetColor = labelColor ?? guideColor
+
+  const markPointFor = (c: number, color: string | undefined) =>
+    c === highlightSeries && highlightPoints.length > 0
+      ? {
+          silent: true,
+          symbol: "circle",
+          symbolSize: kind === "bar" ? 0 : 7,
+          itemStyle: { color, borderColor: "transparent" },
+          label: {
+            show: true,
+            position: horizontalBars ? ("right" as const) : ("top" as const),
+            distance: 6,
+            fontSize: 12,
+            fontWeight: 500,
+            color: labelColor,
+            ...(labelBackground ? { backgroundColor: labelBackground, padding: [2, 4], borderRadius: 2 } : {}),
+            formatter: (p: { value?: unknown }) => highlightText(Number(p.value)),
+          },
+          data: highlightPoints.map((p) => {
+            // Below the point; on the forecast boundary, on the forecast side (the actual line comes in from the left).
+            const label = shareHighlight
+              ? // Inside the bottom band, under its upper edge: the label reads as that band's share.
+                { ...edgeAlign(p.index), position: "bottom" as const }
+              : below(p)
+              ? p.index === boundaryIndex && p.index !== last
+                ? { position: "bottom" as const, align: "left" as const, offset: [6, 0] }
+                : { ...edgeAlign(p.index), position: "bottom" as const }
+              : edgeAlign(p.index)
+            return {
+              name: p.kind,
+              value: p.value,
+              coord: horizontalBars ? [p.value, p.index] : [p.index, p.value],
+              ...(label ? { label } : {}),
+            }
+          }),
+        }
+      : undefined
+
+  // Threshold colours: bars side by side (one series or several). A stacked segment is a part, not a level to judge, so stacks keep their series colours.
+  const byValue = kind === "bar" && !stacked && Boolean(thresholds?.length)
+  const multiSeries = categories.length > 1
+  // Horizontal bars of one series read light; only the highlighted bar is solid (the one the page is about).
+  const lightBars = kind === "bar" && horizontalBars && !stacked && !multiSeries
+  const series: Record<string, unknown>[] = categories.map((category, c) => {
+    const solid = palette[c] || undefined
+    const color = lightBars && solid ? withAlpha(solid, LIGHT_BAR_ALPHA) : solid
+    const dimSeries = active !== null && active.category !== category
+    const seriesData = pad(values[c]!)
+    if (kind === "bar") {
+      const rounded = horizontalBars ? [0, 4, 4, 0] : [4, 4, 0, 0]
+      // Stacked: only the topmost segment is rounded.
+      const radius = stacked && c !== categories.length - 1 ? 0 : rounded
+      return {
+        id: SERIES_ID_PREFIX + category,
+        type: "bar" as const,
+        name: category,
+        stack: stacked ? "total" : undefined,
+        barCategoryGap,
+        itemStyle: { color, borderRadius: radius },
+        markPoint: markPointFor(c, solid),
+        markLine: undefined,
+        data: seriesData.map((value, i) => {
+          const tone = byValue ? toneForValue(value, thresholds) : undefined
+          const toneColor = tone ? toneColors?.[tone] || undefined : undefined
+          const isHighlight = lightBars && cfg.barHighlight !== undefined && String(rawIndex[i]) === String(cfg.barHighlight)
+          const dimmed = active !== null && !(active.category === category && active.index === i)
+          // Provisional bars: lighter fill and a dashed edge, never the solid look of a confirmed bar.
+          const provisional = provStart !== -1 && i >= provStart && i <= lastActual
+          const zeroLabel =
+            showZeroValues && !stacked && value === 0
+              ? {
+                  show: true,
+                  position: horizontalBars ? ("right" as const) : ("top" as const),
+                  distance: 4,
+                  fontSize: 12,
+                  color: labelColor,
+                  formatter: () => axisFormatter(0),
+                }
+              : undefined
+          if (!dimmed && !toneColor && !isHighlight && !provisional && !zeroLabel) return value
+          return {
+            value,
+            ...(zeroLabel ? { label: zeroLabel } : {}),
+            itemStyle: {
+              ...(isHighlight && solid ? { color: solid } : {}),
+              ...(toneColor ? { color: toneColor } : {}),
+              // Several series: the series colour stays on the edge so the legend still points at the bar.
+              ...(toneColor && multiSeries && color && !provisional ? { borderColor: color, borderWidth: 2 } : {}),
+              ...(provisional ? { opacity: PROVISIONAL_OPACITY, borderColor: toneColor ?? color, borderWidth: 1, borderType: "dashed" as const } : {}),
+              ...(dimmed ? { opacity: DIMMED } : {}),
+            },
+          }
+        }),
+      }
+    }
+    if (c === compIdx) {
+      // The comparison: thin, muted, solid, no markers, no fill, never stacked — behind the main series.
+      return {
+        id: SERIES_ID_PREFIX + category,
+        type: "line" as const,
+        name: category,
+        z: 1,
+        smooth: curveType === "smooth",
+        step: curveType === "step" ? ("middle" as const) : undefined,
+        connectNulls,
+        symbol: "none",
+        showSymbol: false,
+        lineStyle: { width: COMPARISON_LINE_WIDTH, type: "solid" as const, color: comparisonColor, opacity: dimSeries ? DIMMED : 1 },
+        itemStyle: { color: comparisonColor, opacity: dimSeries ? DIMMED : 1 },
+        areaStyle: undefined,
+        markPoint: undefined,
+        markLine: undefined,
+        data: seriesData,
+      }
+    }
+    const areaStyle =
+      kind !== "area" || fill === "none"
+        ? undefined
+        : fill === "solid" || !color
+          ? { opacity: fill === "solid" ? 0.3 : 0.2 }
+          : {
+              color: {
+                type: "linear" as const,
+                x: 0,
+                y: 0,
+                x2: 0,
+                y2: 1,
+                colorStops: [
+                  { offset: 0, color: withAlpha(color, 0.28) },
+                  { offset: 1, color: withAlpha(color, 0) },
+                ],
+              },
+            }
+    return {
+      id: SERIES_ID_PREFIX + category,
+      type: "line" as const,
+      name: category,
+      stack: stacked ? "total" : undefined,
+      smooth: curveType === "smooth",
+      step: curveType === "step" ? ("middle" as const) : undefined,
+      connectNulls,
+      symbol: "circle",
+      symbolSize: 6,
+      showSymbol: showDots || data.length === 1,
+      // 100% stacked: the top band's upper edge is the 100% line, not a value — drawn, it reads as「this band = 100%」.
+      lineStyle:
+        percent && c === categories.length - 1
+          ? { width: 0, color, opacity: 0 }
+          : { width: 2, color, opacity: dimSeries ? DIMMED : 1 },
+      itemStyle: { color, opacity: dimSeries ? DIMMED : 1 },
+      // Hovering a series fades the others (not for a stack, where the bands read together).
+      emphasis: stacked ? undefined : { focus: "series" as const },
+      areaStyle: areaStyle && dimSeries ? { ...areaStyle, opacity: DIMMED * 0.3 } : areaStyle,
+      markPoint: markPointFor(c, color),
+      markLine: undefined,
+      data: provStart === -1 ? seriesData : splitProvisional(seriesData, provStart).confirmed,
+    }
+  })
+
+  /* -- provisional: a dashed, lighter continuation of every series from `provStart`, joined to the last confirmed point */
+  if (kind !== "bar" && provStart !== -1) {
+    categories.forEach((category, c) => {
+      // The comparison is not provisional: it keeps its own line to the end.
+      if (c === compIdx) return
+      const color = palette[c] || undefined
+      const dimSeries = active !== null && active.category !== category
+      const solid = series[c] as { areaStyle?: { opacity?: number } }
+      const opacity = (dimSeries ? DIMMED : 1) * PROVISIONAL_OPACITY
+      series.push({
+        id: PROVISIONAL_SERIES_PREFIX + category,
+        type: "line" as const,
+        name: provisionalLabel,
+        // Its own stack: the joint point repeats the confirmed value and must not pile onto it.
+        stack: stacked ? "provisional" : undefined,
+        smooth: curveType === "smooth",
+        step: curveType === "step" ? ("middle" as const) : undefined,
+        connectNulls: false,
+        symbol: "circle",
+        symbolSize: 6,
+        showSymbol: showDots || data.length === 1,
+        lineStyle:
+          percent && c === categories.length - 1
+            ? { width: 0, color, opacity: 0 }
+            : { width: 2, type: "dashed" as const, color, opacity },
+        itemStyle: { color, opacity },
+        areaStyle: solid.areaStyle ? { ...solid.areaStyle, opacity: (solid.areaStyle.opacity ?? 1) * PROVISIONAL_OPACITY } : undefined,
+        markPoint: undefined,
+        markLine: undefined,
+        data: splitProvisional(pad(values[c]!), provStart).provisional,
+      })
+    })
+  }
+  // A bar legend entry for the provisional style (an empty line series: it takes no bar slot).
+  if (kind === "bar" && provStart !== -1) {
+    series.push({
+      id: PROVISIONAL_SERIES_PREFIX + "legend",
+      type: "line" as const,
+      name: provisionalLabel,
+      silent: true,
+      symbol: "none",
+      showSymbol: false,
+      tooltip: { show: false },
+      legendHoverLink: false,
+      lineStyle: { opacity: 0 },
+      itemStyle: { color: palette[0] || undefined, opacity: PROVISIONAL_OPACITY },
+      markPoint: undefined,
+      markLine: undefined,
+      data: [],
+    })
+  }
+
+  /* -- forecast: dashed continuation (+ optional band) of one series */
+  const forecastLabel = forecast?.label ?? text.forecast
+  const forecastBandAlpha = isDarkSurface(labelBackground) ? FORECAST_BAND_ALPHA_DARK : FORECAST_BAND_ALPHA_LIGHT
+  const forecastValues: (number | null)[] = []
+  if (forecast) {
+    const category =
+      forecast.category !== undefined && categories.includes(forecast.category) && forecast.category !== comparison?.category
+        ? forecast.category
+        : categories[mainIdx[0] ?? 0]!
+    const c = categories.indexOf(category)
+    const color = palette[c] || undefined
+    const actual = values[c]!
+    let start = -1
+    for (let i = actual.length - 1; i >= 0; i--) {
+      if (actual[i] !== null) {
+        start = i
+        break
+      }
+    }
+    const line: (number | null)[] = Array<null>(labels.length).fill(null)
+    const lower: (number | null)[] = Array<null>(labels.length).fill(null)
+    const range: (number | null)[] = Array<null>(labels.length).fill(null)
+    if (start !== -1) {
+      line[start] = actual[start]!
+      lower[start] = actual[start]!
+      range[start] = 0
+    }
+    let hasBand = false
+    forecast.data.forEach((row: ChartForecastRow, k) => {
+      const at = forecastAt[k]!
+      line[at] = cellNumber(row.value)
+      const lo = cellNumber(row.lower)
+      const hi = cellNumber(row.upper)
+      if (lo !== null && hi !== null) {
+        hasBand = true
+        lower[at] = Math.min(lo, hi)
+        range[at] = Math.abs(hi - lo)
+      }
+    })
+    forecastValues.push(...line)
+    const helper = {
+      type: "line" as const,
+      silent: true,
+      symbol: "none",
+      showSymbol: false,
+      connectNulls: true,
+      tooltip: { show: false },
+      legendHoverLink: false,
+      emphasis: { disabled: true },
+      markPoint: undefined,
+      markLine: undefined,
+    }
+    if (hasBand) {
+      series.push(
+        {
+          ...helper,
+          id: FORECAST_BAND_BASE_ID,
+          name: FORECAST_BAND_BASE_ID,
+          stack: FORECAST_BAND_BASE_ID,
+          lineStyle: { opacity: 0 },
+          areaStyle: undefined,
+          data: lower,
+        },
+        {
+          ...helper,
+          id: FORECAST_BAND_RANGE_ID,
+          name: FORECAST_BAND_RANGE_ID,
+          stack: FORECAST_BAND_BASE_ID,
+          lineStyle: { opacity: 0 },
+          areaStyle: color ? { color: withAlpha(color, forecastBandAlpha), opacity: 1 } : { opacity: forecastBandAlpha },
+          data: range,
+        },
+      )
+    }
+    series.push({
+      ...helper,
+      id: FORECAST_SERIES_ID,
+      name: forecastLabel,
+      silent: false,
+      tooltip: undefined,
+      emphasis: undefined,
+      smooth: curveType === "smooth",
+      // Always dashed (2px, 6-4) and lighter — a forecast must never read as a measurement, nor as the 1px dotted target.
+      lineStyle: { width: 2, type: FORECAST_LINE_DASH, color, opacity: 0.7 },
+      itemStyle: { color, opacity: 0.7 },
+      areaStyle: undefined,
+      data: line,
+    })
+  }
+
+  /* -- overlay: target line, forecast boundary, and the extent that keeps the target on the axis */
+  /**
+   * Horizontal bars: the target line is vertical and its label lies flat above the plot, centred
+   * on the line — unless that would run past the plot's right (or left) edge, e.g. a target near
+   * the axis max on a narrow chart; then it hangs to the line's left (right) instead. The axis max
+   * is estimated from the data (ECharts rounds it up, which only moves the line left of the guess).
+   */
+  const horizontalTargetAlign = ((): "left" | "center" | "right" => {
+    if (!horizontalBars || !hasTarget) return "center"
+    const totals = labels.map((_, i) =>
+      stacked
+        ? values.reduce((sum, v) => sum + Math.max(0, v[i] ?? 0), 0)
+        : Math.max(0, ...values.map((v) => v[i] ?? 0)),
+    )
+    const top = percent ? 100 : (maxValue ?? Math.max(target, ...totals))
+    if (!(top > 0)) return "center"
+    const ratio = Math.min(1, Math.max(0, target / top))
+    const half = (estimateTextWidth(targetText) + 8) / 2
+    if (!plotWidth) return ratio > 0.85 ? "right" : ratio < 0.15 ? "left" : "center"
+    const right = highlightPoints.length > 0 ? 64 : 16
+    const categoryColumn = showYAxis ? (yAxisWidth ?? Math.min(160, Math.max(0, ...labels.map(estimateTextWidth)))) + 8 : 0
+    const plot = Math.max(1, plotWidth - categoryColumn - right - 4)
+    const at = ratio * plot
+    if (plot - at + right < half) return "right"
+    if (at + categoryColumn < half) return "left"
+    return "center"
+  })()
+  const markLines: unknown[] = []
+  const markAreas: unknown[] = []
+  if (hasTarget && target !== undefined) {
+    markLines.push({
+      name: "target",
+      [horizontalBars ? "xAxis" : "yAxis"]: target,
+      // 1px dotted — the forecast is 2px dashed, so the two never read as one line.
+      lineStyle: { type: TARGET_LINE_DASH, width: 1, color: guideColor },
+      label: {
+        show: !hideTargetLabel,
+        // The start (left) of the line, above it — under it when a highlight sits just above the target there.
+        // Horizontal bars: the line is vertical, so the label goes flat above its top end, outside the plot (no rotation, clear of the bars).
+        // The category axis is inverted there (first row on top), so the line runs top → bottom and its top end is the *start*.
+        position: horizontalBars
+          ? "start"
+          : kind === "line" && targetLabelPosition === "end"
+            ? "insideEndTop"
+            : targetLabelBelow
+              ? "insideStartBottom"
+              : "insideStartTop",
+        ...(horizontalBars ? { rotate: 0, align: horizontalTargetAlign, verticalAlign: "bottom" as const, distance: 4 } : {}),
+        color: guideColor,
+        formatter: targetText,
+      },
+    })
+  }
+  if (forecast) {
+    const forecastSpan =
+      plotWidth && labels.length > 1
+        ? (Math.max(1, plotWidth - (showYAxis ? (yAxisWidth ?? Y_AXIS_ESTIMATE) : 0) - LINE_RIGHT_MARGIN) / (labels.length - 1)) *
+            (labels.length - 1 - lastActual) +
+          LINE_RIGHT_MARGIN
+        : null
+    markLines.push({
+      name: "forecast-boundary",
+      xAxis: lastActual,
+      lineStyle: { type: "dashed", width: 1, color: guideColor },
+      // Flat (text-xs, muted), just above the plot's top edge at the top of the line (`grid.top` makes the room; the legend
+      // sits above that): along the line at its foot it ran into the x axis labels on a narrow chart.
+      label: {
+        show: true,
+        position: "end",
+        rotate: 0,
+        align: forecastLabelAlign(forecastSpan, forecastBoundaryText(forecastLabel)),
+        verticalAlign: "bottom" as const,
+        distance: 4,
+        fontSize: 12,
+        color: guideColor,
+        formatter: forecastBoundaryText(forecastLabel),
+      },
+    })
+  }
+  /* -- annotations: a thin neutral line, or a faint band for a range, on the category axis (vertical layouts only) */
+  const notes = horizontalBars ? [] : resolveAnnotations(cfg.annotations, rawIndex)
+  const noteGap = plotWidth && labels.length > 1 ? plotWidth / (kind === "bar" ? labels.length : labels.length - 1) : null
+  if (notes.length > 0) {
+    const singles = notes.filter((n) => n.to === undefined)
+    const ends = annotationLabelEnds(singles.map((n) => n.from), noteGap)
+    const background = labelBackground ? { backgroundColor: labelBackground, padding: [1, 3], borderRadius: 2 } : {}
+    singles.forEach((note, k) => {
+      markLines.push({
+        name: `annotation:${note.label}`,
+        xAxis: note.from,
+        lineStyle: { type: "solid", width: 1, color: guideColor },
+        // Along the line, at the top (the legend sits above the plot) or at its foot when a neighbour is close.
+        label: {
+          show: true,
+          position: ends[k] === "top" ? "insideEndTop" : "insideStartBottom",
+          color: guideColor,
+          ...background,
+          formatter: note.label,
+        },
+      })
+    })
+    const over = kind === "bar" ? 0.5 : 0
+    for (const note of notes) {
+      if (note.to === undefined) continue
+      const widthPx = noteGap === null ? null : (note.to - note.from + (kind === "bar" ? 1 : 0)) * noteGap
+      const fits = widthPx === null ? [...note.label].length <= 6 : estimateTextWidth(note.label) + 8 <= widthPx
+      markAreas.push([
+        {
+          name: note.label,
+          xAxis: note.from - over,
+          itemStyle: { color: guideColor ? withAlpha(guideColor, 0.12) : undefined },
+          // The band's foot (bars: just above the plot — inside, the text would run into the value label of a tall bar,
+          // and `grid.top` makes the room); a band narrower than its text reads the text upright along the band instead.
+          label: {
+            show: true,
+            position: kind === "bar" ? "top" : fits ? "insideBottom" : "inside",
+            rotate: fits ? 0 : 90,
+            color: guideColor,
+            fontSize: 12,
+            formatter: note.label,
+          },
+        },
+        { xAxis: note.to + over },
+      ])
+    }
+  }
+  // The target is a legend entry too (an empty line series carries the name): the line may lose its label on a narrow plot.
+  if (hasTarget) {
+    series.push({
+      id: TARGET_LEGEND_SERIES_ID,
+      type: "line" as const,
+      name: targetText,
+      silent: true,
+      symbol: "none",
+      showSymbol: false,
+      tooltip: { show: false },
+      legendHoverLink: false,
+      emphasis: { disabled: true },
+      lineStyle: { opacity: 0 },
+      itemStyle: { color: guideColor },
+      markPoint: undefined,
+      markLine: undefined,
+      data: [],
+    })
+  }
+  if (markLines.length > 0 || markAreas.length > 0) {
+    series.push({
+      id: OVERLAY_SERIES_ID,
+      name: OVERLAY_SERIES_ID,
+      type: "line" as const,
+      silent: true,
+      symbol: "none",
+      showSymbol: false,
+      tooltip: { show: false },
+      legendHoverLink: false,
+      emphasis: { disabled: true },
+      lineStyle: { opacity: 0 },
+      itemStyle: { color: guideColor },
+      // A single invisible point at the target, so the value axis always reaches it.
+      data: labels.map((_, i) => (i === 0 && hasTarget && target !== undefined ? target : null)),
+      markPoint: undefined,
+      // `precision`: ECharts rounds a mark line's value to 2 decimals by default (a 0.035 target would land on 0.04 — off a fitted axis,
+      // where the line is then dropped). `z` keeps the guide lines above the series' own lines.
+      markLine: markLines.length > 0 ? { silent: true, symbol: "none", animation: false, precision: 20, z: 6, data: markLines } : undefined,
+      markArea: markAreas.length > 0 ? { silent: true, animation: false, data: markAreas } : undefined,
+    })
+  }
+  /*
+   * -- per-bar targets: a short marker across each bar at its target. A custom
+   * series (the marker's length follows the bar's width, in px, whatever the chart's
+   * size) whose data also keeps the value axis reaching the largest target. It is
+   * the legend's entry too: the marker is named, with a tick as its icon.
+   */
+  if (barTargets) {
+    series.push({
+      id: TARGET_MARKER_SERIES_ID,
+      type: "custom" as const,
+      name: barTargetName,
+      silent: true,
+      animation: false,
+      z: 5,
+      tooltip: { show: false },
+      legendHoverLink: false,
+      emphasis: { disabled: true },
+      itemStyle: { color: barTargetColor },
+      encode: { x: 0, y: 1 },
+      data: barTargets.flatMap((value, i) => (value === null ? [] : [horizontalBars ? [value, i] : [i, value]])),
+      renderItem: targetMarkerRenderer(horizontalBars, barCategoryGap, barTargetColor),
+    })
+  }
+
+  const categoryAxis = {
+    id: horizontalBars ? "y" : "x",
+    type: "category" as const,
+    data: labels,
+    show: horizontalBars ? showYAxis : showXAxis,
+    boundaryGap: kind === "bar",
+    inverse: horizontalBars,
+    axisTick: { show: false },
+    axisLabel: {
+      hideOverlap: true,
+      rotate: kind === "line" ? 0 : undefined,
+      interval: shownLabel ?? ("auto" as const),
+      formatter:
+        timeLabels || nameLabels
+          ? (value: string, i: number) => {
+              const time = timeLabels?.[i]
+              if (time === "") return ""
+              return hasLabel(nameLabels, value) ? labelOf(value, nameLabels) : (time ?? value)
+            }
+          : undefined,
+      width: horizontalBars ? yAxisWidth : undefined,
+      overflow: horizontalBars && yAxisWidth != null ? ("truncate" as const) : undefined,
+    },
+    name: horizontalBars ? yAxisLabel : xAxisLabel,
+    nameLocation: "middle" as const,
+    nameGap: horizontalBars ? (yAxisWidth ?? 48) + 8 : 28,
+  }
+  const fit = kind === "line" && (fitToData ?? autoMinValue)
+  // A horizontal bar chart's value ticks run along the (narrow) width: as many as fit side by side.
+  const valueSplitNumber = (() => {
+    if (!horizontalBars || !plotWidth) return undefined
+    const top = percent
+      ? 100
+      : (maxValue ?? Math.max(0, ...(stacked ? stackTotalsOf(values) : values.flat()).map((v) => v ?? 0)))
+    const categoryColumn = showYAxis ? (yAxisWidth ?? Math.min(160, Math.max(0, ...labels.map(estimateTextWidth)))) + 8 : 0
+    const plot = plotWidth - categoryColumn - (highlightPoints.length > 0 ? 64 : 16) - 4
+    const text = percent ? (v: number) => `${v}%` : (v: number) => axisFormatter(v)
+    return valueAxisSplitNumber(plot, [text(0), text(top)])
+  })()
+  const limits = valueAxisLimits({ minValue, maxValue }, kind !== "line")
+  // Vertical value axes carry 3 intervals on a short plot, else 4–5 (a horizontal bar chart's follows its width, above).
+  const splitNumber = horizontalBars ? valueSplitNumber : valueAxisSplitCount(plotHeight)
+  /*
+   * Ticks read in one unit — the unit of the axis' largest tick (¥0.5億 / ¥1億, never ¥5,000万 beside ¥1億). The largest
+   * tick is estimated from the data the way ECharts nices its ends.
+   */
+  const tickFormatter = (() => {
+    if (!cfg.axisTicks || percent) return axisFormatter
+    const extentValues: number[] = []
+    const addAll = (list: readonly (number | null)[]) => {
+      for (const v of list) if (v !== null && Number.isFinite(v)) extentValues.push(v)
+    }
+    if (stackTotals) addAll(stackTotals)
+    else values.forEach(addAll)
+    addAll(forecastValues)
+    if (forecast) addAll(forecast.data.flatMap((row) => [cellNumber(row.lower), cellNumber(row.upper)]))
+    if (barTargets) addAll(barTargets)
+    if (hasTarget && target !== undefined) extentValues.push(target)
+    if (maxValue !== undefined && Number.isFinite(maxValue)) extentValues.push(maxValue)
+    if (minValue !== undefined && Number.isFinite(minValue)) extentValues.push(minValue)
+    if (extentValues.length === 0) return axisFormatter
+    const zeroBased = kind !== "line" || !fit
+    const hi = Math.max(...extentValues, zeroBased ? 0 : -Infinity)
+    const lo = Math.min(...extentValues, zeroBased ? 0 : Infinity)
+    return cfg.axisTicks(estimateAxisTop(lo, hi, splitNumber ?? 5, maxValue !== undefined && Number.isFinite(maxValue) ? maxValue : undefined))
+  })()
+  const valueAxis = {
+    id: horizontalBars ? "x" : "y",
+    type: "value" as const,
+    show: horizontalBars ? showXAxis : showYAxis,
+    // Bars and areas always start at 0 (a positive `minValue` can't lift them, a negative one makes room below);
+    // lines do too unless asked to fit the data. A limit never cuts the data: the axis widens to it.
+    min: percent ? 0 : kind === "line" ? (minValue === undefined ? (fit ? undefined : zeroBasedMin) : limits.min) : limits.min,
+    max: percent ? 100 : limits.max,
+    scale: fit && minValue == null,
+    splitNumber,
+    minInterval: allowDecimals ? undefined : 1,
+    axisLine: { show: false },
+    axisTick: { show: false },
+    splitLine: { show: showGridLines },
+    axisLabel: {
+      formatter: percent ? (v: number) => `${v}%` : (v: number) => tickFormatter(v),
+      // Fitted to the data: the lowest tick would print over the first x label at the bottom left. The gridline stays.
+      showMinLabel: fit && minValue == null && !horizontalBars ? false : undefined,
+      // Horizontal: ticks that would still touch on a narrow plot are dropped.
+      hideOverlap: horizontalBars ? true : undefined,
+      // A fixed width lines up side-by-side plots, but a value tick is never cut: the grid contains it.
+      width: horizontalBars ? undefined : yAxisWidth,
+    },
+    name: horizontalBars ? xAxisLabel : yAxisLabel,
+    nameLocation: "middle" as const,
+    nameGap: horizontalBars ? 28 : (yAxisWidth ?? 48) + 8,
+  }
+
+  const legendItems = [
+    ...categories,
+    ...(forecast ? [forecastLabel] : []),
+    ...(provStart !== -1 ? [provisionalLabel] : []),
+    ...(barTargets ? [barTargetName] : []),
+    ...(hasTarget ? [targetText] : []),
+  ]
+  const option = {
+    ...chartMotion(reducedMotion),
+    legend: {
+      show: showLegend,
+      top: 0,
+      // Narrow: left-aligned and wrapping above the plot, so nothing is cut off at the right edge.
+      ...(plotWidth !== undefined && plotWidth < NARROW_PLOT_WIDTH
+        ? { left: 0, right: 0 }
+        : { right: reserveActions ? ACTIONS_RESERVE : 0 }),
+      // Plain wraps onto a second line at narrow widths instead of hiding items behind arrows.
+      type: "plain",
+      icon: "circle",
+      itemWidth: 8,
+      itemHeight: 8,
+      itemGap: 16,
+      // The target marker is a tick, not a dot.
+      // The target is a row of dots and the forecast a row of dashes — their lines' patterns — and a per-bar target a tick.
+      data: legendItems.map((name) =>
+        barTargets && name === barTargetName
+          ? { name, icon: TARGET_LEGEND_ICON }
+          : forecast && name === forecastLabel
+            ? { name, icon: FORECAST_DASHED_ICON }
+            : hasTarget && name === targetText
+              ? { name, icon: TARGET_DOTTED_ICON }
+              : name,
+      ),
+      formatter: nameLabels ? (name: string) => labelOf(name, nameLabels) : undefined,
+    },
+    grid: {
+      top:
+        (showLegend ? 12 + LEGEND_LINE_HEIGHT * legendLines(legendItems, plotWidth, reserveActions ? ACTIONS_RESERVE : 0) : 12) +
+        // The flat target label of a horizontal bar chart sits above the plot.
+        (horizontalBars && hasTarget ? 18 : 0) +
+        // The label of a band over bars sits above the plot's top edge.
+        (kind === "bar" && notes.some((n) => n.to !== undefined) ? BAND_LABEL_ROOM : 0) +
+        // The boundary label of a forecast sits above the plot's top edge too.
+        (forecast ? FORECAST_LABEL_ROOM : 0),
+      // Lines start and end on the outermost ticks, so the last x label (and an edge
+      // highlight) hangs past the plot; a horizontal bar's highlight sits past its end.
+      right: horizontalBars ? (highlightPoints.length > 0 ? 64 : 16) : kind === "bar" ? 16 : LINE_RIGHT_MARGIN,
+      bottom: xAxisLabel ? 24 : 4,
+      left: yAxisLabel ? 24 : 4,
+      containLabel: true,
+    },
+    tooltip: {
+      show: showTooltip,
+      trigger: "axis",
+      axisPointer: { type: kind === "bar" ? "shadow" : "line" },
+      formatter: (params: unknown) => {
+        const list = (Array.isArray(params) ? params : [params]) as AxisTooltipParam[]
+        const i = list[0]?.dataIndex ?? 0
+        const row = i <= lastActual ? (data[i] ?? {}) : {}
+        const rows: TooltipRow[] = []
+        // The main series' difference from the comparison: one muted line under its row.
+        const primary = mainIdx[0]
+        const noteFor = (at: number): { note?: string } => {
+          if (!comparison || compIdx === -1 || at !== primary || i > lastActual) return {}
+          return {
+            note: comparisonNote(
+              cellNumber(row[categories[at]!]),
+              cellNumber(row[comparison.category]),
+              comparison,
+              compGrain,
+              cfg.comparisonFormat,
+              locale,
+            ),
+          }
+        }
+        const shares = percent ? cartesianSeriesValues(i <= lastActual ? [row] : [], categories, "percent") : null
+        // Rows follow the legend order (categories first), not ECharts' own series order.
+        const legendRank = (p: AxisTooltipParam) => {
+          const at = categories.indexOf(p.seriesName ?? "")
+          return at === -1 ? categories.length : at
+        }
+        for (const p of [...list].sort((a, b) => legendRank(a) - legendRank(b))) {
+          const color = typeof p.color === "string" ? p.color : "currentColor"
+          if (p.seriesId === FORECAST_SERIES_ID) {
+            // At and before the boundary the forecast repeats the actual value.
+            if (i > lastActual) rows.push({ name: p.seriesName ?? forecastLabel, color, value: forecastValues[i] ?? null })
+            continue
+          }
+          if (p.seriesId?.startsWith("__")) continue
+          if (i > lastActual) continue
+          const name = p.seriesName ?? ""
+          const at = categories.indexOf(name)
+          const share = shares && at !== -1 ? (shares[at]![0] ?? undefined) : undefined
+          rows.push({
+            name: labelOf(name, nameLabels),
+            color: at === compIdx ? (comparisonColor ?? color) : color,
+            value: cellNumber(row[name]),
+            ...(share !== undefined ? { share } : {}),
+            ...(at !== -1 ? noteFor(at) : {}),
+          })
+        }
+        if (stackTotals && i <= lastActual && rows.length > 1) {
+          rows.push({ name: text.total, color: "transparent", value: stackTotals[i] ?? null })
+        }
+        const provisional = provStart !== -1 && i >= provStart && i <= lastActual
+        if (provisional) {
+          // The confirmed series are empty here: rows come from the data, under a 「速報」 title.
+          rows.length = 0
+          categories.forEach((name, at) => {
+            const share = shares ? (shares[at]![0] ?? undefined) : undefined
+            rows.push({
+              name,
+              color: at === compIdx ? (comparisonColor ?? "currentColor") : palette[at] || "currentColor",
+              value: cellNumber(row[name]),
+              ...(share !== undefined ? { share } : {}),
+              ...noteFor(at),
+            })
+          })
+          if (stackTotals && rows.length > 1) rows.push({ name: text.total, color: "transparent", value: stackTotals[i] ?? null })
+        }
+        const title = tooltipTitles[i] ?? labels[i] ?? ""
+        const lines: string[] = []
+        if (barTargets && i <= lastActual) {
+          const total = stackTotals ? (stackTotals[i] ?? null) : (values[0]?.[i] ?? null)
+          const note = barTargetNote(barTargetName, total, barTargets[i] ?? null, valueFormatter, locale)
+          if (note) lines.push(note)
+        }
+        for (const note of notes) {
+          if (note.to === undefined ? note.from === i : note.from <= i && i <= note.to) lines.push(note.label)
+        }
+        return tooltipHtml(provisional ? text.provisionalTitle(title, provisionalLabel) : title, rows, valueFormatter, lines, locale)
+      },
+    },
+    xAxis: horizontalBars ? valueAxis : categoryAxis,
+    yAxis: horizontalBars ? categoryAxis : valueAxis,
+    series,
+  }
+  return mergeChartOptions(option as EChartsOption, chartOptions)
+}
+
+/* ------------------------------------------------------------------ donut */
+
+type DonutVariant = "donut" | "pie"
+
+/** What the donut prints in its hole (`donutOptions.centerLabel`). */
+type DonutCenterLabel = "none" | "total" | "top"
+
+/**
+ * The center of the donut as one of the three built-ins or a custom node.
+ * Default `"none"`; the legacy `showLabel` (`false` → none, an explicit `true` →
+ * total, the old default) and `label` (a custom node) still win over the default.
+ */
+function resolveDonutCenter(
+  centerLabel: DonutChartOptions["centerLabel"],
+  { showLabel, label }: { showLabel?: boolean; label?: ReactNode } = {},
+): { kind: DonutCenterLabel } | { kind: "custom"; node: ReactNode } {
+  if (showLabel === false) return { kind: "none" }
+  if (centerLabel === "none") return { kind: "none" }
+  if (centerLabel === "total") return { kind: "total" }
+  if (centerLabel === "top") return { kind: "top" }
+  if (centerLabel !== undefined && centerLabel !== null && centerLabel !== false) return { kind: "custom", node: centerLabel }
+  if (label !== undefined && label !== null && label !== false) return { kind: "custom", node: label }
+  return { kind: showLabel === true ? "total" : "none" }
+}
+
+/** Below this plot width (px) the outside labels can't fit beside the ring. */
+const DONUT_OUTSIDE_LABEL_MIN_WIDTH = 440
+
+/**
+ * How many slices get an outside label. A share is printed once: the legend
+ * carries every slice's share, so with a legend there are no outside labels;
+ * without one the 2 largest are labelled when the plot is wide enough
+ * (`plotWidth` `null` = not measured yet → labelled).
+ */
+function donutOutsideLabelCount(plotWidth: number | null, showLegend: boolean): number {
+  if (showLegend) return 0
+  return plotWidth !== null && plotWidth < DONUT_OUTSIDE_LABEL_MIN_WIDTH ? 0 : DONUT_OUTSIDE_LABELS
+}
+
+/** The `"top"` center: the largest real slice's name (`label`) and share (`amount`); `null` when there is none. */
+function donutTopText(
+  slices: readonly DonutOptionSlice[],
+  labels?: Readonly<Record<string, string>>,
+): { label: string; amount: string } | null {
+  const total = slices.reduce((sum, s) => sum + sliceValue(s.value), 0)
+  const top = [...slices].filter((s) => !s.isOther && sliceValue(s.value) > 0).sort((a, b) => sliceValue(b.value) - sliceValue(a.value))[0]
+  return top ? { label: labelOf(top.name, labels), amount: donutShareText(top.value, total) } : null
+}
+
+/** 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
+}
+
+/** A slice as the builder takes it: already sorted, folded and coloured (see `donutSlices`). */
+interface DonutOptionSlice {
+  name: string
+  value: number
+  /** The folded「その他」slice: never labelled outside. */
+  isOther?: boolean
+}
+
+/** How many of the largest slices get an outside label (「自然検索 41%」) by default. */
+const DONUT_OUTSIDE_LABELS = 2
+
+const sliceValue = (value: number) => (Number.isFinite(value) && value > 0 ? value : 0)
+
+/** A slice's share of `total` as text: whole percent, `<1%` for a sliver, `0%` for nothing. */
+function donutShareText(value: number, total: number): string {
+  const v = sliceValue(value)
+  if (total <= 0 || v === 0) return "0%"
+  const pct = (v / total) * 100
+  return pct < 1 ? "<1%" : `${Math.round(pct)}%`
+}
+
+/** One legend row: name, share text and the slice's position (for its colour). */
+interface DonutLegendItem {
+  name: string
+  value: number
+  share: string
+  isOther: boolean
+  /** Index into the slices / palette. */
+  slice: number
+}
+
+/**
+ * The donut legend: every slice with its share, largest first, the folded
+ * 「その他」 last (it is a remainder, not a rank).
+ */
+function donutLegendItems(slices: readonly DonutOptionSlice[]): DonutLegendItem[] {
+  const total = slices.reduce((sum, s) => sum + sliceValue(s.value), 0)
+  return slices
+    .map((s, slice) => ({ name: s.name, value: sliceValue(s.value), share: donutShareText(s.value, total), isOther: Boolean(s.isOther), slice }))
+    .sort((a, b) => Number(a.isOther) - Number(b.isOther) || b.value - a.value || a.slice - b.slice)
+}
+
+/**
+ * The default center label: what is totalled (「合計」 / "Total" in `locale`, default the page's), the formatted total
+ * (`amount`, the big line), the unit (a small line under it) and both as one
+ * string (`value`, 「9.2万 セッション」).
+ */
+function donutCenterText(
+  total: number,
+  valueFormatter: (value: number) => string,
+  { totalLabel, unit, locale }: { totalLabel?: string; unit?: string; locale?: string } = {},
+): { label: string; value: string; amount: string; unit?: string } {
+  totalLabel ??= chartText(locale).total
+  const amount = valueFormatter(total)
+  return { label: totalLabel, value: unit ? `${amount} ${unit}` : amount, amount, ...(unit ? { unit } : {}) }
+}
+
+/** The ring's inner radius, in percent of the plot's shorter side / 2 — with and without outside labels. */
+const DONUT_INNER_WITH_LABELS = 50
+const DONUT_INNER_PLAIN = 72
+
+/**
+ * The hole's diameter as a fraction of the plot's shorter side (ECharts reads a
+ * `%` radius against half of it), so an HTML center label can be sized to fit.
+ */
+function donutHoleRatio(withOutsideLabels: boolean): number {
+  return (withOutsideLabels ? DONUT_INNER_WITH_LABELS : DONUT_INNER_PLAIN) / 100
+}
+
+interface DonutChartConfig {
+  /** Slices in draw order (largest first, 「その他」 last). */
+  slices: readonly DonutOptionSlice[]
+  /** Resolved slice colours, by slice position. `""`/missing → theme palette. */
+  palette: readonly string[]
+  /** Display names for slice names (tooltip, outside labels). Missing keys show as they are. */
+  labels?: Readonly<Record<string, string>>
+  valueFormatter: (value: number) => string
+  /** The value column's name, shown in the tooltip row. */
+  valueName?: string
+  variant?: DonutVariant
+  showTooltip?: boolean
+  /** How many of the largest (non-「その他」) slices get an outside label. Default `DONUT_OUTSIDE_LABELS` (2); 0 = none. */
+  outsideLabels?: number
+  /** Name of the selected slice; the others are dimmed. */
+  active?: string | null
+  /** Colour of the outside labels (resolved foreground). Default: the theme's text colour. */
+  labelColor?: string
+  reducedMotion?: boolean
+  /** Deep-merged onto the generated option last. */
+  chartOptions?: EChartsOption
+}
+
+/** Sum of the `value` column, ignoring gaps and negative cells. */
+function donutTotal(data: readonly Record<string, unknown>[], value: string): number {
+  return data.reduce((sum, row) => {
+    const n = cellNumber(row[value])
+    return n !== null && n > 0 ? sum + n : sum
+  }, 0)
+}
+
+interface ItemTooltipParam {
+  name?: string
+  value?: unknown
+  percent?: number
+  color?: unknown
+}
+
+/**
+ * The donut / pie option. Only the `outsideLabels` largest slices carry an
+ * outside label (name + share); the legend, center label and tooltip carry the
+ * rest. No entrance animation, a short ease on updates.
+ */
+function buildDonutOption(cfg: DonutChartConfig): EChartsOption {
+  const {
+    slices,
+    palette,
+    labels: nameLabels,
+    valueFormatter,
+    valueName = "",
+    variant = "donut",
+    showTooltip = true,
+    outsideLabels = DONUT_OUTSIDE_LABELS,
+    active = null,
+    labelColor,
+    reducedMotion = false,
+    chartOptions,
+  } = cfg
+  const total = slices.reduce((sum, s) => sum + sliceValue(s.value), 0)
+  // The largest real slices, by value (the slices arrive sorted, but don't rely on it).
+  const labelled = new Set(
+    slices
+      .map((s, i) => ({ i, v: sliceValue(s.value), other: Boolean(s.isOther) }))
+      .filter((s) => !s.other && s.v > 0)
+      .sort((a, b) => b.v - a.v || a.i - b.i)
+      .slice(0, Math.max(0, outsideLabels))
+      .map((s) => s.i),
+  )
+  const withLabels = labelled.size > 0
+  // Room for the outside labels: the ring shrinks inside the plot.
+  const outer = withLabels ? "70%" : "100%"
+  const option = {
+    ...chartMotion(reducedMotion),
+    tooltip: {
+      show: showTooltip,
+      trigger: "item",
+      formatter: (params: unknown) => {
+        const p = params as ItemTooltipParam
+        const n = cellNumber(p.value)
+        const share = typeof p.percent === "number" ? ` (${p.percent.toFixed(1)}%)` : ""
+        return tooltipHtml(
+          `${labelOf(p.name ?? "", nameLabels)}${share}`,
+          [{ name: valueName, color: typeof p.color === "string" ? p.color : "currentColor", value: n }],
+          valueFormatter,
+        )
+      },
+    },
+    series: [
+      {
+        id: "slices",
+        type: "pie",
+        radius: variant === "donut" ? [`${donutHoleRatio(withLabels) * 100}%`, outer] : [0, outer],
+        center: ["50%", "50%"],
+        avoidLabelOverlap: true,
+        // Plain text: no outline / shadow, which reads as a halo on a dark surface.
+        label: {
+          show: false,
+          position: "outside",
+          color: labelColor,
+          textBorderWidth: 0,
+          textBorderColor: "transparent",
+          textShadowBlur: 0,
+          textShadowColor: "transparent",
+        },
+        labelLine: { show: false, length: 8, length2: 8 },
+        // A hairline gap between slices instead of a border — no background colour to match.
+        padAngle: slices.length > 1 ? 1 : 0,
+        itemStyle: { borderRadius: variant === "donut" ? 2 : 0 },
+        emphasis: { scale: true, scaleSize: 4 },
+        data: slices.map((slice, i) => ({
+          name: slice.name,
+          value: sliceValue(slice.value),
+          itemStyle: { color: palette[i] || undefined, opacity: active !== null && active !== slice.name ? DIMMED : 1 },
+          ...(labelled.has(i)
+            ? {
+                label: { show: true, formatter: () => `${labelOf(slice.name, nameLabels)} ${donutShareText(slice.value, total)}` },
+                labelLine: { show: true },
+              }
+            : {}),
+        })),
+      },
+    ],
+  }
+  return mergeChartOptions(option as EChartsOption, chartOptions)
+}
+
+/* -------------------------------------------------------------- selection */
+
+/** Toggle: clicking the active point again clears the selection. */
+function nextChartSelection(
+  current: ChartActivePoint | null,
+  category: string,
+  index: number,
+): ChartActivePoint | null {
+  return current && current.category === category && current.index === index ? null : { category, index }
+}
+
+/** What `onValueChange` receives: the clicked row plus what was clicked (ours win over row keys). */
+function chartSelectionPayload(
+  selection: ChartActivePoint | null,
+  data: readonly Record<string, unknown>[],
+  eventType: NonNullable<ChartEventPayload>["eventType"],
+): ChartEventPayload {
+  if (!selection) return null
+  return { ...data[selection.index], eventType, categoryClicked: selection.category }
+}
+
+interface ChartClickParams {
+  componentType?: string
+  seriesName?: string
+  name?: string
+  dataIndex?: number
+}
+
+/**
+ * Click-to-select for the typed charts: the `onEvents` to hand `EChart`, and
+ * the active point to dim the rest with. Inert (no handler, nothing active)
+ * without `onValueChange`.
+ */
+function useChartSelection(
+  data: readonly Record<string, unknown>[],
+  onValueChange: ((value: ChartEventPayload) => void) | undefined,
+  eventType: NonNullable<ChartEventPayload>["eventType"],
+): { active: ChartActivePoint | null; onEvents: Record<string, (params: unknown) => void> | undefined } {
+  const [active, setActive] = useState<ChartActivePoint | null>(null)
+  // Handlers read the latest props without re-subscribing on every render.
+  const latest = useRef({ data, onValueChange, active })
+  latest.current = { data, onValueChange, active }
+  const interactive = onValueChange !== undefined
+  const onEvents = useMemo(() => {
+    if (!interactive) return undefined
+    return {
+      click: (raw: unknown) => {
+        const p = raw as ChartClickParams
+        if (p.componentType !== "series" || typeof p.dataIndex !== "number") return
+        const category = eventType === "slice" ? (p.name ?? "") : (p.seriesName ?? "")
+        const next = nextChartSelection(latest.current.active, category, p.dataIndex)
+        latest.current.active = next
+        setActive(next)
+        latest.current.onValueChange?.(chartSelectionPayload(next, latest.current.data, eventType))
+      },
+    }
+  }, [interactive, eventType])
+  return { active: interactive ? active : null, onEvents }
+}
+
+/**
+ * Display name for `key`: `labels[key]` when present, else `key` itself.
+ * (Own keys only, so `"constructor"` is not looked up on the prototype.)
+ */
+function labelOf(key: string, labels?: Readonly<Record<string, string>>): string {
+  return hasLabel(labels, key) ? labels![key]! : key
+}
+
+/** `data` with each row's `index` cell replaced by its display name (rows are copied, not mutated). */
+function labelRows<Row extends Record<string, unknown>>(
+  data: readonly Row[],
+  index: string,
+  labels?: Readonly<Record<string, string>>,
+): Row[] {
+  if (!labels) return data as Row[]
+  return data.map((row) => ({ ...row, [index]: labelOf(String(row[index] ?? ""), labels) }))
+}
+
+/** Whether `labels` renames `key` (own keys only). */
+function hasLabel(labels: Readonly<Record<string, string>> | undefined, key: string): boolean {
+  return Boolean(labels) && Object.prototype.hasOwnProperty.call(labels, key)
+}
+
+/* ------------------------------------------------------------ provisional */
+
+/** The default label for points that are not final yet, in `locale`: "Preliminary" / 「速報」. Default the page's locale. */
+function defaultProvisionalLabel(locale?: string): string {
+  return chartText(locale).provisional
+}
+
+/**
+ * Position of the first provisional point: the first entry of `indexValues`
+ * that equals `from` (compared as text, so `"2026-09"` and a Date-less string
+ * key both work). `-1` when `from` is unset or not among the values — the chart
+ * then draws everything as confirmed.
+ */
+function provisionalStart(indexValues: readonly unknown[], from: string | number | undefined | null): number {
+  if (from === undefined || from === null) return -1
+  const key = String(from)
+  return indexValues.findIndex((value) => String(value ?? "") === key)
+}
+
+/**
+ * Split one series at `start` (see `provisionalStart`). `confirmed` keeps the
+ * points before `start`; `provisional` keeps `start` onward plus the last
+ * confirmed point, so the dashed line joins the solid one. `start <= 0` or
+ * `-1` leaves nothing to join (all provisional / none provisional).
+ */
+function splitProvisional(
+  values: readonly (number | null)[],
+  start: number,
+): { confirmed: (number | null)[]; provisional: (number | null)[] } {
+  if (start < 0) return { confirmed: [...values], provisional: values.map(() => null) }
+  return {
+    confirmed: values.map((v, i) => (i < start ? v : null)),
+    provisional: values.map((v, i) => (i >= Math.max(0, start - 1) ? v : null)),
+  }
+}
+
+/* ---------- end of inlined code ---------- */
 
 export 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
 }
 
-const DEFAULT_COLORS = [
-  "bg-chart-1",
-  "bg-chart-2",
-  "bg-chart-3",
-  "bg-chart-4",
-  "bg-chart-5",
-] as const
+/** Every step is the same quantity narrowing down: one colour, not a palette. */
+const DEFAULT_TOKEN: ChartColorToken = "chart-1"
+
+/** The smallest bar (percent of the first step) a non-zero step is drawn at, so it stays visible. */
+export const FUNNEL_MIN_BAR_PERCENT = 4
 
 export const funnelStepsVariants = cva("flex w-full", {
   variants: {
@@ -55,7 +3419,7 @@ export const funnelStepsVariants = cva("flex w-full", {
   },
 })
 
-const funnelBarVariants = cva("rounded-sm transition-[width] ease-out", {
+const funnelBarVariants = cva("rounded-sm transition-[width] ease-out motion-reduce:transition-none", {
   variants: {
     size: {
       sm: "h-6",
@@ -120,21 +3484,146 @@ const funnelConversionVariants = cva("flex items-center text-muted-foreground",
   },
 })
 
-export interface FunnelStepsProps
-  extends ComponentProps<"div">,
+export interface FunnelStepsProps<T extends object = FunnelStep>
+  extends Omit<ComponentProps<"div">, "title" | "color">,
+    Pick<ChartCommonProps, "format" | "valueFormatter" | "title" | "summary" | "isLoading" | "emptyState">,
     VariantProps<typeof funnelStepsVariants> {
-  /** ファネルステップの配列(先頭が最大幅) */
-  data: FunnelStep[]
+  /** ファネルステップの配列(先頭が最大幅)。`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
+}
+
+
+/**
+ * The value formatter a FunnelSteps uses: `valueFormatter`, else the deprecated
+ * `formatValue`, else `format` (default `"compact"`) like every other chart.
+ */
+export function resolveFunnelFormatter(
+  valueFormatter: ((value: number) => string) | undefined,
+  formatValue: ((value: number) => string) | undefined,
+  format?: ValueFormat,
+  locale?: string,
+): (value: number) => string {
+  return resolveValueFormatter(valueFormatter ?? formatValue, format, locale)
+}
+
+const TEXT = {
+  ja: {
+    step: "ステップ",
+    value: "値",
+    previous: "前期",
+    previousHeader: "前期",
+    change: (label: string, points: string) => `(${label}比 ${points})`,
+    funnel: "ファネル",
+  },
+  en: {
+    step: "Step",
+    value: "Value",
+    previous: "prior period",
+    previousHeader: "Prior period",
+    change: (label: string, points: string) => `(vs. ${label} ${points})`,
+    funnel: "Funnel",
+  },
+}
+
+/**
+ * The step reached by the lowest step-to-step conversion (index of the later
+ * step), or `-1` with fewer than 3 steps (nothing to compare) or no rate.
+ */
+export function lowestConversionStep(values: readonly number[]): number {
+  if (values.length < 3) return -1
+  let lowest = -1
+  let lowestRate = Infinity
+  for (let i = 1; i < values.length; i++) {
+    const prev = values[i - 1]!
+    if (prev <= 0) continue
+    const rate = values[i]! / prev
+    if (rate < lowestRate) {
+      lowestRate = rate
+      lowest = i
+    }
+  }
+  return lowest
+}
+
+/**
+ * The step reached by the step-to-step conversion that fell the most against
+ * `previous` (index of the later step), or `-1` when no rate fell or nothing
+ * can be compared (a missing or zero earlier step in either period).
+ */
+export function worstChangeStep(values: readonly number[], previous: readonly (number | null)[]): number {
+  let worst = -1
+  let worstChange = 0
+  for (let i = 1; i < values.length; i++) {
+    const change = conversionChange(values, previous, i)
+    if (change !== null && change < worstChange) {
+      worstChange = change
+      worst = i
+    }
+  }
+  return worst
+}
+
+/** This period's rate into step `i` minus the previous period's (a ratio difference), or `null`. */
+function conversionChange(values: readonly number[], previous: readonly (number | null)[], i: number): number | null {
+  const prevFrom = previous[i - 1]
+  const prevTo = previous[i]
+  const from = values[i - 1]
+  const to = values[i]
+  if (from === undefined || to === undefined || from <= 0) return null
+  if (prevFrom === null || prevFrom === undefined || prevTo === null || prevTo === undefined || prevFrom <= 0) return null
+  return to / from - prevTo / prevFrom
+}
+
+interface FunnelRow {
+  label: string
+  value: number
+  /** The unmapped step name (`index` value), what `highlight` is matched against. */
+  name: string
+  /** The bar colour as CSS (a `--chart-N` token). */
+  css: string
+  /** Deprecated per-step Tailwind bg class: painted as given (no tint). */
+  colorClass?: string
+  onClick?: () => void
 }
 
-function defaultFormatValue(value: number): string {
-  return value.toLocaleString()
+/** Read label / value (numeric strings count, gaps are 0) and the bar colour of each step. */
+function funnelRows(
+  data: readonly object[],
+  index: string,
+  category: string,
+  colors: readonly ChartColorToken[] | undefined,
+): FunnelRow[] {
+  return data.map((row, i) => {
+    const cells = row as Record<string, unknown>
+    const token = colors && colors.length > 0 ? colors[i % colors.length]! : undefined
+    return {
+      label: String(cells[index] ?? ""),
+      name: String(cells[index] ?? ""),
+      value: toChartNumber(cells[category]) ?? 0,
+      css: `var(--${token ?? DEFAULT_TOKEN})`,
+      colorClass: typeof cells.color === "string" ? cells.color : undefined,
+      onClick: typeof cells.onClick === "function" ? (cells.onClick as () => void) : undefined,
+    }
+  })
 }
 
 function computeConversionRate(current: number, previous: number): string {
@@ -142,42 +3631,83 @@ function computeConversionRate(current: number, previous: number): string {
   return `${((current / previous) * 100).toFixed(1)}%`
 }
 
-export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function FunnelSteps(
+/** Label row + bar per step (vertical) or column (horizontal): the skeleton / empty height. */
+const FRAME_HEIGHT = { sm: 4 * 48, md: 4 * 58, lg: 4 * 68 } as const
+
+/** Rows not given yet (a draft fills props in steps): draw the empty state, keep the same array between renders. */
+const NO_ROWS: never[] = []
+
+function FunnelStepsImpl<T extends object>(
   {
-    data,
+    data = NO_ROWS,
+    index = "label" as keyof T & string,
+    categories,
+    colors,
+    labels,
+    highlight,
+    format: valueFormat,
+    valueFormatter,
+    title,
+    summary,
+    isLoading = false,
+    emptyState,
     showConversion = false,
-    formatValue = defaultFormatValue,
+    comparison,
+    formatValue,
     animate = false,
     size = "md",
     direction = "vertical",
+    ariaLabel,
     className,
     ...props
-  },
-  ref,
+  }: FunnelStepsProps<T>,
+  ref: ForwardedRef<HTMLDivElement>,
 ) {
   const [mounted, setMounted] = useState(false)
   const isHorizontal = direction === "horizontal"
+  const locale = useLocale()
+  const t = TEXT[uiLanguage(locale)]
+  const format = resolveFunnelFormatter(valueFormatter, formatValue, valueFormat, locale)
 
   useEffect(() => {
     if (animate) setMounted(true)
   }, [animate])
 
-  const maxValue = data.length > 0 ? data[0]!.value : 0
+  const ready = !isLoading && data.length > 0
+  const steps = funnelRows(data, index, categories?.[0] ?? "value", colors).map((step) => ({
+    ...step,
+    label: labelOf(step.label, labels),
+  }))
+  const maxValue = steps.length > 0 ? steps[0]!.value : 0
+  const values = steps.map((s) => s.value)
+  // `comparison` puts the rates on screen too.
+  const previous = comparison?.values
+  const comparisonLabel = comparison?.label ?? t.previous
+  const showRates = showConversion || previous !== undefined
+  // Only with the rates on screen: the step behind the weakest rate (or, with `comparison`,
+  // the rate that fell the most) is the one to look at.
+  const focus = !showRates ? -1 : previous ? worstChangeStep(values, previous) : lowestConversionStep(values)
+  const dataTable = chartDataTable(
+    steps.map((step, i) => ({ label: step.label, value: step.value, previous: previous?.[i] ?? null })),
+    "label",
+    previous ? ["value", "previous"] : ["value"],
+    format,
+    {
+      label: labels?.[index] ?? t.step,
+      value: (categories?.[0] && labels?.[categories[0]]) || t.value,
+      previous: comparison?.label ?? t.previousHeader,
+    },
+  )
 
-  return (
-    <div
-      ref={ref}
-      data-slot="funnel-steps"
-      role="list"
-      aria-label="ファネル"
-      className={cn(funnelStepsVariants({ size, direction }), className)}
-      {...props}
-    >
-      {data.map((step, index) => {
+  const list = (
+    <div data-slot="funnel-steps" role="list" className={funnelStepsVariants({ size, direction })} {...props}>
+      {steps.map((step, index) => {
         const percentage = maxValue > 0 ? (step.value / maxValue) * 100 : 0
-        // Keep a sliver visible for non-zero steps that would round to nothing.
-        const barSize = step.value > 0 && percentage < 2 ? 2 : percentage
-        const color = step.color ?? DEFAULT_COLORS[index % DEFAULT_COLORS.length]
+        // Keep a visible sliver for non-zero steps that would shrink to a few px.
+        const barSize = step.value > 0 && percentage < FUNNEL_MIN_BAR_PERCENT ? FUNNEL_MIN_BAR_PERCENT : percentage
+        // Light by default (BarList's tint); the highlighted step is the full colour. A legacy bg class is painted as given.
+        const solid = highlight !== undefined && step.name === highlight
+        const paint = step.colorClass ? undefined : solid ? step.css : tintCss(step.css, BAR_LIST_TINT)
         const isClickable = !!step.onClick
 
         const barInteractionProps = isClickable
@@ -204,7 +3734,7 @@ export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function
               <div
                 role="listitem"
                 className="flex min-w-0 flex-1 flex-col items-center gap-1"
-                aria-label={`${step.label}: ${formatValue(step.value)}`}
+                aria-label={`${step.label}: ${format(step.value)}`}
               >
                 <span
                   data-slot="funnel-value"
@@ -213,17 +3743,18 @@ export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function
                     size === "sm" ? "text-xs" : "text-sm",
                   )}
                 >
-                  {formatValue(step.value)}
+                  {format(step.value)}
                 </span>
                 <div className={funnelBarContainerHorizontalVariants({ size })}>
                   <div
                     {...barInteractionProps}
                     className={cn(
-                      "w-full rounded-sm transition-[height] ease-out",
-                      color,
+                      "w-full rounded-sm transition-[height] ease-out motion-reduce:transition-none",
+                      step.colorClass,
                       barInteractionClasses,
                     )}
                     style={{
+                      background: paint,
                       height: animate ? (mounted ? `${barSize}%` : "0%") : `${barSize}%`,
                       transitionDuration: "0.5s",
                       transitionDelay: animate ? `${index * 0.08}s` : undefined,
@@ -240,18 +3771,19 @@ export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function
                 </span>
               </div>
             ) : (
-              <div role="listitem" aria-label={`${step.label}: ${formatValue(step.value)}`}>
+              <div role="listitem" aria-label={`${step.label}: ${format(step.value)}`}>
                 <div className={funnelLabelVariants({ size })}>
                   <span className="truncate">{step.label}</span>
                   <span data-slot="funnel-value" className="tabular-nums">
-                    {formatValue(step.value)}
+                    {format(step.value)}
                   </span>
                 </div>
                 <div className="relative w-full overflow-hidden rounded-sm bg-muted">
                   <div
                     {...barInteractionProps}
-                    className={cn(funnelBarVariants({ size }), color, barInteractionClasses)}
+                    className={cn(funnelBarVariants({ size }), step.colorClass, barInteractionClasses)}
                     style={{
+                      background: paint,
                       width: animate ? (mounted ? `${barSize}%` : "0%") : `${barSize}%`,
                       transitionDuration: "0.5s",
                       transitionDelay: animate ? `${index * 0.08}s` : undefined,
@@ -260,9 +3792,19 @@ export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function
                 </div>
               </div>
             )}
-            {showConversion && index < data.length - 1 && (
+            {showRates && index < steps.length - 1 && (
               <div className={funnelConversionVariants({ size, direction })} aria-hidden="true">
-                <span>→ {computeConversionRate(data[index + 1]!.value, step.value)}</span>
+                <span
+                  data-focus={index + 1 === focus || undefined}
+                  className={cn(index + 1 === focus && "font-medium text-negative")}
+                >
+                  → {computeConversionRate(steps[index + 1]!.value, step.value)}
+                  {previous && (
+                    <span data-slot="funnel-change" className="ml-1 tabular-nums">
+                      {t.change(comparisonLabel, formatPoints(conversionChange(values, previous, index + 1), locale))}
+                    </span>
+                  )}
+                </span>
               </div>
             )}
           </Fragment>
@@ -270,5 +3812,32 @@ export const FunnelSteps = forwardRef<HTMLDivElement, FunnelStepsProps>(function
       })}
     </div>
   )
-})
+
+  return (
+    <ChartFrame
+      ref={ref}
+      title={title}
+      summary={summary}
+      isLoading={isLoading}
+      isEmpty={data.length === 0}
+      emptyState={emptyState}
+      // Loading / empty keep a fixed height; the steps themselves are as tall as they are.
+      height={ready ? "auto" : FRAME_HEIGHT[size ?? "md"]}
+      variant="list"
+      ariaLabel={ariaLabel ?? t.funnel}
+      plotRole="group"
+      dataTable={dataTable}
+      className={className}
+    >
+      {list}
+    </ChartFrame>
+  )
+}
+
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+export const FunnelSteps = forwardRef(
+  FunnelStepsImpl as (props: FunnelStepsProps<object>, ref: ForwardedRef<HTMLDivElement>) => ReactElement,
+) as (<T extends object = FunnelStep>(props: FunnelStepsProps<T> & { ref?: Ref<HTMLDivElement> }) => ReactElement) & {
+  displayName?: string
+}
 FunnelSteps.displayName = "FunnelSteps"