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

package/registry/ui/waterfall-chart.tsx

@@ -0,0 +1,4561 @@
+// Copied by `vantage add ui waterfall-chart`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/charts/waterfall-chart.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * WaterfallChart — a typed waterfall chart over `EChart`: pass the steps as rows,
+ * the name key (`index`) and the amount key (`categories: [valueKey]`) instead of
+ * an ECharts option. 売上 → 原価 → 粗利 の内訳、前期からの増減要因。
+ *
+ * Each row is a step that moves the running total by its value; rows named in
+ * `totals` are totals — a bar from 0 to the running total (or to their own value
+ * when they carry one). The bars are a stacked bar chart over a transparent base,
+ * so the value axis always starts at 0. Increase / decrease bars use the
+ * area tokens (`--positive-fill` / `--negative-fill`, swapped by `polarity`), totals are
+ * `--chart-1`; every step also prints its signed amount (+ / -), so the colour is
+ * never the only carrier of the direction. Missing values (null) draw no bar and read「—」.
+ * `mode="delta"` draws only the moves: the axis is the cumulative change from 0 (the start),
+ * totals are not bars (their numbers go in a note above the plot), so a small change against
+ * a large total is not a hairline on a tall axis; the axis still starts at 0 and can go negative.
+ * A closing「純増」bar (the net change, `--chart-1`, signed) is appended in `delta`. Value-axis ticks carry no "+" in
+ * both modes; the sign is on the bar labels only.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state, and
+ * a visually-hidden table of the steps).
+ */
+import { forwardRef, useMemo, type ForwardedRef, type ReactElement, type Ref } from "react"
+import { use } from "echarts/core"
+import { GraphicComponent } from "echarts/components"
+import type { EChartsOption } from "echarts"
+
+import { ChartFrame } from "@squadbase/vantage/components"
+import { EChart } from "@squadbase/vantage/components"
+import type { Polarity } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, MINUS_SIGN } from "@squadbase/vantage/components"
+import type { ChartCommonProps, NumericKeys, ValueFormatter } from "@squadbase/vantage/components"
+import { useSyncExternalStore } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, type RefObject } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
+import { type ReactNode } from "react"
+import { computeComparison, defaultChangeDisplay, formatChange, toneForValue, type ComparisonKind, type PeriodGrain } from "@squadbase/vantage/components"
+import { DEFAULT_LOCALE, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartThreshold, ChartAnnotation, ChartEventPayload, ChartForecast, ChartForecastRow, ChartHighlight } from "@squadbase/vantage/components"
+import { formatValue, toValueFormatter } from "@squadbase/vantage/components"
+import type { ChartColor, ChartColors, ChartSeriesColor } 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-theme.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The colour of the folded「その他」series / slice / row. The ONLY place this
+ * grey is defined — every chart takes it from here. It is the most subdued
+ * colour in a chart, not the darkest: the theme's `--neutral` mixed halfway into
+ * `--background`, so it recedes in light and dark alike (and brand themes follow
+ * it). `--neutral-subtle` alone sits too close to the background to read as a
+ * slice. Canvas charts resolve it through `resolveChartColors`.
+ */
+const CHART_OTHER_COLOR = "color-mix(in oklab, var(--neutral) 50%, var(--background))"
+
+/**
+ * True inside `ChartFrame`. The frame's plot area carries the chart's single
+ * `role="img"` and label, so `EChart` drops its own when it sees this.
+ */
+const ChartFrameContext = createContext(false)
+
+/** Series palette, in order. Missing tokens are skipped, not defaulted. */
+const SERIES_TOKENS = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5"] as const
+
+interface ChartTokens {
+  /** Resolved `--chart-1..5`, in order. */
+  series: string[]
+  /** Computed `font-family` of the container, so canvas text matches the DOM. Optional. */
+  fontFamily?: string
+  /** Body text: titles and the default `textStyle`. */
+  foreground: string | null
+  /** Secondary text: axis labels, legend, subtitles. */
+  mutedForeground: string | null
+  /** Axis lines, ticks, split lines, tooltip border. */
+  border: string | null
+  /** Tooltip surface. */
+  popover: string | null
+  /** Semantic and surface dependencies used by typed chart options. Optional for hand-built tokens. */
+  colors?: Record<string, string>
+  /** Actual inherited painting surface (may change without a token changing). */
+  surface?: string | null
+  /** Tooltip text. */
+  popoverForeground: string | null
+}
+
+// Keep scope out of the public token shape. A resolved snapshot remembers where arbitrary
+// var(--token) expressions must be read, without retaining unmounted charts globally.
+const tokenScopes = new WeakMap<ChartTokens, Element>()
+const OPTION_COLOR_TOKENS = [
+  "--background", "--card", "--muted", "--primary", "--destructive",
+  ...["positive", "negative", "warning", "neutral", "info"].flatMap((tone) =>
+    ["", "-fill", "-subtle"].map((suffix) => `--${tone}${suffix}`)),
+]
+
+let normalizeContext: CanvasRenderingContext2D | null | undefined
+
+/** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
+const ZRENDER_COLOR_RE = /^(?:#[0-9a-f]{6}|rgba?\()/i
+
+/**
+ * Serialize a CSS colour into a canvas-safe form, or `null` if the browser
+ * rejects it. Assigning an invalid value to `fillStyle` is a no-op, so the same
+ * input is written over two different known colours: agreeing results mean the
+ * value parsed, differing ones mean it was dropped.
+ */
+function toCanvasColor(value: string): string | null {
+  const raw = value.trim()
+  if (!raw) return null
+  if (normalizeContext === undefined) {
+    const canvas = document.createElement("canvas")
+    canvas.width = 1
+    canvas.height = 1
+    normalizeContext = canvas.getContext("2d", { willReadFrequently: true })
+  }
+  const ctx = normalizeContext
+  if (!ctx) return raw
+  ctx.fillStyle = "#000000"
+  ctx.fillStyle = raw
+  const onBlack = ctx.fillStyle
+  ctx.fillStyle = "#ffffff"
+  ctx.fillStyle = raw
+  if (onBlack !== ctx.fillStyle || typeof onBlack !== "string") return null
+  if (ZRENDER_COLOR_RE.test(onBlack)) return onBlack
+  // Still `oklch()` / `lab()` / `color(...)`: paint it and read the pixel back.
+  // Wide-gamut colours clip to sRGB, which is all zrender can express anyway.
+  ctx.clearRect(0, 0, 1, 1)
+  ctx.fillRect(0, 0, 1, 1)
+  const [r = 0, g = 0, b = 0, a = 0] = ctx.getImageData(0, 0, 1, 1).data
+  return a === 255
+    ? `rgb(${r}, ${g}, ${b})`
+    : `rgba(${r}, ${g}, ${b}, ${Math.round((a / 255) * 1000) / 1000})`
+}
+
+/**
+ * Read the chart tokens off `el` (the document root by default — tokens live on
+ * `:root` and inherit). Returns `null` outside the browser so callers fall back
+ * to plain ECharts defaults.
+ */
+function readChartTokens(el?: Element | null): ChartTokens | null {
+  if (typeof document === "undefined") return null
+  const target = el ?? document.documentElement
+  if (!target) return null
+  const styles = getComputedStyle(target)
+  const read = (name: string) => toCanvasColor(styles.getPropertyValue(name))
+  const series: string[] = []
+  for (const token of SERIES_TOKENS) {
+    const color = read(token)
+    if (color) series.push(color)
+  }
+  const tokens: ChartTokens = {
+    series,
+    colors: Object.fromEntries(OPTION_COLOR_TOKENS.map((name) => [name, styles.getPropertyValue(name).trim()])),
+    surface: readChartSurface(target),
+    ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
+    foreground: read("--foreground"),
+    mutedForeground: read("--muted-foreground"),
+    border: read("--border"),
+    popover: read("--popover"),
+    popoverForeground: read("--popover-foreground"),
+  }
+  tokenScopes.set(tokens, target)
+  return tokens
+}
+
+/** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
+function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return (
+    tokenScopes.get(a) === tokenScopes.get(b) &&
+    a.surface === b.surface &&
+    Object.keys(a.colors ?? {}).length === Object.keys(b.colors ?? {}).length &&
+    Object.entries(a.colors ?? {}).every(([name, value]) => b.colors?.[name] === value) &&
+    a.series.length === b.series.length &&
+    a.series.every((color, i) => color === b.series[i]) &&
+    a.fontFamily === b.fontFamily &&
+    a.foreground === b.foreground &&
+    a.mutedForeground === b.mutedForeground &&
+    a.border === b.border &&
+    a.popover === b.popover &&
+    a.popoverForeground === b.popoverForeground
+  )
+}
+
+/**
+ * Watch everything that can change the resolved tokens and call `onChange` when
+ * something might have. It only ever says "re-read" — the caller compares with
+ * `sameChartTokens` and decides whether anything actually moved. Returns a
+ * disposer.
+ *
+ * Two sources, not one:
+ *  - light/dark flips, which land as `class` / `data-theme` (or an inline
+ *    `style`) on `<html>`/`<body>`, or as an OS preference change
+ *  - stylesheet changes. In dev, editing `styles.css` rewrites the injected
+ *    `<style>` in `<head>` and touches nothing else, so watching the theme
+ *    attributes alone leaves the chart painted in the previous palette until a
+ *    reload — the tokens in the DOM are new, the canvas is not.
+ */
+function watchChartTokens(onChange: () => void, scope?: Element | null): () => void {
+  if (typeof document === "undefined") return () => {}
+  // Style edits arrive as bursts of mutations; coalesce them into one read, and
+  // take it after the next frame so a swapped stylesheet has been applied.
+  let frame = 0
+  const schedule = () => {
+    if (frame) return
+    frame = requestAnimationFrame(() => {
+      frame = 0
+      onChange()
+    })
+  }
+
+  const themeObserver = new MutationObserver(schedule)
+  const attributeFilter = ["class", "style", "data-theme"]
+  // Only the chart and its ancestors can change its inherited theme. Never observe
+  // the document subtree: canvas/tooltip/rendering mutations would trigger every chart.
+  for (let node: Element | null = scope ?? document.body ?? document.documentElement; node; node = node.parentElement) {
+    themeObserver.observe(node, { attributes: true, attributeFilter })
+  }
+
+  const styleObserver = new MutationObserver(schedule)
+  if (document.head) {
+    styleObserver.observe(document.head, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["href", "media", "disabled"],
+    })
+  }
+
+  // A swapped `<link>` only applies once the sheet has loaded, after its mutation.
+  const onLoad = (event: Event) => {
+    if (event.target instanceof HTMLLinkElement) schedule()
+  }
+  document.addEventListener("load", onLoad, true)
+
+  const media = window.matchMedia("(prefers-color-scheme: dark)")
+  media.addEventListener("change", schedule)
+
+  return () => {
+    if (frame) cancelAnimationFrame(frame)
+    themeObserver.disconnect()
+    styleObserver.disconnect()
+    document.removeEventListener("load", onLoad, true)
+    media.removeEventListener("change", schedule)
+  }
+}
+
+/** Shared shape for the four axis types ECharts themes address separately. */
+function axisTheme(tokens: ChartTokens, splitLine: boolean) {
+  const line = tokens.border ?? undefined
+  return {
+    axisLine: { show: false },
+    axisTick: { show: false },
+    axisLabel: { show: true, color: tokens.mutedForeground ?? undefined, fontSize: 12 },
+    // Faint horizontal rules only: the border colour at low opacity.
+    splitLine: { show: splitLine, lineStyle: { color: line ? [line] : undefined, opacity: 0.5, width: 1 } },
+    splitArea: { show: false },
+  }
+}
+
+/**
+ * Build the ECharts theme. `option.color` still wins over `theme.color`, so an
+ * app that sets its own palette keeps it.
+ */
+function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
+  const text = tokens.foreground ?? undefined
+  const muted = tokens.mutedForeground ?? undefined
+  const line = tokens.border ?? undefined
+  return {
+    // Let the page background show through: charts sit on cards, not on a canvas.
+    backgroundColor: "transparent",
+    ...(tokens.series.length > 0 ? { color: tokens.series } : {}),
+    textStyle: { color: text, ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}) },
+    title: { textStyle: { color: text }, subtextStyle: { color: muted } },
+    legend: { textStyle: { color: muted } },
+    categoryAxis: axisTheme(tokens, false),
+    valueAxis: axisTheme(tokens, true),
+    logAxis: axisTheme(tokens, true),
+    timeAxis: axisTheme(tokens, true),
+    tooltip: {
+      // ECharts' default 0.4s transform lags the tooltip ~300ms behind the cursor.
+      transitionDuration: 0,
+      backgroundColor: tokens.popover ?? undefined,
+      borderColor: line,
+      borderWidth: 1,
+      padding: [8, 12],
+      // Rounded card with a soft shadow; in dark mode the shadow barely shows, so the border carries the edge.
+      extraCssText: "border-radius:8px;box-shadow:var(--shadow-card, 0 4px 12px rgb(0 0 0 / 0.08));",
+      textStyle: {
+        color: tokens.popoverForeground ?? undefined,
+        fontSize: 12,
+        ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}),
+      },
+      axisPointer: { lineStyle: { color: line }, crossStyle: { color: line } },
+    },
+  }
+}
+
+/**
+ * The resolved tokens, kept current: re-read whenever `watchChartTokens` says
+ * they may have moved, and only replaced when a value actually changed. For
+ * components that build an ECharts option from token colours themselves (the
+ * typed charts), so their palette follows light/dark like `EChart`'s theme.
+ */
+function useChartTokens(scope?: Element | null | RefObject<Element | null>): ChartTokens | null {
+  const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
+  // Compared here, not inside a `setTokens` updater: an updater that reads the DOM is
+  // replayed by React on every rebase and returns a fresh object each time, so the state
+  // never settles ("Maximum update depth exceeded" once the tokens change after mount).
+  const tokensRef = useRef(tokens)
+  useEffect(() => {
+    const target = scope && "current" in scope ? scope.current : scope
+    const sync = () => {
+      const next = readChartTokens(target)
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
+    }
+    sync()
+    return watchChartTokens(sync, target)
+  }, [scope])
+  return tokens
+}
+
+const SERIES_TOKEN_NAME_RE = /^chart-([1-5])$/
+const TONE_NAME_RE = /^(?:positive|warning|negative|neutral|info)(?:-fill)?$/
+const CSS_VAR_RE = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.+))?\)$/
+const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
+
+/**
+ * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
+ * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
+ * variants `"positive-fill"`, …) are read in the snapshot's inherited scope (`--positive`, …); `var(--token)` uses the same scope; any
+ * other CSS colour is normalized like the tokens are. A colour that can't be
+ * resolved comes back as `""`, which ECharts treats as "use the palette".
+ */
+function resolveChartColors(colors: readonly string[], tokens: ChartTokens | null): string[] {
+  return colors.map((color) => {
+    const token = SERIES_TOKEN_NAME_RE.exec(color.trim())
+    if (token) return tokens?.series[Number(token[1]) - 1] ?? ""
+    // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
+    if (TONE_NAME_RE.test(color.trim())) {
+      if (typeof document === "undefined") return ""
+      const target = (tokens && tokenScopes.get(tokens)) ?? document.documentElement
+      return toCanvasColor(getComputedStyle(target).getPropertyValue(`--${color.trim()}`)) ?? ""
+    }
+    if (typeof document === "undefined") return color
+    let value = color.trim()
+    const cssVar = CSS_VAR_RE.exec(value)
+    const styles = getComputedStyle((tokens && tokenScopes.get(tokens)) ?? document.documentElement)
+    if (cssVar) {
+      value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
+    } else if (value.includes("var(")) {
+      // A colour function over tokens (`color-mix(… var(--muted-foreground) …)`):
+      // substitute the tokens, then let the canvas resolve the rest.
+      value = value.replace(EMBEDDED_VAR_RE, (_, name: string) => styles.getPropertyValue(name).trim())
+    }
+    return toCanvasColor(value) ?? ""
+  })
+}
+
+/** Every meaning colour resolved for the canvas (`""` when it can't be resolved). */
+function resolveToneColors(tokens: ChartTokens | null): Record<ChartTone, string> {
+  const [positive = "", warning = "", negative = "", neutral = ""] = resolveChartColors(
+    ["positive", "warning", "negative", "neutral"],
+    tokens,
+  )
+  return { positive, warning, negative, neutral }
+}
+
+/** The area (`--<tone>-fill`) colours of every meaning tone, resolved for the canvas (`""` when it can't be resolved). */
+function resolveFillColors(tokens: ChartTokens | null): Record<ChartTone, string> {
+  const [positive = "", warning = "", negative = "", neutral = ""] = resolveChartColors(
+    ["positive-fill", "warning-fill", "negative-fill", "neutral-fill"],
+    tokens,
+  )
+  return { positive, warning, negative, neutral }
+}
+
+const TRANSPARENT_RE = /^(?:transparent|rgba\([^)]*,\s*0(?:\.0+)?\))$/i
+
+/**
+ * The colour the chart is painted on: the first opaque `background-color` up
+ * from `el` (a card, the page), else `--background`. Canvas-safe, or `null`
+ * outside the browser.
+ */
+function readChartSurface(el: Element | null): string | null {
+  if (typeof document === "undefined") return null
+  for (let node: Element | null = el; node; node = node.parentElement) {
+    const bg = getComputedStyle(node).backgroundColor.trim()
+    if (bg && !TRANSPARENT_RE.test(bg)) {
+      const color = toCanvasColor(bg)
+      if (color) return color
+    }
+  }
+  return toCanvasColor(getComputedStyle(el ?? document.documentElement).getPropertyValue("--background"))
+}
+
+/** Widths are bucketed so a resize only rebuilds the option when the label budget can change. */
+const WIDTH_BUCKET = 40
+
+/**
+ * The surface colour behind a chart (see `readChartSurface`), re-read when the
+ * tokens move (light/dark), and the plot's width (rounded down to 40px;
+ * `undefined` until measured). Returns a ref for the plot that also feeds the
+ * component's forwarded ref.
+ */
+function useChartSurface<E extends Element>(
+  forwarded: ForwardedRef<E>,
+  tokens?: ChartTokens | null,
+): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined; tokens: ChartTokens | null } {
+  const [node, setNode] = useState<E | null>(null)
+  const scopedTokens = useChartTokens(node)
+  const [surface, setSurface] = useState<string | undefined>(undefined)
+  const [width, setWidth] = useState<number | undefined>(undefined)
+  const ref = useCallback(
+    (el: E | null) => {
+      setNode(el)
+      if (typeof forwarded === "function") forwarded(el)
+      else if (forwarded) forwarded.current = el
+    },
+    [forwarded],
+  )
+  useEffect(() => {
+    if (!node) return
+    setSurface(readChartSurface(node) ?? undefined)
+  }, [node, tokens, scopedTokens])
+  useEffect(() => {
+    if (!node || typeof ResizeObserver === "undefined") return
+    const update = (w: number) => setWidth(Math.floor(w / WIDTH_BUCKET) * WIDTH_BUCKET)
+    update(node.getBoundingClientRect().width)
+    const observer = new ResizeObserver((entries) => update(entries[0]?.contentRect.width ?? 0))
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node])
+  return { ref, surface, width, tokens: scopedTokens }
+}
+
+/* ---------- 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
+
+/**
+ * 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`.
+ */
+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" },
+    }
+  }
+}
+
+/**
+ * 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)),
+  }
+}
+
+/* ---------- 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)}`
+}
+
+/* ---------- end of inlined code ---------- */
+
+// The delta note is a `graphic` text, which `EChart` does not register for the other charts.
+use([GraphicComponent])
+
+/**
+ * `"total"`: 合計の段を 0 からの棒として描く(既定)。`"delta"`: 増減の段だけを描く(開始を 0 とした累計増減の軸)。
+ */
+export type WaterfallMode = "total" | "delta"
+
+export interface WaterfallChartProps<T extends Record<string, unknown> = Record<string, unknown>>
+  extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors" | "summary"> {
+  /** 段の名前に使う列名。行の並びがそのままグラフの左から右の順。 */
+  index: keyof T & string
+  /** 増減額(合計の行は合計値)の列名を 1 つだけ入れた配列(`["金額"]`)。2 つ以上渡しても最初の 1 つだけを使う。値は number か数値文字列。 */
+  categories: NumericKeys<T>[]
+  /**
+   * 合計の段にする行の `index` の値(例 `["売上", "粗利"]`)。合計の段は 0 から累計まで届く棒で、色は `--chart-1`。
+   * 合計の行の値が null なら直前までの累計になる(計算に任せるのが確実)。値があればその値が合計になり、以降の累計はそこから続く。
+   * 最初の段が増減の行なら 0 から始まる。`mode="delta"` では棒にならず、先頭の行が「開始」、末尾の行が「終了」の注記になる。
+   */
+  totals?: string[]
+  /**
+   * 増えるのが良いか。`"higher-is-better"`(既定)は増加が `--positive-fill`・減少が `--negative-fill`(棒用の面のトークン)。
+   * 解約数のように増えて悪い指標は `"lower-is-better"` で色が入れ替わる。`"neutral"` は増減とも `--neutral-fill`(符号は付く)。
+   */
+  polarity?: Polarity
+  /**
+   * 描き方。`"total"`(既定)は合計の段を 0 からの棒で描く。
+   * `"delta"` は開始を 0 とした累計増減の軸で増減の段だけを描き、`totals` の行は棒にせず、
+   * 開始・終了の値は図の上の注記(と要約・データ表)に出し、末尾に「純増」棒(増減の合計。`--chart-1`、符号つき)を足す。値軸の目盛に `+` は付かない。合計に対して増減が小さい(目安: 総額の 5% 未満)ときに使う。
+   * 軸は 0 起点のまま(累計が負になる段も 0 の下に描く)。例 `mode="delta"`
+   */
+  mode?: WaterfallMode
+  /** 段の名前(`index` の値)→ 表示名。軸・ツールチップ・データ表に反映。例 `{ cogs: "売上原価" }`。無いキーはそのまま。データ表の先頭列名を直すには `index` のキーも渡す(既定は「項目」)。 */
+  labels?: Record<string, string>
+  /**
+   * 縦軸の下限。軸は常に 0 を含むので、0 以下の値だけ有効(累計が負になる段の下に余白を取る。正の値は無視)。
+   * データが下限を下回るときは軸を広げる(切り詰めない)。`mode="total"` / `"delta"` の両方で効く。
+   * 部署別などを並べて比べるときは、全部のグラフに同じ `minValue` / `maxValue` を渡して縦軸をそろえる。
+   */
+  minValue?: number
+  /**
+   * 縦軸の上限。データが上限を超えるときは軸を広げる(切り詰めない)。`mode="total"` / `"delta"` の両方で効く。
+   * 並べて比べるときは、全部のグラフに同じ `minValue` / `maxValue` を渡して縦軸をそろえる。
+   */
+  maxValue?: number
+  /** y 軸ラベルの幅(px)。並べた複数グラフのプロット領域を揃えたいときに固定する。 */
+  yAxisWidth?: number
+  /** 各棒に符号つきの増減額(合計は累計)を書く。既定 `true`。 */
+  showValues?: boolean
+  /** ホバー時のツールチップ(増減と累計)を出す。既定 `true`。 */
+  showTooltip?: boolean
+  /**
+   * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら steps から「<見出し>: <最初> <値> → <最後> <値>。最大の増加は …、最大の減少は …」を組む(`mode="delta"` は「<開始> <値> → <終了> <値>（<増減>）」)。
+   * 省略時は要約なし。例: `summary="auto"`
+   */
+  summary?: string | "auto"
+  /** 見出しが無いときのプロット領域の読み上げ名。省略時は「<金額の列>のウォーターフォールチャート」。 */
+  ariaLabel?: string
+}
+
+/* ------------------------------------------------------------------ model */
+
+const TEXT = {
+  ja: {
+    net: "純増",
+    total: "合計",
+    change: "増減",
+    cumulative: "累計",
+    cumulativeChange: "累計増減",
+    item: "項目",
+    start: "開始",
+    end: "終了",
+    fromTo: (from: string, to: string, net: string) => `${from} → ${to}（${net}）`,
+    from: (from: string, net: string) => `${from} から ${net}`,
+    to: (to: string, net: string) => `${to}（${net}）`,
+    netOnly: (net: string) => `増減の合計 ${net}`,
+    increase: (name: string, value: string) => `最大の増加は ${name}（${value}）`,
+    decrease: (name: string, value: string) => `最大の減少は ${name}（${value}）`,
+    sentenceJoin: "。",
+    chart: (label: string) => `${label}のウォーターフォールチャート`,
+  },
+  en: {
+    net: "Net change",
+    total: "Total",
+    change: "Change",
+    cumulative: "Cumulative",
+    cumulativeChange: "Cumulative change",
+    item: "Item",
+    start: "Start",
+    end: "End",
+    fromTo: (from: string, to: string, net: string) => `${from} → ${to} (${net})`,
+    from: (from: string, net: string) => `${net} from ${from}`,
+    to: (to: string, net: string) => `${to} (${net})`,
+    netOnly: (net: string) => `Net change ${net}`,
+    increase: (name: string, value: string) => `Largest increase: ${name} (${value})`,
+    decrease: (name: string, value: string) => `Largest decrease: ${name} (${value})`,
+    sentenceJoin: ". ",
+    chart: (label: string) => `Waterfall chart of ${label}`,
+  },
+}
+
+const textOf = (locale?: string) => TEXT[uiLanguage(resolveLocale(locale))]
+
+export type WaterfallKind = "total" | "increase" | "decrease" | "flat" | "gap"
+
+export interface WaterfallStep {
+  name: string
+  kind: WaterfallKind
+  /** A step's signed change, a total's value. `null` for a gap. */
+  value: number | null
+  /** The running total before this step (a total starts at 0). */
+  start: number
+  /** The running total after this step. */
+  end: number
+  row: Record<string, unknown>
+}
+
+/**
+ * Rows → steps. A row named in `totals` is a total: it spans 0 → its own value,
+ * or 0 → the running total when the value is missing. Every other row moves the
+ * running total by its value; a missing value moves nothing (a gap).
+ */
+export function waterfallSteps(
+  data: readonly Record<string, unknown>[],
+  config: { index: string; value: string; totals?: readonly string[]; mode?: WaterfallMode; locale?: string },
+): WaterfallStep[] {
+  const totals = new Set(config.totals ?? [])
+  const delta = config.mode === "delta"
+  let running = 0
+  // `delta`: totals are not steps (they neither draw nor move the running change), so only the moves remain.
+  const steps = (delta ? data.filter((row) => !totals.has(String(row[config.index] ?? ""))) : data).map((row) => {
+    const name = String(row[config.index] ?? "")
+    const n = config.value ? toChartNumber(row[config.value]) : null
+    if (totals.has(name)) {
+      const end = n ?? running
+      running = end
+      return { name, kind: "total" as const, value: end, start: 0, end, row }
+    }
+    if (n === null) return { name, kind: "gap" as const, value: null, start: running, end: running, row }
+    const start = running
+    running = start + n
+    return { name, kind: n > 0 ? ("increase" as const) : n < 0 ? ("decrease" as const) : ("flat" as const), value: n, start, end: running, row }
+  })
+  // `delta`: the net change closes the plot as a total bar from 0 (series colour 1), so the moves add up to something.
+  if (delta && steps.some((s) => s.kind !== "gap")) {
+    steps.push({ name: deltaTotalName(config.locale), kind: "total", value: running, start: 0, end: running, row: {} })
+  }
+  return steps
+}
+
+/** The name of the net-change bar that `mode="delta"` appends, in `locale` ("Net change" / 「純増」). Default the page's locale. */
+export function deltaTotalName(locale?: string): string {
+  return textOf(locale).net
+}
+
+/** What `mode="delta"` leaves out of the bars: the opening / closing totals and the net change of the moves. */
+export interface WaterfallDeltaEnds {
+  /** The first total row when it comes before every move (its value, `null` when the row carries none). */
+  opening: { name: string; value: number | null } | null
+  /** The last total row when it comes after every move; a missing value is the opening plus the net change. */
+  closing: { name: string; value: number | null } | null
+  /** The sum of every move (the cumulative change at the last step). */
+  net: number
+}
+
+/** `mode="delta"`: the opening / closing totals and the net change, read from the rows (`totals` rows are not bars there). */
+export function waterfallDeltaEnds(
+  data: readonly Record<string, unknown>[],
+  config: { index: string; value: string; totals?: readonly string[] },
+): WaterfallDeltaEnds {
+  const totals = new Set(config.totals ?? [])
+  const kinds = data.map((row) => totals.has(String(row[config.index] ?? "")))
+  const firstMove = kinds.indexOf(false)
+  const lastMove = kinds.lastIndexOf(false)
+  const valueAt = (i: number) => (config.value ? toChartNumber(data[i]![config.value]) : null)
+  const nameAt = (i: number) => String(data[i]![config.index] ?? "")
+  const net = data.reduce((sum, row, i) => (kinds[i] ? sum : sum + (toChartNumber(row[config.value]) ?? 0)), 0)
+  const openingAt = kinds.indexOf(true)
+  const closingAt = kinds.lastIndexOf(true)
+  const opening =
+    openingAt !== -1 && (firstMove === -1 || openingAt < firstMove) ? { name: nameAt(openingAt), value: valueAt(openingAt) } : null
+  const closingRow =
+    closingAt !== -1 && closingAt !== openingAt && (lastMove === -1 || closingAt > lastMove)
+      ? { name: nameAt(closingAt), value: valueAt(closingAt) }
+      : null
+  const closing =
+    closingRow && closingRow.value === null && opening?.value != null ? { ...closingRow, value: opening.value + net } : closingRow
+  return { opening, closing, net }
+}
+
+/** The note above a delta plot: `前期 ¥2.2億 → 当期 ¥2.2億（+¥130万）`; without the totals' values, the net change alone. */
+export function waterfallDeltaNote(
+  ends: WaterfallDeltaEnds,
+  formatter: ValueFormatter,
+  labels?: Record<string, string>,
+  locale?: string,
+): string {
+  const t = textOf(locale)
+  const net = signedText(ends.net, formatter)
+  const { opening, closing } = ends
+  const side = (e: { name: string; value: number | null } | null) => (e && e.value !== null ? `${labelOf(e.name, labels)} ${formatter(e.value)}` : null)
+  const from = side(opening)
+  const to = side(closing)
+  if (from && to) return t.fromTo(from, to, net)
+  if (from) return t.from(from, net)
+  if (to) return t.to(to, net)
+  return t.netOnly(net)
+}
+
+export interface WaterfallStack {
+  /** The transparent base under each bar (0 when the bar starts at the axis or crosses it). */
+  base: number[]
+  /** The part of each bar above 0. */
+  pos: number[]
+  /** The part of each bar below 0 (≤ 0). */
+  neg: number[]
+  /** Which series carries the step's value label. */
+  labelOn: ("pos" | "neg")[]
+}
+
+/**
+ * Steps → the three stacked series (base, above 0, below 0). Positive and negative
+ * values stack separately in ECharts, so a bar entirely in the negative needs its
+ * base there too, and a bar crossing 0 has no base and a part on each side.
+ */
+export function waterfallStack(steps: readonly WaterfallStep[]): WaterfallStack {
+  const base: number[] = []
+  const pos: number[] = []
+  const neg: number[] = []
+  const labelOn: ("pos" | "neg")[] = []
+  for (const step of steps) {
+    if (step.kind === "gap") {
+      base.push(0)
+      pos.push(0)
+      neg.push(0)
+      labelOn.push("pos")
+      continue
+    }
+    const from = step.kind === "total" ? 0 : step.start
+    const lo = Math.min(from, step.end)
+    const hi = Math.max(from, step.end)
+    if (lo >= 0) {
+      base.push(lo)
+      pos.push(hi - lo)
+      neg.push(0)
+      labelOn.push("pos")
+    } else if (hi <= 0) {
+      base.push(hi)
+      pos.push(0)
+      neg.push(lo - hi)
+      labelOn.push("neg")
+    } else {
+      base.push(0)
+      pos.push(hi)
+      neg.push(lo)
+      labelOn.push("pos")
+    }
+  }
+  return { base, pos, neg, labelOn }
+}
+
+/** The colour role of a step: totals are series colour 1, steps follow `polarity` (neutral: both directions grey). */
+export function waterfallTone(kind: WaterfallKind, polarity: Polarity = "higher-is-better"): "total" | "positive" | "negative" | "neutral" {
+  if (kind === "total") return "total"
+  if (kind === "gap" || kind === "flat" || polarity === "neutral") return "neutral"
+  const up = kind === "increase"
+  return up === (polarity === "higher-is-better") ? "positive" : "negative"
+}
+
+/** `+600` / `−600` (U+2212) through `formatter`; zero has no sign. */
+export function signedText(value: number, formatter: ValueFormatter): string {
+  if (value > 0) return `+${formatter(value)}`
+  if (value < 0) return `${MINUS_SIGN}${formatter(-value)}`
+  return formatter(0)
+}
+
+/** The text on a step's bar: a signed change, a total as is, 「—」 for a gap. */
+export function waterfallStepText(step: WaterfallStep, formatter: ValueFormatter, delta = false): string {
+  if (step.value === null) return EMPTY_VALUE
+  // `delta`: the closing total is the net change, so it carries a sign like the moves it sums.
+  return step.kind === "total" && !delta ? formatter(step.value) : signedText(step.value, formatter)
+}
+
+/** `summary="auto"`: first → last level and the largest increase / decrease. `undefined` with no usable step. */
+export function buildWaterfallSummary(
+  steps: readonly WaterfallStep[],
+  formatter: ValueFormatter,
+  title?: string,
+  labels?: Record<string, string>,
+  delta?: WaterfallDeltaEnds,
+  locale?: string,
+): string | undefined {
+  const t = textOf(locale)
+  const real = steps.filter((s) => s.kind !== "gap")
+  const first = real[0]
+  const last = real[real.length - 1]
+  if (!first || !last) return undefined
+  const name = (s: WaterfallStep) => labelOf(s.name, labels)
+  const head = title ? `${title}: ` : ""
+  // A first step starts at 0, so its end is its value; a total's end is the total. `delta`: the note (totals and net change) instead.
+  const parts = [
+    delta
+      ? waterfallDeltaNote(delta, formatter, labels, locale)
+      : real.length === 1
+        ? `${name(first)} ${formatter(first.end)}`
+        : `${name(first)} ${formatter(first.end)} → ${name(last)} ${formatter(last.end)}`,
+  ]
+  let up: WaterfallStep | undefined
+  let down: WaterfallStep | undefined
+  for (const s of real) {
+    if (s.kind === "increase" && (!up || s.value! > up.value!)) up = s
+    if (s.kind === "decrease" && (!down || s.value! < down.value!)) down = s
+  }
+  if (up) parts.push(t.increase(name(up), signedText(up.value!, formatter)))
+  if (down) parts.push(t.decrease(name(down), signedText(down.value!, formatter)))
+  return `${head}${parts.join(t.sentenceJoin)}`
+}
+
+/** The screen-reader table: one row per step with its change and the running total. */
+export function waterfallDataTable(
+  steps: readonly WaterfallStep[],
+  names: { index: string; value: string },
+  formatter: ValueFormatter,
+  labels?: Record<string, string>,
+  delta?: WaterfallDeltaEnds,
+  locale?: string,
+): ChartDataTable {
+  const t = textOf(locale)
+  const label = (key: string) => labelOf(key, labels)
+  const rows = steps.map((s) => [
+    label(s.name),
+    s.kind === "total" ? (delta ? t.net : t.total) : s.value === null ? EMPTY_VALUE : signedText(s.value, formatter),
+    s.kind === "gap" ? EMPTY_VALUE : delta ? signedText(s.end, formatter) : formatter(s.end),
+  ])
+  // `delta`: the totals are not bars, so the opening / closing values are rows of their own (they are not in `steps`).
+  const end = (e: WaterfallDeltaEnds["opening"], role: string) =>
+    e && e.value !== null ? [[label(e.name), role, formatter(e.value)]] : []
+  return {
+    columns: [labels?.[names.index] ?? t.item, t.change, delta ? t.cumulativeChange : t.cumulative],
+    rows: delta ? [...end(delta.opening, t.start), ...rows, ...end(delta.closing, t.end)] : rows,
+  }
+}
+
+/* ----------------------------------------------------------------- option */
+
+export interface WaterfallOptionConfig {
+  steps: readonly WaterfallStep[]
+  /** Resolved (canvas-safe) colours; `""` leaves the theme palette. */
+  colors: { total: string; positive: string; negative: string; neutral: string }
+  polarity?: Polarity
+  labels?: Record<string, string>
+  /** Tooltip and value labels. */
+  valueFormatter: ValueFormatter
+  /** Value-axis ticks (short form). */
+  axisFormatter?: ValueFormatter
+  showValues?: boolean
+  showTooltip?: boolean
+  labelColor?: string
+  /** The plot's width (px), when known: every step name is shown (wrapped into its share, or tilted when narrow) and value labels that would collide are thinned. */
+  plotWidth?: number | null
+  chartOptions?: EChartsOption
+  /** Value-axis limits (see `WaterfallChartProps`): the axis always reaches 0 and widens to the data. */
+  minValue?: number
+  maxValue?: number
+  /** The value axis' label width (px); fixes the plot's left edge so stacked charts line up. */
+  yAxisWidth?: number
+  /** `"delta"`: only the moves are bars, the axis is the signed cumulative change, and `deltaNote` prints above the plot. */
+  mode?: WaterfallMode
+  /** `mode="delta"`: the note printed above the plot (opening → closing and the net change), and the signed value axis. */
+  deltaNote?: string
+  /** Text colour for the note (the muted token). */
+  noteColor?: string
+  /** Colour of the 1px line joining the bars' tops (the border token). `undefined` draws no connector. */
+  connectorColor?: string
+  /** Language of the tooltip. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+/** The bar fills 45% of its category band. ECharts reads `barCategoryGap` as a share of the band (not of the bar), so the gap is the other 55%; a gap over 100% leaves the bar at its 1px minimum. */
+const WATERFALL_BAR_SHARE = 0.45
+const WATERFALL_BAR_GAP = `${Math.round((1 - WATERFALL_BAR_SHARE) * 100)}%`
+
+/** The area tokens one step lighter: the same colour at 75% over the surface (light and dark alike). */
+export function waterfallSoftFill(color: string): string {
+  return color ? withAlpha(color, 0.75) : color
+}
+
+/**
+ * The 1px lines that join the tops of consecutive bars: [step index, level] per link. A link needs two real bars
+ * that meet at the same level (a gap, or a total whose own value breaks the running level, is not joined).
+ */
+export function waterfallConnectors(steps: readonly WaterfallStep[]): [number, number][] {
+  const links: [number, number][] = []
+  for (let i = 0; i < steps.length - 1; i++) {
+    const a = steps[i]!
+    const b = steps[i + 1]!
+    if (a.kind === "gap" || b.kind === "gap") continue
+    const meets = b.kind === "total" ? b.end === a.end : b.start === a.end
+    if (meets) links.push([i, a.end])
+  }
+  return links
+}
+
+/** The value-tick column and the grid's left / right margins, px: what the steps do not get of the plot's width. */
+const WATERFALL_GUTTER = 60 + 20
+
+/** The width (px) each step gets: the plot less the tick column and margins, shared by the steps. */
+export function stepSlotWidth(plotWidth: number, steps: number): number {
+  return Math.max(1, Math.floor((plotWidth - WATERFALL_GUTTER) / Math.max(1, steps)))
+}
+
+/** Below this slot (px) a step name no longer wraps into a readable column (under 3 full-width characters): it is tilted instead. */
+const STEP_LABEL_MIN_SLOT = 44
+
+/** Width (px) for a step's axis label: its slot less a gap. */
+export function stepLabelWidth(plotWidth: number, steps: number): number {
+  return Math.max(24, stepSlotWidth(plotWidth, steps) - 8)
+}
+
+/**
+ * How the step names sit on the axis at a plot width: wrapped into the step's slot when it fits a few
+ * characters, otherwise tilted (and not wrapped) so every name stays readable and none is dropped.
+ */
+export function stepLabelLayout(plotWidth: number, steps: number): { width: number; rotate: 0 } | { rotate: 45 } {
+  return stepSlotWidth(plotWidth, steps) >= STEP_LABEL_MIN_SLOT
+    ? { width: stepLabelWidth(plotWidth, steps), rotate: 0 }
+    : { rotate: 45 }
+}
+
+/**
+ * Which steps print their value on the bar at a plot width. Every label stays when they fit side by side;
+ * on a narrow plot the neighbours that would print over each other are dropped (the tooltip and the table still
+ * carry them): totals first, then the largest moves, each kept only if it clears the labels already kept.
+ * A decrease is never dropped: its label sits under its bar (away from the increases' labels above), and a decrease
+ * that would touch the previous decrease's label steps down a line (see `buildWaterfallOption`).
+ * `plotWidth` unknown → all shown.
+ */
+export function waterfallValueLabelPlan(
+  steps: readonly WaterfallStep[],
+  texts: readonly string[],
+  plotWidth?: number | null,
+): boolean[] {
+  const show = steps.map((s) => s.kind !== "gap")
+  if (!plotWidth) return show
+  const slot = stepSlotWidth(plotWidth, steps.length)
+  const kept: { center: number; half: number }[] = []
+  const order = steps
+    .map((_, i) => i)
+    .filter((i) => show[i])
+    .sort((a, b) => {
+      const rank = (i: number) => (steps[i]!.kind === "total" ? 0 : 1)
+      return rank(a) - rank(b) || Math.abs(steps[b]!.value ?? 0) - Math.abs(steps[a]!.value ?? 0) || a - b
+    })
+  for (const i of order) {
+    // Labels above a bar and labels under a bar never meet, so only the same side competes; decreases stay.
+    if (steps[i]!.kind === "decrease") continue
+    const center = (i + 0.5) * slot
+    const half = (estimateTextWidth(texts[i] ?? "") + 6) / 2
+    if (kept.some((k) => Math.abs(k.center - center) < k.half + half)) show[i] = false
+    else kept.push({ center, half })
+  }
+  return show
+}
+
+/** Gap (px) between a decrease label and the bar it hangs under; a stepped-down label adds one line. */
+const DECREASE_LABEL_DISTANCE = 4
+const DECREASE_LABEL_LINE = 14
+
+/**
+ * Where each decrease prints its value: under its bar (`"bottom"`), or — when the bar ends on the axis, where the step
+ * names are — above it (`"top"`). `lineDown` steps a label that would touch the previous decrease's label down one line.
+ */
+export function waterfallDecreaseLabels(
+  steps: readonly WaterfallStep[],
+  texts: readonly string[],
+  plotWidth?: number | null,
+): { position: "top" | "bottom"; lineDown: boolean }[] {
+  const top = Math.max(1, ...steps.map((s) => Math.abs(s.end)), ...steps.map((s) => Math.abs(s.start)))
+  const slot = plotWidth ? stepSlotWidth(plotWidth, steps.length) : null
+  let prev: { index: number; half: number; down: boolean } | null = null
+  return steps.map((step, i) => {
+    if (step.kind !== "decrease") return { position: "top", lineDown: false }
+    const lo = Math.min(step.start, step.end)
+    // A bar whose foot is within 8% of the axis' span of the 0 line has no room under it.
+    const position = lo >= 0 && lo / top < 0.08 ? ("top" as const) : ("bottom" as const)
+    const half = (estimateTextWidth(texts[i] ?? "") + 6) / 2
+    let lineDown = false
+    if (slot && position === "bottom" && prev && (i - prev.index) * slot < prev.half + half) lineDown = !prev.down
+    prev = position === "bottom" ? { index: i, half, down: lineDown } : prev
+    return { position, lineDown }
+  })
+}
+
+/** The `renderItem` of the connectors: a 1px line from the right edge of one bar to the left edge of the next, at the level they share. */
+export function waterfallConnectorRenderer(color: string | undefined) {
+  type Api = { value(dim: number): number; coord(value: number[]): number[]; size(value: number[]): number[] }
+  return (_params: unknown, api: Api) => {
+    const [x = 0, y = 0] = api.coord([api.value(0), api.value(1)])
+    const band = Math.abs(api.size([1, 0])[0] ?? 0)
+    const half = (band * WATERFALL_BAR_SHARE) / 2
+    // Snap to the pixel grid so the 1px line stays crisp.
+    const at = Math.round(y) + 0.5
+    return {
+      type: "line" as const,
+      silent: true,
+      shape: { x1: x + half, y1: at, x2: x + band - half, y2: at },
+      style: { stroke: color, lineWidth: 1, fill: "none" },
+    }
+  }
+}
+
+const ROW_STYLE = "display:flex;align-items:center;gap:8px;line-height:20px"
+
+/** The ECharts option: a transparent base plus the part above and below 0, coloured per step. */
+export function buildWaterfallOption(config: WaterfallOptionConfig): EChartsOption {
+  const { steps, colors, polarity, labels, valueFormatter, showValues = true, showTooltip = true } = config
+  const t = textOf(config.locale)
+  const delta = config.mode === "delta"
+  const axisFormatter = config.axisFormatter ?? valueFormatter
+  const noteWidth = config.plotWidth ? Math.max(120, config.plotWidth - 16) : undefined
+  const noteLines = delta && config.deltaNote ? Math.min(3, noteWidth ? Math.ceil(estimateTextWidth(config.deltaNote) / noteWidth) : 1) : 0
+  const gridTop = 28 + (noteLines > 0 ? 6 + noteLines * 16 : 0)
+  const hasNegative = delta && steps.some((s) => s.kind !== "gap" && Math.min(s.start, s.end) < 0)
+  const stack = waterfallStack(steps)
+  const stepTexts = steps.map((step) => waterfallStepText(step, valueFormatter, delta))
+  const valueShown = waterfallValueLabelPlan(steps, stepTexts, config.plotWidth)
+  const decreaseLabels = waterfallDecreaseLabels(steps, stepTexts, config.plotWidth)
+  // A decrease prints under its bar (on the below-0 part when the bar reaches below 0); every other step above its bar.
+  const labelSeries = (step: WaterfallStep, i: number): "pos" | "neg" =>
+    step.kind === "decrease" && Math.min(step.start, step.end) < 0 ? "neg" : stack.labelOn[i]!
+  const colorOf = (step: WaterfallStep) => colors[waterfallTone(step.kind, polarity)] || undefined
+  const series = (id: "pos" | "neg") => ({
+    id,
+    type: "bar" as const,
+    stack: "waterfall",
+    barCategoryGap: WATERFALL_BAR_GAP,
+    data: steps.map((step, i) => {
+      const decrease = decreaseLabels[i]!
+      const isDecrease = step.kind === "decrease"
+      return {
+        value: stack[id][i],
+        itemStyle: { color: colorOf(step), borderRadius: 2 },
+        label: {
+          show: showValues && valueShown[i] === true && labelSeries(step, i) === id,
+          position: isDecrease ? decrease.position : id === "pos" ? ("top" as const) : ("bottom" as const),
+          distance: isDecrease && decrease.position === "bottom" ? DECREASE_LABEL_DISTANCE + (decrease.lineDown ? DECREASE_LABEL_LINE : 0) : undefined,
+          formatter: () => waterfallStepText(step, valueFormatter, delta),
+        },
+      }
+    }),
+    label: { show: false, color: config.labelColor, fontVariantNumeric: "tabular-nums" },
+    // The 0 line is the start: with moves below it, draw it once on the first series so the two sides read as gain / loss.
+    ...(hasNegative && id === "pos"
+      ? {
+          markLine: {
+            silent: true,
+            symbol: "none",
+            animation: false,
+            label: { show: false },
+            lineStyle: { type: "solid" as const, width: 1, color: config.noteColor, opacity: 0.6 },
+            data: [{ yAxis: 0 }],
+          },
+        }
+      : {}),
+  })
+  const limits = valueAxisLimits({ minValue: config.minValue, maxValue: config.maxValue }, true)
+  const option = {
+    ...chartMotion(false),
+    legend: { show: false },
+    grid: { top: gridTop, right: 16, bottom: 4, left: 4, containLabel: true },
+    ...(noteLines > 0
+      ? {
+          graphic: [
+            {
+              type: "text" as const,
+              left: 4,
+              top: 0,
+              silent: true,
+              style: { text: config.deltaNote, fill: config.noteColor, fontSize: 12, lineHeight: 16, ...(noteWidth ? { width: noteWidth, overflow: "break" as const } : {}) },
+            },
+          ],
+        }
+      : {}),
+    tooltip: {
+      show: showTooltip,
+      trigger: "axis",
+      axisPointer: { type: "shadow" },
+      formatter: (params: unknown) => {
+        const list = (Array.isArray(params) ? params : [params]) as { dataIndex?: number }[]
+        const step = steps[list[0]?.dataIndex ?? 0]
+        if (!step) return ""
+        const color = escapeHtml(colorOf(step) ?? "currentColor")
+        const line = (name: string, text: string) =>
+          `<div style="${ROW_STYLE}"><span style="display:inline-block;width:8px;height:8px;border-radius:9999px;background:${color}"></span>` +
+          `<span style="flex:1;opacity:.8">${escapeHtml(name)}</span>` +
+          `<span style="font-weight:500;font-variant-numeric:tabular-nums;margin-left:12px">${escapeHtml(text)}</span></div>`
+        const rows =
+          step.kind === "total"
+            ? line(delta ? t.net : t.total, delta ? signedText(step.end, valueFormatter) : valueFormatter(step.end))
+            : line(t.change, waterfallStepText(step, valueFormatter)) +
+              (step.kind === "gap"
+                ? ""
+                : delta
+                  ? line(t.cumulativeChange, signedText(step.end, valueFormatter))
+                  : line(t.cumulative, valueFormatter(step.end)))
+        return `<div style="font-weight:500;margin-bottom:4px">${escapeHtml(labelOf(step.name, labels))}</div>${rows}`
+      },
+    },
+    xAxis: {
+      type: "category" as const,
+      data: steps.map((s) => s.name),
+      axisTick: { show: false },
+      // A negative cumulative change draws below 0: the names stay at the bottom edge, not on the 0 line.
+      ...(hasNegative ? { axisLine: { onZero: false } } : {}),
+      // Every step name stays (a dropped name makes a bar unreadable): wrapped into the step's share of the
+      // plot, or tilted when the share is too narrow to wrap into.
+      axisLabel: {
+        interval: 0,
+        hideOverlap: false,
+        formatter: (value: string) => labelOf(value, labels),
+        ...(config.plotWidth ? { ...stepLabelLayout(config.plotWidth, steps.length), overflow: "break" as const } : {}),
+      },
+    },
+    yAxis: {
+      type: "value" as const,
+      ...(config.minValue !== undefined || config.maxValue !== undefined ? limits : {}),
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: { show: true },
+      axisLabel: {
+        // Ticks are unsigned: the sign belongs to the bar labels, not the axis.
+        formatter: (v: number) => axisFormatter(v),
+        // A fixed width lines up side-by-side plots, but a value tick is never cut: the grid contains it.
+        width: config.yAxisWidth,
+      },
+    },
+    series: [
+      {
+        id: "base",
+        type: "bar" as const,
+        stack: "waterfall",
+        silent: true,
+        barCategoryGap: WATERFALL_BAR_GAP,
+        itemStyle: { color: "transparent", borderColor: "transparent" },
+        emphasis: { disabled: true },
+        data: stack.base,
+      },
+      series("pos"),
+      series("neg"),
+      {
+        id: "connectors",
+        type: "custom" as const,
+        silent: true,
+        z: 1,
+        tooltip: { show: false },
+        emphasis: { disabled: true },
+        // Every link is [step index, level]; the value axis already reaches each level (they are the bars' own ends).
+        encode: { x: 0, y: 1 },
+        data: waterfallConnectors(steps),
+        renderItem: waterfallConnectorRenderer(config.connectorColor),
+      },
+    ],
+  }
+  return mergeChartOptions(option as EChartsOption, config.chartOptions)
+}
+
+/* -------------------------------------------------------------- component */
+
+/** 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 WaterfallChartImpl<T extends Record<string, unknown>>(
+  {
+    data = NO_ROWS,
+    index,
+    categories = NO_ROWS,
+    totals,
+    mode = "total",
+    polarity = "higher-is-better",
+    labels,
+    format,
+    valueFormatter: valueFormatterProp,
+    showValues = true,
+    showTooltip = true,
+    title,
+    summary,
+    actions,
+    fileName,
+    isLoading,
+    emptyState,
+    height,
+    chartOptions,
+    minValue,
+    maxValue,
+    yAxisWidth,
+    ariaLabel,
+    className,
+    ...rest
+  }: WaterfallChartProps<T>,
+  ref: ForwardedRef<HTMLDivElement>,
+) {
+  const valueKey: string = categories[0] ?? ""
+  const { ref: frameRef, width: plotWidth, tokens } = useChartSurface(ref)
+  // Value labels and the tooltip read in full (as `format` says); ticks read short.
+  const locale = useLocale()
+  const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format, locale), [valueFormatterProp, format, locale])
+  const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatterProp, format, locale), [valueFormatterProp, format, locale])
+  const steps = useMemo(
+    () => waterfallSteps(data, { index, value: valueKey, totals, mode, locale }),
+    [data, index, valueKey, totals, mode, locale],
+  )
+  const ends = useMemo(() => (mode === "delta" ? waterfallDeltaEnds(data, { index, value: valueKey, totals }) : undefined), [data, index, valueKey, totals, mode])
+  const deltaNote = useMemo(() => (ends ? waterfallDeltaNote(ends, valueFormatter, labels, locale) : undefined), [ends, valueFormatter, labels, locale])
+  const colors = useMemo(() => {
+    const fills = resolveFillColors(tokens)
+    const [total = ""] = resolveChartColors(["chart-1"], tokens)
+    // The area tokens one step lighter, so the bars stay quieter than the numbers on them.
+    return {
+      total,
+      positive: waterfallSoftFill(fills.positive),
+      negative: waterfallSoftFill(fills.negative),
+      neutral: waterfallSoftFill(fills.neutral),
+    }
+  }, [tokens])
+  const option = useMemo(
+    () =>
+      buildWaterfallOption({
+        steps,
+        colors,
+        polarity,
+        labels,
+        valueFormatter,
+        axisFormatter,
+        showValues,
+        showTooltip,
+        labelColor: tokens?.foreground ?? undefined,
+        noteColor: tokens?.mutedForeground ?? undefined,
+        connectorColor: tokens?.border ?? undefined,
+        mode,
+        deltaNote,
+        plotWidth,
+        chartOptions,
+        minValue,
+        maxValue,
+        yAxisWidth,
+        locale,
+      }),
+    [steps, colors, polarity, labels, valueFormatter, axisFormatter, showValues, showTooltip, tokens, mode, deltaNote, plotWidth, chartOptions, minValue, maxValue, yAxisWidth, locale],
+  )
+  const dataTable = useMemo(
+    () => waterfallDataTable(steps, { index, value: valueKey }, valueFormatter, labels, ends, locale),
+    [steps, index, valueKey, valueFormatter, labels, ends, locale],
+  )
+  const resolvedSummary = useMemo(
+    () => (summary === "auto" ? buildWaterfallSummary(steps, valueFormatter, title, labels, ends, locale) : summary),
+    [summary, steps, valueFormatter, title, labels, ends, locale],
+  )
+  const t = textOf(locale)
+  const label = ariaLabel ?? t.chart(labelOf(valueKey, labels) || t.change.toLowerCase())
+  return (
+    <ChartFrame
+      {...chartRootProps(rest)}
+      ref={frameRef}
+      title={title}
+      summary={resolvedSummary}
+      isLoading={isLoading ?? false}
+      isEmpty={data.length === 0}
+      emptyState={emptyState}
+      height={height}
+      variant="bar"
+      ariaLabel={label}
+      className={className}
+      dataTable={dataTable}
+    >
+      <EChart option={option} height="100%" ariaLabel={label} actions={actions} fileName={fileName} exportHeader={{ title, summary: resolvedSummary }} />
+    </ChartFrame>
+  )
+}
+
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+export const WaterfallChart = forwardRef(WaterfallChartImpl as (props: WaterfallChartProps, ref: ForwardedRef<HTMLDivElement>) => ReactElement) as (<
+  T extends Record<string, unknown>,
+>(
+  props: WaterfallChartProps<T> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement) & { displayName?: string }
+WaterfallChart.displayName = "WaterfallChart"