@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.81c1bbe

package/registry/ui/echart.tsx

@@ -1,5 +1,7 @@
 // Copied by `vantage add ui echart`. This file is yours to edit.
-// Generated from @squadbase/vantage src/components/echart.tsx by `npm run registry` (in Vantage, edit src/, not registry/).
+// Generated from @squadbase/squadkit registry/charts/echart.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
 /**
  * EChart — a thin Apache ECharts wrapper. It owns the canvas lifecycle (init,
  * resize, dispose), forwards `option` and event handlers, drives the loading
@@ -11,16 +13,71 @@
  * have changed — a light/dark flip, or a stylesheet swap such as editing
  * `styles.css` while the dev server is running. `theme` opts out entirely;
  * `option.color` overrides just the palette and keeps the rest.
+ *
+ * Pitfall: the canvas can't read CSS. A colour written into the option as
+ * `"var(--chart-1)"`, `"chart-1"` or `"oklch(…)"` paints black (or nothing).
+ * Leave colours out and the tokens apply; when you must set one yourself, pass
+ * it through `useResolvedChartColors` and use the result:
+ *
+ * @example
+ * const [accent] = useResolvedChartColors(["chart-2"])
+ * const option = { series: [{ type: "line", data, lineStyle: { color: accent } }] }
+ * return <EChart option={option} />
+ *
+ * Updates merge instead of replacing (`replaceMerge` on every component type in
+ * play), so series with a stable `id` transition to their new values while
+ * anything dropped from the option is still removed. With
+ * `prefers-reduced-motion: reduce` every animation is off.
+ *
+ * ECharts is loaded modularly (`echarts/core`): only the bar / line / pie series (and `custom`, which draws
+ * the per-bar target marker),
+ * the components the typed charts emit and the canvas renderer are registered
+ * below. To draw anything else with `<EChart>` (scatter, funnel, dataZoom, …),
+ * register it once in your own code:
+ *
+ * @example
+ * import { use } from "echarts/core"
+ * import { ScatterChart } from "echarts/charts"
+ * use([ScatterChart])
  */
-import { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from "react"
-import * as echarts from "echarts"
+import { forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react"
+import { init, use } from "echarts/core"
+import { BarChart, CustomChart, LineChart, PieChart } from "echarts/charts"
+import {
+  GridComponent,
+  LegendComponent,
+  MarkAreaComponent,
+  MarkLineComponent,
+  MarkPointComponent,
+  TooltipComponent,
+} from "echarts/components"
+import { CanvasRenderer } from "echarts/renderers"
 import type { ECharts, EChartsOption } from "echarts"
 import { Check, Copy, Download } from "lucide-react"
 
 import { cn } from "@squadbase/vantage/ui"
 import { Button } from "@squadbase/vantage/ui"
+import type { ChartActionsOptions } from "@squadbase/vantage/components"
+import { createContext, type ForwardedRef, type RefObject } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/chart-theme.ts (internal to @squadbase/vantage) ---------- */
 
-/* ---------- inlined from src/components/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
@@ -28,6 +85,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. */
@@ -36,10 +95,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. */
@@ -95,14 +167,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. */
@@ -110,8 +187,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 &&
@@ -134,7 +216,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.
@@ -149,8 +231,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) {
@@ -185,10 +270,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 },
   }
 }
@@ -205,7 +291,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),
@@ -213,10 +299,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 } },
     },
   }
@@ -228,27 +323,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".
  */
@@ -256,19 +359,122 @@ 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) ?? ""
   })
 }
 
+/** 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 }
+}
+
 /* ---------- end of inlined code ---------- */
 
