@adia-ai/web-components 0.0.12 → 0.0.14

package/components/chart/chart.js

@@ -196,8 +196,9 @@ class AdiaChart extends AdiaElement {
     hideValues:  { type: Boolean, default: false,    reflect: true, attribute: 'hide-values' },
     radius:      { type: Number,  default: null,     reflect: true },
     smooth:      { type: Number,  default: 0.4,      reflect: true },
-    aspect:      { type: String,  default: 'std',    reflect: true },  // std | wide | square | tall
+    aspect:      { type: String,  default: 'std',    reflect: true },  // std | wide | square | tall (deprecated — OD-CHART-02)
     size:        { type: String,  default: '',       reflect: true },  // sm | md | lg
+    format:      { type: String,  default: 'abbr',   reflect: true },  // abbr | decimal | currency | percent (OD-CHART-03)
   };
 
   static template = () => null;
@@ -207,6 +208,9 @@ class AdiaChart extends AdiaElement {
   #resizeRaf = null;
   #lastW = 0;
   #lastH = 0;
+  /* Set of series keys hidden by external chart-legend-ui[for=self] toggles.
+     Kept at render time; repopulated lookups rebuild with the new set. */
+  #hiddenSeriesKeys = new Set();
 
   /** Resolves the corner radius: the `radius` prop if explicitly set,
    *  otherwise `--a-radius` from the host's computed style. Falls back
@@ -220,6 +224,7 @@ class AdiaChart extends AdiaElement {
 
   set data(arr) {
     this.#data = Array.isArray(arr) ? arr : [];
+    this.#warnIfOverBudget();
     this.#renderChart();
   }
 
@@ -227,7 +232,55 @@ class AdiaChart extends AdiaElement {
     return this.#data;
   }
 
+  /* OD-CHART-11 — one-shot perf-budget warning. Chart-ui re-renders the
+     full SVG string on every data change; perf drops noticeably past
+     ~5,000 datums (the tipping point varies by type — scatter and
+     multi-line are the worst offenders). Authors over the budget should
+     downsample at the data layer (LTTB, uniform sampling, aggregation
+     by bucket) before setting .data. Override the threshold via the
+     `--chart-perf-budget` CSS token for ad-hoc testing. */
+  #perfBudgetWarned = false;
+  #warnIfOverBudget() {
+    if (this.#perfBudgetWarned) return;
+    const budget = this.#readPerfBudget();
+    if (this.#data.length > budget) {
+      console.warn(
+        `[chart-ui] .data has ${this.#data.length} rows which exceeds the ` +
+        `recommended perf budget of ${budget}. Consider downsampling at the ` +
+        `data layer (e.g., LTTB, bucket aggregation). Override the budget ` +
+        `via CSS: chart-ui { --chart-perf-budget: 10000 }.`
+      );
+      this.#perfBudgetWarned = true;
+    }
+  }
+  #readPerfBudget() {
+    const raw = getComputedStyle(this).getPropertyValue('--chart-perf-budget').trim();
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 5000;
+  }
+
   connected() {
+    if (!this.hasAttribute('role'))       this.setAttribute('role', 'img');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', this.heading || `${this.type} chart`);
+
+    /* Phase 1b — listen for legend-toggle events from external
+       chart-legend-ui[for=self] and hide the matching series. Events
+       bubble so document-level listening catches descendant legends. */
+    document.addEventListener('legend-toggle', this.#onLegendToggle);
+
+    /* OD-CHART-06 — keyboard a11y. Chart becomes focusable; arrow keys
+       move a virtual focus across datums in DOM order, Enter/Space fires
+       chart-select, Escape clears focus. Per-datum focus dispatches the
+       same chart-hover event the pointer path uses, so tooltip-ui[for]
+       tracks keyboard focus transparently.
+       Deprecation warnings for `aspect=` and `heading=` also fire here
+       per OD-CHART-02 — one-shot per instance to keep the console clean. */
+    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '0');
+    this.addEventListener('keydown', this.#onKeydown);
+    this.addEventListener('focus',   this.#onFocus);
+    this.addEventListener('blur',    this.#onBlur);
+    this.#warnDeprecatedAttrs();
+
     this.#resizeObs = new ResizeObserver((entries) => {
       const { inlineSize: w, blockSize: h } = entries[0].contentBoxSize[0];
       if (!this.#data.length) return;
@@ -306,11 +359,31 @@ class AdiaChart extends AdiaElement {
 
   /* ── Main render ──────────────────────────────────────────────── */
 
+  #emptySlotTemplate = null;
+
   #renderChart() {
     if (!this.isConnected) return;
+
+    /* Preserve the empty slot across re-renders. First render captures the
+       author-provided <* slot="empty"> into a template; subsequent renders
+       restore it so data-empty → data-present → data-empty transitions
+       don't lose the slotted empty-state-ui. Visibility is CSS-toggled via
+       [data-has-data] on the host. */
+    const existingEmpty = this.querySelector(':scope > [slot="empty"]');
+    if (existingEmpty && !this.#emptySlotTemplate) {
+      this.#emptySlotTemplate = existingEmpty.cloneNode(true);
+    }
+
     this.innerHTML = '';
+    if (this.#emptySlotTemplate) this.appendChild(this.#emptySlotTemplate.cloneNode(true));
 
-    if (!this.#data.length) return;
+    if (!this.#data.length) {
+      this.removeAttribute('data-has-data');
+      return;
+    }
+    this.setAttribute('data-has-data', '');
+
+    this.#injectSeriesColors();
 
     if (this.heading) {
       const headingEl = document.createElement('div');
@@ -337,6 +410,14 @@ class AdiaChart extends AdiaElement {
       case 'radar':       ({ svg: svgContent, viewBox: vb } = this.#renderRadar()); break;
       case 'sparkline':   ({ svg: svgContent, viewBox: vb } = this.#renderSparkline()); break;
       case 'segments':    ({ svg: svgContent, viewBox: vb } = this.#renderSegments()); break;
+      case 'area':        ({ svg: svgContent, viewBox: vb } = this.#renderArea()); break;
+      case 'scatter':     ({ svg: svgContent, viewBox: vb } = this.#renderScatter()); break;
+      case 'radial-bar':  ({ svg: svgContent, viewBox: vb } = this.#renderRadialBar()); break;
+      case 'gauge':       ({ svg: svgContent, viewBox: vb } = this.#renderGauge()); break;
+      case 'funnel':      ({ svg: svgContent, viewBox: vb } = this.#renderFunnel()); break;
+      case 'treemap':     ({ svg: svgContent, viewBox: vb } = this.#renderTreemap()); break;
+      case 'sankey':      ({ svg: svgContent, viewBox: vb } = this.#renderSankey()); break;
+      case 'composed':    ({ svg: svgContent, viewBox: vb } = this.#renderComposed()); break;
       case 'stacked-bar': ({ svg: svgContent, viewBox: vb } = this.#renderStackedBar()); break;
       case 'grouped-bar': ({ svg: svgContent, viewBox: vb } = this.#renderGroupedBar()); break;
       case 'multi-line':  ({ svg: svgContent, viewBox: vb } = this.#renderMultiLine()); break;
@@ -347,18 +428,59 @@ class AdiaChart extends AdiaElement {
     svgEl.setAttribute('preserveAspectRatio', 'xMidYMid meet');
     svgEl.innerHTML = svgContent;
 
-    /* Append legend for types that need it */
-    if (['pie', 'donut', 'stacked-bar', 'grouped-bar', 'multi-line'].includes(this.type)) {
+    /* Append legend for types that need it. Legend data is also exposed via
+       the public `legendData` getter so a sibling chart-legend-ui[for] can
+       mirror the same series. When an external legend is present (Phase 1b:
+       chart-legend-ui[for=self]), the internal one is suppressed so we
+       don't double-render — the #legendData remains populated for the
+       external to read. */
+    if (['pie', 'donut', 'stacked-bar', 'grouped-bar', 'multi-line', 'radial-bar'].includes(this.type)
+        && !this.#hasExternalLegend()) {
       const legend = this.#buildLegend();
       if (legend) this.appendChild(legend);
     }
 
-    /* Wire hover tooltip — pointer delegate on the SVG reads data-tip-*
-       attrs from the shape under the cursor and shows a single shared
-       popover. See #showTooltip / #hideTooltip below. */
+    /* Notify external legend/tooltip consumers that legendData has refreshed. */
+    this.dispatchEvent(new CustomEvent('legend-update', { bubbles: true }));
+
+    /* Wire hover tooltip + custom events. Internal tooltip (#tipEl) remains
+       for back-compat; Phase 2 retires it when tooltip-ui[follows=pointer]
+       lands. Custom events are additive — fire regardless of tooltip state.
+       OD-CHART-07: pointerdown handles touch (tap-to-pin); pointerover /
+       move still handle mouse + pen (`pointerType` gating inside each). */
     svgEl.addEventListener('pointerover',  this.#onPointerOver);
     svgEl.addEventListener('pointermove',  this.#onPointerMove);
     svgEl.addEventListener('pointerleave', this.#onPointerLeave);
+    svgEl.addEventListener('pointerdown',  this.#onPointerDown);
+    svgEl.addEventListener('click',        this.#onClick);
+  }
+
+  /* ── Per-series --color-{key} injection ──
+     For each declared series key (`y="revenue,users"`), emit an inline CSS
+     custom property on the host mapping the key to the categorical palette
+     slot it occupies. Consumers override `--color-revenue` at any ancestor
+     to recolor that series across chart + legend + (Phase 2) tooltip. */
+  #injectSeriesColors() {
+    const keys = this.#yKeys();
+    for (let i = 0; i < keys.length; i++) {
+      const slot = i % 10;
+      this.style.setProperty(`--color-${keys[i]}`, `var(--chart-${slot})`);
+    }
+  }
+
+  /* Render-time helpers — emit data-slice + series-key + inline style that
+     references `--color-{key}` with fallback to `--chart-{slot}`. Inline
+     style beats the stylesheet's data-slice rule, so consumer overrides of
+     --color-{key} at any ancestor recolor that series. Non-series-keyed
+     elements (pie/donut/segments categorical slots) keep data-slice only
+     and are coloured by the stylesheet. */
+  #seriesFill(slotIdx, seriesKey) {
+    if (!seriesKey) return ` data-slice="${slotIdx}"`;
+    return ` data-slice="${slotIdx}" data-series-key="${esc(seriesKey)}" style="fill: var(--color-${seriesKey}, var(--chart-${slotIdx}))"`;
+  }
+  #seriesStroke(slotIdx, seriesKey) {
+    if (!seriesKey) return ` data-slice="${slotIdx}"`;
+    return ` data-slice="${slotIdx}" data-series-key="${esc(seriesKey)}" style="stroke: var(--color-${seriesKey}, var(--chart-${slotIdx}))"`;
   }
 
   /* ── Tooltip ───────────────────────────────────────────────────── */
@@ -369,23 +491,378 @@ class AdiaChart extends AdiaElement {
     this.#resizeObs?.disconnect();
     this.#resizeObs = null;
     if (this.#resizeRaf) { cancelAnimationFrame(this.#resizeRaf); this.#resizeRaf = null; }
+    document.removeEventListener('legend-toggle', this.#onLegendToggle);
+    document.removeEventListener('pointerdown',   this.#pinnedTouchDismiss);
+    this.removeEventListener('keydown', this.#onKeydown);
+    this.removeEventListener('focus',   this.#onFocus);
+    this.removeEventListener('blur',    this.#onBlur);
     this.#hideTooltip();
   }
 
+  /* Detect whether an external chart-legend-ui or tooltip-ui is acting as
+     this chart's legend / tooltip via [for=self.id]. When present, the
+     internal counterpart is suppressed so we don't double-render. */
+  #hasExternalLegend() {
+    if (!this.id) return false;
+    return !!document.querySelector(`chart-legend-ui[for="${CSS.escape(this.id)}"]`);
+  }
+  #hasExternalTooltip() {
+    if (!this.id) return false;
+    return !!document.querySelector(`tooltip-ui[follows="pointer"][for="${CSS.escape(this.id)}"]`);
+  }
+
+  #onLegendToggle = (event) => {
+    const legend = event.target?.closest?.('chart-legend-ui[for]');
+    if (!legend || legend.getAttribute('for') !== this.id) return;
+    const { key, active } = event.detail || {};
+    if (!key) return;
+    if (active) this.#hiddenSeriesKeys.delete(key);
+    else        this.#hiddenSeriesKeys.add(key);
+    this.#renderChart();
+  };
+
+  #isSeriesHidden(key) {
+    return !!key && this.#hiddenSeriesKeys.has(key);
+  }
+
+  /* ── Deprecation warnings (OD-CHART-02) ─────────────────────────
+     `aspect=` and `heading=` were part of the pre-composition model —
+     `aspect` is stale because parents now size the chart; `heading`
+     because card headers are the semantic location for chart titles.
+     Warn once per instance so the console stays readable. Attrs still
+     honored; removal planned for the next major. */
+  #deprecationWarned = false;
+  #warnDeprecatedAttrs() {
+    if (this.#deprecationWarned) return;
+    if (this.aspect && this.aspect !== 'std') {
+      console.warn(
+        `[chart-ui] aspect="${this.aspect}" is deprecated. ` +
+        `Parents should size the chart directly (width/height on the card ` +
+        `or container). The attribute will be removed in a future major.`
+      );
+      this.#deprecationWarned = true;
+    }
+    if (this.heading) {
+      console.warn(
+        `[chart-ui] heading="${this.heading}" is deprecated. ` +
+        `Place the title in an enclosing card-ui <header><span slot="heading"> ` +
+        `instead. The attribute will be removed in a future major.`
+      );
+      this.#deprecationWarned = true;
+    }
+  }
+
+  /* ── Number formatting (OD-CHART-03) ────────────────────────────
+     `format` attribute selects how datum values are displayed on axis
+     labels, bar/line value overlays, donut centers, etc. Falls back to
+     the local `fmt()` helper for `abbr` (existing behavior). Currency
+     prefix reads --chart-currency-prefix (default "$") so consumers
+     retune per locale without touching the format attr itself. */
+  #fmtValue(v) {
+    if (v == null || v === '') return '';
+    const n = +v;
+    if (!Number.isFinite(n)) return String(v);
+    const fmtAttr = this.format || 'abbr';
+    switch (fmtAttr) {
+      case 'decimal': return n.toFixed(2);
+      case 'percent': return `${(n * 100).toFixed(1)}%`;
+      case 'currency': {
+        /* --chart-currency-prefix is a CSS custom property storing a string.
+           getComputedStyle returns it with the surrounding quotes ('"$"'),
+           which must be stripped before concatenation. Empty/unset falls
+           back to '$'. */
+        let prefix = getComputedStyle(this).getPropertyValue('--chart-currency-prefix').trim();
+        if ((prefix.startsWith('"') && prefix.endsWith('"')) ||
+            (prefix.startsWith("'") && prefix.endsWith("'"))) {
+          prefix = prefix.slice(1, -1);
+        }
+        return `${prefix || '$'}${fmt(n)}`;
+      }
+      case 'abbr':
+      default: return fmt(n);
+    }
+  }
+
+  /* ── Keyboard nav (OD-CHART-06) ─────────────────────────────────
+     Virtual focus across data points in DOM order — ArrowLeft/Right or
+     ArrowUp/Down step by one; Home/End jump to first/last; Enter/Space
+     fires chart-select; Escape clears focus and fires chart-leave. On
+     focus change, the chart emits the same chart-hover event shape as
+     the pointer path so tooltip-ui[follows=pointer][for] tracks keyboard
+     focus without needing its own code path.
+
+     Per-datum focus indicator is a data-a11y-focus attribute on the
+     focused element + a data-a11y-focused attribute on the host; CSS
+     paints the outline. */
+  #focusedDatumIdx = -1;
+
+  #datums() {
+    /* `[data-tip-label]` OR `[data-tip-value]` — every datum emits at
+       least one, so this catches every renderer. `circle[data-hit]` is
+       included intentionally (line/scatter uses a hit overlay as its
+       hover target). */
+    return Array.from(this.querySelectorAll('[data-tip-label], [data-tip-value]'));
+  }
+
+  #setFocusedDatum(idx) {
+    const datums = this.#datums();
+    if (!datums.length) { this.#clearFocusedDatum(); return; }
+    this.#focusedDatumIdx = Math.max(0, Math.min(idx, datums.length - 1));
+    this.#paintFocusIndicator();
+    this.#emitHoverForFocused();
+  }
+
+  #paintFocusIndicator() {
+    const datums = this.#datums();
+    /* Clear previous focus marker. */
+    for (const d of datums) d.removeAttribute('data-a11y-focus');
+    const el = datums[this.#focusedDatumIdx];
+    if (!el) return this.removeAttribute('data-a11y-focused');
+    el.setAttribute('data-a11y-focus', '');
+    this.setAttribute('data-a11y-focused', '');
+  }
+
+  #clearFocusedDatum() {
+    this.#focusedDatumIdx = -1;
+    for (const d of this.#datums()) d.removeAttribute('data-a11y-focus');
+    this.removeAttribute('data-a11y-focused');
+  }
+
+  #emitHoverForFocused() {
+    const el = this.#datums()[this.#focusedDatumIdx];
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const synthEvent = { clientX: rect.left + rect.width / 2, clientY: rect.top + rect.height / 2 };
+    this.#emitHover(el, synthEvent);
+  }
+
+  #emitSelectForFocused() {
+    const el = this.#datums()[this.#focusedDatumIdx];
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const synthEvent = { clientX: rect.left + rect.width / 2, clientY: rect.top + rect.height / 2 };
+    this.dispatchEvent(new CustomEvent('chart-select', {
+      bubbles: true,
+      detail: this.#tipPayload(el, synthEvent),
+    }));
+  }
+
+  #onFocus = () => {
+    /* On first focus, select the first datum. Subsequent focuses keep
+       the prior position (common keyboard-nav convention). */
+    if (this.#focusedDatumIdx === -1) this.#setFocusedDatum(0);
+  };
+
+  #onBlur = () => {
+    this.#clearFocusedDatum();
+    if (this.#hoveredTarget) this.#emitLeave();
+  };
+
+  #onKeydown = (e) => {
+    const datums = this.#datums();
+    if (!datums.length) return;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        e.preventDefault();
+        this.#setFocusedDatum(this.#focusedDatumIdx + 1);
+        break;
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        e.preventDefault();
+        this.#setFocusedDatum(Math.max(0, this.#focusedDatumIdx - 1));
+        break;
+      case 'Home':
+        e.preventDefault();
+        this.#setFocusedDatum(0);
+        break;
+      case 'End':
+        e.preventDefault();
+        this.#setFocusedDatum(datums.length - 1);
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        this.#emitSelectForFocused();
+        break;
+      case 'Escape':
+        e.preventDefault();
+        this.#clearFocusedDatum();
+        if (this.#hoveredTarget) this.#emitLeave();
+        break;
+    }
+  };
+
+  #hoveredTarget = null;
+
   #onPointerOver = (e) => {
+    /* OD-CHART-07 — touch uses pointerdown to tap-to-pin; pointerover
+       is too noisy on touch devices (fires redundantly with down). */
+    if (e.pointerType === 'touch') return;
     const t = e.target.closest('[data-tip-label], [data-tip-value]');
-    if (t) this.#showTooltip(t, e);
+    if (t) {
+      this.#showTooltip(t, e);
+      this.#emitHover(t, e);
+    }
   };
 
   #onPointerMove = (e) => {
+    if (e.pointerType === 'touch') return;  /* touch handled via pointerdown */
     const t = e.target.closest('[data-tip-label], [data-tip-value]');
-    if (!t) return this.#hideTooltip();
+    if (!t) {
+      if (this.#hoveredTarget) this.#emitLeave();
+      return this.#hideTooltip();
+    }
     this.#showTooltip(t, e);
+    if (t !== this.#hoveredTarget) this.#emitHover(t, e);
   };
 
-  #onPointerLeave = () => this.#hideTooltip();
+  #onPointerLeave = (e) => {
+    if (e && e.pointerType === 'touch') return;
+    this.#hideTooltip();
+    if (this.#hoveredTarget) this.#emitLeave();
+  };
+
+  /* OD-CHART-07 — tap-to-pin on touch devices. Tapping a datum shows
+     the tooltip and emits chart-hover; tapping elsewhere (including
+     outside the chart via the document listener below) dismisses it.
+     Mouse + pen go through the existing pointerover path; pointerdown
+     here only processes touch so desktop behavior is unchanged. */
+  #onPointerDown = (e) => {
+    if (e.pointerType !== 'touch') return;
+    const t = e.target.closest('[data-tip-label], [data-tip-value]');
+    if (!t) {
+      /* Tap on empty plot area → dismiss any pinned tooltip. */
+      if (this.#hoveredTarget) this.#emitLeave();
+      return this.#hideTooltip();
+    }
+    this.#showTooltip(t, e);
+    if (t !== this.#hoveredTarget) this.#emitHover(t, e);
+    /* Attach document-level dismiss — removed when tap lands outside
+       the chart. Idempotent: re-attaching replaces the same listener
+       by reference. */
+    document.addEventListener('pointerdown', this.#pinnedTouchDismiss);
+  };
+
+  /* Document-level touch listener — dismiss pinned tooltip when the
+     user taps outside the chart. Only attached when a tooltip is
+     currently pinned via touch. Lazily attached/detached to avoid
+     perpetual document listeners on every page. */
+  #pinnedTouchDismiss = (e) => {
+    if (e.pointerType !== 'touch') return;
+    if (!this.contains(e.target)) {
+      this.#hideTooltip();
+      if (this.#hoveredTarget) this.#emitLeave();
+      document.removeEventListener('pointerdown', this.#pinnedTouchDismiss);
+    }
+  };
+
+  #onClick = (e) => {
+    const t = e.target.closest('[data-tip-label], [data-tip-value]');
+    if (!t) return;
+    this.dispatchEvent(new CustomEvent('chart-select', {
+      bubbles: true,
+      detail: this.#tipPayload(t, e),
+    }));
+  };
+
+  #emitHover(target, event) {
+    this.#hoveredTarget = target;
+    this.dispatchEvent(new CustomEvent('chart-hover', {
+      bubbles: true,
+      detail: this.#tipPayload(target, event),
+    }));
+  }
+
+  #emitLeave() {
+    this.#hoveredTarget = null;
+    this.dispatchEvent(new CustomEvent('chart-leave', { bubbles: true }));
+  }
+
+  /* Build the standard event payload from a hovered/clicked datum element.
+     OD-CHART-05 — per-X-column granularity. For multi-series renderers
+     (stacked-bar, grouped-bar, multi-line, composed), the pointer is
+     logically over "one X-axis column" and all series at that X are
+     hover-relevant. The detail therefore carries:
+       - top-level fields describing the specific datum the pointer
+         actually entered (label, value, pct, series, slot) — back-compat
+         with Phase 1-2 consumers.
+       - `payload` array with every series at this X column, each row
+         shaped { series, value, pct?, slot }. For single-series types,
+         payload has one entry containing the top-level datum.
+     Tooltip-ui[follows=pointer] renders one row per payload entry so
+     the card shows all series at that X, highlighting the hovered
+     series slightly. */
+  #tipPayload(target, event) {
+    const { tipLabel, tipValue, tipPct, tipSeries } = target.dataset;
+    const slot = target.dataset.slice != null ? Number(target.dataset.slice) : null;
+    const value = tipValue != null ? Number(tipValue) : null;
+    const pct = tipPct != null ? Number(tipPct) : null;
+
+    const hoveredLabel = tipLabel ?? null;
+    const hoveredSeries = tipSeries ?? null;
+
+    /* Build the per-X-column payload. Look up the data row whose x-key
+       matches the hovered label; enumerate declared y-keys; project a
+       row per (visible) series. For types without an x-key (pie/donut/
+       segments/radar — categorical) or with no y-keys, payload falls
+       back to a single entry matching the hovered datum. */
+    const payload = this.#buildXColumnPayload(hoveredLabel, hoveredSeries) ?? [{
+      series: hoveredSeries,
+      label:  hoveredLabel,
+      value:  Number.isFinite(value) ? value : (tipValue ?? null),
+      pct:    Number.isFinite(pct) ? pct : null,
+      slot,
+    }];
+
+    return {
+      label:   hoveredLabel,
+      value:   Number.isFinite(value) ? value : (tipValue ?? null),
+      pct:     Number.isFinite(pct) ? pct : null,
+      series:  hoveredSeries,
+      slot,
+      payload,
+      pointerX: event?.clientX ?? null,
+      pointerY: event?.clientY ?? null,
+    };
+  }
+
+  #buildXColumnPayload(xLabel, hoveredSeries) {
+    if (xLabel == null) return null;
+    const xKey = this.x;
+    const yKeys = this.#yKeys();
+    if (!xKey || yKeys.length === 0) return null;
+    /* Find the row whose x-key value matches the hovered label. Raw
+       label string match — both sides came from the same source so no
+       type coercion needed. */
+    const row = this.#data.find(d => String(d[xKey] ?? '') === String(xLabel));
+    if (!row) return null;
+    const visible = yKeys.filter(k => !this.#isSeriesHidden(k));
+    /* Single-series types don't emit `data-tip-series` — the hovered
+       datum is implicitly the one and only series. Promote it so the
+       tooltip can still emphasize the row. */
+    const effectiveHovered = hoveredSeries || (visible.length === 1 ? visible[0] : null);
+    return visible.map((k, i) => {
+      const v = +(row[k] ?? 0);
+      return {
+        series: k,
+        label:  xLabel,
+        value:  Number.isFinite(v) ? v : null,
+        pct:    null,
+        slot:   i % 10,
+        hovered: k === effectiveHovered,
+      };
+    });
+  }
 
   #showTooltip(target, event) {
+    /* Phase 2 follow-up — when an external tooltip-ui[follows=pointer][for=self]
+       is present on the page, it owns the tooltip affordance. Skip the
+       internal #tipEl entirely to avoid double-render / fighting for the
+       top-layer. The external tooltip subscribes to chart-hover events
+       emitted in #emitHover below. */
+    if (this.#hasExternalTooltip()) return;
+
     const { tipLabel, tipValue, tipPct, tipSeries } = target.dataset;
 
     if (!this.#tipEl) {
@@ -402,7 +879,7 @@ class AdiaChart extends AdiaElement {
     if (tipLabel)  lines.push(`<span data-tip-role="label">${esc(tipLabel)}</span>`);
     if (tipValue !== undefined) {
       const pct = tipPct !== undefined ? ` <span data-tip-role="pct">(${tipPct}%)</span>` : '';
-      lines.push(`<span data-tip-role="value">${fmt(tipValue)}${pct}</span>`);
+      lines.push(`<span data-tip-role="value">${this.#fmtValue(tipValue)}${pct}</span>`);
     }
     this.#tipEl.innerHTML = lines.join('');
 
@@ -463,7 +940,7 @@ class AdiaChart extends AdiaElement {
       /* Y-axis labels */
       for (const t of displayTicks) {
         const gy = p.top + (height - p.top - p.bottom) * (1 - (t - ticks[0]) / safeRange);
-        s += `<text data-y-label x="${p.left - 4}" y="${gy + fs * 0.35}" text-anchor="end" font-size="${fs}">${fmt(t)}</text>`;
+        s += `<text data-y-label x="${p.left - 4}" y="${gy + fs * 0.35}" text-anchor="end" font-size="${fs}">${this.#fmtValue(t)}</text>`;
       }
 
       /* X-axis labels — stride based on label width so they never overlap */
@@ -519,7 +996,7 @@ class AdiaChart extends AdiaElement {
       svg += `<rect data-bar${tip({ label: labels[i], value: v })} x="${bx}" y="${by}" width="${barInner}" height="${barH}" rx="${this.#resolveRadius()}"/>`;
 
       if (showValues) {
-        svg += `<text data-value x="${bx + barInner / 2}" y="${by - 4}" text-anchor="middle" font-size="${dims.valueSize}">${fmt(v)}</text>`;
+        svg += `<text data-value x="${bx + barInner / 2}" y="${by - 4}" text-anchor="middle" font-size="${dims.valueSize}">${this.#fmtValue(v)}</text>`;
       }
     }
 
@@ -527,7 +1004,7 @@ class AdiaChart extends AdiaElement {
       const avg = vals.reduce((a, b) => a + b, 0) / vals.length;
       const ay = pad.top + plotH - (maxVal ? (avg / maxVal) * plotH : 0);
       svg += `<line data-avg x1="${pad.left}" y1="${ay}" x2="${width - pad.right}" y2="${ay}"/>`;
-      svg += `<text data-avg-label x="${width - pad.right + 2}" y="${ay + 3}" text-anchor="start" font-size="${dims.valueSize}">${fmt(avg)}</text>`;
+      svg += `<text data-avg-label x="${width - pad.right + 2}" y="${ay + 3}" text-anchor="start" font-size="${dims.valueSize}">${this.#fmtValue(avg)}</text>`;
       /* Wider invisible hit target so the thin dashed line is hoverable */
       svg += `<line data-hit${tip({ label: 'Average', value: avg })} x1="${pad.left}" y1="${ay}" x2="${width - pad.right}" y2="${ay}" stroke="transparent" stroke-width="12"/>`;
     }
@@ -575,7 +1052,7 @@ class AdiaChart extends AdiaElement {
       svg += `<circle data-dot cx="${p.x}" cy="${p.y}" r="${dotR}"/>`;
       svg += `<circle data-hit${tip({ label: p.label, value: p.v })} cx="${p.x}" cy="${p.y}" r="${hitR}" fill="transparent"/>`;
       if (showValues) {
-        svg += `<text data-value x="${p.x}" y="${p.y - 8}" text-anchor="middle" font-size="${dims.valueSize}">${fmt(p.v)}</text>`;
+        svg += `<text data-value x="${p.x}" y="${p.y - 8}" text-anchor="middle" font-size="${dims.valueSize}">${this.#fmtValue(p.v)}</text>`;
       }
     }
 
@@ -583,7 +1060,7 @@ class AdiaChart extends AdiaElement {
       const avg = vals.reduce((a, b) => a + b, 0) / vals.length;
       const ay = pad.top + plotH - (maxVal ? (avg / maxVal) * plotH : 0);
       svg += `<line data-avg x1="${pad.left}" y1="${ay}" x2="${width - pad.right}" y2="${ay}"/>`;
-      svg += `<text data-avg-label x="${width - pad.right + 2}" y="${ay + 3}" text-anchor="start" font-size="${dims.valueSize}">${fmt(avg)}</text>`;
+      svg += `<text data-avg-label x="${width - pad.right + 2}" y="${ay + 3}" text-anchor="start" font-size="${dims.valueSize}">${this.#fmtValue(avg)}</text>`;
       /* Wider invisible hit target so the thin dashed line is hoverable */
       svg += `<line data-hit${tip({ label: 'Average', value: avg })} x1="${pad.left}" y1="${ay}" x2="${width - pad.right}" y2="${ay}" stroke="transparent" stroke-width="12"/>`;
     }
@@ -678,7 +1155,7 @@ class AdiaChart extends AdiaElement {
     /* Center total — font size tied to donut radius so it scales with the chart */
     const totalFs = Math.max(14, Math.round(outer * 0.32));
     const labelFs = Math.max(9, Math.round(outer * 0.16));
-    svg += `<text data-donut-total x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central" font-size="${totalFs}">${fmt(total)}</text>`;
+    svg += `<text data-donut-total x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central" font-size="${totalFs}">${this.#fmtValue(total)}</text>`;
     svg += `<text data-donut-label x="${cx}" y="${cy + totalFs}" text-anchor="middle" dominant-baseline="central" font-size="${labelFs}">Total</text>`;
 
     this.#legendData = data.map((d, i) => ({
@@ -815,6 +1292,537 @@ class AdiaChart extends AdiaElement {
     return { svg, viewBox: `0 0 ${w} ${h}` };
   }
 
+  /* ── Area chart (filled line) ────────────────────────────────────
+     Single-series axis chart emphasizing the filled region under the
+     curve. Shares all infrastructure with #renderLine() — CSS rules
+     scoped to :scope[type="area"] override the area-fill opacity and
+     the line treatment to make the region dominant. Output is DOM-
+     compatible with #renderLine() so legend / tooltip / events work
+     identically. */
+  #renderArea() {
+    return this.#renderLine();
+  }
+
+  /* ── Scatter (points only, no connecting line) ──────────────────
+     Two-dimensional distribution — each datum is a dot positioned by
+     (x, y). Unlike #renderLine(), no connecting path is emitted. The
+     x-key is typically also numeric; when it's a category label, the
+     dots land at category-indexed column centers. */
+  #renderScatter() {
+    const dims = this.#dims();
+    const data = this.#data;
+    const yKey = this.#yKeys()[0] || this.y;
+    const vals = data.map(v => +(v[yKey] ?? 0));
+    const labels = data.map(v => v[this.x] ?? '');
+    const ticks = niceScale(0, Math.max(...vals), 5);
+    const maxVal = ticks[ticks.length - 1];
+
+    const { width, height, pad } = dims;
+    const plotH = height - pad.top - pad.bottom;
+    const plotW = width - pad.left - pad.right;
+    const step = plotW / Math.max(data.length - 1, 1);
+
+    let svg = this.#gridAndAxes(width, height, ticks, labels, pad, dims);
+
+    const dotR = dims.sizeClass === 'sm' ? 2.5 : 4;
+    const hitR = Math.max(dotR * 2, 10);
+
+    for (let i = 0; i < vals.length; i++) {
+      const px = pad.left + step * i;
+      const py = pad.top + plotH - (maxVal ? (vals[i] / maxVal) * plotH : 0);
+      svg += `<circle data-dot data-scatter cx="${px}" cy="${py}" r="${dotR}"/>`;
+      svg += `<circle data-hit${tip({ label: labels[i], value: vals[i] })} cx="${px}" cy="${py}" r="${hitR}" fill="transparent"/>`;
+    }
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Radial bar (concentric rings, each ring one datum) ─────────
+     Each datum gets its own ring in a concentric stack. The ring's
+     sweep angle is proportional to value/max — e.g., v=max is a full
+     ring, v=0 is nothing. Rings are clipped to a common max-radius
+     track shown as a faint backing arc so empty values read visually.
+     Center is empty — authors who want a value overlay use the
+     `[slot=empty]` trick or compose in a sibling element. */
+  #renderRadialBar() {
+    const data = this.#data;
+    const yKey = this.#yKeys()[0] || this.y;
+    const vals = data.map(d => +(d[yKey] ?? 0));
+    const labels = data.map(d => d[this.x] ?? '');
+    const maxVal = Math.max(...vals) || 1;
+
+    const dims = this.#dims();
+    const { width, height } = dims;
+    const cx = width / 2;
+    const cy = height / 2;
+    const outerR = Math.max(30, Math.min(width, height) * 0.45);
+    const innerR = outerR * 0.3;
+    const ringCount = vals.length || 1;
+    const bandW = (outerR - innerR) / ringCount;
+    const gap = Math.min(2, bandW * 0.15);
+
+    let svg = '';
+
+    /* Backing tracks + filled arcs per datum, from inner to outer.
+       Uses the stroke-dasharray technique: each ring is a single <circle>,
+       rotated so the dash starts at 12 o'clock, with dasharray sized to
+       (filled, remainder). Avoids the "full circle" vs "arc path" branch
+       that produced rendering artifacts at 100% fills. */
+    for (let i = 0; i < vals.length; i++) {
+      const r0 = innerR + bandW * i + gap / 2;
+      const r1 = innerR + bandW * (i + 1) - gap / 2;
+      const mid = (r0 + r1) / 2;
+      const thickness = r1 - r0;
+      const circumference = 2 * Math.PI * mid;
+      const filled = Math.max(0, Math.min(1, vals[i] / maxVal)) * circumference;
+
+      /* Backing ring — full circle, faint stroke */
+      svg += `<circle data-radial-track cx="${cx}" cy="${cy}" r="${mid}" fill="none" stroke-width="${thickness}"/>`;
+
+      if (filled <= 0) continue;
+
+      const pct = ((vals[i] / maxVal) * 100).toFixed(1);
+      const tipAttrs = tip({ label: labels[i], value: vals[i], pct });
+
+      /* Filled arc — stroke-dasharray splits the circumference into
+         (drawn, gap). Rotated -90° around the center so the dash begins
+         at 12 o'clock and sweeps clockwise. stroke-linecap="butt" for
+         full rings (so the ends don't overlap into a wedge artifact);
+         "round" for partial arcs so ends read as bar caps. */
+      const isFull = Math.abs(filled - circumference) < 0.5;
+      const linecap = isFull ? 'butt' : 'round';
+      const dashArray = isFull
+        ? `${circumference} 0`
+        : `${filled} ${circumference - filled}`;
+
+      svg += `<circle data-slice="${i % 10}"${tipAttrs} data-radial-bar cx="${cx}" cy="${cy}" r="${mid}" fill="none" stroke-width="${thickness}" stroke-linecap="${linecap}" stroke-dasharray="${dashArray}" transform="rotate(-90 ${cx} ${cy})"/>`;
+    }
+
+    this.#legendData = data.map((d, i) => ({
+      label: labels[i],
+      key: labels[i],
+      value: vals[i],
+      pct: ((vals[i] / maxVal) * 100).toFixed(1),
+      slot: i % 10,
+    }));
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Gauge (half-donut with center value) ───────────────────────
+     Common KPI visualization: a 180° arc filled from the leftmost
+     point (9 o'clock) clockwise to the current value. Center shows
+     the value as a large number. Uses the same data-slice fill path
+     as pie/donut for theme coherence. Accepts a single datum OR
+     sums all data values — max is `maxVal` prop if set, otherwise
+     taken as the sum of all values (treats the total as 100%). */
+  #renderGauge() {
+    const data = this.#data;
+    const yKey = this.#yKeys()[0] || this.y;
+    const vals = data.map(d => +(d[yKey] ?? 0));
+    const sum = vals.reduce((a, b) => a + b, 0) || 1;
+
+    /* Gauge reads a single value + optional max from the first datum
+       (v, max?) OR treats the first value as the numerator and the
+       sum as the denominator for "X of Y" style metrics. */
+    const primary = vals[0] ?? 0;
+    const maxVal = data[0]?.max != null ? +data[0].max : (vals.length === 1 ? Math.max(primary, 1) : sum);
+    const pct = Math.max(0, Math.min(1, primary / maxVal));
+
+    const dims = this.#dims();
+    const { width, height } = dims;
+
+    /* Place the arc's visual center so the half-circle uses the full
+       width below the value label. cy sits lower so the half-arc has
+       room for the big center label above it. */
+    const cx = width / 2;
+    const cy = height * 0.68;
+    const outerR = Math.max(40, Math.min(width * 0.45, height * 0.6));
+    const innerR = outerR * 0.72;
+
+    let svg = '';
+
+    /* Backing arc — full 180° upper semicircle, from 9 o'clock (angle π)
+       clockwise through 12 o'clock (3π/2) to 3 o'clock (2π). donutArcPath
+       produces a filled ring wedge; with start=π, end=2π the sliceAngle
+       equals π so large-arc-flag=0 and the arc passes over the top. */
+    svg += `<path data-radial-track d="${donutArcPath(cx, cy, outerR, innerR, Math.PI, 2 * Math.PI, 0)}"/>`;
+
+    /* Filled portion — 0..180° proportional to pct. pct=0 draws nothing;
+       pct=1 overlays the full backing arc. */
+    if (pct > 0) {
+      const fillEnd = Math.PI + Math.PI * pct;
+      const tipAttrs = tip({ label: data[0]?.[this.x] ?? 'Value', value: primary, pct: (pct * 100).toFixed(1) });
+      svg += `<path data-slice="0"${tipAttrs} data-gauge-fill d="${donutArcPath(cx, cy, outerR, innerR, Math.PI, fillEnd, 0)}"/>`;
+    }
+
+    /* Center value label */
+    const totalFs = Math.max(18, Math.round(outerR * 0.42));
+    const labelFs = Math.max(10, Math.round(outerR * 0.2));
+    const labelY = cy - outerR * 0.15;
+    svg += `<text data-gauge-value x="${cx}" y="${labelY}" text-anchor="middle" dominant-baseline="central" font-size="${totalFs}">${this.#fmtValue(primary)}</text>`;
+    if (maxVal !== primary) {
+      svg += `<text data-gauge-max x="${cx}" y="${labelY + totalFs * 0.8}" text-anchor="middle" dominant-baseline="central" font-size="${labelFs}">of ${this.#fmtValue(maxVal)}</text>`;
+    }
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Funnel (stage drop-off) ───────────────────────────────────
+     Classic conversion funnel: stages listed top-to-bottom, each
+     rendered as a trapezoid whose width shrinks proportional to its
+     value. Stage labels live to the left, value + pct vs first stage
+     to the right. Typical use: sales pipeline, signup funnel.
+
+     Trapezoid geometry: for stage i with value v_i and max value v_0:
+       halfWidthTop  = (v_i / v_max) * plotW / 2
+       halfWidthBot  = (v_{i+1} / v_max) * plotW / 2
+     Last stage uses halfWidthBot = halfWidthTop (degrades to rect). */
+  #renderFunnel() {
+    const data = this.#data;
+    const yKey = this.#yKeys()[0] || this.y;
+    const vals = data.map(d => +(d[yKey] ?? 0));
+    const labels = data.map(d => d[this.x] ?? '');
+    const n = vals.length;
+    if (n === 0) return { svg: '', viewBox: '0 0 100 100' };
+
+    const maxVal = Math.max(...vals) || 1;
+
+    const dims = this.#dims();
+    const { width, height } = dims;
+    const fs = dims.fontSize;
+    const padX = Math.max(width * 0.18, 80);      /* room for stage labels */
+    const padY = fs * 0.8;
+    const plotW = width - padX * 2;
+    const plotH = height - padY * 2;
+    const stageH = plotH / n;
+    const gap = Math.max(2, stageH * 0.08);
+
+    const cx = width / 2;
+
+    let svg = '';
+    for (let i = 0; i < n; i++) {
+      const vTop = vals[i];
+      const vBot = (i < n - 1) ? vals[i + 1] : vals[i];
+      const halfTop = (vTop / maxVal) * (plotW / 2);
+      const halfBot = (vBot / maxVal) * (plotW / 2);
+      const y0 = padY + stageH * i + gap / 2;
+      const y1 = padY + stageH * (i + 1) - gap / 2;
+
+      const pct = ((vTop / maxVal) * 100).toFixed(1);
+      const tipAttrs = tip({ label: labels[i], value: vTop, pct });
+
+      /* Trapezoid path: top-left, top-right, bottom-right, bottom-left. */
+      const d = `M ${cx - halfTop} ${y0} L ${cx + halfTop} ${y0} L ${cx + halfBot} ${y1} L ${cx - halfBot} ${y1} Z`;
+      svg += `<path data-slice="${i % 10}" data-funnel-stage${tipAttrs} d="${d}"/>`;
+
+      /* Stage label — left-aligned outside the funnel */
+      svg += `<text data-funnel-label x="${padX - 8}" y="${y0 + stageH / 2}" text-anchor="end" dominant-baseline="central" font-size="${fs}">${esc(labels[i])}</text>`;
+
+      /* Value + pct — right-aligned outside the funnel */
+      svg += `<text data-funnel-value x="${width - padX + 8}" y="${y0 + stageH / 2}" text-anchor="start" dominant-baseline="central" font-size="${fs}">${this.#fmtValue(vTop)}</text>`;
+      if (i > 0) {
+        const dropPct = ((vals[i] / vals[0]) * 100).toFixed(0);
+        svg += `<text data-funnel-drop x="${width - padX + 8}" y="${y0 + stageH / 2 + fs * 1.1}" text-anchor="start" dominant-baseline="central" font-size="${fs * 0.85}">${dropPct}%</text>`;
+      }
+    }
+
+    this.#legendData = data.map((d, i) => ({
+      label: labels[i], value: vals[i], pct: ((vals[i] / maxVal) * 100).toFixed(1), slot: i % 10,
+    }));
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Treemap (hierarchical rect tiling) ────────────────────────
+     Flat squarified treemap: each datum is a rect whose area is
+     proportional to its value. Not nested — Phase 5 ships flat
+     rectangles; a nested variant (children arrays) is a natural
+     future extension.
+
+     Uses the Bruls/Huijbregts/Van Wijk squarified algorithm adapted
+     for single-level data: sorts values desc, packs rows that hold
+     aspect ratios close to 1, alternating row direction based on
+     remaining container aspect. */
+  #renderTreemap() {
+    const data = this.#data;
+    const yKey = this.#yKeys()[0] || this.y;
+    const vals = data.map(d => +(d[yKey] ?? 0));
+    const labels = data.map(d => d[this.x] ?? '');
+    const n = vals.length;
+    if (n === 0) return { svg: '', viewBox: '0 0 100 100' };
+
+    const dims = this.#dims();
+    const { width, height, fontSize } = dims;
+    const total = vals.reduce((a, b) => a + b, 0) || 1;
+
+    /* Sort indices by value desc — squarified needs sorted input but
+       we keep original indices for color/label/hit mapping. */
+    const order = Array.from({ length: n }, (_, i) => i).sort((a, b) => vals[b] - vals[a]);
+
+    const rects = [];  /* {i, x, y, w, h} in plot coords */
+
+    /* Scale areas so they fill the container. */
+    const area = width * height;
+    const scaled = order.map(i => (vals[i] / total) * area);
+
+    /* Squarified packer — iterative rows. */
+    let x = 0, y = 0, w = width, h = height;
+    let row = [];
+    let rowStart = 0;
+
+    const worst = (row, width) => {
+      if (row.length === 0) return Infinity;
+      const sum = row.reduce((a, b) => a + b, 0);
+      const max = Math.max(...row);
+      const min = Math.min(...row);
+      const wsq = width * width;
+      const ssq = sum * sum;
+      return Math.max((wsq * max) / ssq, ssq / (wsq * min));
+    };
+
+    const layoutRow = (row, rowStart, x, y, w, h) => {
+      const sum = row.reduce((a, b) => a + b, 0);
+      const horizontal = w >= h;
+      const rowH = horizontal ? sum / w : h;
+      const rowW = horizontal ? w : sum / h;
+
+      let offset = 0;
+      for (let k = 0; k < row.length; k++) {
+        const frac = row[k] / sum;
+        const idx = order[rowStart + k];
+        if (horizontal) {
+          const segW = frac * w;
+          rects.push({ i: idx, x: x + offset, y, w: segW, h: rowH });
+          offset += segW;
+        } else {
+          const segH = frac * h;
+          rects.push({ i: idx, x, y: y + offset, w: rowW, h: segH });
+          offset += segH;
+        }
+      }
+      if (horizontal) return { x, y: y + rowH, w, h: h - rowH };
+      return { x: x + rowW, y, w: w - rowW, h };
+    };
+
+    let remaining = scaled.slice();
+    while (remaining.length > 0) {
+      row = [remaining[0]];
+      rowStart = scaled.length - remaining.length;
+      const shortSide = Math.min(w, h);
+      let i = 1;
+      while (i < remaining.length) {
+        const next = row.concat(remaining[i]);
+        if (worst(next, shortSide) > worst(row, shortSide)) break;
+        row = next;
+        i++;
+      }
+      const newRect = layoutRow(row, rowStart, x, y, w, h);
+      x = newRect.x; y = newRect.y; w = newRect.w; h = newRect.h;
+      remaining = remaining.slice(row.length);
+    }
+
+    /* Emit rects + labels. */
+    let svg = '';
+    const pad = 2;
+    for (const r of rects) {
+      const pct = ((vals[r.i] / total) * 100).toFixed(1);
+      const tipAttrs = tip({ label: labels[r.i], value: vals[r.i], pct });
+      svg += `<rect data-slice="${r.i % 10}" data-treemap-tile${tipAttrs} x="${r.x + pad}" y="${r.y + pad}" width="${Math.max(0, r.w - pad * 2)}" height="${Math.max(0, r.h - pad * 2)}" rx="${this.#resolveRadius()}"/>`;
+
+      /* Three text-placement branches keyed on available tile size:
+         - `tall` (h > ~2.5 line heights): label + value stacked, top-aligned
+         - `short` (h ≥ ~1.2 line heights but < tall): label only, vertically
+           centered — avoids the clipped-text look when tiles are squat
+         - `tiny` (h too small for even one line): no text
+         All branches gate on width > ~4× fontSize so labels don't overflow. */
+      const labelX = r.x + 8;
+      const canShowAny = r.w > fontSize * 4;
+      const tall  = canShowAny && r.h > fontSize * 2.5;
+      const short = canShowAny && !tall && r.h > fontSize * 1.2;
+
+      if (tall) {
+        svg += `<text data-treemap-label x="${labelX}" y="${r.y + fontSize + 4}" font-size="${fontSize}" dominant-baseline="hanging">${esc(labels[r.i])}</text>`;
+        svg += `<text data-treemap-value x="${labelX}" y="${r.y + fontSize * 2 + 6}" font-size="${fontSize * 0.9}" dominant-baseline="hanging">${this.#fmtValue(vals[r.i])}</text>`;
+      } else if (short) {
+        const cy = r.y + r.h / 2;
+        svg += `<text data-treemap-label x="${labelX}" y="${cy}" font-size="${fontSize}" dominant-baseline="central">${esc(labels[r.i])}</text>`;
+      }
+    }
+
+    this.#legendData = data.map((d, i) => ({
+      label: labels[i], value: vals[i], pct: ((vals[i] / total) * 100).toFixed(1), slot: i % 10,
+    }));
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Sankey (flow between source and target nodes) ─────────────
+     Flow diagram with columns of nodes and curved bands connecting
+     them. Data shape for Sankey differs from other chart types:
+       data = [{ source: 'A', target: 'B', value: 10 }, ...]
+     Nodes are auto-derived from unique source/target values.
+     Lays out two columns (source-left, target-right) with node
+     heights proportional to throughput. */
+  #renderSankey() {
+    const data = this.#data;
+    if (!data.length) return { svg: '', viewBox: '0 0 100 100' };
+
+    /* Derive source + target node sets from the link data. */
+    const sourceSet = new Map();  /* name → { outflow, y0, y1 } */
+    const targetSet = new Map();  /* name → { inflow, y0, y1 } */
+    for (const link of data) {
+      const s = link.source ?? link.from ?? '';
+      const t = link.target ?? link.to ?? '';
+      const v = +(link.value ?? link.v ?? 0);
+      if (!sourceSet.has(s)) sourceSet.set(s, { name: s, flow: 0 });
+      if (!targetSet.has(t)) targetSet.set(t, { name: t, flow: 0 });
+      sourceSet.get(s).flow += v;
+      targetSet.get(t).flow += v;
+    }
+
+    const dims = this.#dims();
+    const { width, height, fontSize } = dims;
+    const nodeW = Math.max(8, width * 0.03);
+    const colPad = nodeW + fontSize * 5;
+
+    const sourceTotal = [...sourceSet.values()].reduce((a, s) => a + s.flow, 0) || 1;
+    const targetTotal = [...targetSet.values()].reduce((a, t) => a + t.flow, 0) || 1;
+
+    const nodeGap = fontSize * 0.6;
+
+    /* Assign y0/y1 to each source node, stacked top-to-bottom. */
+    const sources = [...sourceSet.values()];
+    const targets = [...targetSet.values()];
+    const sourceTotalH = height - nodeGap * (sources.length - 1);
+    const targetTotalH = height - nodeGap * (targets.length - 1);
+
+    let y = 0;
+    for (const s of sources) {
+      const h = (s.flow / sourceTotal) * sourceTotalH;
+      s.y0 = y;
+      s.y1 = y + h;
+      s.cursor = y;  /* running y for outgoing links */
+      y += h + nodeGap;
+    }
+    y = 0;
+    for (const t of targets) {
+      const h = (t.flow / targetTotal) * targetTotalH;
+      t.y0 = y;
+      t.y1 = y + h;
+      t.cursor = y;
+      y += h + nodeGap;
+    }
+
+    let svg = '';
+
+    const nodeRx = Math.min(this.#resolveRadius(), nodeW / 2);
+
+    /* Source nodes — left column */
+    sources.forEach((s, i) => {
+      svg += `<rect data-sankey-node data-slice="${i % 10}" x="${colPad - nodeW}" y="${s.y0}" width="${nodeW}" height="${s.y1 - s.y0}" rx="${nodeRx}"/>`;
+      svg += `<text data-sankey-label x="${colPad - nodeW - 6}" y="${(s.y0 + s.y1) / 2}" text-anchor="end" dominant-baseline="central" font-size="${fontSize}">${esc(s.name)}</text>`;
+    });
+
+    /* Target nodes — right column */
+    targets.forEach((t, i) => {
+      svg += `<rect data-sankey-node data-slice="${(sources.length + i) % 10}" x="${width - colPad}" y="${t.y0}" width="${nodeW}" height="${t.y1 - t.y0}" rx="${nodeRx}"/>`;
+      svg += `<text data-sankey-label x="${width - colPad + nodeW + 6}" y="${(t.y0 + t.y1) / 2}" text-anchor="start" dominant-baseline="central" font-size="${fontSize}">${esc(t.name)}</text>`;
+    });
+
+    /* Links — bezier bands */
+    for (const link of data) {
+      const s = sourceSet.get(link.source ?? link.from ?? '');
+      const t = targetSet.get(link.target ?? link.to ?? '');
+      if (!s || !t) continue;
+      const v = +(link.value ?? link.v ?? 0);
+      if (v <= 0) continue;
+
+      const sH = (v / sourceTotal) * sourceTotalH;
+      const tH = (v / targetTotal) * targetTotalH;
+      const sTop = s.cursor;
+      const sBot = sTop + sH;
+      const tTop = t.cursor;
+      const tBot = tTop + tH;
+      s.cursor += sH;
+      t.cursor += tH;
+
+      const x0 = colPad;
+      const x1 = width - colPad;
+      const mx = (x0 + x1) / 2;
+      const tipAttrs = tip({ label: `${s.name} → ${t.name}`, value: v });
+
+      const path = `M ${x0} ${sTop} C ${mx} ${sTop}, ${mx} ${tTop}, ${x1} ${tTop} L ${x1} ${tBot} C ${mx} ${tBot}, ${mx} ${sBot}, ${x0} ${sBot} Z`;
+      svg += `<path data-sankey-link${tipAttrs} d="${path}"/>`;
+    }
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
+  /* ── Composed (bar + line overlay) ─────────────────────────────
+     Multi-series combining a bar chart for primary values with a line
+     overlay for secondary values. Data shape: each row has the x-key,
+     a `bar` key, and a `line` key. Both are axis-aligned against the
+     same Y scale (single axis for v1; dual-axis future extension).
+
+     Uses y="bar,line" as the series keys by convention. */
+  #renderComposed() {
+    const dims = this.#dims();
+    const data = this.#data;
+    const keys = this.#yKeys();
+    const barKey = keys[0] || 'bar';
+    const lineKey = keys[1] || 'line';
+    const labels = data.map(d => d[this.x] ?? '');
+    const barVals = data.map(d => +(d[barKey] ?? 0));
+    const lineVals = data.map(d => +(d[lineKey] ?? 0));
+    const allVals = [...barVals, ...lineVals];
+    const ticks = niceScale(0, Math.max(...allVals), 5);
+    const maxVal = ticks[ticks.length - 1];
+
+    const { width, height, pad } = dims;
+    const plotH = height - pad.top - pad.bottom;
+    const plotW = width - pad.left - pad.right;
+    const barW = plotW / data.length;
+    const barInner = barW * 0.6;
+    const barGap = (barW - barInner) / 2;
+    const step = plotW / Math.max(data.length - 1, 1);
+
+    let svg = this.#gridAndAxes(width, height, ticks, labels, pad, dims);
+
+    /* Bar series (slot 0) */
+    if (!this.#isSeriesHidden(barKey)) {
+      for (let i = 0; i < data.length; i++) {
+        const v = barVals[i];
+        const barH = maxVal ? (v / maxVal) * plotH : 0;
+        const bx = pad.left + barW * i + barGap;
+        const by = pad.top + plotH - barH;
+        svg += `<rect${this.#seriesFill(0, barKey)}${tip({ label: labels[i], value: v, series: barKey })} x="${bx}" y="${by}" width="${barInner}" height="${barH}" rx="${this.#resolveRadius()}"/>`;
+      }
+    }
+
+    /* Line series (slot 1) — anchored at bar center X positions */
+    if (!this.#isSeriesHidden(lineKey)) {
+      const points = lineVals.map((v, i) => ({
+        x: pad.left + barW * i + barW / 2,
+        y: pad.top + plotH - (maxVal ? (v / maxVal) * plotH : 0),
+        v, label: labels[i],
+      }));
+      const t = Math.max(0, Math.min(1, this.smooth));
+      svg += `<path data-line${this.#seriesStroke(1, lineKey)} d="${smoothPath(points, t)}"/>`;
+      for (const p of points) {
+        svg += `<circle data-dot${this.#seriesFill(1, lineKey)} cx="${p.x}" cy="${p.y}" r="3"/>`;
+        svg += `<circle data-hit${tip({ label: p.label, value: p.v, series: lineKey })} cx="${p.x}" cy="${p.y}" r="10" fill="transparent"/>`;
+      }
+    }
+
+    this.#legendData = [
+      { label: barKey,  key: barKey,  slot: 0 },
+      { label: lineKey, key: lineKey, slot: 1 },
+    ];
+
+    return { svg, viewBox: `0 0 ${width} ${height}` };
+  }
+
   /* ── Segments (single horizontal stacked bar) ──────────────────
      Categorical data rendered as one horizontal bar split into
      proportional colored slices. Good for compact in-card
@@ -915,6 +1923,7 @@ class AdiaChart extends AdiaElement {
       let stackY = pad.top + plotH;
       const segCount = keys.length;
       for (let k = 0; k < segCount; k++) {
+        if (this.#isSeriesHidden(keys[k])) continue;
         const v = +(data[i][keys[k]] ?? 0);
         const segH = maxVal ? (v / maxVal) * plotH : 0;
         if (segH <= 0) { stackY -= segH; continue; }
@@ -926,7 +1935,7 @@ class AdiaChart extends AdiaElement {
         const isBottom = k === 0;
         const r = Math.min(this.#resolveRadius(), barInner / 2, bh / 2);
 
-        const attrs = ` data-slice="${k % 10}"${tip({ label: labels[i], value: v, series: keys[k] })}`;
+        const attrs = `${this.#seriesFill(k % 10, keys[k])}${tip({ label: labels[i], value: v, series: keys[k] })}`;
 
         if (isTop && isBottom) {
           // Single segment — round top + bottom
@@ -944,7 +1953,7 @@ class AdiaChart extends AdiaElement {
       }
     }
 
-    this.#legendData = keys.map((k, i) => ({ label: k, slot: i % 10 }));
+    this.#legendData = keys.map((k, i) => ({ label: k, key: k, slot: i % 10 }));
 
     return { svg, viewBox: `0 0 ${width} ${height}` };
   }
@@ -974,19 +1983,20 @@ class AdiaChart extends AdiaElement {
 
     for (let i = 0; i < data.length; i++) {
       for (let k = 0; k < keys.length; k++) {
+        if (this.#isSeriesHidden(keys[k])) continue;
         const v = +(data[i][keys[k]] ?? 0);
         const barH = maxVal ? (v / maxVal) * plotH : 0;
         const bx = pad.left + groupW * i + groupPad + (subBarW + barGap) * k;
         const by = pad.top + plotH - barH;
-        svg += `<rect data-slice="${k % 10}"${tip({ label: labels[i], value: v, series: keys[k] })} x="${bx}" y="${by}" width="${subBarW}" height="${barH}" rx="${this.#resolveRadius()}"/>`;
+        svg += `<rect${this.#seriesFill(k % 10, keys[k])}${tip({ label: labels[i], value: v, series: keys[k] })} x="${bx}" y="${by}" width="${subBarW}" height="${barH}" rx="${this.#resolveRadius()}"/>`;
 
         if (!this.hideValues) {
-          svg += `<text data-value x="${bx + subBarW / 2}" y="${by - 4}" text-anchor="middle" font-size="${dims.valueSize}">${fmt(v)}</text>`;
+          svg += `<text data-value x="${bx + subBarW / 2}" y="${by - 4}" text-anchor="middle" font-size="${dims.valueSize}">${this.#fmtValue(v)}</text>`;
         }
       }
     }
 
-    this.#legendData = keys.map((k, i) => ({ label: k, slot: i % 10 }));
+    this.#legendData = keys.map((k, i) => ({ label: k, key: k, slot: i % 10 }));
 
     return { svg, viewBox: `0 0 ${width} ${height}` };
   }
@@ -1011,6 +2021,7 @@ class AdiaChart extends AdiaElement {
     let svg = this.#gridAndAxes(width, height, ticks, labels, pad, dims);
 
     for (let k = 0; k < keys.length; k++) {
+      if (this.#isSeriesHidden(keys[k])) continue;
       const vals = data.map(d => +(d[keys[k]] ?? 0));
       const points = vals.map((v, i) => {
         const px = pad.left + step * i;
@@ -1022,20 +2033,20 @@ class AdiaChart extends AdiaElement {
       const t = Math.max(0, Math.min(1, this.smooth));
 
       /* Area fill */
-      svg += `<path data-area data-slice="${k % 10}" d="${smoothAreaPath(points, baseline, t)}"/>`;
+      svg += `<path data-area${this.#seriesFill(k % 10, keys[k])} d="${smoothAreaPath(points, baseline, t)}"/>`;
 
       /* Line */
-      svg += `<path data-line data-slice="${k % 10}" d="${smoothPath(points, t)}"/>`;
+      svg += `<path data-line${this.#seriesStroke(k % 10, keys[k])} d="${smoothPath(points, t)}"/>`;
 
       /* Dots + hit targets. Hit circles deliberately omit data-slice so
          they aren't caught by the circle[data-slice] fill rule in CSS. */
       for (const p of points) {
-        svg += `<circle data-dot data-slice="${k % 10}" cx="${p.x}" cy="${p.y}" r="3"/>`;
+        svg += `<circle data-dot${this.#seriesFill(k % 10, keys[k])} cx="${p.x}" cy="${p.y}" r="3"/>`;
         svg += `<circle data-hit${tip({ label: p.label, value: p.v, series: keys[k] })} cx="${p.x}" cy="${p.y}" r="10" fill="transparent"/>`;
       }
     }
 
-    this.#legendData = keys.map((k, i) => ({ label: k, slot: i % 10 }));
+    this.#legendData = keys.map((k, i) => ({ label: k, key: k, slot: i % 10 }));
 
     return { svg, viewBox: `0 0 ${width} ${height}` };
   }
@@ -1044,6 +2055,14 @@ class AdiaChart extends AdiaElement {
 
   #legendData = null;
 
+  /* Public getter — external consumers (chart-legend-ui[for]) read this to
+     mirror series data. Returns a defensive shallow copy so callers can't
+     mutate our internals. Null when the chart has no legend-bearing type
+     or hasn't rendered yet. */
+  get legendData() {
+    return this.#legendData ? this.#legendData.map(it => ({ ...it })) : null;
+  }
+
   #buildLegend() {
     if (!this.#legendData || !this.#legendData.length) return null;
 
@@ -1053,10 +2072,12 @@ class AdiaChart extends AdiaElement {
     for (const item of this.#legendData) {
       const el = document.createElement('span');
       el.setAttribute('data-legend-item', '');
+      if (item.key) el.setAttribute('data-series-key', item.key);
 
       const dot = document.createElement('span');
       dot.setAttribute('data-legend-dot', '');
       dot.setAttribute('data-slice', String(item.slot));
+      if (item.key) dot.style.background = `var(--color-${item.key}, var(--chart-${item.slot}))`;
       el.appendChild(dot);
 
       const text = document.createElement('span');
@@ -1066,7 +2087,8 @@ class AdiaChart extends AdiaElement {
       legend.appendChild(el);
     }
 
-    this.#legendData = null;
+    /* Intentionally DO NOT null #legendData here — public `legendData`
+       getter needs it to survive so chart-legend-ui[for] can mirror. */
     return legend;
   }
 }