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

package/registry/ui/donut-chart.tsx

@@ -1,21 +1,185 @@
 // Copied by `vantage add ui donut-chart`. This file is yours to edit.
-// Generated from @squadbase/vantage src/components/donut-chart.tsx by `npm run registry` (in Vantage, edit src/, not registry/).
+// Generated from @squadbase/squadkit registry/charts/donut-chart.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
 /**
- * DonutChart — a typed donut / pie chart over `EChart`: pass rows plus the
- * name column (`category`) and the value column (`value`). The donut prints a
- * label in its hole — the formatted total unless `label` says otherwise —
- * as plain HTML over the canvas, so it takes the page's type and colours.
+ * DonutChart — a typed donut / pie chart over `EChart`: pass rows, the label
+ * key (`index`) and the value key (`categories: [valueKey]`). Slices are sorted
+ * largest first and coloured with the `--chart-1..5` tokens in fixed order;
+ * more than 5 fold into one「その他」slice. The hole is empty by default (the
+ * total usually repeats a KPI); `donutOptions.centerLabel` picks `"total"`
+ * (「合計」+ the formatted total, plus `unit`), `"top"` (the largest slice and its
+ * share) or a custom node — plain HTML over the canvas, so it takes the page's
+ * type and colours. A share is printed once: the HTML legend lists every slice
+ * with its share, right of the ring when there is room, below it otherwise, and
+ * with the legend there are no outside labels (without it, a plot at least
+ * `DONUT_OUTSIDE_LABEL_MIN_WIDTH` wide labels its 2 largest slices).
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state,
+ * and a visually-hidden table of the slices).
  */
-import { forwardRef, useMemo, type ReactNode } from "react"
+import { forwardRef, useEffect, useMemo, useState, type ForwardedRef, type ReactElement, type ReactNode, type Ref } from "react"
 
-import { cn } from "@squadbase/vantage/ui"
+import { ChartFrame } from "@squadbase/vantage/components"
 import { EChart } from "@squadbase/vantage/components"
-import type { ChartColor, ChartEventPayload, ValueFormatter } from "@squadbase/vantage/components"
-import { useEffect, useState } from "react"
-import { useRef } from "react"
+import type { ChartCommonProps, ChartEventPayload, ChartSeriesColor } from "@squadbase/vantage/components"
+import { useSyncExternalStore } from "react"
+import { createContext, useCallback, useRef, type RefObject } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, formatValue, toValueFormatter, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartColor, ChartColors, ValueFormatter } from "@squadbase/vantage/components"
 import type { EChartsOption } from "@squadbase/vantage/components"
+import { computeComparison, defaultChangeDisplay, formatChange, toneForValue, type ComparisonKind, type PeriodGrain } from "@squadbase/vantage/components"
+import { DEFAULT_LOCALE } from "@squadbase/vantage/components"
+import type { ChartThreshold, ChartAnnotation, ChartForecast, ChartForecastRow, ChartHighlight, NumericKeys } from "@squadbase/vantage/components"
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The display language of the parts and the defaults that follow it.
+ *
+ * The language comes from `<html lang>`: a tag starting with `ja` reads Japanese, anything else English.
+ * Without a usable `lang` (missing, invalid, or no `document` — SSR, Node) the locale is `FALLBACK_LOCALE`
+ * (`en-US`). A `locale` passed explicitly (a prop, an argument) always wins.
+ *
+ * Parts read the locale through `useLocale` (`hooks/use-locale`) and pass it down; the pure helpers here
+ * and in `format` / `comparison` / `chart-*` take it as an argument and fall back to `documentLocale()`.
+ */
+
+/** The language of the built-in wording: Japanese or English. */
+type UiLanguage = "ja" | "en"
+
+/** The locale used when `<html lang>` gives none (and on the server). */
+const FALLBACK_LOCALE = "en-US"
+
+/** `"ja"` when `locale` starts with `ja` (`ja`, `ja-JP`), else `"en"`. A missing locale is `"en"`. */
+function uiLanguage(locale: string | null | undefined): UiLanguage {
+  return typeof locale === "string" && locale.trim().toLowerCase().startsWith("ja") ? "ja" : "en"
+}
+
+/** A BCP 47 tag in its canonical form (`en-gb` → `en-GB`), or `FALLBACK_LOCALE` when it is empty or invalid. */
+function normalizeLocale(tag: string | null | undefined): string {
+  const value = tag?.trim()
+  if (!value) return FALLBACK_LOCALE
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? FALLBACK_LOCALE
+  } catch {
+    return FALLBACK_LOCALE
+  }
+}
+
+/**
+ * The locale of the page: `document.documentElement.lang`, canonicalized. `FALLBACK_LOCALE` when it is empty or
+ * invalid, or there is no `document`. Parts read it through `useLocale`, never while rendering.
+ */
+function documentLocale(): string {
+  if (typeof document === "undefined") return FALLBACK_LOCALE
+  return normalizeLocale(document.documentElement?.getAttribute("lang"))
+}
+
+/** `locale` when given, else the page's locale (`documentLocale()`). */
+function resolveLocale(locale?: string | null): string {
+  return locale || documentLocale()
+}
+
+/** Picks the wording table of the locale's language. */
+function pickLocale<T>(table: { ja: T; en: T }, locale?: string | null): T {
+  return table[uiLanguage(resolveLocale(locale))]
+}
+
+/** The currency `format="currency"` uses without a `currency`: JPY for Japanese, USD otherwise. */
+function defaultCurrency(locale?: string | null): string {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? "JPY" : "USD"
+}
+
+/** The month a fiscal year starts in (1–12) when none is given: April for Japanese, January otherwise. */
+function defaultFiscalYearStartMonth(locale?: string | null): number {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? 4 : 1
+}
+
+/** A day of the week, 0 = Sunday … 6 = Saturday (the `Date#getDay` / date-fns numbering). */
+type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+/** Locales whose week starts on Sunday when the runtime has no week data. */
+const SUNDAY_FIRST = new Set(["en", "en-US", "en-CA"])
+
+/**
+ * The first day of the week: Monday for Japanese; otherwise the locale's convention from `Intl.Locale`
+ * (`en-US` Sunday, `en-GB` Monday). Without week data in the runtime: Sunday for `en` / `en-US` / `en-CA`,
+ * Monday for the rest.
+ */
+function weekStartsOn(locale?: string | null): WeekDay {
+  const tag = normalizeLocale(resolveLocale(locale))
+  if (uiLanguage(tag) === "ja") return 1
+  try {
+    const info = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number }
+      weekInfo?: { firstDay: number }
+    }
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay
+    if (typeof firstDay === "number" && firstDay >= 1 && firstDay <= 7) return (firstDay % 7) as WeekDay
+  } catch {
+    // Fall through to the table below.
+  }
+  return SUNDAY_FIRST.has(tag) ? 0 : 1
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/hooks/use-locale.ts (internal to @squadbase/vantage) ---------- */
+
+const listeners = new Set<() => void>()
+let observer: MutationObserver | null = null
+
+/** One observer on `<html lang>` for every subscribed part. */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {}
+  listeners.add(onChange)
+  if (!observer) {
+    observer = new MutationObserver(() => {
+      for (const listener of [...listeners]) listener()
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] })
+  }
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0 && observer) {
+      observer.disconnect()
+      observer = null
+    }
+  }
+}
+
+const serverLocale = () => FALLBACK_LOCALE
+
+/**
+ * The page's locale (`<html lang>`), following changes made while the page runs. On the server and during
+ * hydration it is `FALLBACK_LOCALE` (`en-US`), so the markup matches; it switches right after.
+ */
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
 
