@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.54bde93

package/registry/ui/chart-frame.tsx

@@ -0,0 +1,1393 @@
+// Copied by `vantage add ui chart-frame`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/charts/chart-frame.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * ChartFrame — the frame every typed chart renders in: an optional title and a
+ * one-sentence summary above a plot area of fixed height. The plot is labelled
+ * by the title and described by the summary, so a screen reader hears what the
+ * chart says, not just that there is one.
+ *
+ * The plot area is the frame's one `role="img"` (`EChart` inside it drops its
+ * own); `dataTable` adds the numbers as a visually-hidden table beside it, so a
+ * screen reader can read the values the canvas only draws.
+ *
+ * The plot area keeps its height in every state: while loading it shows a
+ * skeleton shaped like the final chart, and with no data it says so (and offers
+ * one action) instead of drawing empty axes.
+ */
+import { forwardRef, useId, type HTMLAttributes, type ReactNode } from "react"
+
+import { cn } from "@squadbase/vantage/ui"
+import type { ChartEmptyState } from "@squadbase/vantage/components"
+import { createContext, useCallback, useEffect, useRef, useState, type ForwardedRef, type RefObject } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
+import { DEFAULT_LOCALE, EMPTY_VALUE, formatValue, toValueFormatter, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartColor, ChartColors, ChartSeriesColor, ValueFormatter } 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
+  /** 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. */
+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)
+  }
+  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. */
+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 &&
+    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, 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.
+  let frame = 0
+  const schedule = () => {
+    if (frame) return
+    frame = requestAnimationFrame(() => {
+      frame = 0
+      onChange()
+    })
+  }
+
+  const themeObserver = new MutationObserver(schedule)
+  const attributeFilter = ["class", "style", "data-theme"]
+  // 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) {
+    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(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 = () => {
+      const next = readChartTokens(target)
+      if (sameChartTokens(tokensRef.current, next)) return
+      tokensRef.current = next
+      setTokens(next)
+    }
+    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; `"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".
+ */
+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 ""
+      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) {
+      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 }
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/chart-utils.ts (internal to @squadbase/vantage) ---------- */
+
+const ROOT_PROP_KEYS = new Set(["id", "style", "role", "tabIndex", "lang", "hidden"])
+const ROOT_PROP_PREFIX_RE = /^(data|aria)-/
+
+/**
+ * The attributes of a typed chart's leftover props that belong on its root
+ * element: `id` / `style` / `role` / `tabIndex` / `lang` / `hidden`, `data-*` and `aria-*`.
+ * An allowlist, so a chart's own (or deprecated, ignored) props never reach the DOM.
+ */
+function chartRootProps(rest: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(rest)) {
+    if (value !== undefined && (ROOT_PROP_KEYS.has(key) || ROOT_PROP_PREFIX_RE.test(key))) out[key] = value
+  }
+  return out
+}
+
+/** The series tokens, in palette order — the default `colors` of every typed chart. */
+const DEFAULT_CHART_COLORS: readonly ChartColor[] = [
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+]
+
+const TOKEN_NAME_RE = /^chart-[1-5]$/
+
+/** The meaning colours; each is a theme token of the same name (`--positive`, …). */
+const CHART_TONES: readonly ChartTone[] = ["positive", "warning", "negative", "neutral"]
+
+/** Whether `color` is a meaning colour (`"positive"` / `"warning"` / `"negative"` / `"neutral"`). */
+function isChartTone(color: string): color is ChartTone {
+  return (CHART_TONES as readonly string[]).includes(color.trim())
+}
+
+/**
+ * A chart colour as a CSS value: `"chart-2"` → `var(--chart-2)` (so it follows
+ * light/dark on its own), anything else passes through unchanged.
+ */
+function chartColorToCss(color: ChartColor): string {
+  const value = color.trim()
+  return TOKEN_NAME_RE.test(value) || isChartTone(value) ? `var(--${value})` : value
+}
+
+/**
+ * A chart colour for an AREA (bar, slice, segment, ring): like `chartColorToCss`, but a meaning
+ * colour resolves to its area token (`"positive"` → `var(--positive-fill)`), which keeps the same
+ * lightness step from the page in light and dark. `--positive` etc. are for text and icons.
+ */
+function chartFillToCss(color: ChartColor): string {
+  const value = color.trim()
+  return isChartTone(value) ? `var(--${value}-fill)` : chartColorToCss(color)
+}
+
+/** The colour name to resolve for an area: a meaning colour becomes its `-fill` token (`"positive"` → `"positive-fill"`), the rest is unchanged. */
+function chartFillName(color: ChartColor): ChartColor {
+  const value = color.trim()
+  return isChartTone(value) ? `${value}-fill` : color
+}
+
+/** The `i`-th colour, cycling through `colors` (the token palette when empty). */
+function chartColorAt(colors: readonly ChartColor[] | undefined, i: number): ChartColor {
+  const palette = colors && colors.length > 0 ? colors : DEFAULT_CHART_COLORS
+  return palette[i % palette.length]!
+}
+
+/** `colors` extended (by cycling) to exactly `count` entries. */
+function chartColorsFor(colors: readonly ChartColor[] | undefined, count: number): ChartColor[] {
+  return Array.from({ length: count }, (_, i) => chartColorAt(colors, i))
+}
+
+/** A translucent version of a CSS colour (works for `var(--…)` too). */
+function tintCss(cssColor: string, percent: number): string {
+  return `color-mix(in oklab, ${cssColor} ${percent}%, transparent)`
+}
+
+const numberFormat = new Intl.NumberFormat("ja-JP", { maximumFractionDigits: 2 })
+
+/** Default `valueFormatter`: grouped digits, up to two decimals (`1,234.5`). */
+const defaultValueFormatter: ValueFormatter = (value) => numberFormat.format(value)
+
+/**
+ * The formatter a chart actually uses: an explicit `valueFormatter` wins, else
+ * `format` (default `"compact"`, so ¥1億 / 9.2万 on axes) via `toValueFormatter`.
+ */
+function resolveValueFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  locale?: string,
+): ValueFormatter {
+  return valueFormatter ?? toValueFormatter(format, locale)
+}
+
+/**
+ * The formatter of value-axis ticks and on-plot labels: an explicit
+ * `valueFormatter` wins; else `"compact"` / `"number"` / `"currency"` read in
+ * the short form (`1億`, `¥1億`, `¥4,520万` — a tick of `¥100,000,000` is
+ * too wide to read), and `"percent"` / `"multiple"` as `format` says. The short
+ * form goes through `formatValue` (compact notation, `digits` / `unit` dropped),
+ * so an axis tick and a KPI / tooltip of the same `format` always print the same
+ * currency sign and grouping.
+ */
+function resolveAxisFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  locale: string = DEFAULT_LOCALE,
+): ValueFormatter {
+  if (valueFormatter) return valueFormatter
+  const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
+  if (spec.type !== "compact" && spec.type !== "number" && spec.type !== "currency") return toValueFormatter(format, locale)
+  const currency = "currency" in spec ? spec.currency : undefined
+  const short: ValueFormat =
+    spec.type === "currency" ? { type: "currency", currency, notation: "compact" } : { type: "compact" }
+  return (value) => formatValue(value, short, locale)
+}
+
+/** The unit words of a ja number (`1.2万` / `3.4億` / `1兆`) and their sizes, largest first. */
+const JA_UNITS = [
+  { char: "兆", size: 1e12 },
+  { char: "億", size: 1e8 },
+  { char: "万", size: 1e4 },
+] as const
+
+const JA_NUMBER_TOKEN_RE = /\d[\d,]*(?:\.\d+)?(?:兆|億|万)?/
+
+/**
+ * The value-axis tick formatter for an axis whose largest tick is `top`: every tick reads in the unit of
+ * that largest tick, so 万 and 億 never mix on one axis (`¥0.5億` / `¥1億` / `¥1.5億`, not `¥5,000万` / `¥1億`).
+ * Only the ja short forms (`compact` / `number` / `currency`, no `valueFormatter`) have units to align;
+ * any other format — and an axis whose largest tick is under 1万 — keeps `resolveAxisFormatter`'s output as it is.
+ */
+function resolveAxisTickFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  locale: string = DEFAULT_LOCALE,
+): (top: number) => ValueFormatter {
+  const base = resolveAxisFormatter(valueFormatter, format, locale)
+  const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
+  const aligns =
+    !valueFormatter && locale.toLowerCase().startsWith("ja") && (spec.type === "compact" || spec.type === "number" || spec.type === "currency")
+  if (!aligns) return () => base
+  const number = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 })
+  return (top) => {
+    const unit = JA_UNITS.find((u) => Math.abs(top) >= u.size)
+    if (!unit) return base
+    return (value) => {
+      const text = base(value)
+      if (value === 0 || !Number.isFinite(value)) return text
+      const scaled = `${number.format(Math.abs(value) / unit.size)}${unit.char}`
+      return text.replace(JA_NUMBER_TOKEN_RE, () => scaled)
+    }
+  }
+}
+
+/**
+ * A data cell as a number, or `null` for a gap. Numeric strings count — SQL
+ * `DECIMAL` / `BIGINT` columns usually arrive as strings.
+ */
+function toChartNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null
+  if (typeof value === "bigint") return Number(value)
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/** Clamp `value` into `[min, max]`. */
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+/* ------------------------------------------------------------ aggregation */
+
+/** How many categories a chart colours individually; the rest fold into「その他」. */
+const MAX_CHART_SERIES = 5
+
+/** The series name the folded categories get. */
+const OTHER_SERIES_LABEL = "その他"
+
+interface AggregatedItems<Item extends { name: string; value: number }> {
+  /** The `n` largest items, in their given order. All items when there are `n` or fewer. */
+  top: Item[]
+  /** The items folded into `other`, in their given order. */
+  rest: Item[]
+  /** The folded remainder, or `null` when nothing was folded. */
+  other: { name: string; value: number } | null
+}
+
+/**
+ * Keep the `n` largest items (by value; ties keep the earlier one) in their
+ * given order and fold the rest into one `otherLabel` item. Shared by every
+ * chart that caps its categories (Area / Line / Bar series, Donut slices,
+ * BarList rows).
+ */
+function aggregateTopN<Item extends { name: string; value: number }>(
+  items: readonly Item[],
+  n: number = MAX_CHART_SERIES,
+  otherLabel: string = OTHER_SERIES_LABEL,
+): AggregatedItems<Item> {
+  if (items.length <= n) return { top: [...items], rest: [], other: null }
+  const ranked = items
+    .map((item, i) => ({ item, i }))
+    .sort((a, b) => b.item.value - a.item.value || a.i - b.i)
+  const keep = new Set(ranked.slice(0, n).map((r) => r.i))
+  const top = items.filter((_, i) => keep.has(i))
+  const rest = items.filter((_, i) => !keep.has(i))
+  return { top, rest, other: { name: otherLabel, value: rest.reduce((sum, item) => sum + item.value, 0) } }
+}
+
+interface AggregatedSeries {
+  /** Rows to draw: the input rows, plus an `otherCategory` column when categories were folded. */
+  data: Record<string, unknown>[]
+  /** Series to draw: the kept categories in their given order, then `otherCategory`. */
+  categories: string[]
+  /** The folded series' name, or `null`. */
+  otherCategory: string | null
+}
+
+/**
+ * Cap a cartesian chart at `n` series: rank the categories by the sum of their
+ * values, keep the top `n` and add a per-row sum of the rest as `otherLabel`.
+ */
+function aggregateSeries(
+  data: readonly Record<string, unknown>[],
+  categories: readonly string[],
+  n: number = MAX_CHART_SERIES,
+  otherLabel: string = OTHER_SERIES_LABEL,
+): AggregatedSeries {
+  const totals = categories.map((name) => ({
+    name,
+    value: data.reduce((sum, row) => sum + (toChartNumber(row[name]) ?? 0), 0),
+  }))
+  const { top, rest, other } = aggregateTopN(totals, n, otherLabel)
+  if (!other) return { data: [...data], categories: [...categories], otherCategory: null }
+  const folded = rest.map((item) => item.name)
+  return {
+    data: data.map((row) => {
+      let sum: number | null = null
+      for (const name of folded) {
+        const v = toChartNumber(row[name])
+        if (v !== null) sum = (sum ?? 0) + v
+      }
+      return { ...row, [other.name]: sum }
+    }),
+    categories: [...top.map((item) => item.name), other.name],
+    otherCategory: other.name,
+  }
+}
+
+/**
+ * `aggregateSeries` that never folds `keep` (a comparison series) into「その他」: the others are capped
+ * at `n` as usual and `keep` is appended last, so it is drawn on top of the cap and never takes the first slot.
+ */
+function aggregateSeriesKeeping(
+  data: readonly Record<string, unknown>[],
+  categories: readonly string[],
+  keep: string | undefined,
+  n: number = MAX_CHART_SERIES,
+): AggregatedSeries {
+  if (keep === undefined || !categories.includes(keep)) return aggregateSeries(data, categories, n)
+  const aggregated = aggregateSeries(
+    data,
+    categories.filter((c) => c !== keep),
+    n,
+  )
+  return { ...aggregated, categories: [...aggregated.categories, keep] }
+}
+
+/**
+ * `seriesColorsFor` for a chart with a comparison series: the comparison takes no `--chart-*` token (the
+ * builder paints it in muted grey; its slot here is `""`), and the others are assigned as if it were absent,
+ * so a main series keeps its colour whether or not a comparison is drawn.
+ */
+function seriesColorsWithComparison(
+  categories: readonly string[],
+  colors: ChartColors | undefined,
+  otherColor: string,
+  otherCategory: string | null,
+  allCategories: readonly string[],
+  comparison: string | undefined,
+): string[] {
+  if (comparison === undefined || !categories.includes(comparison)) {
+    return seriesColorsFor(categories, colors, otherColor, otherCategory, allCategories)
+  }
+  const main = categories.filter((c) => c !== comparison)
+  const mainColors = seriesColorsFor(
+    main,
+    colors,
+    otherColor,
+    otherCategory,
+    allCategories.filter((c) => c !== comparison),
+  )
+  return categories.map((c) => (c === comparison ? "" : (mainColors[main.indexOf(c)] ?? "")))
+}
+
+/**
+ * Colour per drawn series: the record's token for that category, else the
+ * array's token at the category's position in `allCategories` (cycled), else
+ * the token palette by drawn position. `otherCategory` — and a category the
+ * data itself names「その他」(`OTHER_SERIES_LABEL`) — always gets `otherColor`.
+ */
+function seriesColorsFor(
+  categories: readonly string[],
+  colors: ChartColors | undefined,
+  otherColor: string,
+  otherCategory: string | null = null,
+  allCategories: readonly string[] = categories,
+): string[] {
+  const list = Array.isArray(colors) ? (colors as ChartSeriesColor[]) : undefined
+  const record = !Array.isArray(colors) && colors ? (colors as Partial<Record<string, ChartSeriesColor>>) : undefined
+  return categories.map((category, i) => {
+    if ((otherCategory !== null && category === otherCategory) || category === OTHER_SERIES_LABEL) return otherColor
+    const fromRecord = record?.[category]
+    if (fromRecord) return fromRecord
+    if (list && list.length > 0) {
+      const at = allCategories.indexOf(category)
+      return list[(at === -1 ? i : at) % list.length]!
+    }
+    return DEFAULT_CHART_COLORS[i % DEFAULT_CHART_COLORS.length]!
+  })
+}
+
+/* ------------------------------------------------------------------ Donut */
+
+/** One drawn donut slice, largest first. */
+interface DonutSlice {
+  name: string
+  /** Negative and missing values count as 0. */
+  value: number
+  /** A chart token (`"chart-1"`…), or `otherColor` for the folded slice. */
+  color: string
+  /** The folded「その他」slice. */
+  isOther: boolean
+  /** The input row, or a synthesized `{ [index]: "その他", [value]: sum }` for the folded slice. */
+  row: Record<string, unknown>
+}
+
+interface DonutSlicesConfig {
+  /** Label column. */
+  index: string
+  /** Value column. */
+  value: string
+  /** Slice colours by rank (cycled). Default: the token palette in order. */
+  colors?: readonly ChartSeriesColor[]
+  /** How many slices are drawn individually; the rest fold into「その他」. Default 5. */
+  maxSlices?: number
+  /** Colour of the folded slice (pass `CHART_OTHER_COLOR`). */
+  otherColor: string
+  otherLabel?: string
+}
+
+/**
+ * Donut slices: sorted by value (largest first, ties keep input order), the
+ * `maxSlices` largest kept and coloured by rank in fixed token order, the rest
+ * summed into one「その他」slice in `otherColor`.
+ */
+function donutSlices(
+  data: readonly Record<string, unknown>[],
+  { index, value, colors, maxSlices = MAX_CHART_SERIES, otherColor, otherLabel = OTHER_SERIES_LABEL }: DonutSlicesConfig,
+): DonutSlice[] {
+  const items = data
+    .map((row, i) => {
+      const n = toChartNumber(row[value])
+      return { name: String(row[index] ?? ""), value: n !== null && n > 0 ? n : 0, row, i }
+    })
+    .sort((a, b) => b.value - a.value || a.i - b.i)
+  const { top, other } = aggregateTopN(items, Math.max(1, maxSlices), otherLabel)
+  const palette = colors && colors.length > 0 ? colors : DEFAULT_CHART_COLORS
+  const slices: DonutSlice[] = top.map((item, rank) => ({
+    name: item.name,
+    value: item.value,
+    color: palette[rank % palette.length]!,
+    isOther: false,
+    row: item.row,
+  }))
+  if (other) {
+    slices.push({
+      name: other.name,
+      value: other.value,
+      color: otherColor,
+      isOther: true,
+      row: { [index]: other.name, [value]: other.value },
+    })
+  }
+  return slices
+}
+
+/* ---------------------------------------------------------------- BarList */
+
+type BarListSortOrder = "ascending" | "descending" | "none"
+
+/** Sort a copy of the rows by value; `"none"` keeps the given order. */
+function sortBarListData<T extends { value: number }>(data: readonly T[], sortOrder: BarListSortOrder): T[] {
+  const rows = [...data]
+  if (sortOrder === "ascending") rows.sort((a, b) => a.value - b.value)
+  else if (sortOrder === "descending") rows.sort((a, b) => b.value - a.value)
+  return rows
+}
+
+/** BarList-only settings. */
+interface BarListOptions {
+  /** 並べ順。既定 `"descending"`(大きい順)。`"none"` は渡した順。「その他」は常に最後。 */
+  sortOrder?: BarListSortOrder
+  /** 個別に出す行の数。超えた分は合計して「その他」の 1 行にまとめる。既定 5。 */
+  maxItems?: number
+  /** まとめた行のラベル。既定「その他」。 */
+  otherLabel?: string
+  /** 順位に入れず、常に「その他」へ足す行の名前。例 `["(not set)", "Unassigned"]`。 */
+  exclude?: readonly string[]
+  /** 値の横に構成比(「その他」も含めた全行の合計に対する割合。整数 %)を添える。例「¥8,240万 · 43%」。既定 `false`。 */
+  showShare?: boolean
+}
+
+/** One drawn BarList row. */
+interface BarListRow<Row = Record<string, unknown>> {
+  /** React key: the row's `key`, else its name (`"__other"` for the folded row). */
+  key: string
+  name: string
+  value: number
+  /** Only for real rows; the folded row never links. */
+  href?: string
+  /** Legacy per-row colour (`BarListItem.color`). */
+  color?: ChartColor
+  /** The folded「その他」row. */
+  isOther: boolean
+  /** The input row (`null` for the folded row). */
+  row: Row | null
+}
+
+interface BarListRowsConfig extends BarListOptions {
+  /** Name column. Default `"name"`. */
+  index?: string
+  /** Value column. Default `"value"`. */
+  category?: string
+}
+
+/**
+ * The rows a BarList draws: read name / value (numeric strings count, gaps are
+ * 0), keep the `maxItems` largest (via `aggregateTopN`), sort them, and append
+ * the folded remainder as one「その他」row. Rows named in `exclude` skip the
+ * ranking and are always added to「その他」.
+ */
+function barListRows<Row extends object>(
+  data: readonly Row[],
+  { index = "name", category = "value", sortOrder = "descending", maxItems = MAX_CHART_SERIES, otherLabel = OTHER_SERIES_LABEL, exclude }: BarListRowsConfig = {},
+): BarListRow<Row>[] {
+  const items = data.map((row): BarListRow<Row> => {
+    const cells = row as Record<string, unknown>
+    const name = String(cells[index] ?? "")
+    return {
+      key: typeof cells.key === "string" ? cells.key : name,
+      name,
+      value: toChartNumber(cells[category]) ?? 0,
+      href: typeof cells.href === "string" ? cells.href : undefined,
+      color: typeof cells.color === "string" ? cells.color : undefined,
+      isOther: false,
+      row,
+    }
+  })
+  const excluded = new Set(exclude ?? [])
+  const ranked = excluded.size > 0 ? items.filter((item) => !excluded.has(item.name)) : items
+  const outside = excluded.size > 0 ? items.filter((item) => excluded.has(item.name)) : []
+  const { top, other } = aggregateTopN(ranked, Math.max(0, maxItems), otherLabel)
+  const rows = sortBarListData(top, sortOrder)
+  if (other || outside.length > 0) {
+    const value = (other?.value ?? 0) + outside.reduce((sum, item) => sum + item.value, 0)
+    rows.push({ key: "__other", name: otherLabel, value, isOther: true, row: null })
+  }
+  return rows
+}
+
+/** Bar widths in percent of the largest value (at least a sliver for non-zero values). */
+function barListWidths(values: readonly number[]): number[] {
+  const max = Math.max(0, ...values)
+  if (max === 0) return values.map(() => 0)
+  return values.map((v) => (v <= 0 ? 0 : Math.max(1, (v / max) * 100)))
+}
+
+/**
+ * How strongly the BarList bars are painted: every row the same tint of the bar
+ * colour (rank is the bar's length, not its weight). A tint over transparent, so
+ * it sits on the card in light and dark; it must stay visible against the card
+ * while the label printed over the bar keeps its contrast (see `tests/contrast.test.ts`).
+ */
+const BAR_LIST_TINT = 45
+/** 「その他」: a tint of the other colour, so it is the palest fill in the list (light and dark). */
+const BAR_LIST_OTHER_TINT = 30
+
+/**
+ * The fill of each BarList row: all real rows in the same tint of `color`
+ * (`BAR_LIST_TINT`), the folded「その他」row in a tint of `otherColor`
+ * (`BAR_LIST_OTHER_TINT`) — the palest fill, a remainder never outweighs a
+ * ranked row. A legacy per-row `color` (or a threshold tone) replaces `color`
+ * for that row. A tint, not the solid token, so the label printed over the bar
+ * keeps its contrast.
+ */
+function barListFills(
+  rows: readonly Pick<BarListRow, "isOther" | "color">[],
+  color: ChartColor,
+  otherColor: string,
+): string[] {
+  return rows.map((row) =>
+    row.isOther ? tintCss(otherColor, BAR_LIST_OTHER_TINT) : tintCss(chartColorToCss(row.color ?? color), BAR_LIST_TINT),
+  )
+}
+
+/** A row's share of `total` as text: whole percent (fixed, no decimals), `<1%` for a sliver, `0%` for nothing. */
+function barListShareText(value: number, total: number): string {
+  const v = Number.isFinite(value) && value > 0 ? value : 0
+  if (total <= 0 || v === 0) return "0%"
+  const pct = (v / total) * 100
+  return pct < 1 ? "<1%" : `${Math.round(pct)}%`
+}
+
+/**
+ * The text at the end of each BarList row: the formatted value and, with
+ * `showShare`, its share of the total of all drawn rows (including「その他」,
+ * so the shares are of the whole list): `value` and `share` apart (the share is
+ * drawn muted), `text` as one string (「¥8,240万 · 43%」).
+ */
+function barListValueTexts(
+  values: readonly number[],
+  formatter: ValueFormatter,
+  showShare = false,
+): { value: string; share?: string; text: string }[] {
+  const total = values.reduce((sum, v) => sum + (Number.isFinite(v) && v > 0 ? v : 0), 0)
+  return values.map((v) => {
+    const value = formatter(v)
+    if (!showShare) return { value, text: value }
+    const share = barListShareText(v, total)
+    return { value, share, text: `${value} · ${share}` }
+  })
+}
+
+/* -------------------------------------------------------------- DataTable */
+
+/** The visually-hidden table `ChartFrame` renders next to the plot (`dataTable`). */
+interface ChartDataTable {
+  /** 表の見出し(`<caption>`)。 */
+  caption?: string
+  /** 列見出し。先頭がラベル列。 */
+  columns: string[]
+  /** 行。セルは書式済みの文字列。 */
+  rows: string[][]
+}
+
+/**
+ * The chart's numbers as a table, for screen readers: one row per data row, the
+ * `index` cell then each category through `formatter` (gaps → `—`). `labels`
+ * renames column keys for the header (`{ sessions: "セッション" }`); `indexName` is the first column's header when `labels` has none for `index` (e.g. 「項目」, instead of the raw key).
+ */
+function chartDataTable(
+  data: readonly Record<string, unknown>[],
+  index: string,
+  categories: readonly string[],
+  formatter: ValueFormatter,
+  labels?: Readonly<Record<string, string>>,
+  indexName?: string,
+): ChartDataTable {
+  const label = (key: string) => labels?.[key] ?? key
+  return {
+    columns: [labels?.[index] ?? indexName ?? index, ...categories.map(label)],
+    rows: data.map((row) => [
+      String(row[index] ?? ""),
+      ...categories.map((key) => {
+        const n = toChartNumber(row[key])
+        return n === null ? EMPTY_VALUE : formatter(n)
+      }),
+    ]),
+  }
+}
+
+/* ------------------------------------------------------------ CategoryBar */
+
+interface CategoryBarSegment {
+  /** Width in percent of the whole bar. */
+  width: number
+  /** Where the segment starts, in percent. */
+  start: number
+  /** The running total at the segment's end — what its right-hand label shows. */
+  end: number
+}
+
+/** Lay the values side by side; negative values count as zero. */
+function categoryBarSegments(values: readonly number[]): CategoryBarSegment[] {
+  const clean = values.map((v) => (Number.isFinite(v) && v > 0 ? v : 0))
+  const total = clean.reduce((sum, v) => sum + v, 0)
+  let running = 0
+  return clean.map((v) => {
+    const start = total === 0 ? 0 : (running / total) * 100
+    running += v
+    return { width: total === 0 ? 0 : (v / total) * 100, start, end: running }
+  })
+}
+
+interface CategoryBarLabel {
+  /** Position in percent of the bar. */
+  position: number
+  /** The running total printed there. */
+  value: number
+}
+
+/**
+ * Tick labels under the bar: `0` at the start, then the running total at each
+ * segment's end. A label closer than `minGap` percent to the one before is
+ * dropped so narrow segments don't print on top of each other — except the
+ * last one (the total), which replaces its neighbour instead. With a
+ * `markerPosition`, an inner label closer than `minGap` to the marker is dropped
+ * too — the marker sits right under it and the two read as one crowded spot.
+ */
+function categoryBarLabels(values: readonly number[], minGap = 8, markerPosition?: number): CategoryBarLabel[] {
+  const segments = categoryBarSegments(values).filter((s) => s.width > 0)
+  if (segments.length === 0) return []
+  const labels: CategoryBarLabel[] = [{ position: 0, value: 0 }]
+  segments.forEach((s, i) => {
+    const label = { position: s.start + s.width, value: s.end }
+    const prev = labels[labels.length - 1]!
+    if (label.position - prev.position >= minGap) labels.push(label)
+    else if (i === segments.length - 1 && labels.length > 1) labels[labels.length - 1] = label
+  })
+  if (markerPosition === undefined || !Number.isFinite(markerPosition)) return labels
+  return labels.filter(
+    (label, i) => i === 0 || i === labels.length - 1 || Math.abs(label.position - markerPosition) >= minGap,
+  )
+}
+
+/**
+ * `labels` thinned to what fits side by side on a bar `width` px wide, given each label's printed text
+ * (`texts`, same order): a label that would touch the one before is dropped — except the last (the
+ * total), which replaces its neighbour instead. The first sits at the left edge, the last at the right
+ * edge, the rest centred on their position. The width is a rough estimate (full-width characters 12 px,
+ * the rest 7 px at 12 px type).
+ */
+function categoryBarFitLabels(
+  labels: readonly CategoryBarLabel[],
+  texts: readonly string[],
+  width: number,
+  gap = 8,
+): CategoryBarLabel[] {
+  const textWidth = (text: string) => {
+    let w = 0
+    for (const ch of text) w += /[\u3000-\u9fff\uff00-\uffef]/.test(ch) ? 12 : 7
+    return w
+  }
+  const extent = (label: CategoryBarLabel, text: string): [number, number] => {
+    const w = textWidth(text)
+    if (label.position <= 0) return [0, w]
+    if (label.position >= 100) return [width - w, width]
+    const center = (label.position / 100) * width
+    return [center - w / 2, center + w / 2]
+  }
+  const kept: { label: CategoryBarLabel; extent: [number, number] }[] = []
+  labels.forEach((label, i) => {
+    const here = extent(label, texts[i] ?? "")
+    const touches = () => kept.length > 0 && kept[kept.length - 1]!.extent[1] + gap > here[0]
+    if (i === labels.length - 1) while (kept.length > 1 && touches()) kept.pop()
+    else if (touches()) return
+    kept.push({ label, extent: here })
+  })
+  return kept.map((k) => k.label)
+}
+
+/** Marker position in percent of the bar, clamped to its ends. */
+function categoryBarMarkerPosition(value: number, values: readonly number[]): number {
+  const total = values.reduce((sum, v) => sum + (Number.isFinite(v) && v > 0 ? v : 0), 0)
+  if (total === 0) return 0
+  return clamp((value / total) * 100, 0, 100)
+}
+
+/** Index of the segment the marker sits on (the last one for a value past the end). */
+function categoryBarMarkerSegment(value: number, values: readonly number[]): number {
+  const segments = categoryBarSegments(values)
+  const index = segments.findIndex((s) => s.width > 0 && value <= s.end)
+  if (index !== -1) return index
+  for (let i = segments.length - 1; i >= 0; i--) if (segments[i]!.width > 0) return i
+  return 0
+}
+
+/* --------------------------------------------------------- ProgressCircle */
+
+interface ProgressCircleGeometry {
+  /** SVG width/height. */
+  size: number
+  /** Radius of the stroke's centre line. */
+  normalizedRadius: number
+  circumference: number
+  /** `stroke-dashoffset` for the value arc. */
+  offset: number
+  /** The value as a fraction of `max`, clamped to `[0, 1]`. */
+  ratio: number
+}
+
+function progressCircleGeometry(
+  value: number,
+  max: number,
+  radius: number,
+  strokeWidth: number,
+): ProgressCircleGeometry {
+  const ratio = max > 0 && Number.isFinite(value) ? clamp(value / max, 0, 1) : 0
+  const normalizedRadius = Math.max(0, radius - strokeWidth / 2)
+  const circumference = 2 * Math.PI * normalizedRadius
+  return { size: radius * 2, normalizedRadius, circumference, offset: circumference * (1 - ratio), ratio }
+}
+
+/* ---------------------------------------------------------------- summary */
+
+interface ChartSummaryInput {
+  data: readonly Record<string, unknown>[]
+  /** The x-axis key. */
+  index: string
+  /** Series keys; the first one is described. */
+  categories: readonly string[]
+  /** Title of the chart, put in front when given. */
+  title?: string
+  /** Same as the chart's `format` (default `"compact"`). */
+  format?: ValueFormat
+  /** Wins over `format`. */
+  valueFormatter?: ValueFormatter
+}
+
+/**
+ * One-sentence summary built from the rows, for `summary="auto"`:
+ * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」. The direction is
+ * computed from the last two non-empty points of the first series — never
+ * written by hand, so it cannot contradict the data. `undefined` when there is
+ * no usable point.
+ */
+function buildChartSummary(input: ChartSummaryInput): string | undefined {
+  const key = input.categories[0]
+  if (key === undefined) return undefined
+  const points: { label: string; value: number }[] = []
+  for (const row of input.data) {
+    const raw = row[key]
+    const value = raw === null || raw === undefined || raw === "" ? NaN : Number(raw)
+    if (Number.isFinite(value)) points.push({ label: String(row[input.index] ?? ""), value })
+  }
+  const latest = points[points.length - 1]
+  if (!latest) return undefined
+  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact")
+  const prev = points[points.length - 2]
+  const direction = !prev ? "" : latest.value > prev.value ? "、前の点より増加" : latest.value < prev.value ? "、前の点より減少" : "、前の点と横ばい"
+  const head = input.title ? `${input.title}: ` : ""
+  return `${head}最新 ${latest.label} は ${text(latest.value)}${direction}`
+}
+
+/**
+ * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」 from the slices
+ * (largest first). `undefined` when there is nothing to describe.
+ */
+function buildShareSummary(
+  slices: readonly { name: string; value: number }[],
+  title?: string,
+): string | undefined {
+  const total = slices.reduce((sum, s) => sum + s.value, 0)
+  const top = slices[0]
+  if (!top || total <= 0) return undefined
+  const share = `${Math.round((top.value / total) * 1000) / 10}%`
+  return `${title ? `${title}: ` : ""}最大は ${top.name}(${share})`
+}
+
+/* ---------- end of inlined code ---------- */
+
+/** The shape the loading skeleton takes, matching the chart it stands in for. */
+export type ChartSkeletonVariant = "line" | "area" | "bar" | "donut" | "list"
+
+/** The plot height of every typed chart unless `height` says otherwise (px). */
+export const DEFAULT_CHART_HEIGHT = 288
+
+const DEFAULT_EMPTY_TITLE = "表示できるデータがありません"
+
+export interface ChartFrameProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "children"> {
+  /** グラフの見出し。プロット領域の `aria-labelledby` になる。 */
+  title?: string
+  /** 1 文の要約。見出しの下に出し、プロット領域の `aria-describedby` になる。 */
+  summary?: string
+  /** 読み込み中。`variant` の形のスケルトンを同じ高さで出す。 */
+  isLoading?: boolean
+  /** データが無い。高さを保ったまま `emptyState` を出す。 */
+  isEmpty?: boolean
+  emptyState?: ChartEmptyState
+  /** プロット領域の高さ。数値は px。既定 288。 */
+  height?: number | string
+  /** スケルトンの形。既定 `"line"`。 */
+  variant?: ChartSkeletonVariant
+  /** 見出しが無いときのプロット領域のラベル。 */
+  ariaLabel?: string
+  /**
+   * プロット領域の役割。既定 `"img"`(canvas のグラフ)。行がボタンやリンクになる
+   * HTML のグラフ(BarList・FunnelSteps)は `"group"` にして、中身を読ませる。
+   */
+  plotRole?: "img" | "group"
+  /** 値の表。画面には出さず(`sr-only`)、スクリーンリーダー向けに図の中に置く。`chartDataTable` で作る。 */
+  dataTable?: ChartDataTable
+  /** プロット(チャート本体)。読み込み中・空のときは描かない。 */
+  children?: ReactNode
+}
+
+/**
+ * The frame. `ref` points at the plot area (the element with the fixed height),
+ * `className` / other attributes go to the outer `<figure>`.
+ */
+export const ChartFrame = forwardRef<HTMLDivElement, ChartFrameProps>(function ChartFrame(
+  {
+    title,
+    summary,
+    isLoading = false,
+    isEmpty = false,
+    emptyState,
+    height = DEFAULT_CHART_HEIGHT,
+    variant = "line",
+    ariaLabel,
+    plotRole = "img",
+    dataTable,
+    className,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const id = useId()
+  const titleId = title ? `${id}-title` : undefined
+  const summaryId = summary ? `${id}-summary` : undefined
+  const state = isLoading ? "loading" : isEmpty ? "empty" : "ready"
+
+  return (
+    <figure data-slot="chart-frame" className={cn("m-0 flex w-full min-w-0 flex-col gap-3", className)} {...props}>
+      {(title || summary) && (
+        <figcaption data-slot="chart-frame-header" className="flex flex-col gap-1">
+          {title && (
+            <h3 id={titleId} data-slot="chart-frame-title" className="text-sm leading-snug font-semibold">
+              {title}
+            </h3>
+          )}
+          {summary && (
+            <p id={summaryId} data-slot="chart-frame-summary" className="text-sm leading-relaxed text-muted-foreground">
+              {summary}
+            </p>
+          )}
+        </figcaption>
+      )}
+      <div
+        ref={ref}
+        data-slot="chart-frame-body"
+        data-state={state}
+        role={state === "ready" ? plotRole : "group"}
+        aria-label={titleId ? undefined : ariaLabel}
+        aria-labelledby={titleId}
+        aria-describedby={summaryId}
+        aria-busy={isLoading || undefined}
+        className="relative w-full min-w-0"
+        style={{ height: typeof height === "number" ? `${height}px` : height }}
+      >
+        {state === "loading" ? (
+          <ChartSkeleton variant={variant} />
+        ) : state === "empty" ? (
+          <ChartEmpty {...emptyState} />
+        ) : (
+          <ChartFrameContext.Provider value>{children}</ChartFrameContext.Provider>
+        )}
+      </div>
+      {state === "ready" && dataTable && dataTable.rows.length > 0 && (
+        <ChartDataTableView table={dataTable} fallbackCaption={title ?? ariaLabel} />
+      )}
+    </figure>
+  )
+})
+ChartFrame.displayName = "ChartFrame"
+
+/* ---------------------------------------------------------------- skeleton */
+
+const BAR_HEIGHTS = [58, 74, 46, 88, 64, 80, 52]
+const LIST_WIDTHS = [92, 76, 64, 48, 36]
+const LINE_POINTS = "0,70 16,58 33,62 50,40 66,46 83,28 100,34"
+
+function ChartSkeleton({ variant }: { variant: ChartSkeletonVariant }) {
+  const pulse = "animate-pulse motion-reduce:animate-none"
+  return (
+    <div data-slot="chart-skeleton" data-variant={variant} className="absolute inset-0 flex flex-col gap-3">
+      <div aria-hidden="true" className="contents">
+      {variant === "list" ? (
+        <div className={cn("flex flex-1 flex-col justify-around", pulse)}>
+          {LIST_WIDTHS.map((w) => (
+            <div key={w} className="flex items-center gap-3">
+              <div className="h-5 rounded-sm bg-muted" style={{ width: `${w}%` }} />
+            </div>
+          ))}
+        </div>
+      ) : variant === "donut" ? (
+        <div className={cn("flex flex-1 items-center justify-center", pulse)}>
+          <svg viewBox="0 0 100 100" className="h-full max-h-full w-auto text-muted">
+            <circle cx="50" cy="50" r="40" fill="none" stroke="currentColor" strokeWidth="14" />
+          </svg>
+        </div>
+      ) : variant === "bar" ? (
+        <div className={cn("flex flex-1 items-end gap-3 px-1", pulse)}>
+          {BAR_HEIGHTS.map((h, i) => (
+            <div key={i} className="flex-1 rounded-t-sm bg-muted" style={{ height: `${h}%` }} />
+          ))}
+        </div>
+      ) : (
+        // A soft muted silhouette only — no stroke, no baseline, nothing that reads as a data line.
+        <div className={cn("relative flex-1", pulse)}>
+          <svg viewBox="0 0 100 100" preserveAspectRatio="none" className="absolute inset-0 h-full w-full text-muted">
+            <polygon points={`${LINE_POINTS} 100,100 0,100`} fill="currentColor" opacity={variant === "area" ? 0.8 : 0.5} />
+          </svg>
+        </div>
+      )}
+      </div>
+      <span className="sr-only">読み込み中</span>
+    </div>
+  )
+}
+
+/* --------------------------------------------------------------- data table */
+
+function ChartDataTableView({ table, fallbackCaption }: { table: ChartDataTable; fallbackCaption?: string }) {
+  const caption = table.caption ?? fallbackCaption
+  // The wrapper is the visually-hidden box: `sr-only` on the <table> itself still
+  // lets table auto-layout give it a real width, which overflows narrow pages.
+  return (
+    <div data-slot="chart-frame-table-wrapper" className="sr-only">
+      <table data-slot="chart-frame-table">
+        {caption && <caption>{caption}</caption>}
+        <thead>
+          <tr>
+            {table.columns.map((column, i) => (
+              <th key={i} scope="col">
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row, r) => (
+            <tr key={r}>
+              {row.map((cell, c) =>
+                c === 0 ? (
+                  <th key={c} scope="row">
+                    {cell}
+                  </th>
+                ) : (
+                  <td key={c}>{cell}</td>
+                ),
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------- empty */
+
+function ChartEmpty({ title, description, action }: ChartEmptyState) {
+  return (
+    <div
+      data-slot="chart-empty"
+      className="absolute inset-0 flex flex-col items-center justify-center gap-1 rounded-md border border-dashed border-border p-6 text-center"
+    >
+      <p className="text-sm font-medium text-balance">{title ?? DEFAULT_EMPTY_TITLE}</p>
+      {description && <p className="max-w-prose text-sm text-balance text-muted-foreground">{description}</p>}
+      {action && <div className="mt-3">{action}</div>}
+    </div>
+  )
+}