@squadbase/vantage 0.6.1 → 0.6.2-dev1.25d59a0

package/registry/ui/echart.tsx

@@ -0,0 +1,923 @@
+// Copied by `vantage add ui echart`. This file is yours to edit.
+// 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
+ * spinner, and can copy/download the chart as a PNG.
+ *
+ * Colours follow the design tokens: `--chart-1..5` become the series palette,
+ * and the text/border/popover tokens style axes, legend and tooltip. They're
+ * resolved once at init (see `chart-theme.ts`) and re-read whenever they can
+ * 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, 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 @squadbase/squadkit registry/lib/chart-theme.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The colour of the folded「その他」series / slice / row. The ONLY place this
+ * grey is defined — every chart takes it from here. It is the most subdued
+ * colour in a chart, not the darkest: the theme's `--neutral` mixed halfway into
+ * `--background`, so it recedes in light and dark alike (and brand themes follow
+ * it). `--neutral-subtle` alone sits too close to the background to read as a
+ * slice. Canvas charts resolve it through `resolveChartColors`.
+ */
+const CHART_OTHER_COLOR = "color-mix(in oklab, var(--neutral) 50%, var(--background))"
+
+/**
+ * True inside `ChartFrame`. The frame's plot area carries the chart's single
+ * `role="img"` and label, so `EChart` drops its own when it sees this.
+ */
+const ChartFrameContext = createContext(false)
+
+/** Series palette, in order. Missing tokens are skipped, not defaulted. */
+const SERIES_TOKENS = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5"] as const
+
+interface ChartTokens {
+  /** Resolved `--chart-1..5`, in order. */
+  series: string[]
+  /** Computed `font-family` of the container, so canvas text matches the DOM. Optional. */
+  fontFamily?: string
+  /** Body text: titles and the default `textStyle`. */
+  foreground: string | null
+  /** Secondary text: axis labels, legend, subtitles. */
+  mutedForeground: string | null
+  /** Axis lines, ticks, split lines, tooltip border. */
+  border: string | null
+  /** Tooltip surface. */
+  popover: string | null
+  /** Tooltip text. */
+  popoverForeground: string | null
+}
+
+let normalizeContext: CanvasRenderingContext2D | null | undefined
+
+/** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
+const ZRENDER_COLOR_RE = /^(?:#[0-9a-f]{6}|rgba?\()/i
+
+/**
+ * Serialize a CSS colour into a canvas-safe form, or `null` if the browser
+ * rejects it. Assigning an invalid value to `fillStyle` is a no-op, so the same
+ * input is written over two different known colours: agreeing results mean the
+ * value parsed, differing ones mean it was dropped.
+ */
+function toCanvasColor(value: string): string | null {
+  const raw = value.trim()
+  if (!raw) return null
+  if (normalizeContext === undefined) {
+    const canvas = document.createElement("canvas")
+    canvas.width = 1
+    canvas.height = 1
+    normalizeContext = canvas.getContext("2d", { willReadFrequently: true })
+  }
+  const ctx = normalizeContext
+  if (!ctx) return raw
+  ctx.fillStyle = "#000000"
+  ctx.fillStyle = raw
+  const onBlack = ctx.fillStyle
+  ctx.fillStyle = "#ffffff"
+  ctx.fillStyle = raw
+  if (onBlack !== ctx.fillStyle || typeof onBlack !== "string") return null
+  if (ZRENDER_COLOR_RE.test(onBlack)) return onBlack
+  // Still `oklch()` / `lab()` / `color(...)`: paint it and read the pixel back.
+  // Wide-gamut colours clip to sRGB, which is all zrender can express anyway.
+  ctx.clearRect(0, 0, 1, 1)
+  ctx.fillRect(0, 0, 1, 1)
+  const [r = 0, g = 0, b = 0, a = 0] = ctx.getImageData(0, 0, 1, 1).data
+  return a === 255
+    ? `rgb(${r}, ${g}, ${b})`
+    : `rgba(${r}, ${g}, ${b}, ${Math.round((a / 255) * 1000) / 1000})`
+}
+
+/**
+ * Read the chart tokens off `el` (the document root by default — tokens live on
+ * `:root` and inherit). Returns `null` outside the browser so callers fall back
+ * to plain ECharts defaults.
+ */
+function readChartTokens(el?: Element | null): ChartTokens | null {
+  if (typeof document === "undefined") return null
+  const target = el ?? document.documentElement
+  if (!target) return null
+  const styles = getComputedStyle(target)
+  const read = (name: string) => toCanvasColor(styles.getPropertyValue(name))
+  const series: string[] = []
+  for (const token of SERIES_TOKENS) {
+    const color = read(token)
+    if (color) series.push(color)
+  }
+  return {
+    series,
+    ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
+    foreground: read("--foreground"),
+    mutedForeground: read("--muted-foreground"),
+    border: read("--border"),
+    popover: read("--popover"),
+    popoverForeground: read("--popover-foreground"),
+  }
+}
+
+/** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
+function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return (
+    a.series.length === b.series.length &&
+    a.series.every((color, i) => color === b.series[i]) &&
+    a.fontFamily === b.fontFamily &&
+    a.foreground === b.foreground &&
+    a.mutedForeground === b.mutedForeground &&
+    a.border === b.border &&
+    a.popover === b.popover &&
+    a.popoverForeground === b.popoverForeground
+  )
+}
+
+/**
+ * Watch everything that can change the resolved tokens and call `onChange` when
+ * something might have. It only ever says "re-read" — the caller compares with
+ * `sameChartTokens` and decides whether anything actually moved. Returns a
+ * disposer.
+ *
+ * Two sources, not one:
+ *  - light/dark flips, which land as `class` / `data-theme` (or an inline
+ *    `style`) on `<html>`/`<body>`, or as an OS preference change
+ *  - stylesheet changes. In dev, editing `styles.css` rewrites the injected
+ *    `<style>` in `<head>` and touches nothing else, so watching the theme
+ *    attributes alone leaves the chart painted in the previous palette until a
+ *    reload — the tokens in the DOM are new, the canvas is not.
+ */
+function watchChartTokens(onChange: () => void): () => void {
+  if (typeof document === "undefined") return () => {}
+  // Style edits arrive as bursts of mutations; coalesce them into one read, and
+  // take it after the next frame so a swapped stylesheet has been applied.
+  let frame = 0
+  const schedule = () => {
+    if (frame) return
+    frame = requestAnimationFrame(() => {
+      frame = 0
+      onChange()
+    })
+  }
+
+  const themeObserver = new MutationObserver(schedule)
+  const attributeFilter = ["class", "style", "data-theme"]
+  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
+  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+
+  const styleObserver = new MutationObserver(schedule)
+  if (document.head) {
+    styleObserver.observe(document.head, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["href", "media", "disabled"],
+    })
+  }
+
+  // A swapped `<link>` only applies once the sheet has loaded, after its mutation.
+  const onLoad = (event: Event) => {
+    if (event.target instanceof HTMLLinkElement) schedule()
+  }
+  document.addEventListener("load", onLoad, true)
+
+  const media = window.matchMedia("(prefers-color-scheme: dark)")
+  media.addEventListener("change", schedule)
+
+  return () => {
+    if (frame) cancelAnimationFrame(frame)
+    themeObserver.disconnect()
+    styleObserver.disconnect()
+    document.removeEventListener("load", onLoad, true)
+    media.removeEventListener("change", schedule)
+  }
+}
+
+/** Shared shape for the four axis types ECharts themes address separately. */
+function axisTheme(tokens: ChartTokens, splitLine: boolean) {
+  const line = tokens.border ?? undefined
+  return {
+    axisLine: { show: false },
+    axisTick: { show: false },
+    axisLabel: { show: true, color: tokens.mutedForeground ?? undefined, fontSize: 12 },
+    // Faint horizontal rules only: the border colour at low opacity.
+    splitLine: { show: splitLine, lineStyle: { color: line ? [line] : undefined, opacity: 0.5, width: 1 } },
+    splitArea: { show: false },
+  }
+}
+
+/**
+ * Build the ECharts theme. `option.color` still wins over `theme.color`, so an
+ * app that sets its own palette keeps it.
+ */
+function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
+  const text = tokens.foreground ?? undefined
+  const muted = tokens.mutedForeground ?? undefined
+  const line = tokens.border ?? undefined
+  return {
+    // Let the page background show through: charts sit on cards, not on a canvas.
+    backgroundColor: "transparent",
+    ...(tokens.series.length > 0 ? { color: tokens.series } : {}),
+    textStyle: { color: text, ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}) },
+    title: { textStyle: { color: text }, subtextStyle: { color: muted } },
+    legend: { textStyle: { color: muted } },
+    categoryAxis: axisTheme(tokens, false),
+    valueAxis: axisTheme(tokens, true),
+    logAxis: axisTheme(tokens, true),
+    timeAxis: axisTheme(tokens, true),
+    tooltip: {
+      // ECharts' default 0.4s transform lags the tooltip ~300ms behind the cursor.
+      transitionDuration: 0,
+      backgroundColor: tokens.popover ?? undefined,
+      borderColor: line,
+      borderWidth: 1,
+      padding: [8, 12],
+      // Rounded card with a soft shadow; in dark mode the shadow barely shows, so the border carries the edge.
+      extraCssText: "border-radius:8px;box-shadow:var(--shadow-card, 0 4px 12px rgb(0 0 0 / 0.08));",
+      textStyle: {
+        color: tokens.popoverForeground ?? undefined,
+        fontSize: 12,
+        ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}),
+      },
+      axisPointer: { lineStyle: { color: line }, crossStyle: { color: line } },
+    },
+  }
+}
+
+/**
+ * The resolved tokens, kept current: re-read whenever `watchChartTokens` says
+ * they may have moved, and only replaced when a value actually changed. For
+ * components that build an ECharts option from token colours themselves (the
+ * typed charts), so their palette follows light/dark like `EChart`'s theme.
+ */
+function useChartTokens(): 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 = () => {
+      const next = readChartTokens()
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
+    }
+    sync()
+    return watchChartTokens(sync)
+  }, [])
+  return tokens
+}
+
+const SERIES_TOKEN_NAME_RE = /^chart-([1-5])$/
+const TONE_NAME_RE = /^(?:positive|warning|negative|neutral|info)(?:-fill)?$/
+const CSS_VAR_RE = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.+))?\)$/
+const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
+
+/**
+ * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
+ * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
+ * variants `"positive-fill"`, …) are read 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".
+ */
+function resolveChartColors(colors: readonly string[], tokens: ChartTokens | null): string[] {
+  return colors.map((color) => {
+    const token = SERIES_TOKEN_NAME_RE.exec(color.trim())
+    if (token) return tokens?.series[Number(token[1]) - 1] ?? ""
+    // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
+    if (TONE_NAME_RE.test(color.trim())) {
+      if (typeof document === "undefined") return ""
+      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) {
+      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 のオプション。
+   *
+   * 型推論を効かせるため、必ず `EChartsOption` を annotation するか
+   * `satisfies EChartsOption` を付けること。付けないと `type: "category"` などの
+   * literal が `string` に拡張され、ビルドが失敗する。
+   *
+   * @example
+   * import type { EChartsOption } from "@/components/echart"
+   *
+   * const option: EChartsOption = {
+   *   xAxis: { type: "category", data: ["A", "B"] },
+   *   yAxis: { type: "value" },
+   *   series: [{ type: "bar", data: [1, 2] }],
+   * }
+   * <EChart option={option} />
+   */
+  option: EChartsOption
+  /**
+   * チャートの高さ。数値は px、文字列は CSS 値(例: `"50vh"`)として扱う。
+   *
+   * 省略した場合は外側ラッパーに `h-[400px]` がデフォルトで当たるが、`className` に
+   * `h-full` や `h-[360px]` などの高さクラスを渡せばそちらが優先される
+   * (`h-full` を使う場合は親要素に確定した高さが必要)。
+   * `height` と `className` の高さを両方指定した場合は `height`(インライン style)が勝つ。
+   */
+  height?: string | number
+  loading?: boolean
+  /**
+   * `echarts.init` にそのまま渡すテーマ(名前または登録済みテーマオブジェクト)。
+   *
+   * 渡すとデザイントークン追従は**完全に無効**になり、明暗の切り替えにも追従しなく
+   * なる。系列色だけ変えたいなら `option.color` を使う ― option はテーマより優先
+   * されるので、軸・凡例・ツールチップのトークン追従は残る。
+   */
+  theme?: string | object
+  onEvents?: Record<string, (params: unknown) => void>
+  ariaLabel?: string
+  className?: string
+  /**
+   * 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,
+    height,
+    loading = false,
+    theme,
+    onEvents,
+    ariaLabel,
+    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())
+  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` 側が持つ。値が変わら
+  // ないときは 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 = () => {
+      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()
+    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])
+  const resolvedTheme = theme ?? autoTheme
+
+  // init / re-init: ECharts はテーマの差し替えに対応しないので、テーマが変わったら
+  // インスタンスを破棄して作り直す(トークンが実際に変わったときだけここに来る)
+  useEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+    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 = ""
+    inst.on("finished", () => {
+      delete container.dataset.rendering
+    })
+    setInstance(inst)
+
+    // 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 (containerRef.current) containerRef.current.dataset.rendering = ""
+    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
+    if (loading) instance.showLoading()
+    else instance.hideLoading()
+  }, [instance, loading])
+
+  useEffect(() => {
+    if (!instance || !onEvents) return
+    const entries = Object.entries(onEvents)
+    for (const [event, handler] of entries) {
+      instance.on(event, handler as EChartsEventHandler)
+    }
+    return () => {
+      if (instance.isDisposed()) return
+      for (const [event, handler] of entries) {
+        instance.off(event, handler as EChartsEventHandler)
+      }
+    }
+  }, [instance, onEvents])
+
+  const includeTitle = typeof actions === "object" ? (actions.includeTitle ?? true) : true
+  const getPngDataUrl = useCallback(async (): Promise<string | null> => {
+    if (!instance) return null
+    // 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 = await getPngDataUrl()
+    if (!dataUrl) return
+    try {
+      const blob = await (await fetch(dataUrl)).blob()
+      await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })])
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch {
+      // ClipboardItem 未対応ブラウザでは silent fail
+    }
+  }, [getPngDataUrl])
+
+  const handleDownload = useCallback(async () => {
+    const dataUrl = await getPngDataUrl()
+    if (!dataUrl) return
+    const link = document.createElement("a")
+    link.href = dataUrl
+    link.download = fileName
+    link.click()
+  }, [getPngDataUrl, fileName])
+
+  // 高さの解決: height prop を渡した場合はインライン style が勝つ。未指定なら
+  // h-[400px] をデフォルトで当て、className の高さクラスに後勝ちさせる。
+  const inFrame = useContext(ChartFrameContext)
+  const styleHeight =
+    height == null ? undefined : typeof height === "number" ? `${height}px` : height
+
+  return (
+    <div
+      ref={ref}
+      data-slot="echart"
+      className={cn("group relative w-full", height == null && "h-[400px]", className)}
+      style={styleHeight != null ? { height: styleHeight } : undefined}
+    >
+      {/* `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 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"
+            variant="ghost"
+            size="icon-sm"
+            onClick={handleCopy}
+            aria-label={copied ? "コピーしました" : "PNG をクリップボードにコピー"}
+          >
+            {copied ? <Check className="size-4" /> : <Copy className="size-4" />}
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            onClick={handleDownload}
+            aria-label="PNG をダウンロード"
+          >
+            <Download className="size-4" />
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+})
+EChart.displayName = "EChart"
+
+export type { EChartsOption } from "echarts"