@squadbase/vantage 0.6.2-dev1.a7c4a3e → 0.6.2-dev1.ac99e02

package/registry/ui/echart.tsx

@@ -0,0 +1,486 @@
+// 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/).
+/**
+ * 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.
+ */
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from "react"
+import * as echarts from "echarts"
+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"
+
+/* ---------- inlined from src/components/chart-theme.ts (internal to @squadbase/vantage) ---------- */
+
+/** 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[]
+  /** 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,
+    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.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: 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 } },
+    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 },
+    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: {
+      backgroundColor: tokens.popover ?? undefined,
+      borderColor: line,
+      borderWidth: 1,
+      textStyle: { color: tokens.popoverForeground ?? undefined },
+      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())
+  useEffect(() => {
+    const sync = () => {
+      setTokens((prev) => {
+        const next = readChartTokens()
+        return sameChartTokens(prev, next) ? prev : next
+      })
+    }
+    sync()
+    return watchChartTokens(sync)
+  }, [])
+  return tokens
+}
+
+const SERIES_TOKEN_NAME_RE = /^chart-([1-5])$/
+const CSS_VAR_RE = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.+))?\)$/
+
+/**
+ * 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
+ * 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] ?? ""
+    if (typeof document === "undefined") return color
+    let value = color.trim()
+    const cssVar = CSS_VAR_RE.exec(value)
+    if (cssVar) {
+      const styles = getComputedStyle(document.documentElement)
+      value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
+    }
+    return toCanvasColor(value) ?? ""
+  })
+}
+
+/* ---------- end of inlined code ---------- */
+
+export interface EChartProps {
+  /**
+   * ECharts のオプション。
+   *
+   * 型推論を効かせるため、必ず `EChartsOption` を annotation するか
+   * `satisfies EChartsOption` を付けること。付けないと `type: "category"` などの
+   * literal が `string` に拡張され、ビルドが失敗する。
+   *
+   * @example
+   * import type { EChartsOption } from "@squadbase/vantage/components"
+   *
+   * 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 コピー / ダウンロードボタンを表示する */
+  actions?: boolean
+  /** ダウンロード時のファイル名(拡張子含む)。省略時は "chart.png" */
+  fileName?: string
+}
+
+type EChartsEventHandler = (params: unknown) => void
+
+export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
+  {
+    option,
+    height,
+    loading = false,
+    theme,
+    onEvents,
+    ariaLabel,
+    className,
+    actions = false,
+    fileName = "chart.png",
+  },
+  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 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 = echarts.init(container, resolvedTheme, { renderer: "canvas" })
+    // `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)
+
+    const observer = new ResizeObserver(() => inst.resize())
+    observer.observe(container)
+
+    return () => {
+      observer.disconnect()
+      inst.dispose()
+    }
+  }, [resolvedTheme])
+
+  useEffect(() => {
+    if (!instance) return
+    if (containerRef.current) containerRef.current.dataset.rendering = ""
+    instance.setOption(option, { notMerge: true, lazyUpdate: true })
+  }, [instance, option])
+
+  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 getPngDataUrl = useCallback(() => {
+    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])
+
+  const handleCopy = useCallback(async () => {
+    const dataUrl = 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(() => {
+    const dataUrl = 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 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"
+      aria-label={ariaLabel ?? "チャート"}
+    >
+      <div ref={containerRef} data-slot="echart-canvas" className="h-full w-full" />
+      {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"
+        >
+          <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"