@opendata-ai/openchart-vanilla 6.25.4 → 6.27.0

package/src/renderers/axes.ts

@@ -10,6 +10,25 @@ import {
 } from '@opendata-ai/openchart-core';
 import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
+function appendCompoundLabel(
+  parent: SVGElement,
+  primaryText: string,
+  subtitle: string,
+  fontWeight: number,
+): void {
+  const primarySpan = createSVGElement('tspan');
+  primarySpan.setAttribute('font-weight', String(fontWeight));
+  primarySpan.textContent = primaryText;
+  parent.appendChild(primarySpan);
+
+  const subtitleSpan = createSVGElement('tspan');
+  subtitleSpan.setAttribute('dx', '0.5em');
+  subtitleSpan.textContent = subtitle;
+  subtitleSpan.setAttribute('font-weight', '400');
+  subtitleSpan.setAttribute('fill-opacity', '0.6');
+  parent.appendChild(subtitleSpan);
+}
+
 function renderAxis(
   parent: SVGElement,
   axis: AxisLayout,
@@ -85,30 +104,72 @@ function renderAxis(
         const availableWidth = area.x - TICK_LABEL_OFFSET;
         const fontSize = axis.tickLabelStyle.fontSize;
         const fontWeight = axis.tickLabelStyle.fontWeight;
-        const fullWidth = estimateTextWidth(tick.label, fontSize, fontWeight);
-        if (fullWidth > availableWidth && availableWidth > 20) {
-          const ellipsis = '…';
-          const ellipsisWidth = estimateTextWidth(ellipsis, fontSize, fontWeight);
-          let lo = 0;
-          let hi = tick.label.length;
-          while (lo < hi) {
-            const mid = (lo + hi + 1) >>> 1;
-            const candidate = tick.label.slice(0, mid);
-            if (
-              estimateTextWidth(candidate, fontSize, fontWeight) + ellipsisWidth <=
-              availableWidth
-            ) {
-              lo = mid;
+
+        if (tick.subtitle) {
+          // Compound label: primary + gap + subtitle via tspan elements
+          const gapWidth = fontSize * 0.5;
+          const subtitleWidth = estimateTextWidth(tick.subtitle, fontSize, fontWeight);
+          const primaryWidth = estimateTextWidth(tick.label, fontSize, fontWeight);
+          const totalWidth = primaryWidth + gapWidth + subtitleWidth;
+
+          if (totalWidth > availableWidth && availableWidth > 20) {
+            const ellipsis = '…';
+            const ellipsisWidth = estimateTextWidth(ellipsis, fontSize, fontWeight);
+            const budgetForPrimary = availableWidth - gapWidth - subtitleWidth - ellipsisWidth;
+
+            let primaryText = tick.label;
+            if (budgetForPrimary > 0) {
+              let lo = 0;
+              let hi = tick.label.length;
+              while (lo < hi) {
+                const mid = (lo + hi + 1) >>> 1;
+                const candidate = tick.label.slice(0, mid);
+                if (estimateTextWidth(candidate, fontSize, fontWeight) <= budgetForPrimary) {
+                  lo = mid;
+                } else {
+                  hi = mid - 1;
+                }
+              }
+              primaryText = lo > 0 ? tick.label.slice(0, lo).trimEnd() + ellipsis : ellipsis;
             } else {
-              hi = mid - 1;
+              primaryText = ellipsis;
             }
+
+            appendCompoundLabel(label, primaryText, tick.subtitle, fontWeight);
+
+            const titleEl = createSVGElement('title');
+            titleEl.textContent = `${tick.label}  ${tick.subtitle}`;
+            label.appendChild(titleEl);
+          } else {
+            appendCompoundLabel(label, tick.label, tick.subtitle, fontWeight);
           }
-          label.textContent = lo > 0 ? tick.label.slice(0, lo).trimEnd() + ellipsis : ellipsis;
-          const titleEl = createSVGElement('title');
-          titleEl.textContent = tick.label;
-          label.appendChild(titleEl);
         } else {
-          label.textContent = tick.label;
+          // Plain label (no subtitle)
+          const fullWidth = estimateTextWidth(tick.label, fontSize, fontWeight);
+          if (fullWidth > availableWidth && availableWidth > 20) {
+            const ellipsis = '…';
+            const ellipsisWidth = estimateTextWidth(ellipsis, fontSize, fontWeight);
+            let lo = 0;
+            let hi = tick.label.length;
+            while (lo < hi) {
+              const mid = (lo + hi + 1) >>> 1;
+              const candidate = tick.label.slice(0, mid);
+              if (
+                estimateTextWidth(candidate, fontSize, fontWeight) + ellipsisWidth <=
+                availableWidth
+              ) {
+                lo = mid;
+              } else {
+                hi = mid - 1;
+              }
+            }
+            label.textContent = lo > 0 ? tick.label.slice(0, lo).trimEnd() + ellipsis : ellipsis;
+            const titleEl = createSVGElement('title');
+            titleEl.textContent = tick.label;
+            label.appendChild(titleEl);
+          } else {
+            label.textContent = tick.label;
+          }
         }
       } else {
         label.textContent = tick.label;

package/src/renderers/legend.ts

@@ -2,12 +2,16 @@
  * Legend rendering: swatches + labels with wrap/overflow handling.
  */
 
-import type { LegendLayout } from '@opendata-ai/openchart-core';
+import type { CategoricalLegendLayout, LegendLayout } from '@opendata-ai/openchart-core';
 import { estimateTextWidth } from '@opendata-ai/openchart-core';
 import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
+function isCategorical(legend: LegendLayout): legend is CategoricalLegendLayout {
+  return !legend.type || legend.type === 'categorical';
+}
+
 export function renderLegend(parent: SVGElement, legend: LegendLayout): void {
-  if (legend.entries.length === 0) return;
+  if (!isCategorical(legend) || legend.entries.length === 0) return;
 
   const g = createSVGElement('g');
   g.setAttribute('class', 'oc-legend');

package/src/sankey-renderer.ts

@@ -7,6 +7,7 @@
  */
 
 import type {
+  CategoricalLegendLayout,
   LegendLayout,
   MeasureTextFn,
   ResolvedAnimation,
@@ -230,8 +231,9 @@ function renderBrand(parent: SVGElement, layout: SankeyLayout): void {
 // Legend rendering
 // ---------------------------------------------------------------------------
 
-function renderLegend(parent: SVGElement, legend: LegendLayout): void {
-  if (legend.entries.length === 0) return;
+function renderLegend(parent: SVGElement, legendLayout: LegendLayout): void {
+  if (!('entries' in legendLayout) || legendLayout.entries.length === 0) return;
+  const legend = legendLayout as CategoricalLegendLayout;
 
   const g = createSVGElement('g');
   g.setAttribute('class', 'oc-legend');

package/src/svg-renderer.ts

@@ -41,7 +41,7 @@ const EASE_VAR_MAP: Record<string, string> = {
 export function renderChartSVG(
   layout: ChartLayout,
   container: HTMLElement,
-  opts?: { animate?: boolean },
+  opts?: { animate?: boolean; crosshair?: boolean },
 ): SVGElement {
   const { width, height } = layout.dimensions;
   const animation = layout.animation;
@@ -64,6 +64,13 @@ export function renderChartSVG(
   svg.setAttribute('role', layout.a11y.role);
   svg.setAttribute('aria-label', layout.a11y.altText);
 
+  // Sparkline display mode: stamp a data attribute so consumers can target
+  // sparkline-specific styles. Only set the attribute in sparkline mode so
+  // regular charts keep an unchanged DOM signature.
+  if (layout.display === 'sparkline') {
+    svg.setAttribute('data-display', 'sparkline');
+  }
+
   // oc-animate must be set before the SVG enters the DOM to prevent a flash
   // of the final state. mount.ts passes animate: true only on genuine first render.
   const classes = opts?.animate ? 'oc-chart oc-animate' : 'oc-chart';
@@ -164,6 +171,26 @@ export function renderChartSVG(
       overlay.setAttribute('class', 'oc-voronoi-overlay');
       overlay.setAttribute('data-voronoi-overlay', 'true');
       clippedGroup.appendChild(overlay);
+
+      // Crosshair line: opt-in vertical line that tracks the nearest data point
+      if (opts?.crosshair) {
+        const crosshairLine = createSVGElement('line');
+        crosshairLine.setAttribute('data-crosshair', 'true');
+        crosshairLine.setAttribute('class', 'oc-crosshair');
+        setAttrs(crosshairLine, {
+          x1: 0,
+          y1: layout.area.y,
+          x2: 0,
+          y2: layout.area.y + layout.area.height,
+          stroke: layout.theme.colors.gridline,
+          'stroke-opacity': '0.5',
+          'stroke-dasharray': '4,3',
+          'stroke-width': '1',
+          'pointer-events': 'none',
+        });
+        crosshairLine.style.display = 'none';
+        clippedGroup.appendChild(crosshairLine);
+      }
     }
 
     svg.appendChild(clippedGroup);

package/src/tilemap-mount.ts

@@ -0,0 +1,394 @@
+/**
+ * TileMap mount API: the main entry point for vanilla JS tilemap usage.
+ *
+ * createTileMap() takes a container, TileMapSpec, and options, compiles the
+ * tilemap, renders it as SVG, sets up responsive resizing, tooltip interaction,
+ * and returns a TileMapInstance with update/resize/export/destroy.
+ */
+
+import type {
+  CompileOptions,
+  DarkMode,
+  ThemeConfig,
+  TileMapLayout,
+  TileMapSpec,
+} from '@opendata-ai/openchart-core';
+import { compileTileMap } from '@opendata-ai/openchart-engine';
+import { cancelAnimations, setupAnimationCleanup } from './animation';
+import {
+  exportJPG,
+  exportPNG,
+  exportSVG,
+  exportSVGWithFonts,
+  type JPGExportOptions,
+  type SVGExportOptions,
+} from './export';
+import { createMeasureText } from './measure-text';
+import { observeResize } from './resize-observer';
+import { renderTileMapSVG } from './tilemap-renderer';
+import { createTooltipManager, type TooltipManager } from './tooltip';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TileMapMountOptions {
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode setting: "auto" (system pref), "force", or "off". */
+  darkMode?: DarkMode;
+  /** Enable responsive resizing. Defaults to true. */
+  responsive?: boolean;
+  /** Show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
+  /** Show tooltips on hover. Defaults to true. */
+  tooltip?: boolean;
+  /** Callback when a tile is clicked. */
+  onTileClick?: (tile: {
+    stateCode: string;
+    stateName: string;
+    value: number | null;
+    data: Record<string, unknown>;
+  }) => void;
+  /** Callback when a tile is hovered (null on mouse leave). */
+  onTileHover?: (
+    tile: {
+      stateCode: string;
+      stateName: string;
+      value: number | null;
+      data: Record<string, unknown>;
+    } | null,
+  ) => void;
+}
+
+export interface TileMapInstance {
+  /** Re-compile and re-render with a new spec. */
+  update(spec: TileMapSpec): void;
+  /** Re-compile at current container dimensions. */
+  resize(): void;
+  /** Export the tilemap. */
+  export(
+    format: 'svg' | 'svg-with-fonts' | 'png' | 'jpg',
+    options?: JPGExportOptions | SVGExportOptions,
+  ): string | Promise<Blob> | Promise<string>;
+  /** Remove all DOM elements and disconnect observers. */
+  destroy(): void;
+  /** The current compiled layout. */
+  readonly layout: TileMapLayout;
+}
+
+// ---------------------------------------------------------------------------
+// Dark mode resolution
+// ---------------------------------------------------------------------------
+
+function resolveDarkMode(mode?: DarkMode): boolean {
+  if (mode === 'force') return true;
+  if (mode === 'off' || mode === undefined) return false;
+  if (typeof window !== 'undefined' && window.matchMedia) {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a tilemap instance from a spec and mount it into a container.
+ */
+export function createTileMap(
+  container: HTMLElement,
+  spec: TileMapSpec,
+  options?: TileMapMountOptions,
+): TileMapInstance {
+  let currentSpec = spec;
+  let currentLayout: TileMapLayout;
+  let destroyed = false;
+
+  // DOM
+  let svgElement: SVGSVGElement | null = null;
+
+  // Subsystems
+  let tooltipManager: TooltipManager | null = null;
+  let cleanupTooltipEvents: (() => void) | null = null;
+  let disconnectResize: (() => void) | null = null;
+
+  // Animation state
+  let animationCleanup: (() => void) | null = null;
+  let pendingResize = false;
+
+  const measureText = createMeasureText();
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  function getContainerDimensions(): { width: number; height: number } {
+    const rect = container.getBoundingClientRect();
+    return {
+      width: Math.max(rect.width || 600, 100),
+      height: Math.max(rect.height || 400, 100),
+    };
+  }
+
+  function compile(): TileMapLayout {
+    const { width, height } = getContainerDimensions();
+    const darkMode = resolveDarkMode(options?.darkMode);
+
+    const compileOpts: CompileOptions = {
+      width,
+      height,
+      theme: options?.theme,
+      darkMode,
+      watermark: options?.watermark,
+      measureText,
+    };
+
+    return compileTileMap(currentSpec, compileOpts);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tooltip and interaction wiring
+  // ---------------------------------------------------------------------------
+
+  function wireTooltipAndInteraction(svg: SVGSVGElement, layout: TileMapLayout): () => void {
+    const cleanups: Array<() => void> = [];
+
+    // Wire tooltip on tile elements
+    const tileElements = svg.querySelectorAll('.oc-tilemap-tile');
+    for (const el of tileElements) {
+      const stateCode = el.getAttribute('data-state');
+      if (!stateCode) continue;
+
+      const content = layout.tooltipDescriptors.get(stateCode);
+      const tile = layout.tiles.find((t) => t.stateCode === stateCode);
+
+      const handleMouseEnter = (e: Event) => {
+        const mouseEvent = e as MouseEvent;
+        if (content && tooltipManager && options?.tooltip !== false) {
+          const svgRect = svg.getBoundingClientRect();
+          const x = mouseEvent.clientX - svgRect.left;
+          const y = mouseEvent.clientY - svgRect.top;
+          tooltipManager.show(content, x, y);
+        }
+        if (tile) {
+          options?.onTileHover?.({
+            stateCode: tile.stateCode,
+            stateName: tile.data.stateName as string,
+            value: tile.value,
+            data: tile.data,
+          });
+        }
+      };
+
+      const handleMouseMove = (e: Event) => {
+        if (content && tooltipManager && options?.tooltip !== false) {
+          const mouseEvent = e as MouseEvent;
+          const svgRect = svg.getBoundingClientRect();
+          const x = mouseEvent.clientX - svgRect.left;
+          const y = mouseEvent.clientY - svgRect.top;
+          tooltipManager.show(content, x, y);
+        }
+      };
+
+      const handleMouseLeave = () => {
+        tooltipManager?.hide();
+        options?.onTileHover?.(null);
+      };
+
+      const handleClick = () => {
+        if (tile) {
+          options?.onTileClick?.({
+            stateCode: tile.stateCode,
+            stateName: tile.data.stateName as string,
+            value: tile.value,
+            data: tile.data,
+          });
+        }
+      };
+
+      el.addEventListener('mouseenter', handleMouseEnter);
+      el.addEventListener('mousemove', handleMouseMove);
+      el.addEventListener('mouseleave', handleMouseLeave);
+      el.addEventListener('click', handleClick);
+
+      cleanups.push(() => {
+        el.removeEventListener('mouseenter', handleMouseEnter);
+        el.removeEventListener('mousemove', handleMouseMove);
+        el.removeEventListener('mouseleave', handleMouseLeave);
+        el.removeEventListener('click', handleClick);
+      });
+    }
+
+    return () => {
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Render + update
+  // ---------------------------------------------------------------------------
+
+  function render(animate = false): void {
+    // Cancel running animations
+    if (animationCleanup) {
+      animationCleanup();
+      animationCleanup = null;
+    }
+
+    // Remove old SVG
+    if (svgElement) {
+      if (cleanupTooltipEvents) {
+        cleanupTooltipEvents();
+        cleanupTooltipEvents = null;
+      }
+      svgElement.remove();
+    }
+
+    // Render new SVG
+    const newSvg = renderTileMapSVG(currentLayout, { animate });
+    container.appendChild(newSvg);
+    svgElement = newSvg;
+
+    // Wire interactions
+    cleanupTooltipEvents = wireTooltipAndInteraction(newSvg, currentLayout);
+
+    // Setup tooltips if enabled
+    if (options?.tooltip !== false) {
+      if (!tooltipManager) {
+        tooltipManager = createTooltipManager(container);
+      }
+    }
+
+    // Setup animation cleanup
+    if (currentLayout.animation?.enabled) {
+      animationCleanup = setupAnimationCleanup(newSvg, () => {
+        // On animation complete, check if resize was pending
+        if (pendingResize && !destroyed) {
+          pendingResize = false;
+          resize();
+        }
+      });
+    }
+  }
+
+  function update(newSpec: TileMapSpec): void {
+    currentSpec = newSpec;
+    currentLayout = compile();
+    render();
+  }
+
+  function resize(): void {
+    if (destroyed) return;
+
+    // If animation is running, queue the resize for after it completes
+    if (animationCleanup) {
+      pendingResize = true;
+      return;
+    }
+
+    currentLayout = compile();
+    render();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Export
+  // ---------------------------------------------------------------------------
+
+  function exportChart(
+    format: 'svg' | 'svg-with-fonts' | 'png' | 'jpg',
+    options_?: JPGExportOptions | SVGExportOptions,
+  ): string | Promise<Blob> | Promise<string> {
+    if (!svgElement) return '';
+
+    switch (format) {
+      case 'svg':
+        return exportSVG(svgElement);
+      case 'svg-with-fonts':
+        return exportSVGWithFonts(svgElement);
+      case 'png':
+        return exportPNG(svgElement, options_ as JPGExportOptions);
+      case 'jpg':
+        return exportJPG(svgElement, options_ as JPGExportOptions);
+      default:
+        return '';
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Destroy
+  // ---------------------------------------------------------------------------
+
+  function destroy(): void {
+    if (destroyed) return;
+    destroyed = true;
+
+    // Cancel running animations
+    if (animationCleanup) {
+      cancelAnimations(svgElement);
+      animationCleanup();
+      animationCleanup = null;
+    }
+
+    // Clean up events
+    if (cleanupTooltipEvents) {
+      cleanupTooltipEvents();
+      cleanupTooltipEvents = null;
+    }
+
+    // Remove SVG
+    if (svgElement) {
+      svgElement.remove();
+      svgElement = null;
+    }
+
+    // Unmount tooltip manager
+    if (tooltipManager) {
+      tooltipManager.destroy();
+      tooltipManager = null;
+    }
+
+    // Disconnect resize observer
+    if (disconnectResize) {
+      disconnectResize();
+      disconnectResize = null;
+    }
+
+    // Remove root classes
+    container.classList.remove('oc-tilemap-root', 'oc-dark');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Initialize
+  // ---------------------------------------------------------------------------
+
+  // Add root class for CSS custom properties (tokens, tooltip styles)
+  container.classList.add('oc-tilemap-root');
+  if (resolveDarkMode(options?.darkMode)) {
+    container.classList.add('oc-dark');
+  }
+
+  // Initial compile and render (animate on first mount)
+  currentLayout = compile();
+  render(true);
+
+  // Setup responsive resizing
+  if (options?.responsive !== false) {
+    disconnectResize = observeResize(container, () => {
+      resize();
+    });
+  }
+
+  return {
+    update,
+    resize,
+    export: exportChart,
+    destroy,
+    get layout(): TileMapLayout {
+      return currentLayout;
+    },
+  };
+}