+// What the typed charts (Bar / Line / Area / Donut) emit. Other series and
+// components are the consumer's to `use()` — see the note at the top.
+use([
+  BarChart,
+  CustomChart,
+  LineChart,
+  PieChart,
+  GridComponent,
+  LegendComponent,
+  MarkAreaComponent,
+  MarkLineComponent,
+  MarkPointComponent,
+  TooltipComponent,
+  CanvasRenderer,
+])
+
 export interface EChartProps {
   /**
    * ECharts のオプション。
@@ -278,7 +484,7 @@ export interface EChartProps {
    * literal が `string` に拡張され、ビルドが失敗する。
    *
    * @example
-   * import type { EChartsOption } from "@squadbase/vantage/components"
+   * import type { EChartsOption } from "@/components/echart"
    *
    * const option: EChartsOption = {
    *   xAxis: { type: "category", data: ["A", "B"] },
@@ -309,14 +515,327 @@ export interface EChartProps {
   onEvents?: Record<string, (params: unknown) => void>
   ariaLabel?: string
   className?: string
-  /** true にするとチャート右上に PNG コピー / ダウンロードボタンを表示する */
-  actions?: boolean
+  /**
+   * true にするとチャート右上に PNG コピー / ダウンロードボタンを表示する。
+   * `exportHeader` があれば PNG の上にその見出しを含める(`{ includeTitle: false }` で含めない)。
+   */
+  actions?: boolean | ChartActionsOptions
   /** ダウンロード時のファイル名(拡張子含む)。省略時は "chart.png" */
   fileName?: string
+  /**
+   * PNG の上に含める見出しと要約。型付きグラフは自分の `title` / `summary` を渡す。
+   * 自分で `ChartFrame` を組むときも同じものを渡すと、保存した画像だけで何のグラフか分かる。
+   */
+  exportHeader?: ChartExportHeader
+}
+
+/** The heading a saved PNG carries above the plot. */
+export interface ChartExportHeader {
+  title?: string
+  summary?: string
+}
+
+const HEADER_PAD_X = 16
+const HEADER_PAD_TOP = 16
+const HEADER_PAD_BOTTOM = 12
+const HEADER_LINE_HEIGHT = 20
+const HEADER_GAP = 4
+const HEADER_FONT_SIZE = 14
+
+export interface ChartExportHeaderLine {
+  text: string
+  kind: "title" | "summary"
+}
+
+/**
+ * Break `text` into lines no wider than `maxWidth` (px, via `measure`), character
+ * by character so Japanese wraps without spaces. Always at least one line for
+ * non-empty text; a single over-wide character still gets its own line.
+ */
+export function wrapChartText(text: string, maxWidth: number, measure: (text: string) => number): string[] {
+  const lines: string[] = []
+  let line = ""
+  for (const ch of text) {
+    if (ch === "\n") {
+      lines.push(line)
+      line = ""
+      continue
+    }
+    if (line !== "" && measure(line + ch) > maxWidth) {
+      lines.push(line)
+      line = ch.trim() === "" ? "" : ch
+    } else {
+      line += ch
+    }
+  }
+  if (line !== "" || lines.length === 0) lines.push(line)
+  return lines.filter((l, i) => l !== "" || i < lines.length - 1)
+}
+
+/**
+ * The lines and total height (CSS px) of the PNG's heading band for a plot
+ * `width` px wide. `measure` takes (text, kind) and returns its width in px.
+ * No title and no summary → no band (`height` 0).
+ */
+export function chartExportHeaderLayout(
+  header: ChartExportHeader | undefined,
+  width: number,
+  measure: (text: string, kind: "title" | "summary") => number,
+): { lines: ChartExportHeaderLine[]; height: number } {
+  const title = header?.title?.trim()
+  const summary = header?.summary?.trim()
+  if (!title && !summary) return { lines: [], height: 0 }
+  const room = Math.max(40, width - HEADER_PAD_X * 2)
+  const lines: ChartExportHeaderLine[] = [
+    ...(title ? wrapChartText(title, room, (t) => measure(t, "title")).map((text) => ({ text, kind: "title" as const })) : []),
+    ...(summary ? wrapChartText(summary, room, (t) => measure(t, "summary")).map((text) => ({ text, kind: "summary" as const })) : []),
+  ]
+  const gap = title && summary ? HEADER_GAP : 0
+  return { lines, height: HEADER_PAD_TOP + lines.length * HEADER_LINE_HEIGHT + gap + HEADER_PAD_BOTTOM }
+}
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image()
+    image.onload = () => resolve(image)
+    image.onerror = () => reject(new Error("PNG の読み込みに失敗しました"))
+    image.src = src
+  })
+}
+
+/** Draw a heading band (title in foreground, summary muted) above the exported plot and return the new PNG. */
+async function pngWithHeader(
+  dataUrl: string,
+  header: ChartExportHeader,
+  look: { background: string; color: string; mutedColor: string; fontFamily: string },
+  pixelRatio: number,
+): Promise<string> {
+  const image = await loadImage(dataUrl)
+  const width = image.width / pixelRatio
+  const plotHeight = image.height / pixelRatio
+  const canvas = document.createElement("canvas")
+  const ctx = canvas.getContext("2d")
+  if (!ctx) return dataUrl
+  const font = (kind: "title" | "summary") => `${kind === "title" ? 500 : 400} ${HEADER_FONT_SIZE}px ${look.fontFamily}`
+  ctx.font = font("title")
+  const layout = chartExportHeaderLayout(header, width, (text, kind) => {
+    ctx.font = font(kind)
+    return ctx.measureText(text).width
+  })
+  if (layout.height === 0) return dataUrl
+  canvas.width = Math.round(image.width)
+  canvas.height = Math.round((layout.height + plotHeight) * pixelRatio)
+  ctx.scale(pixelRatio, pixelRatio)
+  ctx.fillStyle = look.background
+  ctx.fillRect(0, 0, width, layout.height + plotHeight)
+  ctx.textBaseline = "middle"
+  let y = HEADER_PAD_TOP
+  let previous: "title" | "summary" | null = null
+  for (const line of layout.lines) {
+    if (previous === "title" && line.kind === "summary") y += HEADER_GAP
+    ctx.font = font(line.kind)
+    ctx.fillStyle = line.kind === "title" ? look.color : look.mutedColor
+    ctx.fillText(line.text, HEADER_PAD_X, y + HEADER_LINE_HEIGHT / 2)
+    y += HEADER_LINE_HEIGHT
+    previous = line.kind
+  }
+  ctx.drawImage(image, 0, layout.height, width, plotHeight)
+  return canvas.toDataURL("image/png")
+}
+
+/**
+ * Canvas-safe versions of theme colours, kept current across light/dark.
+ * Takes `"chart-1"`〜`"chart-5"`, `"var(--token)"` or any CSS colour; one that
+ * can't be resolved comes back as `""` (ECharts then uses the palette).
+ * Use it whenever a colour goes into a raw `EChart` option by hand.
+ *
+ * @example
+ * const [line, band] = useResolvedChartColors(["chart-1", "var(--muted-foreground)"])
+ */
+export function useResolvedChartColors(colors: readonly string[]): string[] {
+  const tokens = useChartTokens()
+  const key = colors.join("\u0000")
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- `key` stands for the array's contents
+  return useMemo(() => resolveChartColors(colors, tokens), [key, tokens])
 }
 
 type EChartsEventHandler = (params: unknown) => void
 
