@squadbase/vantage 0.7.0 → 0.7.1-dev1.215984c

package/registry/ui/treemap.tsx

@@ -0,0 +1,1917 @@
+// Copied by `vantage add ui treemap`. This file is yours to edit.
+// Generated from @squadbase/squadkit registry/charts/treemap.tsx by `pnpm run registry` (in Vantage, edit packages/squadkit, not registry/).
+"use client"
+
+/**
+ * Treemap — parts of a whole as nested rectangles whose areas are the values.
+ * Pass rows, the leaf column (`index`),
+ * optionally a parent column (`group`, for two levels) and the number (`value`) instead of an ECharts option.
+ *
+ * Colour is categorical by `group` (or by `index` without one): `--chart-1..5` for the largest five, the rest the
+ * 「その他」grey. A numeric `color` column shades each tile on a single-hue ramp of `tone` instead (like Heatmap).
+ * Each tile carries its name and value when it fits. Values that are zero, negative or missing take no area; they
+ * stay in the screen-reader table. Clicking a tile calls `onSelect` with its row.
+ */
+import { forwardRef, useMemo, type ForwardedRef, type ReactElement, type Ref } from "react"
+import { use } from "echarts/core"
+import { TreemapChart } from "echarts/charts"
+import type { EChartsOption } from "echarts"
+
+import { ChartFrame } from "@squadbase/vantage/components"
+import { EChart } from "@squadbase/vantage/components"
+import { Legend } from "@squadbase/vantage/components"
+import { EMPTY_VALUE, formatValue, 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 { 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)}`
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/lib/color-ramp.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The single-hue ramp the canvas charts shade by (FilledMap, SymbolMap, Treemap): the tone mixed into the surface
+ * it sits on, from 20% (the lowest value) to 100% (the highest). The same ramp as Heatmap's, computed per value so
+ * no visual map is needed. Pure and DOM-free; canvas-safe colours in, `rgb()` out (internal chart helper).
+ */
+
+/** The lightest end of the ramp is this share of the tone mixed into the surface; the darkest end is the tone itself. */
+const RAMP_FLOOR_SHARE = 0.2
+/** At or above this share of the ramp a mark is dark: text on it takes the surface colour, below it the foreground. */
+const RAMP_LIGHT_TEXT_FROM = 0.55
+
+/** `#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(", ")})`
+}
+
+/** A canvas-safe colour at `alpha`; anything unreadable comes back unchanged. */
+function withAlpha(color: string, alpha: number): string {
+  const c = parseRgb(color)
+  return c ? `rgba(${c[0]}, ${c[1]}, ${c[2]}, ${alpha})` : color
+}
+
+/**
+ * `share` (0–1) of `color` mixed into `surface` — the canvas form of `color-mix(in oklch, <color> N%, <surface>)`.
+ * An unreadable colour falls back to `color` at `share` opacity.
+ */
+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])
+}
+
+/** Where a value sits on a `[min, max]` ramp (0–1, clamped). A flat range reads as the top. */
+function rampRatio(value: number, min: number, max: number): number {
+  return max > min ? Math.min(1, Math.max(0, (value - min) / (max - min))) : 1
+}
+
+/** The ramp colour at `ratio` (0 = the floor, 20% of the tone; 1 = the tone itself). */
+function rampColor(color: string, surface: string | undefined, ratio: number): string {
+  return mixIntoSurface(color, surface, RAMP_FLOOR_SHARE + (1 - RAMP_FLOOR_SHARE) * Math.min(1, Math.max(0, ratio)))
+}
+
+/** The CSS gradient of the ramp for an HTML legend (`tone` is a token name such as `"chart-1"`). */
+function rampGradientCss(tone: string): string {
+  return `linear-gradient(to right, color-mix(in oklch, var(--${tone}) ${RAMP_FLOOR_SHARE * 100}%, var(--card)), var(--${tone}))`
+}
+
+/* ---------- end of inlined code ---------- */
+
+// The treemap series is this part's own.
+use([TreemapChart])
+
+/** Categories coloured `--chart-1..5` (largest first); the rest share the「その他」grey. */
+const MAX_CATEGORIES = 5
+
+/** 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 TreemapProps<T extends Record<string, unknown> = Record<string, unknown>> extends ChartRootAttributes {
+  /** 行の配列。1 行 = 1 タイル(集計済みの値)。 */
+  data: T[]
+  /** タイル(葉)の名前の列名。例 `"product"`。 */
+  index: keyof T & string
+  /** 親の列名(2 階層にする)。例 `"category"`。省略時は 1 階層。 */
+  group?: keyof T & string
+  /** タイルの面積を決める数値の列名。0 以下・欠損の行は面積を持たない(データ表には残る)。 */
+  value: NumericColumn<T>
+  /** タイルの色を決める数値の列名(`tone` の単色の濃淡)。省略時は `group`(無ければ `index`)ごとのカテゴリ色。 */
+  color?: NumericColumn<T>
+  /** 列名・値 → 表示名(タイル・ツールチップ・凡例・データ表)。 */
+  labels?: Record<string, string>
+  /** `value` の書式。既定 `"number"`。 */
+  format?: ValueFormat
+  /** `color` の値の書式。省略時は `format`。 */
+  colorFormat?: ValueFormat
+  /** 書式を関数で直接渡す逃げ道(`value`)。`format` より優先する。 */
+  valueFormatter?: ValueFormatter
+  /** 数値の `color` の濃淡の色。既定 `"chart-1"`。 */
+  tone?: ChartSeriesColor
+  /** 凡例(カテゴリ色なら色の一覧、数値の色なら濃淡の帯)を出す。既定 `true`(カテゴリ色は `group` があるときだけ)。 */
+  showLegend?: boolean
+  /** ホバーでツールチップを出す。既定 `true`。 */
+  showTooltip?: boolean
+  /** タイルのクリック。その行を受け取る(フィルターの操作に使う)。 */
+  onSelect?: (row: T) => void
+  /** グラフの見出し。 */
+  title?: string
+  /** グラフが言っていることの 1 文要約。`"auto"` で最大のタイルとその構成比。 */
+  summary?: string | "auto"
+  /** 読み込み中。最終形と同じ高さのスケルトンを出す。 */
+  isLoading?: boolean
+  /** `data` が空のときの表示。 */
+  emptyState?: ChartEmptyState
+  /** プロット領域の高さ(px)。既定 288。 */
+  height?: number
+  /** 生成した EChartsOption に最後に深くマージする逃げ道。 */
+  chartOptions?: EChartsOption
+  /** グラフ右上に PNG 保存/コピーのボタンを出す。 */
+  actions?: boolean | ChartActionsOptions
+  /** PNG 保存時のファイル名(拡張子つき)。 */
+  fileName?: string
+  className?: string
+  /** スクリーンリーダー向けのラベル。 */
+  ariaLabel?: string
+}
+
+/* ------------------------------------------------------------------ model */
+
+export interface TreemapLeaf {
+  name: string
+  group: string | null
+  value: number | null
+  shade: number | null
+  row: Record<string, unknown>
+}
+
+export interface TreemapModel {
+  /** Every row, in data order. */
+  leaves: TreemapLeaf[]
+  /** Leaves that take area (value > 0), grouped; groups and leaves largest first. */
+  groups: { name: string | null; total: number; leaves: TreemapLeaf[] }[]
+  /** The colour categories (groups, or leaves without a group), largest first. */
+  categories: string[]
+  total: number
+  shadeMin: number
+  shadeMax: number
+}
+
+export function buildTreemapModel(config: {
+  data: readonly Record<string, unknown>[]
+  index: string
+  group?: string
+  value: string
+  color?: string
+}): TreemapModel {
+  const { data, index, group, value, color } = config
+  const leaves: TreemapLeaf[] = []
+  let [lo, hi] = [Infinity, -Infinity]
+  for (const row of data) {
+    if (!row || typeof row !== "object") continue
+    const shade = color ? toChartNumber(row[color]) : null
+    if (shade !== null) [lo, hi] = [Math.min(lo, shade), Math.max(hi, shade)]
+    leaves.push({
+      name: String(row[index] ?? EMPTY_VALUE),
+      group: group ? String(row[group] ?? EMPTY_VALUE) : null,
+      value: toChartNumber(row[value]),
+      shade,
+      row,
+    })
+  }
+  const byGroup = new Map<string | null, TreemapLeaf[]>()
+  for (const leaf of leaves) {
+    if (leaf.value === null || leaf.value <= 0) continue
+    const list = byGroup.get(leaf.group) ?? []
+    list.push(leaf)
+    byGroup.set(leaf.group, list)
+  }
+  const groups = [...byGroup.entries()]
+    .map(([name, list]) => ({ name, total: list.reduce((s, l) => s + (l.value as number), 0), leaves: [...list].sort((a, b) => (b.value as number) - (a.value as number)) }))
+    .sort((a, b) => b.total - a.total)
+  const total = groups.reduce((s, g) => s + g.total, 0)
+  const categories = group
+    ? groups.map((g) => g.name as string)
+    : [...new Set(groups.flatMap((g) => g.leaves.map((l) => l.name)))]
+  const shadeMin = Number.isFinite(lo) ? lo : 0
+  let shadeMax = Number.isFinite(hi) ? hi : 1
+  if (shadeMax <= shadeMin) shadeMax = shadeMin + 1
+  return { leaves, groups, categories, total, shadeMin, shadeMax }
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!)
+}
+
+const TEXT = {
+  ja: {
+    join: "・",
+    item: "項目",
+    group: "グループ",
+    share: "構成比",
+    top: (name: string, share: string) => `最大は ${name}(全体の ${share})`,
+    chart: (value: string) => `${value}のツリーマップ`,
+  },
+  en: {
+    join: ", ",
+    item: "Item",
+    group: "Group",
+    share: "Share",
+    top: (name: string, share: string) => `Largest: ${name} (${share} of the total)`,
+    chart: (value: string) => `Treemap of ${value}`,
+  },
+}
+
+const textOf = (locale?: string) => TEXT[uiLanguage(resolveLocale(locale))]
+
+export interface TreemapOptionConfig {
+  model: TreemapModel
+  hasGroup: boolean
+  colorMode: "category" | "numeric"
+  /** Resolved ramp colour (numeric). */
+  toneColor: string
+  /** Resolved category colours in order; the entry after the fifth is the「その他」grey. */
+  categoryColors: readonly string[]
+  surfaceColor?: string
+  /** Text on a light tile. */
+  foregroundColor: string
+  labels?: Record<string, string>
+  valueFormatter: ValueFormatter
+  colorFormatter: ValueFormatter
+  colorKey?: string
+  showTooltip: boolean
+  chartOptions?: EChartsOption
+  locale?: string
+}
+
+export function buildTreemapOption(config: TreemapOptionConfig): EChartsOption {
+  const { model, labels, valueFormatter } = config
+  const t = textOf(config.locale)
+  const label = (key: string) => labels?.[key] ?? key
+  const surface = config.surfaceColor ?? "#ffffff"
+  const base = config.toneColor || "#6366f1"
+  const categoryColor = (name: string) => {
+    const at = model.categories.indexOf(name)
+    return config.categoryColors[at === -1 ? MAX_CATEGORIES : Math.min(at, MAX_CATEGORIES)] ?? base
+  }
+  const share = (v: number) => formatValue(model.total > 0 ? v / model.total : 0, "percent", config.locale)
+  const leafNode = (leaf: TreemapLeaf) => {
+    let fill: string
+    let dark = true
+    if (config.colorMode === "numeric") {
+      const ratio = leaf.shade === null ? 0 : rampRatio(leaf.shade, model.shadeMin, model.shadeMax)
+      fill = rampColor(base, config.surfaceColor, ratio)
+      dark = ratio >= RAMP_LIGHT_TEXT_FROM
+    } else fill = categoryColor(config.hasGroup ? (leaf.group as string) : leaf.name)
+    return {
+      name: label(leaf.name),
+      value: leaf.value as number,
+      leaf,
+      itemStyle: { color: fill },
+      label: { color: dark ? surface : config.foregroundColor },
+    }
+  }
+  const tooltip = (leaf: TreemapLeaf | undefined, name: string, value: number): string => {
+    const head = leaf?.group != null ? `${escapeHtml(label(leaf.group))} / ${escapeHtml(name)}` : escapeHtml(name)
+    const parts = [`${head} ${escapeHtml(valueFormatter(value))}`, `${t.share} ${escapeHtml(share(value))}`]
+    if (leaf && config.colorKey && config.colorMode === "numeric")
+      parts.push(`${escapeHtml(label(config.colorKey))} ${leaf.shade === null ? EMPTY_VALUE : escapeHtml(config.colorFormatter(leaf.shade))}`)
+    return parts.join(t.join)
+  }
+  const data = config.hasGroup
+    ? model.groups.map((g) => ({
+        name: label(g.name as string),
+        value: g.total,
+        itemStyle: { color: config.colorMode === "numeric" ? config.foregroundColor : categoryColor(g.name as string) },
+        children: g.leaves.map(leafNode),
+      }))
+    : model.groups.flatMap((g) => g.leaves.map(leafNode))
+  const option: EChartsOption = {
+    animation: false,
+    tooltip: config.showTooltip
+      ? {
+          trigger: "item",
+          formatter: (p: unknown) => {
+            const d = p as { name: string; value: number; data: { leaf?: TreemapLeaf } }
+            return tooltip(d.data?.leaf, d.name, Number(d.value))
+          },
+        }
+      : { show: false },
+    series: [
+      {
+        id: "tiles",
+        type: "treemap",
+        left: 0,
+        right: 0,
+        top: 0,
+        bottom: 0,
+        roam: false,
+        nodeClick: false,
+        breadcrumb: { show: false },
+        squareRatio: 0.5 * (1 + Math.sqrt(5)),
+        label: {
+          show: true,
+          position: "insideTopLeft",
+          overflow: "truncate",
+          lineHeight: 16,
+          formatter: (p: unknown) => {
+            const d = p as { name: string; value: number }
+            return `${d.name}\n${valueFormatter(Number(d.value))}`
+          },
+        },
+        upperLabel: { show: config.hasGroup, height: 20, color: surface, fontWeight: 600 },
+        itemStyle: { borderColor: surface, borderWidth: 1, gapWidth: 1 },
+        emphasis: { disabled: true },
+        levels: config.hasGroup
+          ? [{ itemStyle: { borderColor: surface, borderWidth: 2, gapWidth: 2 } }, { itemStyle: { borderColor: surface, borderWidth: 0, gapWidth: 1 } }]
+          : [{ itemStyle: { borderColor: surface, borderWidth: 0, gapWidth: 1 } }],
+        data,
+      } as never,
+    ],
+  }
+  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: every row (in data order), with its share of the total. */
+export function treemapDataTable(
+  model: TreemapModel,
+  names: { index: string; group?: string; value: string; color?: string },
+  formatters: { value: ValueFormatter; color: ValueFormatter },
+  labels?: Record<string, string>,
+  locale?: string,
+): ChartDataTable {
+  const t = textOf(locale)
+  const label = (key: string) => labels?.[key] ?? key
+  const share = (v: number | null) => (v === null || v <= 0 || model.total <= 0 ? EMPTY_VALUE : formatValue(v / model.total, "percent", locale))
+  return {
+    columns: [
+      ...(names.group ? [labels?.[names.group] ?? t.group] : []),
+      labels?.[names.index] ?? t.item,
+      label(names.value),
+      t.share,
+      ...(names.color && names.color !== names.value ? [label(names.color)] : []),
+    ],
+    rows: model.leaves.map((leaf) => [
+      ...(names.group ? [label(leaf.group ?? EMPTY_VALUE)] : []),
+      label(leaf.name),
+      leaf.value === null ? EMPTY_VALUE : formatters.value(leaf.value),
+      share(leaf.value),
+      ...(names.color && names.color !== names.value ? [leaf.shade === null ? EMPTY_VALUE : formatters.color(leaf.shade)] : []),
+    ]),
+  }
+}
+
+/** `summary="auto"`: the largest tile and its share. */
+export function buildTreemapSummary(model: TreemapModel, title?: string, labels?: Record<string, string>, locale?: string): string | undefined {
+  let best: TreemapLeaf | undefined
+  for (const g of model.groups) for (const l of g.leaves) if (!best || (l.value as number) > (best.value as number)) best = l
+  if (!best || model.total <= 0) return undefined
+  return `${title ? `${title}: ` : ""}${textOf(locale).top(labels?.[best.name] ?? best.name, formatValue((best.value as number) / model.total, "percent", locale))}`
+}
+
+/* -------------------------------------------------------------- component */
+
+function colorsFor(tokens: ChartTokens | null, tone: string) {
+  const resolved = resolveChartColors([tone, "var(--foreground)", ...DEFAULT_CHART_COLORS, CHART_OTHER_COLOR], tokens)
+  const [toneColor = "", foreground = ""] = resolved
+  return { toneColor, foreground, categories: resolved.slice(2) }
+}
+
+/** 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 TreemapImpl<T extends Record<string, unknown>>(
+  {
+    data = NO_ROWS,
+    index,
+    group,
+    value,
+    color,
+    labels,
+    format,
+    colorFormat,
+    valueFormatter,
+    tone = "chart-1",
+    showLegend = true,
+    showTooltip = true,
+    onSelect,
+    title,
+    summary,
+    isLoading,
+    emptyState,
+    height,
+    chartOptions,
+    actions,
+    fileName,
+    className,
+    ariaLabel,
+    ...rest
+  }: TreemapProps<T>,
+  ref: ForwardedRef<HTMLDivElement>,
+) {
+  const rows = Array.isArray(data) ? data : NO_ROWS
+  const { ref: frameRef, surface, tokens } = useChartSurface(ref)
+  const locale = useLocale()
+  const formatter = useMemo(() => resolveValueFormatter(valueFormatter, format ?? "number", locale), [valueFormatter, format, locale])
+  const colorFormatter = useMemo(() => resolveValueFormatter(undefined, colorFormat ?? format ?? "number", locale), [colorFormat, format, locale])
+  const model = useMemo(() => buildTreemapModel({ data: rows, index, group, value, color }), [rows, index, group, value, color])
+  const colorMode = color ? "numeric" : "category"
+  const colors = useMemo(() => colorsFor(tokens, tone), [tokens, tone])
+  const option = useMemo(
+    () =>
+      buildTreemapOption({
+        model,
+        hasGroup: !!group,
+        colorMode,
+        toneColor: colors.toneColor,
+        categoryColors: colors.categories,
+        surfaceColor: surface ?? undefined,
+        foregroundColor: colors.foreground || tokens?.foreground || "#111111",
+        labels,
+        valueFormatter: formatter,
+        colorFormatter,
+        colorKey: color,
+        showTooltip,
+        chartOptions,
+        locale,
+      }),
+    [model, group, colorMode, colors, surface, tokens, labels, formatter, colorFormatter, color, showTooltip, chartOptions, locale],
+  )
+  const onEvents = useMemo(
+    () =>
+      onSelect
+        ? {
+            click: (params: unknown) => {
+              const leaf = (params as { data?: { leaf?: TreemapLeaf } }).data?.leaf
+              if (leaf) onSelect(leaf.row as T)
+            },
+          }
+        : undefined,
+    [onSelect],
+  )
+  const dataTable = useMemo(
+    () => treemapDataTable(model, { index, group, value, color }, { value: formatter, color: colorFormatter }, labels, locale),
+    [model, index, group, value, color, formatter, colorFormatter, labels, locale],
+  )
+  const resolvedSummary = useMemo(
+    () => (summary === "auto" ? buildTreemapSummary(model, title, labels, locale) : summary),
+    [summary, model, title, labels, locale],
+  )
+  const label = ariaLabel ?? textOf(locale).chart(labels?.[value] ?? value ?? "")
+  const legendCategories =
+    model.categories.length > MAX_CATEGORIES ? [...model.categories.slice(0, MAX_CATEGORIES), otherSeriesLabel(locale)] : model.categories
+  const legend = !showLegend ? null : colorMode === "numeric" ? (
+    <div data-slot="treemap-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">
+        {color && <span>{labels?.[color] ?? color}</span>}
+        <span>{colorFormatter(model.shadeMin)}</span>
+        <span aria-hidden className="h-2 w-24 rounded-sm" style={{ backgroundImage: rampGradientCss(tone) }} />
+        <span>{colorFormatter(model.shadeMax)}</span>
+      </span>
+    </div>
+  ) : group ? (
+    <Legend categories={legendCategories} labels={labels} />
+  ) : null
+  return (
+    <ChartFrame
+      {...chartRootProps(rest)}
+      ref={frameRef}
+      title={title}
+      summary={resolvedSummary}
+      isLoading={isLoading ?? false}
+      isEmpty={rows.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} onEvents={onEvents} height="100%" ariaLabel={label} actions={actions} fileName={fileName} exportHeader={{ title, summary: resolvedSummary }} />
+        </div>
+        {legend}
+      </div>
+    </ChartFrame>
+  )
+}
+
+/** Generic over the row type, so the column keys are checked against `data`. */
+export const Treemap = forwardRef(TreemapImpl as (props: TreemapProps, ref: ForwardedRef<HTMLDivElement>) => ReactElement) as (<
+  T extends Record<string, unknown>,
+>(
+  props: TreemapProps<T> & { ref?: Ref<HTMLDivElement> },
+) => ReactElement) & { displayName?: string }
+Treemap.displayName = "Treemap"