radiant-charts-core 0.2.0

package/src/core/ChartManager.ts

@@ -0,0 +1,1062 @@
+import { Scene } from '../scene/Scene';
+import { Group, Rect, Text } from '../scene/Shapes';
+import { RadiantChartOptions } from '../RadiantChart';
+import { BandScale, LinearScale, Scale } from '../scale/Scale';
+import { CartesianAxis } from '../axes/CartesianAxis';
+import { BarSeries } from '../series/BarSeries';
+import { LineSeries } from '../series/LineSeries';
+import { PieSeries } from '../series/PieSeries';
+import { AreaSeries } from '../series/AreaSeries';
+import { ScatterSeries } from '../series/ScatterSeries';
+import { TooltipStore } from '../tooltip/TooltipStore';
+import { ThemeManager, ThemeOption } from './ThemeManager';
+import { Legend, LegendItem } from './Legend';
+import { CrosshairRenderer } from './CrosshairManager';
+
+const NON_CARTESIAN = new Set([
+  'pie',
+]);
+
+export class ChartManager {
+  private container: HTMLElement;
+  private options: RadiantChartOptions;
+  private scene: Scene;
+  private tooltipStore = new TooltipStore();
+  private themeManager = new ThemeManager();
+  private legend = new Legend();
+  private legendProxy?: HTMLElement;
+  private crosshair = new CrosshairRenderer();
+  private resizeObserver: ResizeObserver;
+
+  // ── System theme media query listener ──────────────────────────────────────
+  private mediaQuery: MediaQueryList | null = null;
+  private _onSystemThemeChange = () => {
+    // Only react if the user's option is 'system'; ignore for explicit themes.
+    if (this.options.theme !== 'system') return;
+    // Re-resolve the theme and re-render the chart with the new palette.
+    this.themeManager.setTheme('system');
+    const bg = this.themeManager.theme.backgroundColor;
+    this.container.style.backgroundColor = bg;
+    this.scene.backgroundColor = bg;
+    this.processData();
+    this.performLayout();
+    this.render();
+  };
+
+  private titleGroup    = new Group();
+  private subtitleGroup = new Group();
+  private legendGroup   = new Group();
+  private seriesGroup   = new Group();
+  private axesGroup     = new Group();
+  private crosshairGroup = new Group();
+  private emptyGroup     = new Group();
+
+  private categoryScale: Scale<any, number> = new BandScale();
+  private valueScale: Scale<any, number>    = new LinearScale();
+  private valueScaleRight: Scale<any, number> = new LinearScale();
+  private xAxis?: CartesianAxis;
+  private yAxis?: CartesianAxis;
+  private yAxisRight?: CartesianAxis;
+
+  private series: any[] = [];
+  private seriesInstances = new Map<string, any>();
+  private isCartesian = true;
+  private seriesRect = { x: 0, y: 0, width: 0, height: 0 };
+  private initialized = false;
+  private animRafId: number | null = null;
+  private hoveredSeriesId: string | null = null;
+  private hiddenSeries: string[] = [];
+  private minY: number = 0;
+  private maxY: number = 0;
+
+  private lastDataRef: readonly any[] | null = null;
+
+  /** Keyboard navigation index for tooltip accessibility */
+  private _kbIndex = -1;
+  private readonly _onKeyDown: (e: KeyboardEvent) => void;
+  private readonly _onPointerLeave: (e: PointerEvent) => void;
+
+  constructor(container: HTMLElement, options: RadiantChartOptions) {
+    this.container = container;
+    this.options   = options;
+    this.scene     = new Scene(container);
+    this.tooltipStore.setOptions(options.tooltip ?? {});
+
+    // Keyboard navigation for tooltip accessibility
+    this.container.setAttribute('tabindex', '0');
+    this._onKeyDown = this._handleKeyboard.bind(this);
+    this.container.addEventListener('keydown', this._onKeyDown);
+
+    this._onPointerLeave = () => {
+      this.tooltipStore.deactivate();
+      this.crosshair.hide();
+      this.crosshair.hideSeriesSnaps();
+      this.hoveredSeriesId = null;
+      this.series.forEach(s => { s.getGroup().opacity = 1; });
+    };
+    this.container.addEventListener('pointerleave', this._onPointerLeave);
+
+    this.scene.root.add(this.titleGroup);
+    this.scene.root.add(this.subtitleGroup);
+    this.scene.root.add(this.axesGroup);
+    this.scene.root.add(this.seriesGroup);
+    // Legend must render AFTER seriesGroup so it paints on top of chart content
+    // (prevents occlusion for full-area charts like Pie, etc.)
+    this.scene.root.add(this.legendGroup);
+    this.scene.root.add(this.crosshairGroup);
+    this.scene.root.add(this.emptyGroup);
+    
+    this.legendGroup.add(this.legend.getGroup());
+    this.crosshairGroup.add(this.crosshair.getGroup());
+
+    // DOM proxy for the legend — allows external CSS/DOM targeting while
+    // the legend itself is rendered to the canvas for performance.
+    this.legendProxy = document.createElement('div');
+    this.legendProxy.className = 'radiant-chart-legend';
+    this.legendProxy.style.position = 'absolute';
+    this.legendProxy.style.pointerEvents = 'none';
+    this.legendProxy.style.display = 'none';
+    this.container.appendChild(this.legendProxy);
+
+    this.setupInteractivity();
+    this.startLoop();
+
+    this.resizeObserver = new ResizeObserver(entries => {
+      for (const e of entries) {
+        if (e.contentRect.width > 0 && e.contentRect.height > 0) {
+          this.scene.resize();
+          this.performLayout();
+          this.render();
+          this.initialized = true;
+          // Notify tooltip portal to recompute position after resize
+          this.tooltipStore.notifyResize();
+        }
+      }
+    });
+    this.resizeObserver.observe(container);
+
+    // Listen for OS-level theme toggles only when the user explicitly opts in to 'system'.
+    // _syncMediaQueryListener() handles attaching / detaching on every update() call.
+    this._syncMediaQueryListener();
+
+    this.update(options);
+  }
+
+  private startLoop() {
+    const loop = () => {
+      this.crosshair.tick();
+      this.render();
+      this.animRafId = requestAnimationFrame(loop);
+    };
+    this.animRafId = requestAnimationFrame(loop);
+  }
+
+  private stopLoop() {
+    if (this.animRafId !== null) { cancelAnimationFrame(this.animRafId); this.animRafId = null; }
+  }
+
+  private setupInteractivity() {
+    this.scene.onHover = (node, event) => {
+      if (!this.initialized) return;
+
+      if (node === null) {
+        this.tooltipStore.deactivate();
+        this.crosshair.hide();
+        this.crosshair.hideSeriesSnaps();
+        this.hoveredSeriesId = null;
+        this.series.forEach(s => { s.getGroup().opacity = 1; });
+        return;
+      }
+
+      const rect  = this.container.getBoundingClientRect();
+      const mx    = event.clientX - rect.left;
+      const my    = event.clientY - rect.top;
+      const theme = this.themeManager.theme;
+      const sr    = this.seriesRect;
+      const palette = theme.palette;
+
+      // Snap-to-data crosshair
+      if (this.isCartesian && mx >= sr.x && mx <= sr.x + sr.width && my >= sr.y && my <= sr.y + sr.height) {
+        const xOpt = this.options.series[0]?.xKey;
+        this.crosshair.show(
+          mx, my, sr, theme,
+          xOpt ? (this.categoryScale as BandScale) : undefined,
+          xOpt ? this.options.data : undefined,
+          xOpt
+        );
+      } else {
+        this.crosshair.hide();
+      }
+
+      if (this.options.tooltip?.enabled !== false) {
+        if (this.isCartesian && mx >= sr.x && mx <= sr.x + sr.width && my >= sr.y && my <= sr.y + sr.height) {
+          // Emit raw hover data for external tooltip implementations
+          this.tooltipStore.activate(
+            [],
+            { x: event.clientX, y: event.clientY },
+            { x: event.clientX, y: event.clientY },
+            { x: mx, y: my },
+            null,
+          );
+        } else if (node?.datum && !this.isCartesian) {
+          this.tooltipStore.activate(
+            [],
+            { x: event.clientX, y: event.clientY },
+            { x: event.clientX, y: event.clientY },
+            { x: mx, y: my },
+            null,
+          );
+        } else {
+          this.tooltipStore.deactivate();
+          this.crosshair.hide();
+          this.crosshair.hideSeriesSnaps();
+        }
+      }
+
+      // Focus dimming
+      const seriesId = node?.seriesId ?? null;
+      if (node?.datum && seriesId !== this.hoveredSeriesId) {
+        this.hoveredSeriesId = seriesId;
+        this.series.forEach((s, i) => {
+          const id = this.options.series[i]?.yKey ?? this.options.series[i]?.angleKey ?? `s${i}`;
+          s.getGroup().opacity = (id === seriesId || this.series.length === 1) ? 1 : 0.15;
+        });
+      } else if (!node?.datum && this.hoveredSeriesId !== null) {
+        this.hoveredSeriesId = null;
+        this.series.forEach(s => { s.getGroup().opacity = 1; });
+      }
+    };
+
+    // ── Click handler for legend toggle ────────────────────────────────
+    this.scene.onClick = (node, _event) => {
+      if (!node) return;
+
+      // Walk up the scene graph and check if the clicked node (or any
+      // ancestor) lives inside the legendGroup.  If it does, the first
+      // non-empty seriesId we encounter on the way up is the toggle target.
+      let current = node;
+      let seriesId: string | null = null;
+      let insideLegend = false;
+
+      while (current) {
+        if (current.seriesId && !seriesId) {
+          seriesId = current.seriesId;
+        }
+        if (current === this.legendGroup || current === this.legend.getGroup()) {
+          insideLegend = true;
+          break;
+        }
+        current = current.parent;
+      }
+
+      // ── User-supplied node click listener ─────────────────────────────────
+      // Fires for any clicked data node outside the legend that carries a
+      // datum payload — bars, markers, sectors, tiles, etc. The seriesId is
+      // resolved by walking up the scene graph above.
+      if (!insideLegend && node.datum && this.options.listeners?.nodeClick) {
+        const seriesOpt = this.options.series.find(
+          so => (so.yKey ?? so.angleKey ?? '') === seriesId
+        );
+        this.options.listeners.nodeClick({
+          seriesId: seriesId ?? '',
+          datum: node.datum,
+          xKey: seriesOpt?.xKey,
+          yKey: seriesOpt?.yKey,
+          type: seriesOpt?.type,
+        });
+      }
+
+      if (!insideLegend || !seriesId) return;
+
+      // ── Pagination arrows ──────────────────────────────────────────────────
+      if (seriesId === '__legend_prev__' || seriesId === '__legend_next__') {
+        this.legend.paginate(seriesId === '__legend_next__' ? 1 : -1);
+        this.performLayout();
+        this.render();
+        return;
+      }
+
+      // ── Series toggle ──────────────────────────────────────────────────────
+      const idx = this.hiddenSeries.indexOf(seriesId);
+      if (idx >= 0) {
+        this.hiddenSeries.splice(idx, 1);
+      } else {
+        this.hiddenSeries.push(seriesId);
+      }
+
+      // ── User-supplied legend item click listener ──────────────────────────
+      this.options.legend?.listeners?.legendItemClick?.({
+        seriesId,
+        visible: !this.hiddenSeries.includes(seriesId),
+      });
+
+      // Sync state to the Legend renderer and re-process everything so the
+      // value-scale domain is recalculated without the hidden series.
+      this.legend.setHiddenSeries([...this.hiddenSeries]);
+      this.processData();
+      this.performLayout();
+      this.render();
+    };
+
+    // ── Double-click handler ──────────────────────────────────────────────
+    // Two responsibilities:
+    //  1. Inside the legend → isolate the dbl-clicked series (hide all others;
+    //     if already isolated, restore the full set). Fires the user-supplied
+    //     legendItemDoubleClick callback.
+    //  2. Outside the legend on a data node → fire nodeDoubleClick.
+    this.scene.onDblClick = (node, _event) => {
+      if (!node) return;
+
+      let current = node;
+      let seriesId: string | null = null;
+      let insideLegend = false;
+      while (current) {
+        if (current.seriesId && !seriesId) seriesId = current.seriesId;
+        if (current === this.legendGroup || current === this.legend.getGroup()) {
+          insideLegend = true;
+          break;
+        }
+        current = current.parent;
+      }
+
+      if (insideLegend) {
+        if (!seriesId || seriesId === '__legend_prev__' || seriesId === '__legend_next__') return;
+
+        // Build the full set of series IDs the same way the legend item builder did.
+        const allIds = this.options.series.map((s, i) => s.yKey ?? s.angleKey ?? `s${i}`);
+        const others = allIds.filter(id => id !== seriesId);
+        // Already isolated when every "other" series is currently hidden.
+        const isIsolated = others.every(id => this.hiddenSeries.includes(id));
+
+        if (isIsolated) {
+          this.hiddenSeries = []; // restore everything
+        } else {
+          this.hiddenSeries = others; // hide every other series
+        }
+
+        this.options.legend?.listeners?.legendItemDoubleClick?.({
+          seriesId,
+          isolated: !isIsolated,
+        });
+
+        this.legend.setHiddenSeries([...this.hiddenSeries]);
+        this.processData();
+        this.performLayout();
+        this.render();
+        return;
+      }
+
+      if (node.datum && this.options.listeners?.nodeDoubleClick) {
+        const seriesOpt = this.options.series.find(
+          so => (so.yKey ?? so.angleKey ?? '') === seriesId
+        );
+        this.options.listeners.nodeDoubleClick({
+          seriesId: seriesId ?? '',
+          datum: node.datum,
+          xKey: seriesOpt?.xKey,
+          yKey: seriesOpt?.yKey,
+          type: seriesOpt?.type,
+        });
+      }
+    };
+  }
+
+  /** Public accessor for the tooltip state store (consumed by React wrappers). */
+  getTooltipStore(): TooltipStore { return this.tooltipStore; }
+
+  /**
+   * Keyboard navigation handler for tooltip accessibility.
+   * ArrowLeft/Right cycle through X-axis data points.
+   */
+  private _handleKeyboard(e: KeyboardEvent) {
+    if (!this.initialized || !this.isCartesian) return;
+    const data = this.options.data;
+    if (!data?.length) return;
+
+    const xKey = this.options.series[0]?.xKey;
+    if (!xKey) return;
+
+    if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const delta = e.key === 'ArrowRight' ? 1 : -1;
+      this._kbIndex = Math.max(0, Math.min(data.length - 1, this._kbIndex + delta));
+
+      const sr = this.seriesRect;
+      const theme = this.themeManager.theme;
+      const palette = theme.palette;
+
+      this.crosshair.show(
+        sr.x + sr.width / 2, sr.y + sr.height / 2, sr, theme,
+        this.categoryScale instanceof BandScale ? this.categoryScale : undefined,
+        data, xKey,
+      );
+      this.options.onFocusChange?.(this._kbIndex);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      this.tooltipStore.deactivate();
+      this.crosshair.hide();
+      this.crosshair.hideSeriesSnaps();
+      this._kbIndex = -1;
+      this.options.onFocusChange?.(null);
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      this._kbIndex = 0;
+      // Re-trigger via synthetic ArrowRight at index 0
+      this._handleKeyboard(new KeyboardEvent('keydown', { key: 'ArrowLeft' }));
+      this._kbIndex = 0;
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      this._kbIndex = data.length - 1;
+      this._handleKeyboard(new KeyboardEvent('keydown', { key: 'ArrowRight' }));
+      this._kbIndex = data.length - 1;
+    }
+  }
+
+  update(options: RadiantChartOptions) {
+    const dataChanged = options.data !== this.lastDataRef;
+    this.lastDataRef = options.data;
+
+    this.options = options;
+    if (options.theme) this.themeManager.setTheme(options.theme as ThemeOption);
+    const themeBackground = this.themeManager.theme.backgroundColor;
+    this.container.style.backgroundColor = themeBackground;
+    this.scene.backgroundColor = themeBackground;
+    this.container.style.transition = 'background-color 0.3s';
+    this.crosshair.updateOptions(options.crosshair ?? {});
+    this.tooltipStore.setOptions(options.tooltip ?? {});
+    this._syncMediaQueryListener();
+    this.processData();
+    this.performLayout(dataChanged);
+    this.render();
+  }
+
+  /**
+   * Attaches the `prefers-color-scheme` listener when theme is 'system', or
+   * removes it when the theme has changed away from 'system'.  Safe to call
+   * repeatedly — it is idempotent (won't double-attach).
+   */
+  private _syncMediaQueryListener() {
+    if (typeof window === 'undefined') return;
+
+    const needsListener = this.options.theme === 'system';
+
+    if (needsListener && !this.mediaQuery) {
+      this.mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      this.mediaQuery.addEventListener('change', this._onSystemThemeChange);
+    } else if (!needsListener && this.mediaQuery) {
+      this.mediaQuery.removeEventListener('change', this._onSystemThemeChange);
+      this.mediaQuery = null;
+    }
+  }
+
+  private processData() {
+    // Normalize series types to avoid fallback rendering
+    const series = (this.options.series || []).map(s => {
+      const type = (s.type || '').toLowerCase().replace(/[-_ ]/g, '');
+      let yAxisId = s.yAxisId;
+      if (!yAxisId && type === 'line' && s.yKey && /percent|cumulative|pareto/i.test(s.yKey)) {
+        yAxisId = 'right';
+      }
+      return { ...s, type, yAxisId };
+    });
+    this.options = { ...this.options, series: series as any };
+    const { data } = this.options;
+    this.emptyGroup.clear();
+
+    if (!data?.length || !series?.length) {
+      this.isCartesian = false;
+      this.initialized = true;
+      this.axesGroup.visible = false;
+      this.seriesGroup.clear();
+      // Hide the legend when there is no data — prevents stale legend items
+      // from persisting after a data clear (e.g. Interactive Editor removes
+      // the `data` key and clicks "Run").
+      this.legendGroup.visible = false;
+      this.legend.getGroup().visible = false;
+      this.series = [];
+      this.seriesInstances.clear();
+      return;
+    }
+
+    this.isCartesian = series.every(s => !NON_CARTESIAN.has(s.type ?? ''));
+
+    if (this.isCartesian) {
+      const xKeys = new Set<any>();
+      this.minY = Infinity;
+      this.maxY = -Infinity;
+
+      const isContinuousX = series.some(s => s.type === 'scatter');
+      if (isContinuousX) {
+        this.categoryScale = new LinearScale();
+        this.valueScale = new LinearScale();
+      } else {
+        this.categoryScale = new BandScale();
+        this.valueScale = new LinearScale();
+      }
+
+      const stackedBars  = series.filter(s => s.type === 'bar' && (s.stacked || s.normalized));
+      const stackedAreas = series.filter(s => s.type === 'area' && (s.stacked || s.normalized));
+      const colTotals    = data.map(d => stackedBars.reduce((t, s) => t + (d[s.yKey!] ?? 0), 0));
+      const areaColTotals = data.map(d => stackedAreas.reduce((t, s) => t + (d[s.yKey!] ?? 0), 0));
+
+      if (stackedBars.length > 0) {
+        if (series.some(s => s.type === 'bar' && s.normalized)) this.maxY = 100;
+        else {
+          data.forEach((_, i) => { this.maxY = Math.max(this.maxY, colTotals[i]); });
+        }
+      }
+      if (stackedAreas.length > 0) {
+        if (series.some(s => s.type === 'area' && s.normalized)) {
+          this.maxY = Math.max(this.maxY, 100);
+        } else {
+          data.forEach((_, i) => { this.maxY = Math.max(this.maxY, areaColTotals[i]); });
+        }
+      }
+
+      const xKeyFields = new Set<string>();
+      const yKeyFields = new Set<string>();
+      series.forEach(s => {
+        if (s.xKey) xKeyFields.add(s.xKey);
+      });
+
+      series.forEach((s, sIdx) => {
+        const seriesId = s.yKey ?? s.angleKey ?? `s${sIdx}`;
+        const isHidden = this.hiddenSeries.includes(seriesId);
+        if (!isHidden && s.yKey && !s.stacked && !s.normalized && s.type !== 'histogram') {
+          yKeyFields.add(s.yKey);
+        }
+      });
+
+      data.forEach(d => {
+        xKeyFields.forEach(k => { if (d[k] !== undefined) xKeys.add(d[k]); });
+        yKeyFields.forEach(k => {
+          const v = d[k];
+          if (v > this.maxY) this.maxY = v;
+          if (v < this.minY) this.minY = v;
+        });
+      });
+
+      if (this.categoryScale instanceof BandScale) {
+        this.categoryScale.domain = Array.from(xKeys);
+      } else {
+        const numericX = Array.from(xKeys).map(v => typeof v === 'number' ? v : Number(new Date(v))).filter(v => !isNaN(v));
+        if (numericX.length > 0) {
+          const minX = Math.min(...numericX);
+          const maxX = Math.max(...numericX);
+          this.categoryScale.domain = [minX, maxX];
+        }
+      }
+
+      if (this.valueScale instanceof BandScale) {
+        const yKeys = new Set<any>();
+        series.forEach(s => {
+          if (s.yKey) data.forEach(d => yKeys.add(d[s.yKey!]));
+        });
+        this.valueScale.domain = Array.from(yKeys);
+      } else {
+        const mustStartAtZero = series.some(s => s.type === 'bar' || s.type === 'area');
+        const dMin = mustStartAtZero ? Math.min(0, this.minY) : this.minY;
+        const dMax = this.maxY === -Infinity ? 100 : this.maxY;
+        this.valueScale.domain = [dMin * (dMin < 0 ? 1.1 : 0.98), dMax * 1.05];
+      }
+      const hasRightAxis = series.some(s => s.yAxisId === 'right');
+      if (hasRightAxis) {
+        let minYRight = 0, maxYRight = -Infinity;
+        series.forEach(s => {
+          if (s.yAxisId === 'right' && s.yKey) {
+            data.forEach(d => {
+              const v = d[s.yKey!];
+              if (v > maxYRight) maxYRight = v;
+              if (v < minYRight) minYRight = v;
+            });
+          }
+        });
+        this.valueScaleRight.domain = [minYRight, (maxYRight === -Infinity ? 100 : maxYRight) * 1.12];
+      }
+
+      const isH = series.some(s =>
+        (s.type === 'bar' && s.direction === 'horizontal')
+      );
+      const theme = this.themeManager.theme;
+      this.axesGroup.clear();
+
+      if (!isH) {
+        this.xAxis = new CartesianAxis(this.categoryScale, { 
+          position: 'bottom',
+          fontSize: this.options.xAxisFontSize,
+          fontFamily: this.options.xAxisFontFamily,
+          rotation: this.options.xAxisRotation,
+          labelAlignment: this.options.xAxisLabelAlignment
+        });
+        this.yAxis = new CartesianAxis(this.valueScale, { 
+          position: 'left',
+          fontSize: this.options.yAxisFontSize,
+          fontFamily: this.options.yAxisFontFamily,
+          rotation: this.options.yAxisRotation,
+          labelAlignment: this.options.yAxisLabelAlignment
+        });
+        if (series.some(s => s.yAxisId === 'right')) {
+          this.yAxisRight = new CartesianAxis(this.valueScaleRight, {
+            position: 'right',
+            fontSize: this.options.yAxisRightFontSize ?? this.options.yAxisFontSize,
+            fontFamily: this.options.yAxisRightFontFamily ?? this.options.yAxisFontFamily,
+            rotation: this.options.yAxisRightRotation ?? this.options.yAxisRotation,
+            labelAlignment: this.options.yAxisRightLabelAlignment ?? this.options.yAxisLabelAlignment
+          });
+        } else {
+          this.yAxisRight = undefined;
+        }
+      } else {
+        this.xAxis = new CartesianAxis(this.valueScale, { 
+          position: 'bottom',
+          fontSize: this.options.xAxisFontSize,
+          fontFamily: this.options.xAxisFontFamily,
+          rotation: this.options.xAxisRotation,
+          labelAlignment: this.options.xAxisLabelAlignment
+        });
+        this.yAxis = new CartesianAxis(this.categoryScale, { 
+          position: 'left',
+          fontSize: this.options.yAxisFontSize,
+          fontFamily: this.options.yAxisFontFamily,
+          rotation: this.options.yAxisRotation,
+          labelAlignment: this.options.yAxisLabelAlignment
+        });
+        this.yAxisRight = undefined;
+      }
+      this.xAxis.setTheme(theme); this.yAxis.setTheme(theme);
+      this.axesGroup.add(this.xAxis.getGroup());
+      this.axesGroup.add(this.yAxis.getGroup());
+      if (this.yAxisRight) {
+        this.yAxisRight.setTheme(theme);
+        this.axesGroup.add(this.yAxisRight.getGroup());
+      }
+      this.axesGroup.visible = true;
+    } else {
+      this.axesGroup.visible = false;
+    }
+  }
+
+  private createSeriesInstance(s: any, i: number): any {
+    const palette = this.themeManager.theme.palette;
+    const color = s.fill ?? palette[i % palette.length];
+    const animation = { ...this.options.animation, ...s.animation };
+    const base = { ...s, fill: color, stroke: s.stroke ?? color, animation };
+
+    switch (s.type) {
+      case 'bar':     return new BarSeries(base as any);
+      case 'line':    return new LineSeries(base as any);
+      case 'pie':     return new PieSeries({ ...s, fills: s.fills ?? palette } as any);
+      case 'donut':   return new PieSeries({ ...s, fills: s.fills ?? palette, innerRadius: s.innerRadius ?? 0.6 } as any);
+      case 'area':    return new AreaSeries(base as any);
+      case 'scatter': return new ScatterSeries({ ...base, jitter: s.jitter } as any);
+      default:        return null;
+    }
+  }
+
+  private renderEmpty() {
+    const { width, height } = this.container.getBoundingClientRect();
+    if (!width || !height) return;
+    const theme = this.themeManager.theme;
+
+    const icon = new Text();
+    icon.text = '⬜';
+    icon.x = width / 2; icon.y = height / 2 - 20;
+    icon.fontSize = 26; icon.fill = theme.axisColor;
+    icon.textAlign = 'center'; icon.textBaseline = 'middle';
+    this.emptyGroup.add(icon);
+
+    const msg = new Text();
+    msg.text = 'No data available';
+    msg.x = width / 2; msg.y = height / 2 + 16;
+    msg.fontSize = 13; msg.fill = theme.subtextColor;
+    msg.fontFamily = theme.fontFamily;
+    msg.textAlign = 'center'; msg.textBaseline = 'middle';
+    this.emptyGroup.add(msg);
+  }
+
+  private performLayout(shouldAnimate: boolean = false) {
+    const { width, height } = this.container.getBoundingClientRect();
+    if (!width || !height) return;
+
+    this.axesGroup.opacity = 1;
+    this.seriesGroup.opacity = 1;
+
+    // Default padding is intentionally minimal so charts fill their container.
+    // When the user sets padding these defaults are replaced entirely.
+    const pad = this.options.padding ?? { top: 4, right: 4, bottom: 0, left: 4 };
+    let top    = pad.top    ?? 4;
+    let bottom = height - (pad.bottom ?? 0);
+    let left   = pad.left   ?? 4;
+    let right  = width  - (pad.right  ?? 4);
+    const innerPad = (pad as any).inner ?? 0;
+
+    const theme = this.themeManager.theme;
+
+    // Title / subtitle
+    this.titleGroup.clear(); this.subtitleGroup.clear();
+    if (this.options.title) {
+      const t = new Text();
+      t.text = this.options.title.text; t.fontSize = this.options.title.fontSize ?? 16;
+      t.fontWeight = '600'; t.fill = theme.textColor; t.fontFamily = theme.fontFamily;
+      t.x = width / 2; t.y = top + t.fontSize; t.textAlign = 'center';
+      this.titleGroup.add(t);
+      top += t.fontSize + 8;
+    }
+    if (this.options.subtitle) {
+      const s = new Text();
+      s.text = this.options.subtitle.text; s.fontSize = this.options.subtitle.fontSize ?? 12;
+      s.fill = theme.subtextColor; s.fontFamily = theme.fontFamily;
+      s.x = width / 2; s.y = top + s.fontSize; s.textAlign = 'center';
+      this.subtitleGroup.add(s);
+      top += s.fontSize + 6;
+    }
+
+    // Legend
+    const legendOpt = this.options.legend;
+    const showLegend = legendOpt?.enabled !== false && this.options.series.length > 1;
+
+
+    if (showLegend) {
+      let items: LegendItem[] = [];
+      // Chart types that live in the non-Cartesian performLayout branch and
+      // therefore store their series instance under the `${type}-${i}-null`
+      // key. When we have to create an instance ahead of the layout pass to
+      // build the legend, we cache it under the same key so the real render
+      // re-uses it instead of throwing away our temp and losing its config.
+      const NON_CARTESIAN_TYPES = new Set(NON_CARTESIAN);
+
+      this.options.series.forEach((sOpt, i) => {
+        // Try to find an existing instance to delegate legend item generation
+        let instance: any = null;
+        for (const [key, inst] of this.seriesInstances.entries()) {
+          if (key.startsWith(`${sOpt.type}-${i}-`)) {
+            instance = inst;
+            break;
+          }
+        }
+
+        // If no instance exists (first render), create one and cache it so the
+        // downstream performLayout pass finds the same object. Previously the
+        // temp instance was discarded, which — combined with performLayout
+        // re-creating its own instance — could leave the legend items out of
+        // sync with the series config on the first paint.
+        if (!instance) {
+          instance = this.createSeriesInstance(sOpt, i);
+          if (instance && NON_CARTESIAN_TYPES.has(sOpt.type as string)) {
+            this.seriesInstances.set(`${sOpt.type}-${i}-null`, instance);
+          }
+        }
+
+        if (instance && typeof instance.getLegendData === 'function') {
+          const legendItems = instance.getLegendData(theme, this.options.data);
+          if (Array.isArray(legendItems) && legendItems.length > 0) {
+            items.push(...legendItems);
+          } else {
+            items.push({
+              id:         sOpt.yKey ?? sOpt.angleKey ?? `s${i}`,
+              label:      sOpt.title ?? sOpt.yKey ?? sOpt.angleKey ?? `Series ${i + 1}`,
+              fill:       sOpt.fill ?? theme.palette[i % theme.palette.length],
+              markerType: (sOpt.type === 'line' || sOpt.type === 'scatter') ? 'circle' : 'square',
+            });
+          }
+        } else {
+          items.push({
+            id:         sOpt.yKey ?? sOpt.angleKey ?? `s${i}`,
+            label:      sOpt.title ?? sOpt.yKey ?? sOpt.angleKey ?? `Series ${i + 1}`,
+            fill:       sOpt.fill ?? theme.palette[i % theme.palette.length],
+            markerType: (sOpt.type === 'line' || sOpt.type === 'scatter') ? 'circle' : 'square',
+          });
+        }
+      });
+
+      this.legend.setHiddenSeries([...this.hiddenSeries]);
+
+      const position = legendOpt?.position ?? 'bottom';
+      const isVertical = position === 'left' || position === 'right';
+      // For vertical legend, limit width to 30% of container or 200px.
+      const legendMaxWidth = isVertical ? Math.min(width * 0.3, 200) : width;
+
+      this.legend.update(items, theme, legendMaxWidth, height, position);
+      // Ensure the legend layer is visible — a previous pass may have hidden
+      // it if it was empty, and opacity defaults can drift from context.
+      this.legendGroup.visible = true;
+      this.legendGroup.opacity = 1;
+      const legendGroupNode = this.legend.getGroup();
+      legendGroupNode.visible = true;
+      legendGroupNode.opacity = 1;
+
+      const lb = this.legend.getBBox();
+      if (lb.width > 0 && lb.height > 0) {
+        let lx = 0, ly = 0;
+        if (position === 'bottom') {
+          lx = (width - lb.width) / 2 - lb.x;
+          ly = bottom - lb.height - lb.y;
+          bottom -= lb.height + 10;
+        } else if (position === 'top') {
+          lx = (width - lb.width) / 2 - lb.x;
+          ly = top - lb.y;
+          top += lb.height + 10;
+        } else if (position === 'left') {
+          lx = left - lb.x;
+          ly = (height - lb.height) / 2 - lb.y;
+          left += lb.width + 10;
+        } else if (position === 'right') {
+          lx = right - lb.width - lb.x;
+          ly = (height - lb.height) / 2 - lb.y;
+          right -= lb.width + 10;
+        }
+
+        legendGroupNode.translation = { x: lx, y: ly };
+
+        // Update DOM proxy — allows external CSS/DOM targeting (e.g. for
+        // accessibility tools or CSS-based layout verification) while the
+        // legend itself remains canvas-rendered for high performance.
+        if (this.legendProxy) {
+          this.legendProxy.style.display = 'block';
+          this.legendProxy.style.left = `${lx + lb.x}px`;
+          this.legendProxy.style.top = `${ly + lb.y}px`;
+          this.legendProxy.style.width = `${lb.width}px`;
+          this.legendProxy.style.height = `${lb.height}px`;
+        }
+      } else {
+        // Fallback for empty/zero bbox
+        if (position === 'bottom') {
+          legendGroupNode.translation = { x: 0, y: bottom - 24 };
+          bottom -= 24;
+        } else if (position === 'top') {
+          legendGroupNode.translation = { x: 0, y: top };
+          top += 24;
+        }
+        if (this.legendProxy) this.legendProxy.style.display = 'none';
+      }
+    } else {
+      this.legendGroup.visible = false;
+      if (this.legendProxy) this.legendProxy.style.display = 'none';
+    }
+
+    // Axis visibility — default true; false collapses the reserved space to 0
+    // so the plot fills the full edge with no dead zone.
+    const showXAxis = this.options.showXAxis !== false;
+    const showYAxis = this.options.showYAxis !== false;
+    const showYAxisRight = this.options.showYAxisRight !== false;
+
+    // Dynamic axis sizing — ask each axis how much space its labels actually need.
+    const ctx = this.scene.getContext();
+    let yAxisW = 0;
+    let yAxisRightW = 0;
+    let xAxisH = 0;
+    let topAxisH = 0;
+    const Y_LABEL_DATA_GAP = 12;
+
+    if (this.isCartesian && this.yAxis && showYAxis) {
+      this.yAxis.setTheme(theme);
+      this.yAxis.updateOptions({
+        fontSize: this.options.yAxisFontSize,
+        fontFamily: this.options.yAxisFontFamily,
+        rotation: this.options.yAxisRotation,
+        labelAlignment: this.options.yAxisLabelAlignment
+      });
+      yAxisW = this.yAxis.getRequiredSpace(ctx).size + Y_LABEL_DATA_GAP;
+      // Cap Y-axis width to 40% of container to prevent pushing the chart to oblivion on mobile
+      const maxYWidth = width * 0.4;
+      if (yAxisW > maxYWidth) {
+        yAxisW = maxYWidth;
+        this.yAxis.setLayoutMaxWidth(yAxisW - Y_LABEL_DATA_GAP);
+      } else {
+        this.yAxis.setLayoutMaxWidth(0); // clear any previous cap
+      }
+    }
+    if (this.isCartesian && this.yAxisRight && showYAxisRight) {
+      this.yAxisRight.setTheme(theme);
+      this.yAxisRight.updateOptions({
+        fontSize: this.options.yAxisRightFontSize ?? this.options.yAxisFontSize,
+        fontFamily: this.options.yAxisRightFontFamily ?? this.options.yAxisFontFamily,
+        rotation: this.options.yAxisRightRotation ?? this.options.yAxisRotation,
+        labelAlignment: this.options.yAxisRightLabelAlignment ?? this.options.yAxisLabelAlignment
+      });
+      yAxisRightW = this.yAxisRight.getRequiredSpace(ctx).size + Y_LABEL_DATA_GAP;
+    }
+    if (this.isCartesian && this.xAxis && showXAxis) {
+      this.xAxis.setTheme(theme);
+      this.xAxis.updateOptions({
+        fontSize: this.options.xAxisFontSize,
+        fontFamily: this.options.xAxisFontFamily,
+        rotation: this.options.xAxisRotation,
+        labelAlignment: this.options.xAxisLabelAlignment
+      });
+      xAxisH = this.xAxis.getRequiredSpace(ctx).size;
+    }
+
+    this.seriesRect = {
+      x:      left + yAxisW,
+      y:      top + topAxisH,
+      width:  right - left - yAxisW - yAxisRightW,
+      height: bottom - top - xAxisH - topAxisH,
+    };
+    const sr = this.seriesRect;
+
+    // Inner plot area (shrunk by innerPad)
+    const ip = {
+      x:      sr.x + innerPad,
+      y:      sr.y + innerPad,
+      width:  sr.width  - innerPad * 2,
+      height: sr.height - innerPad * 2,
+    };
+
+    if (this.isCartesian && this.xAxis && this.yAxis) {
+      this.xAxis.setTheme(theme); this.yAxis.setTheme(theme);
+
+      this.xAxis.getGroup().translation = { x: sr.x, y: sr.y + sr.height };
+      // Range the axis to include the inner padding
+      this.xAxis.update(sr.width, 0, showXAxis, innerPad);
+      this.yAxis.getGroup().translation = { x: sr.x - Y_LABEL_DATA_GAP, y: sr.y };
+      this.yAxis.update(sr.height, sr.width + Y_LABEL_DATA_GAP, showYAxis, innerPad, Y_LABEL_DATA_GAP);
+
+      if (this.yAxisRight) {
+        this.yAxisRight.getGroup().translation = { x: sr.x + sr.width + Y_LABEL_DATA_GAP, y: sr.y };
+        this.yAxisRight.update(sr.height, sr.width + Y_LABEL_DATA_GAP, showYAxisRight, innerPad);
+      }
+
+      this.seriesGroup.translation = { x: sr.x, y: sr.y };
+      this.seriesGroup.clipRect = { x: 0, y: 0, width: sr.width, height: sr.height };
+
+      this.seriesGroup.clear();
+      const usedSeries: any[] = [];
+      const fData = this.options.data;
+
+      this.options.series.forEach((sOpt, sIdx) => {
+        const sId = sOpt.yKey ?? sOpt.angleKey ?? `s${sIdx}`;
+        if (this.hiddenSeries.includes(sId)) return;
+
+        const isH = (sOpt.type === 'bar' && sOpt.direction === 'horizontal');
+        let catScale: any = isH ? this.yAxis?.scale : this.xAxis?.scale;
+        let valScale: any = sOpt.yAxisId === 'right' && this.yAxisRight ? this.yAxisRight.scale : (isH ? this.xAxis?.scale : this.yAxis?.scale);
+
+        const decimationType = sOpt.type === 'line' || sOpt.type === 'area';
+
+        const instanceKey = `${sOpt.type}-${sIdx}-null`;
+        let s = this.seriesInstances.get(instanceKey);
+        if (!s) {
+          s = this.createSeriesInstance(sOpt, sIdx);
+          if (s) this.seriesInstances.set(instanceKey, s);
+        }
+        if (!s) return;
+        usedSeries.push(s);
+
+        this.seriesGroup.add(s.getGroup());
+
+        const subRect = { x: 0, y: 0, width: sr.width, height: sr.height };
+
+        const seriesOptForUpdate: any = decimationType && fData.length > 1000
+          ? { ...(sOpt as any), marker: { ...(sOpt as any).marker, enabled: false } }
+          : (sOpt as any);
+
+        if (s instanceof BarSeries) {
+          const allBars = this.options.series.filter(so => so.type === 'bar');
+          let barOffsets: number[] | undefined;
+          let barTotals: number[] | undefined;
+
+          if (sOpt.stacked || sOpt.normalized) {
+            const allStackedBars = allBars.filter(so => so.stacked || so.normalized);
+            const myIdx = allStackedBars.indexOf(sOpt);
+            barOffsets = fData.map(d =>
+              allStackedBars.slice(0, myIdx).reduce((acc, so) => acc + (d[so.yKey!] ?? 0), 0)
+            );
+            barTotals = fData.map(d =>
+              allStackedBars.reduce((acc, so) => acc + (d[so.yKey!] ?? 0), 0)
+            );
+          }
+
+          s.update(fData, catScale as BandScale, valScale, subRect, true, sIdx, allBars.length, barOffsets, barTotals, sOpt as any);
+        } else if (s instanceof AreaSeries) {
+          let areaOffsets: number[] | undefined;
+          let areaTotals: number[] | undefined;
+          if (sOpt.stacked || sOpt.normalized) {
+            const allStackedAreas = this.options.series.filter(
+              so => so.type === 'area' && (so.stacked || so.normalized)
+            );
+            const myIdx = allStackedAreas.indexOf(sOpt);
+            areaOffsets = fData.map(d =>
+              allStackedAreas.slice(0, myIdx).reduce((acc, so) => acc + (d[so.yKey!] ?? 0), 0)
+            );
+            areaTotals = fData.map(d =>
+              allStackedAreas.reduce((acc, so) => acc + (d[so.yKey!] ?? 0), 0)
+            );
+          }
+          s.update(fData, catScale as BandScale, valScale, subRect, true, areaOffsets, seriesOptForUpdate, areaTotals);
+        } else if (
+          s instanceof LineSeries ||
+          s instanceof ScatterSeries
+        ) {
+          s.update(fData, catScale as any, valScale, subRect, true, seriesOptForUpdate);
+        }
+      });
+      this.series = usedSeries;
+    } else {
+      this.seriesGroup.translation = { x: 0, y: 0 };
+      this.seriesGroup.clipRect = { x: sr.x - innerPad, y: sr.y - innerPad, width: sr.width + innerPad * 2, height: sr.height + innerPad * 2 };
+      this.seriesGroup.clear();
+      const usedSeries: any[] = [];
+      this.options.series.forEach((sOpt, i) => {
+        // Skip hidden series in non-cartesian rendering.
+        const sId = sOpt.yKey ?? sOpt.angleKey ?? `s${i}`;
+        if (this.hiddenSeries.includes(sId)) return;
+
+        const instanceKey = `${sOpt.type}-${i}-null`;
+        let s = this.seriesInstances.get(instanceKey);
+        if (!s) {
+          s = this.createSeriesInstance(sOpt, i);
+          if (s) this.seriesInstances.set(instanceKey, s);
+        }
+        if (!s) return;
+        usedSeries.push(s);
+
+        this.seriesGroup.add(s.getGroup());
+        if (s instanceof PieSeries) {
+          s.update(this.options.data, sr, shouldAnimate, sOpt as any);
+        }
+      });
+      this.series = usedSeries;
+    }
+
+  }
+
+  private render() {
+    this.scene.render();
+  }
+
+  /**
+   * Exports the current chart as a PNG file and triggers a browser download.
+   *
+   * @param filename  Download filename. Defaults to 'chart.png'.
+   */
+  exportToPng(filename = 'chart.png') {
+    const canvas = this.scene.getCanvas();
+    const dataUrl = canvas.toDataURL('image/png');
+    const a = document.createElement('a');
+    a.href = dataUrl;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  }
+
+
+  destroy() {
+    this.stopLoop();
+    this.resizeObserver.disconnect();
+    // Clean up the OS-level color-scheme listener
+    if (this.mediaQuery) {
+      this.mediaQuery.removeEventListener('change', this._onSystemThemeChange);
+      this.mediaQuery = null;
+    }
+    this.container.removeEventListener('keydown', this._onKeyDown);
+    this.container.removeEventListener('pointerleave', this._onPointerLeave);
+    this.scene.destroy();
+    this.tooltipStore.destroy();
+    if (this.legendProxy) {
+      this.legendProxy.remove();
+      this.legendProxy = undefined;
+    }
+  }
+}