+/**
+ * ECharts component main types. Listed in `replaceMerge`, a type keeps only the
+ * components whose `id` matches (merged, so they can transition) and drops the
+ * rest — including every one of them when the new option no longer has the type.
+ */
+const COMPONENT_MAIN_TYPES = new Set([
+  "title", "legend", "grid", "xAxis", "yAxis", "polar", "radiusAxis", "angleAxis", "radar",
+  "dataZoom", "visualMap", "tooltip", "axisPointer", "toolbox", "brush", "geo", "parallel",
+  "parallelAxis", "singleAxis", "graphic", "calendar", "dataset", "series", "matrix", "thumbnail",
+])
+
+export interface EChartSetOptionOpts {
+  notMerge: boolean
+  replaceMerge?: string[]
+  lazyUpdate: boolean
+}
+
+/**
+ * How to apply `next` after `prev`: the first option and timeline / media
+ * options replace everything; otherwise merge, replacing every component type
+ * either option uses so nothing stale survives.
+ */
+export function echartSetOptionOpts(prev: EChartsOption | null, next: EChartsOption): EChartSetOptionOpts {
+  const special = (o: EChartsOption) => "timeline" in o || "baseOption" in o || "options" in o || "media" in o
+  if (!prev || special(prev) || special(next)) return { notMerge: true, lazyUpdate: true }
+  const types = new Set<string>()
+  for (const key of [...Object.keys(prev), ...Object.keys(next)]) if (COMPONENT_MAIN_TYPES.has(key)) types.add(key)
+  return { notMerge: false, replaceMerge: [...types], lazyUpdate: true }
+}
+
+/**
+ * Component types that get a generated `id` when the option has none, so replaceMerge can match them across updates.
+ * Not `dataset` / `graphic` / `tooltip`: they are rebuilt on every update (there is nothing to transition).
+ */
+const ID_TYPES = [
+  "title", "legend", "grid", "xAxis", "yAxis", "polar", "radiusAxis", "angleAxis", "radar",
+  "dataZoom", "visualMap", "geo", "singleAxis", "calendar",
+] as const
+
+/**
+ * What `withStableIds` remembers between updates: per generated id, the shape last applied and how many
+ * times it changed (the id's `~v<n>` suffix); per component type, the order of its ids.
+ */
+export interface StableIdState {
+  ids: Map<string, { shape: string; version: number }>
+  order: Map<string, string[]>
+}
+export const createStableIdState = (): StableIdState => ({ ids: new Map(), order: new Map() })
+
+/**
+ * Shape of a component: which keys it has, recursively (arrays only as "array", values not at all —
+ * except `type`). A merge keeps keys the new option dropped, so a changed shape must not be merged.
+ */
+function shapeOf(v: unknown): string {
+  if (Array.isArray(v)) return "[]"
+  if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return "."
+  const o = v as Record<string, unknown>
+  return `{${Object.keys(o)
+    .filter((k) => o[k] !== undefined)
+    .sort()
+    .map((k) => (k === "type" || k === "id" ? `${k}=${String(o[k])}` : `${k}:${shapeOf(o[k])}`))
+    .join(",")}}`
+}
+
+/**
+ * Gives every series (and the common components) an `id` it does not have yet —
+ * series: `series:<name ?? index>`, others `<type>:<index>` — so an update that
+ * only changes values is matched to the existing component and transitions
+ * instead of being rebuilt. If the component's shape changed since `state` last
+ * saw it (a key was removed or added, the type changed), the id gets a new
+ * `~v<n>` suffix so replaceMerge builds it from scratch: the result then always
+ * equals applying the option with `notMerge`. Explicit ids are kept; the input is not mutated.
+ */
+export function withStableIds(option: EChartsOption, state: StableIdState = createStableIdState()): EChartsOption {
+  const out: Record<string, unknown> = { ...(option as Record<string, unknown>) }
+  const taken = new Set<string>()
+  const list = (v: unknown): Record<string, unknown>[] | null =>
+    Array.isArray(v) ? (v as Record<string, unknown>[]) : v && typeof v === "object" ? [v as Record<string, unknown>] : null
+  const give = (key: string, pick: (c: Record<string, unknown>, i: number) => string) => {
+    const items = list(out[key])
+    if (!items) return
+    const used = new Set<string>(items.flatMap((c) => (c && c.id != null ? [String(c.id)] : [])))
+    const bases = items.map((c, i) => {
+      if (!c || typeof c !== "object" || c.id != null) return null
+      let base = pick(c, i)
+      for (let n = 2; used.has(base) || taken.has(`${key}\u0000${base}`); n++) base = `${pick(c, i)}#${n}`
+      used.add(base)
+      taken.add(`${key}\u0000${base}`)
+      return base
+    })
+    // A merge fills the empty slots a removal left and keeps the slot order of what exists, so after any
+    // change in which components there are (or their order) it would not match a fresh render: rebuild them all.
+    const prevOrder = state.order.get(key) ?? []
+    const cur = bases.filter((b): b is string => b !== null)
+    const inOrder = cur.length === prevOrder.length && cur.every((b, i) => b === prevOrder[i])
+    state.order.set(key, cur)
+    out[key] = items.map((c, i) => {
+      const base = bases[i]
+      if (base == null) return c
+      const shape = shapeOf(c)
+      const prev = state.ids.get(base)
+      const version = !prev ? 0 : prev.shape === shape && inOrder ? prev.version : prev.version + 1
+      state.ids.set(base, { shape, version })
+      return { ...c, id: version ? `${base}~v${version}` : base }
+    })
+  }
+  give("series", (c, i) => `series:${typeof c.name === "string" && c.name ? c.name : i}`)
+  for (const key of ID_TYPES) give(key, (_c, i) => `${key}:${i}`)
+  return out as EChartsOption
+}
+
+/** Copy of the plain objects / arrays of an option (functions, class instances, Dates stay shared), to compare against later in-place edits. */
+export function snapshotOption<T>(v: T): T {
+  if (Array.isArray(v)) return v.map(snapshotOption) as T
+  if (v && typeof v === "object") {
+    const proto = Object.getPrototypeOf(v)
+    if (proto === Object.prototype || proto === null) {
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, snapshotOption(x)])) as T
+    }
+  }
+  return v
+}
+
+/** Structural equality for option trees; functions and other non-plain objects compare by reference. */
+export function optionEquals(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a)) {
+    const bb = b as unknown[]
+    return a.length === bb.length && a.every((v, i) => optionEquals(v, bb[i]))
+  }
+  if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+  const pa = Object.getPrototypeOf(a)
+  if ((pa !== Object.prototype && pa !== null) || Object.getPrototypeOf(b) !== pa) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && optionEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
+/** `graphic` text doesn't inherit the global `textStyle`, so give it the inherited font unless it sets its own. */
+function withGraphicFont(option: EChartsOption, fontFamily: string | undefined): EChartsOption {
+  const graphic = (option as { graphic?: unknown }).graphic
+  if (!fontFamily || !Array.isArray(graphic)) return option
+  return {
+    ...option,
+    graphic: graphic.map((g: { type?: string; style?: Record<string, unknown> }) =>
+      g && g.type === "text" && g.style && !g.style.fontFamily ? { ...g, style: { ...g.style, fontFamily } } : g,
+    ),
+  } as EChartsOption
+}
+
+/** `option` as applied: reduced motion forces `animation: false`; otherwise animation stays explicit so it can flip back. */
+export function withMotionPreference(option: EChartsOption, reducedMotion: boolean): EChartsOption {
+  return { ...option, animation: reducedMotion ? false : (option.animation ?? true) }
+}
+
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)"
+
+/** `prefers-reduced-motion: reduce`, kept current. `false` on the server. */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(
+    () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(REDUCED_MOTION_QUERY).matches,
+  )
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return
+    const media = window.matchMedia(REDUCED_MOTION_QUERY)
+    const sync = () => setReduced(media.matches)
+    sync()
+    media.addEventListener("change", sync)
+    return () => media.removeEventListener("change", sync)
+  }, [])
+  return reduced
+}
+
 export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   {
     option,
@@ -328,29 +847,20 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     className,
     actions = false,
     fileName = "chart.png",
+    exportHeader,
   },
   ref,
 ) {
   const containerRef = useRef<HTMLDivElement | null>(null)
   const [instance, setInstance] = useState<ECharts | null>(null)
   const [copied, setCopied] = useState(false)
-  // 初回はレンダー前に読めるので、マウント直後の作り直しが起きない
-  const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
-
-  // 明暗の切り替えとスタイルシートの差し替え(dev で styles.css を書き換えたときなど)を
-  // 拾ってトークンを読み直す ― 何を見張るかは `watchChartTokens` 側が持つ。値が変わら
-  // ないときは同じオブジェクトを返して再 init を防ぐ。
-  useEffect(() => {
-    if (theme !== undefined) return
-    const sync = () => {
-      setTokens((prev) => {
-        const next = readChartTokens()
-        return sameChartTokens(prev, next) ? prev : next
-      })
-    }
-    sync()
-    return watchChartTokens(sync)
-  }, [theme])
+  const tokens = useChartTokens(containerRef)
+  const reducedMotion = usePrefersReducedMotion()
+  // What the current instance last received, to pick the merge mode of the next update.
+  const appliedRef = useRef<EChartsOption | null>(null)
+  // The option (before ids) as it was when applied, deep-copied; and the shape history behind the generated ids.
+  const snapshotRef = useRef<EChartsOption | null>(null)
+  const idStateRef = useRef<StableIdState>(createStableIdState())
 
   const autoTheme = useMemo(() => (tokens ? buildChartTheme(tokens) : undefined), [tokens])
   const resolvedTheme = theme ?? autoTheme
@@ -360,7 +870,9 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   useEffect(() => {
     const container = containerRef.current
     if (!container) return
-    const inst = echarts.init(container, resolvedTheme, { renderer: "canvas" })
+    const inst = init(container, resolvedTheme, { renderer: "canvas" })
+    appliedRef.current = null
+    snapshotRef.current = null
     // `data-rendering` stays on until the (animated) paint is done, so anything
     // capturing the page — printing a document — can wait for real pixels.
     container.dataset.rendering = ""
@@ -369,29 +881,47 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     })
     setInstance(inst)
 
-    const observer = new ResizeObserver(() => inst.resize())
+    // At most one resize per frame (the sidebar animates the width).
+    let frame = 0
+    const observer = new ResizeObserver(() => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(() => {
+        if (!inst.isDisposed()) inst.resize()
+      })
+    })
     observer.observe(container)
 
     return () => {
       observer.disconnect()
+      cancelAnimationFrame(frame)
       inst.dispose()
     }
   }, [resolvedTheme])
 
   useEffect(() => {
-    if (!instance) return
+    if (!instance || instance.isDisposed()) return
+    const prepared = withGraphicFont(
+      withMotionPreference(option, reducedMotion),
+      theme === undefined ? tokens?.fontFamily : undefined,
+    )
+    // Same content as last time (a re-render that built an equal option): nothing to redraw.
+    // Compared with a snapshot, so an in-place edit of a nested array of the caller's option still counts as a change.
+    if (snapshotRef.current && optionEquals(snapshotRef.current, prepared)) return
     if (containerRef.current) containerRef.current.dataset.rendering = ""
-    instance.setOption(option, { notMerge: true, lazyUpdate: true })
-  }, [instance, option])
+    const next = withStableIds(prepared, idStateRef.current)
+    instance.setOption(next, echartSetOptionOpts(appliedRef.current, next))
+    appliedRef.current = next
+    snapshotRef.current = snapshotOption(prepared)
+  }, [instance, option, reducedMotion, theme, tokens?.fontFamily])
 
   useEffect(() => {
-    if (!instance) return
+    if (!instance || instance.isDisposed()) return
     if (loading) instance.showLoading()
     else instance.hideLoading()
   }, [instance, loading])
 
   useEffect(() => {
-    if (!instance || !onEvents) return
+    if (!instance || instance.isDisposed() || !onEvents) return
     const entries = Object.entries(onEvents)
     for (const [event, handler] of entries) {
       instance.on(event, handler as EChartsEventHandler)
@@ -404,20 +934,38 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     }
   }, [instance, onEvents])
 