-/* ---------- inlined from src/components/chart-theme.ts (internal to @squadbase/vantage) ---------- */
+/** 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
@@ -23,6 +187,8 @@ const SERIES_TOKENS = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--ch
 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. */
@@ -31,10 +197,23 @@ interface ChartTokens {
   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. */
@@ -90,14 +269,19 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     const color = read(token)
     if (color) series.push(color)
   }
-  return {
+  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. */
@@ -105,8 +289,13 @@ 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 &&
@@ -129,7 +318,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
  *    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): () => void {
+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.
@@ -144,8 +333,11 @@ function watchChartTokens(onChange: () => void): () => void {
 
   const themeObserver = new MutationObserver(schedule)
   const attributeFilter = ["class", "style", "data-theme"]
-  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
-  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+  // 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) {
@@ -180,10 +372,11 @@ function watchChartTokens(onChange: () => void): () => void {
 function axisTheme(tokens: ChartTokens, splitLine: boolean) {
   const line = tokens.border ?? undefined
   return {
-    axisLine: { show: true, lineStyle: { color: line } },
-    axisTick: { show: true, lineStyle: { color: line } },
-    axisLabel: { show: true, color: tokens.mutedForeground ?? undefined },
-    splitLine: { show: splitLine, lineStyle: { color: line ? [line] : undefined } },
+    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 },
   }
 }
@@ -200,7 +393,7 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
     // 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 },
+    textStyle: { color: text, ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}) },
     title: { textStyle: { color: text }, subtextStyle: { color: muted } },
     legend: { textStyle: { color: muted } },
     categoryAxis: axisTheme(tokens, false),
@@ -208,10 +401,19 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
     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,
-      textStyle: { color: tokens.popoverForeground ?? undefined },
+      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 } },
     },
   }
@@ -223,27 +425,35 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  * 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(): ChartTokens | null {
+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 = () => {
-      setTokens((prev) => {
-        const next = readChartTokens()
-        return sameChartTokens(prev, next) ? prev : next
-      })
+      const next = readChartTokens(target)
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
     }
     sync()
-    return watchChartTokens(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; `var(--token)` is read off the document root; any
+ * 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".
  */
@@ -251,18 +461,121 @@ function resolveChartColors(colors: readonly string[], tokens: ChartTokens | nul
   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) {
-      const styles = getComputedStyle(document.documentElement)
       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) ?? ""
   })
 }
 
-/* ---------- inlined from src/components/chart-utils.ts (internal to @squadbase/vantage) ---------- */
+/** 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-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[] = [
@@ -275,13 +588,37 @@ const DEFAULT_CHART_COLORS: readonly ChartColor[] = [
 
 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) ? `var(--${value})` : value
+  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). */
@@ -305,6 +642,115 @@ 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.
@@ -324,6 +770,237 @@ 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"
@@ -336,6 +1013,78 @@ function sortBarListData<T extends { value: number }>(data: readonly T[], sortOr
   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)
@@ -343,6 +1092,102 @@ function barListWidths(values: readonly number[]): number[] {
   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 {
@@ -377,9 +1222,11 @@ interface CategoryBarLabel {
  * 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.
+ * 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): CategoryBarLabel[] {
+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 }]
@@ -389,7 +1236,46 @@ function categoryBarLabels(values: readonly number[], minGap = 8): CategoryBarLa
     if (label.position - prev.position >= minGap) labels.push(label)
     else if (i === segments.length - 1 && labels.length > 1) labels[labels.length - 1] = label
   })
-  return labels
+  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. */
@@ -434,26 +1320,219 @@ function progressCircleGeometry(
   return { size: radius * 2, normalizedRadius, circumference, offset: circumference * (1 - ratio), ratio }
 }
 
-/* ---------- inlined from src/components/chart-options.ts (internal to @squadbase/vantage) ---------- */
+/* ---------------------------------------------------------------- summary */
 
