@squadbase/vantage 0.6.2 → 0.7.0-dev1.19083f7

package/registry/ui/heatmap.tsx

@@ -0,0 +1,2027 @@
+// Copied by `vantage add ui heatmap`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/charts/heatmap.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * Heatmap — a typed heatmap over `EChart`: pass rows, the column keys for the
+ * x axis / y axis (`x` / `y`) and the number to shade by (`value`) instead of an
+ * ECharts option. Cohort retention (週 × コホート), weekday × hour counts, …
+ *
+ * Shading is a single-colour ramp (light → dark) of one theme colour
+ * (`--chart-1` by default; `tone` moves it to another series token or a meaning
+ * colour) and follows light/dark. A cell with no value (null / missing row) is left
+ * unpainted (transparent, no text), never shaded like 0; the tooltip and the table say「—」.
+ * The shading range is the data's min–max unless `scale` fixes it. The ramp's lowest end is the tone mixed 20% into
+ * the surface (`color-mix(in oklch, var(--chart-1) 20%, var(--card))`), so the lowest cell never melts into the
+ * background in dark mode; the legend's gradient starts at the same colour.
+ * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state)
+ * with the numbers as a screen-reader table.
+ */
+import { forwardRef, useMemo, type ForwardedRef, type ReactElement, type Ref } from "react"
+import { use } from "echarts/core"
+import { HeatmapChart } from "echarts/charts"
+import { VisualMapComponent } from "echarts/components"
+import type { EChartsOption } from "echarts"
+
+import { ChartFrame } from "@squadbase/vantage/components"
+import { EChart } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, type ValueFormat } from "@squadbase/vantage/components"
+import type { ChartActionsOptions, ChartEmptyState, ChartRootAttributes, ChartSeriesColor, ValueFormatter } from "@squadbase/vantage/components"
+import { useSyncExternalStore } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, type RefObject } from "react"
+import type { ChartTone } from "@squadbase/vantage/components"
+import { formatValue, toValueFormatter } from "@squadbase/vantage/components"
+import type { ChartColor, ChartColors } from "@squadbase/vantage/components"
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The display language of the parts and the defaults that follow it.
+ *
+ * The language comes from `<html lang>`: a tag starting with `ja` reads Japanese, anything else English.
+ * Without a usable `lang` (missing, invalid, or no `document` — SSR, Node) the locale is `FALLBACK_LOCALE`
+ * (`en-US`). A `locale` passed explicitly (a prop, an argument) always wins.
+ *
+ * Parts read the locale through `useLocale` (`hooks/use-locale`) and pass it down; the pure helpers here
+ * and in `format` / `comparison` / `chart-*` take it as an argument and fall back to `documentLocale()`.
+ */
+
+/** The language of the built-in wording: Japanese or English. */
+type UiLanguage = "ja" | "en"
+
+/** The locale used when `<html lang>` gives none (and on the server). */
+const FALLBACK_LOCALE = "en-US"
+
+/** `"ja"` when `locale` starts with `ja` (`ja`, `ja-JP`), else `"en"`. A missing locale is `"en"`. */
+function uiLanguage(locale: string | null | undefined): UiLanguage {
+  return typeof locale === "string" && locale.trim().toLowerCase().startsWith("ja") ? "ja" : "en"
+}
+
+/** A BCP 47 tag in its canonical form (`en-gb` → `en-GB`), or `FALLBACK_LOCALE` when it is empty or invalid. */
+function normalizeLocale(tag: string | null | undefined): string {
+  const value = tag?.trim()
+  if (!value) return FALLBACK_LOCALE
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? FALLBACK_LOCALE
+  } catch {
+    return FALLBACK_LOCALE
+  }
+}
+
+/**
+ * The locale of the page: `document.documentElement.lang`, canonicalized. `FALLBACK_LOCALE` when it is empty or
+ * invalid, or there is no `document`. Parts read it through `useLocale`, never while rendering.
+ */
+function documentLocale(): string {
+  if (typeof document === "undefined") return FALLBACK_LOCALE
+  return normalizeLocale(document.documentElement?.getAttribute("lang"))
+}
+
+/** `locale` when given, else the page's locale (`documentLocale()`). */
+function resolveLocale(locale?: string | null): string {
+  return locale || documentLocale()
+}
+
+/** Picks the wording table of the locale's language. */
+function pickLocale<T>(table: { ja: T; en: T }, locale?: string | null): T {
+  return table[uiLanguage(resolveLocale(locale))]
+}
+
+/** The currency `format="currency"` uses without a `currency`: JPY for Japanese, USD otherwise. */
+function defaultCurrency(locale?: string | null): string {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? "JPY" : "USD"
+}
+
+/** The month a fiscal year starts in (1–12) when none is given: April for Japanese, January otherwise. */
+function defaultFiscalYearStartMonth(locale?: string | null): number {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? 4 : 1
+}
+
+/** A day of the week, 0 = Sunday … 6 = Saturday (the `Date#getDay` / date-fns numbering). */
+type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+/** Locales whose week starts on Sunday when the runtime has no week data. */
+const SUNDAY_FIRST = new Set(["en", "en-US", "en-CA"])
+
+/**
+ * The first day of the week: Monday for Japanese; otherwise the locale's convention from `Intl.Locale`
+ * (`en-US` Sunday, `en-GB` Monday). Without week data in the runtime: Sunday for `en` / `en-US` / `en-CA`,
+ * Monday for the rest.
+ */
+function weekStartsOn(locale?: string | null): WeekDay {
+  const tag = normalizeLocale(resolveLocale(locale))
+  if (uiLanguage(tag) === "ja") return 1
+  try {
+    const info = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number }
+      weekInfo?: { firstDay: number }
+    }
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay
+    if (typeof firstDay === "number" && firstDay >= 1 && firstDay <= 7) return (firstDay % 7) as WeekDay
+  } catch {
+    // Fall through to the table below.
+  }
+  return SUNDAY_FIRST.has(tag) ? 0 : 1
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/hooks/use-locale.ts (internal to @squadbase/vantage) ---------- */
+
+const listeners = new Set<() => void>()
+let observer: MutationObserver | null = null
+
+/** One observer on `<html lang>` for every subscribed part. */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {}
+  listeners.add(onChange)
+  if (!observer) {
+    observer = new MutationObserver(() => {
+      for (const listener of [...listeners]) listener()
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] })
+  }
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0 && observer) {
+      observer.disconnect()
+      observer = null
+    }
+  }
+}
+
+const serverLocale = () => FALLBACK_LOCALE
+
+/**
+ * The page's locale (`<html lang>`), following changes made while the page runs. On the server and during
+ * hydration it is `FALLBACK_LOCALE` (`en-US`), so the markup matches; it switches right after.
+ */
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
+
+/** The locale a part renders in: its `locale` prop when given, else the page's (`useDocumentLocale`). */
+function useLocale(locale?: string | null): string {
+  const page = useDocumentLocale()
+  return locale || page
+}
+
+/* ---------- 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,
+  localeArg?: string,
+): ValueFormatter {
+  if (valueFormatter) return valueFormatter
+  const locale = resolveLocale(localeArg)
+  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)
+}
+
+interface CompactUnit {
+  token: string
+  size: number
+}
+
+const compactUnitCache = new Map<string, CompactUnit[] | null>()
+
+/**
+ * The compact-notation unit words of a locale and their sizes, largest first: `兆` / `億` / `万` in ja,
+ * `T` / `B` / `M` / `K` in en. `null` when the locale's compact form puts anything between the number and its
+ * word (`1,5 Mio.`), where a token cannot be swapped in place.
+ */
+function compactUnits(locale: string): CompactUnit[] | null {
+  const cached = compactUnitCache.get(locale)
+  if (cached !== undefined) return cached
+  let units: CompactUnit[] | null = []
+  try {
+    const compact = new Intl.NumberFormat(locale, { notation: "compact" })
+    const seen = new Set<string>()
+    for (let exp = 3; exp <= 15; exp++) {
+      const parts = compact.formatToParts(10 ** exp)
+      const at = parts.findIndex((p) => p.type === "compact")
+      if (at === -1) continue
+      if (parts[at - 1]?.type !== "integer" || at !== parts.length - 1) {
+        units = null
+        break
+      }
+      const token = parts[at]!.value
+      if (seen.has(token)) continue
+      seen.add(token)
+      units.push({ token, size: 10 ** exp })
+    }
+  } catch {
+    units = null
+  }
+  const sorted = units && units.length > 0 ? units.sort((a, b) => b.size - a.size) : null
+  compactUnitCache.set(locale, sorted)
+  return sorted
+}
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/**
+ * The value-axis tick formatter for an axis whose largest tick is `top`: every tick reads in the unit of
+ * that largest tick, so units never mix on one axis (`¥0.5億` / `¥1億` / `¥1.5億`, not `¥5,000万` / `¥1億`;
+ * `$0.5M` / `$1M` / `$1.5M`, not `$500K` / `$1M`). Only the short forms (`compact` / `number` / `currency`,
+ * no `valueFormatter`) have units to align; any other format — an axis whose largest tick is under the smallest
+ * unit (1万 / 1K), or a locale whose compact form cannot be aligned in place — keeps `resolveAxisFormatter`'s output as it is.
+ */
+function resolveAxisTickFormatter(
+  valueFormatter: ValueFormatter | undefined,
+  format: ValueFormat | undefined,
+  localeArg?: string,
+): (top: number) => ValueFormatter {
+  const locale = resolveLocale(localeArg)
+  const base = resolveAxisFormatter(valueFormatter, format, locale)
+  const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
+  const units = !valueFormatter && (spec.type === "compact" || spec.type === "number" || spec.type === "currency") ? compactUnits(locale) : null
+  if (!units) return () => base
+  const number = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 })
+  const numberToken = new RegExp(`\\d[\\d,]*(?:\\.\\d+)?(?:${units.map((u) => escapeRegExp(u.token)).join("|")})?`)
+  return (top) => {
+    const unit = 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.token}`
+      return text.replace(numberToken, () => 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, by language. */
+const OTHER_SERIES_LABELS: Record<UiLanguage, string> = { ja: "その他", en: "Other" }
+
+/** The series name the folded categories get in `locale` ("Other" / "その他"). Default the page's locale (`<html lang>`). */
+function otherSeriesLabel(locale?: string): string {
+  return OTHER_SERIES_LABELS[uiLanguage(resolveLocale(locale))]
+}
+
+const OTHER_NAMES = new Set(Object.values(OTHER_SERIES_LABELS))
+
+/** Whether a category / row is the "other" bucket by name (「その他」 or "Other", whatever the page language). */
+function isOtherName(name: string | null | undefined): boolean {
+  return typeof name === "string" && OTHER_NAMES.has(name)
+}
+
+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 = otherSeriesLabel(),
+): 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 = otherSeriesLabel(),
+): 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,
+  otherLabel: string = otherSeriesLabel(),
+): AggregatedSeries {
+  if (keep === undefined || !categories.includes(keep)) return aggregateSeries(data, categories, n, otherLabel)
+  const aggregated = aggregateSeries(
+    data,
+    categories.filter((c) => c !== keep),
+    n,
+    otherLabel,
+  )
+  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" (`OTHER_SERIES_LABELS`) — 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) || isOtherName(category)) 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 = otherSeriesLabel() }: 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,
+    // A row the data itself names「その他」/ "Other" is the same remainder: grey, like the folded slice.
+    color: isOtherName(item.name) ? otherColor : 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 = otherSeriesLabel(), 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 (and a row the data names「その他」/ "Other") 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"> & { name?: string })[],
+  color: ChartColor,
+  otherColor: string,
+): string[] {
+  return rows.map((row) =>
+    row.isOther || isOtherName(row.name)
+      ? 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
+  /** Language of the sentence. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+const SUMMARY_TEXT = {
+  ja: {
+    up: "、前の点より増加",
+    down: "、前の点より減少",
+    flat: "、前の点と横ばい",
+    latest: (label: string, value: string) => `最新 ${label} は ${value}`,
+    top: (name: string, share: string) => `最大は ${name}(${share})`,
+  },
+  en: {
+    up: ", up from the previous point",
+    down: ", down from the previous point",
+    flat: ", flat from the previous point",
+    latest: (label: string, value: string) => `Latest ${label}: ${value}`,
+    top: (name: string, share: string) => `Largest: ${name} (${share})`,
+  },
+}
+
+/**
+ * One-sentence summary built from the rows, for `summary="auto"`:
+ * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」("<title>: Latest <index>: <value>, up from the previous point"). 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 locale = resolveLocale(input.locale)
+  const t = SUMMARY_TEXT[uiLanguage(locale)]
+  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact", locale)
+  const prev = points[points.length - 2]
+  const direction = !prev ? "" : latest.value > prev.value ? t.up : latest.value < prev.value ? t.down : t.flat
+  const head = input.title ? `${input.title}: ` : ""
+  return `${head}${t.latest(latest.label, text(latest.value))}${direction}`
+}
+
+/**
+ * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」("<title>: Largest: <name> (<share>)") from the slices
+ * (largest first). `undefined` when there is nothing to describe. `locale` picks the language; default the page's.
+ */
+function buildShareSummary(
+  slices: readonly { name: string; value: number }[],
+  title?: string,
+  locale?: 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}: ` : ""}${SUMMARY_TEXT[uiLanguage(resolveLocale(locale))].top(top.name, share)}`
+}
+
+/* ---------- end of inlined code ---------- */
+
+// HeatmapChart and the (hidden) visual map that shades the cells are this part's own.
+use([HeatmapChart, VisualMapComponent])
+
+/** The lightest end of the ramp is this share of the tone colour mixed into the surface; the darkest end is the colour itself. */
+export const HEATMAP_FLOOR_SHARE = 0.2
+/** Cells at or above this share of the ramp get the surface colour as text (dark cell), below it the foreground. */
+export const HEATMAP_LIGHT_TEXT_FROM = 0.55
+
+/** Columns of `T` that hold numbers (null / undefined allowed for gaps); untyped rows keep every key. */
+type NumericColumn<T> = {
+  [K in keyof T]-?: unknown extends T[K] ? K : T[K] extends number | bigint | null | undefined ? K : never
+}[keyof T] &
+  string
+
+export interface HeatmapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+  /** 行の配列。1 行 = 1 マス(x と y の組)。同じ組が複数あれば後の行が勝つ。値は number か数値文字列。 */
+  data: T[]
+  /** 横軸(列)に使う列名。例 `"hour"`・`"week"`。 */
+  x: keyof T & string
+  /** 縦軸(行)に使う列名。例 `"weekday"`・`"cohort"`。先頭の行が一番上。 */
+  y: keyof T & string
+  /** マスの濃さを決める数値の列名。null・欠損・数値でない値のマスは塗らない(0 とは別。ツールチップとデータ表は「—」)。 */
+  value: NumericColumn<T>
+  /** 横軸の並び順(と表示するマス)。省略時は `data` の出現順。ここに無い x の行は描かない。 */
+  xLabels?: string[]
+  /** 縦軸の並び順(と表示するマス)。省略時は `data` の出現順。ここに無い y の行は描かない。 */
+  yLabels?: string[]
+  /**
+   * 列名・軸の値 → 表示名(軸・ツールチップ・データ表に反映)。
+   * 例 `{ mon: "月曜", value: "件数", breached: "SLA 未達" }`。無いキーはそのまま。データ表の先頭列名は `y` のキーを渡すと直る(既定は「項目」)。
+   */
+  labels?: Record<string, string>
+  /** 数値の書式(`"number"` / `"percent"` / `{ type: "number", unit: "件" }` など)。マス内・ツールチップ・データ表で同じ書式。既定 `"number"`。 */
+  format?: ValueFormat
+  /** 書式を関数で直接渡す逃げ道。`format` より優先する。 */
+  valueFormatter?: ValueFormatter
+  /**
+   * 濃淡の色。`"chart-1"`〜`"chart-5"` か意味色(`"positive"` / `"warning"` / `"negative"` / `"neutral"`)。
+   * 薄い → 濃いの単色グラデーション(レインボーにしない)。既定 `"chart-1"`。
+   */
+  tone?: ChartSeriesColor
+  /**
+   * 濃さの固定スケール。省略時はデータの最小〜最大(自動)。比べたい上限・下限が決まっているときだけ渡す。`min` 以下が最も薄く、`max` 以上が最も濃い(範囲外の値は端に丸める)。凡例の両端もこの値になる。
+   * 継続率(0〜100)なら `{ min: 0, max: 100 }`。片方だけでもよく、省略した側はデータの最小・最大。
+   * `minValue` / `maxValue` より優先する。
+   */
+  scale?: { min?: number; max?: number }
+  /** @deprecated `scale={{ min }}` を使う。濃さの下限(この値以下が最も薄い)。 */
+  minValue?: number
+  /** @deprecated `scale={{ max }}` を使う。濃さの上限(この値以上が最も濃い)。 */
+  maxValue?: number
+  /** マスの中に値を書く(`format` どおり)。既定 `false`。 */
+  showValues?: boolean
+  /** 凡例(薄い → 濃いの帯と両端の値)を出す。既定 `true`。 */
+  showLegend?: boolean
+  /** ホバーでツールチップを出す。既定 `true`。 */
+  showTooltip?: boolean
+  /**
+   * ツールチップとデータ表に添える列(同じ行の別の数値)。例 `["breached"]` →「月曜 9時台 電話 12件・SLA 未達 2件」の「SLA 未達 2件」。
+   * 列名の表示は `labels`、値は `format`(単位つきの書式なら同じ単位)で出る。
+   */
+  details?: NumericColumn<T>[]
+  /**
+   * この列が真(`true` / 0 でない数)の行のマスに、注意色(`--negative`)の枠を付ける。
+   * 例 SLA 未達が集中したマス。色だけでなく枠の太さでも区別でき、ツールチップに「要注意」と出る。
+   */
+  flag?: keyof T & string
+  /** グラフの見出し。 */
+  title?: string
+  /** グラフが言っていることの 1 文要約。`"auto"` で最大のマスから自動生成。 */
+  summary?: string | "auto"
+  /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+  isLoading?: boolean
+  /** `data` が空のときの表示。 */
+  emptyState?: ChartEmptyState
+  /** プロット領域の高さ(px)。既定 288。 */
+  height?: number
+  /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+  chartOptions?: EChartsOption
+  /** グラフ右上に PNG 保存/コピーのボタンを出す。見出しがあれば PNG の上に含める(`{ includeTitle: false }` で含めない)。 */
+  actions?: boolean | ChartActionsOptions
+  /** PNG 保存時のファイル名(拡張子つき)。 */
+  fileName?: string
+  className?: string
+  /** スクリーンリーダー向けのラベル。省略時は `<yの列>×<xの列>のヒートマップ`。 */
+  ariaLabel?: string
+}
+
+/* ------------------------------------------------------------------ model */
+
+export interface HeatmapCell {
+  /** Index into `xs`. */
+  xi: number
+  /** Index into `ys`. */
+  yi: number
+  /** `null` for a gap. */
+  value: number | null
+  flagged: boolean
+  row: Record<string, unknown> | null
+}
+
+export interface HeatmapModel {
+  xs: string[]
+  ys: string[]
+  /** One per grid position (`xs.length * ys.length`), row-major by y. */
+  cells: HeatmapCell[]
+  min: number
+  max: number
+  hasGap: boolean
+}
+
+function truthy(raw: unknown): boolean {
+  if (typeof raw === "number") return raw !== 0 && !Number.isNaN(raw)
+  return raw === true || raw === "true"
+}
+
+/** Rows → the grid: axes in order, one cell per (x, y) with `null` for gaps, and the shading range. */
+export function buildHeatmapModel(config: {
+  data: readonly Record<string, unknown>[]
+  x: string
+  y: string
+  value: string
+  xLabels?: readonly string[]
+  yLabels?: readonly string[]
+  flag?: string
+  scale?: { min?: number; max?: number }
+  /** @deprecated Use `scale`. */
+  minValue?: number
+  /** @deprecated Use `scale`. */
+  maxValue?: number
+}): HeatmapModel {
+  const { data, x, y, value, flag } = config
+  const order = (key: string, given: readonly string[] | undefined) => {
+    if (given) return [...given]
+    const seen: string[] = []
+    for (const row of data) {
+      const k = String(row[key] ?? "")
+      if (!seen.includes(k)) seen.push(k)
+    }
+    return seen
+  }
+  const xs = order(x, config.xLabels)
+  const ys = order(y, config.yLabels)
+  const byCell = new Map<string, Record<string, unknown>>()
+  for (const row of data) byCell.set(`${String(row[x] ?? "")}\u0000${String(row[y] ?? "")}`, row)
+  const cells: HeatmapCell[] = []
+  let lo = Infinity
+  let hi = -Infinity
+  let hasGap = false
+  ys.forEach((yk, yi) =>
+    xs.forEach((xk, xi) => {
+      const row = byCell.get(`${xk}\u0000${yk}`) ?? null
+      const n = row ? toChartNumber(row[value]) : null
+      if (n === null) hasGap = true
+      else {
+        lo = Math.min(lo, n)
+        hi = Math.max(hi, n)
+      }
+      cells.push({ xi, yi, value: n, flagged: !!(row && flag && truthy(row[flag])), row })
+    }),
+  )
+  const min = config.scale?.min ?? config.minValue ?? (Number.isFinite(lo) ? lo : 0)
+  let max = config.scale?.max ?? config.maxValue ?? (Number.isFinite(hi) ? hi : 1)
+  if (max <= min) max = min + 1
+  return { xs, ys, cells, min, max, hasGap }
+}
+
+/** The share (0–1) of the ramp a value sits at. */
+export function heatmapRatio(value: number, min: number, max: number): number {
+  return max > min ? Math.min(1, Math.max(0, (value - min) / (max - min))) : 1
+}
+
+/** A canvas-safe colour (`#rrggbb` / `rgb()` / `rgba()`) at `alpha`; anything else comes back unchanged. */
+export function withAlpha(color: string, alpha: number): string {
+  const hex = /^#([0-9a-f]{6})$/i.exec(color.trim())
+  if (hex) {
+    const n = parseInt(hex[1]!, 16)
+    return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color.trim())
+  return rgb ? `rgba(${rgb[1]}, ${rgb[2]}, ${rgb[3]}, ${alpha})` : color
+}
+
+/** `#rrggbb` / `rgb()` / `rgba()` → [r, g, b] (0–255), or null. */
+function parseRgb(color: string): [number, number, number] | null {
+  const hex = /^#([0-9a-f]{6})$/i.exec(color.trim())
+  if (hex) {
+    const n = parseInt(hex[1]!, 16)
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color.trim())
+  return rgb ? [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])] : null
+}
+
+const toLinear = (c: number) => ((c /= 255) <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const fromLinear = (c: number) => Math.round(255 * Math.min(1, Math.max(0, c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055)))
+
+function toOklab([r, g, b]: [number, number, number]): [number, number, number] {
+  const [lr, lg, lb] = [toLinear(r), toLinear(g), toLinear(b)]
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb)
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb)
+  const t = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb)
+  return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * t, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * t, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * t]
+}
+
+function fromOklab([L, a, b]: [number, number, number]): string {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const t = (L - 0.0894841775 * a - 1.291485548 * b) ** 3
+  const rgb = [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * t, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * t, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * t]
+  return `rgb(${rgb.map(fromLinear).join(", ")})`
+}
+
+/**
+ * `share` of `color` mixed into `surface` — the canvas form of `color-mix(in oklch, <color> 20%, <surface>)`. The
+ * surface is a neutral, so its hue is powerless and the oklch mix is the straight line in Oklab. An unreadable
+ * colour falls back to `color` at `share` opacity.
+ */
+export function mixIntoSurface(color: string, surface: string | undefined, share: number): string {
+  const c = parseRgb(color)
+  const s = surface ? parseRgb(surface) : null
+  if (!c || !s) return withAlpha(color, share)
+  const [c1, c2] = [toOklab(c), toOklab(s)]
+  return fromOklab([0, 1, 2].map((i) => c2[i]! + (c1[i]! - c2[i]!) * share) as [number, number, number])
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!)
+}
+
+/** Rough width (px) of 12px text: full-width characters 12, the rest 7 (as `chart-options` estimates it; kept local, like `escapeHtml`, so this part inlines on its own). */
+function estimateTextWidth(text: string): number {
+  let w = 0
+  for (const ch of text) w += /[\u3000-\u9fff\uff00-\uffef]/.test(ch) ? 12 : 7
+  return w
+}
+
+/** The grid's left and right margins (px), and the room a cell's text needs beside its edges. */
+const HEATMAP_GRID_X = 16
+const HEATMAP_CELL_PADDING = 4
+/** `plotWidth` is floored to a 40 px bucket (`useChartSurface`): the true width is half a bucket more on average. */
+const HEATMAP_BUCKET_MID = 20
+
+/**
+ * The font size (px) of the numbers inside the cells at a plot width: 12 when the widest text fits a cell,
+ * 10 when only the smaller size does, `null` (no numbers: the shade and the tooltip carry them) when neither.
+ * Cells are the plot — its width less the margins and the row-name column — shared by the columns.
+ */
+export function heatmapCellFontSize(
+  plotWidth: number,
+  columns: number,
+  rowNames: readonly string[],
+  texts: readonly string[],
+): 12 | 10 | null {
+  const widest = (items: readonly string[]) => items.reduce((m, t) => Math.max(m, estimateTextWidth(t)), 0)
+  const cell = (plotWidth + HEATMAP_BUCKET_MID - HEATMAP_GRID_X - (widest(rowNames) + 8)) / Math.max(1, columns)
+  const text = widest(texts)
+  if (text + HEATMAP_CELL_PADDING <= cell) return 12
+  return (text * 10) / 12 + HEATMAP_CELL_PADDING <= cell ? 10 : null
+}
+
+const TEXT = {
+  ja: {
+    join: "・",
+    flagged: "要注意",
+    item: "項目",
+    top: (y: string, x: string, value: string) => `最大は ${y} ${x} の ${value}`,
+    chart: (y: string, x: string) => `${y}×${x}のヒートマップ`,
+  },
+  en: {
+    join: ", ",
+    flagged: "Needs attention",
+    item: "Item",
+    top: (y: string, x: string, value: string) => `Highest: ${y} ${x} (${value})`,
+    chart: (y: string, x: string) => `Heatmap of ${y} × ${x}`,
+  },
+}
+
+const textOf = (locale?: string) => TEXT[uiLanguage(resolveLocale(locale))]
+
+export interface HeatmapOptionConfig {
+  model: HeatmapModel
+  x: string
+  y: string
+  value: string
+  /** Resolved (canvas-safe) tone colour; `""` leaves it to the theme palette. */
+  color: string
+  /** Resolved colour of the flag outline. */
+  flagColor: string
+  /** Resolved muted colour, for the missing-value cells and the axis. */
+  mutedColor: string
+  /** The colour the chart sits on (a card): the ramp's lowest end mixes the tone into it. */
+  surfaceColor?: string
+  /** Text on a dark cell / on a light cell. */
+  darkCellText: string
+  lightCellText: string
+  labels?: Record<string, string>
+  valueFormatter: ValueFormatter
+  details?: readonly string[]
+  showValues: boolean
+  showTooltip: boolean
+  /** The plot's width (px), when known: the numbers shrink (or go) when the cells are too narrow for them. */
+  plotWidth?: number | null
+  chartOptions?: EChartsOption
+  /** Language of the tooltip. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+/**
+ * The ECharts option: a shaded series (visual map, hidden), a grey series for gaps, category axes.
+ * ECharts requires every heatmap series to be bound to a visual map (it throws「Heatmap must use with
+ * visualMap」otherwise) and skips cells whose value is not a number, so the gap series gets its own
+ * hidden visual map with a single grey and carries a placeholder `0` as its value (the label and the
+ * tooltip read「—」from the cell, never the placeholder).
+ */
+export function buildHeatmapOption(config: HeatmapOptionConfig): EChartsOption {
+  const { model, labels, valueFormatter } = config
+  const t = textOf(config.locale)
+  const label = (key: string) => labels?.[key] ?? key
+  const present = model.cells.filter((c) => c.value !== null)
+  const missing = model.cells.filter((c) => c.value === null)
+  const base = config.color || "#6366f1"
+  const range = [mixIntoSurface(base, config.surfaceColor, HEATMAP_FLOOR_SHARE), base]
+  const gapColor = "rgba(0, 0, 0, 0)"
+  const flagged = (cell: HeatmapCell) =>
+    cell.flagged ? { borderColor: config.flagColor, borderWidth: 3, borderType: "solid" as const } : { borderColor: "transparent", borderWidth: 1 }
+
+  const tooltip = (cell: HeatmapCell): string => {
+    const head = `${escapeHtml(label(model.ys[cell.yi]!))} ${escapeHtml(label(model.xs[cell.xi]!))}`
+    const main = cell.value === null ? EMPTY_VALUE : escapeHtml(valueFormatter(cell.value))
+    const extras = (config.details ?? [])
+      .map((key) => {
+        const n = cell.row ? toChartNumber(cell.row[key]) : null
+        return `${escapeHtml(label(key))} ${n === null ? EMPTY_VALUE : escapeHtml(valueFormatter(n))}`
+      })
+      .join(t.join)
+    const flag = cell.flagged ? `${t.join}${t.flagged}` : ""
+    return `${head} ${main}${extras ? `${t.join}${extras}` : ""}${flag}`
+  }
+
+  const cellFont = config.plotWidth
+    ? heatmapCellFontSize(
+        config.plotWidth,
+        model.xs.length,
+        model.ys.map(label),
+        model.cells.flatMap((cell) => (cell.value === null ? [] : [valueFormatter(cell.value)])),
+      )
+    : 12
+  const point = (cell: HeatmapCell) => ({ value: [cell.xi, cell.yi, cell.value], cell })
+  const option: EChartsOption = {
+    animation: false,
+    tooltip: config.showTooltip
+      ? { trigger: "item", formatter: (p: unknown) => tooltip((p as { data: { cell: HeatmapCell } }).data.cell) }
+      : { show: false },
+    grid: { left: 8, right: 8, top: 8, bottom: 8, containLabel: true },
+    xAxis: {
+      type: "category",
+      data: model.xs,
+      splitArea: { show: false },
+      axisTick: { show: false },
+      axisLine: { show: false },
+      axisLabel: { formatter: (v: string) => label(v), hideOverlap: true },
+    },
+    yAxis: {
+      type: "category",
+      data: model.ys,
+      inverse: true,
+      splitArea: { show: false },
+      axisTick: { show: false },
+      axisLine: { show: false },
+      axisLabel: { formatter: (v: string) => label(v) },
+    },
+    visualMap: [
+      {
+        type: "continuous",
+        show: false,
+        min: model.min,
+        max: model.max,
+        dimension: 2,
+        seriesIndex: 0,
+        inRange: { color: range },
+        outOfRange: { color: range },
+      },
+      {
+        type: "continuous",
+        show: false,
+        min: 0,
+        max: 1,
+        dimension: 2,
+        seriesIndex: 1,
+        inRange: { color: [gapColor, gapColor] },
+        outOfRange: { color: [gapColor, gapColor] },
+      },
+    ],
+    series: [
+      {
+        id: "values",
+        type: "heatmap",
+        data: present.map((cell) => ({
+          ...point(cell),
+          itemStyle: flagged(cell),
+          label: {
+            color:
+              heatmapRatio(cell.value as number, model.min, model.max) >= HEATMAP_LIGHT_TEXT_FROM
+                ? config.darkCellText
+                : config.lightCellText,
+          },
+        })),
+        label: {
+          show: config.showValues && cellFont !== null,
+          fontSize: cellFont ?? 12,
+          formatter: (p: unknown) => valueFormatter((p as { value: [number, number, number] }).value[2]),
+        },
+        itemStyle: { borderColor: "transparent", borderWidth: 1, borderRadius: 2 },
+        emphasis: { itemStyle: { borderColor: config.lightCellText, borderWidth: 2 } },
+        z: 2,
+      },
+      {
+        id: "gaps",
+        type: "heatmap",
+        data: missing.map((cell) => ({ value: [cell.xi, cell.yi, 0], cell, itemStyle: flagged(cell) })),
+        label: { show: false },
+        itemStyle: {
+          color: gapColor,
+          borderColor: "transparent",
+          borderWidth: 1,
+          borderRadius: 2,
+        },
+        emphasis: { disabled: true },
+        z: 1,
+      },
+    ],
+  }
+  return config.chartOptions ? mergeDeep(option as Record<string, unknown>, config.chartOptions as Record<string, unknown>) as EChartsOption : option
+}
+
+function mergeDeep(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a }
+  for (const [k, v] of Object.entries(b)) {
+    const cur = out[k]
+    out[k] =
+      v && cur && typeof v === "object" && typeof cur === "object" && !Array.isArray(v) && !Array.isArray(cur)
+        ? mergeDeep(cur as Record<string, unknown>, v as Record<string, unknown>)
+        : v
+  }
+  return out
+}
+
+/** The screen-reader table: one row per y, one column per x; gaps read「—」. */
+export function heatmapDataTable(
+  model: HeatmapModel,
+  names: { x: string; y: string },
+  formatter: ValueFormatter,
+  labels?: Record<string, string>,
+  locale?: string,
+): ChartDataTable {
+  const label = (key: string) => labels?.[key] ?? key
+  const rows = model.ys.map((yk, yi) => [
+    label(yk),
+    ...model.xs.map((_, xi) => {
+      const v = model.cells[yi * model.xs.length + xi]?.value
+      return v === null || v === undefined ? EMPTY_VALUE : formatter(v)
+    }),
+  ])
+  return { caption: `${label(names.y)}×${label(names.x)}`, columns: [labels?.[names.y] ?? textOf(locale).item, ...model.xs.map(label)], rows }
+}
+
+/**
+ * `summary="auto"`: the strongest cell, e.g. 「最大は 月曜 9時台 の 12件」 / "Highest: Mon 9am (12)". `undefined` with no usable cell.
+ * `locale` picks the language; default the page's (`<html lang>`).
+ */
+export function buildHeatmapSummary(
+  model: HeatmapModel,
+  formatter: ValueFormatter,
+  title?: string,
+  labels?: Record<string, string>,
+  locale?: string,
+): string | undefined {
+  let best: HeatmapCell | undefined
+  for (const cell of model.cells) if (cell.value !== null && (!best || cell.value > (best.value as number))) best = cell
+  if (!best) return undefined
+  const label = (key: string) => labels?.[key] ?? key
+  const head = title ? `${title}: ` : ""
+  return `${head}${textOf(locale).top(label(model.ys[best.yi]!), label(model.xs[best.xi]!), formatter(best.value as number))}`
+}
+
+/* -------------------------------------------------------------- component */
+
+function colorsFor(tokens: ChartTokens | null, tone: string) {
+  const [color = "", flag = "", muted = ""] = resolveChartColors([tone, "negative", "var(--muted-foreground)"], tokens)
+  return { color, flag, muted }
+}
+
+/** Rows not given yet (a draft fills props in steps): draw the empty state, keep the same array between renders. */
+const NO_ROWS: never[] = []
+
+function HeatmapImpl<T extends Record<string, unknown>>(
+  {
+    data = NO_ROWS,
+    x,
+    y,
+    value,
+    xLabels,
+    yLabels,
+    labels,
+    format,
+    valueFormatter,
+    tone = "chart-1",
+    scale,
+    minValue,
+    maxValue,
+    showValues = false,
+    showLegend = true,
+    showTooltip = true,
+    details,
+    flag,
+    title,
+    summary,
+    isLoading,
+    emptyState,
+    height,
+    chartOptions,
+    actions,
+    fileName,
+    className,
+    ariaLabel,
+    ...rest
+  }: HeatmapProps<T>,
+  ref: ForwardedRef<HTMLDivElement>,
+) {
+  const { ref: frameRef, surface, width: plotWidth, tokens } = useChartSurface(ref)
+  const locale = useLocale()
+  const formatter = useMemo(() => resolveValueFormatter(valueFormatter, format ?? "number", locale), [valueFormatter, format, locale])
+  const model = useMemo(
+    () => buildHeatmapModel({ data, x, y, value, xLabels, yLabels, flag, scale, minValue, maxValue }),
+    [data, x, y, value, xLabels, yLabels, flag, scale?.min, scale?.max, minValue, maxValue],
+  )
+  const colors = useMemo(() => colorsFor(tokens, tone), [tokens, tone])
+  const option = useMemo(
+    () =>
+      buildHeatmapOption({
+        model,
+        x,
+        y,
+        value,
+        color: colors.color,
+        flagColor: colors.flag,
+        mutedColor: colors.muted,
+        surfaceColor: surface ?? undefined,
+        darkCellText: surface ?? "#ffffff",
+        lightCellText: tokens?.foreground ?? "",
+        labels,
+        valueFormatter: formatter,
+        details: details as string[] | undefined,
+        showValues,
+        showTooltip,
+        plotWidth,
+        chartOptions,
+        locale,
+      }),
+    [model, x, y, value, colors, surface, tokens, labels, formatter, details, showValues, showTooltip, plotWidth, chartOptions, locale],
+  )
+  const dataTable = useMemo(() => heatmapDataTable(model, { x, y }, formatter, labels, locale), [model, x, y, formatter, labels, locale])
+  const resolvedSummary = useMemo(
+    () => (summary === "auto" ? buildHeatmapSummary(model, formatter, title, labels, locale) : summary),
+    [summary, model, formatter, title, labels, locale],
+  )
+  const label = ariaLabel ?? textOf(locale).chart(labels?.[y] ?? y, labels?.[x] ?? x)
+  const legend = showLegend ? (
+    <HeatmapLegend model={model} formatter={formatter} tone={tone} />
+  ) : null
+  return (
+    <ChartFrame
+      {...chartRootProps(rest)}
+      ref={frameRef}
+      title={title}
+      summary={resolvedSummary}
+      isLoading={isLoading ?? false}
+      isEmpty={data.length === 0}
+      emptyState={emptyState}
+      height={height}
+      variant="bar"
+      ariaLabel={label}
+      className={className}
+      dataTable={dataTable}
+    >
+      <div className="flex h-full w-full flex-col gap-2">
+        <div className="min-h-0 flex-1">
+          <EChart option={option} height="100%" ariaLabel={label} actions={actions} fileName={fileName} exportHeader={{ title, summary: resolvedSummary }} />
+        </div>
+        {legend}
+      </div>
+    </ChartFrame>
+  )
+}
+
+function HeatmapLegend({
+  model,
+  formatter,
+  tone,
+}: {
+  model: HeatmapModel
+  formatter: ValueFormatter
+  tone: string
+}) {
+  const ramp = `linear-gradient(to right, color-mix(in oklch, var(--${tone}) ${HEATMAP_FLOOR_SHARE * 100}%, var(--card)), var(--${tone}))`
+  return (
+    <div data-slot="heatmap-legend" className="flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-muted-foreground tabular-nums">
+      <span className="flex items-center gap-2">
+        <span>{formatter(model.min)}</span>
+        <span aria-hidden className="h-2 w-24 rounded-sm" style={{ backgroundImage: ramp }} />
+        <span>{formatter(model.max)}</span>
+      </span>
+    </div>
+  )
+}
+
+/** Generic over the row type, so `x` / `y` / `value` keys are checked against `data`. */
+export const Heatmap = forwardRef(HeatmapImpl as (props: HeatmapProps, ref: ForwardedRef<HTMLDivElement>) => ReactElement) as (<
+  T extends Record<string, unknown>,
+>(
+  props: HeatmapProps<T> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement) & { displayName?: string }
+Heatmap.displayName = "Heatmap"