-  const getPngDataUrl = useCallback(() => {
+  const includeTitle = typeof actions === "object" ? (actions.includeTitle ?? true) : true
+  const getPngDataUrl = useCallback(async (): Promise<string | null> => {
     if (!instance) return null
-    // Export over the page background so the PNG isn't transparent. Computed
-    // styles resolve to rgb(a), so this stays canvas-safe whatever the token.
-    const pageBg = getComputedStyle(document.documentElement).backgroundColor
-    return instance.getDataURL({
-      type: "png",
-      pixelRatio: 2,
-      backgroundColor: pageBg && pageBg !== "rgba(0, 0, 0, 0)" ? pageBg : "#ffffff",
-    })
-  }, [instance])
+    // Export over the nearest opaque background (card, then page) so the PNG
+    // matches what is on screen in dark too. Computed styles resolve to rgb(a),
+    // so this stays canvas-safe whatever the token.
+    let backgroundColor = "#ffffff"
+    for (let el: HTMLElement | null = containerRef.current; el; el = el.parentElement) {
+      const bg = getComputedStyle(el).backgroundColor
+      if (bg && bg !== "rgba(0, 0, 0, 0)" && bg !== "transparent") {
+        backgroundColor = bg
+        break
+      }
+    }
+    const pixelRatio = 2
+    const dataUrl = instance.getDataURL({ type: "png", pixelRatio, backgroundColor })
+    if (!includeTitle || !exportHeader || !(exportHeader.title || exportHeader.summary) || !containerRef.current) return dataUrl
+    try {
+      const style = getComputedStyle(containerRef.current)
+      return await pngWithHeader(
+        dataUrl,
+        exportHeader,
+        { background: backgroundColor, color: style.color, mutedColor: tokens?.mutedForeground ?? style.color, fontFamily: style.fontFamily },
+        pixelRatio,
+      )
+    } catch {
+      return dataUrl
+    }
+  }, [instance, includeTitle, exportHeader, tokens])
 
   const handleCopy = useCallback(async () => {
-    const dataUrl = getPngDataUrl()
+    const dataUrl = await getPngDataUrl()
     if (!dataUrl) return
     try {
       const blob = await (await fetch(dataUrl)).blob()
@@ -429,8 +977,8 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     }
   }, [getPngDataUrl])
 
