@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.9365dcd

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 } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
 
-/* ---------- inlined from src/components/chart-theme.ts (internal to @squadbase/vantage) ---------- */
+/* ---------- 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
@@ -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. */
@@ -97,6 +156,7 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
   }
   return {
     series,
+    ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
     foreground: read("--foreground"),
     mutedForeground: read("--muted-foreground"),
     border: read("--border"),
@@ -112,6 +172,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
   return (
     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 &&
@@ -185,10 +246,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 +267,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 +275,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 } },
     },
   }
@@ -230,12 +301,16 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  */
 function useChartTokens(): 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 sync = () => {
-      setTokens((prev) => {
-        const next = readChartTokens()
-        return sameChartTokens(prev, next) ? prev : next
-      })
+      const next = readChartTokens()
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
     }
     sync()
     return watchChartTokens(sync)
@@ -244,11 +319,14 @@ function useChartTokens(): ChartTokens | null {
 }
 
 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 off the document root (`--positive`, …); `var(--token)` is read off the document root; 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 +334,120 @@ 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 ""
+      return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue(`--${color.trim()}`)) ?? ""
+    }
     if (typeof document === "undefined") return color
     let value = color.trim()
     const cssVar = CSS_VAR_RE.exec(value)
+    const styles = getComputedStyle(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(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 } {
+  const [node, setNode] = useState<E | null>(null)
+  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])
+  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 }
+}
+
 /* ---------- 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 +457,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 +488,217 @@ 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 }
+}
+
+/** `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,6 +710,7 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     className,
     actions = false,
     fileName = "chart.png",
+    exportHeader,
   },
   ref,
 ) {
@@ -336,20 +719,39 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   const [copied, setCopied] = useState(false)
   // 初回はレンダー前に読めるので、マウント直後の作り直しが起きない
   const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
+  const reducedMotion = usePrefersReducedMotion()
+  // What the current instance last received, to pick the merge mode of the next update.
+  const appliedRef = useRef<EChartsOption | null>(null)
 
   // 明暗の切り替えとスタイルシートの差し替え(dev で styles.css を書き換えたときなど)を
   // 拾ってトークンを読み直す ― 何を見張るかは `watchChartTokens` 側が持つ。値が変わら
-  // ないときは同じオブジェクトを返して再 init を防ぐ。
+  // ないときは state を更新せず、再 init を防ぐ。比較は updater 関数の中ではなく ref で行う:
+  // DOM を読む updater は React に何度も再生され、そのたびに新しいオブジェクトを返して
+  // 再描画が止まらなくなる(変数を後から当てた直後に Maximum update depth exceeded)。
+  const tokensRef = useRef(tokens)
   useEffect(() => {
     if (theme !== undefined) return
+    // Colours come from the document root, but the font is whatever this container inherits: an app
+    // can set its own font on a wrapper, and the canvas text has to match the DOM around it.
     const sync = () => {
-      setTokens((prev) => {
-        const next = readChartTokens()
-        return sameChartTokens(prev, next) ? prev : next
-      })
+      const base = readChartTokens()
+      const font = containerRef.current ? getComputedStyle(containerRef.current).fontFamily : ""
+      const next = base && font ? { ...base, fontFamily: font } : base
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
     }
     sync()
-    return watchChartTokens(sync)
+    const stop = watchChartTokens(sync)
+    // A font set on a wrapper (class / inline style) isn't seen by the document-level watcher.
+    const ancestors = new MutationObserver(sync)
+    for (let node = containerRef.current?.parentElement; node; node = node.parentElement) {
+      ancestors.observe(node, { attributes: true, attributeFilter: ["class", "style"] })
+    }
+    return () => {
+      stop()
+      ancestors.disconnect()
+    }
   }, [theme])
 
   const autoTheme = useMemo(() => (tokens ? buildChartTheme(tokens) : undefined), [tokens])
@@ -360,7 +762,8 @@ 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
     // `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,11 +772,19 @@ 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])
@@ -381,8 +792,10 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   useEffect(() => {
     if (!instance) return
     if (containerRef.current) containerRef.current.dataset.rendering = ""
-    instance.setOption(option, { notMerge: true, lazyUpdate: true })
-  }, [instance, option])
+    const next = withGraphicFont(withMotionPreference(option, reducedMotion), theme === undefined ? tokens?.fontFamily : undefined)
+    instance.setOption(next, echartSetOptionOpts(appliedRef.current, next))
+    appliedRef.current = next
+  }, [instance, option, reducedMotion, theme, tokens?.fontFamily])
 
   useEffect(() => {
     if (!instance) return
@@ -404,20 +817,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 +860,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 +871,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 +881,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"