-type CartesianChartKind = "area" | "bar" | "line"
+interface ChartSummaryInput {
+  data: readonly Record<string, unknown>[]
+  /** The x-axis key. */
+  index: string
+  /** Series keys; the first one is described. */
+  categories: readonly string[]
+  /** Title of the chart, put in front when given. */
+  title?: string
+  /** Same as the chart's `format` (default `"compact"`). */
+  format?: ValueFormat
+  /** Wins over `format`. */
+  valueFormatter?: ValueFormatter
+  /** Language of the sentence. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+const SUMMARY_TEXT = {
+  ja: {
+    up: "、前の点より増加",
+    down: "、前の点より減少",
+    flat: "、前の点と横ばい",
+    latest: (label: string, value: string) => `最新 ${label} は ${value}`,
+    top: (name: string, share: string) => `最大は ${name}(${share})`,
+  },
+  en: {
+    up: ", up from the previous point",
+    down: ", down from the previous point",
+    flat: ", flat from the previous point",
+    latest: (label: string, value: string) => `Latest ${label}: ${value}`,
+    top: (name: string, share: string) => `Largest: ${name} (${share})`,
+  },
+}
+
+/**
+ * One-sentence summary built from the rows, for `summary="auto"`:
+ * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」("<title>: Latest <index>: <value>, up from the previous point"). The direction is
+ * computed from the last two non-empty points of the first series — never
+ * written by hand, so it cannot contradict the data. `undefined` when there is
+ * no usable point.
+ */
+function buildChartSummary(input: ChartSummaryInput): string | undefined {
+  const key = input.categories[0]
+  if (key === undefined) return undefined
+  const points: { label: string; value: number }[] = []
+  for (const row of input.data) {
+    const raw = row[key]
+    const value = raw === null || raw === undefined || raw === "" ? NaN : Number(raw)
+    if (Number.isFinite(value)) points.push({ label: String(row[input.index] ?? ""), value })
+  }
+  const latest = points[points.length - 1]
+  if (!latest) return undefined
+  const locale = resolveLocale(input.locale)
+  const t = SUMMARY_TEXT[uiLanguage(locale)]
+  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact", locale)
+  const prev = points[points.length - 2]
+  const direction = !prev ? "" : latest.value > prev.value ? t.up : latest.value < prev.value ? t.down : t.flat
+  const head = input.title ? `${input.title}: ` : ""
+  return `${head}${t.latest(latest.label, text(latest.value))}${direction}`
+}
+
+/**
+ * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」("<title>: Largest: <name> (<share>)") from the slices
+ * (largest first). `undefined` when there is nothing to describe. `locale` picks the language; default the page's.
+ */
+function buildShareSummary(
+  slices: readonly { name: string; value: number }[],
+  title?: string,
+  locale?: string,
+): string | undefined {
+  const total = slices.reduce((sum, s) => sum + s.value, 0)
+  const top = slices[0]
+  if (!top || total <= 0) return undefined
+  const share = `${Math.round((top.value / total) * 1000) / 10}%`
+  return `${title ? `${title}: ` : ""}${SUMMARY_TEXT[uiLanguage(resolveLocale(locale))].top(top.name, share)}`
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/chart-options.ts (internal to @squadbase/vantage) ---------- */
+
+/** The built-in words of the option builders, by language. */
+const CHART_TEXT = {
+  ja: {
+    target: "目標",
+    forecast: "予測",
+    total: "合計",
+    provisional: "速報",
+    noComparison: "比較なし",
+    share: (share: string) => `（${share}）`,
+    targetRate: (rate: string) => `（達成率 ${rate}）`,
+    provisionalTitle: (title: string, label: string) => `${title}(${label})`,
+  },
+  en: {
+    target: "Target",
+    forecast: "Forecast",
+    total: "Total",
+    provisional: "Preliminary",
+    noComparison: "No comparison",
+    share: (share: string) => ` (${share})`,
+    targetRate: (rate: string) => ` (${rate} achieved)`,
+    provisionalTitle: (title: string, label: string) => `${title} (${label})`,
+  },
+} satisfies Record<UiLanguage, unknown>
+
+const chartText = (locale?: string) => CHART_TEXT[uiLanguage(resolveLocale(locale))]
+
+type CartesianChartKind = "area" | "bar" | "line"
 type CartesianStackType = "default" | "stacked" | "percent"
 type CartesianCurveType = "linear" | "smooth" | "step"
 type AreaFill = "gradient" | "solid" | "none"
 type BarLayout = "horizontal" | "vertical"
 
+/** AreaChart-only settings. */
+interface AreaChartOptions {
+  /** `"stacked"` は積み上げ、`"percent"` は各点の合計を 100% にした積み上げ。既定 `"default"`。 */
+  type?: CartesianStackType
+  /** 線の形。既定 `"linear"`。 */
+  curveType?: CartesianCurveType
+  /** 面の塗り。既定 `"gradient"`。 */
+  fill?: AreaFill
+  /** 値の欠けた点(`null` など)をまたいで線をつなぐ。既定 `false`。 */
+  connectNulls?: boolean
+}
+
+/** LineChart-only settings. */
+interface LineChartOptions {
+  /** 線の形。既定 `"linear"`。 */
+  curveType?: CartesianCurveType
+  /** 値の欠けた点(`null` など)をまたいで線をつなぐ。既定 `false`。 */
+  connectNulls?: boolean
+  /** 値軸を 0 からではなくデータの範囲に合わせる。既定 `false`(0 起点)。最小の目盛ラベルは先頭の x ラベルと重なるので出さない(グリッド線は残る)。 */
+  fitToData?: boolean
+  /**
+   * 目標線(`target`)のラベルの置き場所。`"start"`(既定)は線の左端の上(最大・最新の強調と近いときは下)。
+   * `"end"` は線の右端の上。`"legend"` は凡例だけに出し、線の上には出さない(線の周りが混み合うとき)。
+   * 目標の呼び名は、どれを選んでも凡例に出る。
+   */
+  targetLabelPosition?: LineTargetLabelPosition
+}
+
+/** Where a line chart prints its target label: at the line's left end, its right end, or in the legend only. */
+type LineTargetLabelPosition = "start" | "end" | "legend"
+
+/** BarChart-only settings. */
+interface BarChartOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** `"stacked"` は積み上げ、`"percent"` は各カテゴリの合計を 100% にした積み上げ。既定 `"default"`(横並び)。 */
+  type?: CartesianStackType
+  /**
+   * 棒の向き。既定 `"horizontal"`(カテゴリが横に並ぶ縦棒)。`"vertical"` はカテゴリを
+   * 縦に並べた横棒で、ラベルの長いランキングに向く(先頭の行が一番上)。
+   */
+  layout?: BarLayout
+  /** カテゴリ間の隙間(`"20%"` や px)。省略時は ECharts の既定。 */
+  barCategoryGap?: string | number
+  /**
+   * 値が 0 の棒に「0」の値ラベルを付ける。棒が描かれない 0 が「データなし」に見えるのを防ぐ
+   * (在庫 0・件数 0 など)。積み上げでは付けない。0 以外の棒の見た目は変わらない。既定 `true`。
+   */
+  showZeroValues?: boolean
+  /**
+   * 棒ごとの目標値が入った `data` の列名(行ごとの目標。店舗別の月次目標など)。各棒に短い目標マーカーを
+   * 引き、ツールチップに「目標 … (達成率 …%)」を足す。凡例に目標の呼び名(`targetLabel`、既定「目標」)が出る。
+   * 1 系列の棒と積み上げ(達成率は合計に対して)で使える。横並びの複数系列と 100% 積み上げでは描かない。
+   * 値が欠けた(null・0 以下の)行はマーカーを引かない。
+   *
+   * 優先順位: `targetKey` を渡すと 1 本の目標線 `target` は描かない(`targetLabel` はマーカーの呼び名として使う)。
+   * 値による色分け `thresholds` とは併用できる(色は棒、マーカーは目標)。値軸は最大の目標を含む。
+   * 例: `barOptions={{ targetKey: "月次目標" }}`
+   */
+  targetKey?: NumericKeys<T>
+  /**
+   * 横棒(`layout: "vertical"`)の 1 系列で伝えたい 1 本。`index` の値で渡す(例 `"東京店"`)。
+   * 横棒は淡い色(`--chart-1` の薄い塗り)が既定で、この 1 本だけ濃い色(系列色そのまま)になる。省略すると全部が淡い色。
+   * 縦棒・複数系列・積み上げでは効かない(色は変わらない)。意味色の `thresholds` に当たった棒はそちらの色が優先。
+   * 例: `barOptions={{ layout: "vertical", highlight: "東京店" }}`
+   */
+  highlight?: string | number
+}
+
 /** Props every cartesian typed chart (Area / Bar / Line) shares. */
-interface CartesianChartBaseProps {
-  /** 行の配列。1 行 = x 軸の 1 点。数値の列は number か数値文字列(SQL の DECIMAL など)。 */
-  data: Record<string, unknown>[]
-  /** x 軸(カテゴリ軸)に使う列名。 */
-  index: string
-  /** 系列として描く列名。並び順が凡例と配色の順になる。 */
-  categories: string[]
-  /** 系列色。`"chart-1"`〜`"chart-5"` か CSS カラー。省略時はテーマのトークン順。足りなければ繰り返す。 */
-  colors?: ChartColor[]
-  /** 軸目盛りとツールチップの数値の書式。 */
-  valueFormatter?: ValueFormatter
+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`。 */
@@ -466,9 +1545,18 @@ interface CartesianChartBaseProps {
   startEndOnly?: boolean
   /** y 軸ラベルの幅(px)。並べた複数グラフのプロット領域を揃えたいときに固定する。 */
   yAxisWidth?: number
+  /**
+   * 値軸の下限。Bar / Area は常に 0 起点なので、0 以下の値だけ有効(負の値の下に余白を取る。正の値は無視)。
+   * Line は指定した値から始める。データが下限を下回るときは軸を広げる(切り詰めない)。
+   * 並べて比べる複数のグラフには同じ値を渡して軸をそろえる。
+   */
   minValue?: number
+  /**
+   * 値軸の上限(横棒は横軸)。データが上限を超えるときは軸を広げる(切り詰めない)。
+   * 並べて比べる複数のグラフには同じ値を渡して軸をそろえる。
+   */
   maxValue?: number
-  /** 値軸を 0 からではなくデータの範囲に合わせる。 */
+  /** @deprecated `lineOptions.fitToData` を使う。Bar / Area では無視される(常に 0 起点)。 */
   autoMinValue?: boolean
   /** `false` で値軸の目盛りを整数に限る。 */
   allowDecimals?: boolean
@@ -479,11 +1567,8 @@ interface CartesianChartBaseProps {
    * 足して渡し、同じ点をもう一度クリックすると `null`。渡すと選択以外が薄くなる。
    */
   onValueChange?: (value: ChartEventPayload) => void
-  /** 高さ。数値は px。省略時は `h-80`(320px)で、`className` の高さクラスが勝つ。 */
-  height?: string | number
+  /** @deprecated `isLoading` を使う。 */
   loading?: boolean
-  ariaLabel?: string
-  className?: string
 }
 
 /** The point a user clicked, used to dim everything else. */
@@ -492,6 +1577,17 @@ interface ChartActivePoint {
   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>[]
@@ -499,7 +1595,23 @@ interface CartesianChartConfig {
   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
@@ -513,9 +1625,14 @@ interface CartesianChartConfig {
   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
@@ -523,8 +1640,315 @@ interface CartesianChartConfig {
   /** 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
@@ -580,23 +2004,178 @@ 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
 }
 
-/** The tooltip body: a title, then one `● name  value` row per series. */
-function tooltipHtml(title: string, rows: readonly TooltipRow[], valueFormatter: (value: number) => string): 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:500;font-variant-numeric:tabular-nums;margin-left:12px">${
-        row.value === null ? "–" : escapeHtml(valueFormatter(row.value))
-      }</span></div>`,
+      `<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("")}`
+  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
@@ -604,6 +2183,244 @@ interface AxisTooltipParam {
 
 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,
@@ -611,7 +2428,11 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     index,
     categories,
     palette,
+    labels: nameLabels,
+    thresholds,
+    toneColors,
     valueFormatter,
+    axisFormatter = valueFormatter,
     type = "default",
     layout = "horizontal",
     curveType = "linear",
@@ -627,38 +2448,321 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     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 labels = data.map((row) => String(row[index] ?? ""))
-  const values = cartesianSeriesValues(data, categories, kind === "line" ? "default" : type)
   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,
+  )
 
-  const series = categories.map((category, c) => {
-    const color = palette[c] || undefined
+  /*
+   * -- 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 radius = stacked ? 0 : horizontalBars ? [0, 3, 3, 0] : [3, 3, 0, 0]
+      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 },
-        emphasis: { focus: "series" as const },
-        data: values[c]!.map((value, i) =>
-          active !== null && !(active.category === category && active.index === i)
-            ? { value, itemStyle: { opacity: DIMMED } }
-            : value,
-        ),
+        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 =
@@ -674,12 +2778,13 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
                 x2: 0,
                 y2: 1,
                 colorStops: [
-                  { offset: 0, color: withAlpha(color, 0.35) },
+                  { 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,
@@ -688,16 +2793,357 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
       connectNulls,
       symbol: "circle",
       symbolSize: 6,
-      showSymbol: showDots || labels.length === 1,
-      lineStyle: { width: 2, color, opacity: dimSeries ? DIMMED : 1 },
+      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,
-      emphasis: { focus: "series" as const },
-      data: values[c]!,
+      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,
@@ -706,48 +3152,137 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     axisTick: { show: false },
     axisLabel: {
       hideOverlap: true,
-      interval: startEndOnly ? (i: number) => i === 0 || i === last : ("auto" as const),
-      ...(horizontalBars && yAxisWidth != null ? { width: yAxisWidth, overflow: "truncate" as const } : {}),
+      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,
-    min: percent ? 0 : minValue,
-    max: percent ? 100 : maxValue,
-    scale: autoMinValue && minValue == null,
+    // 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) => valueFormatter(v),
-      ...(!horizontalBars && yAxisWidth != null ? { width: yAxisWidth, overflow: "truncate" as const } : {}),
+      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,
   }
 
-  return {
-    animationDuration: 400,
+  const legendItems = [
+    ...categories,
+    ...(forecast ? [forecastLabel] : []),
+    ...(provStart !== -1 ? [provisionalLabel] : []),
+    ...(barTargets ? [barTargetName] : []),
+    ...(hasTarget ? [targetText] : []),
+  ]
+  const option = {
+    ...chartMotion(reducedMotion),
     legend: {
       show: showLegend,
       top: 0,
-      right: 0,
-      type: "scroll",
+      // 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 ? 36 : 12,
-      // Lines start and end on the outermost ticks, so the last label hangs past the plot.
-      right: kind === "bar" ? 12 : 24,
+      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,
@@ -759,38 +3294,249 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
       formatter: (params: unknown) => {
         const list = (Array.isArray(params) ? params : [params]) as AxisTooltipParam[]
         const i = list[0]?.dataIndex ?? 0
-        const row = data[i] ?? {}
-        return tooltipHtml(
-          String(row[index] ?? ""),
-          list.map((p) => ({
-            name: p.seriesName ?? "",
-            color: typeof p.color === "string" ? p.color : "currentColor",
-            value: cellNumber(row[p.seriesName ?? ""]),
-          })),
-          valueFormatter,
-        )
+        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,
-  } as EChartsOption
+  }
+  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 {
-  data: readonly Record<string, unknown>[]
-  category: string
-  value: string
-  /** Resolved slice colours, by row position. `""`/missing → theme palette. */
+  /** 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. */
@@ -808,10 +3554,41 @@ interface ItemTooltipParam {
   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 { data, category, value, palette, valueFormatter, variant = "donut", showTooltip = true, active = null } = cfg
-  return {
-    animationDuration: 400,
+  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",
@@ -820,37 +3597,49 @@ function buildDonutOption(cfg: DonutChartConfig): EChartsOption {
         const n = cellNumber(p.value)
         const share = typeof p.percent === "number" ? ` (${p.percent.toFixed(1)}%)` : ""
         return tooltipHtml(
-          `${p.name ?? ""}${share}`,
-          [{ name: value, color: typeof p.color === "string" ? p.color : "currentColor", value: n }],
+          `${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" ? ["72%", "100%"] : [0, "100%"],
+        radius: variant === "donut" ? [`${donutHoleRatio(withLabels) * 100}%`, outer] : [0, outer],
         center: ["50%", "50%"],
         avoidLabelOverlap: true,
-        label: { show: false },
-        labelLine: { show: false },
+        // 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: data.length > 1 ? 1 : 0,
+        padAngle: slices.length > 1 ? 1 : 0,
         itemStyle: { borderRadius: variant === "donut" ? 2 : 0 },
         emphasis: { scale: true, scaleSize: 4 },
-        data: data.map((row, i) => {
-          const name = String(row[category] ?? "")
-          const color = palette[i] || undefined
-          const n = cellNumber(row[value])
-          return {
-            name,
-            value: n !== null && n > 0 ? n : 0,
-            itemStyle: { color, opacity: active !== null && active !== name ? DIMMED : 1 },
-          }
-        }),
+        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 },
+              }
+            : {}),
+        })),
       },
     ],
-  } as EChartsOption
+  }
+  return mergeChartOptions(option as EChartsOption, chartOptions)
 }
 
 /* -------------------------------------------------------------- selection */
@@ -913,92 +3702,305 @@ function useChartSelection(
   return { active: interactive ? active : null, onEvents }
 }
 
+/**
+ * Display name for `key`: `labels[key]` when present, else `key` itself.
+ * (Own keys only, so `"constructor"` is not looked up on the prototype.)
+ */
+function labelOf(key: string, labels?: Readonly<Record<string, string>>): string {
+  return hasLabel(labels, key) ? labels![key]! : key
+}
+
+/** `data` with each row's `index` cell replaced by its display name (rows are copied, not mutated). */
+function labelRows<Row extends Record<string, unknown>>(
+  data: readonly Row[],
+  index: string,
+  labels?: Readonly<Record<string, string>>,
+): Row[] {
+  if (!labels) return data as Row[]
+  return data.map((row) => ({ ...row, [index]: labelOf(String(row[index] ?? ""), labels) }))
+}
+
+/** Whether `labels` renames `key` (own keys only). */
+function hasLabel(labels: Readonly<Record<string, string>> | undefined, key: string): boolean {
+  return Boolean(labels) && Object.prototype.hasOwnProperty.call(labels, key)
+}
+
+/* ------------------------------------------------------------ provisional */
+
+/** The default label for points that are not final yet, in `locale`: "Preliminary" / 「速報」. Default the page's locale. */
+function defaultProvisionalLabel(locale?: string): string {
+  return chartText(locale).provisional
+}
+
+/**
+ * Position of the first provisional point: the first entry of `indexValues`
+ * that equals `from` (compared as text, so `"2026-09"` and a Date-less string
+ * key both work). `-1` when `from` is unset or not among the values — the chart
+ * then draws everything as confirmed.
+ */
+function provisionalStart(indexValues: readonly unknown[], from: string | number | undefined | null): number {
+  if (from === undefined || from === null) return -1
+  const key = String(from)
+  return indexValues.findIndex((value) => String(value ?? "") === key)
+}
+
+/**
+ * Split one series at `start` (see `provisionalStart`). `confirmed` keeps the
+ * points before `start`; `provisional` keeps `start` onward plus the last
+ * confirmed point, so the dashed line joins the solid one. `start <= 0` or
+ * `-1` leaves nothing to join (all provisional / none provisional).
+ */
+function splitProvisional(
+  values: readonly (number | null)[],
+  start: number,
+): { confirmed: (number | null)[]; provisional: (number | null)[] } {
+  if (start < 0) return { confirmed: [...values], provisional: values.map(() => null) }
+  return {
+    confirmed: values.map((v, i) => (i < start ? v : null)),
+    provisional: values.map((v, i) => (i >= Math.max(0, start - 1) ? v : null)),
+  }
+}
+
 /* ---------- end of inlined code ---------- */
 
-export interface DonutChartProps {
-  /** 行の配列。1 行 = 1 切片。 */
-  data: Record<string, unknown>[]
+export interface DonutChartProps<T extends Record<string, unknown> = Record<string, unknown>>
+  extends Omit<ChartCommonProps<T>, "index" | "categories" | "colors"> {
   /** 切片の名前に使う列名。 */
-  category: string
-  /** 切片の大きさに使う列名(number か数値文字列)。0 以下と欠損は 0 扱い。 */
-  value: string
-  /** 切片の色(行の順)。`"chart-1"`〜`"chart-5"` か CSS カラー。省略時はトークン順で、足りなければ繰り返す。 */
-  colors?: ChartColor[]
-  /** `"donut"`(中央に穴とラベル)か `"pie"`。既定 `"donut"`。 */
-  variant?: DonutVariant
-  /** ツールチップと中央ラベルの数値の書式。 */
-  valueFormatter?: ValueFormatter
-  /** 中央ラベル。省略時は合計を `valueFormatter` で書いたもの。donut のみ。 */
-  label?: ReactNode
-  /** 中央ラベルを出す。既定 `true`(donut のみ)。 */
-  showLabel?: boolean
+  index?: keyof T & string
+  /** 切片の大きさに使う列名を 1 つだけ入れた配列(`["売上"]`)。2 つ以上渡しても最初の 1 つだけを使う。 */
+  categories?: (keyof T & string)[]
+  /** 切片の色(大きい順)。`"chart-1"`〜`"chart-5"` か意味色(`"positive"` など。面用の `--<tone>-fill` で塗る)。省略時はトークン順。「その他」は常に灰色。 */
+  colors?: ChartSeriesColor[]
+  /** 切片の名前(`index` の値)→ 表示名。凡例・ツールチップ・外ラベル・データ表に反映。例 `{ organic: "自然検索" }`。無いキーはそのまま。データ表の列名を直すには、`index` と値のキーも渡す(`{ source: "流入元", sessions: "セッション" }`。既定は「項目」「値」)。 */
+  labels?: Record<string, string>
+  /** ドーナツ固有の設定(形・中央に出すもの `centerLabel`・凡例・切片の上限)。同名のフラットな props より優先。 */
+  donutOptions?: DonutChartOptions
+  /**
+   * グラフが言っていることの 1 文要約(自由文)。`"auto"` なら slices から「<見出し>: 最大は <名前>(<構成比>)」を組む。
+   * 順位や構成比を文に書くなら `"auto"` を使うか data から作る。省略時は要約なし。例: `summary="auto"`
+   */
+  summary?: string | "auto"
   showTooltip?: boolean
   /** 切片のクリックで呼ばれる。同じ切片をもう一度クリックすると `null`。渡すと選択以外が薄くなる。 */
   onValueChange?: (value: ChartEventPayload) => void
+  /** @deprecated `index` を使う。 */
+  category?: keyof T & string
+  /** @deprecated `categories={[value]}` を使う。 */
+  value?: keyof T & string
+  /** @deprecated `donutOptions.variant` を使う。 */
+  variant?: DonutVariant
+  /** @deprecated `donutOptions.centerLabel` を使う。 */
+  label?: ReactNode
+  /** @deprecated `donutOptions.centerLabel`(`"none"` で消す)を使う。 */
+  showLabel?: boolean
+  /** @deprecated `isLoading` を使う。 */
   loading?: boolean
-  ariaLabel?: string
-  /** 外枠のクラス。既定の大きさは `size-40`(160px 四方)。 */
-  className?: string
 }
 
-export const DonutChart = forwardRef<HTMLDivElement, DonutChartProps>(function DonutChart(
+const TEXT = {
+  ja: { item: "項目", value: "値", chart: (shares: readonly string[]) => `構成比のドーナツグラフ（${shares.join("、")}）` },
+  en: { item: "Item", value: "Value", chart: (shares: readonly string[]) => `Donut chart of shares (${shares.join(", ")})` },
+}
+
+/** The element's width, kept current (`null` until measured). */
+function useElementWidth(): [(el: HTMLDivElement | null) => void, number | null] {
+  const [node, setNode] = useState<HTMLDivElement | null>(null)
+  const [width, setWidth] = useState<number | null>(null)
+  useEffect(() => {
+    if (!node || typeof ResizeObserver === "undefined") return
+    setWidth(node.getBoundingClientRect().width)
+    const observer = new ResizeObserver((entries) => setWidth(entries[0]?.contentRect.width ?? null))
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node])
+  return [setNode, width]
+}
+
+/** 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 DonutChartImpl<T extends Record<string, unknown>>(
   {
-    data,
-    category,
-    value,
+    data = NO_ROWS,
+    index,
+    categories,
     colors,
-    variant = "donut",
-    valueFormatter = defaultValueFormatter,
-    label,
-    showLabel = true,
+    labels,
+    format,
+    valueFormatter: valueFormatterProp,
+    title,
+    summary,
+    actions,
+    fileName,
+    isLoading,
+    loading,
+    emptyState,
+    height,
+    chartOptions,
+    donutOptions,
     showTooltip = true,
     onValueChange,
-    loading,
+    category,
+    value,
+    variant,
+    label,
+    showLabel,
     ariaLabel,
     className,
-  },
-  ref,
+    ...rest
+  }: DonutChartProps<T>,
+  ref: ForwardedRef<HTMLDivElement>,
 ) {
-  const tokens = useChartTokens()
-  const palette = useMemo(
-    () => resolveChartColors(chartColorsFor(colors, data.length), tokens),
-    [colors, data.length, tokens],
+  const labelKey: string = index ?? category ?? ""
+  const valueKey: string = categories?.[0] ?? value ?? ""
+  const shape = donutOptions?.variant ?? variant ?? "donut"
+  const center = resolveDonutCenter(donutOptions?.centerLabel, { showLabel: donutOptions?.showLabel ?? showLabel, label })
+  const maxSlices = donutOptions?.maxSlices
+  const showLegend = donutOptions?.showLegend ?? true
+  const locale = useLocale()
+  const t = TEXT[uiLanguage(locale)]
+  const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format, locale), [valueFormatterProp, format, locale])
+
+  const { ref: frameRef, tokens } = useChartSurface(ref)
+  const slices = useMemo(
+    () =>
+      donutSlices(data, { index: labelKey, value: valueKey, colors, maxSlices, otherColor: CHART_OTHER_COLOR, otherLabel: otherSeriesLabel(locale) }),
+    [data, labelKey, valueKey, colors, maxSlices, locale],
   )
-  const { active, onEvents } = useChartSelection(data, onValueChange, "slice")
+  const palette = useMemo(() => resolveChartColors(slices.map((s) => chartFillName(s.color)), tokens), [slices, tokens])
+  const rows = useMemo(() => slices.map((s) => s.row), [slices])
+  const { active, onEvents } = useChartSelection(rows, onValueChange, "slice")
+  const [plotRef, plotWidth] = useElementWidth()
+  // The legend carries every share, so outside labels (name + share) only stand in for it when it is hidden.
+  const outsideLabels = donutOutsideLabelCount(plotWidth, showLegend)
+  const holeRatio = donutHoleRatio(outsideLabels > 0)
   const option = useMemo(
     () =>
       buildDonutOption({
-        data,
-        category,
-        value,
+        slices,
         palette,
+        labels,
         valueFormatter,
-        variant,
+        valueName: valueKey,
+        variant: shape,
         showTooltip,
+        outsideLabels,
         active: active?.category ?? null,
+        labelColor: tokens?.foreground ?? undefined,
+        chartOptions,
       }),
-    [data, category, value, palette, valueFormatter, variant, showTooltip, active],
+    [slices, palette, labels, valueFormatter, valueKey, shape, showTooltip, outsideLabels, active, tokens, chartOptions],
+  )
+  const total = slices.reduce((sum, s) => sum + s.value, 0)
+  const legend = useMemo(() => donutLegendItems(slices), [slices])
+  // Sized off the hole (cqmin of the plot): the small caption above, the big figure, the unit small below.
+  const hole = holeRatio * 100
+  const captionStyle = { fontSize: `clamp(10px, ${hole * 0.1}cqmin, 14px)` }
+  const figureStyle = { fontSize: `clamp(14px, ${hole * 0.22}cqmin, 32px)` }
+  const caption = (label: string, amount: string, unit?: string) => (
+    <span className="flex flex-col items-center gap-[0.15em] whitespace-nowrap">
+      <span className="max-w-full truncate font-normal text-muted-foreground" style={captionStyle}>
+        {label}
+      </span>
+      <span className="leading-none" style={figureStyle}>
+        {amount}
+      </span>
+      {unit && (
+        <span className="font-normal text-muted-foreground" style={captionStyle}>
+          {unit}
+        </span>
+      )}
+    </span>
+  )
+  let centerLabel: ReactNode = null
+  if (center.kind === "custom") centerLabel = center.node
+  else if (center.kind === "total") {
+    const text = donutCenterText(total, valueFormatter, { totalLabel: donutOptions?.totalLabel, unit: donutOptions?.unit, locale })
+    centerLabel = caption(text.label, text.amount, text.unit)
+  } else if (center.kind === "top") {
+    const top = donutTopText(slices, labels)
+    centerLabel = top && caption(top.label, top.amount)
+  }
+  // Built from the slices (names and shares), not the column keys.
+  const a11yLabel = ariaLabel ?? t.chart(legend.map((item) => `${labelOf(item.name, labels)} ${item.share}`))
+  const dataTable = useMemo(
+    () =>
+      chartDataTable(
+        // Fixed keys, so `labels` (which renames the rows) cannot collide with the column names.
+        rows.map((row) => ({ name: labelOf(String(row[labelKey] ?? ""), labels), value: row[valueKey] })),
+        "name",
+        ["value"],
+        valueFormatter,
+        { name: labels?.[labelKey] ?? t.item, value: labels?.[valueKey] ?? t.value },
+      ),
+    [rows, labelKey, valueKey, valueFormatter, labels, t],
   )
-  const centerLabel = label ?? valueFormatter(donutTotal(data, value))
 
+  const resolvedSummary = useMemo(
+    () => (summary === "auto" ? buildShareSummary(slices, title, locale) : summary),
+    [summary, slices, title, locale],
+  )
   return (
-    <div ref={ref} data-slot="donut-chart" className={cn("relative size-40", className)}>
-      <EChart
-        option={option}
-        onEvents={onEvents}
-        loading={loading}
-        ariaLabel={ariaLabel ?? `${category}別の${value}`}
-        className="h-full"
-      />
-      {variant === "donut" && showLabel && (
-        <div
-          data-slot="donut-chart-label"
-          className="pointer-events-none absolute inset-0 flex items-center justify-center px-[18%] text-center text-lg font-semibold text-foreground tabular-nums"
-        >
-          {centerLabel}
+    <ChartFrame
+      {...chartRootProps(rest)}
+      ref={frameRef}
+      title={title}
+      summary={resolvedSummary}
+      isLoading={isLoading ?? loading ?? false}
+      isEmpty={data.length === 0}
+      emptyState={emptyState}
+      height={height}
+      variant="donut"
+      ariaLabel={a11yLabel}
+      dataTable={dataTable}
+      className={className}
+    >
+      <div data-slot="donut-chart" className="@container/donut h-full w-full">
+        <div className="flex h-full w-full flex-col gap-3 @md/donut:flex-row @md/donut:items-center">
+          {/* A size container, so the center label can be sized in `cqmin` against the ring. */}
+          <div ref={plotRef} className="relative min-h-0 min-w-0 flex-1 @md/donut:h-full" style={{ containerType: "size" }}>
+            <EChart option={option} onEvents={onEvents} height="100%" ariaLabel={a11yLabel} actions={actions} fileName={fileName} exportHeader={{ title, summary: resolvedSummary }} />
+            {shape === "donut" && centerLabel !== null && centerLabel !== false && (
+              <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+                {/* A box inscribed in the hole: never wider than the ring's inside, text never wraps mid-word. */}
+                <div
+                  data-slot="donut-chart-label"
+                  className="flex items-center justify-center overflow-hidden text-center leading-tight font-semibold whitespace-nowrap text-foreground tabular-nums"
+                  style={{ width: `${hole * 0.78}cqmin`, height: `${hole * 0.78}cqmin` }}
+                >
+                  {centerLabel}
+                </div>
+              </div>
+            )}
+          </div>
+          {showLegend && legend.length > 0 && (
+            <ul
+              data-slot="donut-chart-legend"
+              className="flex shrink-0 flex-wrap gap-x-4 gap-y-1 text-xs @md/donut:w-44 @md/donut:flex-col @md/donut:flex-nowrap"
+            >
+              {legend.map((item) => (
+                <li key={item.slice} data-slot="donut-chart-legend-item" className="flex min-w-0 items-center gap-1.5">
+                  <span
+                    aria-hidden="true"
+                    className="size-2.5 shrink-0 rounded-[2px]"
+                    style={{ background: chartFillToCss(slices[item.slice]!.color) }}
+                  />
+                  <span className="min-w-0 truncate text-muted-foreground">{labelOf(item.name, labels)}</span>
+                  <span className="ml-auto pl-2 font-medium text-foreground tabular-nums">{item.share}</span>
+                </li>
+              ))}
+            </ul>
+          )}
         </div>
-      )}
-    </div>
+      </div>
+    </ChartFrame>
   )
-})
+}
+
+/** Generic over the row type, so `index` / `categories` keys are checked against `data`. */
+export const DonutChart = forwardRef(DonutChartImpl as (props: DonutChartProps, ref: ForwardedRef<HTMLDivElement>) => ReactElement) as (<
+  T extends Record<string, unknown>,
+>(
+  props: DonutChartProps<T> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement) & { displayName?: string }
 DonutChart.displayName = "DonutChart"