-  const handleDownload = useCallback(() => {
-    const dataUrl = getPngDataUrl()
+  const handleDownload = useCallback(async () => {
+    const dataUrl = await getPngDataUrl()
     if (!dataUrl) return
     const link = document.createElement("a")
     link.href = dataUrl
@@ -440,6 +988,7 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
 
   // 高さの解決: height prop を渡した場合はインライン style が勝つ。未指定なら
   // h-[400px] をデフォルトで当て、className の高さクラスに後勝ちさせる。
+  const inFrame = useContext(ChartFrameContext)
   const styleHeight =
     height == null ? undefined : typeof height === "number" ? `${height}px` : height
 
@@ -449,14 +998,19 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
       data-slot="echart"
       className={cn("group relative w-full", height == null && "h-[400px]", className)}
       style={styleHeight != null ? { height: styleHeight } : undefined}
-      role="img"
-      aria-label={ariaLabel ?? "チャート"}
     >
-      <div ref={containerRef} data-slot="echart-canvas" className="h-full w-full" />
+      {/* `role="img"` wraps the canvas only, so the action buttons stay reachable. Inside a ChartFrame the plot area is the one image. */}
+      <div
+        ref={containerRef}
+        data-slot="echart-canvas"
+        className="h-full w-full"
+        role={inFrame ? undefined : "img"}
+        aria-label={inFrame ? undefined : (ariaLabel ?? "チャート")}
+      />
       {actions && (
         <div
           data-slot="echart-actions"
-          className="absolute top-2 right-2 z-10 flex gap-1 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100"
+          className="absolute top-2 right-2 z-10 flex gap-1 pointer-events-none opacity-0 transition-opacity group-hover:pointer-events-auto group-hover:opacity-100 focus-within:pointer-events-auto focus-within:opacity-100 [@media(hover:none)]:pointer-events-auto [@media(hover:none)]:opacity-100"
         >
           <Button
             type="button"